Visual COBOL Development Hub 5.0

Welcome to Visual COBOL Development Hub

  • What is Development Hub?
  • Setup and Licensing

What's New

  • New Features in 5.0
  • Significant Changes in Behavior or Usage

Getting Started

  • Upgrading to Visual COBOL Development Hub
  • New to COBOL

Resources

  • Language References
  • Demonstrations
  • Micro Focus Community Forums
  • Micro Focus Channel on YouTube
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Training Store

Talk to Us

  • Contact SupportLine
  • Community Feedback


Welcome

Visual COBOL Development Hub (Development Hub) is a part of the Visual COBOL product portfolio from Micro Focus which includes testing and developer productivity tools.

Development Hub is a companion of Visual COBOL for Eclipse. It enables the developers to use intelligent, integrated development tools in Eclipse while keeping the application source on a UNIX or Linux production-like server with access to middleware and test data. Developers get the power of Eclipse on their Windows or Linux desktop and can test their applications in a realistic environment without duplicating source code or emulating server behavior. With Visual COBOL, Visual COBOL Development Hub can be used for distributed development of COBOL for JVM applications.

You can use Development Hub in one of the following ways:
  1. As a companion to Visual COBOL for Eclipse.
  2. As a stand-alone application development environment.

Using Development Hub with Visual COBOL for Eclipse

If you use Development Hub in conjunction with Visual COBOL for Eclipse you can take full advantage of Visual COBOL for Eclipse's support for building and testing COBOL applications on the UNIX or Linux server from a locally installed Eclipse IDE.

You keep the project source code, databases and other services on the target UNIX or Linux platform while the Eclipse environment runs on the programmer's Windows or Linux desktop for maximum performance:

Using Development Hub with Visual COBOL for Eclipse

Source code is stored either on the target UNIX or Linux machine or within the source control system being used in Eclipse and checked out to the programmer's work area on the server. This source code is accessed from the Eclipse client via a variety of standard network methods. There is no need to copy source code to the programmer's local Windows or Linux desktop and then copy it back to the server for system or integration build and test.

Development Hub includes a debug engine which the Eclipse client accesses to debug COBOL applications. The COBOL code on the server can access local databases, middleware or other services without complex simulation or duplication of the services on the programmer's desktop. A lightweight and easy to manage protocol is used for debugging, particularly where access to the application's server is protected by a firewall.

Development Hub performs the application builds on the server with all messages (for example, warnings, errors and success messages) being returned to the Eclipse client.

Note: For more information, see Configuring the Remote System Explorer Support in the product help for Visual COBOL for Eclipse.

Using Development Hub as a stand-alone development environment

If you use Development Hub without Visual COBOL for Eclipse, you keep the project source code, databases and other services on the target UNIX or Linux platform and use the command line to edit, compile and debug the code directly on the target machine.

Visual COBOL Development Hub provides the COBOL compiler, the Animator and a variety of command line tools to help you maintain your existing application directly on target UNIX or Linux platform and to help you upgrade any existing Server Express applications to the Visual COBOL environment.

Note:
  • For information on how to use Development Hub for application development as a stand-alone product, refer to the rest of this product help.
  • Most references to Visual COBOL in this product help are for the IDE-based product, Visual COBOL for Eclipse. However, because Visual COBOL for Eclipse and Development Hub have some shared functionality, some references to Visual COBOL apply to Development Hub as well as Visual COBOL for Eclipse.
  • The Micro Focus Community
  • 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.
  • Updating from an Earlier Release
  • Product Information
    Includes information about installing and licensing this product, any known issues, and about how to contact Micro Focus.
  • Using the Command Line Demonstrations
  • Upgrading to Visual COBOL Development Hub
  • Help on Help
Parent topic: Visual COBOL Development Hub 5.0


The Micro Focus Community

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

Parent topic: Welcome
Related concepts
Further Information and Product Support


Where do I start

Now that you have installed Visual COBOL Development Hub, 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.

  • New to Visual COBOL Development Hub
  • New to COBOL
  • Upgrading from Server Express
  • Want to deploy an application
Parent topic: Welcome


New to Visual COBOL Development Hub

Visual COBOL Development Hub is a development environment for Linux and UNIX platforms that enables you to edit, compile and debug the code directly on the target machine. It provides the COBOL compiler, Animator and a variety of command line tools to help you maintain your existing applications directly on target UNIX or Linux platform and to help you upgrade any existing Server Express applications to Visual COBOL.

Where to start?

If you've never used Visual COBOL Development Hub before, this product help includes the following resources to help you get started:

  • An Overview of Application Development using Development Hub.
  • Developing Applications, which contains information about creating applications.

What next?

Visual COBOL Development Hub provides a variety of features and tools suited to help you get on with your programming effectively and efficiently.

Explore the available demonstrations to help you get started with Visual COBOL Development Hub and introduce you to its features.

For a more contemporary developer experience, use Visual COBOL Development Hub in client-server scenarios where you develop your applications remotely using Micro Focus Visual COBOL for Eclipse installed on a local developer's machine.

Parent topic: Where do I start
Parent topic: Upgrading Your COBOL Applications


New to COBOL

COBOL (Common Business-Oriented Language) was developed in 1959 and, since then, has been used as the basis for many business and government applications. Reports show that over 80% of the world's business applications run on COBOL with billions more lines of code existing and billions being written annually.

Micro Focus has been the market leader and provider of distributed COBOL development tooling for nearly 40 years. Micro Focus's COBOL has evolved and today it differs significantly to the COBOL language of 1959, embracing object-orientation and enabling you to write code that takes full advantage of new operating systems and platforms such as Microsoft's .NET framework and the Java Virtual Machine (JVM).

Where to start?

Micro Focus provides the following resources to help you get started with COBOL programming:

  • A Micro Focus course introducing you to COBOL programming, Visual COBOL: Modern COBOL for the Next Generation.

    This course is the ideal first step on your journey to learning about the COBOL language and how to take advantage of what Visual COBOL can do for you. After taking the course you will have a good knowledge of the basics of COBOL and Visual COBOL, and will be ready to build on that general knowledge by learning more about taking full advantage of Visual COBOL to meet the specific requirements of your applications.

    The course is available from a link in your Micro Focus Electronic Product Delivery email which you were sent about your license. Follow the link and click the Documentation tab.

  • Other training courses - available from Support & Services on the Micro Focus Web site.
  • Training videos on the Micro Focus You Tube channel.
  • Explore the available demonstrations for examples of applications written in COBOL.

What next?

Micro Focus provides a variety of resources that illustrate how you can use COBOL to develop applications:

  • Take COBOL Programming for Business Success, a web-based training course teaching you how to design and code COBOL programs.
  • Refer to the COBOL Language Reference for in-depth information about the syntax and the usage of the COBOL language.
  • Explore the power of COBOL to prepare your applications for interaction with modern day technologies. Managed COBOL is COBOL with extensions to support the Java Virtual Machine (JVM). It offers support for object orientation and access to the JVM. For more see:
    • Check Procedural COBOL Compared with Managed COBOL which covers introductory information about the COBOL language including the difference between native and managed code.
    • Introduction to Object-Oriented Programming for COBOL Developers
    • Visual COBOL - A Developer's Guide to Modern COBOL - in PDF format, available from the Micro Focus Web site.
    • Managed COBOL Reference
    • Comparison of COBOL with Other Managed Languages
Parent topic: Where do I start


Upgrading from Server Express

Visual COBOL Development Hub enables you to develop applications that were created using Server Express.

Where to start?

  • If you've never used Visual COBOL Development Hub before, see Overview of Application Development.
  • See Developing Applications, which contains information about creating applications and about the working mode.
  • Watch a Micro Focus YouTube video explaining what the steps are for upgrading from Server Express.
  • Explore the available demonstrations for examples of COBOL applications you can create and maintain with Visual COBOL Development Hub.

Reading to import your existing applications?

Once you are familiar with Visual COBOL Development Hub, you can upgrade your applications to it. See the following resources:

  • A guide about Upgrading to Visual COBOL Development Hub for an explanation of what you need to install and an overview of the process of upgrading existing applications.
  • Read about the differences between Server Express and Visual COBOL.

What next?

Once you have upgraded your applications from Server Express, you can continue to maintain your applications in Visual COBOL as before. You can also employ new technologies such as JVM COBOL and modernize the applications over time. See the following resources for help on getting started with JVM COBOL programming:

  • Introduction to Object-Oriented Programming for COBOL Developers
  • Visual COBOL - A Developer's Guide to Modern COBOL - in PDF format, available from the Micro Focus Web site.
Parent topic: Where do I start


Want to deploy an application

Applications that you develop in Visual COBOL require a variety of run-time system support files in order to be able to run. When running these applications from Visual COBOL, these support files are accessed from Visual COBOL itself, but if you need to deploy these applications to users that do not have Visual COBOL installed you also need to deploy COBOL Server to provide the required run-time system support files. When deploying COBOL 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 Deploy JVM applications if you have a managed COBOL application.

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:
    • Implementing a COBOL program as a SOAP Web service
    • Implementing a COBOL program as a REST Web service
Parent topic: Where do I start


Updating from an Earlier Release

If you have used Visual COBOL 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 in 5.0
  • Features Added in 4.0
  • Features Added
  • Major Features
  • Significant Changes in Behavior or Usage
Parent topic: Welcome


New Features in 5.0

This release provides enhancements in the following areas:

  • Enterprise Server Common Web Administration
  • Data File Tools
  • Database Connectors
  • Enterprise Server Security
  • Platform Support
Parent topic: Updating from an Earlier Release

Enterprise Server Common Web Administration

Back to Top

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

Visual COBOL 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 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.

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 information
Compare Two Data Files

Database Connectors

Back to Top

You can now create an identity column in your database by using a new XFD directive - IDENTITY_COLUMN. This must be specified on a numeric field.

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
Related information
Deployment Listeners
The .mfdeploy file
Selective Auditing

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.


Features Added in 4.0

This release provides enhancements in the following areas:

  • Application Server JCA Support for Enterprise Server
  • Compiler directives
  • Data File Tools
  • Database Connectors
  • Docker
  • Enterprise Server
  • File Handler
  • Managed COBOL
  • OpenESQL
  • Platform support
  • XML Extensions

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.

Compiler directives

Back to Top

The following Compiler directives are new in this release:

  • DISPSIGN - determines the display output of numeric fields with included signs, under an IBM mainframe dialect only.
  • GNTLITLINKSTD - stops the suppression of call-convention 8 when both call-convention 2 and call-convention 8 are in effect for a .gnt file in an Intel x86 32-bit environment.
  • ILSMARTTRIM - trims any trailing spaces from a string item returned by the get property associated with an alphanumeric item processed by ILSMARTLINKAGE.
  • MAINFRAME-FLOATING-POINT - specifies the format of a program's floating point data items: either IBM hexadecimal format or IEEE format. This directive is supported in managed code only.

The following Compiler directives contain new parameters in this release:

  • CHECKDIV - a new parameter 'ACOS' now emulates a divide by zero operation on an ACOS mainframe system: the quotient and the remainder are set to the value of the dividend.
  • OOCTRL - a new parameter, L, specifies whether to include directory location comments in .cls and .ins inheritance files.
  • NUMPROC - a new parameter 'ACOS' provides partial compatibility with the behavior of NEC ACOS COBOL processing of invalid data in USAGE DISPLAY data items and invalid sign information in USAGE COMP-3 data items.

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.

Database Connectors

Back to Top

Database Connectors for Microsoft SQL Server

The following enhancements have been made to Database Connectors for Microsoft SQL Server:

  • Database Connectors for MSSQL is now available on Linux/UNIX platforms where MSSQL server is supported; see the Microsoft SQL Server support web pages for an up-to-date list of specific supported platforms.

    With Database Connectors for Microsoft SQL Server, you can connect to both an instance running on a Linux machine, or an instance running on a Windows machine. You can also use it to connect to an instance of SQL Server running on Linux from a Windows client. (Note that setting up SQL Server on a Linux machine is beyond the scope of our documentation.)

    See To install Database Connectors for Microsoft SQL Server for more information.

  • Database Connectors for MSSQL now supports connecting to a Microsoft SQL Server running a multi-subnet failover cluster. To use this feature requires changes to the connection string sent to the server, which is accomplished by using the following 4 new configuration variables:
    • A_MSSQL_MULTI_SUBNET_FAILOVER - set to TRUE to enable a connection that supports multisubnet failover support. If set to FALSE (the default) support is not enabled, and the other configuration variables have no effect.
    • A_MSSQL_FAILOVER_PARTNER - the name of the failover partner used. Refer to your SQL Server documentation for valid values.
    • A_MSSQL_FAILOVER_PARTNER_SPN - the name of the failover partner SPN used. Refer to your SQL Server documentation for valid values.
    • A_MSSQL_SERVER_SPN - the name of the Server SPN. Refer to your SQL Server documentation for valid values.
  • Database Connectors for MSSQL now supports columns of type GUID for existing SQL tables. A new configuration variable, A_MSSQL_IGNORE_GUID_COLUMNS, determines the behavior when handling existing tables that contain a column of this type.
    Note: Database Connectors for MSSQL cannot create a new column of this type.

Database Connectors for ODBC

  • Database Connectors for ODBC is now available, allowing you to use ODBC connectivity to access supported databases from your COBOL programs. See Database Connectors for ODBC for more information.

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

Managed COBOL

Back to Top

Deploying JVM COBOL to an Application Server:

  • Running JVM COBOL under WebSphere 9.0 and WebLogic 12.2.1 is now supported.

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:

  • SUSE platforms - this release only supports SUSE Linux 12 SP2, 64-bit.

    On this platform, you can only build COBOL programs to 64-bit executables. This applies when using Eclipse on SUSE or with remote projects when Visual COBOL Development Hub is installed on SUSE.

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

XML Extensions

Back to Top

Two new state management statements have been introduced, XML GET WHITESPACE-FLAGS and XML SET WHITESPACE-FLAGS, that enable you to control how whitespace is handled when importing data; refer to the topic Handling spaces and whitespace in XML for more information.

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

Parent topic: Updating from an Earlier Release
Related reference
Defining XA Resource Entry
Filter the Data File
Introduction to Docker


Features Added

This release provides enhancements in the following areas:

  • Application Server JCA support for Enterprise Server
  • Data File Tools
  • Deployment on multiple platforms
  • Documentation
  • Enterprise Server

Application Server JCA support for Enterprise Server

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

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.

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.

Deployment on multiple platforms

This release provides support for deploying JVM COBOL applications on multiple platforms. You can compile an application on one platform (such as Windows) and then deploy its class files to a different platform (such as Linux or UNIX).

Some features of the COBOL language, however, are platform-specific and their behavior on different platforms might vary. See Multi-Platform Deployment of JVM COBOL Applications for details.

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.
  • Multi-Platform Deployment of JVM COBOL Applications - includes information about how to ensure the portability of your JVM COBOL applications between Windows and UNIX or Linux platforms.

Back to Top

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

Enterprise Server

Improvements are available in the following areas:

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.

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.

Parent topic: Updating from an Earlier Release
Related reference
Application Server JCA support
Data File Tools


Major Features

Visual COBOL Development Hub offers the following major features:

Advanced application development using Visual COBOL for Eclipse

This product help describes how to use Visual COBOL Development Hub as a standalone product.

Originally, Visual COBOL Development Hub was designed as the companion of Micro Focus Visual COBOL for Eclipse and offers tight integration with the Eclipse IDE in remote development and debug scenarios. If you have Visual COBOL for Eclipse installed on your local development machine, you can connect to the UNIX or Linux box that has Development Hub installed and take advantage of the advanced edit, compile and debug functionality that the IDE offers:

  • Remote development:
    • Editing programs as standalone files or as part of an Eclipse project. Setting Compiler directives to hold your sources or edit single programs on the remote box take advantage of the advanced COBOL editor in Eclipse
    • Advanced COBOL editor that offers syntax error reporting, smart edit features, Code Assistance suggestions when typing code.
    • Code Analysis features
    • Various views in the IDE optimized to show you all the information which is relevant when editing COBOL sources.
  • Remote debugging:
    • Use the Eclipse debugger to step through both native and managed COBOL code on the remote machine.
    • Breakpoints and watchpoints setting.
    • A dedicated layout (Debug Perspective) of the views in the IDE optimized for debugging showing you the active threads, your all the information which is relevant when editing COBOL sources.

Animator

Note: This facility only supports native COBOL code.

Provides enhanced debugging support for all executable file formats, and for mixed-language applications, multi-threaded applications, and other active COBOL processes.

Application Configuration System

The Application Configuration System enables programs to use a standard configuration technique to control their behavior. This program is extensively used by Visual COBOL Development Hub itself and enables you to configure many of the tools described here.

Class Library

The Class Library is a set of predefined objects which you can use as a foundation for building your own applications using object-oriented programming.

Client/Server Binding

Note: This feature is available if you install the Compatibility AddPack for Visual COBOL.

Client/Server Binding is a simple and effective way to connect a client to a server. You can create distributed applications without having to write any communications code.

COBOL Compiler

Provides full support of many COBOL dialects, and can produce portable intermediate code, optimized generated code, and native object code that can be linked to produce system executables or ultra-efficient callable shared objects.

COBOL System Library Routines

The COBOL system library routines can be called directly from your program, providing many operations not available in the COBOL language itself.

There are some additional routines as well that provide features needed for cross-system compatibility, such as generic screen attributes.

COBOL Source Information

The COBOL Source Information (CSI) functions let you perform a static analysis of your program source. The information provided includes extensive information about data items, copyfiles, sections and paragraphs in your program. These functions allow you to find your way around your source very quickly and are particularly useful for maintenance of existing programs. This information is available from within the Animator.

Data File Tools

Micro Focus Data File Tools is a standalone text editor in which to create and edit data files for use in your COBOL testing environment. The files you create can belong to a Fileshare server or reside locally on your machine. You can also open existing data sets within your Enterprise Server regions, for editing.

The DFCONV utility is also included. This is also known as the Data File Converter and is used for converting data files. The utility provides a batch and called program interface to enable conversion of file formats, organizations and data formats and reorganization of indexed files using data file conversion profiles.

Data File Tools comprises two editors, producing two different types of file. Use the files produced by the two editors, within the Data File Editor, to produce a rich data editing experience.

Database support

Includes SQL support software that provides seamless integration with a number of other vendors' database systems.

DBCS Transparency Support

DBCS Transparency is a level of DBCS support that supports creating native language applications using DBCS code sets. You can use it under system locales such as, for example, Traditional Chinese, Simplified Chinese, and Korean provided you have them on your system. It enables you to use single- and double-byte character strings, using tools such as Animator and Editor to create and maintain application programs that support your native language.

Demonstration programs

A number of demonstration programs are provided to supplement the documentation of certain components and to demonstrate features in Visual COBOL Development Hub. By default, the demonstrations are installed in /opt/microfocus/VisualCOBOL/demo/.

Device Handling and Terminfo Support

Device Handling and Terminfo Support enables you to use UNIX devices with the run-time system and the run-time support modules.

Dialog System Character Mode

Note: This feature is available if you install the Compatibility AddPack for Visual COBOL.

Dialog System creates character-based user interfaces for your COBOL applications. All handling of the interface is done for you, leaving your program free to concentrate on processing the data.

EBCDIC Support

Visual COBOL Development Hub provides support for EBCDIC data on UNIX systems, making the behavior of applications on your computer highly compatible with that on IBM mainframes. When you use this option, the program stores all data in EBCDIC, and operations such as comparisons and sorts use the EBCDIC collating sequence.

Enterprise Server

Provides an environment in which you deploy services written in COBOL. It listens for requests from client applications to invoke the services. It also provides functions such as scalability, thus saving programming time.

External Filename Mapping Support

Filename mapping enables you to alter the physical filename accessed by your program at run time, assign files to UNIX pipes, assign the index and data files of indexed files to different directories, and assign a file to a printer.

File Handler

The File Handler is a module providing run-time support for COBOL files.

The File Handler includes an interface that enables you to call it from your program using CALL statements. This gives you low-level control over files of all COBOL organizations, so you can write sophisticated file and database handling programs. You can also use it to access COBOL format files from other languages, such as C or Assembler.

Fileshare

Fileshare provides rapid network I/O by compressing I/O requests into packets and sending them across network lines, so that the file processing is done on the server that contains the files. It can also link several files together into a logical database. You can set up a recovery log when accessing that database, providing a high level of data integrity.

Fileshare has transaction logging which allows your user to delay writing changes to files until all the information is complete. You can secure these changes with a COMMIT or cancel them with a ROLLBACK.

Header-to-COPY

The Header-to-COPY utility translates C-language header files into their equivalent COBOL copyfiles. Its main use is to simplify COBOL programming when using system libraries whose basic definitions are provided only for C programs. Examples are interfaces to UNIX TP systems and various relational databases on UNIX.

Key Usage

Because UNIX terminals vary widely, the keys documented in this product help may not be available on your keyboard. Also, most UNIX terminals do not recognise the Alt or Ctrl key when they are pressed, so Visual COBOL Development Hub cannot detect these keys. The UNIX Key Usage Chart lists alternatives for keys that might be undetectable on your specific UNIX terminal, and shows which keys you can configure.

The chart also tells you how to select soft or hard operation for the Alt and Ctrl keys. With soft operation, the Alt or Ctrl key is automatically turned off after the next keystroke. This means that whenever you want a function from the Alt menu you must hold down Alt again to get the Alt menu displayed; and similarly with Ctrl. With hard operation, the Alt and Ctrl keys work in a similar way to the Caps Lock key, in that having been pressed they remain in effect until pressed again.

Integrated Preprocessor Support

The Integrated Preprocessor is an extension to the Compiler. It allows the Compiler to invoke a user-defined language processor to convert non-COBOL syntax to COBOL syntax.

When using Animator you see the original source, as it is before statements are altered by the preprocessor.

Library

Library is a utility that groups individual files into one file, making them easier to administer.

Managed COBOL

Managed COBOL is regular procedural COBOL with extensions to take advantage of the features of the managed frameworks. This includes object-oriented (OO) syntax that allows access to large libraries of functionality you can use in your application, and much more. To take full advantage of Managed COBOL, it is helpful to understand the object-oriented concepts.

Managed COBOL for JVM (also referred to as JVM COBOL) compiles to Java bytecode, and native COBOL compiles to machine code. Both managed and native COBOL can run on any platform when compiled.

For JVM managed code, the management services are provided by JVM. For native COBOL, the management services are available in the operating system, and your code has to call the appropriate services depending on the operating system. The management services enable seamless interoperation of COBOL programs with programs in other JVM languages.

Multi-threading support

You can use Visual COBOL Development Hub to create non-threaded or multi-threaded applications. Multi-threading exploits the power of your processor by enabling applications to run in a true multi-process environment.

You specify whether a program is multi-threaded or single threaded using Compiler directives. Execution support is provided by multi-threaded versions of commands; for example, cobrun_t is the multi-threading equivalent of cobrun.

National Locale Support

National Locale Support (NLS) enables your program to adapt itself automatically at run time to the character set, currency symbol, and editing symbols appropriate to your user's country. It also ensures correct collation and folding of national (for example, accented) characters, and provides library routines to fetch messages in the appropriate national language from a message file.

This facility depends on operating system support.

Object-oriented Programming

The COBOL language in Visual COBOL Development Hub has language extensions to enable you to use object-oriented programming methods in COBOL. Object-oriented programming is explained in the Object-oriented Programming with COBOL book.

You can of course use traditional COBOL programming instead of the object-oriented style if you prefer.

Profiler

The Profiler gives you detailed statistics on the run-time performance of a COBOL program.

Run-time Configuration Support

Run-time Configuration Support consists of environment variables and tunables in a run-time configuration file, which you can configure to affect certain run-time behavior.

Run-time support programs and libraries

Contain routines supporting advanced features of the COBOL language.

Screen and Keyboard Configuration Tools

The screen and keyboard configuration tools are utilities you can use to configure screen and keyboard handling to your own environment and requirements, or to be compatible with other COBOL systems.

Screen and Keyboard Handler

The Screen and Keyboard Handler, often known as Adis, is a module that provides run-time support for the enhanced (full screen) ACCEPT/DISPLAY verbs and Screen Section features available with this system.

Sort Module

The Sort Module is a stand-alone sort routine which enables you to sort and reorder data files. It is faster than the default COBOL sort mechanism. The interface provides greater flexibility in sorting data and enables you to substitute alternative sort modules.

Windowing Support

Windowing Support consists of COBOL syntax which enables you to draw lines and boxes on the screen and create virtual windows on a physical screen. The syntax also allows underlying displays to be kept and restored. It is compatible with ACUCOBOL.

XML-enabled COBOL

Provides a set of syntax extensions you can code in your COBOL program manually, or generate automatically using the CBL2XML Wizard or command line utility. You can use these extensions to perform input/output on an XML instance document rather than using a traditional file method such as an index file.

Parent topic: Updating from an Earlier Release


Significant Changes in Behavior or Usage

This section describes significant changes in behavior or usage in the current and past releases of . 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 HotFix releases. Refer to the HotFix readmes for information about such changes.
  • Changes in Behavior in This Release
  • 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

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 Micro Focus SupportLine Web site.

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 Micro Focus SupportLine Web site.

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

  • Enterprise Server security
  • Application Server JCA Support for Enterprise Server
  • 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_unix.ldf file, which is located in the etc sub-directory of your product directory.

Application Server JCA Support for Enterprise Server

With this release, all CICS-related Java artifacts have been delivered using a new directory structure under the javaee-ccl directory of your installation directory. The javaee-ccl directory structure mimics the structure of the javaee directory. For example, mfccl.jar is no longer located in the bin subdirectory, but can be found in the javaee-ccl\common directory.

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 Micro Focus SupportLine Web site.

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

  • Compiler Directives
  • OpenESQL
  • Reserved words

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.

OpenESQL

Back to the list

The new OpenESQL OPTIMIZECURSORS SQL compiler directive option is turned on by default for ODBC (DBMAN=ODBC). This ensures that 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
  • 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)

  • On UNIX, if the "File Path" setting was not specified in the configuration of an Enterprise Server, the environment variable TXFILEP was defaulting to $COBDIR/etc/cas. This has been changed and TXFILEP is not populated when the "File Path" is not specified.

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)

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

  • Run-Time System
  • SQL: OpenESQL
  • SQL Option for DB2

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

  • CAS Security
  • CAS XA Switch modules
  • File Handling
  • File Locking
  • J2EE Connector
  • MF Server Administrator (GUI)
  • Updated Run-Time System

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 Visual COBOL 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 (Visual COBOL 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 Visual COBOL 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)

File Locking

Back to the list

  • In versions prior to Visual COBOL 2.3, the semantics of the sharing phrase specified in an OPEN statement or used within a call to CBL_OPEN_FILE were not correctly applied in some cases on UNIX and Linux platforms. From version 2.3 onwards, the sharing phrase is correctly honored when the tunable strict_file_locking=true is set, which is the default setting.

    Example of potential changes in behavior:

    • Process-A opens a file with read-only access and a sharing mode that denies other processes write access (SHARING WITH READ ONLY).
    • Process-B then attempts to open the file with read-only access and a sharing mode that denies other processes read access (SHARING WITH NO OTHER).

    With strict_file_locking=true, Process-B is unable to open the file, because Process-A has successfully opened the file allowing only read access.

    With strict_file_locking=false, Process-B successfully opens the file.

    If your application encounters unexpected OPEN conditions or fails to open files, it might be as a result of the new file locking behavior. In such circumstances, we recommend that you review the file locking and sharing requirements of your application and refactor your source code to work with the default setting. The original file locking and sharing behavior can be restored by setting strict_file_locking=false.

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)

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)

Updated Run-Time System

Back to the list

  • COBOL 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 Visual COBOL prior to version 2.3, you should ensure that the executable is rebuilt and packaged with the new run-time system. You can rebuild from the IDE or the command line.

    Other COBOL subprograms built with previous versions of Visual COBOL 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).

  • Compiler
  • Documentation
  • Enterprise Server
  • J2EE Connector

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)

J2EE Connector

Back to the list

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

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

COBSQL

Back to the list

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

    2673619 (1093197)

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

  • MF Directory Server
  • MF Server Administrator (GUI)
  • Request Handler

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)

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

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

  • Run-Time System
  • Vision File System

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

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

  • DB2
  • File Handling

DB2

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)

Parent topic: Updating from an Earlier Release


Product Information

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

  • Installing Visual COBOL Development Hub
  • Managing Licenses
  • Updates and Product Support
  • Setup and Licensing
    Includes information about setting up and licensing this product.
  • Micro Focus End User License Agreement
  • Known Issues and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


Installing Visual COBOL Development Hub

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


Before Installing

  • Downloading the Product
  • UNIX and Linux Installer Issues
  • System Requirements
Parent topic: Installing Visual COBOL Development Hub


Downloading the Product

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

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

Parent topic: Before Installing


UNIX and Linux Installer Issues

Installing while using AFS/Kerberos authentication

If you are using AFS/Kerberos authentication to log onto your Linux system then you need to ensure you have a local user ID which SOA and Visual COBOL components of the product can use. This user ID must be set up prior to running the installer. When running the installer you need to specify -ESadminID=[User ID] on the command line so it is used by the installer.

License Server

You need to configure the computer hostname to ensure the license server will start properly.

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

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

127.0.0.1 localhost.localdomain localhost
IP machinelonghostname machineshorthostname

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

Parent topic: Before Installing
Parent topic: Known Issues and Restrictions


System Requirements

  • Hardware Requirements
  • Operating Systems Supported
  • Software Requirements
  • Additional Software Requirements for Visual COBOL Development Hub
Parent topic: Before Installing


Hardware Requirements

The disk space requirements are approximately:

Platform | Installer type | Setup file size | Disk space required for the installation | Disk space required for running the product | Sentinel RMS license server
POWER running AIX | Micro Focus | 462 MB | 1.85 GB | 924 MB | 41 MB
HP IA | Micro Focus | 847 MB | 3.39 GB | 1.74 GB | 79 MB
System Z running Red Hat Linux | Micro Focus | 382 MB | 1.53 GB | 764 MB | 39 MB
System Z running Red Hat Linux | RPM | 109 MB | 436 MB | 218 MB | 34 MB
x86-64 running Red Hat Linux | Micro Focus | 455 MB | 1.82 GB | 910 MB | 50 MB
x86-64 running Red Hat Linux | RPM | 138 MB | 552 MB | 276 MB | 50 MB
ppc64le running Red Hat Linux | Micro Focus | 267 MB | 1.07 GB | 534 MB | 1 MB
ppc64le running Red Hat Linux | RPM | 58 MB | 232 MB | 116 MB | 1 MB
SPARC running Solaris | Micro Focus | 456 MB | 1.82 GB | 912 MB | 41 MB
x86-64 running Solaris | Micro Focus | 431 MB | 1.72 GB | 862 MB | 33 MB
System Z running SUSE SLES | Micro Focus | 280 MB | 1.12 GB | 560 MB | 39 MB
System Z running SUSE SLES | RPM | 56 MB | 224 MB | 112 MB | 39 MB
x64 running SUSE SLES | Micro Focus | 333 MB | 1.33 GB | 666 MB | 50 MB
x64 running SUSE SLES | RPM | 68 MB | 272 MB | 136 MB | 50 MB
ppc64le running SUSE SLES | Micro Focus | 247 MB | 988 MB | 494 MB | 1 MB
ppc64le running SUSE SLES | RPM | 46 MB | 184 MB | 92 MB | 1 MB
Parent topic: System Requirements
Related information
Operating Systems Supported
Software Requirements
Additional Software Requirements for Visual COBOL Development Hub


Operating Systems Supported

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

Parent topic: System Requirements
Related information
Hardware Requirements
Software Requirements
Additional Software Requirements for Visual COBOL Development Hub


Software Requirements

Note: This product includes OpenSSL version 1.1.1b.

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

  • Xterm, the terminal emulator for the X Window System, is part of your UNIX/Linux distribution but is not installed by default. Use your UNIX/Linux installation media to install it.
  • The "awk", "ed", "sed" and "tar" utilities must be installed and added to the PATH.
  • On SUSE 12, you can only install and use the 64-bit version of Visual COBOL.
  • The pax archiving utility is required by the setup file. Pax is distributed with most UNIX/Linux systems but, if it is missing, you must install it separately. To verify pax is installed, run pax --help or pax --version at the command line.
  • Required libraries for Red Hat and SUSE Linux platforms - the installer checks that both the 32-bit and 64-bit libraries listed below are installed on both 32-bit and on 64-bit Operating Systems for this product to install and work correctly.

    If installing on a 64-bit OS, the 32-bit libraries are not installed by default and must be installed before you start the installation.

    Table 1. Default Libraries.

    The following table shows which of the required libraries are not installed by default on the specified platforms - X indicates the libraries are missing.

    Library 32-bit Library Name 64-bit Library Name s390

    Library Name

            Platform
    SUSE 12¹ | Red Hat 7
    glibc | glibc-*.i686 | glibc-*.x86_64 | glibc-*.s390 | X
    libgcc | libgcc-*.i686 | libgcc-*.x86_64 | libgcc-*.s390 | X
    libstdc++ | libstdc++-*.i686 | libstdc++-*.x86_64 | libstdc++-*.s390 | X
    glibc-devel | glibc-devel-*.i686 | glibc-devel-*.x86_64 | glibc-devel-*.s390 | X
    gcc2 | gcc*.i686 | gcc*x86_64 | X | X | X
    cpp2 | cpp*x86_64 | X

    Visit the Red Hat Web site for more information.

    • ¹ On SuSe 12, you can only install the 64-bit version of Visual COBOL. The glibc-locale-32bit library is still required by the SafeNet Sentinel licensed components.
    • 2 On Red Hat these libraries are required to enable COBOL to compile.
  • Java 8 (32 or 64-bit versions), and Java 11 (64-bit version only) are supported for executing JVM COBOL code and for native COBOL and Java interoperability. You can download AdoptOpenJDK's OpenJDK 8 with Hotspot from AdoptOpenJDK's Web site and unpack the archive anywhere on your machine.
    Note:
    • On AIX and zLinux, you need to have IBM's JDK. The earliest supported release of IBM's JDK is 7.0 Service Refresh 8. If you install IBM's JDK 8, on AIX you must install its latest fix - JDK 8 SR5 FP16. You can get IBM's AIX JDK from IBM's Web site.
    • On HP-UX, you need to have HP-UX JDK. The earliest supported release of HP-UX is JDK 7.0.11. You can get the HP-UX Java JDK from HP's Web site.
    • On Solaris platforms (both SPARC and Intel) only the 64-bit version of Java 8 and later is supported.

To execute JVM COBOL code, you need to set the environment as follows:

  • You need to set the JAVA_HOME environment variable. When installing the product, set this variable to a 64-bit Java installation or the installation terminates. For example, execute the following:
    export JAVA_HOME=java_install_dir

    where java_install_dir is the path to the JAVA installation directory such as /usr/java/javan.n

  • You need to add $JAVA_HOME/bin to your system PATH variable. To do this, execute:
    export PATH=$JAVA_HOME/bin:$PATH
  • You need to set the LANG environment variable to pick up localized messages. The LANG settings are English and Japanese only.
Important: For local servers, you do not need to install the Micro Focus License Administration tool separately, as the setup file installs a new Visual COBOL client and a new licensing server on the same machine.

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

If Micro Focus License Manager version 10000.2.02070 or older is installed, it must be uninstalled before the product installation or upgrade can continue.

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

Parent topic: System Requirements
Related reference
Eclipse Ux - Installing into different Eclipse packages
Related information
Hardware Requirements
Operating Systems Supported
Additional Software Requirements for Visual COBOL Development Hub


Additional Software Requirements on UNIX

Additional Software Requirements for Visual COBOL Development Hub

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

  • Application server support for JVM COBOL
  • Application server JCA support for Enterprise Server
  • Database Access
  • Database Access - COBSQL (Pro*COBOL)
  • Database Access - DB2 ECM
  • Database Access - OpenESQL
  • WebSphere MQ

Application server support for JVM COBOL

Back to Top

The following application servers are supported using the following JDKs:

Application Server | JDK version | Containers support version
Tomcat 7.0.X | 1.7 | Servlets 2.5
JBoss EAP 6.4 | 1.7, 1.8 | Servlets 2.5
WebLogic 12.1.1 | 1.7 | Servlets 2.5
WebLogic 12.2.1 | 1.8 | Servlets 2.5
WebSphere 8.5 | 1.7 | Servlets 2.5
WebSphere 9.0 | 1.8 | Servlets 2.5
Note:
  • On AIX and zLinux, you need to have IBM's JDK. The earliest supported release of IBM's JDK 1.7 is 7.0 Service Refresh 8. If you install IBM's JDK 8, on AIX you must install its latest fix - JDK 8 SR5 FP16. You can get IBM's AIX JDK from IBM's Web site.
  • On HP-UX, you need to have HP-UX JDK. The earliest supported release of HP-UX JDL 1.7 is Java 7.0.11. You can get the HP-UX Java JDK from HP's Web site.
  • On Solaris platforms (both SPARC and Intel) only the 64-bit version of Java 8 is supported.
  • On all other platforms, you need Oracle's JDK. The earliest supported release of Oracle's JDK 1.7 is 1.7.027. You can download Oracle's JDK from Oracle's Web site.

Application server JCA support for Enterprise Server

Back to Top

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

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

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

Application Servers | JDK (vendor) | Java EE | COBOL RA
JBoss EAP 7.1.4 | 1.8 (Oracle) 1.8 (AdoptOpenJDK)1 | 7 | X
Oracle WebLogic 12.2.1 | 1.8 (Oracle) | 7 | X
IBM WebSphere 9.0 | 1.8 (IBM) | 7 | X
Tomcat 9.0.x2 | 1.8 (AdoptOpenJDK) |  |
1JBoss EAP 7.1.4 restricts support of AdoptOpenJDK to Red Hat Enterprise Linux platforms. For more information, see the Red Hat Web site for supported configurations. 2Apache 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).

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

  • Start the Application Server
  • Compile EJBs and Servlets generated by the Interface Mapping Toolkit or the imtkmake command

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

The availability of COBOL resource adapters for these Application Servers differs between UNIX platforms. The following table indicates where support is available for each platform:

Feature/Platform | JBoss EAP 7.1.4 | WebSphere 9.0 | WebLogic 12.2.1 | Tomcat 9.0.x1
AIX 7.1 on RS6000 | 64-bit | 64-bit | 64-bit | 64-bit
HP/UX 11.31 on Intel IA64 | 64-bit | 64-bit | 64-bit | 64-bit
Red Hat EL 6.2 on IBM390 | 64-bit | 64-bit | 64-bit | 64-bit
Red Hat EL 6.1 on x86-64 | 64-bit | 64-bit | 64-bit | 64-bit
Solaris 11.3 on AMD Opteron | 64-bit | 64-bit | 64-bit |
Solaris 11.3 on SPARC | 64-bit | 64-bit | 64-bit |
SUSE SLES 12 SP2 on IBM390 | 64-bit2 | 64-bit | 64-bit | 64-bit
SUSE SLES 12 SP2 on AMD x86-64 | 64-bit2 | 64-bit | 64-bit | 64-bit
SUSE SLES12 on PowerLinux LE |  | 64-bit |  |
1Apache 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). 2JBoss EAP 7.1.4 not listed as tested by RedHat on this platform.

Database Access

Back to Top

Before you can use Visual COBOL to deploy SQL applications that use COBSQL, DB2 ECM, or OpenESQL, ensure any third-party software prerequisites are installed and the environment is set properly.

Database Access - COBSQL (Pro*COBOL)

Back to Top

Note: COBSQL (Pro*COBOL) is supported for native COBOL only.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Red Hat Linux | X | X
x86-64 running SUSE Linux | X | X
IBM System p running AIX | X | X
IBM System z running Red Hat Linux | X | X
IBM System z running SUSE Linux | X | X
Itanium running HP-UX | X | X
x86-64 running Solaris | X | X
SPARC running Solaris | X | X
XA Switch Module
When the Enterprise Server feature is enabled, 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.
Executing
On HP-UX, to execute an application precompiled using Pro*COBOL (or COBSQL) after you have created a callable shared object of Oracle DBMS routines, you need set an environment variable, LD_PRELOAD, to point to the Oracle client callable shared object, for example:
LD_PRELOAD=$ORACLE_HOME/libdir/libclntsh.so
export LD_PRELOAD
where libdir is:
  • lib32 for 32-bit environments
  • lib for 64-bit environments.

A script is available that creates an executable run-time system or a callable shared object containing Oracle support. You can find the script in the Micro Focus Knowledge Base article titled Building and executing Pro*COBOL applications on UNIX.

Testing
For this version, COBSQL was tested with Oracle 12.2 and 18c.

Database Access - DB2 ECM

Back to Top

Note: DB2 ECM is supported for native COBOL only.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Red Hat Linux | X | X
x86-64 running SUSE Linux | X | X
IBM System p running AIX | X | X
IBM System z running Red Hat Linux | X | X
IBM System z running SUSE Linux | X | X
Itanium running HP-UX | X
x86-64 running Solaris
SPARC running Solaris | X | X
PowerLinux LE running Red Hat Linux | X
PowerLinux LE running SUSE Linux | X
XA Switch Module
When the Enterprise Server feature is enabled, the DB2 XA switch module is provided and is available on the same platforms as are indicated in the Availability section above.
Testing
For this version, DB2 ECM was tested with DB2 LUW 10.5 and 11.1.

Database Access - OpenESQL

Back to Top

Availability
Feature/Platform | Native and JVM Managed COBOL 32-bit | Native and JVM Managed COBOL 64-bit
x86-64 running Red Hat Linux | X | X
x86-64 running SUSE Linux | X | X
x86-64 running Solaris | X | X
IBM System p running AIX | X | X
IBM System z running Red Hat Linux | X | X
IBM System z running SUSE Linux | X | X
Itanium running HP-UX | X | X
SPARC running Solaris | X | X
PowerLinux LE running SUSE Linux | X
PowerLinux LE running Red Hat Linux | X
XA Switch Module
When the Enterprise Server feature is enabled, the ODBC One-phase Commit switch module is provided and is available on the same platforms as are indicated in the Availability section above.

The PostgreSQL switch module is available on the following platforms:

  • x86-64 running Red Hat Linux
  • x86-64 running SUSE Linux
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
JVM Managed COBOL
OpenESQL supports access to relational databases using JDBC 4.0-compliant JDBC drivers. The following table shows the tested DBMSs and their corresponding JDBC driver filenames:
Tested DBMS Versions | JDBC 4.0 Compliant Drivers
DB2 LUW 10.5

DB2 LUW 11.1

db2jcc4.jar (and db2jcc_license_cu.jar)
Oracle 12.2 | ojdbc7.zip*
Microsoft SQL Server 2012

Microsoft SQL Server 2014

Microsoft SQL Server 2016

Microsoft SQL Server 2017

sqljdbc4.jar
EDB PostgreSQL 10.5 | postgresql-42.0.0.jre7.jar
*Some Oracle JDBC drivers are distributed as .zip rather than .jar files.

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

  • If you are using a Java application server, it includes a JNDI server you can use to configure DataSource objects. This process is described in the Java documentation for the application server.
  • If you are not using a Java application server, or if you require a standalone JNDI server to configure DataSource objects for initial evaluation and development, see the To install and configure Simple-JNDI topic in this documentation set for instructions on downloading, installing, and configuring the open source JNDI server Simple-JNDI for this purpose.
Testing
For this version, OpenESQL was tested with:
  • Oracle 12.2 and 18c
  • DB2 LUW 10.5 and 11.1
  • SQL Server 2012, 2014, 2016, and 2017
  • PowerLinux LE using DB2 LUW 10.5 only
  • EDB PostgreSQL 10.5 and MySQL 5.7 (5.3 ODBC drivers only) on the following platforms:
    • x86-64 running Red Hat Linux
    • x86-64 running SUSE Linux
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.
Planned
Support for the following is planned for future release:
  • SQL Server 2017
  • Amazon Aurora PostgreSQL-Compatible Edition

Both running on the following platforms:

  • x86-64 running Red Hat
  • x86-64 running SUSE Linux

WebSphere MQ

Back to Top

IBM WebSphere MQ version 7 and later.

XML Extensions

Back to Top

  • XML Extensions has the same requirements as Visual COBOL. Both 32-bit and 64-bit versions are available. See the XML Extensions for Visual COBOL, available from the Visual COBOL product documentation section of the Micro Focus SupportLine Web site for more details.
Parent topic: System Requirements
Related concepts
Database Access
Related information
Hardware Requirements
Operating Systems Supported
Software Requirements


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, see Advanced Installation Tasks.

  • Installing Visual COBOL Development Hub
Parent topic: Installing Visual COBOL Development Hub


Installing on UNIX

Installing Visual COBOL Development Hub

Note: Micro Focus offers two types of installers on UNIX and Linux - a proprietary Micro Focus installer for installing on UNIX and Linux and a standard RPM (RPM Package Manager) installer for installing on Linux.

These are the steps to install this product:

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

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

    The COBOL environment is installed by default into /opt/microfocus/VisualCOBOL, (COBDIR).

SafeNet Sentinel considerations

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

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

Note:

During the installation process, the installer configures the product's Enterprise Server System Administrator Process User ID. The Process User ID will be the owner of all Enterprise Server processes except the one for the Micro Focus Directory Server (MFDS). The Directory Server process (Enterprise Server Administration) runs as root as this allows it to access the system files and ports.

All Enterprise Server processes you start from Enterprise Server Administration run under the Process User ID which can affects the file access and creation.

By default, the installer uses the login id of the user that runs the installer for the Process User ID. To change the user id after you complete the installation, execute $COBDIR/bin/casperm.sh.

Parent topic: Basic Installation


Advanced Installation Tasks

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

  • Installing as an Upgrade
  • Visual COBOL Development Hub Installation Options
  • RPM Installer
Parent topic: Installing Visual COBOL Development Hub


Installing as an Upgrade

This release works concurrently with the previous version of Visual COBOL Development Hub, so you do not need to uninstall it.

Install the latest version in a different location and set the environment to point to it. To do this, run the Visual COBOL Development Hub installer with the –installlocation option:

  1. Execute the following command:
    ./InstallFile -installlocation="/opt/microfocus/VisualCOBOL"
    Note: You can use variables when specifying an absolute path for –installlocation. For example, the following examples are equivalent:
    -installlocation="/home/myid/installdir"
    -installlocation="$HOME/installdir"
  2. Execute cobsetenv to set the environment and point to the new install location:
    . <product-install-dir>/bin/cobsetenv
    Note: cobsetenv is only compatible with POSIX-like shells, such as bash, ksh, or XPG4 sh. It is not compatible with C-shell or pre-XPG4 Bourne shell.
Parent topic: Advanced Installation Tasks


UNIX Installation Options

Visual COBOL Development Hub Installation Options

Installing into a different location

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

./setup_visualcobol_devhub_5.0_platform -installlocation="full path of new location"
Note: You can use variables when specifying an absolute path for –installlocation. For example, the following examples are equivalent:
-installlocation="/home/myid/installdir"
-installlocation="$HOME/installdir"

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

Configuring the Enterprise Server installation

You can use the following options to configure the Enterprise Server installation: [ -ESsysLog="Y/N" ] [ -ESadminID="User ID" ] [ -CASrtDir="location" ], where:
-ESsysLog
Use this to enable ("Y") or disable ("N") Enterprise Server system logging. Logging is enabled by default. Log files are saved in /var/mfcobol/logs.
-ESadminID
Sets the Enterprise Server System Administrator Process User ID from the command line - for example, -ESadminID="esadm". The default user ID is the one that runs the installer.
-CASrtDir
Specifies the location were the Enterprise Server run-time system files are placed - for example, -CASrtDir="/home/esuser/casrt/es". The default location is /var/mfcobol/es.

Installing Silently

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

You can use the following command line arguments to install silently on UNIX/Linux. You need to execute the commands as root:

–silent -IacceptEULA

For example, execute:

setup_filename –silent -IacceptEULA
Parent topic: Advanced Installation Tasks


RPM Installer

In addition to its proprietary installer for installing on UNIX and Linux, Micro Focus provides a standard RPM installer for installing on Linux. RPM Package Manager (RPM) is a technology available on all Linux operating systems for managing the installation of products.

The RPM installer for supports all the RPM functionality.

  • Using the RPM Installer
  • Other RPM Installer Options
  • Uninstalling Using the RPM Installer
Parent topic: Advanced Installation Tasks


Using the RPM Installer

Before starting a standard RPM installation, ensure that all of the prerequisite software is installed on your machine. See Software Requirements for details.

This is not necessary if you are using an RPM administration utility as it installs any missing prerequisite packages at the same time as installing the Micro Focus package.

Downloading the installer

The RPM installer for is distributed as a .bin file and is available from your Electronic Product Delivery email.

To download and extract the file:

  1. Use the links in your Electronic Product Delivery email to download the filename.bin file that includes the RPM installer.
  2. Execute the .bin file from a terminal.
  3. Accept the terms of the End User License Agreement to extract the filename.rpm file on your machine.

Standard RPM installation

To install :

  1. Open a terminal and navigate to the location of the .rpm file.
  2. Execute the following command with superuser permissions:
    rpm -i filename.rpm

    This installs the product to the following default location - /opt/microfocus/VisualCOBOL.

Alternatively, you can start the filename.rpm file from the file manager program available on your operating system:

  1. Open the file manager program and navigate to the location of the filename.rpm file.
  2. Start the file.

    This installs the product and any missing prerequisites.

Installing using the yum utility

The yum repository must be configured before you start a yum installation. See your yum documentation for instructions. This is not necessary if you have a subscription to an RPM Web site.

To install from a CD or using an ISO image:

  1. Mount the CD or mount the ISO on a virtual machine CD drive using a DevLab machine administration Web page.
  2. Execute the following command to create a repository configuration file:
    vi /etc/yum.repos.d/rhel-dvd.repo
  3. Add the following code to the repository configuration file:
    [dvd]
name=Red Hat Enterprise Linux Installation DVD
baseurl=file:///media/RHEL_6.1_DVD
enabled=1
gpgcheck=0
  4. Execute the following command to start the installation:
    yum install [filename.rpm]
  5. Follow the instructions on the screen to install the package and any missing software prerequisites from the ISO image.

Installing using the YaST2 utility

To install using YaST2:

  1. Open a terminal and navigate to the location of the .rpm file.
  2. Execute the following command:
    yast2 -i filename.rpm
  3. Follow the instructions on the screen to complete the installation.

    If there is any missing prerequisite software, YaST prompts for the CD Media that includes the installation files.

Installing using the zypper utility

To installing using zypper:

  1. Ensure the SUSE OS CD Media is mounted on your machine.
  2. Execute the following from a terminal to see the repositories that are available on your machine:
    zypper repos

    The output is similar to the following:

    # | Alias        | Name         | Enabled | Refresh
--+-----------------------------------+-----------------------------------+---------+--------
1 |  SLES12-12-0 |  SLES12-12-0 | Yes     | No

    Where the number 1 repository is the SUSE OS CD Media.

  3. Execute the following command to select the OS CD Media as the repository to run:
    zypper repos 1
  4. Execute the following command to install the product and its dependencies:
    zypper install [filename.rpm]
  5. Follow the instructions on the screen to complete the installation.

Installing a Micro Focus product as an upgrade

When installing an upgrade or a HotFix release of a Micro Focus product, execute the following command with superuser permissions to upgrade the existing installation:

rpm -U filename.rpm

This upgrades the existing installation of your product in /opt/microfocus/VisualCOBOL.

The installed product that you want to upgrade might contain non-default configuration settings. In such cases, when you are installing an upgrade, the RPM installer creates copies of the existing configuration files with an extension filename.rpmsave before installing the configuration files from the newer product version.

To check whether the installer has created copies of any of the older configuration files, execute the following command after you install the product:

find /opt/microfocus/VisualCOBOL -name *.rpmsave -print

Installing without root user permissions

By default, you must run the RPM installer with superuser permissions so that it has write access to the RPM installation database.

In order to perform a non-root installation, you need to create and use a local user RPM installation database which does not require superuser permissions.

To install into a non-root location, execute the following commands:

cd $HOME
mkdir -p $HOME/rpmdb
rpm --initdb --dbpath $HOME/rpmdb
rpm --root $HOME --dbpath $HOME/rpmdb --relocate /usr=$HOME \ --nodeps -i --nodeps --prefix=$HOME/VisualCOBOL filename.rpm

Installing the product into a non-default location

To install the product into a non-default location, execute the following command with superuser permissions:

rpm -i --prefix=[FullPath] filename.rpm

Where FullPath is the directory on your machine where you want to install the product.

Viewing the log files

During the installation, the RPM installer creates a log file in /opt/microfocus/logs. The log file contains all of the information that was displayed on the terminal screen during the installation as well as some additional information about the product configuration.

Parent topic: RPM Installer


Other RPM Installer Options

The following list includes some additional command line options available for the RPM installer.

To display a list of all Micro Focus products installed on your machine:

rpm -qa | grep Micro_Focus

This returns PackageName, the RPM names of the Micro Focus products which are used to identify the install packages.

To show the RPM package information:

rpm -qi [PackageName]

To show the location of an installed product:

rpm -ql [PackageName] | head -1

To check which files have post-install changes:

rpm -V [PackageName]

To view a list of the contents of an RPM file:

rpm -qpl filename.rpm

To view the dependencies of an RPM file:

rpm -qpR filename.rpm

To view a list of the files in an RPM package before installing the product:

rpm -qip filename.rpm

To display the scripts that run during the installation:

rpm -qp --scripts filename.rpm

To check whether the RPM file is corrupt:

rpm -Kvv --nosignature filename.rpm

To find the default installation location for a package:

rpm -q --qf "%{PREFIXES}\n" -p filename.rpm

For Visual COBOL, this is /opt/microfocus/VisualCOBOL.

To install the product into a non-default location, execute the following command with superuser permissions:

rpm -i --prefix=[FullPath] filename.rpm

To install a product and skip any package dependencies:

rpm -i --nodeps filename.rpm

By default, RPM installers only install one product at a time. This is to avoid overwriting any products installed in the default location. To install two or more products on the same machine, use the --prefix and --nodeps options together to install the additional products:

rpm -i --nodeps --prefix=[FullPath] filename.rpm

To access the files in the installer and view the installer payload, you can extract the contents of an RPM file to your disk without installing the product. To do this, use the following command:

rpm2cpio filename.rpm | cpio -idmv
Parent topic: RPM Installer


Uninstalling Using the RPM Installer

To uninstall a Micro Focus product:
  1. Execute the following command to discover the name of the installed package:
    rpm -qa | grep Micro_Focus

    This returns PackageName, the RPM name of your Micro Focus product which is used to identify the install package.

  2. Execute the following command to uninstall the product:
    rpm -e [ PackageName ]

Uninstalling several installation packages simultaneously

If you installed the same package more than once on the same machine using the --nodeps --prefix command line options, to remove all of these installations execute the following command:

[ as root ] rpm -e --allmatches [ package name ]
Parent topic: RPM Installer


After Installing

  • Check the Product Documentation section of the Micro Focus SupportLine Web site for any updates to the documentation which might have been uploaded.
  • Setting up the product
  • Configuring the Remote System Explorer Support
  • Repairing on UNIX
  • Uninstalling
Parent topic: Installing Visual COBOL Development Hub


Setting up the product

If you have installed the product to a directory other than the default one, you need to set the environment as described below.

Note: The default directory is /opt/microfocus/Visual COBOL/.
  1. To set up your product, execute:
    . <product-install-dir>/bin/cobsetenv
  2. To verify that your product is installed, execute:
    cob -V
Important: These commands set the environment only for the current shell. You need to execute them for each new shell that you start.

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

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

Note: If there are two or more products installed on the machine or the products are installed in non-default locations then the /opt/microfocus/logs/MicroFocusProductRegistry.dat data file can be used to find the product locations.

The file contains the following entries:

[ Install Location ]#[ Date of Installation ]#[ Product Name ]

For example:

/home/user1/VisCobol30#2017-01-20#Micro Focus Visual COBOL Development Hub 3.0

/home/user1/CobolServer30#2017-01-20#Micro Focus COBOL Server 3.0

Parent topic: After Installing
Related concepts
Accessing Development Hub


Configuring the Remote System Explorer Support

Note: The following only applies if you are using Visual COBOL Development Hub with Visual COBOL for Eclipse.

The remote development support from the Eclipse IDE relies upon Visual COBOL Development Hub running on the UNIX machine and handling all requests from the IDE for building and debugging programs. Visual COBOL Development Hub provides a UNIX daemon, the Remote Development Option (RDO) daemon, which initiates the RDO as Eclipse clients connect to it. Whichever environment is used to start the RDO daemon will be inherited for all servers and hence all build and debug sessions.

Configuring the Environment

You may need to configure some aspects of the environment before you start the daemon. This is because when a build or debug session is initiated on the Development Hub from one of the Eclipse clients, the environment used will be inherited from whatever was used to start the daemon. A typical example of the kind of environment that might need to be set up would include database locations and settings for SQL access at build/run time.

Starting the Daemon

Important: Before starting the daemon you must have the following on your UNIX machine:
  • A version of Perl.
  • A version of Java 8 or later.
  • The as (assembler) and ld (linking) programs on the path, as specified by the PATH environment variable.

To start the daemon on the default port (4075) as a background process, perform this command with superuser authority:

$COBDIR/remotedev/startrdodaemon

The daemon will now listen for any Eclipse client processes connecting to that machine on port 4075. If you want to use another port, specify another port number on the startrdodaemon command.

The daemon can also be configured to instantiate the servers on a specified port or range of ports. This is particularly relevant when you want to only open certain ports through a firewall. To do this, perform this command with superuser authority:

$COBDIR/remotedev/startrdodaemon [<port> | <low port>-<high port>]
where:
  • <port> is the port number the daemon should use to listen for connections from Eclipse on the client machine. If no value is given, it will be assigned a default value of 4075. This value matches the value assigned within the Eclipse installation.

    For example,

    $COBDIR/remotedev/startrdodaemon 4999

    This command will start a daemon listening on port 4999 and will use random server ports.

  • <low port>-<high port> is the range of ports on which the servers (launched by the daemon) should use to communicate with Eclipse on the client machine.

    For example,

    $COBDIR/remotedev/startrdodaemon 4080 4090-4999

    This command will start a daemon listening on port 4080 and server ports will be in the range 4090 to 4999.

Stopping the Daemon

To stop the daemon, type the following command with superuser authority:

$COBDIR/remotedev/stoprdodaemon <port>
Parent topic: After Installing


Repairing on UNIX

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

Parent topic: After Installing


Uninstalling

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

To uninstall this product:

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

To uninstall Micro Focus License Administration:

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

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

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

Parent topic: After Installing


Managing Licenses

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


Overview

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

When you install your Micro Focus product, the Sentinel RMS license server is also installed to manage your license. Depending on how your site administers licenses, you can request licenses from a central license server.

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 that uses Sentinel RMS

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

Parent topic: Managing Licenses


To start Micro Focus License Administration

Log on as root, and from a command prompt type:
/var/microfocuslicensing/bin/cesadmintool.sh
Parent topic: Managing Licenses


Installing licenses

You need either a license file (with a .mflic extension) or an authorisation code which consists of a string of 16 alphanumeric characters.

  • If you have a license file
  • If you have an authorization code
  • Configuring your machine to use a central license server
Parent topic: Managing Licenses


If you have a license file

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


If you have an authorization code

  • Authorizing your product when you have an Internet connection
  • Authorizing your product when you don't have an Internet connection
Parent topic: Installing licenses


Authorizing your product when you have an Internet connection

Note:
  • This topic only applies if you have an authorization code
  • It is not possible to install licenses remotely. You must be logged into the machine on which you are installing the licenses.

The following procedure describes how to authorize your product using a local or network license server. The license server is set up automatically when you first install the product.

  1. Start Micro Focus License Administration.
  2. Select the Online Authorization option by entering 1 and pressing Enter.
  3. Enter your authorization code at the Authorization Code prompt and then press Enter.
Parent topic: If you have an authorization code


Authorizing your product when you don't have an Internet connection

Note: This topic only applies if you have an authorization code.

This method of authorization is required if the machine you want to license does not have an Internet connection or if normal (automatic) authorization fails.

In order to authorize your product you must have the following:
  • Access to a computer which is connected to the Internet.
  • Your authorization code (a 16-character alphanumeric string).
  • The machine ID. To get this, start the Micro Focus License Administration tool and select the Get Machine Id option by inputting 6. Make a note of the "Old machine ID".

If you have previously received the licenses and put them in a text file, skip to step 6.

  1. Open the Micro Focus license activation web page http://supportline.microfocus.com/activation in a browser.
  2. Enter your authorization code and old machine ID and, optionally, your email address in the Email Address field.
  3. Click Generate.
  4. Copy the licenses strings from the web page or the email you receive into a file.
  5. Put the license file onto your target machine.
  6. Start the Micro Focus License Administration tool and select the Manual License Installation option by inputting 4.
  7. Enter the name and location of the license file.
Parent topic: If you have an authorization code


Configuring your machine to use a 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 Micro Focus SupportLine.
  1. Start Micro Focus License Administration
  2. Select the Advanced Configuration Options option by inputting 3.
  3. Select the License server option by inputting the corresponding list number and pressing Enter.
  4. Enter the IP address or server name of the central license server and press Enter.
Parent topic: Installing licenses


Installing licenses silently

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

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

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

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

Parent topic: Managing Licenses


Viewing installed licenses

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

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

Parent topic: Managing Licenses


Uninstalling licenses

Licenses installed with an authorization code have a Revoke link in the Uninstall column. Licenses installed using a license file have a Remove link in the Uninstall column

  • Removing licenses
  • Revoking licenses when you have an Internet connection
  • Revoking licenses when you do not have an Internet connection
Parent topic: Managing Licenses


Removing licenses

Note: This topic only applies if you installed the product using a license file (.mflic).
  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to remove and press Enter.
Parent topic: Uninstalling licenses


Revoking licenses when you have an Internet connection

Note: This topic only applies for licenses installed with an authorization code.

You must revoke licenses if, for example, you want to move your product to a different machine or if you no longer use your product and want to reallocate the license.

You must have write access on the license file that contains the authorization codes.

  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to revoke and press Enter.
  4. Type the number of licenses to revoke and press Enter.
Important: If there is a problem accessing the Micro Focus License Authorization Server and the revocation fails, your licenses are revoked and cannot be used.

An error message is returned confirming there is no Internet connection. This message includes the name of the file containing the License Revocation Tickets (LRTs).

Copy this file into an email and send it to your SupportLine representative.
Parent topic: Uninstalling licenses


Revoking licenses when you do not have an Internet connection

Note: This topic only applies for licenses installed with an authorization code.

You must have write access on the license file that contains the authorization codes.

  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to revoke and press Enter.
  4. Type the number of licenses to revoke and press Enter.

    An error message is returned confirming there is no Internet connection. This message includes the name of the file containing the License Revocation Tickets (LRTs).

  5. Copy this file into an email and send it to your SupportLine representative.
Parent topic: Uninstalling licenses


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
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. Navigate to Product Updates on the Micro Focus SupportLine pages: https://supportline.microfocus.com/websync/productupdatessearch.aspx.
  2. Click Search updates by Product Name: and select License Manager from the drop-down list.
  3. Click Find Updates.
  4. Click + in front of License Manager and then in front of the version you are interested in.
  5. Click [image] to download the installer.
  6. Run the installer 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. You can download this from the Product Updates page on the Micro Focus SupportLine Web site. A link is provided in the customer's EPD email.
  • Installing on UNIX and Linux
Parent topic: Installing License Manager


Installing on UNIX and Linux

Notes:
  • Before you perform this procedure, ensure you are logged in as root.
  • The console mode License Manager is a Java application and therefore requires a Java Runtime Environment installed and available on the path.
  1. Run the following commands:

    pax -rf [platform ]_10000_2_1380.pax

    chmod +x ./MFLicenseServerInstall.sh

    ./MFLicenseServerInstall.sh

  2. Change directory to:

    /var/microfocuslicensing/bin

  3. To start the console mode License Manager:

    cesadmintool.sh

    You can now manage licenses on the machine.

Parent topic: Installing a standalone network license server


Trial licenses

Depending on your product you may have trial licenses installed. If this is the case and you have not yet authorized your full license a Trial Notice dialog box might be displayed when you run your product.

While you are using a trial license within the license period, the Trial Notice dialog box might display every time you run your product. To prevent this, enter your authorization code to obtain a full license.

CAUTION:
If you are using a timed license (for example, a 30 day trial license), do not change the machine’s date and time. If you do, the license will be invalidated and you will need to call Micro Focus SupportLine.

If you need to change the machine’s date and time, make sure that you have installed a full license that is not time limited.

Parent topic: Managing Licenses


Commuter licenses

A commuter license can be moved temporarily from a license server on your network to your own computer. You can then use that license while you are disconnected from the server. Commuter licenses are useful when, for example, working from home or visiting a client site.

You obtain and manage commuter licenses by using the Micro Focus License Administration tool. If there are any commutable licenses on your network server, you can view a list of them by selecting the Commuter/Return Licenses option.

At the end of your commute period the license on your computer expires. The license is available from your network server when you reconnect. Typically, the maximum commute period is 30 days.

You can return a commute license back to the license server before it has expired. Use the Micro Focus License Administration tool to do this.

Not all licenses are commutable. You must have commuter licenses on your license server.

  • To obtain a commuter license
  • To return a commuter license
Parent topic: Managing Licenses


To obtain a commuter license

  1. Start Micro Focus License Administration
  2. Select the Commute/Return Licenses option by inputting 7.
  3. Select the product whose license you want to commute and press Enter.
Parent topic: Commuter licenses


To return a commuter license

  1. Start Micro Focus License Administration
  2. Select the Commute/Return Licenses option by inputting 7.
  3. Select the product whose license you want to return and press Enter.
Parent topic: Commuter licenses


Usage log

The licensing system creates a usage log file that details all licensing activity. In addition to monitoring usage, the file is a useful licensing diagnostic tool.

Log files are called lservrc.log. When they reach 10 MB in size they are archived to lservrc.log.xxx where xxx is an incremental number for the archive file.

The files are located in:
  • /var/microfocuslicensing/logs

As these files contain important and useful information, and to maintain disk space, we recommend that you manage these files accordingly.

Parent topic: Managing Licenses


Licensing Error Messages

  • Initialization error - Initializing: Cannot communicate with licensing daemon
    Check the licensing daemon is running.
  • Error - Initalizing: Cannot find initialization file
    The initialization file <path to Micro Focus licensing bin directory> ces.ini is missing. Verify your installation with Micro Focus SupportLine.
  • Error - Unable to manage licenses in license manager that is not running on localhost
    You have a remote license server configured. You should install the licenses on that machine or configure your license server to be the local host.
  • Error [5]: Cannot talk to the license server on host "xxx.x.x.x". Server not running
    The /etc/hosts file might not contain an entry for hostname and IP address.
  • Error authorizing... Remote request error - The authorization code is invalid
    Check the authorization code you have entered against the code provided by Micro Focus.
  • Error [26] - Request Denied due to clock tamper detection
    The clock has been changed on a machine where a time-limited license is installed.
  • Error[18]: No license code is available for feature (component)
    The license string installed on the machine does not contain the necessary license string of the component being used.
  • Unable to authorize (cause)
    The authorization code cannot be verified. The specific cause is given in the brackets. Depending on the nature of the message, further detail and instruction will accompany the message.
Parent topic: Managing Licenses
Parent topic: Licensing


Initialization error - Initializing: Cannot communicate with licensing daemon

Check the licensing daemon is running.

Run /var/microfocuslicensing/bin/mfcesdchk to check if the daemon is running.

If it isn't, log in as root and run /var/microfocuslicensing/bin/startmfcesd.sh to start it.

Parent topic: Licensing Error Messages


Error - Initalizing: Cannot find initialization file

The initialization file <path to Micro Focus licensing bin directory> ces.ini is missing. Verify your installation with Micro Focus SupportLine.
Parent topic: Licensing Error Messages


Error - Unable to manage licenses in license manager that is not running on localhost

You have a remote license server configured. You should install the licenses on that machine or configure your license server to be the local host.
Parent topic: Licensing Error Messages


Error [5]: Cannot talk to the license server on host "xxx.x.x.x". Server not running

The /etc/hosts file might not contain an entry for hostname and IP address.
Ensure that these values are added to the /etc/hosts file. You can find the hostname by typing hosntame from a command prompt. To obtain the IP address, type /sbin/ipconfig from a command prompt.
Parent topic: Licensing Error Messages


Error authorizing... Remote request error - The authorization code is invalid

Check the authorization code you have entered against the code provided by Micro Focus.
Parent topic: Licensing Error Messages


Error [26] - Request Denied due to clock tamper detection

The clock has been changed on a machine where a time-limited license is installed.
Contact your Micro Focus SupportLine representative in order to resolve the matter. You will be asked to provide the locking code of the machine and in return will receive a clean certificate which you run on the machine in order to restore the license to its previous working state.
Parent topic: Licensing Error Messages


Error[18]: No license code is available for feature (component)

The license string installed on the machine does not contain the necessary license string of the component being used.
Contact your Micro Focus SupportLine representative in order to obtain the correct license string.
Parent topic: Licensing Error Messages


Unable to authorize (cause)

The authorization code cannot be verified. The specific cause is given in the brackets. Depending on the nature of the message, further detail and instruction will accompany the message.
Parent topic: Licensing Error Messages


Updates and Product Support

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

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

  1. Click Register on the Product Support page.
  2. Enter your details. You will need your product serial numbers, which you can find .

To log in:

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

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

  2. Click Login.

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

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

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

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


Setup and Licensing

Read these topics to learn how to setup and license your product.

  • Installing Visual COBOL Development Hub
  • Managing Licenses
Parent topic: Product Information


Micro Focus End User License Agreement

  • MICRO FOCUS® ENTERPRISE DEVELOPER v5
  • MICRO FOCUS ENTERPRISE SERVER v5
  • MICRO FOCUS ENTERPRISE SERVER FOR .NET v5
  • MICRO FOCUS ENTERPRISE TEST SERVER v5
  • MICRO FOCUS ENTERPRISE TEST SERVER PREMIUM v5
  • VISUAL COBOL® v5
  • COBOL SERVER v5
  • DATABASE CONNECTORS v5

IMPORTANT: LICENSOR IS PROVIDING THIS LICENSED SOFTWARE TO LICENSEE (THE ORIGINAL PURCHASER EITHER AS AN INDIVIDUAL OR ON BEHALF OF ANOTHER LEGAL ENTITY AS ITS EMPLOYEE OR AUTHORIZED AGENT) FOR ITS USE SUBJECT TO LICENSEE’S AGREEMENT TO THE TERMS AND CONDITIONS SET FORTH BELOW. THESE TERMS AND CONDITIONS MAY BE DIFFERENT FROM THE END USER LICENSE AGREEMENT(S) THAT ACCOMPANIED EARLIER RELEASES OF THE LICENSED SOFTWARE. PLEASE READ THEM CAREFULLY TO ENSURE FULL UNDERSTANDING BEFORE PROCEEDING, AS THEY MAY CONTAIN ADDITIONAL RESTRICTIONS ON YOUR USE OF THE SOFTWARE. PLEASE DIRECT ANY QUESTIONS TO THE MICRO FOCUS LEGAL DEPARTMENT AT LEGALDEPT@MICROFOCUS.COM. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT, YOU WILL NOT BE AUTHORIZED TO USE THE LICENSED SOFTWARE. BY CLICKING THE ACCEPT BUTTON OR SIMILAR ACCEPTANCE MECHANISM DURING INSTALLATION, OR BY COPYING OR USING THE LICENSED SOFTWARE, LICENSEE ACKNOWLEDGES THAT IT HAS READ THIS LICENSE AGREEMENT, UNDERSTOOD IT, AND AGREED TO BE BOUND BY ITS TERMS AND CONDITIONS. THE LICENSED SOFTWARE IS LICENSED NOT SOLD.

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

"Documentation" means the Licensor user documentation that is included with the Licensed Software.

"Licensee" means the single legal entity or person that rightfully acquires the Licensed Software from Licensor or from a distributor or reseller of Licensor.

"License Options" means those license options set forth in Annex 1 to this License Agreement.

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

"Licensed Software" means the object code version of the Licensor computer program(s) listed above, their Documentation, and other supplemental materials, as provided to Licensee by Licensor, including but not limited to any software security keys relating thereto. The Documentation may be delivered electronically and may only be available in the English language. The Licensed Software will be accompanied by a license key where required for activation and use of the Licensed Software. The Licensed Software shall also include, and this License Agreement shall govern the use of any update to the Licensed Software that Licensee receives pursuant to a separate support and/or maintenance purchase as described in Section 6 below, unless such update contains or comes with a different end user license agreement, in which case such end user license agreement shall supersede this License Agreement and govern the use of such software license without need for a mutually executed amendment to this License Agreement as set forth in Section 17 of this License Agreement. This License Agreement does not grant Licensee the right to any updates to the Licensed Software unless provided by Licensor under Section 6 and/or Section 7 below.

"Product Order" means a document that has been (i) executed by Licensee describing each Licensed Software license to be purchased, and (ii) accepted by Licensor. Licensor will accept the Product Order by either confirming Licensor's acceptance in writing or by delivering the Licensed Software to Licensee, whichever occurs first. A Product Order may also mean a written quote, or if referred to as such, a solution order, issued by Licensor describing each Licensed Software license purchased that is accepted by Licensee within the validity period of the quote either by Licensee executing and returning the quote or a solution order, to Licensor, by Licensee issuing a purchase order or other written confirmation of acceptance to Licensor in conformance with the quote, and/or by Licensee paying to Licensor all fees set forth in the quote. Each Product Order shall constitute a separate agreement and shall incorporate therein this License Agreement. In the event of any conflict between the terms and conditions of this License Agreement and the terms and conditions of any Product Order, the conflicting terms and conditions of the Product Order shall govern. In no event shall any terms and conditions contained in a purchase order or similar document issued by Licensee in connection with this License Agreement or with a Product Order apply and any such document issued shall be only for the administrative purposes of identifying the Licensed Software ordered, the number of licenses, and the price to be paid and shall have no other legal effect. Licensor for purposes of this paragraph shall mean Licensor or, if applicable, one of Licensor's authorized resellers from whom Licensee purchases the Licensed Software, provided however that any conflicting or additional terms in a Product Order accepted by an authorized reseller of Licensor shall have no effect unless such terms have been agreed by Licensor in writing.

"Warranty Period" means a period of ninety (90) days from delivery of the Licensed Software to Licensee.

  1. GRANT OF LICENSE; LICENSE CONDITIONS. For payment of the applicable non-refundable license fees identified on the Product Order and subject to Licensee's compliance with the terms and conditions set forth in this License Agreement, Licensor grants solely to Licensee, as an end user, a personal, perpetual (unless a subscription/term license has been purchased by Licensee), non-transferable, non-sublicensable and non?exclusive license to use the Licensed Software solely for its own internal use and benefit. Licensee's use and operation of the Licensed Software and the license grant provided to the Licensed Software is subject to Licensee being in possession of a valid license key where required for the Licensed Software to run. Licensee agrees that Licensor is not liable or responsible for lost or broken license keys or media or the provision of replacement license keys or media and/or new license keys or media unless Licensee is current on support and maintenance for the applicable license and then only to the extent set forth in the applicable annual support and/or maintenance agreement and only to the extent Licensor then has sufficient rights from any applicable third party suppliers, if necessary, to provide such replacement. If not current on support and maintenance for the applicable license, replacement or new license keys or media may be available for purchase at Licensor's then current list fees for applicable new licenses.

    Different License Options are available from Licensor as set forth or referred to in Annex 1. The applicable License Option and license count to be purchased by Licensee for the Licensed Software shall be identified in the Product Order or otherwise identified in writing by Licensor. Licensed Software is also subject to additional terms and conditions as set forth in the "Specific Software Terms" located in Annex 2. Any conflicting terms and conditions shall be resolved according to the following order of precedence: Annex 2, Annex 1, and the main body of the License Agreement.

  2. USE RESTRICTIONS. Except as may be otherwise specifically permitted in Annex 1 or Annex 2 to this License Agreement, Licensee agrees not to:
    • 2.1 Copy and/or distribute the Licensed Software, in whole or in part, for internal use without paying Licensor the applicable additional fees required by Licensor, except (i) for making a reasonable number of archival back-up copies; or (ii) as expressly authorized by Licensor in writing; or (iii) for making a reasonable number of copies of the Documentation supplied to Licensee by Licensor in electronic form. Licensee shall reproduce and affix all copyright and other proprietary rights notices appearing in or on the Licensed Software, including notices of all third party suppliers.
    • 2.2 Use the Licensed Software for timesharing, facilities management, outsourcing, hosting, service bureau use, or for providing other application service (ASP) or data processing services to third parties or for like purposes.
    • 2.3 Modify the Licensed Software or provide any person with the means to do the same.
    • 2.4 Create derivative works of the Licensed Software, or translate, disassemble, recompile or reverse engineer the Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity).
    • 2.5 Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software or Documentation.
    • 2.6 Use the Licensed Software in a manner other than as specifically permitted in this License Agreement.
  3. AUDITS. Licensor or an Auditor (as defined below) has the right to verify Licensee's compliance with this License Agreement (and please see Micro Focus License Compliance Charter - http://supportline.microfocus.com/licensing/licVerification.aspx). Licensee agrees to:
    • A. Implement internal safeguards to prevent any unauthorized copying, distribution, installation, or use of, or access to, the Licensed Software and associated support and maintenance, or breach of the terms or conditions of this License Agreement;
    • B. Take all necessary steps to destroy or erase all Licensed Software codes, programs and other proprietary information before disposing of any media containing the Licensed Software;
    • C. Keep records sufficient to certify Licensee's compliance with this License Agreement including serial numbers and license keys of the Licensed Software, hypervisor logs where applicable, and the location, model (including quantity and type of processor) and serial number of all machines on which the Licensed Software is installed or from which the Licensed Software is accessed, and the names (including corporate entity) and number of users that are accessing the Licensed Software, and, upon request of Licensor, provide and certify metrics and/or reports based upon such records and account for, among other things, numbers of copies (by product and version) and network architectures as they may reasonably relate to Licensee's licensing and deployment of the Licensed Software and associated support and maintenance;
    • D. Upon Licensor's request, Licensee shall furnish Licensor or an independent auditor chosen at Licensor's sole discretion ("Auditor"), within seven (7) days of the request, with a completed questionnaire provided by Licensor or the Auditor, and with a written statement, in a format required by Licensor, signed by a director of Licensee, certifying the accuracy of any information provided;
    • E. Allow a Licensor representative or an Auditor to inspect and audit Licensee's computers and records, during Licensee's normal business hours, for compliance with the licensing terms for Licensor's software products and associated maintenance. Upon Licensor's (and Auditor's if applicable) presentation of their signed written confidentiality statement form, Licensee shall fully cooperate with such audit and provide any necessary assistance and access to records and computers; and
    • F. In the event that Licensee has or at any time has had unlicensed installation, use of, or access to the Licensed Software or has otherwise breached the license granted (a "Non-Compliance"), without prejudice to any other rights or remedies Licensor may have, including without limitation injunctive relief, Licensee shall, within thirty (30) days, purchase sufficient licenses and or subscriptions and associated support and maintenance to cure the Non-Compliance, without benefit of any otherwise applicable discount, by paying Licensor's current (as of the date of such additional purchase) list license fees and 12-month support and maintenance fees to Licensor for such additional licenses, plus Licensor's current (as of the date of such additional purchase) list term license and support and maintenance fees and interest (compounded at 1.5% monthly or the maximum rate permitted by applicable law if lower) for such additional licenses for the time period from the commencement of the Non-Compliance until payment of the aforementioned fees. The aforementioned interest shall be payable even if an invoice was not issued at the time the Non-Compliance commenced. If a material license shortfall of 5% or more is found, Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due. The obligations in this Section 3 shall apply to both Licensee's Non-Compliance and any third party's Non-Compliance.
  4. DOCUMENTATION. One (1) electronic copy of Licensor's standard Documentation, describing Licensor's recommended use and application of the Licensed Software, will be furnished or made available on Licensor's website free of additional charge to Licensee by Licensor with the Licensed Software. Printed copies of any Documentation may be available for purchase from Licensor or its authorized distributors. Additional copies of standard Documentation may be available on Licensor's website.
  5. TERM OF LICENSE. This License Agreement and Licensee's license for the Licensed Software is perpetual, unless a subscription/term license has been purchased by Licensee (in which case the term of the license shall be as set forth in the Product Order, specified in Annex 1 or Annex 2, or as otherwise agreed in writing between the Licensee and Licensor), and is subject to earlier termination as provided in this Section 5. If Licensee has purchased a subscription/term license, Licensee's license to the Licensed Software shall automatically terminate upon expiry of such subscription/term. Licensor may terminate this License Agreement and Licensee's license to the Licensed Software immediately by giving Licensee written notice of termination in the event that either (i) Licensee breaches any term or condition of this License Agreement and Licensee has failed to remedy such breach within ten (10) days of the date of notice from Licensor to Licensee or (ii) Licensee is wound up, has a receiver appointed or has applied for or enters into liquidation or bankruptcy or analogous process or processes. Termination shall be without prejudice to any other rights or remedies Licensor may have. In the event of any termination Licensee will have no right to keep, access, or use the Licensed Software or any copy of the Licensed Software for any purpose and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control, and forward written certification to Licensor that all such copies of Licensed Software have been destroyed or erased. Termination shall not entitle the Licensee to any refund or reimbursement of any kind of previously paid fees. The rights and obligations of the parties contained in Sections 3, 8, 9, 10, 11, 12, and 13, and other sections that by their nature are intended to survive, will survive the termination or expiration of this License Agreement.
  6. SUPPORT AND MAINTENANCE. Where Licensee purchases support and/or maintenance services, Licensee's initial support and/or maintenance term will begin upon delivery to Licensee of the Licensed Software and continue for one (1) year thereafter (or the length of the term if less than a year for any subscription/term license) unless otherwise specified in the applicable annual support and/or maintenance agreement, Product Order, or other written agreement executed between Licensor and Licensee. Where Licensee purchases support and/or maintenance for any Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software product. Support and/or maintenance services provided by Licensor will be subject to Licensor's then current applicable standard annual support and/or maintenance agreement unless otherwise agreed by the parties in writing.
  7. LIMITED WARRANTY. Licensor warrants for the Warranty Period (i) that if the Licensed Software is supplied via media, then the media will be free from defects in materials or workmanship under normal use and (ii) that the copy of the Licensed Software delivered to Licensee conforms in all material respects to the Documentation. As the sole and exclusive remedy for not meeting part (i) of the above warranty, Licensor's sole obligation shall be to repair or replace free of charge any defective media on which the Licensed Software is delivered if the media is returned to Licensor by Licensee during the Warranty Period. As the sole and exclusive remedy for not meeting part (ii) of the above warranty, Licensor shall repair or replace the Licensed Software free of charge so that it conforms with the warranty or, if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid by Licensee with respect to that particular Licensed Software. Upon such refund Licensee's license to use such Licensed Software will terminate. The warranty set forth in this Section 7 shall not apply if the defect in the Licensed Software is the result of: (a) the Licensed Software not being used in accordance with the Documentation, this License Agreement or with the platform(s) for which the Licensed Software has been designed and licensed by Licensor; or (b) the Licensed Software having been altered, modified or converted by Licensee or any third party except as may be specified in the Documentation; or (c) the malfunctioning of Licensee's equipment; or (d) accident or abuse; or (e) service by any unauthorized person; or (f) other software used by Licensee which has not been provided by Licensor or for which the Licensed Software is not designed and licensed for operation; or (g) Third Party Software (as defined herein); or (h) any other cause occurring after initial delivery of the media to Licensee unless caused directly by Licensor. The foregoing states the complete and entire remedies that Licensee has under this warranty. Licensor shall have no responsibility for any warranty claims made outside of the Warranty Period. The foregoing warranty shall not apply to any free-of-charge Licensed Software including updates, though issues with such software may be eligible for support under applicable support terms and conditions.
  8. DISCLAIMER OF WARRANTY. The Licensed Software cannot be tested in every possible operating environment, therefore Licensor does not warrant that the functions contained in the Licensed Software will meet Licensee's requirements, that operation of the Licensed Software will be uninterrupted, or that the Licensed Software is error free. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE EXCLUDED ON THE PART OF LICENSOR AND ITS THIRD-PARTY SUPPLIERS. Licensee acknowledges that Licensee is responsible for the selection of the Licensed Software to achieve Licensee's intended results and for the installation and/or use of, and results obtained from, the Licensed Software.
  9. LIMITATION OF LIABILITY. ANY LIABILITY OF LICENSOR SHALL BE LIMITED IN THE AGGREGATE TO THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE GIVING RISE TO THE APPLICABLE CLAIM. THIS LIMITATION APPLIES TO ALL CAUSES OF ACTION, INCLUDING WITHOUT LIMITATION BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR SIMILAR DAMAGES NOR FOR ANY LOSS OF PROFITS, CONTRACTS, DATA, OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE. LICENSOR’S LIMITATIONS OF LIABILITY ARE NOT CUMULATIVE. LICENSEE’S REMEDIES IN THIS LICENSE AGREEMENT ARE LICENSEE’S EXCLUSIVE REMEDIES.

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

    LICENSEE AGREES THAT, IN ENTERING INTO THIS LICENSE AGREEMENT, EITHER IT DID NOT RELY ON ANY REPRESENTATIONS (WHETHER WRITTEN OR ORAL) OF ANY KIND OTHER THAN THOSE EXPRESSLY SET OUT IN THIS LICENSE AGREEMENT, OR IF IT DID RELY ON ANY REPRESENTATIONS, THAT IT SHALL HAVE NO REMEDY AGAINST LICENSOR IN RESPECT OF SUCH REPRESENTATIONS.

    LICENSEE FURTHER ACKNOWLEDGES THAT THE LIMITATIONS OF LIABILITY IN THIS SECTION ARE AN ESSENTIAL ELEMENT OF THIS LICENSE AGREEMENT AND THAT, IN THE ABSENCE OF SUCH LIMITATIONS, THE PRICING AND OTHER TERMS AND CONDITIONS SET FORTH HEREIN WOULD BE SUBSTANTIALLY DIFFERENT.

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

  10. HIGH-RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury or severe physical or environmental damage. Licensor and its suppliers shall have no liability for any use of the Licensed Software in any high-risk situations.
  11. OWNERSHIP. Licensor (or its affiliates) and where applicable Licensor's third party suppliers have and will retain all ownership rights to the Licensed Software, together with any complete or partial copies thereof. Such ownership rights include without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. This License Agreement does not convey any proprietary interest to Licensee with respect to the Licensed Software other than the license specified herein.
  12. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may come with and/or require certain named third party software programs that Licensee shall license directly from the third party subject to such third party's terms and conditions (for example Adobe Acrobat or Microsoft Internet Explorer) ("Third Party Software"). Any Third Party Software is provided by the licensor of the Third Party Software solely under a direct license between such third party and Licensee under such third party's terms and conditions. Therefore the obligations, duties and rights of Licensor and Licensee under this License Agreement do not apply to such Third Party Software. Additionally, Licensor has embedded in some Licensed Software certain run time or other elements provided by third party suppliers to Licensor ("Third Party Components"). Such Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee pursuant to this License Agreement. Third Party Components may also include open source software, details of which (where applicable) may be found (i) in a file accompanying the applicable Licensed Software or (ii) in the applicable Documentation. Licensee may only access Third Party Components of the Licensed Software in the course of using the Licensed Software. Licensee may not make or attempt any direct access to any such Third Party Components other than with the Licensed Software. All limitations, restrictions and obligations applicable to the Licensed Software set forth in this License Agreement shall apply to Licensee's use of the Third Party Components. The Third Party Software and Third Party Components are the property of its respective third party supplier to Licensor. Such third party suppliers own all copies of the Third Party Software and Third Party Components, however made. Licensee agrees not to contest the ownership of the Third Party Software and Third Party Components nor use any trademark or service mark belonging to such third party suppliers. Licensee agrees that such third party suppliers are intended third party beneficiaries of all terms and conditions of this License Agreement intended to protect intellectual property rights in the Licensed Software (including the Third Party Components) and limit certain uses thereof. Nothing in this License Agreement shall restrict, limit or otherwise affect any rights or obligations Licensee may have, or conditions to which Licensee may be subject, under any applicable open source licenses to any open source code contained in the Licensed Software.
  13. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Software and Documentation are deemed to be "Commercial Items," as defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7207, as applicable. Consistent with such sections, the Licensed Software and Documentation are licensed to U.S. Government end users (i) only as Commercial Items, and (ii) with only those rights as are granted pursuant to this License Agreement. Manufacturer is Micro Focus (US), Inc., 700 King Farm Blvd., Suite 125, Rockville, MD 20850 as or on behalf of Licensor.
  14. LICENSE FEES AND PAYMENT TERMS. Licensee agrees to pay the applicable end user license fees for the Licensed Software within thirty (30) days of the date of invoice or such other date as agreed in writing by the parties. End user license fees are non-refundable except as provided in Section 7 above, or in the Specific Software Terms below, and shall be paid without deduction, including without limitation, of any withholding tax. End user license fees are exclusive of any applicable transportation charges, value added and other applicable taxes and duties and all such amounts shall be paid or reimbursed by Licensee. Outstanding past-due amounts shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by applicable law. Licensee shall be liable for any such interest and all related collection costs, whether or not an action has been filed. Licensor may decline to enter into any additional Product Orders if any such past-due balance, interest and collection costs are not paid.
  15. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and support software (including operating systems) and for proper installation and implementation of and training concerning the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting and/or training services), Licensee and Licensor agree that such services shall be subject to Licensor's then current standard terms, conditions and rates for such services unless otherwise agreed in writing by Licensor.
  16. PRIVACY. If the Licensed Software contains features that may allow Licensee to collect data from, control and/or monitor computers running the Licensed Software deployed by Licensee without notice to or knowledge by users of the Licensed Software, then: (i) Licensee is solely responsible for, and assumes all liability with respect to, the collection of data with respect to its users of the Licensed Software including, without limitation, notifying such users and complying with all data collection, privacy and other regulations, laws, industry standards and rights of others applicable to any such activity; and (ii) Licensee shall indemnify and hold Licensor harmless from and against any damages, claims, losses, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection therewith. To the extent permitted by law, by entering into this License Agreement, Licensee hereby expressly consents to (i) Licensor sending information to Licensee from time to time advertising the various products that Licensor provides, whether or not such products are provided under this License Agreement; (ii) the use of Licensee's name in Licensor customer lists, promotional materials and/or press releases; and (iii) the collection and use by Licensor of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes; Licensor does not use this information to identify individuals utilizing such software.
  17. MISCELLANEOUS. Licensor may assign this License Agreement (in whole or in part) to any member of Licensor's group of companies or to a purchaser of the intellectual property rights in the Licensed Software, but otherwise neither this License Agreement nor any rights hereunder may be assigned (any change of control merger, sale or other transfer of all, or substantially all, of the assets of Licensee shall be included in the meaning of an assignment) nor duties delegated by either party, and any attempt to do so will be void.

    If Licensee acquires the Licensed Software in North America, the laws of the state of Maryland govern this License Agreement and the licenses granted hereunder and the parties hereto consent and agree that they shall be subject to the exclusive jurisdiction of the State and/or Federal courts sitting in the State of Maryland in any action based on this License Agreement or concerning the licenses granted, or the products licensed, hereunder. Each party waives any right it may have to object to such venue, including objections based on personal jurisdiction or forum non conveniens (inconvenient forum). The parties agree that the Uniform Computer Information Transaction Act or any version thereof, adopted by any state, in any form ("UCITA"), shall not apply to this License Agreement. To the extent that UCITA is applicable, the parties hereby opt out of the applicability of UCITA pursuant to the opt-out provision(s) contained therein. If Licensee acquires the Licensed Software in France, Germany or Japan, this License Agreement is governed by the laws of the country in which Licensee acquired the Licensed Software. In the rest of the world the laws of England govern this License Agreement. The aforesaid applicable law shall apply without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this License Agreement, the licenses granted hereunder, and the parties hereto, shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid. In the event of a dispute, the prevailing party shall have the right to collect from the other party its reasonable costs and necessary disbursements and attorneys' fees incurred in enforcing this License Agreement.

    This License Agreement is in addition subject to any United States, United Kingdom or European Union laws, regulations and other restrictions regarding export or re-export of computer software and technology. Licensee agrees not to export or re-export any Licensed Software or derivative thereof in contradiction to any such applicable restriction. In particular but without limitation, Licensee acknowledges that Licensor's products and/or technology are subject to the U.S. Export Administration Regulations (the "EAR") and Licensee agrees to comply with the EAR. Licensee will not export or re-export Licensor's products, directly or indirectly, to: (1) any countries that are subject to US or applicable export restrictions; (2) any end user who Licensee knows or has reason to know will utilize Licensor's products in the design, development or production of nuclear, chemical or biological weapons, or rocket systems, space launch vehicles, and sounding rockets, or unmanned air vehicle systems; or (3) any end user who has been prohibited from participating in export transactions by any applicable agency of government. By downloading or using the Licensed Software, Licensee is agreeing to the foregoing and Licensee is representing and warranting that Licensee is not located in, under the control of, or a national or resident of any such country or on any such list.

    Licensor may identify Licensee by name and/or logo as a licensee of Licensor for investor relations, analyst relations, and public relations purposes, and in online and printed sales and marketing materials. Any other use of Licensee's name or logo, or a description of Licensee's use of the Licensed Software, shall be subject to Licensee's prior consent. Within eight (8) weeks after installation of the Licensed Software, upon Licensor's written request Licensee will provide Licensor with input to a written description of Licensee's use of the Licensed Software including details of the business challenge, software solution, and results realised from the installation of the Licensed Software. The input shall be provided by a representative of Licensee (who is knowledgeable of the Licensed Software and its performance after installation) during a meeting with a representative of Licensor (at a reasonable time to be agreed by the parties). The meeting may be conducted by telephone. This input may be used internally within Licensor and in confidential sales situations. Any other use of this input shall be subject to Licensee's prior consent.

    Except for the Product Order, this License Agreement is the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Software and supersedes all proposals, communications, purchase orders, and prior agreements, verbal or written, including without limitation prior end user license agreements in relation to the Licensed Software between the parties and end user license agreements embedded in such Licensed Software. No employee, agent, or representative of Licensor has the authority to bind Licensor to any oral representation or warranty concerning the Licensed Software. No representation or statement not expressly contained in this License Agreement nor any supplement, modification, or amendment of this License Agreement will be binding on either party unless executed in writing by a duly authorized representative of Licensor and Licensee (excluding any distributor or reseller of Licensor) to this License Agreement. No waiver of any right under this License Agreement will be effective unless in writing, signed by a duly authorized representative of the party to be bound (excluding any distributor or reseller of Licensor). 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 this License Agreement. If any provision in this License Agreement is 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 of this License Agreement will remain unaffected. Each party acknowledges that in entering into this License Agreement it has not relied on any representations, agreements, warranties or other assurances (other than those repeated in this License Agreement and the Product Order) and waives all rights and remedies which but for this section 17 would be available to it. Nothing in this section 17 excludes liability for fraudulent misrepresentation.

    If Licensee is situated in Italy, by placing or executing a Product Order, Licensee declares to have read and to have explicitly approved the following clauses of the License Agreement: 5. Term of License, 6. Support and Maintenance, 7. Limited Warranty, 8. Disclaimer of Warranty, 9. Limitation of Liability, 10. High-Risk Uses, 16. Privacy, 17. Miscellaneous, Annex 1, and Annex 2.

ANNEX 1, LICENSE OPTIONS

DEFINITIONS

For this License Agreement, the following additional definitions shall apply:

"Batch Processing" means the execution of one or more tasks, transactions or programs by a computer system without the continuous interaction of the end user with the Licensed Software for the entire period during which each such task, transaction or program is being executed by the system. Batch processing includes situations where a queue of jobs is processed as resources become available and is in contrast to transaction or interactive processing.

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

"Container" means an isolated user-space instance created using operating-system-level virtualization, also known as containerization. A program running inside a Container can only see the resources and devices assigned to the Container.

"Core" means a physical (not virtual) subunit within a CPU on a single chip that handles the main computational activities of a computer. A CPU may have one or more Cores and therefore be a "Multicore CPU" if it has more than one Core.

"CPU" (Central Processor Unit) means a data processing unit, normally identified with a single microchip mounted on a single circuit board and can comprise several Cores.

"Hard Partitioning" means using hard physical partitioning to physically segment a single larger server or machine into separate and distinct smaller systems where each separate system acts as a physically independent, self-contained server or machine with its own CPUs, operating system, separate boot area, memory, input/output subsystem and network resources (each known as a "Hard Partition"). Examples of Hard Partitioning methods include: Physical Domains (also known as PDomains, Dynamic Domains or Dynamic System Domains), Solaris Zones (also known as Solaris Containers, capped Zones/Containers only), LPAR (adds DLPAR with AIX 5.2), Micro-Partitions (capped partitions only), vPar, nPar, Integrity Virtual Machine (capped partitions only), Secure Resource Partitions (capped partitions only), and Fujitsu’s PPAR.

"Platform" means a hardware chipset (e.g., PA-RISC, Itanium, x86, or SPARC) and operating system (e.g., Windows, Linux, Solaris, AIX, or HP-UX) combination.

"Soft Partitioning" means using an operating system resource manager to segment and limit the number of Cores, CPUs, or other processing devices utilized by the Licensed Software by creating areas where processor resources are allocated and limited within the same operating system (each such area known as a "Soft Partition"). Examples of such Soft Partitioning include: Solaris 9 Resource Containers, AIX Workload Manager, HP Process Resource Manager, Affinity Management, Oracle VM, VMware, and Partition Relocation (such as IBM Power VM Live Partition Mobility).

"Update" means the definition for such term set forth in Licensor's then current applicable standard annual support and/or maintenance agreement.

"Upgrade" means any change in the licensed Platform for the Licensed Software or a successor product to the Licensed Software.

"Virtual Machine" means a software implementation that can run its own operating system and execute programs like a physical machine where the software running inside the virtual machine is limited to the resources and abstractions provided by the virtual machine.

LICENSE OPTIONS

  1. Development License Options (Enterprise Developer and Visual COBOL only)
    1. Named User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server, or one or more Containers on such single machine or server, for use solely by the number of named users expressly authorized by Licensor in the Product Order for whom Licensee has paid the applicable license fee . A named user must only be one named person and such named person has the right to unlimited access to the Licensed Software on such single machine or server. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named users. Licensee may change a named end user provided that the change is made either (i) permanently, or (ii) temporarily to accommodate the use of the Licensed Software by a temporary worker while the named user is absent, but in each case no more than once every 30 days. Licensee may not use the Licensed Software for user acceptance testing, system/load testing, production or deployment.
    2. Concurrent User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on multiple host machines or servers, or one or more Containers on such host machines or servers, for use solely by the maximum number of concurrent users expressly authorized by Licensor in the Product Order for whom Licensee has paid the applicable license fee. Concurrent users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. Licensee may not use the Licensed Software for user acceptance testing, system/load testing, production or deployment.
  2. Deployment License Options (Enterprise Server, Enterprise Server for .NET, Enterprise Test Server, Enterprise Test Server Premium, COBOL Server, and Database Connectors)
    1. User License Option (COBOL Server only).

      User License for Authorized Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on an unlimited number of servers or Containers for use by up to the total number of named individuals for whom Licensee has paid the applicable license fee. The Licensed Software may not be used or accessed by (i) individuals who are not named individuals; or (ii) any other software or hardware device that does not require a named individual to use or access it. A named individual means an individual identified by Licensee by name who is authorized to use any device or other software program that may access the Licensed Software, either directly or indirectly through any other software program, regardless of how such access occurs or if such individual uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, Batch Processing. Licensor reserves the right at any time to require Licensee to provide a list of the named individual(s). Licensee may change a named individual provided that the change is made either permanently away from the named individual or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named individual is absent, but in no event more than once every 30 days.

    2. Server License Options. There are two options for server-based licenses. Please note that server-based licenses may only be installed on one machine or server or one or more Containers on such single machine or server. Additional licenses are therefore required to be purchased by Licensee for use of the Licensed Software on more than one machine for any purpose, including disaster recovery, load-balancing, clustering, fail-over, training, or testing. Licensed Software may be licensed solely for evaluation, disaster recovery, fail-over, training, or testing purposes and in such case will be subject to the applicable License Option terms and conditions set forth in this Annex 1.

      (i) Server License for Concurrent Users (COBOL Server and Database Connectors only). Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server, or one or more Containers on such single machine or server, for use by the maximum number of Concurrent Users for whom Licensee has paid the applicable license fee. Concurrent Users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, Batch Processing. Licensee may only use the Licensed Software on or access the Licensed Software from one server at any one time. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee's customers to access and use the Licensed Software via the internet and/or Licensee's terminals in connection with Licensee's internal business purposes (for example to access internet banking from Licensee) but not for the public's and/or Licensee's customers' own internal use.

      (ii) Server License for CPUs. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server ("Host Server"), or one or more Containers on the Host Server, and have the Licensed Software executed by up to the total number of CPUs, Cores, Integrated Facility for Linux processors ("IFLs"), Blades or other processing devices specified for the license in the applicable Product Order ("License Specification"). If the number of Cores is not specified for a CPU in the event a CPU is specified in the License Specification, such CPU shall be considered to be single-Core. A Server License for CPUs license covering all CPUs, Cores, IFLs, Blades and other processing devices that are contained in and/or can be accessed by the Host Server ("Total Processors") is required with all applicable license fees paid, even if one or more of such CPUs, Cores, IFLs, Blades or other processing devices are not accessing or running the Licensed Software. For example, if 32 Cores are the Total Processors on the Host Server, but only 16 Cores are utilized to execute the Licensed Software, a 32-Core Server License for CPUs license is required notwithstanding the fact that 16 of the 32 Cores may not actually be accessing the Licensed Software. Each Core on a multi-core CPU requires a Server License for CPUs license covering each such Core. For example a Host Server with Total Processors consisting of a single quad-core CPU will require a 4-Core Server License for CPUs license and payment of the license fees applicable to all 4 Cores.

      The Licensed Software is for use by an unlimited number of Licensee's internal users, other software devices and hardware devices. A Server License for CPUs is the only license authorized for use or access by Licensee for any Batch Processing. Licensor reserves the right at any time to require Licensee to provide a specification of the Host Server. Licensee may change the designated Host Server provided that the new Host Server's specifications are authorized under the applicable Server License for CPUs license, including, but not limited to, the Total Processors in, and thus the Server License for CPUs licenses required for, the new Host Server do not exceed the License Specification(s) for the Server License for CPUs license(s) used for the old Host Server plus any new Server License for CPUs license(s) purchased by Licensee for use on the new Host Server. Licensee is required to purchase a license for the Total Processors on each Host Server that accesses or uses the Licensed Software either directly or indirectly through any other software program, regardless of how such access occurs, or if the Host Server, CPU or operator uses any hardware or software that reduces the apparent number of CPU, Cores, IFLs, Blades or other processing devices that are using the Licensed Software, such as by using a terminal service. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee's customers to access and use the Licensed Software via the internet and/or Licensee's terminals in connection with Licensee's internal business purposes (for example to access internet banking from Licensee) but not for the public's and/or Licensee's customers' own internal use.

    3. Test License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal testing purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, commercial, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. If Licensee uses the Test Licenses for any purpose other than for Licensee's internal testing purposes, the Test License shall terminate automatically and without notice. Upon such termination, Licensee may convert the terminated Test License to a standard license type listed above by paying the applicable conversion fee. In relation to Licensed Software provided pursuant to this Test License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement. For the avoidance of doubt, a "test" license as described above is not a license to use Licensor's software quality or "testing" products, however such products may be available under this Test License Option.
    4. Disaster Recovery License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a Cold Disaster Recovery System subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. A Cold Disaster Recovery System is a computer system that is used only (i) if a disaster arises and the original production, test, or development system is unavailable, (ii) for the purposes of disaster recovery testing and/or (iii) for system diagnostics or maintenance of the Cold Disaster Recovery System itself. Licensed Software provided under this option cannot be used (a) concurrently with any Deployment License for the Licensed Software except while the original production, test, or development system is being recovered; (b) in production, test, or development environments except in a disaster recovery situation: or (c) for load-balancing, failover, testing (other than disaster recovery testing), clustering, or training purposes. Additional copies for use in production, test, and/or development environments, or for load-balancing, failover, clustering, or training purposes, or for installation in any computer system that is in use must be purchased separately. Cold Disaster Recovery Licenses shall terminate automatically without notice if the Licensed Software provided under this License Option is installed on anything other than a Cold Disaster Recovery System, if Licensee ceases to use the Licensed Software for disaster recovery purposes, or if Licensee is otherwise in violation of the restrictions set forth in this section.
    5. Failover License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a single standby failover server in standby, non-production mode subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. Licensee may not use the Licensed Software for production, testing (other than failover testing), development, or training except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional. Licensee may not use the Licensed Software for load-balancing or clustering, for which a separate license is required to be purchased by Licensee.
    6. Training License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal training purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, testing, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it.
  3. Evaluation License Option Licensed Software provided under this License Option gives Licensee a term license to use the Licensed Software within Licensee during the evaluation term specified in writing by Licensor, solely for evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. Licensee may not reproduce or distribute the Licensed Software. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. At any time during the evaluation term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the evaluation license with a license to use the Licensed Software pursuant to one of the other applicable options listed in Annex 1. In the absence of such notification by Licensee, the evaluation license shall automatically terminate at the end of the evaluation term and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of such deletion and destruction being completed. Licensor may, in its sole discretion, grant Licensee an extension to the evaluation term subject to receiving a written request and reasons for such request from Licensee prior to expiration of the evaluation term. Licensor will specify any such agreed extension in writing to Licensee. Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided pursuant to this Evaluation License Option unless otherwise agreed in writing. In the absence of any contrary period specified in writing by Licensor, the evaluation term shall be deemed to be thirty (30) days. In relation to Licensed Software provided pursuant to this Evaluation License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.

ANNEX 2, SPECIFIC SOFTWARE TERMS

Additional Restrictions. Licensee agrees not to:

  1. Copy and/or distribute the Licensed Software, in whole or in part, to third parties, or use the Licensed Software for the benefit of any third party, or permit use or access by any third party to all or part of the Licensed Software without first paying Licensor any applicable additional fees required by Licensor and entering into a separate distribution license agreement with Licensor. For the avoidance of doubt, third party(ies) include without limitation contractors, outsourcers, Licensee's customers and the public.
  2. Transfer, ship or use the Licensed Software outside the continent in which it was originally licensed to Licensee without first paying Licensor any applicable additional fees required by Licensor. For purposes of the foregoing, "continent" shall mean North America, South America, Europe, Africa, Asia, Australia, or Antarctica.
  3. Install, access or use the Licensed Software on a Platform other than the Platform for which the Licensed Software was originally licensed to Licensee. Additional licenses for use of the Licensed Software on a Platform other than the one set forth in the applicable Product Order may be available upon payment of an additional license fee.
  4. Assign, sell, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, or authorize or appoint any third party to do so, or otherwise allow a third party to directly or indirectly use or access the Licensed Software, without Licensee first paying Licensor the applicable additional fees required by Licensor.
  5. Install, use, or access the Licensed Software on, in, or from a Hard Partition, Soft Partition, or Virtual Machine, except in accordance with the Virtualization Rights clause below, or where Licensee is otherwise expressly authorized in each instance by Licensor in the applicable Product Order or otherwise in writing separate from this License Agreement (the "Authorization") which in each event will be subject to Licensee's payment to Licensor of additional applicable fees required by Licensor and Licensee's written confirmation to Licensor of Licensee's planned installation environment signed by a director or officer of Licensee (accompanied by all information as Licensor reasonably requires to verify). Except for licenses subject to the Virtualization Rights clause below, w here authorized in accordance with the foregoing and to the extent applicable to the subject license: (i) such Hard Partition, Soft Partition, or Virtual Machine, may only be tied to one physical machine and shall be considered the entire machine for licensing purposes ; and (ii) Licensee shall provide to Licensor, at such times as Licensor may reasonably request, confirmation that Licensee's computer systems comply with the applicable Authorization and the requirements of the License Agreement. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement, including without limitation any relevant hypervisor logs. The foregoing is in addition to Licensor's rights under the Audits section of the License Agreement .
  6. Utilize any software application and/or program created, in whole or in part, with any Development License without first purchasing a valid and properly granted Deployment License.

Enterprise Developer, Visual COBOL. Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.

This Licensed Software may include or generate limited licenses for Enterprise Server, COBOL Server, or other application deployment product. If such licenses are included or generated, these limited licenses are provided solely for use by the licensed user(s) of the Licensed Software in order to unit test an application developed with the Licensed Software on the same machine or server used to develop the application and may not be used for system testing, production or deployment, and with respect to Visual COBOL may only be used if the Licensed Software is current on support and maintenance. Any use of this limited license outside of the development and unit testing of such applications is not permitted.

Enterprise Developer may come with Licensor's Rumba software, and in such event, Licensee may only use such copy of Rumba with Enterprise Developer on the same machine subject to the terms and conditions applicable to such Enterprise Developer license.

Enterprise Developer Connect. Licensee may install certain Enterprise Developer components and models in another Eclipse or IBM Developer for z environment in accordance with the applicable Documentation solely for use with a valid license for Enterprise Developer Connect.

Enterprise Server, Enterprise Server for .NET, Enterprise Test Server, Enterprise Test Server Premium, COBOL Server. With any valid and properly granted license to this Licensed Software, Licensee may reproduce and distribute internally, in whole or in part, subject to the applicable license option as described in Annex 1 and the applicable Product Order, any software application program created by Licensee using the corresponding development product for the Licensed Software (if separately licensed to Licensee by Micro Focus) ("Licensee Application Software"). In such event Licensee shall (a) include Licensor's copyright notice for the Licensed Software on any product label and as a part of any sign-on message for such Licensee Application Software product; and (b) indemnify, hold harmless and defend Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys' fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software.

Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensee Application Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any of the Licensee Application Software's functionality when linked into another software application program. Access and/or use of data, results and/or output obtained and/or generated, either directly or indirectly, and in any format whatsoever, through the use of any Licensed Software (such as when a user accesses an application that calls or uses output from another application running the Licensed Software, whether or not on the same machine or server) are deemed to be access and/or use of such Licensed Software. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

Enterprise Test Server, Enterprise Test Server Premium. This Licensed Software may be used only for Licensee's internal testing purposes. At no time may Licensee use the Licensed Software for any production purpose.

Enterprise Developer Models. This Licensed Software may only be used with a valid license for Enterprise Developer and shall be governed by the same terms and conditions as such license. No support or maintenance is provided or available for this Licensed Software.

Virtualization Rights. Notwithstanding any language in this License Agreement to the contrary, with respect to a license for Enterprise Server, Enterprise Test Server, and COBOL Server, in the event the applicable Product Order specifies that such license includes "Virtualization Rights" in the line item for such license, then for as long as such license is current on support and maintenance with Licensor, Licensee may install, use, or access such license on, in, or from a single instance of the Licensed Software, or one or more Containers, within a single Virtual Machine that is not necessarily tied to just one physical machine. This Virtual Machine may not access more than the number of licensed physical Cores purchased (or virtual Cores provided that a virtual Core is equivalent to a physical Core). Such license may be installed on Licensee's owned and controlled premises or hosted off-premise by an external cloud provider. Licensee may make one (1) copy of the Virtual Machine in which the Licensed Software is installed and instantiate such Virtual Machine in the event and for as long as the primary installation is unavailable. Licensee shall provide to Licensor, at such times as Licensor may reasonably request, confirmation that the applicable computer systems comply with the foregoing and the requirements of the License Agreement. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement, including without limitation any relevant hypervisor logs. The foregoing is in addition to Licensor's rights under the Audits section of the License Agreement. Upon any lapse in support and maintenance for the aforementioned license, such license will not enjoy the additional rights described in this clause.

Subscription and/or On-Demand License. Notwithstanding any language in this License Agreement to the contrary, with respect to a license for Visual COBOL, Enterprise Developer, Enterprise Server, Enterprise Test Server, and COBOL Server, in the event that the applicable Product Order specifies that such license is a Subscription and/or On-Demand license, such license will be subject to a separate written agreement signed by Licensor and Licensee setting forth additional terms and conditions specific to Subscription and/or On-Demand licenses.

All-or-None Support and Maintenance. Where Licensee purchases support and/or maintenance for the Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software including all related development and deployment product licenses.

Updates and Upgrades. Upon delivery to Licensee of any Update and/or Upgrade, the license granted to such prior version and/or release being updated or upgraded shall terminate after a ninety (90) day transition period from such delivery and only the license to such Update or Upgrade shall continue unless (i) Licensee has paid to Licensor the applicable additional fees required by Licensor to use both versions, or (ii) in the case of an Update that is provided to Licensee at no additional charge from Licensor pursuant to support and/or maintenance for which Licensee has separately contracted, Licensee provides written notice to Licensor during the aforementioned transition period of its election not to use the Update but instead remain with the prior version and Licensee's de-installation and destruction of such Update.

Editions. Any reference to a Licensed Software product in this License Agreement shall also apply to such products various editions or variants except where otherwise specifically stated. For example, the terms and conditions applicable to Enterprise Developer also apply to Enterprise Developer for Eclipse, Enterprise Developer for Visual Studio, Enterprise Developer Connect, and Enterprise Developer for z, etc., and the terms and conditions applicable to Visual COBOL also apply to Visual COBOL for Visual Studio, Visual COBOL for Eclipse, Visual COBOL Development Hub, etc.

Bundles/Suites. If the Licensed Software is licensed as part of a bundle or suite of multiple products, and the applicable Product Order specifies the License Option and license count for the bundle or suite (but not the individual product components of the bundle or suite), then each product in the suite or bundle shall share such license type and count. Individual products in the bundle or suite cannot be used by multiple users if only one user license is purchased (for user-based licenses) and cannot be installed on multiple devices or servers if only one device or server license is purchased (for device or server-based licenses). For example, if Visual COBOL for XYZ is a bundle that includes Visual COBOL for XY and Visual COBOL for Z, and the applicable Product Order specifies that a single named user license for Visual COBOL for XYZ is purchased, then Visual COBOL for XY and Visual COBOL for Z would be limited to the same single machine for use by the same single named user. If COBOL Server for XYZ is a bundle that includes COBOL Server for XY and COBOL Server for Z, and the applicable Product Order specifies that a 4-Core license for COBOL Server for XYZ is purchased, then COBOL Server for XY and COBOL Server for Z would be limited to the same 4-Core machine.

Academic Editions/Users. Where Licensed Software is licensed under Licensor's Academic Program, in addition to the above terms and conditions:

  • (i) Licensee shall not use the Licensed Software for any purpose other than for non-commercial education or academic research activities.
  • (ii) Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.
  • (iii) License management: If Licensee is the academic institution using the Licensed Software for teaching purposes, Licensee will manage all student licenses through a license server provided by Licensor in accordance with guidelines provided by Licensor. Licensee agrees to provide reports describing the number of licenses Licensee has issued in each period upon Licensor's request.

Personal Edition Products.

  • (i) Licensee shall not use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes.
  • (ii) Licensee shall not: (a) use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or (b) deploy or transfer such application on or to any other machine or third party; or (b) with respect to Enterprise Developer, use the Licensed Software for any purpose other than to input, edit and syntax check code for personal educational use.
  • (iii) Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.

Batch-Only Licenses. Where any Licensed Software is designated as "Batch-Only" using such description or similar terminology, such Licensed Software may only be used to perform batch processing.

PRE-EXISTING LICENSES. FROM COMMENCEMENT OF THIS LICENSE AGREEMENT, IF THE LICENSED SOFTWARE SUBJECT TO THIS LICENSE AGREEMENT IS THE MOST CURRENT VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE, THE "LICENSED SOFTWARE" SHALL ALSO INCLUDE, AND THIS LICENSE AGREEMENT SHALL APPLY TO, ANY PRE-EXISTING AND FUTURE LICENSES FOR ANY EARLIER VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE AND REPLACE ANY PRIOR END USER LICENSE AGREEMENTS APPLICABLE THERETO ("PRIOR EULA(S)"). NOTWITHSTANDING THE FOREGOING, IF THE EARLIER VERSION INCLUDES DIFFERENT COMPONENTS, ANY TERMS SPECIFICALLY APPLICABLE TO THOSE COMPONENTS IN THE APPLICABLE PRIOR EULA SHALL CONTINUE TO APPLY TO SUCH COMPONENTS. "ANY VERSION OF THE LICENSED SOFTWARE" SHALL ALSO INCLUDE THE RELATED DEVELOPMENT AND DEPLOYMENT/RUNTIME PRODUCTS OF SUCH LICENSED SOFTWARE.

ENDS

Parent topic: Product Information


Known Issues and Restrictions

The restrictions covered here are those that are not covered elsewhere in the documentation, or that are of a temporary nature and may be removed in a later product. Permanent limits are generally covered in the main help.

Where an entry arose from a problem report, the report's number is given, to enable Product Support to help you more quickly if you call. These numbers are called Reported Product Issue (RPI) numbers.

  • Application Server JCA Support for Enterprise Server
  • Audit Manager
  • Calling COBOL Programs from C
  • COBOL Programming
  • Compatibility
  • Issues with the Installation on Windows
  • UNIX and Linux Installer Issues
  • Data Access
  • Debugging, Problem Determination and Diagnostic Tools
  • Docker Known Issues and Restrictions
  • Documentation
  • JVM COBOL Applications - Known Issues and Restrictions
  • Licensing
  • Issues with Resource Adapters
Parent topic: Product Information
Related information
Updates and Product Support


Application Server JCA Support for Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Starting with Visual COBOL version 2.2 Update 2, HotFix 9, Micro Focus ECI programs that use mfccl.jar raise an error exception, EXCIRespException, if exciResp1 and exciResp2 are not both equal to zero. To ensure your ECI program captures all errors, you must catch this exception in your code. Please add the following code snippet, which enables your program to compile and execute properly:
    try {
                …
        } catch(ExciRespException e) {
               String rcMsg = e.getRcMsg();
        }

    If an error occurs, rcMsg captures the appropriate error message.

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


Audit Manager

The Security Audit Manager is now deprecated.

The Audit Manager does not work on Solaris 11.4 and later.

Parent topic: Known Issues and Restrictions


Calling COBOL Programs from C

Linking

  • When using COBOL and C object code together, Micro Focus recommends you build and keep the COBOL and C executables separate, and use import libraries and the Micro Focus C functions for calling COBOL (see "C functions for calling COBOL" in the product help) to resolve calls between them.

Calling a COBOL entry point directly

Note: The following instructions are required on little-endian PowerLinux platforms, but should also be considered good programming practice on other platforms. References to COBOL entry points in this topic include both the PROCEDURE DIVISION header and ENTRY statements.

When calling a COBOL entry point directly from C (as opposed to using cobcall() or cobfunc()), and passing fewer parameters than are specified on the entry point (that is, fewer actual parameters than formal parameters) then the COBOL entry point called from C should either:

  • Not be declared in the C program with a function prototype; or
  • Be declared in the C program with a function prototype with a variadic parameter list (see below).

Example

Take a COBOL program with the following entry points defined:

 entry "bob" using arg1 arg2 arg3 arg4 arg5 arg6
 arg7 arg8 arg9.

and a C program that contains code such as:

 i = bob(&x1, &x2);

then the correct way to declare this COBOL entry point in the C program is as follows:

 int bob(void *arg1, void *arg2,...);
Parent topic: Known Issues and Restrictions
Parent topic: Mixed Language Programming


COBOL Programming

  • Boolean Data Items
  • CBL2XML Utility
  • Enhanced ACCEPT/DISPLAY Syntax (Adis)
  • Filenames
  • IDXFORMAT 8 and 12 File Size Limits
  • Unsupported Features
  • XML Extensions
Parent topic: Known Issues and Restrictions


Boolean Data Items

  • Argument-2 of the BOOLEAN-OF-INTEGER statement must be a numeric constant when the function is used in an expression with B-NOT, or as part of a boolean expression which is used as an argument in INTEGER-OF-BOOLEAN.
  • You can only query PIC 1(n) USAGE BIT items which are at the 01 level.
  • You cannot query boolean data items defined as PIC1(n) USAGE BIT that are subscripted. If you need to query them, move the value to a PIC 1 (n) USAGE DISPLAY data item.
  • The JUSTIFIED clause cannot be specified for boolean data items.
  • You cannot use reference modification on boolean data items.
  • If you use the ODOSLIDE directive, you cannot have boolean data items following a variable-length table in the same record; neither can you have data items following a variable-length table containing boolean data items.
  • You cannot use the BX literal format.
  • You cannot have boolean data items in text-data used in EXEC(UTE) CICS or EXEC(UTE) SQL statements.
  • You cannot use include boolean data items in conditional compilation statements.
  • You cannot use boolean data items in the Screen Section.
  • The Report Writer feature does not support boolean data items.
  • You cannot use variable length items with GROUP-USAGE BIT specified in boolean expressions.
  • You cannot set CHARSET"EBCDIC" for programs using boolean data items.
  • You cannot move data between national items and boolean items.
  • Boolean data items can contain up to 64 digit positions; groups of GROUP-USAGE BIT are also limited to 64 digit positions.
  • If you use the syntax VALUE IS {{literal}... FROM ({subscript-1}...) [TO ({subscript-2}...)]}, subscript-1 and subscript-2 cannot be boolean data items.
  • Using the SYNCHRONIZED clause has no effect on the alignment of any type of bit data item.
Parent topic: COBOL Programming


CBL2XML Utility

When converting from COBOL to COBOL with XML syntax using the cbl2xml command, level 88 conditions cause erroneous results.

Parent topic: COBOL Programming


Enhanced ACCEPT/DISPLAY Syntax (Adis)

Some DBCS fields are displayed with different content depending on whether or not the cursor is in the field.

This problem only occurs if the PROMPT option is on, and either of the two bytes that comprise a non-space DBCS character in the field matches (for value and position) either of the two bytes that comprise a DBCS space.

Parent topic: COBOL Programming


Filenames

The names of source, project, and solution files cannot include characters outside the 7-bit ASCII character set.

Parent topic: COBOL Programming


IDXFORMAT 8 and 12 File Size Limits

File size limits for IDXFORMAT 8 and IDXFORMAT 12 files are not enforced. Allowing your file to grow over the documented limit could result in an error related to the relevant restriction. If you think your file may exceed the documented limits, use FILEMAXSIZE=8 where applicable.

Parent topic: COBOL Programming


Unsupported Features

Run-time Features

The run-time features of your COBOL development system not supported include:

  • HyHelp

Note that some of these features might compile correctly, but won't run.

Parent topic: COBOL Programming


XML Extensions

"50 Error - missing XML parser (MSXML6)" is displayed for XML Extensions
The XML parser could not be found. This error occurs only on Windows and indicates the MSXML 6.0 parser is not installed in the Windows system. The MSXML 6.0 parser is normally installed on most Windows systems, but could not be found on this system. MSXML 6.0 can be obtained by downloading it from Microsoft's web site.
Parent topic: COBOL Programming


Compatibility

  • Coexisting with earlier Micro Focus products
Parent topic: Known Issues and Restrictions


Coexisting with earlier Micro Focus products

Run-time system error due to COBCONFIG
A run-time system error occurs if the COBCONFIG environment variable is set when you run Visual COBOL applications or when you use Visual COBOL to edit or create projects and the configuration file it refers to contains entries that are not valid for Visual COBOL.

For example, this might happen if you have Studio Enterprise Edition installed and COBCONFIG is set for it.

To work around this issue, ensure that Visual COBOL is not running and then modify the configuration file by doing one of the following:

  • If the invalid tunable is not needed by another application, remove it from the run-time configuration file.
  • Add the following as the first line in the configuration file:
    set cobconfig_error_report=false
  • Unset COBCONFIG or set it to another configuration file that does not contain the invalid tunable for the particular session you are running in.
Performance Monitoring Issue
Having an Enterprise Developer product and Studio Enterprise Edition 6.0 or Server Enterprise Edition 6.0 installed on the same machine, and trying to uninstall one of them, breaks performance monitoring and it is not possible to see the Enterprise Server performance counters. To resolve this problem, run the installer of the product you wish to retain on your machine, and repair the installation.
Parent topic: Compatibility


Issues with the Installation

Issues with the Installation on Windows

  • Installing this product fails if Micro Focus License Manager version 10000.2.02070 (April 2015) or older is already installed on your machine. The setup files does not upgrade the License Manager automatically to the latest version. You must uninstall the existing version before you start the installation.
Parent topic: Known Issues and Restrictions


Data Access

  • COBSQL
  • DB2
  • File Handling
  • OpenESQL
Parent topic: Known Issues and Restrictions


COBSQL

  • The COBSQL preprocessor is supported only for standard procedural COBOL programs. You cannot use COBSQL with Object Oriented COBOL syntax (OO programs) or with nested programs.
  • If an Embedded SQL statement has a comment in columns 73 - 80 and is not terminated by a period, the Oracle precompiler (Pro*Cobol) considers the next COBOL line as part of the Embedded SQL statement and comments it out.

    To prevent this making COBSQL hang, use the COBSQL directive SQLDEBUG. Then, when COBSQL encounters such a line, it displays:

    CSQL-W-040: Pro*Cobol commented out the following line

    The program logic is altered because Pro*Cobol has commented out a COBOL line. We recommend, therefore, that you do not execute programs that produce this message. You should either remove the comment text or terminate the Embedded SQL statement with a period.

  • If an EXEC WHENEVER ... END-EXEC or an EXEC DECLARE ... END-EXEC statement is the last statement in a paragraph or section, you may get a compilation error on the name of the following paragraph. If this happens, place an extra COBOL sentence (terminated by a period) after the WHENEVER or DECLARE statement. For example:
    CONTINUE.
Parent topic: Data Access


DB2

  • Starting with Visual COBOL version 3.0, the DB2 ECM preprocessor no longer converts underscores that appear in EXEC SQL WHATEVER statements to dashes. Underscores encountered in EXEC SQL WHATEVER statements could cause compiler errors.
  • Due to third-party restrictions, we do not support the debugging of DB2 LUW COBOL stored procedures.
Parent topic: Data Access


File Handling - Known Issues

File Handling

  • The following restrictions apply to MFDBFH:
    • 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 alpha-numeric, binary, and numeric.
    • Some database restrictions may apply – for instance, PostgreSQL does not support EBCDIC collating sequence.
  • Using Btrieve, a START operation cannot be performed with a part-key. The whole key must be used.
  • In Visual COBOL, if you attempt to open a data file located on a Novell Netware drive you may receive a file status 9/181 message, which indicates that you have used an invalid parameter.

    The defaults for new indexed files are IDXFORMAT(8) and FILEMAXSIZE = 8, which enables support for 64-bit file handling. Novell Netware drives only behave like 32-bit drives and can only handle files up to 4GB in size.

    To access files from a Novell Netware drive in Visual COBOL, you need to override these file handling formats by setting the following options in the file handler configuration file (EXTFH.CFG):

    [XFH-DEFAULT]
IDXFORMAT=4
FILEMAXSIZE=4
  • If you are accessing Vision files through the Vision file handler (as opposed to the default Micro Focus File Handler) and you are upgrading from Visual COBOL version 2.0 to version 2.1, you must first uninstall version 2.0, otherwise the Vision file handler may not function correctly.
  • An improvement to allow greater scope in the naming of external files (files using the EXTERNAL keyword in the file description) has resulted in a possible issue if the applications sharing a file were compiled using different versions of Visual COBOL: if any applications compiled prior to Visual COBOL 2.2 share files with applications compiled with this version, you must recompile your older applications.
Parent topic: Data Access


OpenESQL

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.

On UNIX/Linux, the symbol oesqleb2 is defined in the shared objects coboesqlebc.so (32-bit) and coboesqlebc64.so (64-bit). To resolve the link error, compile using the -d flag as follows:

cob -x program.cbl -d {oesqleb2@coboesqlebc.so | oesqleb2@coboesqlebc64.so}

Where program.cbl is the name of your COBOL program 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: Data Access
Related reference
CALL
BINARY SQL Type


Debugging, Problem Determination and Diagnostic Tools

  • Core Dump Debugging
  • Reverse Debug and Live Recording
  • Test Coverage
Parent topic: Known Issues and Restrictions


Core Dump Debugging

  • core_on_error=3 does not work correctly on AIX 7.2.
Parent topic: Debugging, Problem Determination and Diagnostic Tools


Reverse Debug and Live Recording

Reverse Debug and Live Recording are supported on the following platforms:

  • Red Hat Linux (x86 and x64)
  • SUSE Linux Enterprise Server (SLES) 12 SP2 (x64 only)

In addition, the following issues and restrictions apply:

Compiling and code generation restrictions
  • To use the Live Recording functionality to create or view a live recording, compile the application for debugging.
  • Reverse Debug and Live Recording are supported for generated code only, meaning .gnt, .so, and executable code but not .int code. You can reverse debug the .gnt code in a mixed application that contains both .gnt and .int code; however, reverse debugging stops when it reaches the .int code.
Additional considerations
  • When reverse stepping, you are essentially rewinding a recording just as you might rewind a video while it is playing. You cannot change what was recorded. Therefore:
    • No I/O occurs, meaning that the screen is not updated, accept statements are not re-accepted, and files do not change.
    • You cannot move the execution point.
    • You cannot change the values of data items.
  • Applications can run slower when reverse debugging, especially applications that call multiple programs.
  • You might experience a significant time delay after launching the debug of a live recording and before the debug session begins.
  • Live Recorder is not available while debugging.
Parent topic: Debugging, Problem Determination and Diagnostic Tools


Test Coverage

Programs in .exe or .dll format that have been compiled with the TESTCOVER directive set, and have been run under the TESTCOVER environment, might find that at the reporting stage the .idy or .cbl/.cpy files cannot be found when creating reports from the results file(s). To work around this, run the tcreport utility from the directory containing the .idy/.cbl/.cpy files. [530281]

Parent topic: Debugging, Problem Determination and Diagnostic Tools


Docker Known Issues and Restrictions

You should be aware of the following limitations when using Visual COBOL with Docker:

Debugging

  • You must be using Visual Studio 2017 or later to be able to debug a managed COBOL application running in a container.

General

  • Java is supported from version 8 update 162 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.

Operating Systems

Visual COBOL is supported for use with Docker on the following operating systems:

  • Red Hat Enterprise Linux 7.4 or later
  • SUSE Linux Enterprise Server 12 SP3 or later

Use with Micro Focus Products

  • There is no support for building or managing Docker images from the Visual COBOL IDE.
Parent topic: Known Issues and Restrictions
Related information
Introduction to Docker


Documentation

Feedback link

  • Each help topic in the documentation for 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


JVM COBOL Applications - Known Issues and Restrictions

  • Application Servers - Known Issues
  • COBOL JVM Projects - Known Issues
  • Java Virtual Machine - Known Issues
  • OpenESQL
Parent topic: Known Issues and Restrictions


Application Servers - Known Issues

You can edit, debug, and compile COBOL applications to run on a variety of application servers. The following are not supported:

  • COBOL file handling (including ACUCOBOL-GT file handling and Fileshare)
  • Threading syntax, such as START and WAIT, and the CBL_THREAD library routines
  • The PC_PRINTER library routines
  • CALLing native COBOL library routines or OS-native APIs
  • The STATIC keyword for class members
  • Enhanced ACCEPT/DISPLAY statements
  • Deploying the SQL runtime in a shared model while deploying the COBOL runtime in a per-bean model when using a class that implements the EJB specification to run your JVM COBOL code.
Parent topic: JVM COBOL Applications - Known Issues and Restrictions


COBOL JVM Projects - Known Issues

Adding Projects to the Java Build Path

If a project you add to the Java build path of a COBOL JVM project has its default output folder set to its root and not a sub-folder, you will get errors when building the COBOL JVM project.

To avoid this problem, add the project output folder as a sub-folder.

Compiling large programs

When compiling a large program within a JVM COBOL project, the following compiler error message might occur:

COBCH0015S Procedure division too large

JVM COBOL compiles a COBOL program to Java byte code. The byte code is organized into methods, which have a maximum size of 65,535 (216 - 1) bytes. This error occurs because the COBOL compiler is unable to keep methods below the maximum size limit due to the size and complexity of the program. The program must be changed to avoid the methods reaching the size limit.

Reaching the size limit can result from overlapping perform ranges. Compile your program with the ILSHOWPERFORMOVERLAP compiler directive and examine the error messages to see why perform ranges overlap. Resolving the overlap problems can resolve this issue.

Note: If the program is compiled with "PERFORM-TYPE(OSVS) STICKY-PERFORM" directives, then the only solution might be to split the program into smaller sub-programs.

Editing Remote JRE Settings

If you are developing a remote COBOL JVM project, problems can occur if you use a remote JRE and change its settings in the project's JVM Build Path dialog box.

Parent topic: JVM COBOL Applications - Known Issues and Restrictions


Java Virtual Machine - Known Issues

You can edit, debug, and compile COBOL applications to JVM byte code (.class files) so that they can be run on a Java Virtual Machine. The following limitations and restrictions apply:

  • Currently, JVM COBOL is only supported on System z running Linux 390 when the JIT compiler is restricted to use only the cold level optimisations.

    This can be done by specifying 'cobjrun -Xjit:optLevel=cold ProgramName' (or 'java -Xjit:optLevel=cold ProgramName') to launch the program. For more information, see the topic Selectively disabling the JIT in the Java SDK documentation available on IBM's Web site.

  • In JVM_LOAD_NATIVE, the myLibrary parameter must be passed as a literal; it cannot be declared in a COBOL storage section.
  • You cannot use the COBCONFIG or COBCONFIG_ environment variables. You must use COBCONFIGJVM instead.
  • The format of a JVM tunables file must be that of a standard Java properties file and not the format used by the native runtime.
  • XML PARSE is not supported in JVM COBOL code. XML GENERATE is supported.
  • You cannot use generics in your JVM COBOL code.
  • COBOL class package and the directory structure is enforced. You might get errors finding source code.

    For example:

    If a COBOLClass1.cbl is within a package com.microfocus.core then it should be in the Project/src/com/microfocus/core/COBOLClass1.cbl directory. In the case the com.microfocus.core package is mapped to com/microfocus/core directory.

  • You cannot pass a JVM procedure-pointer to a native COBOL application.
  • There is a known issue with IBM’s JVM support for the Java™ Attach API which causes the API to leak semaphores under certain conditions. If you are running IBM’s JVM on AIX and Redhat or SUSE Linux on z390, this can cause your machine to run out of semaphore space resulting in the machine running slower or causing intermittent failures.

    To determine whether you are experiencing this issue, type the following at the command line to check the number of semaphores that start with the 0xa1 prefix:

    "ipcs -s -r | grep 0xa1 | wc –l"

    If this number is very high and keeps growing you need to follow the cleanup procedure described in the "IBM Developer Kit and Runtime Environment Diagnostics Guide", "Chapter 19. Attach API problem determination", ftp://public.dhe.ibm.com/software/dw/jdk/diagnosis/diag50.pdf

    You can disable the Java™ Attach APIs to avoid the issue. Note, however, that when Attach API is disabled, it will not be possible for other Java application to attach to your application and features such as jtop, jstat, jconsole, JMX agents, JVMTI agents will cease to function.

    The Attach API is enabled by default for Java 6 SR6 and later. To disable the feature you need to set the IBM JVM property com.ibm.tools.attach.enable to "no".

    You can use this property with any Java trigger, or with IBM’s environment variable IBM_JAVA_OPTIONS which allows you to pass extra arguments to the JVM without changing any command lines.

    You can set the variable as follows:

    export IBM_JAVA_OPTIONS=-Dcom.ibm.tools.attach.enable=no
  • A combination of using continuation lines and a source-format of variable has been known to produce screen corruption and sometimes crash the JVM. A workaround is to compile your application with the source-format"fixed" directive, or if that is not possible, set and then unset the directive immediately before and after the code containing the continuation lines.
  • You can run some COBOL classes as COBOL JVM applications even when the COBOL class does not explicitly define a main method that satisfies all criteria for JVM, which are that the main method:
    • Is named main
    • Is marked public static
    • Uses the string occurs any arguments

    However, the application must not contain a using clause in at least one static method or in the class itself.

    When all of these criteria are met, the Run as COBOL JVM Application option is available.

Parent topic: JVM COBOL Applications - Known Issues and Restrictions


OpenESQL

JDBC

  • You cannot directly enable integrated authentication for Microsoft SQL Server in Visual COBOL. If you use integrated authentication with Microsoft SQL Server, you must add the .jar file for your JDBC driver directly to the Java Build Path or CLASSPATH of your Eclipse project, and then set its native library location.
  • The following scenario can cause the COBOL compiler to fail to update output host variables when the cursor for a stored procedure call is closed. This can happen when stored procedures meet all three of the following criteria:
    • Are called using the OPEN statement
    • Return a return value, output parameters, or both
    • Return a result set

    The failure occurs because the COBOL compiler, when possible, compiles 01-level fields and their subordinate 01-level FILLER fields as JVM types.

    To ensure successful compilation, use traditional COBOL data types, such as PIC X(n), COMP-3, etc., for host variables rather than object types, such as string, binary-long, BigDecimal, etc., and do one of the following:

    • Compile using the NOILNATIVE COBOL compiler directive
    • Declare host variables that receive return values or output parameters at level 02 or higher, with a record name other than FILLER

    This scenario does not apply to stored procedures called using the CALL statement.

OpenESQL JVM Managed Runtime

OpenESQL applications are optimized for performance by default, with OpenESQL now implicitly setting the BEHAVIOR compiler directive to OPTIMIZED; with previous products, the BEHAVIOR compiler directive was implicitly set to UNOPTIMIZED. This change can impact program behavior as follows:

  • Programs that include the SET SCROLLOPTION or SET CONCURRENCY EXEC SQL statements fail to compile. For affected programs, do one of the following:
    • Before compiling, set the BEHAVIOR compiler directive to UNOPTIMIZED. While this is the simplest solution, we do not recommended it due to the possibility of degraded performance.
    • Remove all SET SCROLLOPTION and SET CONCURRENCY statements and, if necessary, modify the DECLARE CURSOR statement to include appropriate parameters to yield the same behavior. For example, to elicit the same behavior as the SET SCROLLOPTION statement, use the following DECLARE CURSOR statement:
      EXEC SQL DECLARE cursorname SCROLL LOCK CURSOR FOR…

      By default, cursors are forward and read only. If this is the desired behavior, you can safely remove the SET statements with no further action required. However, we recommend as a matter of good practice to always include FOR READ ONLY or FOR UPDATE in cursor declarations to ensure that the default behavior is always explicit. We recommended this solution.

  • The OPTIMIZED setting does not make ambiguous cursors updateable. Therefore, applications that expect cursors to be updateable, according to the default ANSI standards for Embedded SQL, are affected. In this case, we recommend that you set the BEHAVIOR compiler directive option to ANSI.
  • The OPTIMIZED setting does not assume scrollable cursors. Therefore, applications that expect cursors to be scrollable are affected. In these cases, we recommend that you modify your DECLARE CURSOR statements to compensate, as specified above.
Important: If you do not want to take advantage of the performance gains provided by this change in implicit behavior, use the OpenESQL Configuration Utility to change the implicit value of the BEHAVIOR compiler directive back to UNOPTIMIZED. For details, see OpenESQL Embedded SQL Cursor Behavior and Performance.
Parent topic: JVM COBOL Applications - Known Issues and Restrictions
Related concepts
OpenESQL Embedded SQL Cursor Behavior and Performance


Licensing

Commuter licenses

If there are a number of entries displayed in the License Administration tool, these might be either for different products or for the same product but for different serial numbers, for example.

When a commute request is made using the license manager, that request is serviced from a pool of licenses that could be provided by any number of Micro Focus product licenses stored on that server. The commute request cannot target a particular RMS license by product name, serial number, or number of cores.

The products to which you apply the commuter licenses will be licensed correctly but the number of licenses left in the License Administration tool might appear to be less than expected. This issue is more likely to occur with multiple entries for the same product.

If you are using a number of different products, Micro Focus recommends that you use a different licensing server for each product in order to help minimize the issue.

Parent topic: Known Issues and Restrictions


Issues with Resource Adapters

  • Trying to deploy the local resource adaptor mfcobol-localtx.rar to WebLogic may fail with a ClassCastException. To work around this issue, you need to deploy mfcobol-xa.rar first, then need to undeploy this file and deploy the local one, mfcobol-localtx.rar. If there are issues deploying using the WebLogic GUI, you can use the command line. If there are issues with this as well, try reducing the length of the command (for example, by moving the file to a location with a shorter path).
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 Product Support
  • Information We Need
  • Contact information
Parent topic: Product Information


Further Information and Product Support

Additional technical information or advice is available from several sources.

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

  • The Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates. Go to https://supportline.microfocus.com/websync/productupdatessearch.aspx
  • The Examples and Utilities section of the Micro Focus SupportLine Web site, including demos and additional product documentation. Go to https://supportline.microfocus.com/examplesandutilities/index.aspx.
  • The Support Resources section of the Micro Focus SupportLine 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 in your browser to go to the Micro Focus home page, then click Support & Services > Support > Support Resources > All Support Resources by Product. In the Browse by Product field, click the product you require, and then click Log into SupportLine.

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, 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 product.
Parent topic: Contacting Micro Focus
Related information
Micro Focus SupportLine
Examples and Utilities
Support Resources
Micro Focus Community
White Papers and Webcasts
Micro Focus YouTube Channel


Information We Need

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

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

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

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

To run mfsupport:

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

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

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

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

Parent topic: Contacting Micro Focus


Contact information

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

Additional technical information or advice is available from several sources.

The product support pages contain considerable additional information, including the Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates.

To connect, enter https://www.microfocus.com in your browser to go to the Micro Focus home page, then click Support & Services > Support > Support Resources > All Support Resources by Product. In the Browse by Product field, click the product you require, then click either Log into SupportLine or Contact Support.

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

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


Using the Command Line Demonstrations

Perform the following steps to use the demonstrations:

  1. Create a new directory for the demonstration program and change to that directory.
  2. Copy all the files from the directory $COBDIR/demo/demo_name containing the demonstration program to the new directory.
  3. Use the make command to compile the sample program and create the executable.
  4. Run the program.
  • Command Line Demonstrations of COBOL for JVM
  • Command Line Demonstrations of Native COBOL
  • Command Line Demonstrations of COBOL used with SQL
  • Command Line Demonstrations of COBOL used with Business Information Server (BIS)
Parent topic: Welcome


Command Line Demonstrations of COBOL for JVM

These demonstration programs are installed in $COBDIR/demo/jvm_cobol by default.

The following demonstrations are supplied:

Arrays (JVM)
Demonstrates the managed COBOL syntax for arrays.
Collections (JVM)
Demonstrates how to use the LIST and DICTIONARY collection types in managed COBOL.
Core (JVM)
This is an introduction in programming in managed COBOL for JVM.
Enums (JVM)
Demonstrates how to use enumeration in COBOL for JVM.
Extension Methods (JVM)
Demonstrates how to extend methods in COBOL for JVM.
Iterators (JVM)
Demonstrates how to use iterators in COBOL for JVM.
Indexers (JVM)
Demonstrates how to use indexers in COBOL for JVM.
SQL (JDBC)
Demonstrates how to use SQL with JDBC.
Local Variables (JVM)
Demonstrates how to declare local variables in COBOL for JVM.
Operator Overloading (JVM)
Demonstrates operator overloading in COBOL for JVM.
Properties (JVM)
Demonstrates how to use properties in COBOL for JVM.
SwingBook (JVM)
Demonstrates how to use Java style inner-classes (SHARING PARENT) in managed COBOL and shows the use of Swing with managed COBOL. Swing is part of the Java Foundation Classes which provides an API for a graphical user interface (GUI) for JVM programs. The application shows a Swing front-end to the COBOL legacy book program which accesses an indexed data file with book stock information.
JVM COBOL to Native COBOL Interop
Demonstrates how COBOL for JVM can interoperate with native COBOL.
Parent topic: Using the Command Line Demonstrations
Related information
Command Line Demonstrations of Native COBOL
Command Line Demonstrations of COBOL used with SQL
Command Line Demonstrations of COBOL used with Business Information Server (BIS)


Command Line Demonstrations of Native COBOL

These demonstration programs are installed in $COBDIR/demo/cobol by default.

adsamp
Demonstrates how to use the Screen Section to create a character user interface.
cobolctf
Shows how to enable a COBOL program to use the Consolidated Trace Facility.
mthread
Demonstrates how a main server thread responds to client requests by starting off separate threads to handle those requests.
tictac
Demonstrates how to develop native COBOL applications.
mfunit
Provides a set of simple examples that demonstrate the capabilities of the unit testing framework.
c-cobol
Illustrates the way to use COBOL, C and C++ interchangeably, and also shows how to pass parameters from each language to each of the others in an interchangeable manner.
c-ctf
Shows how to enable a C program to use the Consolidated Trace Facility.
sharedmem
Demonstrates the use of shared memory through COBOL calling UNIX functions.
Parent topic: Using the Command Line Demonstrations
Related information
Command Line Demonstrations of COBOL for JVM
Command Line Demonstrations of COBOL used with SQL
Command Line Demonstrations of COBOL used with Business Information Server (BIS)


Command Line Demonstrations of COBOL used with SQL

The demonstration programs are installed in subfolders under $COBDIR/demo/sql by default.

db2
Demonstrates the following:
  • Syntax variants supported by IBM DB2 LUW for connecting to and disconnecting from a DB2 database using TYPE 1 CONNECTs.
  • Using SELECT...INTO and cursor-based data retrieval (DECLARE, OPEN, FETCH, CLOSE).
  • Using dynamic SQL to CREATE a table and insert and update data to it.
  • Using LOB LOCATOR and VALUES function to retrieve data from a LOB and copy it to a host variable.
openesql
Demonstrates the following:
  • Using the ODBC catalog functions from COBOL.
  • Using dynamic SQL functions from COBOL
  • Using INSERT, UPDATE, DELETE, SELECT INTO and SELECT using a cursor, plus COMMIT and ROLLBACK.
  • Using different formats of the CONNECT and DISCONNECT statements
Parent topic: Using the Command Line Demonstrations
Related information
Command Line Demonstrations of COBOL for JVM
Command Line Demonstrations of Native COBOL
Command Line Demonstrations of COBOL used with Business Information Server (BIS)


Command Line Demonstrations of COBOL used with Business Information Server (BIS)

These demonstration programs are installed in $COBDIR/demo/BIS by default.

SimpleGraph
Demonstrates drawing a bar chart.
StackedGraph
Demonstrates drawing a stacked bar chart.
PieChart
Demonstrates drawing a pie chart.
GaugeExample
Demonstrates creating a gauge and SVG widget applets for use in a dashboard.
USPSBarcodes
Creates an Intelligent Mail barcode and demonstrates the use of an XSL stylesheet to produce an SVG graphics document rendering the barcode for XML/SVG capable rendering engines.
FloorPlan
Simulates a casino slot machine floor diagram.
Envelope
Creates an XML document containing the data used to address an envelope, and then invokes the Apache FOP processor to produce a PDF document.
XMLSpreadsheet
Creates a Microsoft Office spreadsheet applet.
Parent topic: Using the Command Line Demonstrations
Related information
Command Line Demonstrations of COBOL for JVM
Command Line Demonstrations of Native COBOL
Command Line Demonstrations of COBOL used with SQL


Upgrading to Visual COBOL Development Hub

This guide provides information on upgrading applications from Micro Focus Server Express to Visual COBOL Development Hub. It highlights the differences between the old and the new product, and offers solutions on how to keep your application working in the same way as before.

  1. Advantages of Upgrading
  2. Upgrading Your COBOL Applications
  3. Compiling Your Applications
  4. Differences between Visual COBOL and Server Express
    You can upgrade COBOL applications that were developed in Server Express to Visual COBOL without the need to change their code.
Parent topic: Welcome


Advantages of Upgrading

The products from the Visual COBOL suite help you bring existing applications up-to-date and extend them so they take advantage of the variety of new technologies that are emerging. In most cases, you can keep the existing COBOL logic intact and then extend your applications to enable support for the modern technologies.

Choosing to upgrade to Visual COBOL Development Hub offers the following advantages:

  • A basic upgrade - Visual COBOL Development Hub supercedes Server Express. There should be no changes required in your existing build scripts and not or minimal changes to your source code to ensure that the applications compile as before.

    The development environment is very similar to Server Express so you can quickly get up-to-speed with developing and maintaining your applications.

  • Utilize modern technologies - Visual COBOL Development Hub enables you to compile your existing applications to Java byte code without any changes. Compiling to Java byte code helps expose your applications to any other languages and technologies that use Java byte code.
Parent topic: Upgrading to Visual COBOL Development Hub
Next topic: Upgrading Your COBOL Applications


Upgrading Your COBOL Applications

Note: Visual COBOL provides many options for modernizing your existing applications following the upgrade so we recommend you contact Micro Focus Professional Services for assistance with the modernization process.

Before you start upgrading your applications, Micro Focus recommends that you get familiar with Visual COBOL Development Hub - check New to Visual COBOL Development Hub in the Where do I start section of this product help.

Prerequisites

Keep your existing source code and build scripts on your UNIX machine and install Visual COBOL Development Hub on the same machine.

Process

The following is a typical approach to upgrading an application to Visual COBOL Development Hub:

  1. Assess your existing processes for building and testing your applications that were created with Server Express.
  2. Compile your existing sources at the command line and ensure that the application behaves as it did previously:
    1. From a terminal window, set the environment for Visual COBOL Development Hub.
    2. Build the existing application.
    3. Resolve any compilation issues - see Compiling Your Applications.
  3. Compile for debugging and for release and ensure that the application performs as expected.
  4. If you have been using build scripts to compile the applications before, update these to use the new installation directory.

    Update and relink any databases being used and any third-party tools as required.

    Compile using your build scripts.

Once your applications compile as before, you can consider ways to modernize them such as to compile them to Java byte code. Procedural COBOL compiles to Java byte code without any changes which helps expose it to modern languages and technologies that interact with Java byte code.

Note: You can maximize the benefits of upgrading by using Visual COBOL Development Hub in conjunction with Visual COBOL for Eclipse installed on a local developer's machine. The Eclipse IDE helps improve the developers' productivity and efficiency by providing a number of advanced features such as a COBOL-aware editor (with Content Assist, a variety of productivity features), advanced compile, test and debug features and integration with major source control systems.
  • New to Visual COBOL Development Hub
  • Compiling Your Applications
Parent topic: Upgrading to Visual COBOL Development Hub
Previous topic: Advantages of Upgrading
Next topic: Compiling Your Applications


Compiling Your Applications

The products from the Visual COBOL suite include a lot of enhancements and some changes in behavior when compared to Server Express. Because of this, when you upgrade to Visual COBOL Development Hub from an earlier Micro Focus product you must recompile your applications using Visual COBOL Development Hub.

To compile your existing programs from a terminal window directly on the UNIX machine:

  1. Ensure that Visual COBOL Development Hub is installed and configured on the remote machine where you store your existing COBOL programs.
  2. Log onto the UNIX machine and from a terminal window and compile your programs using the cob command or the build scripts or makefiles used to build the application with Server Express.

    Remember to review and reuse all Compiler directives that were previously used when compiling the application in Server Express.

Most programs created with Server Express should compile cleanly using your existing build scripts and makefiles without any changes to your code, as Visual COBOL Development Hub also provides the cob utility to create .int, .gnt or .o files.

Fixing compilation issues

Because Micro Focus continues to enhance the COBOL language, you might encounter some problems when compiling your existing Server Express applications in Visual COBOL.

For example, the list of reserved COBOL words changes with each new level of the COBOL language, so an application created with an older Micro Focus product might use data names that are now reserved keywords in Visual COBOL. If this happens, a COBOL syntax error COBCH0666 ("Reserved word used as data name or unknown data description qualifier") occurs. See Reserved Words Table in this product help for a comprehensive list of reserved words and the levels at which they are supported.

Also, these Server Express Compiler directives are no longer supported:

  • 01SHUFFLE
  • 64KPARA
  • 64KSECT
  • AUXOPT
  • CHIP
  • DATALIT
  • EANIM
  • EDITOR
  • ENSUITE
  • EXPANDDATA
  • FIXING
  • FLAG-CHIP
  • MASM
  • MODEL
  • OPTSIZE
  • OPTSPEED
  • PARAS
  • PROTMODE
  • REGPARM
  • SEGCROSS
  • SEGSIZE
  • SIGNCOMPARE
  • SMALLDD
  • TABLESEGCROSS
  • TRICKLECHECK
  • WB2
  • WB3
  • WB

and the pseudovariables of the following Server Express environment variables are obsolete and can't be used:

  • BASENAME
  • FILENAME
  • PATH
  • TARGETDIR

You should consider using the following methods to solve such issues:

  • Rewrite the source to avoid using these keywords in your code and directives files.
  • Use the REMOVE Compiler directive to remove individual keywords from the reserved words list.
  • Use the MF or MFLEVEL Compiler directive to select an earlier version of Micro Focus COBOL that your code is compatible with. For example, setting MFLEVEL"12" ensures compatibility with Mainframe Express 3.0 and 3.1, Net Express 4.0, 5.0, and 5.1, and Server Expresss 4.0, 5.0, and 5.1. Refer to Reserved Words Table in this product help for the value to use to ensure support for your existing reserved words.

To use REMOVE from the terminal window, type the following:

cob myprogram.cbl -C remove=title

The command above removes TITLE as a keyword from the language so you can use it as an identifier in a COBOL program.

To use the set of reserved words that was used for Server Express v5.1 WrapPack 5, use this command line:

cob myprogram.cbl -C mflevel=15

To set either one of the directives in your source code, type the following starting with $ in the indicator area of your COBOL program:

$set remove "title"

Or:

$set mflevel"15"
Parent topic: Upgrading to Visual COBOL Development Hub
Previous topic: Upgrading Your COBOL Applications
Next topic: Differences between Visual COBOL and Server Express
Parent topic: Upgrading Your COBOL Applications


Differences between Visual COBOL and Server Express

You can upgrade COBOL applications that were developed in Server Express to Visual COBOL without the need to change their code.

All references to Net Express and Server Express in this guide relate to the variants of those products that provided Mainframe Subsystem Support as part of the Studio Enterprise Edition bundle.

This guide lists the differences between Net Express, Server Express and Visual COBOL in the following areas:

Compiling and building
You use the command line to build your applications as you did in the previous Micro Focus products.
Run-time systems
There are some differences between the run-time systems supplied with Visual COBOL and those supplied with Server Express. This, however, will not affect your existing applications and they will continue to run under Visual COBOL - you only need to recompile the applications from the source code with Visual COBOL.
Run-time system technologies
Some technologies behave differently and require some upgrade work.
Restrictions and unsupported features
Some features of Server Express are not available in Visual COBOL.
Editing and debugging
Much of the Server Express functionality for editing and debugging is available in Visual COBOL.
  • Licensing Changes
    Micro Focus is using a new standard industry technology for license management in Visual COBOL.
  • Recompile all source code
    Application executables that were compiled using Net Express, Server Express, RM/COBOL or extend® (ACUCOBOL-GT) must be recompiled from the sources using Visual COBOL.
  • Default Working Mode
  • Summary of Differences
    The majority of the applications created with Net Express or Server Express will continue to work in Visual COBOL without any changes. However, there are some differences between these development systems you should consider when you upgrade to Visual COBOL.
  • Compiling and Building Differences
    There are several aspects of compiling and building applications that behave differently in Visual COBOL. You might need to change the project properties and update some of the Compiler directives and settings that you previously used.
  • Run-time System Differences
    There are some differences between the run-time systems supplied with Visual COBOL and those supplied with Server Express. These, however, do not affect your existing applications if you recompile them from the source code in Visual COBOL.
  • Restrictions and Unsupported Features
    Some features in earlier Micro Focus products are not available in Visual COBOL. However there are alternative techniques for many of these features.
  • Run-Time Technology Differences
    Some technologies behave differently in Visual COBOL and this might affect how you upgrade existing applications.
  • Editing and Debugging Differences
    Much of the edit and debug functionality in Server Express is available in Visual COBOL, but some of it has a different name or slightly different behavior.
  • Procedural COBOL Compared with Managed COBOL
    Procedural COBOL is regular COBOL without any of the new syntax that has been added for .NET and JVM. Managed COBOL is the collective term for .NET COBOL and JVM COBOL.
Parent topic: Upgrading to Visual COBOL Development Hub
Previous topic: Compiling Your Applications


Licensing Changes

For a number of years Micro Focus used the Micro Focus License System Administration for Net Express and Server Express.

Micro Focus now uses a standard industry technology for license management, Sentinel RMS from SafeNet. New product releases use Sentinel RMS, as do updates to existing products.

For more on the Micro Focus License Administration tool, see Managing Licenses.

Parent topic: Differences between Visual COBOL and Server Express
Related concepts
Managing Licenses


Recompile all source code

Application executables that were compiled using Net Express, Server Express, RM/COBOL or extend® (ACUCOBOL-GT) must be recompiled from the sources using Visual COBOL.

If you do not recompile, you may receive an error. The exact error depends on the operating system you are running. The error might be similar to this, on UNIX:

ld.so.1: rts32: fatal: libcobrts.so.2: open failed: No such file or directory
Killed
Parent topic: Differences between Visual COBOL and Server Express


Default Working Mode

The default working mode in Server Express was 32-bit. In Development Hub it is 64-bit. On machines that support both 32 and 64-bit, you can change the working mode to 32-bit.

Parent topic: Differences between Visual COBOL and Server Express


Summary of Differences

The majority of the applications created with Net Express or Server Express will continue to work in Visual COBOL without any changes. However, there are some differences between these development systems you should consider when you upgrade to Visual COBOL.

Compiling and Building Differences

There are several aspects of compiling and building applications that behave differently in Visual COBOL. You might need to change the project properties and update some of the Compiler directives and settings that you previously used.

Compiler directives
When you upgrade your source code to Visual COBOL some Compiler directives that were specifically designed for 16-bit systems now produce an error on compilation because they are no longer relevant. You should remove them from your code and directives files before you compile.
SQL Compiler Directive Options
When you upgrade your to Visual COBOL, some SQL applications could require additional SQL Compiler directive options to avoid compiler errors.
XML PARSE Statement
In Server Express, the default setting for the XMLPARSE Compiler directive is COMPAT, which causes the XML PARSE statement to return information and events for IBM Enterprise COBOL Version 3. In Visual COBOL, the default is XMLPARSE(XMLSS), which returns information and events for IBM Enterprise COBOL Version 4.

Run-Time System Differences

There are some differences between the run-time systems supplied with Visual COBOL and those supplied with Server Express. These, however, do not affect your existing applications if you recompile them from the source code in Visual COBOL.

OpenESQL
Visual COBOL sets the BEHAVIOR SQL Compiler directive option to MAINFRAME by default to provide optimal performance. To revert to the default behavior exhibited in Server Express, set the BEHAVIOR directive to UNOPTIMIZED.
Static-Linked Run-Time System
The static-linked run-time system is not available in Visual COBOL. Instead, you now link native code to the shared or dynamic run-time system. This has no effect on your existing applications.
Setting the environment on UNIX
You use the cobsetenv script to set your COBOL environment on UNIX if you have installed the product to a directory other than the default one.

Restrictions and Unsupported Features

Some features in earlier Micro Focus products are not available in Visual COBOL. However there are alternative techniques for many of these features.

Character-Mode Dialog System
Support for creating character-based user interfaces for applications that run in character environments is available in Visual COBOL.
DBMS Preprocessors
Earlier Micro Focus products supported DBMS preprocessor versions that are not supported in Visual COBOL. For a list of currently supported DBMS preprocessors, see the Database Access Support with Native COBOL topic.
FSView
FSView is a utility for administering Fileshare servers. The FSView GUI is not supported in Visual COBOL.
GNT Analyzer
GNT Analyzer is not available in Visual COBOL. It has been replaced by Test Coverage.
Host Compatibility Option (HCO)
Host Compatibility Option (HCO) is not supported in Visual COBOL.
INTLEVEL Support
The INTLEVEL directive is rejected by the Compiler in Visual COBOL.
NSAPI
There is no support for NSAPI in Visual COBOL.
OO Class and Method Wizards
The OO Class and Methods wizards are not available in Visual COBOL. However, the run-time components for the base and COM OO class libraries are available.
SQL Option for DB2
SQL Option for DB2, also known as XDB, is not supported in Visual COBOL.
UNIX Publish
The UNIX Publish feature is superseded by the remote development functionality in Visual COBOL for Eclipse. You use the Eclipse IDE on a local machine as the development interface. You use Visual COBOL Development Hub on a remote development server where you host your source code.

Run-Time Technology Differences

Some technologies behave differently in Visual COBOL and this might affect how you upgrade existing applications.

File Handling
The way you integrate your own security modules into Fileshare has changed. Also, the FILEMAXSIZE setting is different for Visual COBOL and for Net Express and Server Express .
Java and COBOL
The cobsje script is not available in Visual COBOL. Visual COBOL uses the COBOL run-time system to load JVM based on LIBPATH, LD_LIBRARY_PATH, JAVA_HOME etc...
Test Coverage
Test Coverage replaces GNT Analyzer, which was available in Server Express.

Editing and Debugging Differences

Much of the edit and debug functionality in Server Express is available in Visual COBOL, but some of it has a different name or slightly different behavior.

Data Tools
The Net Express Data Tools are available as the Classic Data File Tool utility in Visual COBOL on Windows, but not on UNIX. On UNIX, there is a new Data File Tools utility which is a standalone text editor in which you can create and edit data files .
Interface Mapping Toolkit
The Interface Mapping Toolkit is not available in Visual COBOL Development Hub. It is available in Visual COBOL for Eclipse; however it does not support CICS or IMS service interfaces.
Parent topic: Differences between Visual COBOL and Server Express


Compiling and Building Differences

There are several aspects of compiling and building applications that behave differently in Visual COBOL. You might need to change the project properties and update some of the Compiler directives and settings that you previously used.
  • Compiler directives
    When you upgrade your source code to Visual COBOL some Compiler directives that were specifically designed for 16-bit systems now produce an error on compilation because they are no longer relevant. You should remove them from your code and directives files before you compile.
  • SQL Compiler Directive Options
    When you upgrade your to Visual COBOL, some SQL applications could require additional SQL Compiler directive options to avoid compiler errors.
  • XML PARSE Statement
    In Server Express, the default setting for the XMLPARSE Compiler directive is COMPAT, which causes the XML PARSE statement to return information and events for IBM Enterprise COBOL Version 3. In Visual COBOL, the default is XMLPARSE(XMLSS), which returns information and events for IBM Enterprise COBOL Version 4.
Parent topic: Differences between Visual COBOL and Server Express


Compiler directives

When you upgrade your source code to Visual COBOL some Compiler directives that were specifically designed for 16-bit systems now produce an error on compilation because they are no longer relevant.

The following Compiler directives are no longer relevant and we recommend that you remove them from your code and directives files before you compile:
  • 01SHUFFLE
  • 64KPARA
  • 64KSECT
  • ASM
  • ASMLIST
  • AUXOPT
  • CHIP
  • DATALIT
  • EANIM
  • EARLY-RELEASE
  • EDITOR
  • ENSUITE
  • EXPANDDATA
  • FAULTFIND
  • FIXING
  • FLAG-CHIP
  • FLAGGED
  • LOGICOPT
  • MASM
  • MF-OO
  • MODEL
  • NESTCALL
  • OMF
  • OPTSIZE
  • OPTSPEED
  • PARAS
  • PROTMODE
  • REGPARM
  • SEGCROSS
  • SEGSIZE
  • SIGNCOMPARE
  • SMALLDD
  • TABLESEGCROSS
  • TARGET
  • TRICKLECHECK
  • WEBSERVER
Parent topic: Compiling and Building Differences


SQL Compiler Directive Options

If you get errors in Visual COBOL when compiling an object application that was created in Server Express, recompile specifying the GEN-CLASS-VAR SQL Compiler directive option in addition to other appropriate options.

Parent topic: Compiling and Building Differences


XML PARSE Statement

In Server Express, the default setting for the XMLPARSE Compiler directive is COMPAT, which causes the XML PARSE statement to return information and events for IBM Enterprise COBOL Version 3. In Visual COBOL, the default is XMLPARSE(XMLSS), which returns information and events for IBM Enterprise COBOL Version 4.

To emulate the Server Express behavior in Visual COBOL, specify the XMLPARSE(COMPAT) Compiler directive option.

For a summary of the differences in event information between XMLPARSE(XMLSS) and XMLPARSE(COMPAT), see the Special Registers topic in your Visual COBOL documentation.

Parent topic: Compiling and Building Differences


Run-time System Differences

There are some differences between the run-time systems supplied with Visual COBOL and those supplied with Server Express. These, however, do not affect your existing applications if you recompile them from the source code in Visual COBOL.

The changes in the run-time system are described in the following sections.

  • OpenESQL
    Visual COBOL sets the BEHAVIOR SQL Compiler directive option to MAINFRAME by default to provide optimal performance. To revert to the default behavior exhibited in Server Express, set the BEHAVIOR directive to UNOPTIMIZED.
  • Static-Linked Run-Time System
    The static-linked run-time system is not available in Visual COBOL. Instead, you now link native code to the shared or dynamic run-time system. This has no effect on your existing applications.
  • Setting the environment on UNIX
    You use the cobsetenv script to set your COBOL environment on UNIX if you have installed the product to a directory other than the default one.
Parent topic: Differences between Visual COBOL and Server Express


OpenESQL

Visual COBOL sets the BEHAVIOR SQL Compiler directive option to MAINFRAME by default to provide optimal performance. To revert to the default behavior exhibited in Server Express, set the BEHAVIOR directive to UNOPTIMIZED.
Parent topic: Run-time System Differences


Static-Linked Run-Time System

The static-linked run-time system is not available in Visual COBOL. Instead, you now link native code to the shared or dynamic run-time system. This has no effect on your existing applications.

See Linking Native COBOL Code in the product Help.

Parent topic: Run-time System Differences


Setting the environment on UNIX

If you have installed the product to a directory other than the default one, before you start developing applications with Visual COBOL on UNIX, you need to set the environment. We recommend that you use the cobsetenv script to do this:

. <product-install-dir>/bin/cobsetenv

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

Parent topic: Run-time System Differences


Restrictions and Unsupported Features

Some features in earlier Micro Focus products are not available in Visual COBOL. However there are alternative techniques for many of these features.
  • Character-Mode Dialog System
    Support for creating character-based user interfaces for applications that run in character environments is available in Visual COBOL.
  • DBMS Preprocessors
    Earlier Micro Focus products supported DBMS preprocessor versions that are not supported in Visual COBOL. For a list of currently supported DBMS preprocessors, see the Database Access Support with Native COBOL topic.
  • FSView
    FSView is a utility for administering Fileshare servers. The FSView GUI is not supported in Visual COBOL.
  • GNT Analyzer
    GNT Analyzer is not available in Visual COBOL. It has been replaced by Test Coverage.
  • Host Compatibility Option (HCO)
    Host Compatibility Option (HCO) is not supported in Visual COBOL.
  • INTLEVEL Support
    The INTLEVEL directive is rejected by the Compiler in Visual COBOL.
  • NSAPI
    There is no support for NSAPI in Visual COBOL.
  • OO Class and Method Wizards
    The OO Class and Methods wizards are not available in Visual COBOL. However, the run-time components for the base and COM OO class libraries are available.
  • OpenESQL
    In both Net Express and Studio Enterprise Edition, support is provided for Oracle OCI in OpenESQL. Visual COBOL does not support Oracle OCI in OpenESQL.
  • SQL Option for DB2
    SQL Option for DB2, also known as XDB, is not supported in Visual COBOL.
  • UNIX Publish
    The UNIX Publish feature is superseded by the remote development functionality in Visual COBOL for Eclipse. You use the Eclipse IDE on a local machine as the development interface. You use Visual COBOL Development Hub on a remote development server where you host your source code.
Parent topic: Differences between Visual COBOL and Server Express


Character-Mode Dialog System

Support for creating character-based user interfaces for applications that run in character environments is available in Visual COBOL.
Parent topic: Restrictions and Unsupported Features


DBMS Preprocessors

Earlier Micro Focus products supported DBMS preprocessor versions that are not supported in Visual COBOL. For a list of currently supported DBMS preprocessors, see the Database Access Support with Native COBOL topic.
Parent topic: Restrictions and Unsupported Features


FSView

FSView is a utility for administering Fileshare servers. The FSView GUI is not supported in Visual COBOL.

Visual COBOL provides all the FSView functions through the command-line utility fsview. For more information see File Handling Reference > FSView > FSVIEW Command Line in the product Help.

Parent topic: Restrictions and Unsupported Features


GNT Analyzer

GNT Analyzer is not available in Visual COBOL. It has been replaced by Test Coverage.
Parent topic: Restrictions and Unsupported Features


Host Compatibility Option (HCO)

Host Compatibility Option (HCO) is not supported in Visual COBOL.
Parent topic: Restrictions and Unsupported Features


INTLEVEL Support

The INTLEVEL directive is rejected by the Compiler in Visual COBOL.

An INTLEVEL of 1, 2, or 3 is no longer supported and causes compilation errors. Other values are reserved for internal use and should not be used.

Parent topic: Restrictions and Unsupported Features


NSAPI

There is no support for NSAPI in Visual COBOL.
Parent topic: Restrictions and Unsupported Features


OO Class and Method Wizards

The OO Class and Methods wizards are not available in Visual COBOL. However, the run-time components for the base and COM OO class libraries are available.
Parent topic: Restrictions and Unsupported Features


OpenESQL

In both Net Express and Studio Enterprise Edition, support is provided for Oracle OCI in OpenESQL. Visual COBOL does not support Oracle OCI in OpenESQL.
Parent topic: Restrictions and Unsupported Features


SQL Option for DB2

SQL Option for DB2, also known as XDB, is not supported in Visual COBOL.
Parent topic: Restrictions and Unsupported Features


UNIX Publish

The UNIX Publish feature is superseded by the remote development functionality in Visual COBOL for Eclipse. You use the Eclipse IDE on a local machine as the development interface. You use Visual COBOL Development Hub on a remote development server where you host your source code.
Parent topic: Restrictions and Unsupported Features


Run-Time Technology Differences

Some technologies behave differently in Visual COBOL and this might affect how you upgrade existing applications.
  • File Handling
    The way you integrate your own security modules into Fileshare has changed. Also, the FILEMAXSIZE setting is different for Visual COBOL and for Net Express and Server Express .
  • Java and COBOL
    The cobsje script is not available in Visual COBOL. Visual COBOL uses the COBOL run-time system to load JVM based on LIBPATH, LD_LIBRARY_PATH, JAVA_HOME etc...
  • Test Coverage
    Test Coverage replaces GNT Analyzer, which was available in Server Express.
Parent topic: Differences between Visual COBOL and Server Express


File Handling

The way you integrate your own security modules into Fileshare has changed. Also, the FILEMAXSIZE setting is different for Visual COBOL and for Net Express and Server Express .

Using security modules

The way you integrate your own security modules (fhrdrlngpwd, fhrdrpwd, fsseclog and fssecopn) into Fileshare has changed.

In Visual COBOL, you no longer relink Fileshare but you need to supply your own separate files, which are .dll files on Windows or shared objects on UNIX. For more information, see Writing Your Own FHRdrLngPwd Module, File Access Validation Module and Logon Validation Module in the File Handling section of your product Help.

To use fsseclog and fssecopn, you need to link one or both of them into a cobfssecurity.dll or a shared object and place on the search path. Fileshare will issue a message indicating that it has loaded user security modules.

On UNIX, you no longer use fsclose to call Fileshare Manager. You need to use cobfsclose instead.

Sharing data files between applications built in Visual COBOL and others built using Net Express or Server Express

If you have applications that access the same data files, all those applications should be built with the same FILEMAXSIZE setting otherwise file corruption may occur. However, you need to be aware that applications built with Visual COBOL use a default setting of FILEMAXSIZE=8, while those built in Net Express or Server Express use FILEMAXSIZE=4.

Parent topic: Run-Time Technology Differences


Java and COBOL

The cobsje script is not available in Visual COBOL. Visual COBOL uses the COBOL run-time system to load JVM based on LIBPATH, LD_LIBRARY_PATH, JAVA_HOME etc...
Parent topic: Run-Time Technology Differences


Test Coverage

Test Coverage replaces GNT Analyzer, which was available in Server Express.
Parent topic: Run-Time Technology Differences


Editing and Debugging Differences

Much of the edit and debug functionality in Server Express is available in Visual COBOL, but some of it has a different name or slightly different behavior.
  • Data Tools
    The Net Express Data Tools are available as the Classic Data File Tool utility in Visual COBOL on Windows, but not on UNIX. On UNIX, there is a new Data File Tools utility which is a standalone text editor in which you can create and edit data files .
  • Interface Mapping Toolkit
    The Interface Mapping Toolkit is not available in Visual COBOL Development Hub. It is available in Visual COBOL for Eclipse; however it does not support CICS or IMS service interfaces.
  • Remote Debugging
    The Net Express animserv utility used for debugging programs remotely has been replaced by cobdebugremote32 (or cobdebugremote64 when debugging 64-bit processes) in Visual COBOL.
Parent topic: Differences between Visual COBOL and Server Express


Data Tools

The Net Express Data Tools are available as the Classic Data File Tool utility in Visual COBOL on Windows, but not on UNIX. On UNIX, there is a new Data File Tools utility which is a standalone text editor in which you can create and edit data files .
On UNIX, you can use the Micro Focus Data File Tools utility. It is a standalone text editor in which you can create and edit data files for use in your COBOL testing environment. The files you create can belong to a Fileshare server or reside locally on your machine. You can also open existing data sets within your Enterprise Server regions, for editing.
Parent topic: Editing and Debugging Differences


Interface Mapping Toolkit

The Interface Mapping Toolkit is not available in Visual COBOL Development Hub. It is available in Visual COBOL for Eclipse; however it does not support CICS or IMS service interfaces.
Parent topic: Editing and Debugging Differences


Remote Debugging

The Net Express animserv utility used for debugging programs remotely has been replaced by cobdebugremote32 (or cobdebugremote64 when debugging 64-bit processes) in Visual COBOL.

To debug locally-developed programs on a remote machine you must start cobdebugremote32 (or cobdebugremote64 when debugging 64-bit processes) before communication can be established. See the Visual COBOL help for more information on cobdebugremote.

To debug remotely-developed programs on a remote machine:

  • You use a local Visual COBOL installation to develop remote projects on a remote UNIX machine that has Visual COBOL Development Hub installed.

  • To debug a COBOL project, the project must be compiled for debugging and you need to create a debug configuration.

For more information, see the section on Remote Debugging in your Visual COBOL product help.

Parent topic: Editing and Debugging Differences


Procedural COBOL Compared with Managed COBOL

Note: Visual COBOL for Eclipse supports managed COBOL. To develop applications for managed COBOL, install one of our Visual COBOL for Visual Studio products.

Procedural COBOL is regular COBOL without any of the new syntax that has been added for .NET and JVM. This is the COBOL that was used to write Net Express, Server Express and Mainframe Express applications, and it is still actively supported today.

You can compile to native or (in most cases) managed code. The core COBOL syntax is supported in managed code. However, there are some features that are not supported (for example Panels V2, Dialog System and ACUCOBOL-GT). This means that you can take most existing COBOL applications and recompile to create managed applications.

Managed COBOL

Managed COBOL is the collective term for .NET COBOL and JVM COBOL.

Managed COBOL is COBOL with extensions to support the .NET and JVM frameworks. It offers OO syntax support and syntax to allow access to the available class libraries.

When you compile managed JVM COBOL, the compiler generates managed code: .class or .jar for JVM that runs on the Java Virtual Machine.

Managed Code and Native Code

You can compile your COBOL program to managed code using the jvmgen compiler directive. From within the IDE this happens automatically if you are using a managed COBOL JVM project.

The compiler has now created an intermediate language (JVM byte code .class/.jar).

COBOL and all other JVM languages (for example Java, JRuby and Jyphon) compile to this format, which makes mixed language applications easy to write.

You can also create native code applications.In Eclipse, the default COBOL project compiles to native code.

The compiler generates .exe/.dlls as the result of a native compilation.

The native COBOL application has to call the appropriate management services available for the operating system, whereas a managed application can take advantage of the management services provided by the run time such as exception handling, garbage collection, and thread management.

Run Time

The JVM byte code (.class/.jar files) can be deployed to a Java Virtual Machine for execution.

The JVM's just-in-time (JIT) compiler compiles the byte code into code native to the operating system. The JVM provides additional services including memory management, exception handling, garbage collection and thread management.

Developing Native and Managed Applications

You use the IDE to develop, compile and debug both native and managed applications. You can write new COBOL code or you can recompile existing COBOL applications to managed or native code, potentially without any code changes.

You can deploy and further debug the application under the run-time system provided by COBOL Server.

JVM COBOL applications are deployed to a Java Virtual Machine for execution.

Parent topic: Differences between Visual COBOL and Server Express
Related concepts
Executable File Formats
Native COBOL compared with managed COBOL


Help on Help

The latest up-to-date Help is available on the Micro Focus SupportLine Web site.

Release Notes

The Release Notes accompany major releases and updates. They are available from the Product Updates section on the Micro Focus SupportLine Web site and your EPD email.

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


Developing Applications

  • Overview of Application Development
  • Packaging Applications
  • Working in 32-bit and 64-bit Modes
  • Creating Programs
  • Building applications
    To build an application, you need to compile its programs and link them to a run-time system.
  • Debugging Applications
  • Running Applications
  • Test Coverage (Native COBOL)
Parent topic: Visual COBOL Development Hub 5.0


Overview of Application Development

Visual COBOL Development Hub can be used standalone or in conjunction with Visual COBOL for Eclipse.

The following is an overview of the process of developing programs if you are using Visual COBOL Development Hub as a standalone product:

  1. Access Visual COBOL Development Hub:
    1. Connect to the UNIX or Linux machine that has Development Hub installed.
    2. Open a terminal and set the environment - see Setting up the product.
  2. Create a program:

    Use a UNIX-based editor to create a COBOL source file and type your code in it.

  3. Compile the program:

    When you have created your source program, you can invoke the Compiler and try to compile the program to ensure it is valid COBOL.

    If the Compiler finds any syntax errors, return to the editor to correct the errors before compiling again.

  4. Debug the program:

    When the program compiles with no errors, you debug, run and test it using Animator. Animator enables you to watch and control the working of your program, seen entirely as COBOL source, and therefore makes testing and debugging very efficient.

    If you find an error while testing, go back to the source in the editor to correct the error. You then need to invoke the Compiler and Animator again.

    You can use Animator only on native COBOL programs that have been compiled or linked to any of the formats supported by Visual COBOL: intermediate code, generated code, callable shared object code or system executable code. The ability of Animator to debug all supported executable formats means that you can debug programs at any stage of the application development cycle.

    Note: You can only use Animator to test native COBOL programs. A debugger for JVM COBOL at present is only available if you use Visual COBOL for Eclipse to debug your sources on the remote UNIX or Linux machine.
  5. When your program is working correctly, you can run it. Any subprograms and run-time support modules that it needs are automatically loaded as necessary.
  6. Ship the application:

    When your application is working correctly you might want to optimize it and ship it to your users.

    The Compiler's syntax check phase produces intermediate code; this is a Micro Focus proprietary code, contained in a file with a filename extension of .int, which can be interpreted by Animator and the Run function. If you want faster execution, you can create optimized object code in two native machine code formats:

    • Generated code, contained in a file with a filename extension .gnt
    • Callable shared object code, contained in a filename extension .so

    You can run files in both formats in the same way as intermediate code.

    You can create generated code or callable shared objects using the menus, or by using the cob command. You can also create an executable file by creating native machine code, with the filename extension .o, and then linking this with the run-time support files to create a system executable file (which usually has no extension and is known as an a.out file). This executable file can call .so, .int and .gnt files if required.

    Shipping components of this system to users is subject to a license agreement.

  • Accessing Development Hub
  • Editing Programs
  • Compiling Programs
  • Linking Programs
  • Debugging Programs
  • Running Programs
Parent topic: Developing Applications


Accessing Development Hub

You can access Development Hub in order to edit, compile, debug and run your COBOL applications in one of the following ways:

Using a terminal emulator

Use a terminal emulator such as Micro Focus Rumba to connect to the UNIX or Linux machine where Development Hub is installed to access your sources.

Once you are connected to the remote machine, you need to set the COBOL environment - see Set up the product.

Using Visual COBOL

In this scenario, you need Micro Focus Visual COBOL for Eclipse installed and licensed on a local development machine.

You create a remote connection in Visual COBOL to the UNIX or Linux machine where Development Hub is installed. Then, you can access your COBOL sources by either opening the files in Eclipse as standalone files or creating an Eclipse COBOL project and adding the source files to it.

See the Visual COBOL product help for more details on how to develop applications remotely using Eclipse.

Direct access

Log in directly to the remote UNIX or Linux machine and execute any commands for editing, compiling or debugging from a terminal. Micro Focus does not recommend this scenario as in most cases direct user access to the remote UNIX or Linux machine will be restricted.

Once you are logged onto the remote machine, start a terminal and set the COBOL environment - see Set up the product.

Parent topic: Overview of Application Development
Related tasks
Setting up the product


Editing Programs

If you use Development Hub as a standalone product, use a Linux/UNIX-based editor such as vi to edit your COBOL programs.

If you use Development Hub in conjunction with Visual COBOL for Eclipse installed on a local development machine:

  • Create a connection in Visual COBOL to the remote machine where Development Hub and your source code reside.

    Once a connection is established, from your local Visual COBOL you can open individual files on the remote machine or create remote projects for the source code on the remote machine. Then you can take advantage of the fully-featured development environment and the advanced features for editing, compiling and debugging to change or maintain your COBOL applications.

Parent topic: Overview of Application Development


Compiling Programs

Use the cob command to compile and link your sources.

The Compiler creates the intermediate code in a file with extension .int and produces extra information needed by Animator in an .idy file.

To compile your sources to JVM byte code (.class files), use the cob command with the -j flag: cob -j.

Using Compiler Directives

You can use Compiler directives to control the way in which your source code is compiled such as to change the syntax allowed by the Compiler and the output it produces. You can set the directives at the command line, in the source code or in a directives file.

For example, here's how you specify Compiler directives at the command line:

cob tictac.cbl osvs flag(osvs) list()

You are compiling your COBOL program with three directives. The first two describe the language you want to test for: the OSVS directive means you want the OSVS reserved word list used, and the FLAG(OSVS) directive means you want any syntax that is not OSVS-compatible to be indicated.

The final directive, LIST, means you want the source listing that the Compiler produces sent to a file. The parentheses mean you want to use the default name, which is your program name with an extension of .lst, so this creates tictac.lst.

Generating Callable Shared Objects

You can create a callable shared object file with the extension .so; this contains native machine code, which executes faster than intermediate code. Unlike .int and .gnt files, however, callable shared objects can contain more than one COBOL program and can also contain programs written in other language such as C and C++. Callable shared objects can also be linked with third-party object files or shared libraries. This behavior is similar to system executables and shared libraries but differs from .int files and .gnt files, where each file corresponds to a single COBOL program.

Generating Native Code

You can compile your program to create a file with extension .gnt containing native machine code, which executes faster than intermediate code.

Parent topic: Overview of Application Development
Related reference
Compiling Applications


Linking Programs

When your application is working you might want to make it independent of your COBOL development system so you can distribute it for use on other binary-compatible machines. To do this you use the UNIX system linker.

Note:
  • You can link your program only if you have a C/Operating System Development System installed on your machine. This provides the system tools that the Cob utility needs such as ld, the system linker.
  • You can only run your application on another system if COBOL Server and the requisite licenses are available on that system.
Parent topic: Overview of Application Development
Related reference
Linking


Debugging Programs

You use Animator to watch how your native COBOL code is executing. You can execute your program in one of three modes: Step, Go and Zoom. When you execute your program in Step mode, you manually control the execution of each statement. In Go mode, you initially set the speed of execution, then watch as each statement is automatically executed. Zoom mode executes the entire program without displaying the source until it reaches the end of the program. You can interrupt it, or set a breakpoint where it will stop.

Restriction:

Development Hub does not contain a facility for debugging JVM COBOL applications. You can debug these if you have Visual COBOL for Eclipse installed on a separate machine.

Parent topic: Overview of Application Development
Related reference
Debugging Applications


Running Programs

You run a program from a terminal window in the same way regardless of whether you are running intermediate code, generated code or callable shared objects.

To run native COBOL programs, use the cobrun command.

To run JVM COBOL programs, use the cobjrun command. This initializes the COBOL Run-Time System and then starts the JVM to run the class.

Parent topic: Overview of Application Development
Related reference
cobrun
cobjrun


Packaging Applications

Describes the different ways you can package your applications, and describes how the choices you make affect the process of compiling and linking programs.

  • Introduction
  • Executable File Types - Summary
  • Creating Applications
Parent topic: Developing Applications


Introduction

Throughout the rest of this chapter the word "application" is used to describe the product you want to ship to your users; the word "program" is used specifically to describe the programs that make up an application.

With Visual COBOL you can create applications that consist of any combination of:

  • Callable shared objects. These are executable files in a system format
  • Intermediate or generated code files. These are executable files in a proprietary format
  • Shared libraries or linked programs. These enable you to create applications in a system executable format

Each of the options presented here has its advantages and disadvantages.

When you create an application, you need to consider the following:

  • How you want to present the package to your users
  • Whether application speed is more important than application portability
  • Whether you want your application to appear to your users in the same format as other applications on the target system

The following sections describe the differences between the executable file types, and between the different methods of packaging your applications.

For information on using the Cob utility, see COBOL System Interface (Cob). If you are working in 64-bit mode, you should also see Working in 32-bit and 64-bit Modes.

Parent topic: Packaging Applications
Related concepts
Working in 32-bit and 64-bit Modes
cob (cob32 or cob64) Command


Executable File Types - Summary

The following table summarizes the main advantages of the different executable file formats available in Visual COBOL.

Advantages | File type
Operating system format | Callable shared object System executable Shared library
Executes quickly | Callable shared object Generated code System executable Shared library
Shareable | Callable shared object System executable Shared library
Used for mixed-language applications | Callable shared object System executable Shared library
Dynamically loaded and only run when called from a COBOL program | Callable shared object Generated code Intermediate code
Portable to other processors and operating systems | Intermediate code
Submodules can easily be replaced without relinking the entire application | Callable shared object Generated code Intermediate code Shared library

All of the file formats can be used when debugging a program.

  • Callable Shared Object Files
  • Intermediate Code Files
  • Generated Code Files
  • Shared Library Files
  • System Executable Files
  • Executable File Types
Parent topic: Packaging Applications


Callable Shared Object Files

Callable shared object files are in an operating system format. They can be shared between processes; if two different system executables call, at the same time, a subprogram created as a callable shared object, that program is loaded only once and executed when called. The operating system shares the procedural code and creates separate data areas for each process.

A callable shared object is dynamically loaded and executed by the run-time system. Callable shared objects are not interpreted; their execution time is generally quicker than either intermediate or generated code.

Callable shared object files have the filename extension .so; for example, myprog.so.

Callable shared object files are created using the cob -z command; see the chapters COBOL System Interface (Cob) and Callable Shared Objects for details.

Parent topic: Executable File Types - Summary
Related concepts
Callable Shared Objects
cob (cob32 or cob64) Command


Intermediate Code Files

Intermediate code files are created by the Compiler when it checks the syntax of programs. These files are independent of both the chip-set and operating system, and are thus highly portable to other platforms. They cannot be shared between processes; if two different executables call, at the same time, a subprogram compiled to intermediate code, a separate copy of that subprogram is loaded into each process's virtual memory space, and run.

An intermediate code file is dynamically loaded and interpreted by the run-time system. Because the intermediate code is interpreted by the run-time system, intermediate code files generally execute slower than other executable file formats.

Intermediate code files have the filename extension .int; for example, myprog.int. The phrase ".int file" is often used as a synonym for the phrase "intermediate code file".

Intermediate code files are created when you check the syntax of your program. Syntax-checking is one of the phases of the compilation process. Programs are compiled using the cob -i command; see COBOL System Interface (Cob) for details.

Parent topic: Executable File Types - Summary
Related concepts
cob (cob32 or cob64) Command


Generated Code Files

Generated code files are created by the Compiler's generate phase when requested. These files are portable to the same chip-set, but are operating system dependent. Generated code files cannot be shared between processes; if two different programs call, at the same time, a subprogram compiled to generated code, a separate copy of that subprogram is loaded into each process's virtual memory space, and run.

A generated code file is dynamically loaded and executed by the run-time system. Generated code files are typically many times faster than .int files.

Generated code files have the extension .gnt ; for example myprog.gnt. The phrase ".gnt file" is often used as a synonym for the phrase "generated code file".

Programs are compiled using the cob -u command; see COBOL System Interface (Cob) for details.

Parent topic: Executable File Types - Summary
Related concepts
cob (cob32 or cob64) Command


Shared Library Files

Shared library files are linked into system executable files. They are loaded when the system executable is loaded and run. They cannot be executed themselves. They can be shared between processes. If multiple copies of the same shared library are used at the same time, the operating system shares the procedural code and creates separate data areas for each process. This includes sharing any COBOL procedural code linked into the shared library file.

Shared library files have the prefix lib, and the extension .so; for example, libmyprog.so. On HP-UX PA-RISC, the extension is .sl.

Programs are compiled using the cob -Z command; see COBOL System Interface (Cob) and Linking to System Executables for details.

Parent topic: Executable File Types - Summary
Related concepts
cob (cob32 or cob64) Command
Creating Different Types of Files


System Executable Files

System executable files are in an operating system format. They can be shared between processes. If multiple copies of the same system executable are run at the same time, the operating system shares the procedural code and creates separate data areas for each process. This includes sharing any COBOL procedural code linked into the system executable.

System executable files are loaded by the operating system, which creates a new process in which to run it. They cannot be called from COBOL using the CALL statement.

System executable files do not typically have a filename extension, and are sometimes known as a.out files.

Programs are compiled using the cob -x command; see COBOL System Interface (Cob)and Linking to System Executables for details.

Parent topic: Executable File Types - Summary
Related concepts
cob (cob32 or cob64) Command
Creating Different Types of Files


Executable File Types

You can create five different types of executable file:

  • Callable shared objects
  • Intermediate code files
  • Generated code files
  • Shared libraries
  • System executable files

Callable shared objects are executable files in an operating system format that are dynamically loaded by the COBOL run-time system provided with Visual COBOL. For information on using these files, see Packaging Applications Using Callable File Formats.

Intermediate code files and generated code files are proprietary executable files that are dynamically loaded by the COBOL run-time system provided with Visual COBOL. For information on using these files, see Packaging Applications Using Callable File Formats.

Shared libraries are system linkable files that can be linked into executable files.

System executable files are files compiled and linked to create executable files in operating system formats.

For information on compiling programs, see Using the Compiler. For information on callable shared objects, see Callable Shared Objects. For information on linking programs, see Linking to System Executables.

The executable file types are described in more detail in the following sections.

Whichever file formats you use, you will need to ship COBOL Server with your application.

Parent topic: Executable File Types - Summary
Related concepts
Packaging Applications Using Callable File Formats
Compiling COBOL code
Callable Shared Objects
Creating Different Types of Files


Creating Applications

As you can see from the sections above, there are many ways to package an application to suit your requirements, using executable files in proprietary and system formats.

Perhaps the best way of packaging an application is, therefore, to create a system executable that is linked with shared libraries and calls callable shared object files:

  • The core, application specific code of your application that needs to be loaded every time the application is run is best packaged in system executable files and shared libraries
  • Other code, such as common submodules, that only need to be loaded and run if and when required, are best packaged in callable shared objects
  • Packaging Applications Using Callable File Formats
  • COBOL Link Option
  • Dynamic Loading
Parent topic: Packaging Applications


Packaging Applications Using Callable File Formats

In many COBOL systems, subprograms and support modules must be linked to your programs by a linker utility after compilation. In Visual COBOL, linking is unnecessary, though it is available as an alternative method (see the section COBOL Link Option later in this chapter for an overview of linking).

Using Visual COBOL you can run callable shared objects, .int files, and .gnt files without linking them into a system executable file. This ability is provided by the COBOL dynamic loader (see the the section Dynamic Loading for more details). Dynamic loading is used to:

  • Load and execute your program
  • Load COBOL subprograms and support modules as your application needs them.

To make use of the dynamic loader, you must compile your program to a callable shared object, intermediate code file, or generated code file; these file formats are known as the callable file formats. For example, the command:

cob -z myprog.cbl

creates the callable shared object myprog.so, while the command:

cob -u myprog.cbl

creates myprog.gnt

Callable shared objects, .int files, and .gnt files do not have to be linked into a system executable file to be able to run. However, they do need to be called by a system executable that has been linked with the COBOL run-time system. Visual COBOL provides a default trigger program, cobrun (and for multi-threading applications, cobrun_t). The diagram below shows how an application could be packaged using the callable file formats and the cobrun trigger.

Figure 1. Trigger Executable
Trigger Executable

See the chapter Running for details on using cobrun and cobrun_t. See your Multi-threaded Programming book for details on multi-threaded programming.

You can create your own system executable file to trigger your application if required. See the chapter Linking to System Executables for details on creating system executable files.

Parent topic: Creating Applications
Related concepts
Running Applications
Dynamic Loading
COBOL Link Option
Multi-threaded Programming
Creating Different Types of Files


COBOL Link Option

The UNIX system provides basic functionality to build and execute programs. Your COBOL system exploits this and provides additional COBOL-specific functionality. The Linker is used to create programs in an operating system executable format.

A linked program is a subprogram that is held in object form in one of the following:

  • Callable shared object
  • System executable
  • Shared library file that is referenced from within one or more system executable files

Any program, subprogram or support routine can be linked into these file types.

The procedural code of the linked file types is shared between multiple concurrent users. The procedural code of callable shared objects and shared libraries is also shared between multiple applications.

To run a COBOL application you must first invoke a standard UNIX system executable file. This is loaded by the system loader and control is passed to the main entry point. The application starts to run and control passes explicitly to called subprograms or implicitly to run-time support routines. See the chapter COBOL System Interface (Cob) for details on how you specify the main entry point.

An executable file that requires the first entry point to be specified at run time is generally known as an executable run-time system (RTS). An executable file that has the first entry point built-in at link time is generally known as an executable application. The default executable RTS is:

  • $COBDIR/bin/rts32 for 32-bit systems or $COBDIR/bin/rts32_t for multi-threaded applications on 32-bit systems
  • $COBDIR/bin/rts64 for 64-bit systems or $COBDIR/bin/rts64_t for multi-threaded applications on 64-bit systems

To link the programs in your application use the Cob utility. Cob can be used to link a program to the various system or language support routines, and, if necessary, to any called subroutines that are needed at run time.

See the chapter Linking to System Executables for more details.

Parent topic: Creating Applications
Related concepts
Creating Different Types of Files
cob (cob32 or cob64) Command


Dynamic Loading

UNIX normally requires the names of all called programs, and the called programs themselves, to be provided at link time. With Visual COBOL, however, you can run programs without first linking them to system executables; these programs are dynamically loadable. The COBOL run-time system provides a dynamic loader that can load and execute dynamically loadable COBOL programs or subprograms.

The types of executable file that can be dynamically loaded are callable shared objects, .int files and .gnt files. Callable shared objects enable any type of program or subprogram (for example, COBOL, C or C++) to be dynamically loaded. For .int and .gnt files only COBOL programs or subprograms can be dynamically loaded. These files do not require linking to a system executable, although they do need a system executable as a trigger; Visual COBOL provides the cobrun program (cobrun_t for multi-threaded applications), which you can use as a trigger (see the chapter Running for details).

Programs and submodules loaded using dynamic loading do not need to be linked to a system executable, which speeds the compile-to-run process, and gives increased run-time flexibility. For example, you can modify and recompile a dynamically loaded submodule without affecting any other part of the application, and without needing to relink a system executable.

The COBOL system enables each call to a program to be either linked directly to the program, if it is available at link time, or to be linked to the dynamic loader. At run time the dynamic loader searches for the named program and, if necessary, dynamically loads it.

The program name can be provided to the dynamic loader as either a literal or as the value of a data item. The dynamic loader searches for the named program in the following places:

  1. The list of linked programs, subprograms and routines in memory. The list also records the states of the programs, subprograms and routines. The states are:
    • Active - The program or routine (which must be recursive) is still on the call-stack
    • Inactive - The program or routine has been called, control has returned to the calling program, but the called program or routine has not been canceled
    • Initialized - The program or routine is in the system executable, a shared library, or a loaded callable shared object, but has yet to be called
    • Logically cancelled - The program or routine has been called and cancelled, but not yet purged from memory (see the -l (lower case "L") run-time switch).
  2. The file system for a dynamically loadable file for the program.

You can use flags to the cob command to explicitly name the programs that you want to be linked and directly referenced and those that you want to be dynamically loaded. Without explicit instructions, cob takes default actions that depend on how the COBOL source calls the program.

  • Default Behavior
  • Dynamically Loadable Files
  • Program Names and Entry Points
  • Flexibility and Performance
Parent topic: Creating Applications
Related concepts
Running Applications


Default Behavior

The statement CALL data-name enables the name of the called subprogram to be specified dynamically at run time and implies dynamic loading. In a CALL statement, an ON EXCEPTION clause specifies the action to take if the subprogram cannot be loaded. Linked programs are not considered able to give an exception, unlike dynamically loaded programs and so the ON EXCEPTION clause implies dynamic loading.

Only the statement CALL literal with no ON EXCEPTION clause, when used in a linked program, does not imply dynamic loading. Instead, a direct reference is used; this is superior to dynamic loading in performance terms.

If a program is invoked in a way that implies dynamic loading, then it is invoked by the COBOL run-time system dynamic loader. The dynamic loader first searches the list of loaded programs, subprograms and support routines before trying to load the program dynamically from disk. If the program is already loaded, by virtue of being linked or previously dynamically loaded without any intervening CANCEL, then the dynamic loader simply passes control to it. If the program is not already loaded, then the dynamic loader searches for a suitable dynamically loadable file. The search order is affected by the environment variable COBPATH. Callable shared objects are also affected by the LIBPATH, SHLIB_PATH or LD_LIBRARY_PATH environment variables.

Parent topic: Dynamic Loading


Dynamically Loadable Files

There are three types of dynamically loadable program: callable shared object files, .int files, and .gnt files. If a program needs to be loaded, then the dynamic loader loads a callable shared object file in preference to a .gnt file, and a .gnt file in preference to an .int file, for any given program. Although you can reference the name, extension and path of a program file in a CALL statement, we recommend that you omit any path or extension and ensure that the basename of any dynamically loadable file corresponds to the program name.

Parent topic: Dynamic Loading


Program Names and Entry Points

The COBOL system recognizes various forms of file for a program and assumes all files for a given program have filenames that share the same basename. This basename is taken to be the program name. The COBOL system uses the program name to identify a program and the dynamic loader also uses it to locate a program. Each program has a main entry point identified with the program name.

The main entry point into a program is the default point where execution of the program starts. This is the first non-declarative statement after the Procedure Division header. The COBOL language lets you specify a program-name in the PROGRAM-ID paragraph. If specified, the program-name represents the name of the main entry point.

The ENTRY statement (see your Language Reference for details) allows additional entry points to be named which represent alternative places for the program to start.

The program is identified by the program name, but once a program is loaded, by linking or dynamic loading, the names of the entry points become available for use by the CALL statement. The CANCEL statement must only reference a program name and when executed causes the program to be unloaded, unless the program is linked into the system executable file. Also see the topic -l run-time switch.

We suggest that, for your convenience, if the PROGRAM-ID paragraph is specified, you make the program-name and the basename of a program source file the same.

Multiple programs can be combined to form a single callable shared object, system executable or shared library. Here the main entry point is the basename of the first program on the command line unless the cob -e flag is specified.

On file systems that support long filenames, filenames for programs that are to be dynamically loadable must be unique in the first 30 characters. This is because filenames longer than the entry point name limit are truncated to that limit when linked or dynamically loaded. Therefore, you are recommended to keep program source filenames below 30 characters long.

Parent topic: Dynamic Loading
Related concepts
COBOL Language Reference
Related reference
l run-time switch


Flexibility and Performance

Accessing a program via the dynamic loader is less efficient than accessing it directly via direct reference, even if the program has been linked into a system executable. If the program needs to be dynamically loaded the program needs to be read off disk. If the program is an .int file or .gnt file all subsequent calls in the program use the dynamic loader, so performance drops still further. However, the dynamic loader does give great build and run-time flexibility.

Dynamic loading of programs is especially suitable in a development environment. This is because it requires no link process, speeding the edit, compile and run cycle. It also gives more flexibility; you can even, while debugging, reload a changed version of a subprogram while the rest of the application remains running.

In environments where the application generally runs with a single user, you might need to use dynamically loaded .int files or .gnt files if the amount of memory available is limited. Dynamic loading provides you with full use of the memory management options provided by the dynamic loader of Visual COBOL, enabling you to control the amount of memory required by your application.

In environments where the application generally runs with multiple users, both memory efficiency and performance generally favor an application consisting of a system executable, linked shared libraries and/or callable shared objects. If the subprograms are very large or very numerous they can be combined into callable shared objects or, if size is more important than performance, packaged as .int files or .gnt files.

Parent topic: Dynamic Loading


Working in 32-bit and 64-bit Modes

The default working mode of Visual COBOL Development Hub is 64-bit.

For UNIX or Linux platforms that support both 32 and 64-bit, you can change the working mode to 32-bit and use Visual COBOL Development Hub to create both 32-bit and 64-bit applications.

You can set the working mode at any time using either the COBMODE environment variable which sets the local working mode or the cobmode command which sets the global working mode.

The working mode is determined using the following rules, listed in order, most significant first

  • The local working mode is used, if $COBMODE is set.
  • The global working mode is used, if it has been set using cobmode -s.
  • Otherwise, the default is 64-bit as stated above.
  • Introduction
  • Finding the Current Working Mode
  • The COBMODE Environment Variable
  • The cobmode Command
  • Starting the Required Tool
  • Determining the Format of an Executable File
  • Shipping Dual-mode Applications
  • Configuration Files
Parent topic: Developing Applications


Introduction

On UNIX platforms that support the execution of both 32-bit and 64-bit applications, Visual COBOL for such platforms is installed with both a 32-bit version and 64-bit version of the COBOL development and run-time systems. This enables you to write programs that can be run on both 32-bit and 64-bit systems, and to migrate applications from 32-bit systems to 64-bit systems.

The development tools, run-time libraries and run-time system for both the 32-bit and 64-bit version of Visual COBOL are located in the $COBDIR directory.

You can specify a working mode for Visual COBOL; that is, whether the default development system is the 32-bit system or the 64-bit system. Whichever working mode you specify, you can always use tools that work in the other mode. For example, if you set Visual COBOL to work in 32-bit mode by default, you can still run 64-bit versions of the tools and utilities.

Parent topic: Working in 32-bit and 64-bit Modes


Finding the Current Working Mode

The working mode can be global or local. The global working mode affects all users of the development system. The local working mode is specific to your local environment.

You can find out your working mode by using the cobmode command as follows:

cobmode

To find your current local working mode, enter the command:

cobmode -l

To find the current global working mode, enter the command:

cobmode -s

If you want to know how your working mode is determined add the -v option to the cobmode command line. For example:

cobmode -v
Parent topic: Working in 32-bit and 64-bit Modes


The COBMODE Environment Variable

Use the COBMODE environment variable to set your local working mode. The value you set using COBMODE overrides the global working mode.

The format of COBMODE is:

COBMODE=version

where version can be 32 or 64. The default working mode is 64-bit.

For example, to set the local working mode to the 32-bit development mode:

COBMODE=32
export COBMODE
Parent topic: Working in 32-bit and 64-bit Modes


The cobmode Command

To set the global working mode use the cobmode command.

The format of the cobmode command used to set the global working mode is:

cobmode -s version

where version can be 32 or 64 .

For example, to set the global working mode to the 64-bit version:

cobmode -s 64
Parent topic: Working in 32-bit and 64-bit Modes


Starting the Required Tool

Both 32-bit and 64-bit versions of the tools and utilities are provided. They are suffixed with either 32 or 64 as appropriate. The tools and utilities are also provided in unnumbered versions. You do not need to alter $PATH, $COBDIR, and $LD_LIBRARY_PATH or $LIBPATH in order to switch between working modes.

For example:

cob32 -i myprog.cbl
cobrun32 myprog

compiles the program myprog.cbl to the 32-bit intermediate code file myprog.int, and then runs it.

cob64 -i myprog.cbl
cobrun64 myprog

compiles the program myprog.cbl to the 64-bit intermediate code file myprog.int, and then runs it.

For development tools (such as the cob utility), the unnumbered versions always obey the current working mode.

For cobrun and anim (the trigger for Animator), the unnumbered versions locate the application named on the command line and automatically run it in the correct mode. If the named application cannot be located, these tools obey the current working mode.

For example:

cobrun64 myapp.int

runs myapp.int in 64-bit mode. If myapp.int is a 32-bit application then a run-time error occurs.

cobrun myapp.int

runs myapp.int in either 32-bit or 64-bit mode, as appropriate, depending on which mode myapp.int was compiled to.

anim myapp

runs Animator, using myapp, in either 32-bit or 64-bit mode, as appropriate, depending on which mode myapp.int was compiled to.

These examples are true for .int files, .gnt files and callable shared objects. However, system executable files are run in the same way for both 32-bit and 64-bit modes. For example, you can create and run 32-bit and 64-bit system executable files from the program myprog.cbl as follows:

cob32 -x myprog.cbl
./myprog
cob64 -x myprog.cbl
./myprog
Parent topic: Working in 32-bit and 64-bit Modes


Determining the Format of an Executable File

Both operating system executable files and Micro Focus executable files are held in different formats depending on whether they are 32-bit or 64-bit files. You can use the same commands to run and debug 32-bit and 64-bit executable files, since the commands can identify which format they are dealing with. However, there might be times when you need to find out what format an executable file is in.

  • Operating System Executable Files
  • Micro Focus Executable Files
Parent topic: Working in 32-bit and 64-bit Modes


Operating System Executable Files

To determine the format of an operating system executable file, such as an object file (.o file) or a shared object file (.so file), use the UNIX file command. For example:

file myobj.o

displays one of the following on a Solaris SPARC machine

myobj.o:   ELF 32-bit MSB relocatable SPARC version 1
myobj.o:   ELF 64-bit MSB relocatable SPARCV9 version 1
Parent topic: Determining the Format of an Executable File


Micro Focus Executable Files

To determine the format of a Micro Focus executable file, use the cobfile command. This command checks for intermediate code files (.int files), generated code files (.gnt files) Animator information files (.idy files) produced on Visual COBOL (32-bit and 64-bit) and OCDS Version 4.1 and later.

The cobfile command takes the following format:

cobfile file [file] ...

where file is the filename of a Micro Focus executable file.

For example:

cobfile myprog.int

displays one of the following:

myprog.int: Micro Focus 32-bit intermediate code file
myprog.int: Micro Focus 64-bit intermediate code file

If you supply more than one file parameter to the cobfile command, the command displays a list of results in the same order as the parameters, with one line per file.

If the cobfile command does not recognise a a filename supplied in a file parameter as a Micro Focus format file it passes the parameter to the UNIX file command.

Parent topic: Determining the Format of an Executable File


Shipping Dual-mode Applications

If you ship an application that contains both 32-bit and 64-bit versions of your programs, you can either:

  • Store the 32-bit programs and the 64-bit programs in separate directories, and specify both directories to the COBPATH environment variable. You then need to specify cobrun32 or cobrun64, as appropriate, to run the required version of your program.
  • Use different filenames for the system executable files for the 32-bit and 64-bit versions of your programs. For example, to create a version of myprog.cbl to run in 32-bit mode:
    cob32 -xo myprog myprog.cbl

    You can then run the program by entering:

    ./myprog

    To create a version of myprog.cbl to run in 64-bit mode:

    cob64 -xo myprog64 myprog.cbl

    You can then run the program by entering:

    ./myprog64
Parent topic: Working in 32-bit and 64-bit Modes


Configuration Files

You can configure various utilities, and the run-time system, using configuration files.

Configuration files that effect the run-time system, such as cobconfig, have no suffix whatever version of Visual COBOL you are using. In this case, the settings are shared between the 32-bit and 64-bit versions.

Parent topic: Working in 32-bit and 64-bit Modes


Creating Programs

  • Introduction
  • Creating Intermediate Code Files
  • Creating Generated Code Files
  • Creating Callable Shared Objects
  • Creating System Executable Files
  • Creating Shared Library Files
  • Using Compiler Directives
  • For More Information
Parent topic: Developing Applications


Introduction

You can create the following types of executable files as described in Executable File Types in the chapter Packaging Applications:

  • Callable shared objects
  • Generated code files
  • Intermediate code files
  • Shared library files
  • System executable files

To create an executable file you need to use the Cob utility. Cob invokes the Compiler and/or the system linker for you, depending on the specified output executable file.

The Compiler compiles a program in two phases:

  • The first phase checks the syntax of your COBOL source code. It is during this phase that intermediate code is created.
  • The second phase generates either native object code or generated code. The type of code generated is specified by you.

The system linker converts native object code into a callable shared object, system executable or shared library file.

Cob can take source code, intermediate code or native object code as input. It can also take C or C++ source code as input for certain executable file types. The steps Cob takes to create the various types of executable file are shown in the following diagram:

The sections below give you general information on compiling programs using the Cob utility. For information on using the Cob utility see COBOL System Interface (Cob). If you are working in 64-bit mode, you should also see Working in 32-bit and 64-bit Modes.

Parent topic: Creating Programs
Related reference
Working in 32-bit and 64-bit Modes


Creating Intermediate Code Files

These files are independent of both the chip-set and operating system, and are thus highly portable to other platforms. They cannot be shared between processes; if two different executables call, at the same time, a subprogram compiled to intermediate code, a separate copy of that subprogram is loaded into each process's virtual memory space, and run.

Intermediate code files are dynamically loaded and interpreted by the run-time system. Because the intermediate code is interpreted by the run-time system, intermediate code files generally execute slower than other executable file formats.

You can create an intermediate code file using the Compiler directly. There is no need to link the program. However, to run the program you need to do one of the following:

  • Run the program using the cobrun program (or cobrun_t for multi-threaded applications)
  • Create a system executable file that calls the program

You can compile the source code file myprog.cbl to intermediate code as follows:

cob myprog.cbl

or

cob -i myprog.cbl

This creates an intermediate code file called myprog.int.

The command:

cob -a myprog.cbl

also creates an intermediate code file, along with files for use by Animator.

Parent topic: Creating Programs
Parent topic: Creating Different Types of Files


Creating Generated Code Files

Generated files are portable to the same chip-set, but are operating system dependent. Generated code files cannot be shared between processes; if two different programs call, at the same time, a subprogram compiled to generated code, a separate copy of that subprogram is loaded into each process's virtual memory space, and run.

You create a generated code file using the Compiler. There is no need to link the program. However, to run the program you need to do one of the following:

  • Run the program using the cobrun program (or cobrun_t for multi-threaded applications)
  • Create a system executable file that calls the program

You can compile the source code file myprog.cbl to generated code as follows:

cob -ug myprog.cbl

This creates a generated code file called myprog.gnt, and Animator information files.

You can also create a .gnt file from an .int file using:

cob -ug myprog.int

The -g option produces files for use by Animator.

Parent topic: Creating Programs
Parent topic: Creating Different Types of Files


Creating Callable Shared Objects

Creating a callable shared object involves two steps:

  • Creating native object code
  • Linking the file containing the native object code to create a callable shared object

Both steps are done using Cob.

To run the program you need to do one of the following:

  • Run the program using the cobrun program (or cobrun_t for multi-threaded applications)
  • Create a system executable file that calls the program

For more details see Packaging Applications.

You can compile the source code file myprog.cbl to a callable shared object as follows:

cob -z myprog.cbl

This creates a callable shared object called myprog.so.

The command:

cob -zg myprog.cbl

creates a callable shared object, and files for use by Animator.

You can also create callable shared objects from .int files and native object code files (.o) files using:

cob -z myprog.int

or:

cob -z myprog.o

See Callable Shared Objects for more information.

Parent topic: Creating Programs


Creating System Executable Files

Creating a system executable file involves two steps:

  • Creating native object code
  • Linking the file containing the native object code file to create a system executable file

Both steps are done using Cob.

For example, if the file myprog.cbl contains the source program, you can compile and link the program to a system executable file in one step, as follows:

cob -xg myprog.cbl

This creates a system executable file called myprog.

The -g option produces files for use by Animator.

Parent topic: Creating Programs


Creating Shared Library Files

Creating a shared library file involves two steps:

  • Creating native object code
  • Linking the file containing the native object code file to create a shared library file

Both steps are done using Cob.

For example, if the file myprog.cbl contains the code you want to create as a shared library you can compile and link the program to a shared library file in one step, as follows:

cob -Zg myprog.cbl

The -Z option creates a shared library file called libmyprog.so.

The -g option produces files for use by Animator.

A shared library file is not executable itself. It must be linked into a system executable using the -l flag on the Cob command line. For example:

cob -x myapp.o -L. -lmyprog

creates a system executable myapp that loads libmyprog.so when it is run.

Parent topic: Creating Programs


Using Compiler Directives

Many options are available for controlling the way your program is compiled. These options are specified using directives when you invoke the Compiler. You can enter Compiler directives individually on the command line, or you can create default directives which are then invoked as a group either automatically, or from the command line, or from within the source code.

For normal operation you need to know about and use very few directives. In the majority of cases you will use the default values.

Parent topic: Creating Programs
Related reference
Compiler Directives


For More Information

For more information on compiling and linking programs, see the following chapters in this manual :

  • Using the Compiler - invoking the Compiler, and setting directives
  • Linking to System Executables - linking programs to shared libraries and system executables
  • Callable Shared Objects - creating and using callable shared objects
  • COBOL System Interface (Cob) - the Cob utility
  • Working in 32-bit and 64-bit Modes - if you have installed the 64-bit version of the development system.

For information on Compiler directives, see Compiler directives.

Parent topic: Creating Programs
Related reference
Compiling COBOL code
Compiler Directives
Callable Shared Object Files
cob (cob32 or cob64) Command
Linking
Working in 32-bit and 64-bit Modes


Building applications

To build an application, you need to compile its programs and link them to a run-time system.

Building native COBOL applications

When building native COBOL applications, the Compiler first checks the program for syntax errors. Then, it generates native machine code. Finally, the linker links the native machine code into an executable (either an .exe or a .dll).

  1. The check phase - the Compiler checks the program's syntax and creates files to use for testing and debugging. The check phase creates a dictionary file for use with the Debugger and, if you are building an INT/GNT project or have set the project output type to INT/GNT, it can produce an .int file.
  2. The generate phase - during the generate phase, the Compiler creates native machine code from the intermediate code produced during the check phase, and produces either an industry-standard .obj file or, if you are building an INT/GNT project or have set the project output type to INT/GNT, it can produce a Micro Focus .gnt file.

    You can execute .int and .gnt code directly with the run-time system. You cannot execute the object code file. You must link it with the appropriate run-time system to create an executable file.

  3. The linking phase - during the link phase, the code is linked to the run-time system and creates an executable file - an .exe, .dll or .so.

Building managed COBOL applications

When building JVM COBOL applications, the Compiler compiles your code to Java byte code (.class) which is then executed on a Java Virtual Machine (JVM).

  • Compiling COBOL Applications
  • Linking
  • How To in the IDE
Parent topic: Developing Applications


Compiling COBOL Applications

Before you can run a program, you have to compile the source code.

  • Compiling COBOL code
  • Executable File Formats
  • Compiling JVM COBOL
  • Setting Compiler Directives for COBOL
  • Order in Which Copybooks are Searched For
  • Temporary Files Used when Compiling Native COBOL
  • Techniques for Compiling Quickly
Parent topic: Building applications
Related information
Command line reference
Setting Directives
Compiling and Linking from the Command Line


Compiling COBOL code

Before you can run a program, you have to compile the source code.

You can configure the compilation using the following techniques:

  • Compiler directives. You can control the way programs are compiled by using Compiler directives.

    You use directives to control the way the Compiler behaves. Normally, you need only a few directives. Most of the time, you use the default values. Note that setting some directives affects the default setting of other directives. For example, setting one directive might automatically unset another directive, and some directive settings are mutually exclusive.

  • 32- and 64-bit compilation. You can also compile bit-specific output from the command line by using the cob32, cob64 or cobol (in conjunction with the COBMODE environment variable) commands.
  • Linked resources. Linked resources enable you to link to sources that are outside the project, thereby saving you from copying the sources into the project, and enabling to share resources with others.
  • Copybook locations. You can specify the location of the copybooks that your program refers to, if you keep them in different directories from the program. You can do this through the COBCPY environment variable.
  • Temporary files used during compilation. Before compiling, you must ensure there is enough free space for the Compiler's temporary work files. You can specify the location where the Compiler puts its temporary files.
  • Techniques for compiling quickly. Large applications comprising many programs can take significant time to compile. You can use various techniques to increase the speed of compilation.

The Compiler records errors with severity levels ranging from information messages to fatal errors which stop the Compiler working.

If the source code to be compiled contains characters beyond the standard 7-bit ASCII character set (for example, accented characters or characters belonging to multi-byte character sets), you must ensure that the locale has been set correctly, to match the source encoding of these characters. On UNIX, this means setting LANG, LC_CTYPE, or LC_ALL appropriately; each of these variables takes precedence over the former.

When you compile, the Compiler can produce executable code directly or object code. Object code is not executable, and has to be linked to the run-time system to create an executable file. If your project is set to build to .int and .gnt, by default the Compiler produces .int code during its syntax checking phase, and then it can produce .gnt code during the generating phase. You can modify this behavior from the project or the file properties.

Compiling from the command line

Using the command line, you can compile and link your program in one step using the cob command.

You can either specify all the information required on the command line, or use the Compiler prompts.

See Command line reference for more information.

Parent topic: Compiling COBOL Applications
Related reference
cob Command
Command line reference


Executable File Formats

You must compile your program to an executable before it can be run or debugged. This topic summarizes the different types of executable file that the Micro Focus COBOL Compiler can produce. It also gives recommendations to help you choose which file format is most appropriate for your applications and summarizes how you can simply packaging by bundling intermediate and generate code files into Micro Focus library files.

.NET COBOL code
.NET COBOL compiles to Common Intermediate Language which can be executed under the Common Language Runtime (CLR) on Windows and Linux systems.

The Compiler supports the generation of procedural COBOL code to .NET assemblies and also offers object-oriented extensions to the COBOL language.

JVM COBOL code
JVM COBOL compiles to Java bytecode (.class files) which can run under the Java Virtual Machine.

The Compiler the supports generation of procedural COBOL code to Java .class files and also offers object-oriented extensions to the COBOL language.

Executable code
You produce executable code by compiling and linking in one step.

An executable file has no filename extension.

Object code
The object code file is not executable. It requires linking with the run-time system to produce an executable file.

By default, object code files have the extension .o.

Object code files must be linked to create executable, callable shared object or shared library files.

Intermediate code
Intermediate code files have the extension .int and are usually used for testing and debugging. The Compiler creates the intermediate code file during its first phase, when it checks the program syntax. Intermediate code files compile quickly.

.int files are dynamically loadable, and don't need to be linked into a system executable. You can ship them to your users as executable files, but we recommend that you use .exe files and .dll files for this.

Generated code
Generated code files have the extension .gnt and are created by the Compiler, on request, during its second phase. Generated code is slower to compile than intermediate code but the resulting code runs faster.

.gnt files are dynamically loadable, and don't need to be linked into a system executable. You can ship them to your users as executable files, but we recommend that you use .exe files and .dll files for this.

Dynamic Link Libraries or Callable shared objects
Dynamic link libraries or callable shared objects are dynamically loaded at run time when required; that is, when referenced as a main entry point (for example, by run or cobrun ) or by the COBOL CALL syntax. When all the entry points in a dynamic link library or a callable shared object have been canceled then the file is unloaded, releasing any memory used.

This behavior is similar to .int and .gnt code but is different to linked shared libraries and system executables, which are always loaded at process start-up, whether they are used or not. Further, the code and memory used by shared libraries and system executables are only unloaded when the process terminates.

A dynamic link library or a callable shared object can contain more than one COBOL program and can also contain other language programs, such as C and C++. Dynamic link libraries or callable shared objects can also be linked with third party object files or shared libraries. This behavior is similar to system executables and shared libraries but differs from .int and .gnt files, where each file corresponds to a single COBOL program.

A callable shared object file has a filename extension of .so.

Recommendations

This section contains general guidance and recommendations about when to use each of the different file formats.

.int files have the advantage of being portable across different hardware platforms. They have the disadvantage of not being optimized for any target architecture and will typically execute more slowly than code that has been generated for a specific platform.

.gnt files are optimized for a specific chipset. They typically execute faster than .int code. Micro Focus recommends the use of generated executables for best application performance.

.gnt files are not locked by the operating system while executing. This means that new files can be overlaid, but this is not considered good practice.

Standard executable formats, such as .dll or .exe, are also optimized for the target platform and can be digitally signed. These formats can also contain more than one program.

Micro Focus recommends the use of standard format executables.

Bundling intermediate or generated code files

You can bundle .int files and .gnt files in Micro Focus library files. The advantages of this are:

  • It simplifies the packaging of files for users, as it reduces the number of files to be shipped.
  • When your program calls a subprogram stored in a library file, the library file and all the programs loaded in it are loaded into memory. This can make program execution faster.

A library file has the file extension .lbr.

For example, given the following programs in our application:
Figure 1. Programs in application
Programs in application

ProgC and ProgD could be compiled as generated code files, and then placed in a library file, mylib.lbr. When ProgA calls ProgC, mylib.lbr would be loaded into memory, also loading progc.gnt and progd.gnt. You would need to ship proga.gnt, progb.gnt, and mylib.lbr, as well as a trigger program.

To package the .int and .gnt files into an .lbr file, set the following properties:

Restriction: You cannot compile .lbr files for JVM projects.
Parent topic: Compiling COBOL Applications
Related concepts
Native COBOL compared with managed COBOL
Procedural COBOL Compared with Managed COBOL


Compiling JVM COBOL

You compile JVM COBOL programs from the same command line which you used to set up the environment in Visual COBOL Development Hub.

If your application references external .class or .jars, these files must be added to the CLASSPATH environment variable in order for your code to compile and run.

Note: When compiling JVM COBOL on a remote machine, you must ensure that the version of Java being used on the remote machine has the same bitism as the project being compiled.
Parent topic: Compiling COBOL Applications
Related reference
Compile to JVM byte code
ILDYNCALL


Setting Compiler Directives for COBOL

You can use directives to control the way the Compiler behaves: what output it produces, what code is compiled and how the compiled code behaves when it runs. For normal operation you need only a few directives. Most of the time, you use the default values.

Important: Setting some directives affects the default setting of other directives. For example, setting one directive might automatically unset another directive, and some directive settings are mutually exclusive.

In addition, you can set Compiler directives in a number of other ways, such as on the command line, or in a directives file, or as part of a response to a prompt.

Separate Compiler directives with a space. You can supply parameters either within brackets or quotation marks: for example charset"ascii" dialect(MF), and if you need more than one parameter for a particular directive, separate the parameters with a space: for example outdd(sysout 121 r e) or ACTUAL-PARAMS"MyInterface ClassA ClassB".

  • Setting Compiler Directives from the Command Line
  • Setting Compiler Directives in Source Code
  • Setting Compiler Directives in a Directives File
Parent topic: Compiling COBOL Applications
Related information
Compiler Directives
Setting Directives


Setting Compiler Directives from the Command Line

When you compile from the command line using the cob command, you include any directives as part of the command.

Parent topic: Setting Compiler Directives for COBOL


Setting Compiler Directives in Source Code

You can use $SET statements in source code to set directives when your program is affected by particular circumstances that none of the other programs in an application needs. For example:

$SET OSVS NOFORM CHECKDIV"OSVS"
Parent topic: Setting Compiler Directives for COBOL


Setting Compiler Directives in a Directives File

Using a directives file with one or more projects

You can use a text file, external to your project, to pass Compile directives during the build process.

This can be especially helpful when you need to compile multiple projects with the same directives as you only need to configure the projects to use the directives file:

  1. Place the directives that you want to apply to all your project in a single text file, directivesfile, on your file system.
  2. Then, configure the project's properties of each project that you need to compile with these directives as follows:

Overriding the default product behavior

CAUTION:
The following affects all compilation done on the system and using or editing a system-wide directives file can result in unexpected behavior.

Place the directive that you want to override in the system-wide directives file, cobol.dir. Make sure that the file is in folder in a directory specified by the COBDIR environment variable. By default cobol.dir is in the $COBDIR\etc folder.

Parent topic: Setting Compiler Directives for COBOL
Related concepts
System-wide Directives File
User Directives File
Order in which Compiler Directives Are Processed


Order in Which Copybooks are Searched For

By default, the Compiler looks for copybooks in the same directory as the program using them. If your copybooks are elsewhere, you need to define their location.

Each COPY statement in your program identifies a copybook to be copied. If the filename in the COPY statement is incomplete, because it lacks either an extension or a path, the Compiler searches for it as follows:

  1. In the directory given by the COPY library-name. Note that if the name of the copybook is a qualified filename, that is, it includes the path or directory, the Compiler searches that directory only.
  2. In the directory containing the main source program being compiled.
  3. In any directories listed in the COBCPY environment variable, in the order specified.

If the COPY statement does not give the extension of the copybook's filename, the Compiler searches for files with extensions given by the directive COPYEXT.

Parent topic: Compiling COBOL Applications


Temporary Files Used when Compiling Native COBOL

Note: The following information applies to native code only.

The Compiler creates a number of temporary work files. The size of them depends on the content of your program and the directives used, in particular the number of data and procedure names. The Compiler puts the files in the directory indicated by the environment variable. If this environment variable does not exist, the files are created in a system defined temporary directory, typically /var/tmp or /tmp.

The Compiler normally deletes these temporary files before it terminates. However if the Compiler terminates abnormally, for example due to machine failure, it might leave these files on disk. You can delete them, unless the Compiler is running in another session.

Before compiling, you must ensure there is enough free space for these temporary files in the appropriate directory.

Parent topic: Compiling COBOL Applications


Techniques for Compiling Quickly

Note: The following information applies to native code only.

A large application can consists of many programs; compiling all of these might take some time. To speed up the compilation process, use the following Compiler directives:

  • NOALTER. If your code does not have any ALTER statements, you can disable the ALTER default directive and produce slightly more efficient code and produce it more quickly.
  • NOCOPYLIST. If you are using the LIST directive to create a listing file, you can disable the COPYLIST default directive and prevent the Compiler from expanding the copybooks and include files in the listing. Note that compilation is quicker still if you do not create a listing.
  • NOLIST. This is the default. Compiling is quicker if you accept this default and do not produce a listing file.
  • NOQUAL. If your code does not use qualified data names, you can disable the QUAL default directive to compile more quickly. An example qualified data name is:
    elementary-item-a  of  group-item-1
Parent topic: Compiling COBOL Applications
Related reference
COPYLIST
ALTER
LIST
QUAL


Linking

  • Introduction to Linking
  • Linking and Linked File Types
  • Linking and Binding
  • Dynamic Loading
Parent topic: Building applications


Introduction to Linking

The system linker converts native object code into a callable shared object, system executable or shared library file.

The linker can take source code, intermediate code or native object code as input. It can also take C or C++ source code as input for certain executable file types, as shown in the following diagram.

Parent topic: Linking


Linking and Linked File Types

The Compiler can create a program as an individual, unlinked object ( .o) file. This type of file is incomplete and cannot be directly executed. To create a file that can be executed, you link the compiled program to the various system or language support routines, and, if necessary, to any called subroutines that are needed at run time.

To link the programs in your application, you use the cob command, which can produce executable files of the following types:

Intermediate code

.int files are dynamically loadable, and don't need to be linked into a system executable.

Generated code

.gnt files are dynamically loadable, and don't need to be linked into a system executable.

Callable shared object files
These files are dynamically loadable, and don't need to be linked into a system executable.
Shared library files
These are system linkable files that can be linked into executable files. They cannot be directly executed themselves.
System executable files
These files are directly executable. They are loaded by the operating system, which creates a new process in which to run them.

Any program, subprogram or support routine can be linked into these file types.

The procedural code of the linked file types is shared between multiple concurrent users. The procedural code of callable shared objects and shared libraries is also shared between multiple applications.

Parent topic: Linking
Related information
Introduction to the cob command


Linking and Binding

A shared library can be linked into one or more system executables. When the system executables are executed the system loader loads one copy of the shared library, shares the code area and creates separate data areas for each executable. The shared library remains loaded until the system executable process terminates. A shared library file has a prefix of lib and filename extension of .so.

Callable shared objects are different from shared libraries, but have the same filename extension .so. Callable shared objects are a callable file format, which means that they are dynamically loaded and unloaded at run-time, if and when required. Shared libraries can be linked into callable shared objects.

Binding of a program or subprogram is carried out by the system loader at run time. If the executable file contains a reference to an external procedure (subprogram or even a main program) in a shared library file, the system loader ensures that the procedure is made available for execution. The system loader ensures that, however many concurrent users or applications are bound to that procedure, they all share a single copy in memory of the dynamically-bound procedure.

Linking of a procedure is carried out by the system linker at link time. The linker does not include the code for a linked procedure in the system executable file, but does include a reference to the shared library file that contains the procedure's object code.

Parent topic: Linking


Dynamic Loading

You can run programs or subprograms without linking them, by creating them as dynamically loadable.

The COBOL system enables each call to a program to be either linked directly to the program, if it is available at link time, or to be linked to the dynamic loader. At run time the dynamic loader searches for the named program and, if necessary, dynamically loads it.

Dynamically loadable executable files are callable shared objects, .int files or .gnt files. Callable shared objects enable any type of program or subprogram (for example, COBOL, C or C++) to be dynamically loaded. For .int and .gnt files, only COBOL programs or subprograms can be dynamically loaded.

Dynamically loadable files do not require linking, but they do need a system executable as a trigger, which is cobrun (or cobrun_t for multi-threaded applications).

The program name can be provided to the dynamic loader as either a literal or as the value of a data item. The dynamic loader searches for the named program in the following places:

  1. The list of linked programs, subprograms and routines in memory.
  2. The file system for a dynamically loadable file for the program.

You can use flags to the cob command to explicitly name the programs that you want to be linked and directly referenced and those that you want to be dynamically loaded. Without explicit instructions, cob takes default actions that depend on how the COBOL source calls the program.

Parent topic: Linking
Related concepts
Creating Executables that Use the Dynamic Loader


How To in the IDE

Parent topic: Building applications


Debugging Applications

Debugging native COBOL programs

You use the Character Animator to watch how your native COBOL code is executing. You can execute your program in one of three modes:

  • Step mode - when you execute your program in Step mode, you manually control the execution of each statement.
  • Go mode - you initially set the speed of execution, then in Go mode, watch as each statement is automatically executed.
  • Zoom mode - in Zoom mode, the entire program is executed without displaying the source until it reaches the end of the program. You can interrupt it, or set a breakpoint where it will stop.

If you are using Development Hub in connection with Visual COBOL for Eclipse, you can debug native programs running on your UNIX or Linux box remotely using the Eclipse IDE installed locally on a Windows or UNIX machine.

Debugging managed COBOL programs

Development Hub does not contain a facility for debugging JVM COBOL applications. You can debug these if you have Visual COBOL for Eclipse installed on a separate machine.

See the Visual COBOL product help for more details on how to set up a remote connection and debug your applications on the remote box.

  • Character Animator and Application Development
  • Preparing for Animation
  • Debugging Methods
  • Using Character Animator
Parent topic: Developing Applications


Character Animator and Application Development

Character Animator enables you to debug applications during the various stages of the application development cycle. You can debug:

  • Single-threaded and multi-threaded applications
  • Intermediate code (.int files), generated code (.gnt files), callable shared objects (.so files) and system executable code
  • Live applications

By default, when you syntax-check a program, an information file is created. This file has the extension .idy (and is usually referred to as the .idy file); it contains essential information required by Character Animator.

You can debug programs and applications using the following methods:

  • Standard debugging

    Character Animator can be used to debug your COBOL programs as part of the normal development cycle.

  • Just-in-time debugging

    Enables an application to drop into debugging mode when a run-time error (for example, an "RTS173 File Not Found") occurs. Normally, when encountering a run-time error, you would see the error message, and then the application would end. However, with just-in-time debugging, you can debug the program in-line when an error occurs.

    If you have the source files and the .idy files, the source code is animated at the line where the error occurred. If you do not have the required files, you are given the name of the source file or program where the error occurred.

  • Unsolicited dynamic attachment

    Enables you to dynamically attach Character Animator to a process; you can thus debug an application that is already running. This can be particularly useful for larger applications where debugging from the very start might be difficult or time-consuming. You need to have the source files and the .idy files available to debug using this method.

  • Core dump debugging

    Enables you to debug applications that have generated a core dump. You can use the resulting core file in Character Animator to display a snapshot of the application's state when the core dump occurred. You cannot execute the core file, so cannot perform operations such as stepping through the application, but you can examine data items and view the CALL/PERFORM stack.

    You can perform a core dump even when you don't have any COBOL development tools installed. This is valuable if you need to debug a released application in a production environment. Just as with just-in-time debugging, you must have the source files and the .idy files to view the core file. If you do not have the required source files, you are only given the name of the source file or program where the error occurred.

  • Mixed-language debugging

    Enables you to debug mixed-language applications using Character Animator. When program flow moves from a COBOL program to a C sub-program, the system debugger can be invoked.

  • CBL_DEBUGBREAK

    Enables Character Animator to start when a particular point in a program has been reached. Applications often behave differently to how you expect; such problems might be deep in the code and at a distant point in program execution. By using CBL_DEBUGBREAK, you can start debugging at a specific program execution point.

Parent topic: Debugging Applications


Preparing for Animation

Before you use Character Animator, you must compile your source code, including all called programs; see Compiling for Animation. You can animate source files containing lines longer than 80 characters, provided that you compiled your program with the SOURCEFORMAT"FREE" directive. However, you should be aware that while Character Animator does tolerate free-format source code, it does not scroll beyond the normal COBOL margins, so results can be unpredictable.

You can use Character Animator to debug files in any executable format. The following sections show how to prepare your environment for animation, and how to use the cob utility to create an executable file ready for animation.

By default, compilation includes the creation of an information file (.idy file), which is essential to debugging. This file is portable, enabling you to debug your application using remote development environments. If you port the .idy file, you must port its associated .int file; you cannot port an .idy file with any other type of executable file for debugging in another environment.

Note:

If the system is unable to write to an .idy file upon compilation, you could receive the following error:

I-O Error: IDY file (fatal)

Ensure that sufficient disk space is available, and remove any LOCK or READ ONLY attributes that your file contains, and recompile your program.

  • Preparing the Environment
  • Compiling for Animation
Parent topic: Debugging Applications
Related information
cob Flags


Preparing the Environment

Before you invoke Animator, set the environment variable TERM to the appropriate value for your terminal.

To enable Animator to search for the required source files and information files in directories other than the current working directory, you must set the following environment variables depending the type of files you need to locate:

  • COBAIF - specifies the search path for Animator session files (.aif files).
  • COBCPY - specifies the search path for COBOL copy files.
  • COBDATA - specifies the search path for data files. If you have set this variable, make sure that the path to the file check.lbr is included in the list of paths.
  • COBIDY - specifies the search path for debug information files (.idy files).
  • COBPATH - specifies the search path for dynamically loadable .int and .gnt files, or callable shared objects.

See Environment Variables for more details on how to set any of these variables.

You can also use the COBANIMOPT environment variable to specify Compiler directives in effect during animation.

  • The .aif File and Character Animator
  • Specifying Screen Size for Screen-swapping
  • Screen Borders on aixterm
Parent topic: Preparing for Animation
Related information
Compiling for Animation
Using COBANIMOPT


The .aif File and Character Animator

Character Animator can keep a record of the breakpoints you set, so that when you next load the program into Character Animator, breakpoints remain in the same state as when you set them in the previous Character Animator session. This information is kept in the session information file, which has the file extension .aif. Session information files are usually referred to as .aif files.

You specify whether or not Character Animator is to save and load .aif files using the COBAIF Animator directive; by default COBAIF is set on.

.aif files are loaded or saved by Character Animator if you:

  • Start Character Animator using the anim or anim_t command. In this case, you can specify the directory in which Character Animator searches for or creates the .aif file using the $COBAIF environment variable.
  • Run a program using COBSW=+A, so that it runs under the control of Character Animator. In this case you must specify the basename of the .aif file using the $COBAIFNAME environment variable.

You can also specify $COBAIFNAME if you are starting Character Animator using the command anim; in this case the basename you specify overrides the application name as the basename of the .aif file. You must still specify the COBAIF Animator directive.

Parent topic: Preparing the Environment


Specifying Screen Size for Screen-swapping

When Character Animator executes a program, the program might need to use the terminal for input and output. If you only have access to a single terminal, and both Character Animator and the executing program need access to it, Character Animator keeps a virtual image of the program's output in the background. This image is displayed, and Character Animator swapped to the background, when you press F2=View, or if Character Animator itself displays the program's output (during Step or Zoom operations, for example).

By default, the size of this virtual screen is set to 24 lines. You can change this by setting the environment variable LINES before starting Character Animator; for example:

export LINES=40
anim program.int

You should not set LINES to a size greater than the actual depth of the screen.

For detailed information on environment variables, see Environment Variables.

Parent topic: Preparing the Environment


Screen Borders on aixterm

On AIX systems, aixterm terminals have an inner border between the window border and the text. The color of the inner border is always the same as the current background color. When you are using Animator, the background color can change depending on the current function, such as querying a data item; in this case, the color of the terminal border also changes. If you find this distracting, and want to prevent it happening, you are advised to remove the inner border. You can do this by setting the border's size to zero in your .Xdefaults file:

aixterm*internalBorder:0
Parent topic: Preparing the Environment


Compiling for Animation

By default, the COBOL system uses the -a cob flag to compile your source files ready for animation, producing an .int file and .idy file.

Intermediate code

To compile to intermediate code:

cob prog-name.cbl

Generated code

To compile to generated code:

cob -ug prog-name.cbl
Note: The code optimizations that occur when .gnt files are produced create the following restrictions on Character Animator behavior:
  • When you are stepping through a program compiled to .gnt code, you have to press Step twice to step a line of code with a breakpoint set.
  • When doing Step Perform on an inline PERFORM statement which is the last statement in a paragraph, and where control falls into the next paragraph, Character Animator might skip the first statement of the next paragraph, although the code is correctly executed.

Callable shared objects

To compile to a callable shared object:

cob -zg prog-name.cbl

System executables

To compile to a system executable:

cob -xg prog-name.cbl
Parent topic: Preparing for Animation
Related information
Preparing the Environment
cob Flags


Debugging Methods

The following sections cover the different types of debugging techniques:

  • Command Line Debugging
  • Just-in-time Debugging
  • Core Dump Debugging
  • Unsolicited Dynamic Attachment Debugging
  • Using the Debugging Library Routines
  • Preprocessor Debugging
  • Multi-threaded Program Debugging
  • CGI Program Debugging
  • Cross-session Debugging
  • Using cobesdebug to Debug Services and Applications on Enterprise Server
  • Debugging Enterprise Server Services and Applications Using a Live Recording
Parent topic: Debugging Applications


Command Line Debugging

Note: Any program that you attempt to debug must be compiled for debugging first, which results in an information file (.idy file) being present; see Compiling for Animation.

You can debug a program directly from the command line by invoking Character Animator using one of the following methods:

  • Debug in the same terminal window in which Character Animator was invoked.
  • Debug in a different terminal window to the one in which Character Animator was invoked.
  • Start Character Animator in sleep mode, so that is lies dormant, waiting for a process to attach to.

With each of these methods, you can specify directives, which affect the behavior of the Character Animator when it is running.

  • Starting Character Animator at Your Terminal
  • Starting Character Animator in a Different Window
  • Starting Character Animator In Sleep Mode
  • Specifying Character Animator Directives
Parent topic: Debugging Methods
Related reference
Compiling for Animation


Starting Character Animator at Your Terminal

To invoke Character Animator in the current window use the anim command.

anim [switchparams] program-name [directives]

or:

anim_t [switchparams] program-name [directives]

Use anim_t if your program is multi-threaded. The parameters are:

switchparams | A set of switches. Each switch must be preceded by a plus sign (+) to turn it on, or a minus sign (-) to turn it off. Switches can be set in any order. The last setting of a switch specified multiple times is the one that is accepted. See Descriptions of Run-time Switches for details on the switches available.
program-name | The name of the file you want to animate. If you do not specify a path, the current directory is assumed. If you do not specify an extension, a callable shared object is first searched for, followed by .gnt , .int, then .lbr files.
directives | An optional sequence of one or more Character Animator directives. Each directive must be separated by at least one space and must not be broken across lines. See the chapter Specifying Character Animator Directives for details on the directives available.
Parent topic: Command Line Debugging
Related information
Starting Character Animator in a Different Window
Starting Character Animator In Sleep Mode
Specifying Character Animator Directives


Starting Character Animator in a Different Window

You can start Character Animator in a different terminal window, if the machine you're debugging on has X windows. This is especially useful for debugging threaded applications.

First, you must ensure that the DISPLAY operating system environment variable is set:

export DISPLAY=local_machine_name:0.0

Then, if you are debugging on a different machine, ensure that the remote machine is allowed to start X clients on the local machine (using the xhost command). Then use the cobanim command:

cobanim [switchparams] program-name [directives]

or:

cobanim_t [switchparams] program-name [directives]

Use cobanim_t if your program is multi-threaded.

The parameters are:

switchparams | A set of switches. Each switch must be preceded by a plus sign (+) to turn it on, or a minus sign (-) to turn it off. Switches can be set in any order. The last setting of a switch specified multiple times is the one that is accepted. See Descriptions of Run-time Switches for details on the switches available.
program-name | The name of the file you want to animate. If you do not specify a path, the current directory is assumed. If you do not specify an extension, a callable shared object is first searched for, followed by .gnt , .int, then .lbr files.
directives | An optional sequence of one or more Character Animator directives. Each directive must be separated by at least one space and must not be broken across lines. See Specifying Character Animator Directives for details on the directives available.
Parent topic: Command Line Debugging
Related information
Starting Character Animator at Your Terminal
Starting Character Animator In Sleep Mode
Specifying Character Animator Directives


Starting Character Animator In Sleep Mode

You can start Character Animator in sleep mode, which means that Character Animator sleeps until a process attaches to it, and then starts in a different window or process to the program you are debugging. Refer to Cross-session Debugging for details on how to attach you program to a sleeping Character Animator.

To start Character Animator in sleep mode, use the cobanimsrv command:

cobanimsrv [directives]

or:

cobanimsrv_t [directives]

Use cobanimsrv_t if your program is multi-threaded.

The parameters are:

directives An optional sequence of one or more Character Animator directives. Each directive must be separated by at least one space and must not be broken across lines.

See Specifying Character Animator Directives for details of the directives available.

Parent topic: Command Line Debugging
Related information
Starting Character Animator at Your Terminal
Starting Character Animator in a Different Window
Specifying Character Animator Directives
Cross-session Debugging


Specifying Character Animator Directives

You can use directives when Character Animator is invoked to modify its behavior. Directives are usually specified after the program-name on the command line.

If you specify more than one directive, they must all be enclosed in quotation marks. This is necessary to inform UNIX that all the directives in them are grouped together. If you omit the quotation marks, second and subsequent directives are ignored although no warning to this effect is given.

You can also specify an Character Animator directive in a $SET statement or in a DIRECTIVES file, but the directive value cannot be preceded by an equals sign (=). It must be enclosed either in double quotation marks (" ") or parentheses ( ). Also, you must not include any spaces in a value, because UNIX treats the space character as a delimiter.

You can also specify directives using the COBANIMOPT environment variable.

  • Directive Descriptions
  • Using COBANIMOPT
Parent topic: Command Line Debugging
Related information
Starting Character Animator at Your Terminal
Starting Character Animator in a Different Window
Starting Character Animator In Sleep Mode
Directives for Character Animator


Directive Descriptions

This section describes the Character Animator directives.

  • COBAIF
    Specifies whether to load and save Character Animator session information.
  • END
    Indicates the end of directives to Character Animator and start of command line parameters to your program.
  • MIXEDLANGDEBUG
    Use non-system level debugging. Enables mixed-language debugging.
  • MULTITHREAD
    Use the multi-threaded run-time system, enabling you to debug multi-threaded applications.
  • RESEQ
    Specifies that COBOL line sequence numbers should appear on the Character Animator's source display.
  • ZEROSEQ
    Specifies that leading zeros should appear in the sequence numbers in columns 1 through 6.
Parent topic: Specifying Character Animator Directives
Parent topic: Directives for Character Animator


COBAIF

Specifies whether to load and save Character Animator session information.

Syntax:

>>-.----.----COBAIF-----------------><
   +-NO-+

Parameters:

None

Properties:

Default:
COBAIF

Comments:

This directive can be followed by text for use in ACCEPT ... FROM COMMAND-LINE.

The Character Animator session information file contains details of breakpoints and monitors. Its extension is .aif.

If NOCOBAIF is specified, no session information files are loaded or saved. If COBAIF is specified, the session information files are saved and loaded in the current directory.

You can specify the directory in which Character Animator searches for or creates the .aif file using the $COBAIF environment variable.

Parent topic: Directive Descriptions
Related information
Environment Variables


END

Indicates the end of directives to Character Animator and start of command line parameters to your program.

Syntax:

>>-.---.----END--------------------><
   +-/-+

Parameters:

None

Properties:

Default:
Not present

Comments:

This directive can be followed by text for use in ACCEPT ... FROM COMMAND-LINE.

Parent topic: Directive Descriptions


MIXEDLANGDEBUG

Use non-system level debugging. Enables mixed-language debugging.

Syntax:

>>--.----.---MIXEDLANGDEBUG---------><
    +-NO-+

Parameters:

None

Properties:

Default:
NOMIXEDLANGDEBUG
Parent topic: Directive Descriptions


MULTITHREAD

Use the multi-threaded run-time system, enabling you to debug multi-threaded applications.

Syntax:

>>--.----.---MULTITHREAD------------><
    +-NO-+

Parameters:

None

Properties:

Default:
NOMULTITHREAD

Comments:

This directive creates a multi-threaded environment within which your multi-threaded programs can run.

Parent topic: Directive Descriptions


RESEQ

Specifies that COBOL line sequence numbers should appear on the Character Animator's source display.

Syntax:

>>--.----.---RESEQ------------------><
    +-NO-+

Parameters:

None

Properties:

Default:
RESEQ

Comments:

Do not use RESEQ if the program contains ++INCLUDE or -INC statements.

Parent topic: Directive Descriptions


ZEROSEQ

Specifies that leading zeros should appear in the sequence numbers in columns 1 through 6.

Syntax:

>>--.----.---ZEROSEQ------------------><
    +-NO-+

Parameters:

None

Properties:

Default:
NOZEROSEQ

Comments:

NOZEROSEQ suppresses leading zeros.

Parent topic: Directive Descriptions


Using COBANIMOPT

The COBANIMOPT environment variable enables you to specify directives additional to those specified on the command line. When you invoke Character Animator, it first reads the directives you have specified in COBANIMOPT, and then uses any directives you specify in the command line (which can override the directives set in COBANIMOPT).

COBANIMOPT is particularly useful if you invoke Character Animator using the run-time switch +A, or the debug_on_error run-time tunable.

The following example animates example.int using the MIXEDLANGDEBUG directive:

COBANIMOPT=mixedlangdebug
export COBANIMOPT
cobrun +A example.int
Parent topic: Specifying Character Animator Directives
Parent topic: Directives for Character Animator
Related concepts
Preparing the Environment


Just-in-time Debugging

Just-in-time debugging enables you to start Character Animator and debug a running program if it terminates with a run-time error. This enables you to see what was happening when the program failed.

To start just-in-time debugging you need to add the run-time tunable debug_on_error to the configuration file. To specify which debugger to start, add the run-time tunable debugger_command to the configuration file.

Parent topic: Debugging Methods
Related reference
debug_on_error
debugger_command


Core Dump Debugging

Core dump debugging enables you to see what went wrong during the execution of a program. When an error occurs or when you programmatically invoke a core dump, the operating system generates a core file. This core file contains a snapshot of the process's memory when the core dump process was generated. You can use this core file to debug the failing program on your Development Hub, or if you have the required source and .idy files, you can debug in another (remote) environment.

Note: If you do not have the source file that were directly used to build the program, you must ensure that the sources you do have are in the same state (directive settings, optimization, etc..) as they were during the initial build. Also, if moving the sources to debug, any supporting files used by the application (shared libraries, shared objects, third-party libraries, etc…) must be installed along the same path in the remote environments.

To generate a core dump, you need to call the CBL_CREATE_CORE library routine from your program, or add the run-time tunable core_on_error to your run-time configuration file. For details on the run-time configuration file and run-time tunables, see Run-time Configuration.

Note: If the tunable debug_on_error is set, the core_on_error tunable is overridden. You must therefore delete any reference to debug_on_error.

To use a core file to debug, start Character Animator, specifying the core file:

anim core-filename
Parent topic: Debugging Methods
Related reference
core_on_error
core_filename
Run-time Configuration Tunables - Overview


Unsolicited Dynamic Attachment Debugging

Unsolicited dynamic attachment enables you to start Character Animator at any point in a running program. To start an unsolicited dynamic attachment, you specify which process Character Animator needs to attach to.

Use system commands, such as ps, to ascertain the process id of the program, then start Character Animator using the process id:

anim process-id
Parent topic: Debugging Methods


Using the Debugging Library Routines

There are a number of library routines that you can insert into your code that attach to the Character Animator when executed:

  • CBL_DEBUGBREAK - this is a run-time library routine that enables you to attach Character Animator at any point during COBOL code execution. If you have this routine in your program, then Character Animator starts debugging your program at the line that calls this routine.
  • CBL_DEBUG_START and CBL_DEBUG_STOP are run-time library routines. They enable you to attach and detach Character Animator at various points during COBOL code execution. They are intended for use in remote and cross-session debugging, but they can also be used to control local animation.

For details on using these routines, see Debugging Routines.

Parent topic: Debugging Methods
Related reference
Debugging Routines


Preprocessor Debugging

If you need to debug a preprocessor, you must start Character Animator using either the CBL_DEBUGBREAK or CBL_DEBUG_START library routine. Insert either routine at a suitable point in the preprocessor source code, and when the program calls this routine, Character Animator starts and attaches to the preprocessor.

Parent topic: Debugging Methods
Related reference
Debugging Routines


Multi-threaded Program Debugging

This section assumes that you are familiar with multi-threaded programming. If you are not, refer to Multi-threaded Programming.

When you compile your application, you use the cob -t flag to specify that the program is multi-threaded. You can then run the program using the trigger for the multi-threaded run-time system, cobrun_t, setting the +A run-time switch to start Character Animator:

cobrun_t +A program

or start Character Animator:

anim_t program

Each of the triggers cobrun, anim and cobanim have a corresponding multi-threaded version cobrun_t, anim_t and cobanim_t.

When Character Animator starts, you can use its View-threads function to view multiple threads.

You can use core file debugging, just-in-time debugging and unsolicited dynamic attachment with multi-threaded programs as described in the previous sections; the difference is that you use the _t suffix with any triggers.

  • Multi-threading and Animator
Parent topic: Debugging Methods
Related reference
Multi-threaded Programming


Multi-threading and Animator

You can use Animator with multi-threading programs in two ways:

  • By starting one of the multi-threading versions of Animator using those commands that end in _t; for example anim_t
  • By starting Animator with the MULTITHREAD directive specified

If you start Animator with the MULTITHREAD directive specified, Animator creates a multi-threading environment for the animated program.

If you use the _t version of the commands that start Animator, both Animator and the animated program run in the multi-threaded run-time system. This can affect the speed at which Animator and the animated programs run because both use whatever system resources are necessary to maintain thread state information. However, using _t commands has the advantage over the MULTITHREAD directive that the operating system can share the code spaces of the two executing run-time system shared libraries, so memory use might not be adversely affected.

No hard and fast rules can be given as to whether you should use the _t commands, or the MULTITHREAD directive. Generally, if speed is an issue, use Animator with the MULTITHREAD directive; if memory use is an issue, use the _t commands.

For information on Animator directives, see the chapter Directives for Animator

Parent topic: Multi-threaded Program Debugging


CGI Program Debugging

You can use Character Animator to debug CGI programs using any of the following:

  • Animator from the command line
  • Animator from the CBL_DEBUGBREAK or CBL_DEBUG_START routine
  • Just-in-time debugging
Parent topic: Debugging Methods
Related information
Command Line Debugging
Just-in-time Debugging
Using the Debugging Library Routines


Cross-session Debugging

Cross-session debugging enables you to use Character Animator in a different terminal window to that in which the program to be debugged is running. With cross-session debugging, Character Animator is started first in one session and left in a waiting state; it then attaches to a program started in another session, as long as certain conditions are met. These are:

  • The user IDs of the two sessions are the same.
  • The TMPDIR environment variable is set to the same value for both the Character Animator process and the running program.

You associate the Character Animator process and the program using one of the following methods:

  • Set the COBANIMSRV environment variable to the same value for both the Character Animator process and the program before you start them.
  • Start the Character Animator process and the program running in the same directory.
  • Insert a call to CBL_DEBUG_START in the program; either specify an identifier string that matches the COBANIMSRV environment variable for the Character Animator process, or run the program in the same directory as the Character Animator process.
  • Using the COBANIMSRV Environment Variable
  • Using the Same Directory
  • Using CBL_DEBUG_START and CBL_DEBUG_STOP
Parent topic: Debugging Methods
Parent topic: Using Character Animator


Using the COBANIMSRV Environment Variable

You can specify a unique identifier using the COBANIMSRV environment variable for the processes used by Character Animator and the program you want to debug. Character Animator will then only debug a program that has a matching identifier. For example, in one session enter:

export COBANIMSRV=myid

myid is now a unique identifier you can use to match Character Animator to a program. Enter the command to start Character Animator:

cobanimsrv

Character Animator waits for a COBOL program to start that has a matching identifier. In another session enter:

export COBANIMSRV=myid
cobrun prog1.int

When prog1.int starts, the unique identifier myid matches that of Character Animator, and so Character Animator attaches to this process. In the first session, the Character Animator main screen is displayed and the cursor placed on the first line of prog1.int.

Parent topic: Cross-session Debugging


Using the Same Directory

If you start Character Animator in the same directory as that in which you run the program that is to be debugged, the program will attach to the waiting Character Animator process.

For example, in one session enter:

cd /home/user/program/debug
cobanimsrv

Character Animator is now waiting for a program to start in the /home/user/program/debug directory. Therefore, if in another session you change to the same directory and start a program by entering:

cd /home/user/program/debug
cobrun prog1.int

prog1.int attaches to the waiting Character Animator process; the Character Animator main screen is displayed and the cursor is placed on the first line of prog1.int.

Parent topic: Cross-session Debugging


Using CBL_DEBUG_START and CBL_DEBUG_STOP

With these routines you can switch debugging on and off as you wish and debug more than one program without having to stop and restart the Character Animator process. You start up Character Animator in one session, using the cobanimsrv command. In a second session you run a program that has a different COBANIMSRV environment variable value, or if it is not set, is running in a different directory. This program starts running as normal, not animated.

When a call to CBL_DEBUG_START is encountered with an identifier parameter that matches the value of the COBANIMSRV environment variable for the Character Animator process, or if the identifier parameter is unset, is running in the same directory, then Character Animator attaches to the program.

For example, in one session enter:

export COBANIMSRV=myid

myid is now a unique identifier you can use to match Character Animator to a program. Enter the command to start Character Animator:

cobanimsrv

Character Animator waits for a COBOL program to start that has a matching identifier. In another session enter:

cobrun prog1.int

The prog1.int program starts running without animation. A call to CBL_DEBUG_START is encountered:

call CBL_DEBUG_START using by value     flags, timeout,
                           by reference "myid",
                           returning    status-code

The unique identifier myid matches that of Character Animator, so Character Animator attaches to this process. In the first session, the Character Animator main screen is displayed and the cursor placed on the line of prog1.int containing the CBL_DEBUG_START call.

You can stop or suspend debugging by issuing a call to CBL_DEBUG_STOP.

CBL_DEBUG_START and CBL_DEBUG_STOP calls can also be used to switch remote and local animation on and off.

Note: To control cross-session animation using CBL_DEBUG_START and CBL_DEBUG_STOP, you must either:
  • Use different COBANIMSRV environment variable values for the Character Animator process and the program, in which case you can run them in the same directory
  • Run them in different directories

If the COBANIMSRV environment variable values for the Character Animator process and the program match, Character Animator will start animating the program immediately, instead of when the first call to CBL_DEBUG_START is encountered.

Parent topic: Cross-session Debugging
Related reference
CBL_DEBUG_START
CBL_DEBUG_STOP


Using cobesdebug to Debug Services and Applications on Enterprise Server

There are several methods that you can use to debug services and applications that run on an enterprise server. The most flexible of these, and the one that we recommend, is the use of the Enterprise Server Dynamic Debugging facility.

The Enterprise Server Dynamic Debugging option enables you to attach to, and debug, any application or service running on an enterprise server. It requires no changes to the code of your program. It does however require that you turn on Dynamic Debugging for your enterprise server, that the enterprise server is running on the same machine and under the same user ID as Visual COBOL, that you compile for debug, and that you deploy the dictionary (.idy) files for your application.

  • How it works
  • How Enterprise Server finds a match
  • How to debug services and applications with Enterprise Server Dynamic Debugging
  • Alternative ways of Debugging Services and Applications on Enterprise Server
Parent topic: Debugging Methods
Parent topic: Using Character Animator


How it works

Using the cobesdebug utility, you can tell an enterprise server configured for Dynamic Debugging that you want to debug any service or application instance that matches criteria that you supply. For example, you can specify that you want to debug instances of a given web service that are started from a particular client machine.

Each time an application or service is started the enterprise server checks to see if it matches the criteria that you supplied. If it does, the enterprise server attaches it to the debug session started by cobesdebug. You can then step through the application in the normal way.

Parent topic: Using cobesdebug to Debug Services and Applications on Enterprise Server


How Enterprise Server finds a match

Your match criteria can be specific or general. However, we recommend that you be as specific as possible to avoid conflicts with other users. If more than one user specifies details that match a particular service or application instance, the most specific match (that is, the session that provided the most specific information) will be attached to the instance.

Note: You can view the active dynamic debug sessions and the associated debug criteria on your enterprise server by using Dyn-Dbg in ESMAC. You can also use the screen to remove debug criteria that are no longer required. To access ESMAC, see To start ESMAC for a server.

Example

USERA specifies Web Services started from a particular client IP address. USERB specifies Web Services started from the same client IP address, but also specifies the service name. When a matching web service is started, the enterprise server will attach USERB's debug session to the service.

When you specify the match criteria, you will be warned if they are similar to those provided by another user. If you specify identical match criteria to those provided by another user, you will receive an error message and the criteria will be rejected.

Parent topic: Using cobesdebug to Debug Services and Applications on Enterprise Server


How to debug services and applications with Enterprise Server Dynamic Debugging

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Connect to Enterprise Server Administration.
  2. Enable dynamic debugging for the enterprise server that you want to use for debugging.
  3. If you have not already done so, deploy the service or application to the server. Ensure that you also deploy the program's .cbl, and .cpy source files and the .idy file, which is needed for debugging.
  4. If your program is a service (Web Service or J2EE), you will need to create a client program to submit requests for that service.
  5. At the UNIX shell prompt, run the cobesdebug utility, specifying (on the command line) the details of the service that you want to debug. It takes the following arguments
    Argument | Description | Usage | Applies to
    type | Specify either WS | J2EE, depending on the type of application or service you want to debug. | Mandatory | All
    ipaddress | Specify the IP address of the client that will be used to request the web service you want to debug. Enter the address in the form xxx.xxx.xxx.xxx | Optional | Web service only
    servicename | Specify the fully qualified name of the service. This is formed by taking the name of the service and appending a hash(#) character, for Web Services, or a dot(.), for J2EE, followed by the name of the operation that you want to debug. For example, if the service name for the web service that you deployed is http://tempuri.org/wmapserv, and the operation to be debugged is Read, the fully qualified service name is http://tempuri.org/wmapserv#Read | Optional | Web service and J2EE
    server | Specify the enterprise server region that you are using to run the services you want to debug | Mandatory | All

    For example:cobesdebug type=WS server=ESDEMO servicename=http://tempuri.org/wmapserv#Read

    cobesdebug now passes the service details to the enterprise server region specified by the server parameter and starts the Character Animator. The Character Animator waits for the service to begin.

    Each time a service is started, the enterprise server will check to see if it matches the details that you provided. If it does, the enterprise server attaches the Character Animator to the service.

    Note:
    • You must make sure that the debugger will be able to locate the source and .idy files for the application. To do this, set the cobidy environment variable to include the path for the .idy files, and set the cobcpy environment variable to include the path for the source files.
    • You must run cobesdebug under the same user ID that was used to start your enterprise server.
  6. Run the client program and enter some input.
  7. When the client submits the request, the enterprise server will attach your debugging session to the service.
  8. You can step through the deployed service in the usual manner.
  9. When you reach the exit program statement, cobesdebug waits for another instance of the service to start. If you have finished debugging, type Ctrl-C to close cobesdebug.
Parent topic: Using cobesdebug to Debug Services and Applications on Enterprise Server


Alternative ways of Debugging Services and Applications on Enterprise Server

You can use the following alternative methods for debugging services and applications running on an enterprise server. As with Enterprise Server Dynamic Debugging, Visual COBOL and Enterprise Server must be running on the same machine.

  • Insert a call to CBL_DEBUGBREAK in the program before you deploy it to Enterprise Server. With this method, if you are running the enterprise server on your local machine, make sure the operating system environment variable DISPLAY is not set. If you are using an x-term, make sure DISPLAY points to your machine. If DISPLAY is set, the debugger's output goes to the machine indicated by DISPLAY.
  • Start a debug service execution process at the command line, using the cassi /a command. When you use this method, any service that runs in the debug service execution process is debugged.
  • Debugging Services and Applications on Enterprise Server Using CBL_DEBUGBREAK
  • Debugging Services and Applications on Enterprise Server Using the cassi Command
Parent topic: Using cobesdebug to Debug Services and Applications on Enterprise Server


Debugging Services and Applications on Enterprise Server Using CBL_DEBUGBREAK

To debug a service using CBL_DEBUGBREAK using the default enterprise server ESDEMO, follow these steps:

  1. Start the server ESDEMO. You can do this either using the Web interface Enterprise Server Administration, or using the casstart command. For more information, see your Enterprise Server documentation.
  2. Insert the following line at the beginning of the Procedure Division of your program:
    call "CBL_DEBUGBREAK"
  3. Compile your program with a command such as:
    cob -ia myprog.cbl
  4. Deploy the service to ESDEMO, or if you have already deployed it, redeploy it (this involves deleting the deployed service). See the help topics To deploy a service interface using the deploy tool and To redeploy a service interface. Ensure that you also deploy the program's .cbl and .cpy source files and the .idy file, which is needed for debugging.
  5. Create a client program for your service. See the help topic To generate a COBOL client from a Web service mapping.
  6. Run the client program and enter some input.
  7. On the message saying a call to CBL_DEBUGBREAK has been detected, click Yes. The Character Animator starts, displaying the source of your program ready for debugging. You can now step through the deployed service in the usual manner.

Remember to remove the line that calls CBL_DEBUGBREAK when you have finshed debugging the service.

As an alternative to inserting the call statement, you can compile the program with the Compiler directive INITCALL"CBL_DEBUGBREAK", before you deploy it.

Parent topic: Alternative ways of Debugging Services and Applications on Enterprise Server


Debugging Services and Applications on Enterprise Server Using the cassi Command

To debug a service using the cassi command using the default enterprise server ESDEMO, follow these steps:

  1. Start the server ESDEMO. You can do this either using the Web interface Enterprise Server Administration, or using the casstart command. For more information, see your Enterprise Server documentation.
  2. Start a debug service execution process on the server ESDEMO. Enter:
    cassi -a -rESDEMO
  3. Compile your program with a command such as:
    cob -ia myprog.cbl
  4. Deploy the service to ESDEMO, or if you have already deployed it, redeploy it (this involves deleting the deployed service). See the help topics To deploy a service interface using the deploy tool and To redeploy a service interface. Ensure that you also deploy the program's .idy file, which is needed for debugging.
  5. Create a client program for your service. See the help topic To generate a COBOL client from a Web service mapping.
  6. Run the client program and enter some input.
  7. As soon as the service is entered, the Server Express Animator starts, displaying the source of your program ready for debugging. You can now step through the deployed service in the usual manner.

You must also either deploy the .cbl and .cpy files or set the COBCPY environment variable in ESDEMO's configuration to point to the location of the files. For more information about setting environment variables for enterprise servers see the section Environment Variables in the chapter Configuration in your Enterprise Server Configuration and Administration Guide.

Any service that runs in the debug service execution process is debugged, that is, the Server Express Animator starts up as soon as the service is entered.

Parent topic: Alternative ways of Debugging Services and Applications on Enterprise Server


Debugging Enterprise Server Services and Applications Using a Live Recording

Using the cobeslr command line utility you can configure the Enterprise Server Dynamic Live Recorder to live record any application or service running on an enterprise server region. It requires no changes to the code of your program. However, it has the following requirements:
  • Dynamic Debugging is enabled on the enterprise server region.
  • You issue the cobeslr command on the same machine as is running the enterprise server region, and with the same/equivalent user privileges used to start the region.
  • The programs are compiled for debug and the dictionary files (.idy files) are deployed.
  • How It Works
  • How Enterprise Server Finds a Match
  • To Create a Live Recording with Enterprise Server Dynamic Debugging
Parent topic: Debugging Methods


How It Works

Using the cobeslr utility, you can specify match criteria within an enterprise server region, that when met, will create a live recording file that can be replayed, for debugging purposes, in your Eclipse IDE. You can create multiple criteria for a region.

You can specify criteria for CICS, IMS, JCL, Web services and J2EE. For example, you can specify that you want to live record instances of a given web service that are started from a particular client machine; or you can live record a certain CICS transaction whenever it is run.

Once specified, these criteria remain in place for the lifespan of the region, or until you remove them, either from the Dyn.Debug ESMAC page or by using the cobeslr utility.

To ensure that matching criteria produce a live recording file (.mfr file), dynamic debugging must be enabled for the enterprise server region, and the application's dictionary files (.idy files) must also have been deployed. Live recording files are created in the System Directory of the enterprise server region. More than one recording file may be created, depending on the type of criteria; for example, criteria set for when a CICS transaction is run may be met multiple times, leading to multiple recording files being created.

Live recording files include the SEP, task, and PID details in the file name to ensure it is unique, and to help you identify a particular recording if many are created.
Parent topic: Debugging Enterprise Server Services and Applications Using a Live Recording


How Enterprise Server Finds a Match

Your match criteria can be specific or general. However, we recommend that you be as specific as possible to avoid conflicts with other users. If more than one user specifies details that match a particular service or application instance, the most specific match (that is, the session that provided the most specific information) will be attached to the instance.

Note: You can view the active live record sessions and the associated criteria on your enterprise server by using Dyn.Debug in ESMAC. You can also use the screen to remove criteria that are no longer required. To access ESMAC, see To start ESMAC for a server.

Example

USERA specifies Web Services started from a particular client IP address. USERB specifies Web Services started from the same client IP address, but also specifies the service name. When a matching web service is started, the enterprise server will attach USERB's debug session to the service.

When you specify the match criteria, you will be warned if they are similar to those provided by another user. If you specify identical match criteria to those provided by another user, you will receive an error message and the criteria will be rejected.

Parent topic: Debugging Enterprise Server Services and Applications Using a Live Recording


To Create a Live Recording with Enterprise Server Dynamic Debugging

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

Use these guidelines to create match criteria for a particular service or application. When the criteria are met, a live recording file is produced that you can play in your Eclipse IDE, for debugging purposes.

  1. Connect to Enterprise Server Administration.
  2. Enable dynamic debugging for the enterprise server region that should produce the live recording file.
  3. If you have not already done so, deploy the service or application to the server.
  4. If your program is a service (Web Service or J2EE), you need to create a client program to submit requests for that service.
  5. At the UNIX shell prompt, run the cobeslr utility, specifying the service or application details that you want to live record. It takes the following arguments:
    Note: If your system does not have mainframe support enabled, only the service types (WS and J2EE) are applicable.
    Argument | Description | Usage | Applies to
    type | Specify either CICS | JCL | WS | J2EE | IMS, depending on the type of application or service you want to debug. | Mandatory | All
    tranid=<transaction-id> | The CICS or IMS transaction to debug | Optional | CICS, IMS
    termid=<terminal-id> | Only debug CICS or IMS transactions started from terminal <terminal-id> | Optional | CICS, IMS
    userid=<user-id> | Only debug CICS or IMS transactions started by <user-id> | Optional | CICS, IMS
    progid=<prog-id> | Only debug CICS or IMS program <prog-id> | Optional | CICS, IMS
    jobname=<job-name> | Only debug the JCL job <job-name> | Optional | JCL
    stepname=<step-name> | Only debug the JCL step <step-name> | Optional | JCL
    jobnumber=<job-number> | Only debug the JCL job <job-number> | Optional | JCL
    program=<program-name> | Only debug the JCL program <program-name> | Optional | JCL
    ipaddress

    Specify the IP address of the client that will be used to request the web service you want to debug. Enter the address in the form

    xxx.xxx.xxx.xxx     		Optional Web service only
    servicename

    Specify the fully qualified name of the service. This is formed by taking the name of the service and appending a hash character (#) for Web Services, or a dot (.) for J2EE, followed by the name of the operation that you want to debug. For example, if the service name for the web service that you deployed is http://tempuri.org/wmapserv, and the operation to be debugged is Read, the fully qualified service name is:

    http://tempuri.org/wmapserv#Read
             Optional Web service and J2EE
    server | Specify the enterprise server region running the services that you want to debug | Mandatory | All

    For example: cobeslr type=WS server=ESDEMO servicename=http://tempuri.org/wmapserv#Read

    cobeslr now passes the details to the enterprise server region specified by the server parameter.

  6. You can view the active match criteria that are in effect on the Dyn.Debug ESMAC page; see View the List of Attached Debuggers for more information.
  7. Run the client program and execute the required service, transaction, job, etc... that will trigger the Live Recorder.

    A live recording file (.mfr file) is created in the System Directory of the enterprise server region when the criteria triggers the Live Recorder. For example, the example above triggers a recording when the client submits a request; CICS criteria might live record when a particular transaction is run; or JCL criteria might live record when a particular step is executed.

    The match criteria remain in place, so the next time a match is met, it will also be Live Recorded. This could mean that many .mfr files get created in a short space of time (for example, a CICS transaction gets run multiple times). The name of the recording file includes the SEP, task, and PID details to ensure the file name is unique and helps you to identify a particular recording if many are created.

Tip: To remove the match criteria use cobeslr with the exact same criteria that were set, with the remove option added; for example:
cobeslr remove type=WS server=ESDEMO servicename=http://tempuri.org/wmapserv#Read

Alternatively, you can remove the criteria from the Dyn.Debug ESMAC page.

Now that you have a live recording file, you can debug it in your IDE, as you would any other generated native COBOL live recording; see To debug a live recording.

Parent topic: Debugging Enterprise Server Services and Applications Using a Live Recording


Using Character Animator

Development Hub uses the Character Animator to enable you to animate (debug) your native COBOL programs.

  • Overview of Character Animator Functions
  • Working With Character Animator
  • Directives for Character Animator
    Describes the Character Animator directives you can use to control the animation of your program.
  • Cross-session Debugging
  • Using cobesdebug to Debug Services and Applications on Enterprise Server
Parent topic: Debugging Applications


Overview of Character Animator Functions

Character Animator uses windows to display information about your program during execution, along with the corresponding part of your source code. Animator provides functions that enable you to control the pace at which your program runs, interrupt execution to examine and change data items, alter the sequence of execution or enter COBOL statements for immediate execution before your program continues. These facilities enable you to debug your programs quickly and easily.

Executing a Program

A flexible set of execution functions enables you to execute the code at the speed to suit the problem you are examining. You can Zoom (execute at maximum speed) through code you do not want to see execute, manually Step through each statement or set a convenient automatic execution speed in a problem area.

You can set breakpoints throughout the source code by marking each statement where you want a break to occur or by defining a condition that should give rise to a break. This lets you define exactly when to get manual control of your program when it is executing automatically.

Querying, Monitoring and Changing Data Items

Debugging a program often involves monitoring various data values in order to detect unexpected results. As the values of the data change during program execution, the monitored items are highlighted as they are updated.

You can query a data item in a program and display its contents in either text (ASCII) or hexadecimal format. The contents of the data item can be changed, with immediate effect in subsequent program execution.

Logic Testing

Do functions enable you to execute additional code without having to interrupt your testing session. These COBOL statements can be executed when you enter them, or they can be associated with a statement and executed with that statement. The latter are saved in a file so that they can be incorporated into your source code once you have decided they correct a problem.

Reset functions enable you to bypass code that you do not want to be executed.

Parent topic: Using Character Animator


Working With Character Animator

  • The Character Animator Screen
  • Menus
  • Functions
  • Run-time System Error Messages
Parent topic: Using Character Animator


The Character Animator Screen

  • Character Animator Screen Overview
  • The Information Line
  • Moving the Cursor and Text During Animation
  • Entering Text on Menus
  • Using the Character Animator Windows
  • Obtaining Help
Parent topic: Working With Character Animator


Character Animator Screen Overview

The Character Animator screen appears after Character Animator has been invoked. Your program source code appears on this screen. The cursor is positioned under the first executable statement in the Procedure Division, and this statement is highlighted. The bottom of the screen displays the information line and the Animator main menu.

Main Menu - Animator

The Animator main menu contains functions that you select to control the way your program is executed. A full description of these functions is presented later in this chapter.

When you use an option that causes statements to be executed, the cursor and highlighting follow the execution path, so they are always on the statement to be executed next. At other times, the highlighting remains on the statement that is to be executed next, but you can move the cursor around the screen to access different places in the source. The statement to be executed next, or currently being executed, is always highlighted, and is known as the current statement.

Parent topic: The Character Animator Screen


The Information Line

The information line displays the name of your program. It also shows the current level (Level=01) of nested PERFORM statements in the program, and the speed at which you have selected to animate your program. The Ins, Caps, Num and Scroll indicators, which appear on the right side of the information line, are highlighted when Insert, CapsLock, Num Lock, or Scroll Lock respectively are active.

Parent topic: The Character Animator Screen


Moving the Cursor and Text During Animation

You can use several keys to move the cursor through the displayed code. You can also change the portion of text displayed on the screen.

Some of these keys are symbolic key names which might not be present on your keyboard.

Key Name | Function | Default Key/Keystroke
cursor-left | Moves the cursor left one character position | cursor-left
cursor-right | Moves the cursor right one character position | cursor-right
cursor-up | Moves the cursor up one line; with Scroll Lock on moves the text down one line | cursor-up
cursor-down | Moves the cursor down one line; with Scroll Lock on moves the text up one line | cursor-down
Tab | Moves the cursor to the next tab position to the right; tabs are set every four positions in columns 1 through 76 | Tab
Backtab | Moves the cursor to the next tab position to the left | Backtab
Enter | Moves the cursor to column 1 on the next line in Animator; with Scroll Lock on, moves the text up one line | Enter
Home | Moves the cursor to column 1 of the current line in Animator; pressing Home a second time moves the cursor to column 1 of the top line; pressing Home a third time moves the cursor to the beginning of the file | Home
End | Moves the cursor to the end of the current line; pressing End a second time moves the cursor to the bottom of the screen; pressing End a third time moves the cursor to the end of the file | End
Page-Up | Displays the screen of program text preceding the current screen | KEY_PPAGE or Ctrl+U
Page-Down | Displays the screen of program text following the current screen | KEY_NPAGE or Ctrl+D
Top-of-text | Moves immediately to the top of the program | Ctrl+T
Bottom-of-text | Moves immediately to the end of the program | Ctrl+V
Up-10-screens | Moves (10 x source screen size) lines up the program | KEY_SR or Ctrl+B
Down-10-screens | Moves (10 x source screen size) lines down the program | KEY_SF or Ctrl+F
F1 through F10 | Function key 1 through Function key 10 | KEY_F(0-10)
Escpe | Escape | Esc
Parent topic: The Character Animator Screen


Entering Text on Menus

Several of the Character Animator menus require you to enter text. In all cases, on entry to the menu, the previous contents of the field are present. This can be cleared using F2=clear. This key acts as a delete-to-end-field, deleting all characters from the current cursor position to the end of the field. When entering or editing text, the keys <left-arrow>, <right-arrow>, Home, End and Backspace all operate as normal. Insert or overtype mode can also be selected using the Ins key.

Once you have completed a field, pressing Enter confirms your update. If you want to cancel the update, press Escape. Both keys cause exit to a higher level menu if appropriate.

Where a selection of fields is presented, you can use the cursor keys to move up and down the list, and Enter selects the item you want and places it in the input field if appropriate.

Parent topic: The Character Animator Screen


Using the Character Animator Windows

Character Animator places information in windows which you can manipulate.

You view your COBOL source code as a backdrop to the windowing system displaying the monitored data items. You can fill the screen as required with the contents of data items. The system is capable of covering the entire source code area with data windows. Simple keystrokes enable the monitored items to be hidden, reappearing automatically whenever they change in value.

  • Viewing Data
  • Key Functions for Updating Queried Data Items
Parent topic: The Character Animator Screen


Viewing Data

You can view a maximum of 200 characters in COBOL format in one window. You can scroll through the contents of this window to view other parts of the data item. You use multiple windows to monitor the same data item so that more than 200 characters can be monitored at one time. You also have the option of displaying a maximum of 128 bytes of the monitored item in hexadecimal format.

Note: Numeric values are viewed as equivalent edited PICTURE strings.

The contents of data items that you can change appear in reverse video in the monitoring windows. Keyboard keys and special keystrokes enable efficient editing of the item's contents.

Parent topic: Using the Character Animator Windows


Key Functions for Updating Queried Data Items

The following keys and key combinations have special effects when updating the contents of data items. Some of these keys are symbolic key names which might not be present on your keyboard.

Key Name | Function | Default Key/Keystroke
Home | Moves the cursor to the beginning of the window | Home
Top-of-Text | Moves the cursor to beginning of the data item; causes the contents of the window to change if not currently displaying the beginning of the item | Ctrl+T
End | Moves the cursor to the end of the window | End
Bottom-of-Text | Moves the cursor to the end of the data item; causes the contents of the window to change if not currently displaying the end of the item | Ctrl+V
cursor-up | Moves the cursor up one line; if at the top of the window, updates the window to show the previous window of the item's contents | cursor-up
cursor-down | Moves the cursor down one line; if at the bottom of the window, updates the window to show the next window of the item's contents | cursor-down
cursor-left | Moves the cursor left one character position; if at the beginning of the window, shifts data in the window one character to the right | cursor-left
cursor-right | Moves the cursor right one character position; if at the end of the window shifts data in the window one character to the left | cursor-right
F2 | Clears the contents of the data item | KEY_F2
Ins | Toggles between insert and replace modes; in insert mode, Ins is highlighted on the information line; the cursor changes shape | Ins
Del | Deletes the character at the current cursor position; if insert mode is on, causes all other characters to the right of cursor in the window to shift left one position | Del
Backspace | Deletes the character before the cursor position; if insert mode is on, causes all characters to the right of cursor in the window to shift left one position | Backspace
Parent topic: Using the Character Animator Windows


Obtaining Help

You can access two types of online help from the Character Animator screen:

  • Press F1=help to view a help screen which displays information about the current function as well as defining the options available from that function. If there is more than one screen of help text, pressing F1 again displays the next screen. To return to the current function from the help screen, press F1 (from the last screen) or the Space bar.
  • Press ALT + 1 to access the On-Line Reference. This contains COBOL language syntax diagrams and the error messages for the syntax-check phase of compilation. To return to the current function from the On-line Reference screen, press Escape then Y.
Parent topic: The Character Animator Screen


Menus

Character Animator menus are organized to provide rapid access to the most commonly used functions.

The menus described in this section appear in alphabetical order according to their menu name, which is displayed on the left-hand side of the information line.

  • Animator Main Menu
  • Breakpoints Menu
  • Environment Menu
  • Go Menu
  • Locate-declaration Menu
  • Perform-level Menu
  • Query Menu
  • Reset-execution Menu
  • Text Menu
Parent topic: Working With Character Animator


Animator Main Menu

The Animator main menu is displayed when Character Animator is started (unless the ZOOM Animator directive has been set, in which case the program executes immediately).

The main menu provides access both to direct functions and to submenus. The direct functions enable you, with a single keystroke, to execute the program and to reposition the program text on your screen.

To select a submenu or a function, use the appropriate function key or highlighted key required.

Parent topic: Menus


Breakpoints Menu

The Breakpoints menu is accessed by pressing B on the Character Animator main menu.

You can set breakpoints in your program to halt execution when you are using Go or Zoom mode. They are useful for debugging programs quickly when you have some idea of where a problem lies.

This menu displays options that enable you to perform the following functions:

  • Set a breakpoint at the statement at the current cursor location
  • Set a thread-local breakpoint at the statement at the current cursor location
  • Set a breakpoint at the statement at the current cursor location and zoom execution. This breakpoint is then automatically unset.
  • Cancel either a single breakpoint at the current cursor location or all breakpoints throughout the program
  • Set a conditional breakpoint
  • Examine the set breakpoints
  • Automatically execute a specified COBOL statement at a breakpoint
  • Set the frequency with which a breakpoint is activated

When a breakpoint is reached, you see the message:

Breakpoint encountered

at the bottom of your screen.

You can set up to 100 breakpoints in each program.

Note:

By default, whenever you syntax-check a program, Animator saves details of the breakpoints in an .aif file. This means that breakpoints you set are not lost when you syntax-check a program again, or exit Animator.

The location of a breakpoint is stored in an .aif file as an offset from the start of the relevant section or paragraph. As a result, when you insert or delete lines before a breakpoint in a section or paragraph, rechecking the program could cause the breakpoint to be set on a line other than the line on which you set it.

Parent topic: Menus


Environment Menu

The Environment menu is accessed by pressing E on the Character Animator main menu.

The Environment menu provides functions which enable you to set parameters to control some general execution aspects of the program you are executing. These include:

  • Specifying the name of a program at which to interrupt execution
  • View loaded programs
Parent topic: Menus


Go Menu

The Go menu is accessed by pressing G on the Character Animator main menu.

The Go function automatically executes each statement in the program one by one, displaying the source code on the screen as it is executed. Go mode is an automatic Step mode; you do not have to press a key to execute each statement as you do in Step mode.

You can set the Go execution speed by pressing a key from 0 to 9, where 0 is the slowest. You can also set the speed of execution from the Animator main menu by pressing a number from 0 to 9 before selecting the Go function. The current speed is shown on the information line. The default speed is 5.

Parent topic: Menus


Locate-declaration Menu

The Locate-declaration menu is accessed by pressing L on the Character Animator main menu.

The Locate-declaration function finds the location in the source code where a data item, filename or procedure is declared.

From the Locate-declaration menu you can locate an item either by using the cursor as a pointer or keying in the name of the item you want to locate. You can use the cursor control keys to position the cursor in the program text or monitor window. Data items and filenames can be located from either their monitor windows or name in the text. Procedure-names can be located from their names in the program text.

Parent topic: Menus


Perform-level Menu

The Perform-level menu is accessed by pressing P on the Character Animator main menu.

The Perform-level function enables you to Zoom through performed paragraphs, in-line PERFORM statements and called subprograms. This is useful if you are looking for a bug and are sure it isn't in a particular PERFORM range or subprogram.

The perform functions enable you to:

  • Zoom through the code specified by a PERFORM or CALL statement, or the code that completes such a statement if you have already begun to execute it.
  • View the current CALL/PERFORM stack and switch context to a different level.

You can animate programs with up to a maximum of 254 levels of PERFORM nesting. If your program exceeds this level, Animator will only Step, even if you specify Zoom mode.

Parent topic: Menus


Query Menu

The Query menu is accessed by pressing Q on the Character Animator main menu.

Query Menu - Animator

The Query menu functions enable you to look at and change the contents of data items. From this menu and its submenus, you can query data items, create a file containing a list of data values, and monitor data items.

Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item in a window or at the bottom of the screen.

Note:
  • Monitored variables are not saved between Animator sessions.
  • When you query a variable the cursor must be on one of the first two characters of the name otherwise the query will not work.
  • Query Data-name Menu
Parent topic: Menus


Query Data-name Menu

The Query Data-name menu appears after you have selected the item to be queried. The data-name appears on the information line; the value of the data item appears in a window.

Query Data-name Menu

This menu provides functions which enable you to display the contents of the queried data item; if the data item exceeds 200 bytes, only the first 200 bytes are displayed. From this menu, you can also view the data item in both hexadecimal and ASCII (text) format together and clear or alter the contents of the data item.

The Query Data-name menu is actually a set of two menus: an ASCII (text) menu and a hexadecimal menu. You switch between them using a toggle key.

The ASCII menu is the menu which first appears after selecting the data item to be queried. Selecting F3=hex invokes the hexadecimal menu. On this menu, the F3=hex is replaced by F3=ext function which switches back to the Text menu.

On the hexadecimal menu, the content of the queried data item appears on the left of the display area in hexadecimal form. The corresponding ASCII representation appears on the right.

Parent topic: Query Menu


Reset-execution Menu

The Reset-execution menu is accessed by pressing R on the Character Animator main menu.

Reset Execution Menu

The Reset function enables you to alter the sequence of program execution by changing the current statement, which is the statement that is to be executed next. You can simply skip one statement, reset to the current cursor position, reset at the next (higher) Perform level, or reset at the start of the program. Reset does not change the values of any data.

Parent topic: Menus


Text Menu

The Text menu is accessed by pressing T on the Character Animator main menu.

The Text function enables you to split, join, and redisplay the screen.

Parent topic: Menus


Functions

Character Animator functions are accessed from menus. The function names are sometimes abbreviated on the menus; however, the descriptions in the following sections use the full names.

The following section contains a quick reference listing all of the functions available in Animator. This listing is followed by detailed descriptions of these functions.

  • Function Access
  • Function Descriptions
Parent topic: Working With Character Animator


Function Access

The following table lists the functions in alphabetical order and indicates the keys you must press to access them. Thus, to determine the path to access a given function, follow the sequence of keystrokes. For example, to reach the Set Breakpoint function, from the Character Animator main menu, you press the Breakpoints key (B) followed by the Set Breakpoint key (S).

Some of these keys are symbolic key names which might not be present on your keyboard.

For the purposes of this table, it is assumed that you are using the cursor to identify data-names rather than keying them in; therefore, a C on the menu access path indicates the selection of a data-name using the cursor. If, however, you are not using the cursor, simply substitute E (Enter name) and the name of your data item for the key C to identify fields.

Function | Menu Access Keys
0-9 | 0-9
Align | F3
Alter Path | No explicit access
Alternate | Alt
Breakpoints | B
Cancel All Breakpoints | B, C
Cancel Program Break | E, P, C
Clear | Several
Child Data | Q, C, F8
Parent Data | Q, C, F7
Cursor-name Locate | L, C
Cursor-name Query | Q, C or double-click
Cursor-position Reset | R, C
Detach from application | Esc D
Do | D
Do At Breakpoint | B, D
Down Table | Q, C, F6
Enter | Enter
Enter-name Locate | L, E
Enter-name Query | Q, E
Environment | E
Escape | Esc
Examine Breakpoints | B, E
Exchange | F4
Exit Perform | P, E
Find String | F
Go | G
Hex | Q, C, F3
Hex/ASCII | Q, C, F10
Hide Monitors | Q, H
If Breakpoint | B, I
Join Text | T, J
Look-up | F6
Monitor | Q, C, F4
Monitor-off | Q, M
Next Reset | R, N
On Count Breakpoint | B, O
Organize Monitors | Q, O
Perform-level | P
Perform-view | P, V
Query | Q
Query Data-name | Q, C
Quit-perform | R, Q
Refresh | T, R
Reset-execution | R
Same Level | Q, C, F9
Scroll Up/Down (continuously) | Ctrl+F9/F10
Scroll Up/Down (1 line) | Ctrl + <left-arrow>/<right-arrow>
Select Program Break | E, P, S
Set Breakpoint | B, S
Split Text | T, S
Start | R, S
Step | S
Step Perform | P, S
Text | T or Q, C, T
This Program Break | E, P, T
Thread-local Breakpoint | B, T
Un-set Breakpoint | B, U
Up Table | Q, C, F5
View | F2
View Programs | E, V
View Threads | V
Where | F5
Word left | F9
Word right | F10
Zoom | Z
Zoom Breakpoint | B, Z
Parent topic: Functions


Function Descriptions

This section describes the functions available with Character Animator.

  • 0-9
  • Align
  • Alter Path
  • Breakpoints
  • Cancel All Breakpoints
  • Cancel Program Break
  • Child Data
  • Clear
  • Cursor-name Locate
  • Cursor-name Query
  • Cursor-position Reset
  • Detach from application
  • Do
  • Do At Breakpoint
  • Down-table
  • Enter
  • Enter-name Locate
  • Enter-name Query
  • Environment
  • Escape
  • Examine Breakpoints
  • Exchange
  • Exit Perform
  • Find String
  • Go
  • Hex
  • Hex/ASCII
  • Hide Monitors
  • If Breakpoint
  • Join Text
  • Look-up
  • Monitor
  • Monitor-off
  • Next Reset
  • On Count Breakpoint
  • Organize Monitors
  • Parent Data
  • Perform-level
  • Perform-view
  • Query
  • Query Data-name
  • Quit-perform
  • Refresh
  • Reset-execution
  • Same Level
  • Scroll Up/Down (continuously)
  • Scroll Up/Down (one line)(Ctrl+<left-arrow>/<right-arrow>)
  • Select Program Break
  • Set Breakpoint
  • Split Text
  • Start
  • Step
  • Step Perform
  • Text
  • This Program Break
  • Thread-local Breakpoint
  • Un-set Breakpoint
  • Up Table
  • View
  • View Programs
  • View Threads
  • Where
  • Word Left
  • Word Right
  • Zoom
  • Zoom Breakpoint
Parent topic: Functions


0-9

Enable you to vary the speed at which execution progresses in Go mode, where 0 is the slowest and 9 is the fastest.

Parent topic: Function Descriptions


Align

Repositions the program text so that the line on which the cursor is currently positioned becomes the third line on the display screen.

Parent topic: Function Descriptions


Alter Path

Searches for a file on a different path from the one you originally specified. You can enter any valid path specification, but you must terminate it with a directory separator slash ( /).

This function is offered as appropriate. There is no explicit access.

Parent topic: Function Descriptions


Breakpoints

This function displays the Breakpoints menu.

Parent topic: Function Descriptions


Cancel All Breakpoints

Resets all active breakpoints.

Parent topic: Function Descriptions


Cancel Program Break

Cancels the currently set program break; that is, a breakpoint that is activated when execution reaches the specified program.

Parent topic: Function Descriptions


Child Data

Displays the contents of the first sublevel of the item that is being queried. This query function is available when a group item is being queried.

Parent topic: Function Descriptions


Clear

Clears the current input field.

Parent topic: Function Descriptions


Cursor-name Locate

Finds the location in the source code where a data item, filename or procedure is declared.

You can use the cursor control keys to position the cursor in the program text, a structure diagram or monitor window. Data items and filenames can be located either from their monitor windows or name in the text. Procedure-names can be located from their names in the program text.

Parent topic: Function Descriptions


Cursor-name Query

Displays the contents of the data item at the current cursor position. It gives you access to other functions which enable you to modify and monitor the item. To alter the contents of the queried data type in a new value. The new value replaces the item's previous value. If the data item is a dynamic stream, you can update it using the Do function.

You can place the cursor, or select with the mouse, anywhere in the data item or in the data item window. If you do not select the name of a data item, the message:

Not data item

appears at the bottom of the screen.

Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item at the bottom of the screen.

Parent topic: Function Descriptions


Cursor-position Reset

Enables you to alter the sequence of program execution. The statement at the cursor position becomes the current statement. Execution continues from this statement. This function does not change the value of any data.

Parent topic: Function Descriptions


Detach from application

Enables you, where possible, to terminate Character Animator without terminating the application you are debugging. For example, if you are debugging a CGI application you will need to use this function to ensure that the Web Server is not terminated when you terminate Animator.

Parent topic: Function Descriptions


Do

Enables you to enter a COBOL statement to be executed immediately when debugging intermediate (.int) code. This command enables you to insert a statement in the sequence of execution but does not add it to your program code. To add it, you must key it in using a text editor then recompile your source code file. Alternatively, you can specify that it is done at a breakpoint, in which case it is saved in a file.

The COBOL statement cannot exceed 71 characters.

Entering an invalid COBOL statement gives an error message.

Note: Although most COBOL statements are supported by the Do command, Character Animator does not support some complex statements. An appropriate error message is issued in these cases.
Parent topic: Function Descriptions


Do At Breakpoint

Prompts you for a valid COBOL statement which is to be executed along with the current line. Execution is not interrupted. The line containing the breakpoint is highlighted.

When Character Animator encounters a breakpoint set with the Do option, the COBOL statement is executed immediately before the statement containing the breakpoint. In Zoom or Go mode, execution continues without a break. In Step mode, the Do-statement is executed when the statement containing the breakpoint is stepped onto. A message indicating that the statement has been executed appears at the bottom of the screen. You can repeatedly execute the COBOL statement without retyping it.

Entering an invalid COBOL statement gives an error message.

Note: Although most COBOL statements are supported by the Do command, Animator does not support some complex statements. An appropriate error message is issued in these cases.
Parent topic: Function Descriptions


Down-table

Displays the contents of the next table entry. The display of the variable used as the table subscript (shown with the data-name) reflects the current value and is changed by this function. This query function is only active when a table data item is being queried.

Parent topic: Function Descriptions


Enter

Confirms any selections you have made or data you have keyed in. It might return you to a higher level menu. Where both Escape and Enter options are available, Escape exits without making the update you have keyed in, whereas Enter makes the update and then exits.

Parent topic: Function Descriptions


Enter-name Locate

Displays a menu where you can type in the name of the item to be located in the source code. Once you have entered the name of a data-item, the cursor is moved to one of the following locations:

  • The line in which the data item is declared
  • The first occurrence of the filename in your program
  • The paragraph or section-name at the head of a procedure

depending upon what you enter at the prompt. If you are working with nested programs, you must be positioned in the program in which that data item is defined for this function to work successfully.

Parent topic: Function Descriptions


Enter-name Query

Prompts you for a data item name, which can be entered in upper or lower case. Following a successful query, the Query Data-name menu appears on the screen with the queried data-name on the information line and the value of the data item in a window or at the bottom of the screen. To alter the contents of the queried data, simply type in a new value. The new value replaces the item's previous value.

If you are working with nested programs, you must be positioned in the program in which that data item is defined for this function to work successfully.

Parent topic: Function Descriptions


Environment

Displays the Environment menu.

Parent topic: Function Descriptions


Escape

Returns to the higher level menu or exits from Character Animator altogether if you are at the top menu. Where both Escape and Enter are available options, Escape exits without making the update you have keyed in, whereas Enter makes the update and then exits.

Parent topic: Function Descriptions


Examine Breakpoints

Enables you to review your breakpoints. Each time you execute this function, the cursor is placed on the COBOL statement that has the next breakpoint set on it. After displaying the final breakpoint, the function displays the first breakpoint.

In addition, if the Breakpoint menu is active, whenever the cursor is positioned on a statement containing a breakpoint, a message appears on the bottom line of the screen.

Parent topic: Function Descriptions


Exchange

Toggles to move the cursor, and therefore the display of execution, between screens in split-screen mode. You can split the screen in two using the Split Text function.

Parent topic: Function Descriptions


Exit Perform

Executes the remainder of outstanding code in the PERFORM range which includes the current statement. Execution stops on the statement following the end of the PERFORM range.

This function operates only if the current statement is in a PERFORM range. If you select this function when you are not in the range of a PERFORM (PERFORM LEVEL = 01) and you are currently in a subprogram, you are asked if you want to leave the program. If you reply "Yes", the program execution continues in Zoom mode until the calling program is reached. If you are not in a subprogram, you are reminded that the PERFORM LEVEL = 01 by an error message.

Parent topic: Function Descriptions


Find String

Finds the next occurrence of a text string in the source program file. You can find a text string in both the main program and copybooks or in just the main program. By default, the Find function searches all files in the program. Once the find is completed, the cursor is positioned at the beginning of the text string located.

The string can be up to 32 characters long and must be entered exactly as written in the source code, using upper- and lower-case letters as appropriate.

If you want to include spaces at the end of the string, enter the spaces and terminate them with a hash mark (#). If you want to find a string in the main program only, enter the string, terminated by a # and an M. The M tells Animator to search just the main file.

If you have previously used the Find function during the current session, the last specified string appears in the prompt field. You can use the Clear function to clear the string, or press Enter to search for the same string again.

The Find function searches forward only from the current cursor position. You cannot find a string that you have already passed.

Parent topic: Function Descriptions


Go

Executes automatically each statement in the program one by one, displaying the source code on the screen as it is executed. Go mode is an automatic Step mode; you do not have to press a key to execute each statement as you do in Step mode.

You can set the Go execution speed by pressing a key in the range 0 to 9, where 0 is the slowest. You can also set the speed of execution from the Character Animator main menu by pressing a number in the range 0 to 9 without selecting the Go function. The current speed is shown on the information line. The default speed is 5.

To stop execution in Go mode and return to the Animator main menu, press Escape.

To change to Zoom mode from Go mode, press Z. The program then executes at full speed without animation. You can break out of Zoom mode using the Break key combination (Ctrl+C).

Parent topic: Function Descriptions


Hex

Toggle to change the display of a queried data item to hexadecimal format and to change the menu displayed. You can type over the data using either text or hexadecimal code.

Parent topic: Function Descriptions


Hex/ASCII

Toggles to move the cursor between the hexadecimal and ASCII data representations. It is available when you are displaying a queried data item in hexadecimal format. You can type over the data using either text or hexadecimal code.

Parent topic: Function Descriptions


Hide Monitors

Hides all monitors. They only reappear on the screen if their value changes or if a Refresh function is performed.

Parent topic: Function Descriptions


If Breakpoint

Enables you to set a conditional breakpoint. A conditional breakpoint is a breakpoint that takes effect only if the specified condition is true when the breakpoint is reached. The line containing the breakpoint is highlighted.

The submenu prompts you to enter a condition in COBOL format. Once you have entered a valid statement, pressing Enter sets a conditional breakpoint at the current cursor position. Execution stops at this breakpoint only when the condition is true.

If the condition you specify is false, Character Animator ignores the breakpoint and continues executing the program. You can enter any condition enabled by COBOL syntax, including combinations of conditions. You cannot set a conditional breakpoint on a statement that already has an ordinary breakpoint, and vice versa.

Parent topic: Function Descriptions


Join Text

Cancels the effect of the Split Text function and returns you to a single screen display of source code. You can use the Refresh Text function to repaint the screen after using the Join Text function.

Parent topic: Function Descriptions


Look-up

Repositions the program text so that the line number specified at the prompt becomes the third line on the screen. This provides a quick and easy means of locating a line in your code without having to scroll through it line by line.

Parent topic: Function Descriptions


Monitor

Enables you to display the content of a queried data item as it changes during program execution.

Parent topic: Function Descriptions


Monitor-off

Switches off the monitor display of a queried data item.

Parent topic: Function Descriptions


Next Reset

Causes the next statement to become the current statement without executing any code. This function does not change the value of any data.

Parent topic: Function Descriptions


On Count Breakpoint

Enables you to set periodic breakpoints that halt execution immediately before the specified statement has been executed the specified number of times. For example, if you specify a frequency of 3, set the breakpoint and then Zoom, execution breaks the third time that the breakpoint is encountered, and every third time subsequently. The line containing the breakpoint is highlighted.

The frequency must be in the range 2 through 255 inclusive. Once the frequency has been entered, the normal Breakpoint menu appears, enabling you to set the breakpoint or to specify a breakpoint with the Do function. The number selected for the desired frequency appears on the information line.

Parent topic: Function Descriptions


Organize Monitors

Reorganizes the monitors on your screen to their default positions.

Parent topic: Function Descriptions


Parent Data

Displays the contents of the data item in which the selected item occurs. This query function is available when a member of a group item is being queried.

Parent topic: Function Descriptions


Perform-level

Displays the Perform-level menu.

Parent topic: Function Descriptions


Perform-view

Views and changes context to a different level in the CALL/PERFORM stack.

Parent topic: Function Descriptions


Query

Displays the Query menu.

Parent topic: Function Descriptions


Query Data-name

Displays the Query Data-name menu.

Parent topic: Function Descriptions


Quit-perform

Exits from the current PERFORM range without executing the remaining statements. The next executable statement after the PERFORM statement becomes the current statement. You can select this function only when inside the range of a PERFORM.

This function does not change the value of any data.

Parent topic: Function Descriptions


Refresh

Refreshes the display of all source text and the monitored variables.

Parent topic: Function Descriptions


Reset-execution

Displays the Reset-execution menu.

Parent topic: Function Descriptions


Same Level

Displays the content of the next data item that has the same level as the queried data item. The data-name appears on the information line.

Parent topic: Function Descriptions


Scroll Up/Down (continuously)

Scrolls the text rapidly toward the beginning (Up) or end (Down) of the file. Press any key to stop scrolling in either direction.

Parent topic: Function Descriptions


Scroll Up/Down (one line)(Ctrl+<left-arrow>/<right-arrow>)

Enables you to scroll up or down, line by line, by using the <left-arrow> or the <right-arrow> key respectively.

Parent topic: Function Descriptions


Select Program Break

Prompts you for the name of the program at which you want execution to halt; that is, a program break. A program break is a breakpoint that is activated when execution reaches the specified program.

Parent topic: Function Descriptions


Set Breakpoint

Sets a breakpoint at the current cursor position. When Character Animator encounters the breakpoint, execution halts before executing the statement. The statement containing the breakpoint becomes the current statement. The line containing the breakpoint is highlighted.

Program breakpoints remain set, so if you leave animation without unsetting (canceling) a breakpoint, the breakpoint is set the next time you animate the program. You can set up to 100 breakpoints in each program.

When a breakpoint is reached, you see the message:

Breakpoint encountered

at the bottom of your screen.

Parent topic: Function Descriptions


Split Text

Enables you to split a screen horizontally in two at the current cursor position. You must have a minimum of four lines in a split screen.

When you have split the screen, you can execute in either half. The Exchange function moves the cursor between the halves.

Split-screen mode is particularly useful if you want to query data declarations or a set of variables in one screen while executing in the other.

Parent topic: Function Descriptions


Start

Makes the first executable statement in the program the current statement. No code is executed.

This function does not change the value of any data, so if you use this function to test your program as though you had not executed any code, make sure you reinitialize all of your variables before continuing.

Parent topic: Function Descriptions


Step

Executes the current statement and places the cursor on the next executable statement, which it also highlights.

Parent topic: Function Descriptions


Step Perform

Causes execution in Zoom mode of the entire PERFORM range or subprogram if the current statement is a PERFORM or CALL statement. Execution stops on the statement following the end of the PERFORM range or subprogram.

Parent topic: Function Descriptions


Text

Changes the display of a queried data item to text format and changes the menu displayed if accessed from the Query Data-name menu. You can type over the data using either text or hexadecimal code.

Alternatively, if accessed from the Character Animator main menu, this function displays the Text menu.

Parent topic: Function Descriptions


This Program Break

Sets a program break; that is, a breakpoint that occurs when the selected program is re-entered. For example, if This Program Break specifies a program break for the current program, a breakpoint occurs when the program is re-entered after a subprogram call.

Parent topic: Function Descriptions


Thread-local Breakpoint

Sets a breakpoint that is only active for the current thread at the current cursor position. Any other thread executing this statement does not stop.

Parent topic: Function Descriptions


Un-set Breakpoint

Cancels a breakpoint at the current cursor position.

Parent topic: Function Descriptions


Up Table

Displays the contents of the previous table entry. The display of the variable used as the table subscript (shown with the data-name) reflects the current value and is changed by this function. This query function is active only when a table data item is being queried.

If you select an entry that is before the first table entry, a warning beep is sounded.

Parent topic: Function Descriptions


View

Enables you to view the user screen during animation. The screen changes whenever you execute a statement that echoes a character to the screen. Press any key to return to the source code, unless you are using cross-session animation , in which case the Character Animator screen returns automatically after n seconds.

View has no effect if you are using cooperative animation.

Parent topic: Function Descriptions


View Programs

Lists all programs currently loaded. Also enables you to change context to another program to query it, or set breakpoints.

Parent topic: Function Descriptions


View Threads

Lists all threads running within the application. Enables control over those threads by freezing or thawing a thread. Also enables you to change context to another thread.

Parent topic: Function Descriptions


Where

Moves the cursor to the start of the current statement, and repositions the program text so that the current statement becomes the third line on the screen.

Parent topic: Function Descriptions


Word Left

Moves the cursor to the previous word in the program text. If the cursor is positioned on the first word on a line, this function moves the cursor to the last word on the previous line and scrolls the text if necessary.

Parent topic: Function Descriptions


Word Right

Moves the cursor to the next word in the program text. If the cursor is positioned on the last word on a line, this function moves the cursor to the first word on the next line and scrolls the text if necessary.

Parent topic: Function Descriptions


Zoom

Executes the program at full speed, displaying the user screen rather than the Character Animator screen containing the source code.

You can break out of Zoom mode by pressing Ctrl+Break, unless your program is executing an Enhanced ACCEPT, in which case the CTRL+Break terminates the ACCEPT, and animation continues.

If you do not break out of Zoom mode, execution continues until a STOP RUN statement is encountered. At this point the Animator screen is restored and Step mode resumed.

Parent topic: Function Descriptions


Zoom Breakpoint

Sets a temporary breakpoint at the current cursor position and enters Zoom mode. When this breakpoint is encountered (or execution is interrupted for any other reason) the breakpoint is unset.

Parent topic: Function Descriptions


Run-time System Error Messages

A run-time system error message is returned on a program that is syntactically correct but which encounters problems during the actual running of the intermediate code. You could receive such an error if you try to access a file in the wrong mode or if you use a corrupt file. Refer to your Error Messages for complete descriptions of possible run-time errors.

Character Animator displays run-time errors on the bottom line of the screen in the format described in your Error Messages.

Parent topic: Working With Character Animator
Related reference
Run-time System Error Messages


Directives for Character Animator

  • Directive Descriptions
  • Using COBANIMOPT
Parent topic: Using Character Animator
Related information
Specifying Character Animator Directives


Running Applications

You run a program from a terminal window in the same way whether you are running intermediate code, generated code or callable shared objects.

Running native COBOL programs

You use cobrun to run native COBOL programs.

You can specify switches to control the behavior of the program at run time, how you can specify parameters on the command line that your program can then read, and how you can control the behavior of the run-time system.

You can get statistics on the run-time performance of a COBOL program using the Profiler utility.

Running managed COBOL programs

You use cobjrun to run JVM COBOL programs. This initializes the COBOL Run-Time System and then starts the JVM to run the class. The JVM provides all necessary management services which also enable seamless interoperation of COBOL programs with programs in other JVM languages.

You also use cobjrun to run native COBOL applications calling Java or to call Java applications from a COBOL run-time environment.

  • Creating Runnable Programs
  • Running Native Applications
  • Running Managed Code Applications
  • Run-time System Error Messages
  • Using the Consolidated Tracing Facility
Parent topic: Developing Applications


Creating Runnable Programs

You can create runnable programs in two ways:

  • You create an .int file, a .gnt file or callable shared object. These types of file are dynamically loadable and can be run without having to link into a system executable file.
  • You can create a linked system executable file, which can be run directly from the command line.

See Packaging Applications for an introduction to executable file types.

When you run your program, you can specify:

  • Switches that control the behavior
  • Command-line parameters that your program can read
Note: If you are using the 64-bit version of this product, the names of tools might vary. For more information see Working in 32-bit and 64-bit Modes.
Parent topic: Running Applications
Related concepts
Working in 32-bit and 64-bit Modes
Packaging Applications


Running Native Applications

  • Running Programs
  • Run-time Configuration
Parent topic: Running Applications


Running Programs

The syntax for invoking a linked system executable file varies slightly from that for invoking a dynamically loadable module. The command line for running each type of program is described below.

Before you can run a program you must first set one or more of the environment variables SHLIB_PATH, LIBPATH and LD_LIBRARY_PATH. See Environment Variables for details.

  • Command to Run a Linked System Executable Program
  • cobrun Command
Parent topic: Running Native Applications
Related reference
Environment Variables


Command to Run a Linked System Executable Program

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

program-name [parameters]

where:

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


cobrun Command

Restriction: This command is supported for native COBOL only.

To run dynamically loadable programs (that is, callable shared objects, or .int or .gnt files) use the following command:

cobrun [switch-params] program-name [program-params]
Note: For multi-threaded programs, use cobrun_t instead.

where:

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

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

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.

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

Comments:

Use cobrun in conjunction with the effective working mode to run in a 32-bit or 64-bit environment; alternatively, use cobrun32 or cobrun64 to directly invoke those environments.

  • Switches
  • Setting Switches
  • TMPDIR Environment Variable
  • Accessing Command Line Parameters
Parent topic: Running Programs
Parent topic: Running an Application from the Command Line


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: programmable switches and run-time switches.

  • Programmable Switches
  • Run-time Switches
Parent topic: cobrun Command
Related reference
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


Programmable Switches

Programmable switches consist of a digit in the range 0 through 8. These switches correspond to the COBOL switches that you define in the Special-Names paragraph of your program, enabling you to set these switches on or off when your program begins executing. Any changes made to the settings of these switches using the COBOL statement SET mnemonic-name TO ON or OFF is not effective once the application has terminated. For details of how to use the SET statement with COBOL switches, see your Language Reference.

Parent topic: Switches
Related reference
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


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.

Parent topic: Switches
Related reference
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


Setting Switches

Switches that you specify before running your program can be set using the COBSW environment variable. Alternatively, if you are running a dynamically loadable program, you can set them on the cobrun command line; however, we recommend that you use COBSW instead.

To set a programmable switch or run-time switch on, precede it with a plus sign (+); to set it off, precede it with a minus sign (-).

If you do not explicitly set any switches either in the COBSW environment variable or on the cobrun command line, then their default values apply.

The format for setting switches in COBSW is:

The format for setting switches on the command line is:

where the parameters are:

* | A programmable or run-time switch. The plus sign (+) sets the switch s on, while the minus sign (-) sets it off.
* | 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.
Note: You should note the following when setting switches:
  • 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.
  • Examples
Parent topic: cobrun Command
Related reference
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


Examples

Setting COBSW to:

COBSW=+1+4

sets the programmable switches as follows:

0 | off
1 | on
2 | off
3 | off
4 | on
5 | off
6 | off
7 | off
8 | off

The command:

cobrun -2+5-7+7 ./myprog

loads the program myprog.int, myprog.gnt or myprog.so from the current directory (depending on the program search order) with programmable switches 5 and 7 on and switch 2 off. Note that since the last setting of switch 7 (that is +7) is the one used, that switch is turned on. Switches 0, 1, 3, 4, 6 and 8, which are not specified, are off by default.

Parent topic: Setting Switches
Related reference
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


TMPDIR Environment Variable

The TMPDIR environment variable enables you to specify a different path in which to store temporary files. This can be necessary if the run-time system needs to page data to disk when creating heaps or sorting.

Parent topic: cobrun Command


Accessing Command Line Parameters

You can access program parameters in a number of ways. For example, you can use one of the following formats of the ACCEPT statement:

accept data-name from command-line

or

accept data-name from mnemonic-name

where the parameters are:

data-name The data item to receive the command line parameters.
mnemonic-name Defined in the Special-Names paragraph as:
command-line is mnemonic-name

For full details on the available methods of accessing command line parameters see Writing Efficient Programs in your Program Development book.

  • Example
Parent topic: cobrun Command


Example

Running program myprog with the command line:

COBSW=+1+7
export COBSW
myprog in-file.dat clear

causes the statement:

accept cmd-line from command-line

in the program to place

in-file.dat clear

into the data-item cmd-line.

Parent topic: Accessing Command Line Parameters


Run-time Configuration

You can configure certain run-time behavior through the run-time configurables. There are three types of run-time configurable: environment variables, run-time tunables, and run-time switches.

This section describes the use of run-time tunables. See Environment Variables for a list of environment variables available. See Switches for information about run-time switches.

  • Run-time Configuration File
  • Format of a Run-time Configurable
  • Run-time Tunables
Parent topic: Running Native Applications
Related reference
Environment Variables
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


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 configurables. It is shared by all users of this product.

The run-time configuration file is a text file, which you can edit with your standard text editor. It is an optional file (no error will be issued if it does not exist) with the default name $COBDIR/etc/cobconfig. You can specify a filename for the configuration file by setting the environment variable COBCONFIG; for example:

COBCONFIG=$HOME/myconfig
export COBCONFIG

Each run-time configurable appears on a new line. Blank lines are ignored. A comment line starts with a #; however, as the configuration file is processed at run time, we advise that you limit your comments, in order to keep to a minimum the time it takes to process it. The maximum number of characters permitted in a comment line is 80, including any new-line or carriage return characters that may be placed at the end of the line by some editors.

You can use the configuration file to:

  • Set environment variables, such as dd_ filename mappings, or other significant environment variables. Environment variables set in this way override values already set in the environment.
  • Set run-time tunables. These control the behavior of certain aspects of the COBOL run-time system.
Parent topic: Run-time Configuration
Related reference
Environment Variables
GUID-91372FA5-1AE9-41F8-9312-F93AAF4E6420.ditamap


Format of a Run-time Configurable

Each run-time configurable is specified on one line in the run-time configuration file. The format for run-time tunables is:

set configurable_name=value

while for environment variables, the format is:

setenv configurable_name value
The parameters are:
configurable_name
The name of the run-time configurable. This will be the name of a run-time tunable described in this chapter, or an environment variable described in the appendix Environment Variables. For details on dd_ filename mappings see your File Handling book.
value
The value to be assigned to the run-time configurable. The values that can be assigned to a run-time tunable are described in this chapter. For a run-time tunable, value is validated according to the type and values allowed for that tunable, and the value of cobconfig_error_report.

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 with 0x.

Note that each space in the definition can be replaced with tabs or more than one space.

For example

setenv dd_MYFILE /usr/mydir/myfile
set cobconfig_error_report=TRUE
Parent topic: Run-time Configuration


Run-time Tunables

The run-time tunables are listed and described in Run-time Tunables.

Parent topic: Run-time Configuration
Related reference
Runtime Tunables


Running Managed Code Applications

  • Java/COBOL Application Launcher
  • Using the Java/COBOL Application Launcher from the Command Line
Parent topic: Running Applications


Java/COBOL Application Launcher

The Java/COBOL application launcher, cobjrun, is used to launch:

  • Native COBOL applications calling Java
  • JVM COBOL applications
  • Java applications which call native COBOL from a COBOL Run-Time environment

cobjrun is the trigger for cobjrun32 and cobjrun64 and should be used instead of your usual Java application launcher as it sets up your environment to correctly manage both the COBOL run-time system and the Java Virtual Machine.

  • Using the Java/COBOL Application Launcher from the Command Line
Parent topic: Running Managed Code Applications
Parent topic: Considerations
Related reference
Using the Java/COBOL Application Launcher from the Command Line


Using the Java/COBOL Application Launcher from the Command Line

The command to invoke the Java/COBOL application launcher 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.
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 Managed Code Applications
Parent topic: Java/COBOL Application Launcher
Related concepts
Setting Up the Environment for Java and COBOL
Related reference
Java/COBOL Application Launcher


Run-time System Error Messages

A run-time system error message is returned on a program that is syntactically correct but that encounters problems during the actual running of the program. For example, you could receive such an error if you try to access a file in the wrong mode or if you use a corrupt file. See Run-time System Error Messages for a description of the format and all the possible run-time system errors.

Note: If you try to run a program, but the run is not successful, you should be aware that the program counter (pc) values for native code generated files, callable shared objects and system executable files are undefined.
Parent topic: Running Applications


Using the Consolidated Tracing Facility

The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of Micro Focus software components. The only component currently enabled to provide information using the Consolidated Tracing Facility is the run-time system.

To use the Consolidated Tracing Facility you perform the following steps:

  1. Edit a side file to enable tracing and define the tracing information you want to capture. You use the entries in the side file to specify information such as the applications you want to trace, the severity level of tracing messages you want to see, and details of the text file that the trace information is written to.
  2. Run the applications. The Consolidated Tracing Facility uses a module called an emitter to output all the relevant information. The only emitter currently available writes the information to a text file.
  3. Examine the results. The completeness of the information written to the trace file provides you with all the relevant diagnostic information to help you troubleshoot problems.
Parent topic: Running Applications
Related reference
Consolidated Tracing Facility


Test Coverage (Native COBOL)

Note: This facility is supported in native COBOL only.
  • Overview - Test Coverage
  • How To...
  • Restrictions when Using Test Coverage
  • Troubleshooting Test Coverage
  • Test Coverage Error Messages
  • How To...
Parent topic: Developing Applications
Parent topic: Command line reference


Overview - Test Coverage

Note: This facility is supported in native COBOL only.

Development teams often need to show that they have performed testing which has covered all logical paths through a program. Using the test coverage utility, they can produce a report to illustrate the extent of test coverage, and can promote this report along with the source code at the various stages of the development lifecycle.

This section provides information about using test coverage from the command line. Visual COBOL provides IDE integration of test coverage within - see Code Coverage (Native COBOL) .

Test coverage results can be included as part of the output of any Continuous Integration (CI) testing that the teams are performing.

Results and report files

While a program is running in test coverage mode, code execution is logged for each program and sub-program that has been compiled with the TESTCOVER directive set. The results are stored in a binary results file, which has the filename extension .tcz. The information stored in the results file depends on how you configure test coverage.

Running a program in test coverage mode uses significantly more resources than running the same program without test coverage enabled. As a result, we recommend that you use test coverage only in development systems; we recommend that you do not use test coverage in production systems.

As the results file is a binary file, it has to be formatted to produce a text or HTML report file. You can create a report file from the command line, using the reporting utility cobtcreport . Reports can be formatted to produce a plain text (.txt) file or an HTML (.htm) file.

You can also tag statements in your source code and use test coverage to report on whether these statements have been executed. This is particularly useful if you want to see the coverage of new or changed lines in your source code.

Using test coverage information in Continuous Integrating (CI) testing

In a CI environment, it might be better to create the test coverage results in an alternative format which is better suited for the CI system and for the way the development team wants to integrate the results with the CI. Visual COBOL provides a command line utility for test coverage, tcutil, which enables you to convert the binary results file into an XML file. After the results are in XML format, you can use a Third-Party utility such as an XSLT processor to transform the XML file into a format which is suitable for your CI.

  • Test Coverage Configuration File
  • Test Coverage Report Files
  • Format of a Test Coverage Report
  • Recompiling Programs
  • Reporting on Tagged Lines
  • Test Coverage Tag File
  • Test Coverage Utility Program (tcutil)
Parent topic: Test Coverage (Native COBOL)
Parent topic: Test Coverage (Native COBOL)
Related concepts
Including Code Coverage in a Continuous Integration Process
Related reference
TESTCOVER
Related information
To create test coverage reports
To use test coverage from the command line
To report on tagged lines


Test Coverage Configuration File

Note: This facility is supported in native COBOL only.

If you are using Test Coverage from the command prompt, you need to use it with a configuration file. An example test coverage configuration file, default.tcf, is supplied in $COBDIR/etc. You can edit this or use it as is.

The configuration is a text file that has the format:

[TESTCOVER]
; comment
RESULT filename.tcz [ACCUMULATE]
ECHOLOG [YES|NO]
LOGNAME [filename]
where the options are:
[TESTCOVER]
The configuration file must contain this tag. It identifies the file as a test coverage configuration file.
; comment
The semicolon (;) identifies a comment line. The semicolon must be positioned in the first column of the file. Comments can appear anywhere in the file. Optional.
RESULT filename.tcz [ACCUMULATE]
Specifies the results (.tcz) files to create. Your configuration file must contain a RESULT keyword.
ACCUMULATE
Optional. If specified, test coverage accumulates the results of succesive runs in a single results file filename.tcz.

If you omit ACCUMULATE, on each run test coverage overwrites filename.tcz, unless you use the variable version of filename.tcz (see below).

filename.tcz
The name of the file that is to hold test coverage results. If the file does not exist, a new file is created.

filename.tcz can include the following:

  • an absolute or relative pathname. If the pathname includes the name of a folder that does not exist, the folder is created, for example:
    RESULT tcresult.tcz

    creates the results file tcresult.tcz in the current folder, while

    RESULT ./results/tcresult.tcz

    creates the results file tcresult.tcz in the folder results, which will be created below the current folder.

  • a variable filename, by using the question mark (?) wildcard in the name.

    In this case, the filename should be specified in the form str????.tcz, where str can be any appropriate string. Test coverage then looks for files which match the wildcard string str????.tcz. It then takes the highest numeric value found in the wildcard character positions, increments that value, and uses this as the filename to which to write results.

    For example, if you specify the filename as x????.tcz, and the files x0001.tcz and x0002.tcz already exist, then test coverage automatically creates x0003.tcz.

    The number generated has as many digits as there are wild cards. For example x??.ccz generates x01.ccz, x02.ccz, and so on.

    Using a variable filename enables you to create separate results files for multiple runs of test coverage, without needing to change the configuration file for each run.

  • the token <pid>, which is replaced by the current process id, for example:
    RESULT myres_<pid>.tcz

    creates the results file myres_2749.tcz, assuming a process id of 2749.

ECHOLOG [YES|NO]
Specifies whether the test coverage summary should be echoed to the screen or not. Optional.

If you do not specify an option, or the keyword is omitted, the default is YES.

Use ECHOLOG NO if your application might have problems accessing the screen; for example, during debugging.

LOGNAME [filename]
At the end of each run, the test coverage summary is appended to filename. If filename is not specified, a default file is used, with the name projectdir\testcover\testcover.log, where projectdir is the folder in which your project is located. Optional.

The filename specified for the LOGNAME keyword can include the token <pid>. See the description of the RESULT keyword for more information on this token.

We recommend that a configuration file should contain at least the following:

[TESTCOVER]
ECHOLOG NO
RESULT filename.tcz ACCUMULATE
Note: Only one RESULT, ECHOLOG and LOGNAME keyword are allowed. You can have more than one instance of each of the keywords if they are non-active; that is, preceded by the semicolon (;) comment character.

Examples of the RESULT keyword

RESULT /usr/mydir/results/tcresult.tcz ACCUMULATE

Test coverage accumulates all results in the tcresult.tcz, located in the folder results relative to the current folder.

RESULT /usr/mydir/tcresult.tcz

As the ACCUMLATE verb has been omitted, test coverage stores its results in the file tcresult.tcz, which will be overwritten on each run.

RESULT run????.tcz

Separate results files are used for each run. In this example, on the first run, test coverage would create the results file run0001.tcz. On the second run, test coverage would create the results file run0002.tcz. The number would increment for each additional run.

Configuration file example

[TESTCOVER]
RESULT run????.tcz
ECHO NO
LOGNAME testcover.log

This example shows a complete configuration file. Separate results files are used for each run. Results are not to be echoed to the screen. Summary results are to be appended to testcover.log.

Parent topic: Overview - Test Coverage


Test Coverage Report Files

Note: The following applies to native code only.
The following files are created:
  • An index file, called tcindex.htm or tcindex.txt
  • The .htm or .txt report files
You can view the generated .txt file in any editor, or open the .htm file in your browser. The index file is overwritten every time you produce reports.
Parent topic: Overview - Test Coverage


Format of a Test Coverage Report

Note: This facility is supported in native COBOL only.

When you use cobtcreport to create reports, the following files are produced:

  • An index file (tcindex.htm), in HTML format, which links to your reports.
  • Your reports, in either HTML (.htm) or text (.txt) format.

The information contained in the .htm or .txt files is the same; the .htm format enables the report to contain links to sections within the report.

The picture below shows an example tcindex.htm index report.

Figure 1. Test Coverage Report
Test Coverage Report

The Contents section lists all of the programs in this report. If you had specified the COMBINE option, all the programs would be listed here, with the reports displayed further down the document. This report contains links to two report files: swap-elements.htm and vsort.htm. If you change the location of the report files, enter the new location in the Report Location field so that this report can locate them.

Below is the top of the report for vsort.htm. Report files saved as text contain exactly the same information, and differ only in containing links and formatting enabled by HTML. The explanation of the report contents given below also applies to text files.

Figure 2. Test Coverage Report
Test Coverage Report

The Contents section lists only one program - if we had specified that all the results were to be combined in this report, there could potentially be a large number of programs listed in the Contents section, and we would be able to click on a program name to jump straight to the section of the report that contained the results for that program.

On the row containing the name of the program, you can use the pull-down menu of Unexecuted Blocks and click GO to navigate directly to a specific unexecuted block in that program.

The rightmost column, block, shows the blocks of code in your program. Blocks can be thought of as a number of statements with no jumps: when you've executed one line, the next is executed. They are executed consecutively. Numbering starts from zero. The block starting on line 17 as shown above covers four lines of code, and then has a jump, which means the next block starts.

The other column on the right, count, shows how many times the block has been executed.

Below is the bottom of the report for vsort.htm.

Figure 3. Test Coverage Report
Test Coverage Report

The summary at the bottom shows the percentage of statements, blocks, sections and CALL statements which have been executed in your program.

The number of basic blocks shown tells you that there are five areas of code, thirteen statements and one section/ paragraph which have not been executed.

Parent topic: Overview - Test Coverage


Recompiling Programs

Note: The following applies to native code only.

If you recompile a program that has already been used to produce a .tcz results file, you need to be aware that the .idy file required for reporting the source lines executed will be overwritten and so will give a mismatch on the source lines in the original .tcz file. You will be given a warning when trying to produce a report if an .idy file cannot be found to match exactly a particular program.

Parent topic: Overview - Test Coverage


Reporting on Tagged Lines

Note: The following applies to native code only.

It can be useful to report on the coverage of new or changed lines in your source code. You can do this by tagging the new or changed lines, and then creating a report that provides additional information specific to these tagged lines. You can choose to report on some or all of your tagged lines.

You first have to create tags in your source code. The tags can be any appropriate string (such as, for example, sdnw01, or chng02) entered in the left (columns 1 through 6) or right (columns 73 through 80) margin of your source code. Your tags can only be six characters long.

You then run your program in test coverage mode.

You can create the tag-specific information in the test coverage report using the command line cobtcreport utility.

Parent topic: Overview - Test Coverage


Test Coverage Tag File

Note: This facility is supported in native COBOL only.

The test coverage tag file is used by cobtcreport to identify tags in your source code, enabling cobtcreport to provide information specific to the tagged lines.

The tag file is a text file that contains a list of the tags for which you want information, and a keyword specifying which margin of your source code your tags are in.

The format of the tag file is:

margin
tag1, [tag2, ...]
# comment
where the parameters are:
margin
The margin used by your tags. This can be set to either:
  • @LEFT, which specifies that your tags are in the left margin (columns 1 through 6)
  • @RIGHT, which specifies that your tags are in the right margin (columns 73 through 80).

You can specify one keyword or the other, but not both. By default, margin is set to @LEFT.

tag1, [tag2, ...]
A comma-separated list of tags. The list can contain up to 20 tags. You can also split the list over multiple lines. In this case you need not delimit the last item in the line with a comma. For example:
new1, new2, new7
chg1,chg5
upd4, upd5,up8
#
The # indicates a comment line. Comment text is optional.
Parent topic: Overview - Test Coverage


Test Coverage Utility Program (tcutil)

The Test Coverage Utility Program (tcutil) is a command line utility that enables you to convert the test coverage binary results file into an XML file to help you integrate test coverage with a Continuous Integration system. You can use a Third-Party XSLT processor to transform the XML file into a format which is suitable for your CI.

Syntax

tcutil requires that you specify one or more .tcz files and has the following command line syntax:

tcutil option[option…] tczfilename [tczfilename…]

Where:

tczfilename
The test coverage binary results file (.tcz). You can find the .tcz files in the locations specified in your test coverage configuration file .tcf.

And option is one of the following:

-x [xmlfilename]
Specify a name, xmlfilename, for the output XML summary file. The XML schema file for this file is mftcov.xsd in <installdir>/etc/schema/mftcov.xsd.

If you do not specify a file name for xmlfilename, the utility program generates a file that has the base name as the input .tcz file, tczfilename, if only one .tcz file is specified. If more than one .tcz files are specified, the utility program generates a tcresult.xml file.

-t nnn
Specify a threshold in percentage, nnn, to ensure the test run fails if less than nnn% of the statements are covered. nnn must be a numeric integer value:
  • If the overall threshold is less than nnn%, return a non-zero exit code.
  • If the overall threshold is greater than nnn%, return a zero exit code.
-u
Include any unexecuted programs. The information about these is determined based on the information in the .tcz file and any .idy files in either the current folder or in folders specified by the COBIDY environment variable. This option requires the application to be compiled with the COLLECTION Compiler directive.
-s xslfilename
Include a direct reference to the stylesheet, xslfilename, in the output XML summary file specified by the -x option.
Parent topic: Overview - Test Coverage
Related tasks
Including Code Coverage in a Continuous Integration Process
Related reference
Collection


How To...

  • To use test coverage from the command line
  • To create test coverage reports
  • To report on tagged lines
  • Including Code Coverage in a Continuous Integration Process
Parent topic: Test Coverage (Native COBOL)
Parent topic: Test Coverage (Native COBOL)


To use test coverage from the command line

Note: This facility is supported in native COBOL only.
  1. Create a test coverage configuration file.
  2. Set the TESTCOVER environment variable.

    The value of the variable should be the path of the test coverage configuration file.

  3. Build your application with the TESTCOVER compiler directive set.
  4. Run your application.

    Depending on how you set the options in your configuration file, one or more results (.tcz) files are created.

  5. If you want test coverage to report on tagged lines, create a tag file.
  6. Use cobtcreport to produce reports from the results files. If you want to include information on tags, set the taglines option.
Parent topic: How To...
Parent topic: How To...
Related reference
TESTCOVER


To create test coverage reports

Note: This facility is supported in native COBOL only.
  1. Locate the .tcz file in the location specified in your .tcf file.
  2. From a command prompt, enter:
    cobtcreport filename [NO]options

    where:

    • filename is one of the following:
      • One or more .tcz files, separated by a comma. For example:
        cobtcreport file1.tcz,file2.tcz,file3.tcz... [NO]options
      • Or a text file, filelist.txt, containing a list of all .tcz files to be reported on.

        You can use either a space, a comma or new lines as separators for the .tcz files in filelist.txt.

        The file must be referenced using @ as follows:

        cobtcreport @filelist.txt [NO]options
    • options are shown below. Many of the options can be prepended with no, which means the option will not be acted upon. Options are all off by default, unless otherwise stated. They can be specified in any order. None is mutually exclusive.
      [no]blocknum | Displays the basic block number of each statement in the rightmost column. Blocks can be thought of as a number of contiguous statements with no jumps. They are executed consecutively. Lines within a block will have the same basic block number. There is a limit of 65535 basic blocks per program.
      [no]browse | Opens your browser with the report file in HTML format.
      [no]calls | Gives a summary of CALLed subroutines. Called subprograms are listed alphabetically. The CALL overhead in COBOL can be considerable, and this lets users identify the most commonly called routines.
      [no]combine | Produces a single text and/or HTML file, instead of individual ones on a per program basis.
      [no]datafreq | Computes the total execution count for each data item in the program. ie. it totals the execution counts for all statements in which a data item is referenced. This report also identifies misaligned 2-, 3- or 4-byte items.
      [no]echo | Echoes output to the console.
      [no]html | Creates the output in HTML format. If you do not specify an output format, HTML is on by default: use [no]html if you do not want an .htm output file.
      [no]leftcol | Displays the columns for counts and block numbers on the left of the report.
      reportloc(location) | Creates the report in the folder specified by location.
      rootname(rootname) | Creates reports with a name prepended with rootname.
      [no]source | Produces a listing of the program source, showing execution counts for every statement. This option is on by default. Both the .idy and .cbl source file need to be present for the execution counts to tally correctly.
      taglines(tagfile) | Specifies the tag file, which identifies tags in your source code for which you want the report to generate specific information.
      text | Creates the output in text format, with a .txt extension.
      [no]verbs Gives a summary of COBOL verbs used. Verbs are listed in descending order of execution. The columns used are:
      • occurs - which shows the number of occurrences of that verb in a program
      • coverage - which shows the number of this type of statement that were covered, and what percentage of these verbs it represents
      • executed - which is the total of all the execution counts for this type of statement, and the percentage of the program's total execution count this represents
  3. Open the resulting index file to view the tcindex.txt or .htm file.

If you want to simply list the programs in your .tcz file, without looking at the report file, from a command prompt enter:

cobtcscan filename

where filename is the name of your .tcz file.

Parent topic: How To...
Parent topic: How To...
Related reference
TESTCOVER


To report on tagged lines

To be able to produce a test coverage report with information specific to tagged lines, you must first enter tags in your source code. You can produce the report using cobtcreport.

Before you can format and display a report, you must create a test coverage binary file (a .tcz file) by running test coverage.

  1. Enter the command:
    cobtcreport filename taglines(tagfile) [options]

    where filename is the .tcz file you are using to create the report, tagfile is the file that specifies the tags to be used, and options are other cobtcreport options.

    For example:

    cobtcreport myreport.tcz taglines(tagfile.txt)
Parent topic: How To...
Parent topic: How To...
Related reference
TESTCOVER


Including Code Coverage in a Continuous Integration Process

The process for producing code coverage results (as binary .tcz results files) from applications running under a Continuous Integration (CI) system is the same as when running the application locally from the command line. You need to compile and execute the applications with test coverage - see To use test coverage from the command line.

Format of the results files

You would typically configure the CI machine to store the test coverage results as a CI artifact file for the CI build. Those results could be stored in one or more of the following formats:

  • Binary format - as a .tcz results file.
    Tip: You can load .tcz files in Visual COBOL for Eclipse to examine the results in greater detail.
  • HTML or TXT - report files produced as described in To create test coverage reports.
  • XML format - produced with the Test Coverage Utility Program (tcutil). You can use tcutil with different options depending on what
    • Use the -x option:
      tcutil -x myapp.xml myapp.tcz

      Produces an XML file, myapp.xml, which includes a summary of the test coverage results. In most cases, you muct include the stylesheets as artifact files alongside the XML file to ensure it is rendered correctly

      .
      Tip: Use a Third-Party XSLT processor such as Saxon or xsltproc to transform myapp.xml to an HTML page using the sample stylesheets mftchtml.xsl and mftchtml.css stored in <installdir>\src\tcov
    • Using both the -x and -s options:
      tcutil -x -s myapp.xsl myapp.tcz

      Produces an XML file, myapp.xml, that when displayed is an HTML page of results. The results on the HTML page are rendered using the sample stylesheets mftchtml.xsl and mftchtml.css stored in <installdir>\src\tcov.

See Test Coverage Utility Program (tcutil) for details.

Displaying the results in the CI

Consider installing a plugin in for your CI system to configure the CI build so that the results are displayed directly on the CI dashboard. An example of such plugin is Plot for Jenkins. Plot requires input in CSV format which it then visualizes on the Jenkins dashboard.

Use tcutil with the -x option and a Third-Party XSLT processor to transform the results file, myapp.xml, into a CSV file. See the sample file mftcplot.xsl in <installdir>\src\tcov.

Configuring the CI build to fail

You can use tcutil with the -t option to configure the CI build to fail if the overall test coverage fails to meet a certain threshold level (in percentage). In the following example, tcutil returns a non-zero exit code if the overall code coverage in the .tcz file is less than 80%:

tcutil -t 80 myapp.tcz
Parent topic: How To...
Parent topic: How To...
Related reference
Test Coverage Utility Program (tcutil)
Collection
Related information
Overview - Test Coverage


Restrictions when Using Test Coverage

Note: This facility is supported in native COBOL only.
The following restrictions apply to test coverage:
  • Test coverage does not support nested programs. In particular, it does not work for programs which call the cobsetjmp() and coblongjmp() APIs that are used when calling nested programs.
  • Manually changing the execution point while debugging a program produces test coverage results that are unpredictable.
  • If you have a multi-threaded program (one that is compiled with the REENTRANT directive) and you compile it with the test coverage enabled and run it under test coverage, the test coverage results obtained will be unpredictable.
  • When you use test coverage with preprocessors, only the basic blocks of the original code are taken into account.

Micro Focus recommends that you do not use test coverage in a production system because of the increased requirements on system resources when running in test coverage mode. However, you can compile with test coverage enabled into your production system, if needed. Additionally, you should exercise caution when enabling code coverage on large remote projects, as this results in a significant amount of data transfer caused by the required project files being transferred locally for processing of the test coverage results.

Parent topic: Test Coverage (Native COBOL)
Parent topic: Test Coverage (Native COBOL)
Related reference
TESTCOVER
REENTRANT


Troubleshooting Test Coverage

Note: This facility is supported in native COBOL only.
If you have any problems with test coverage, check the following issues and follow the suggestions.
cobtcreport Cannot find the .idy file
Set COBIDY to the location of the .idy file.
No results file has been produced
Ensure your environment variable is pointing to a valid .tcf file, and that your .tcf file contains a results line.

Ensure you have compiled your program with the TESTCOVER directive set.

Ensure you have exited from the program you are running. The results are only written when the program has exited. If you are debugging a program, you must stop the debugger if it is still active, even when a Stop Run has been encountered. If your program terminates abnormally, the results are not written.

"IDY file cannot be found" error is produced
Ensure you still have the .idy file and source for this compiled version of the program. If you have run another compilation, they will have been overwritten.

If you do have them, and they cannot be located, set COBIDY and COBCPY as necessary to the location of the .idy file.

No source lines are appearing
Ensure that your results file is in the location you were expecting. If you have not specified a directory before the name of the results file in the .tcf file and you are running from a command prompt, the results file will be placed in the directory from which the command line was run, which is not necessarily the same location as the programs. If you are running from the IDE, the results file will be placed in the project folder alongside the application file. You must, therefore, be careful to run your programs from the correct location, or to specify the required directory in the .tcf file.
Not all of the results are being shown, or mismatches are occurring
Ensure that the .cbl or .cpy and .idy files that were used at compile time are still available, and that cobtcreport can find them. You might need to set COBIDY to the location of the .idy file.
Mismatches are occurring
Ensure you have not recompiled your program, thus overwriting the .idy file so that a mismatch will be given on the source lines in the original .tcz file.

Ensure you do not have different compile versions of a program with the same name in different locations.

Parent topic: Test Coverage (Native COBOL)
Parent topic: Test Coverage (Native COBOL)
Related reference
TESTCOVER


Test Coverage Error Messages

Note: This facility is supported in native COBOL only.
  • Test Coverage System Errors
  • TC001S No input results file specified
  • TC004S Too many program / timestamp combinations
  • TC005S Unable to open program source file
  • TC006S Unable to open output report file
  • TC007S Unable to open output text file
  • TC008S Unable to open output index file
  • TC009S The version number on the results file is invalid
  • TC010S Unable to open results file
  • TC012I NOHTML and NOTEXT specified - nothing to do
  • TC014S Invalid option entered
  • TC018I Severe error encountered
  • TC019I The run was incomplete
  • TC021S Timestamp mismatch
  • TC022S Version number from calling program is invalid
  • TC034E IDY/Results timestamp mismatch
  • TC035E IDY/Results program not compiled with TESTCOVER
  • TC037E IDY/Result inconsistency
  • TC039 No unexecuted statements
  • TC040E missing idy - file, no source available
  • TC041E Matching source file not found
  • TC042S These programs cannot be merged, they have been reported separately
  • TC043S Unable to open Trace file
  • TC052S Unable to open the configuration file
  • TC053I
  • TC054I
  • TC055I NOTE no source code available
  • TC056I processed normally
  • TC057I ACCUMULATE ignored, incompatible with ? in .tcz file name
  • TC058S Syntax error in config file
  • TC059S Processed with warnings. Look at report for more details
  • TC060S Source file has been changed since the results file has been generated.
  • TC061S Unable to open tagfile
  • TC062S Unable to open command file
Parent topic: Test Coverage (Native COBOL)
Parent topic: Test Coverage (Native COBOL)
Related information
COBOL


Test Coverage System Errors

If you receive any of the following errors, try rerunning with more memory available. Otherwise, contact Micro Focus.

  • TC002S System error null link list pointer
  • TC003S System error - Unable to get current directory
  • TC011S System error Memory alloc failed
  • TC013S system error - Parsing failed
  • TC015S System error - File list allocation failed
  • TC016S System error - Summary list allocation fail
  • TC017S System error - Suffix list alloc fail
  • TC020S SYSTEM error - null caller program pointer
  • TC015S System error - File list allocation failed
  • TC016S System error - Summary list allocation fail
  • TC017S System error - Suffix list alloc fail
  • TC044S System error - CDI2 cannot find program
Parent topic: Test Coverage Error Messages


TC001S No input results file specified

TCREPORT or TCSCAN executed but no results file is named in the parameters.

Parent topic: Test Coverage Error Messages


TC004S Too many program / timestamp combinations

TCREPORT has encountered too many programs with the same name but different timestamps to be able to generate different file name suffixes for all of them.

Parent topic: Test Coverage Error Messages


TC005S Unable to open program source file

TCREPORT was processing a results file and was unable to open the associated source.

Parent topic: Test Coverage Error Messages


TC006S Unable to open output report file

TCREPORT or TCSCAN was unable to open the named report file - it might be protected or locked for use by another process.

Parent topic: Test Coverage Error Messages


TC007S Unable to open output text file

TCREPORT was unable to open the named text file - it might be protected or locked for use by another process.

Parent topic: Test Coverage Error Messages


TC008S Unable to open output index file

TCREPORT was unable to open the named text file - it might be protected or locked for use by another process.

Parent topic: Test Coverage Error Messages


TC009S The version number on the results file is invalid

TESTCOVER writes a version number to the results file which is checked by TCREPORT to ensure compatibility. This error indicates that the results file was written by a version of TESTCOVER that is incompatible with the version of TCREPORT that is reading it.

Parent topic: Test Coverage Error Messages


TC010S Unable to open results file

TCREPORT was unable to open the named file - it might be protected or locked for use by another process.

Parent topic: Test Coverage Error Messages


TC012I NOHTML and NOTEXT specified - nothing to do

If neither NOHTML nor NOTEXT is specified in TCREPORT, no reports are produced.

Parent topic: Test Coverage Error Messages


TC014S Invalid option entered

One or more of the command line options entered in TCREPORT or TCSCAN was invalid. Re-enter the command.

Parent topic: Test Coverage Error Messages


TC018I Severe error encountered

This information message indicates that a severe error was encountered which prevented the program running to normal completion. It will be accompanied by a further message giving more specific details.

Parent topic: Test Coverage Error Messages


TC019I The run was incomplete

A fatal error occurred when running a program with test coverage, resulting in an incomplete run. Run the program again in order to generate a complete run.

Parent topic: Test Coverage Error Messages


TC021S Timestamp mismatch

TESTCOVER timestamp check has detected a program has been canceled, and a different one of the same name reloaded.

Parent topic: Test Coverage Error Messages


TC022S Version number from calling program is invalid

When the user application program is run, it calls TESTCOVER to log statement execution, and passes a version number which TESTCOVER checks to ensure compatibility. This error indicates that the version numbers do not match. Ensure that the product is properly installed, and that all current FixPacks have been applied.

Parent topic: Test Coverage Error Messages


TC034E IDY/Results timestamp mismatch

TCREPORT was unable to find an IDY file with the correct timestamp. Recompile and rerun the program with the TESTCOVER option.

Parent topic: Test Coverage Error Messages


TC035E IDY/Results program not compiled with TESTCOVER

The TCREPORT user program was not compiled with the TESTCOVER option set. Recompile and rerun the program with the TESTCOVER option.

Parent topic: Test Coverage Error Messages


TC037E IDY/Result inconsistency

There is an inconsistency between the IDY and GNL files, in that each shows the program with a different number of code blocks. You need to recompile and re-run.

Parent topic: Test Coverage Error Messages


TC039 No unexecuted statements

There are no unexecuted statements. Informational message only.

Parent topic: Test Coverage Error Messages


TC040E missing idy - file, no source available

TCREPORT cannot open the IDY file. It might have been deleted or locked by another process. Free the file or recreate it by recompiling the program and rerunning.

Parent topic: Test Coverage Error Messages


TC041E Matching source file not found

Ensure that test coverage can locate both the .idy files and their source files. If the files are not stored in the current directory, you need to set the COBIDY environment variable to the location of the .idy files and COBCPY to the location of the source files.

Parent topic: Test Coverage Error Messages


TC042S These programs cannot be merged, they have been reported separately

Not an error. The results file contains multiple versions of the same program, and therefore it is not possible to merge the test coverage reports.

Parent topic: Test Coverage Error Messages


TC043S Unable to open Trace file

Internal error.

Parent topic: Test Coverage Error Messages


TC052S Unable to open the configuration file

The configuration file named in the TESTCOVER environment variable cannot be read. Correct the environment variable or create the configuration file.

Parent topic: Test Coverage Error Messages


TC053I

Not an error. NOTE Results file(s) contained results from different versions of this program. Due to this, results from each version of the program cannot be merged and have been reported separately.

This message is reported in TCIndex if multiple versions of the same program are found when generating the reports.

Parent topic: Test Coverage Error Messages


TC054I

Not an error. NOTE: Results files(s) contained versions of the same program with different compile times. These programs cannot be merged and have been reported separately, differentiated by the addition of -0001, -0002, extensions to the program name.

This message is reported in TCIndex if multiple versions of the same program are found when generating the reports.

Parent topic: Test Coverage Error Messages


TC055I NOTE no source code available

Not an error. The source file is not found.

Parent topic: Test Coverage Error Messages


TC056I processed normally

Not an error. Tcreport successfully produces a report.

Parent topic: Test Coverage Error Messages


TC057I ACCUMULATE ignored, incompatible with ? in .tcz file name

This error occurs when you specify both ACCUMULATE (which configures test coverage to accumulate results into a single .tcz file), and the '?' wildcard character (which creates a new file for each run, incrementing the count by 1) in the test coverage configuration.

To resolve the issue, either remove ACCUMULATE or any wildcard characters (? ) from your test coverage configuration.

Parent topic: Test Coverage Error Messages


TC058S Syntax error in config file

There is an invalid syntax in the configuration file. Refer to the product help for the correct syntax to use in the file.

Parent topic: Test Coverage Error Messages


TC059S Processed with warnings. Look at report for more details

A non-fatal error has occurred when generating coverage for one or more of the source files. Check the program report file for further information.

Parent topic: Test Coverage Error Messages


TC060S Source file has been changed since the results file has been generated.

The source file has been modified after the generation of the .tcz file.

Parent topic: Test Coverage Error Messages


TC061S Unable to open tagfile

The file specified in a tagline (tcreport report.tcz tagline(filename.txt)) does not exist. To work around this issue, either create a text file that will be used as a tagfile with the specified name or change the filepath in tagline() to point to a valid text file.

Parent topic: Test Coverage Error Messages


TC062S Unable to open command file

The specified command line file does not exist. To work around this problem, you can either specify a valid text file or create a text file that could be used as a command file with the name specified in the error message.

Parent topic: Test Coverage Error Messages


Modern Development Practices

This section of the documentation contains information that is relevant if you are using Visual COBOL as part of a modern development process. As well as describing the modern application development process in general, it looks at how you can integrate Visual COBOL with other key components of the process.

  • Using Visual COBOL in Modern Application Development
  • Using Visual COBOL with Jenkins
  • Using Visual COBOL with Docker
Parent topic: Visual COBOL Development Hub 5.0


Using Visual COBOL in Modern Application Development

Development has traditionally been one discrete element in the process of turning users' requirements into working applications. Modern application development processes enable you to move away from a process containing a number of (at best) loosely-connected, discrete steps, and instead adopt a process where each step is handled by a specialized tool, and a combination of these tools and automation result in a more seamless, repeatable, end-to-end process that enables you to build and deliver the right software at the right time.

This section of the documentation describes modern application development in general and summarizes the role that Visual COBOL and other tools from Micro Focus can play in modern application development.

Note: It is important to bear in mind that even though this documentation covers all of the modern application development process, you can gain significant benefits in terms of quality and productivity by adopting any of the parts of the process in isolation.
  • Introduction to Modern Application Development
  • Agile Methods
  • Continuous Integration
  • Continuous Delivery
  • Continuous Improvement
Parent topic: Modern Development Practices


Introduction to Modern Application Development

The following sections show how modern application development differs from traditional development, outline the benefits of the different stages of a modern application development process, and show how Micro Focus tools can play a key role in your development and deployment processes.

  • What is Modern Application Development?
  • Key Concepts in Modern Application Development
  • Steps Involved in Modern Application Development
Parent topic: Using Visual COBOL in Modern Application Development
Related tasks
Using Visual COBOL with Jenkins
Related reference
Jenkins user documentation


What is Modern Application Development?

For many years the majority of software development followed the waterfall development model. Recently, alternatives to the waterfall model have been devised and subsequently revised in an attempt to make the process of software development more able to respond quickly to changing customer needs.

In the last few years, methodologies such as DevOps and DevSecOps have come into being, bringing even more advantages over older methodologies. In general, modern application development methodologies enable you to reduce your time to market, reduce the complexity of your projects, and ensure a high-quality experience for your users.

The information in this section of the Visual COBOL documentation is concerned with modern application methodologies in general rather than with any specific methodologies. When this section of the documentation refers to modern application development it is referring to any development methodology that aims to be more responsive to customer needs by automating the different parts of the process as well as the transitions between them.

Parent topic: Introduction to Modern Application Development


Key Concepts in Modern Application Development

Any discussion of modern application development methodologies will include reference to a number of key concepts. The following list provides a very brief summary of the key concepts that are used in this section of the documentation.

Agile software development
A set of principles guiding the production of software that focusses on the following:
  • Iterative, incremental, evolutionary delivery
  • Face-to-face communication
  • Short feedback loops
  • Use of automation to promote a focus on quality
Application release automation (ARA)
The use of tools to automate the steps involved to build software and subsequently deploy it to production.
Automated testing
The use of tools to control the running of tests and the comparison of the tests' outcomes with their expected outcomes.
Configuration management (SCM)
The task of tracking and controlling changes made to software as it is developed. Central to the concept of configuration management is version control, which is the management of changes to files.
Continuous delivery (CD)
A process whereby every code change results in the building and testing of new software that can then be deployed to production (if appropriate).
Continuous deployment
A process whereby every code change results in the building and testing of new software that is then deployed to production.
Continuous improvement
The process of regularly assessing a team's performance in a rollout period, evaluating what has gone well and what can be improved on.
Continuous integration (CI)
The practice of ensuring that all developers' working copies of code are regularly merged into a shared trunk, and each code change results in the building and testing of new software.
Requirements management
The process of gathering and managing the requirements for an application and ensuring that those requirements are used to effectively drive the efforts of the development team.
Unit testing
The process where the smallest parts of an application that it is possible to test are tested individually to see if they perform as expected.

You might find some of these terms defined in a number of subtly different ways in different sources. This section of the documentation uses the terms as they are defined here.

Parent topic: Introduction to Modern Application Development


Steps Involved in Modern Application Development

This section introduces a workflow diagram showing the various steps involved in a modern application development lifecycle then gives introductory information on each of the diagram's steps.

As said elsewhere, this documentation is concerned with modern application development in general rather than any specific named instance of modern application development.

The following figure shows the steps involved in the definition of modern application development used by this documentation.

The diagram shows the five main activities that make up the development process:

  • Plan
  • Build
  • Test
  • Release
  • Monitor

Note that there are no start and end points to this sequence of activities. Whereas one might expect the "Release" activity to mark the end of the process, that activity is followed by the "Monitor" activity where questions are asked about improvements that could be made to the released package as well as to the development process and how it was executed. The information from the "Monitor" activity is then used as input to the "Plan" activity, and the development process continues from there.

Outside the five activities are the broader processes that have evolved to optimize the way in which the individual activities work together. These processes are as follows, and each one is covered in more detail in this documentation:

  • Agile methods
  • Continuous integration
  • Continuous delivery
  • Continuous improvement
Parent topic: Introduction to Modern Application Development


Agile Methods

The following sections give an overview of Agile methods, present a typical Agile development workflow, and show the benefits that Micro Focus tools can bring to the Agile development process.

  • Introduction to Agile Methods
  • Agile Development Workflow
  • Agile Development and Micro Focus Development Tools
Parent topic: Using Visual COBOL in Modern Application Development


Introduction to Agile Methods

As mentioned in Key Concepts in Modern Application Development, agile software development (often referred to as "Agile") is a set of principles guiding the production of software that focusses on:

  • Iterative, incremental, and evolutionary delivery
  • Face-to-face communication
  • Short feedback loops
  • Automation to promote a focus on quality

These principles are laid out in a document known as the manifesto for Agile software development.

Agile is intended to be very simple and flexible but it can bring significant benefits such as:

  • Increased business agility

    Agile's iterative approach and short feedback loops shorten development cycles and enable you to quickly switch priorities based on changing customer requirements and market conditions.

  • Delivering the right product

    An Agile approach facilitates early and frequent feedback, maximizing the likelihood that the software delivered is exactly what the customer needs.

    A combination of the frequent feedback and iterative approach produces another benefit. At the end of an iteration, if stakeholder feedback indicates that the software produced in that iteration is not on target to meet customer requirements, the work done in that iteration can be abandoned and developers can adopt a different approach in the next iteration. The amount of development time lost in such a case would be only one iteration, typically two weeks, which is much less than would be wasted if the same issue arose when following the waterfall model.

  • Improved quality

    A key principle of Agile is that testing is integrated throughout the lifecycle.

Parent topic: Agile Methods


Agile Development Workflow

The following diagram summarizes the key steps in an Agile development process:

where the numbered steps are as follows:

  1. Create a list of requirements from customer feedback.
  2. Create a list of requirements based on your internal needs. These can be for anything at all, including new features, bug fixes, infrastructure and systems work, or technical debt.
  3. Combine your customers' requirements and your internal requirements into a product backlog. The product backlog is a prioritized list of the work that your development team will undertake to add the different items from your customers' and internal requirements.
  4. Use the product backlog to create sprint backlogs, which you use to define and track the work that will be done by the development team in a series of sprints. Sprints are also often referred to as "iterations".

    The length of a sprint is typically between one and four weeks and is usually fixed for the duration of a project.

    During each sprint, developers take items from the sprint backlog, work on them, and complete them by the end of the sprint.

    At the end of each sprint, the items on that sprint's backlog must be completed; not just coded, but tested, documented, and integrated into a working product that could be deployed (if required).

  5. Produce a deliverable product package, if required.

    At the end of a sprint you return to the Agile planning stage to create the next sprint backlog.

    At the end of the project you return to the requirements gathering stage to create the new product backlog.

Parent topic: Agile Methods


Agile Development and Micro Focus Development Tools

The sections Introduction to Agile Methods and Agile Development Workflow introduce the idea of Agile software development and summarize how Agile development works as a process. This section looks at the Agile development process and shows how different products available from Micro Focus fit into and add value to that process.

The diagram below shows the process presented in the topic Agile Development Workflow but has been updated to indicate which Micro Focus products are appropriate at different parts of the process. Although this diagram refers to Micro Focus products, the process described does not require the use of Micro Focus products, so if you are already using a third-party product for one part of the process you can continue to work with that and use Micro Focus products to integrate with it.

where the numbered steps are as follows:

  1. Use Micro Focus Atlas to create a list of requirements from customer feedback.
  2. Use Micro Focus Atlas to create a list of requirements based on your internal needs. These can be for anything at all, including new features, bug fixes, infrastructure or systems work, and technical debt.
  3. Use Micro Focus Atlas to combine your customers' requirements and your internal requirements. Once you have combined the requirements in Atlas you can export them to Micro Focus Rhythm as a product backlog. The product backlog is a prioritized list of the work that your development team will undertake to add the different items from your customers' and internal requirements.
  4. Use Micro Focus Rhythm to create sprint backlogs, which you use to define and track the work on the product backlog that will be done by the development team in a series of sprints. Sprints are also often referred to as "iterations".

    The length of a sprint is typically between one and four weeks and is usually fixed for the duration of a project.

    During each sprint, developers take items from the sprint backlog, work on them, and complete them by the end of the sprint.

    At the end of each sprint, the items on that sprint's backlog must be completed; not just coded, but tested, documented, and integrated into a working product that could be deployed (if required).

  5. Use Visual COBOL to produce a deliverable product package, if required.

    When using Visual COBOL, developers can use the complete array of analysis, intelligence and reporting tools provided by COBOL Analyzer to quickly gain a full understanding of the applications they are working on.

    At the end of a sprint you return to the Agile planning stage to create the next sprint backlog.

    At the end of the project you return to the requirements gathering stage to create the new product backlog.

The following list gives a very brief summary of each of the Micro Focus products that play a part in the Agile development process:

  • Atlas

    Micro Focus Atlas is an Agile requirements and delivery platform that enables teams to create products in a much more collaborative and flexible way in comparison to other requirements management tools.

  • COBOL Analyzer

    Micro Focus COBOL Analyzer is powerful code analysis and visualization toolset, designed to address the challenges of working with large-scale, complex applications.

    COBOL Analyzer enables you to quickly gain a thorough understanding of your applications, meaning that you reduce the amount of time it takes you to make your changes and you can have more confidence that your changes have the desired effect and do not introduce any new issues.

    You can also use COBOL Analyzer to run queries to determine if your code conforms to your in-house standards. Any code that does not conform to your standards can be flagged as an error following a commit or during the build process.

  • Rhythm

    Micro Focus Rhythm is the enterprise-class planning and tracking solution for Agile software projects.

    Rhythm has been designed to integrate easily with Atlas and Visual COBOL, as well as with third-party issue-tracking, version control and requirements management tools.

  • Visual COBOL

    Micro Focus Visual COBOL is the next-generation solution for COBOL application development and deployment. It enables you to modernize COBOL systems using Visual Studio and Eclipse as well as deploy COBOL applications and services to new platforms, including .NET, JVM, and the cloud.

    The following features of Visual COBOL make it an invaluable part of the Agile development process:

    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into provides useful debugging features such as colorization, error flagging, and intelligent copybook handling to enable you to quickly track down any issues, establish their cause, and make your edits.
    • Reverse Debug and Live Recording are features that enable you to create a recording of an application's execution then load the recording into the debugger.

      With the recording loaded into the debugger you can monitor everything that influenced the running of the program (such as all input, disk access, and keyboard strokes) and because the debugger lets you move backwards and forwards through the execution path you can easily focus on potential causes of crashes or other unexpected behavior in the application.

    • The Micro Focus Unit Testing Framework, an xUnit-style testing framework, includes much of the architecture you would expect of an xUnit framework, enabling you to create, compile, run, and debug unit tests from either the command line or the Visual COBOL IDE.
    • Core dump debugging. When an application crashes you can arrange for its state to be saved to disk, in a core dump file, which can indicate where the error occurred in the source code, the contents of memory at the time of the error, and the values of any variables and expressions set at the time. You can then use the core dump file to help debug the problems.
    • Remote debugging enables you to debug programs that are running on a different computer from the one on which you are using.
    • The Consolidated Tracing Facility (CTF) produces detailed diagnostic information that can be invaluable in diagnosing problems when you can't easily attach a debugger.
Parent topic: Agile Methods


Continuous Integration

The following sections give an overview of continuous integration, present a typical continuous integration workflow, and show the benefits that Micro Focus tools can bring to the continuous integration process.

  • Introduction to Continuous Integration
  • Continuous Integration Workflow
  • Continuous Integration and Micro Focus Development Tools
Parent topic: Using Visual COBOL in Modern Application Development


Introduction to Continuous Integration

As mentioned in Key Concepts in Modern Application Development, continuous integration (CI) is a software development practice whereby developers on a team regularly integrate their working copies of code to a shared repository. Once a change is integrated to the repository, the application is automatically rebuilt. Automated tests are run before and after the application is rebuilt, to check that no regressions are introduced. If any of the automated tests fail, developers can be notified automatically so that they can provide a fix.

Using continuous integration provides a number of benefits:

  • Developers can find problems earlier than they would be able to if builds happened only every day or every week.
  • When a problem does occur, pinpointing the cause of the problem is quicker and easier because only a small change should have been made since the last working build.
  • The time taken to resolve integration issues is reduced because each change is integrated as required.
  • There is always a working version of the product that contains the latest changes.

Tools that provide CI functionality are known as CI servers. There are many tools available that can be used as CI servers, but the following list shows some of the more commonly used:

  • Bamboo
  • Cruise Control
  • Hudson
  • Jenkins
  • Team Foundation Server

For detailed information on how to use Visual COBOL with Jenkins, see Using Visual COBOL with Jenkins.

Parent topic: Continuous Integration


Continuous Integration Workflow

The following diagram summarizes the key steps in a continuous integration process. Although the process comprises a number of different activities with integration provided between each activity, you do not have to adopt every activity in the process before you can benefit from significant gains in terms of efficiency, effectiveness, and quality. Instead, you might choose to implement this process one activity at a time, taking advantage of the benefits provided by each activity as you add and integrate it with the others.

where the numbered steps are as follows:

  1. Developers check out code into their private workspaces. They then make their changes and test them locally.
  2. When done, developers check in their changes into the source control repository.
  3. The CI server monitors the source control repository and when it detects a change it triggers a build of the relevant sources.
  4. After a successful build, the CI server performs some or all of the following activities:
    • makes deployable artefacts available for testing
    • assigns a build label to the version of the code that was just built
    • notifies the relevant team members that a successful build occurred
    • triggers unit and integration testing

    At this point, the changes that were checked in at step 2 have been successfully built and a build label has been applied to the source code that was used for the build, meaning that the build could be recreated if necessary.

    In the event of a build failure, the CI server sends notifications to the relevant developers who restart the process from step 1 to make the changes necessary to resolve the build errors.

  5. After the unit and integration testing has taken place, the relevant team members are notified of the test results.

    At this point, the changes that were checked in at step 2 have been successfully built and tested, all with little or no manual intervention.

For information on using Jenkins to perform the CI server tasks in the above list, see Using Visual COBOL with Jenkins.

Parent topic: Continuous Integration


Continuous Integration and Micro Focus Development Tools

The sections Introduction to Continuous Integration and Continuous Integration Workflow introduce the idea of continuous integration and summarize how continuous integration works as a process. This section looks at the continuous integration process and shows how different products available from Micro Focus fit into and add value to that process.

The diagram below shows the process presented in the topic Continuous Integration Workflow but has been modified to indicate which Micro Focus products you can use at the different parts of the process. Although this diagram refers to Micro Focus products, the process described does not require the use of Micro Focus products, so if you are already using a third-party product for one part of the process you can continue to work with that and use Micro Focus products to integrate with it.

where the numbered steps are as follows:

  1. Developers use Visual COBOL to check out code into their private workspaces. They then make their changes and test them locally using Visual COBOL's unit testing features.

    This diagram illustrates the use of AccuRev, Dimensions CM, StarTeam or PVCS as the source code control system but you are not limited to using only those products. Visual COBOL works with any SCC-compliant source code control system, so you can work seamlessly in Visual COBOL with virtually any source code control system you choose to use regardless of whether it is a Micro Focus product or a third-party product.

  2. When done, developers check in their changes into the source control repository.
  3. The CI server monitors the source control repository and when it detects a change it triggers a build of the relevant sources. Although the build actions are triggered by the CI server, the build actions themselves will be performed by Visual COBOL, typically using Apache Ant or MSBuild scripts.
  4. After a successful build, the CI server performs activities such as the following:
    • makes deployable artefacts available for testing
    • assigns a build label to the version of the code that was just built
    • notifies the relevant team members that a successful build occurred
    • triggers unit and integration testing to be run under COBOL Server

    At this point, the changes that were checked in at step 2 have been successfully built and a build label has been applied to the source code that was used for the build (so the build could be recreated if necessary).

    In the event of a build failure, the CI server sends notifications to the relevant developers who restart the process from step 1, using Visual COBOL to make the changes necessary to resolve the build errors.

  5. After the unit and integration testing has taken place, the relevant team members are notified of the test results.

    At this point, the changes that were checked in at step 2 have been successfully built and tested, all with little or no manual intervention.

For information on using Jenkins to perform the CI server tasks in the above list, see Using Visual COBOL with Jenkins.

The following list gives a very brief summary of each of the Micro Focus products that play a part in the continuous integration process:

  • AccuRev

    Micro Focus AccuRev is a software configuration management tool that addresses complex parallel and distributed development environments with stream-based architecture to accelerate development processes and improve asset reuse.

    AccuRev integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • COBOL Analyzer

    Micro Focus COBOL Analyzer is powerful code analysis and visualization toolset, designed to address the challenges of working with large-scale, complex applications.

    COBOL Analyzer enables you to quickly gain a thorough understanding of your applications, meaning that you reduce the amount of time it takes you to make your changes and you can have more confidence that your changes have the desired effect and do not introduce any new issues.

    You can also use COBOL Analyzer to run queries to determine if your code conforms to your in-house standards. Any code that does not conform to your standards can be flagged as an error following a commit or during the build process.

  • COBOL Server

    COBOL Server is the deployment and execution environment for applications developed using Visual COBOL. It provides a high-performance, platform-portable run time environment in which your customers can execute your COBOL applications, while its small footprint and ease of installation makes it easy for you to use in your testing.

    As well as providing the environment in which your COBOL applications run, COBOL Server includes features to simplify your testing. For example, once you have set up a COBOL Server environment for testing an application you can export the definition of that environment to an XML file, where the XML definition includes details of all aspects of the COBOL Server environment such as region definitions, locations of data files, and settings of environment variables. Once you have exported the definition you can import it to be used during your testing, ensuring that the COBOL Server environment you use in your testing is exactly the same environment as the one you know to be correct.

  • Dimensions CM

    Micro Focus Dimensions CM streamlines the complexity of collaborative parallel development and increases team velocity while ensuring a high degree of release readiness.

    Dimensions CM integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • PVCS

    Micro Focus PVCS Version Manager is used by thousands of software developers around the world to meet their version control requirements. It is one of the most reliable, trusted, and proven solutions available.

    PVCS integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • StarTeam

    Micro Focus StarTeam delivers changes across multiple ALM repositories and tools as the single source of truth. It's an enterprise change management system, serving both centralized and geographically distributed development teams, helping them achieve their highest level of software delivery.

    StarTeam integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • Visual COBOL

    Micro Focus Visual COBOL is the next-generation solution for COBOL application development and deployment. It enables you to modernize COBOL systems using Visual Studio and Eclipse as well as deploy COBOL applications and services to new platforms, including .NET, JVM, and the cloud.

    Visual COBOL offers the following features that make it a great fit for using in your CI process:

    • Support for means that you can write scripts to enable your CI server to build and run your COBOL applications just as easily as you can build and run your COBOL applications from the Visual COBOL IDE.
    • Integration into an extensible IDE enables you to use a range of third-party functionality to work with different CI servers.
    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into provides useful debugging features such as colorization, error flagging, and intelligent copybook handling to enable you to quickly track down any issues, establish their cause, and make your edits.
    • Reverse Debug and Live Recording are features that enable you to create a recording of an application's execution then load the recording into the debugger.

      With the recording loaded into the debugger you can monitor everything that influenced the running of the program (such as all input, disk access, and keyboard strokes) and because the debugger lets you move backwards and forwards through the execution path you can easily focus on potential causes of crashes or other unexpected behavior in the application.

    • The Micro Focus Unit Testing Framework, an xUnit-style testing framework, includes much of the architecture you would expect of an xUnit framework, enabling you to create, compile, run, and debug unit tests from either the command line or the Visual COBOL IDE.
    • Core dump debugging. When an application crashes you can arrange for its state to be saved to disk, in a core dump file, which can indicate where the error occurred in the source code, the contents of memory at the time of the error, and the values of any variables and expressions set at the time. You can then use the core dump file to help debug the problems.
    • Remote debugging enables you to debug programs that are running on a different computer from the one on which you are using.
    • The Consolidated Tracing Facility (CTF) produces detailed diagnostic information that can be invaluable in diagnosing problems when you can't easily attach a debugger.
Parent topic: Continuous Integration


Continuous Delivery

The following sections give an overview of continuous delivery, present a typical continuous delivery workflow, and show the benefits that Micro Focus tools can bring to the continuous delivery process.

  • Introduction to Continuous Delivery
  • Continuous Delivery Workflow
  • Continuous Delivery and Micro Focus Development Tools
Parent topic: Using Visual COBOL in Modern Application Development


Introduction to Continuous Delivery

As mentioned in Key Concepts in Modern Application Development, continuous delivery (CD) is a practice where teams make use of automated processes so that any code changes result in the building and testing of new software that can then be deployed to production (if appropriate).

Continuous delivery does not mean that every code change is deployed to production. Instead, a continuous delivery environment typically includes a number of different environments for deployment, where deployments to some environments happen automatically but deployment to other environments requires some manual input or approval.

For example, a continuous delivery environment could include deployment environments for development, testing, staging, and production, where deployment happens automatically for the development and testing environments, but manual intervention is required to approve deployment to the staging or production environments.

Using continuous delivery in this way enables you to deliver application changes quickly and more reliably, leading to improved product quality and user experience.

Note: Continuous delivery is very similar to continuous deployment, with the only difference being the existence (or lack) of manual validation steps. With continuous delivery a code change results in automated building and testing followed by at least one manual validation step before the changes are deployed to production, whereas with continuous deployment there are no manual validation steps, so a code change always results in automated building, testing, and deployment to production.
Parent topic: Continuous Delivery


Continuous Delivery Workflow

The following diagram summarizes the steps involved in a continuous delivery process. Although the process comprises a number of different activities with integration provided between each activity, you do not have to adopt every activity in the process before you can benefit from significant gains in terms of efficiency, effectiveness, and quality. Instead, you might choose to implement this process one activity at a time, taking advantage of the benefits provided by each activity as you add and integrate it with the others.

Note that because continuous delivery is effectively an extension of the continuous integration process, the first five steps in this diagram are the same as the steps in the diagram presented in Continuous Integration Workflow.

where the numbered steps are as follows:

  1. Developers check out code into their private workspaces. They then make their changes and test them locally.
  2. When done, developers check in their changes into the source control repository.
  3. The CI server monitors the source control repository and when it detects a change it triggers a build of the relevant sources.
  4. After a successful build, the CI server performs some or all of the following activities:
    • makes deployable artefacts available for testing
    • assigns a build label to the version of the code that was just built
    • notifies the relevant team members that a successful build occurred
    • triggers unit and integration testing

    At this point, the changes that were checked in at step 2 have been successfully built and a build label has been applied to the source code that was used for the build, meaning that the build could be recreated if necessary.

    In the event of a build failure, the CI server sends notifications to the relevant developers who restart the process from step 1 to make the changes necessary to resolve the build errors.

  5. After the unit and integration testing has taken place, the relevant team members are notified of the test results.

    At this point, the changes that were checked in at step 2 have been successfully built and tested, all with little or no manual intervention.

  6. After the unit and integration testing has completed successfully, the CI server triggers the running of more comprehensive, automated acceptance tests.
  7. If the acceptance tests all pass, a decision is made whether or not to release.

    If the acceptance tests result in failures, the CI server sends notifications to the relevant developers who restart the process from step 1 to make the changes necessary to resolve the test failures.

  8. If the validation decision is to release, release management is triggered. This results in the built package being released or deployed to the appropriate environment.

    If the validation decision is not to release, the relevant team members are notified and development work continues as normal.

For information on using Jenkins to perform the CI server tasks in the above list, see Using Visual COBOL with Jenkins.

Parent topic: Continuous Delivery


Continuous Delivery and Micro Focus Development Tools

The sections Introduction to Continuous Delivery and Continuous Delivery Workflow introduce the idea of continuous delivery and summarize how continuous delivery works as a process. This section looks at the continuous delivery process and shows how different products available from Micro Focus fit into and add value to that process.

The diagram below shows the process presented in the section Continuous Delivery Workflow but has been updated to indicate which Micro Focus products are appropriate at different parts of the process. Although this diagram refers to Micro Focus products, the process described does not require the use of Micro Focus products, so if you are already using a third-party product for one part of the process you can continue to work with that and use Micro Focus products to integrate with it.

Note that because continuous delivery is effectively an extension of the continuous integration process, the first five steps in this diagram are the same as the steps in the diagram presented in Continuous Integration and Micro Focus Development Tools.

where the numbered steps are as follows:

  1. Developers use Visual COBOL to check out code into their private workspaces. They then make their changes and test them locally using Visual COBOL's unit testing features.

    This diagram illustrates the use of AccuRev, Dimensions CM, StarTeam or PVCS as the source code control system but you are not limited to using only those products. Visual COBOL works with any SCC-compliant source code control system, so you can work seamlessly in Visual COBOL with virtually any source code control system you choose to use regardless of whether it is a Micro Focus product or a third-party product.

  2. When done, developers check in their changes into the source control repository.
  3. The CI server monitors the source control repository and when it detects a change it triggers a build of the relevant sources. Although the build actions are triggered by the CI server, the build actions themselves will be performed by Visual COBOL, typically using Apache Ant or MSBuild scripts.
  4. After a successful build, the CI server performs activities such as the following:
    • makes deployable artefacts available for testing
    • assigns a build label to the version of the code that was just built
    • notifies the relevant team members that a successful build occurred
    • triggers unit and integration testing to be run under COBOL Server

    At this point, the changes that were checked in at step 2 have been successfully built and a build label has been applied to the source code that was used for the build (so the build could be recreated if necessary).

    In the event of a build failure, the CI server sends notifications to the relevant developers who restart the process from step 1, using Visual COBOL to make the changes necessary to resolve the build errors.

  5. After the unit and integration testing has taken place, the relevant team members are notified of the test results.

    At this point, the changes that were checked in at step 2 have been successfully built and tested, all with little or no manual intervention.

  6. After the unit and integration testing has completed successfully, the CI server triggers the running of more comprehensive, automated acceptance tests using Micro Focus Silk.
  7. If the acceptance tests all pass, a decision is made whether or not to release.

    If the acceptance tests results in failures, the CI server sends notifications to the relevant developers who restart the process from step 1 to make the changes necessary to resolve the test failures.

  8. If the validation decision is to release, use Micro Focus Deployment Automation or Micro Focus Release Control to release or deploy the built package to the appropriate environment.

    If the validation decision is not to release, the relevant team members are notified and development work continues as normal.

For information on using Jenkins to perform the CI server tasks in the above list, see Using Visual COBOL with Jenkins.

The following list gives a very brief summary of each of the Micro Focus products that play a part in the continuous delivery process:

  • AccuRev

    Micro Focus AccuRev is a software configuration management tool that addresses complex parallel and distributed development environments with stream-based architecture to accelerate development processes and improve asset reuse.

    AccuRev integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • COBOL Analyzer

    Micro Focus COBOL Analyzer is powerful code analysis and visualization toolset, designed to address the challenges of working with large-scale, complex applications.

    COBOL Analyzer enables you to quickly gain a thorough understanding of your applications, meaning that you reduce the amount of time it takes you to make your changes and you can have more confidence that your changes have the desired effect and do not introduce any new issues.

    You can also use COBOL Analyzer to run queries to determine if your code conforms to your in-house standards. Any code that does not conform to your standards can be flagged as an error following a commit or during the build process.

  • COBOL Server

    COBOL Server is the deployment and execution environment for applications developed using Visual COBOL. It provides a high-performance, platform-portable run time environment in which your customers can execute your COBOL applications, while its small footprint and ease of installation makes it easy for you to use in your testing.

    As well as providing the environment in which your COBOL applications run, COBOL Server includes features to simplify your testing. For example, once you have set up a COBOL Server environment for testing an application you can export the definition of that environment to an XML file, where the XML definition includes details of all aspects of the COBOL Server environment such as region definitions, locations of data files, and settings of environment variables. Once you have exported the definition you can import it to be used during your testing, ensuring that the COBOL Server environment you use in your testing is exactly the same environment as the one you know to be correct.

  • Deployment Automation

    Micro Focus Deployment Automation simplifies and automates the deployment of your software. It supports continuous delivery and production deployments by seamlessly enabling deployment pipeline automation, reducing cycle times, and providing rapid feedback. With Deployment Automation, you will be able to deliver high-quality, valuable software in an efficient, fast, and reliable manner.

  • Dimensions CM

    Micro Focus Dimensions CM streamlines the complexity of collaborative parallel development and increases team velocity while ensuring a high degree of release readiness.

    Dimensions CM integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • PVCS

    Micro Focus PVCS Version Manager is used by thousands of software developers around the world to meet their version control requirements. It is one of the most reliable, trusted, and proven solutions available.

    PVCS integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • Release Control

    Micro Focus Release Control enables you to plan, control, and automate your release processes from definition to deployment with a visual release calendar and automated approval process. The automation and integration features that Release Control offers result in improved visibility and tracking, and adherence to your compliance and control procedures.

  • Silk

    Micro Focus Silk Test enables you to maintain rigorous quality standards and accelerate application testing on any device and platform. Using Silk Test you can standardize validation efforts by testing web, mobile, rich-client, and enterprise applications with a single, powerful test automation solution.

    Micro Focus Silk Central unifies test assets into one planning, tracking, reporting, and execution hub, enabling you to define quality goals, schedule manual and automated functional and performance tests, and view results in a centralized dashboard.

  • StarTeam

    Micro Focus StarTeam delivers changes across multiple ALM repositories and tools as the single source of truth. It's an enterprise change management system, serving both centralized and geographically distributed development teams, helping them achieve their highest level of software delivery.

    StarTeam integrates with Visual COBOL to enable you to commit your changes to the shared repository quickly and easily with a minimum of fuss.

  • Visual COBOL

    Micro Focus Visual COBOL is the next-generation solution for COBOL application development and deployment. It enables you to modernize COBOL systems using Visual Studio and Eclipse as well as deploy COBOL applications and services to new platforms, including .NET, JVM, and the cloud.

    Visual COBOL includes the following features that make it particularly suitable for using in your continuous delivery process:

    • Support for means that you can write scripts to enable your CI server to build and run your COBOL applications just as easily as you can build and run your COBOL applications from the Visual COBOL IDE.
    • Integration into an extensible IDE enables you to use a range of third-party functionality to work with different CI servers.
    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into provides useful debugging features such as colorization, error flagging, and intelligent copybook handling to enable you to quickly track down any issues, establish their cause, and make your edits.
    • Reverse Debug and Live Recording are features that enable you to create a recording of an application's execution then load the recording into the debugger.

      With the recording loaded into the debugger you can monitor everything that influenced the running of the program (such as all input, disk access, and keyboard strokes) and because the debugger lets you move backwards and forwards through the execution path you can easily focus on potential causes of crashes or other unexpected behavior in the application.

    • The Micro Focus Unit Testing Framework, an xUnit-style testing framework, includes much of the architecture you would expect of an xUnit framework, enabling you to create, compile, run, and debug unit tests from either the command line or the Visual COBOL IDE.
    • Core dump debugging. When an application crashes you can arrange for its state to be saved to disk, in a core dump file, which can indicate where the error occurred in the source code, the contents of memory at the time of the error, and the values of any variables and expressions set at the time. You can then use the core dump file to help debug the problems.
    • Remote debugging enables you to debug programs that are running on a different computer from the one on which you are using.
    • The Consolidated Tracing Facility (CTF) produces detailed diagnostic information that can be invaluable in diagnosing problems when you can't easily attach a debugger.
Parent topic: Continuous Delivery


Continuous Improvement

Continuous improvement is strongly linked to one of the principles of the Agile manifesto which states that "At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly". The improvements you want to achieve can be split into two distinct areas:

  • Improvements to the software being produced.

    The following sources of information could all be used to help you target improvements to your software:

    • Test failures. If a particular area of code regularly causes test failures, is there the potential to redesign that section of the code? Test failures would be flagged by the unit and integration testing carried out in the continuous integration and continuous delivery processes of the modern application development process as well as by the acceptance testing carried out in the continuous delivery process.
    • Code coverage. The code coverage capabilities of Visual COBOL will highlight any areas of your code that aren't being executed as part of your testing, giving you the opportunity to update your tests to ensure that every line of code is thoroughly tested.
    • Customer feedback. Any feedback that you get from your customers about your software can be fed into the requirements gathering step of the Agile development process, giving you the opportunity to assess the feedback and quickly make changes based on it if appropriate. The rapid iterative nature of Agile development ensures that any changes you do make will quickly be delivered to the customer.
  • Improvements to the process used to produce the software.

    A convenient opportunity for a team to have this discussion is the sprint retrospective that is a part of the Agile development process. There is no fixed format to determine exactly what is discussed at a sprint retrospective, but in general, variants of the following questions are asked:

    • What went well?
    • What didn't go well?

    The scope of these questions is not limited to code-writing activities but covers the whole development process, so from requirements gathering to release. For any aspects of operation that are deemed to have not gone well, solutions can be discussed, and any changes can be implemented for future sprints. If substantial changes are required, they can be handled in the same way as any other requirements, with a tool such as Micro Focus Atlas.

    As sprints are very short, typically two weeks, any changes that are made to the process will be put into practice very quickly, and future sprint retrospectives will provide opportunities to discuss if the changes made had the desired effect or if further changes need to be made.

Parent topic: Using Visual COBOL in Modern Application Development


Using Visual COBOL with Jenkins

This section of the documentation contains information that you need to know to in order to use Visual COBOL 3.0 in conjunction with Jenkins version 2.60.1. It includes information on what software you need to install, how to configure Visual COBOL and Jenkins to get the most from them working together, and tips and guidance for using Visual COBOL alongside Jenkins.

General information about using Visual COBOL in a modern application development process is included in Introduction to Modern Application Development.

Note:
  • The examples in this section of the documentation have been tested with the specified versions of Visual COBOL and Jenkins. The concepts described would still apply to earlier or later releases of the two products, however, some specific releases might require changes to the Jenkins configuration.
  • For full details about how to use Jenkins, see the Jenkins user documentation.
  • Overview of Jenkins
  • Terminology
  • Scenarios for Using Jenkins with Visual COBOL
  • Software Requirements
  • Installing and Configuring Jenkins
  • Advanced Configuration
  • Using Jenkins to Build COBOL Applications
  • Examples
  • Best Practices When Using Jenkins
  • Troubleshooting
Parent topic: Modern Development Practices
Related concepts
Introduction to Modern Application Development
Related reference
Jenkins user documentation


Overview of Jenkins

Jenkins is a continuous integration (CI) server that supports a wide range of tools and technologies. Adopting a CI process ensures that all developers' working copies of code are regularly merged into a shared trunk. Once a change is committed to the repository, the product is automatically rebuilt and tested.

With Jenkins you can automate a number of day-to-day tasks such as checking out the sources from source control, building, code analysis, and different levels of testing and deployment.

By setting up Jenkins to run these tasks each time a developer has changed the source code, you can detect any defects much faster meaning that you maintain your applications' quality and reduce time to market.

Jenkins is highly configurable, and there are numerous plugins available that provide access to a range of tools including source control, shell and batch scripts. Jenkins works on multiple platforms, supports Java and integrates with other corporate systems.

Using Projects and Pipelines

Jenkins supports two methods of specifying commands - simple projects and pipelines.

Earlier versions of Jenkins only provided projects (previously known as jobs) for managing your tasks. Projects need to be created and configured manually in the UI and, if you need to create multiple projects, could require more maintenance work. Configuring projects is independent from your code.

More recent versions of Jenkins also support pipelines where all build, test, analysis and deployment tasks are stored in a single pipeline and saved as a Jenkinsfile. Micro Focus recommends using pipelines as they are suitable for organizing complex activities running on multiple machines. Storing a pipeline in a file format also means you can follow common CI best practices and save the pipeline in your source control code system with the rest of your code as another artefact.

For simplicity, the examples in this guide are created using projects and not pipelines. For details about the pipeline syntax, see the Jenkins user documentation.

Parent topic: Using Visual COBOL with Jenkins
Related reference
Jenkins user documentation


Terminology

This section of the documentation uses a number of terms as defined in the Jenkins UI. For a full list of the Jenkins terms, see the Jenkins user documentation.

Agent
A machine which connects to a Jenkins master and executes tasks when directed by the master.1
Job
A deprecated term, synonymous with project.
Master
The central, coordinating machine which stores configuration, loads plugins, and renders the various user interfaces for Jenkins.2
Node
A machine which is part of the Jenkins environment and capable of executing pipelines or projects. Both the master and agents are considered to be nodes.
Pipeline
A user-defined model of a continuous delivery pipeline.3
Plugin
An extension that provides additional functionality that is not provided by standard Jenkins.
Project
A user-configured description of work which Jenkins should perform, such as building a piece of software.
Parent topic: Using Visual COBOL with Jenkins
Related reference
Jenkins user documentation
1 Agent machines are also referred to as Slaves.
2 Typically, this is the machine that has Jenkins installed. The actual work specified in a project would then be performed on one or more agent machines (slaves).
3 The examples in this section of the documentation are created using projects and not pipelines.


Scenarios for Using Jenkins with Visual COBOL

You can integrate Jenkins into your continuous integration environment in a variety of ways. The approach that you decide to implement depends on your particular development process.

Using a Master and Agent Machines

The simplest scenario is to install Jenkins on the same machine on which you build and test your source code.

Real-world development and delivery processes typically require a more complex scenario than this, however, and you often need to ensure that your applications operate as expected on a variety of platforms. You can use Jenkins to its full potential in a multiple machine environment where Jenkins is installed on one machine (master) and controls a number of tasks that execute on various other machines (agents).

Automating Your Processes

You can use Jenkins to automatically start the next task in your application development process when the previous one has completed successfully. For example, this is how you can create a sequence of projects:

  1. Your projects examine the source code control system and trigger a checkout and build after a developer commits a change.
  2. At the end of a successful build, Jenkins can trigger other projects such as ones that run the MFUnit tests or copy the executables to another location for additional testing or deployment.
Parent topic: Using Visual COBOL with Jenkins


Software Requirements

The examples in this section of the documentation are created with the software versions specified below:

  • Jenkins 2.60.1 - see the Jenkins user documentation for information about the software prerequisites. In a scenario where you have a master and a number of agent machines, Jenkins must be installed on the master machine. You can obtain Jenkins from the Jenkins download page.
  • Visual COBOL 3.0 for - see the product's release notes for any software prerequisites.

    In a scenario where you have a master and a number of agent machines, Visual COBOL must be installed on each agent machine. You can obtain Visual COBOL from Micro Focus SupportLine.

  • Apache Ant 1.9.4 - this is required if you are working with COBOL applications created with Visual COBOL for Eclipse. Download Ant from the Apache Ant Web site.

The rest of this section of the documentation assumes that you have installed and licensed the specified software as required.

Parent topic: Using Visual COBOL with Jenkins
Related reference
Apache Ant web site
Jenkins download page
Jenkins user documentation
Micro Focus SupportLine


Installing and Configuring Jenkins

The following is a brief overview of how to install and configure Jenkins and how to create a project.

Installing and Accessing Jenkins

Jenkins is supported on a variety of platforms. See the Jenkins user documentation for detailed instructions on how to install and start it on the platform that you will be using.

You can access Jenkins from any machine using http://<mymachine>:8080, where <mymachine> is the name of the machine where Jenkins is installed.

Configuring Jenkins

You can specify general Jenkins options by clicking Manage Jenkins in the Home page of the Jenkins interface.

Use plugins to extend Jenkins and to enable support for tools or systems - click Manage Plugins. Use this page to check which plugins are installed and to install or update any as required. Widely-used plugins include those used for source control systems (such as Git and Subversion). Other plugins you might find useful include:

  • Conditional Buildstep
  • Copy Artifact
  • JUnit Attachments and xUnit
  • Node and Label Parameter
  • PowerShell
  • SCTMExecutor - works with Micro Focus MFUnit support and Micro Focus Silk Central
  • vSphere - if you are using agent machines that are stored in VMWare vSphere
  • Warnings Plug-in

Creating a Project

Click New Item in the Home page of Jenkins interface to create a project such as a freestyle project.

Use the project's configuration page (click Configure) to modify various aspects of what it does. Some aspects that might be appropriate for your build system are:

  • Restrict where this project can be run - specify the agents (such as remote machines) where the work should be performed.
  • Source Code Management - enter details of where your project is in source control. There are plugins available that allow Jenkins to work with most major source control systems.
  • Build Triggers - define events that automatically start the execution of the project.
  • Build - specify what the project should do such as executing Windows or UNIX commands, or Ant scripts.
  • Post-build Actions - specify the commands that the project should perform upon completion. These could be emailing reports, compiling build results, or triggering other projects based on the output of the current one.
Parent topic: Using Visual COBOL with Jenkins
Related reference
Jenkins user documentation


Advanced Configuration

The following sections provide guidance on how to specify more advanced configuration details to integrate Jenkins even more closely with your Visual COBOL development process.

  • Configuring Email Reporting
  • Using Sources from Source Control
  • Triggering Builds Automatically
  • Creating Environment Variables
  • Using Agents
Parent topic: Using Visual COBOL with Jenkins


Configuring Email Reporting

You can configure Jenkins so that it sends reports at the end of a build or a test, for example a report listing any test failures.

To configure Jenkins to send email notifications:

  1. Click Manage Jenkins in the Jenkins Home page.
  2. Click Configure System.
  3. Specify an SMTP server, any recipients and any other required details such as whether to always send an email or to only email about build failures - see the Extended E-mail Notification and E-mail Notification lists.

To enable email notifications for a project:

  1. Navigate to the configuration area of your project.
  2. In the Post-build Actions section, click Add post-build action.
  3. Add Editable Email Notification and E-mail Notification and specify a recipient email and other settings as required.
  4. For the Editable Email Notification, click Advanced and configure email as well as what triggers it (such as when a certain failure has occurred).
Parent topic: Advanced Configuration


Using Sources from Source Control

You can configure Jenkins to access the sources you store in a source control system, of which there are many types. The simplest way to do this is to use a file system watcher which triggers an action when a change occurs in the source control repository.

To enable Jenkins to access the source control, install a required plugin:

  1. In the Jenkins Home page, click Manage Jenkins > Manage Plugins, and then click the Available tab.
  2. Locate File system SCM, and then install the required plugin by enabling the check box and clicking Install.
  3. Restart Jenkins (you can select Ctrl+C in the command window that is running Jenkins and then start Jenkins again).

The following example shows how to configure your project to access the sources from Subversion:

  1. Navigate to the project's configuration area.
  2. Under Source Code Management, click Subversion.
  3. In the Repository URL area, specify the URL path of the source control that you want to work with.
  4. Specify the credentials and a local check-out directory as required.
  5. Click Apply to save the configuration.

    You have now created a source configuration for your project, but you also need to change the Build Triggers section to tell Jenkins to monitor that location.

Parent topic: Advanced Configuration


Triggering Builds Automatically

Jenkins supports triggers to automatically start running your projects. You can use various events as triggers - a successful build started by another project, detecting a change in the code following a commit in the SCM system, or a change as a result of monitoring a URL or a network location to name a few.

You specify triggers in the Build Triggers section of the project's configuration. For example:

  • Build after other projects are built - starts execution after successfully building another project.
  • Poll SCM - starts execution after a commit to a source code control system. Alternatively, instead of building on a source code change, you could specify that the project is to be executed at a scheduled time.
Parent topic: Advanced Configuration


Creating Environment Variables

There are different ways to specify environment variables in Jenkins. To specify an environment variable that applies globally, go to the Jenkins configuration pages. You can also specify environment variables that only apply to individual nodes, or ones that are set as an external step before starting Jenkins.

In a scenario where you have Visual COBOL installed on multiple platforms on agent machines, using environment variables for common installation paths can greatly simplify the creation of new projects.

For example, you can have an environment variable for the Visual COBOL installation directory on Windows, and another one for the corresponding location on UNIX. Other environment variables could point to locations such as the installation location of , the default source code control system check-out folder, or the location of the samples.

To set global environment variables in Jenkins:

  1. From the Jenkins Home page, click Manage Jenkins.
  2. Click Configure System.
  3. In the Global properties section, check Environment variables.
  4. Click Add and set any environment variables for paths that might be the same across a number of slave machines.

To set environment variables for a node:

  1. In the configuration page of the node, check Environment variables in the Node Properties section.
  2. Click Add and specify any environment variables as required.
Parent topic: Advanced Configuration
Related reference
Specifying any Environment Variables in a Project's Configuration


Using Agents

You can have Jenkins installed on one machine, known as a master, and use it to run projects that control your day-to-day development processes on other machines, known as agents. This can be very helpful if you need to ensure that your applications run correctly on a variety of different test configurations.

Note: An agent can either be a physical or a virtual machine.

The process of setting up agents in Jenkins is as follows:

  1. In Jenkins on the master, create a node that defines a connection to the machine you want to use as an agent. See the example below for instructions.
  2. On the agent, open the Jenkins UI. Open the page for the node and follow the link to launch a Jenkins agent which will establish a connection between Jenkins on the master machine and the agent machine.
  3. In Jenkins on the master, create a project and configure it to execute on the agent.

Example of Creating Agent Machines

The following example shows how to create a connection to an agent machine which is stored in a vSphere cloud. This requires that you install the vSphere plugin in Jenkins.

Ensure that Jenkins is connected to the vSphere cloud:

  1. From the Jenkins Home page, click Manage Jenkins.
  2. Click General.
  3. Under the Cloud section, click Add new cloud > vSphere cloud.
  4. Specify the configuration and login details for connecting to the vSphere host that contains your virtual machines.

To create a connection to an agent machine, first create a node in Jenkins as follows:

  1. Click Manage Jenkins.
  2. Click Manage Nodes.

    This opens the Nodes page showing the machine that has Jenkins installed as the master.

  3. Click New Node.
  4. Specify a name for the node and click Permanent Agent, then click OK.
  5. Fill in the details as required - for example, specify a Remote root directory if this is needed for checking out sources on the agent.
  6. Click Save.

To configure the agent to connect to the master:

  1. On the agent machine, load the Jenkins Home page (http://mastermachine:8080).
  2. From the Jenkins Home page, click the node for the machine that appears under the Build Execution Status box.
  3. From the Jenkins page for the node, click Launch to start the agent that connects the machine to Jenkins.

Configure an existing project to execute on the agent as follows:

  1. On the master machine, go to the project configuration page.
  2. Check Restrict where this project can be run in the General section.
  3. In the Label Expression, specify the name of the node that you just created and connected to.
  4. Save the project.

    Next time you build the project, it will execute on the agent.

Parent topic: Advanced Configuration


Using Jenkins to Build COBOL Applications

The following sections describe aspects of Visual COBOL's behavior that you need to configure to enable your Visual COBOL system to work with Jenkins.

In a Jenkins environment you often use Jenkins installed on a master machine to control processes that execute on a number of other machines (agents) running different operating systems that also have Visual COBOL installed. In such configurations, it is useful to have the same Visual COBOL configuration settings on all agents.

Micro Focus recommends that you install Visual COBOL using the same default settings and locations on all Windows and UNIX machines where you will execute your build, test, analysis and deployment tasks. This will make it easier to configure your Jenkins projects.

  • Setting up the Environment
Parent topic: Using Visual COBOL with Jenkins


Setting up the Environment

In most cases, your Jenkins projects execute tasks in a command line environment and not inside the Visual COBOL IDE. This means that the COBOL environment is not automatically preconfigured as it would be if you used the IDE. As a result, when you use Jenkins projects you typically need to manually set the COBOL environment for your projects.

Note: If you use scripts to build your applications, then the scripts might already include the commands for setting the COBOL environment. In this case, you do not need to specify the environment in Jenkins - you only need to configure Jenkins to run the scripts.
Parent topic: Using Jenkins to Build COBOL Applications
Related concepts
Example - Building COBOL Programs
Example - Integrating Code Analysis
Example - Running MFUnit Tests


Examples

  • Example - Building COBOL Programs
  • Example - Integrating Code Analysis
  • Example - Running MFUnit Tests
Parent topic: Using Visual COBOL with Jenkins


Example - Building COBOL Programs

The following example shows how to use Jenkins projects to build COBOL source code.

You are going to use Visual COBOL and one of the MFUnit Airport samples to see how to use Jenkins to build a COBOL application. The sample is stored in the \COBOL\AirportMFUnitDemo subfolder in the location of the Visual COBOL samples (which is c:\users\Public\Documents\Micro Focus\Enterprise Developer\Samples\COBOL\AirportMFUnitDemo by default).

Parent topic: Examples
Related concepts
Example - Integrating Code Analysis
Getting started with Micro Focus Visual COBOL for Eclipse
Related tasks
Setting up the Environment


Example - Integrating Code Analysis

The following example demonstrates how to configure Jenkins to perform code analysis of COBOL projects created with Visual COBOL.

Parent topic: Examples
Related concepts
Example - Building COBOL Programs
Software Requirements
Related tasks
Setting up the Environment


Example - Running MFUnit Tests

The following example demonstrates how you can configure Jenkins to run MFUnit tests against a COBOL application.

Parent topic: Examples
Related tasks
Setting up the Environment


Best Practices When Using Jenkins

This section includes some best practices that you might want to adopt when working with Visual COBOL and Jenkins. Although you do not have to adopt the processes described here, Micro Focus recommends that you do as they are known to be successful in helping to create an efficient and effective development process.

  • Using Jenkins With Source Control
  • Specifying any Environment Variables in a Project's Configuration
  • Creating Separate Projects for Building and Testing Your Code
  • Using Pipelines to Build Your Applications
Parent topic: Using Visual COBOL with Jenkins


Using Jenkins With Source Control

Micro Focus recommends that you adopt some common best practices in your commit and build process such as:

  • Deliver small changes of code by checking in your code frequently. This ensures that if build problems occur, it is easier to pin-point the exact reason for them.
  • Do not check in any changes that are not tested or that contain any errors.
  • Do not check in any new changes before fixing the error that caused an earlier Jenkins build failure.
Parent topic: Best Practices When Using Jenkins


Specifying any Environment Variables in a Project's Configuration

Specifying required environment variables within a Jenkins project's configuration makes the project more portable between different operating systems and reduces the chances of any external factors causing the build to fail.

Using this approach might mean that there could be some duplication in projects so choose the best method depending on how your particular project runs.

Parent topic: Best Practices When Using Jenkins
Related tasks
Creating Environment Variables


Creating Separate Projects for Building and Testing Your Code

A large benefit of continuous integration is receiving feedback quickly on whether a source code commit has introduced any failures. As such it can often be better to use separate projects for your build and test tasks. In this way, if a build fails, Jenkins will not attempt to run any tests and you will receive an error report much faster.

Parent topic: Best Practices When Using Jenkins


Using Pipelines to Build Your Applications

When you organize your build, test, code analysis and deployment tasks with Jenkins, Micro Focus recommends that you use pipelines in preference to projects.

You can save your pipelines as Jenkinsfiles and store them in your source code control system alongside your code. This means you can use different build instructions in the Jenkinsfile for the different branches of your code that represent the versions of the application. You only configure Jenkins once to use the sources from a particular branch in the source code control system and Jenkins will read the instructions in the pipeline about how to build your application.

Parent topic: Best Practices When Using Jenkins


Troubleshooting

The following sections describe some issues that you might encounter when using Jenkins with Visual COBOL with suggested workarounds.

  • Ant Error "Can't find mfant.jar" When Building COBOL Projects
  • COBOL Projects Don't Build
  • A Build Failure isn't Reported as a Failure
Parent topic: Using Visual COBOL with Jenkins


Ant Error "Can't find mfant.jar" When Building COBOL Projects

If you receive this error when building any of your COBOL projects the most likely cause is that you have not specified the location of mfant.jar to Ant.

To resolve this error perform the operation described in Making mfant.jar Available to Enable Building.

Parent topic: Troubleshooting


COBOL Projects Don't Build

If some of your COBOL projects build successfully but others fail unexpectedly, it suggests that the problem is with the project (or a project-based configuration in either Visual COBOL or Jenkins) rather than with the build system itself.

To investigate what the possible causes might be:

  • Open the COBOL project inside the IDE supplied with Visual COBOL and ensure that it builds correctly.
  • Check the Jenkins project's configuration and any of the build steps defined in it.
Parent topic: Troubleshooting


A Build Failure isn't Reported as a Failure

You can do one of the following to check why failures are not reported:

  • Check the Jenkins configuration and the project configuration to ensure that any errors will be reported correctly. See Configuring Email Reporting.
  • Check the project's console log for any error messages.
  • Build your application inside the Visual COBOL IDE and check whether any errors are reported.
Parent topic: Troubleshooting
Related concepts
Configuring Email Reporting


Using Visual COBOL with Docker

This section of the documentation contains information on how you can use Visual COBOL with Docker to work with your COBOL applications in Docker containers.

It contains general information on Docker, information for using Docker with COBOL applications, and detailed information about the Docker demonstrations that are supplied with Visual COBOL that guide you through all the steps involved in creating Docker containers to work with COBOL applications.

  • Introduction to Docker
  • Benefits of Using Docker
  • Docker Terminology
  • Getting Ready to Use Visual COBOL with Docker
  • Key Concepts When Using Docker with COBOL Applications
  • Building Images for COBOL Applications
  • Debugging COBOL Applications Running in Containers
  • Docker Demonstrations
Parent topic: Modern Development Practices


Introduction to Docker

Docker is a container-based 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.

As can be seen from this diagram, a Docker 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 Docker, which in turn runs on top of the operating system (which can be Windows 10, Windows Server 2016, or Linux).

Compare the containerized approach shown above with the diagram below that shows similar applications running in virtual machines rather than containers.

Note that a virtual machine includes a guest operating system whereas the corresponding container does not.

Parent topic: Using Visual COBOL with Docker
Related reference
Docker: Docker Overview
Docker: Docker Documentation
Related information
Benefits of Using Docker
Docker Terminology
Getting Ready to Use Visual COBOL with Docker
Docker Known Issues and Restrictions


Benefits of Using Docker

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 Docker is running and you can be sure that your application will perform exactly as it did when you tested it. You can even take images that were built on Linux and run them on Windows using Docker's Linux Container on Windows (LCOW).

  • 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 Visual COBOL Development Hub makes it easier for you to deliver the right software at the right time.

  • Isolation

    A Docker container that contains one of your applications also includes the relevant versions of any supporting software that your application requires. If other Docker containers contain applications that require different versions of the same supporting software, that isn't a problem because the different Docker 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 Docker documentation for more information on these options.

Note: Although there are a number of advantages to using Docker, 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 Docker. Micro Focus recommends that when evaluating potential use of Docker you bear in mind the types of application that you will need to run.
Parent topic: Using Visual COBOL with Docker
Related information
Introduction to Docker
Docker Terminology
Getting Ready to Use Visual COBOL with Docker


Docker Terminology

This topic provides a very brief summary of the key terms you need to be familiar with when working with Docker. 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.

Docker Hub
A cloud-based community resource for working with Docker.

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 a Docker 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.

A Docker image is a binary that includes all of the requirements for running a single Docker 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 (such as Docker Hub).

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.

Parent topic: Using Visual COBOL with Docker
Related reference
Docker: Docker Documentation
Related information
Introduction to Docker
Benefits of Using Docker
Getting Ready to Use Visual COBOL with Docker


Getting Ready to Use Visual COBOL with Docker

This topic presents information to help you install Docker so that you can use it with Visual COBOL. Before installing Docker see Docker Known Issues and Restrictions for information that might be relevant to your use of Docker.

There are two editions of Docker: Community Edition (CE) and Enterprise Edition (EE). Docker Enterprise Edition is not supported for use with Visual COBOL so you must install Docker Community Edition.

You must obtain Docker Community Edition for Red Hat Linux or SUSE Linux from your operating system provider rather than from Docker.

For full information on installing Docker on Red Hat Enterprise Linux see Red Hat: Getting Started with Containers.

For full information on installing Docker on SUSE Linux Enterprise Server see SUSE: Docker Guide.

Parent topic: Using Visual COBOL with Docker
Related reference
Red Hat: Getting Started with Containers
SUSE: Docker Guide
Related information
Introduction to Docker
Benefits of Using Docker
Docker Terminology
Docker Known Issues and Restrictions


Key Concepts When Using Docker with COBOL Applications

The topic Introduction to Docker summarizes what Docker is and the benefits of using it. The topics in this section introduce key concepts you need to be familiar with before using Docker with your COBOL applications.

  • Key Concepts When Using Docker for COBOL Application Development
  • Key Concepts When Using Docker for COBOL Application Deployment
Parent topic: Using Visual COBOL with Docker
Related reference
Using Docker with Pipeline
Related information
Building Images for COBOL Applications
Docker Demonstrations
Introduction to Docker


Key Concepts When Using Docker for COBOL Application Development

This section outlines key concepts you should be aware of before you start using Visual COBOL to develop your COBOL applications in containers. It also presents an overview of the process to use to create images for developing your COBOL applications, and directs you other topics where you can find more detailed information about the processes described.

  • Create Different Images for Different Development Tasks
  • Overview of Creating Images to Use in the Development Process
  • Additional Information on Using Docker for COBOL Application Development
Parent topic: Key Concepts When Using Docker with COBOL Applications
Related information
Key Concepts When Using Docker for COBOL Application Deployment
Building a Base Image Containing Visual COBOL Development Hub
Building an Image Containing an Application to use with Visual COBOL Development Hub
Docker Demonstrations
The Docker Demonstration for the Visual COBOL Base Image
The Hello World Docker Demonstration


Create Different Images for Different Development Tasks

When implementing Docker to help you with your development work you need to create and run different images to carry out different parts of the development process. By having a number of different images you can be sure that you always use the right tools for the job, and that the images you use are optimized to carry out their particular tasks.

For example, if you are building a COBOL application you need to use an image that provides the support to enable you to do that, but if you only want to execute an application the image you use does not need to include the build functionality.

Working with different images for different purposes and basing images on other images are techniques used widely across the Docker community.

For instance, the Visual COBOL base image is extended with an extra image that has the environment setup for interactive login use.

This version of the image has the suffix _login in the repository name and can then be used for creating an interactive Docker session that has the COBOL development environment setup ready for use. See the description of the docker run -ti command in the Docker documentation for more information.

Micro Focus uses similar naming and image layering schemes in the Docker demonstrations that are supplied with Visual COBOL and recommends that you adopt the same sort of conventions.

For example, as described above, interactive login images typically have a suffix of _login in the repository name, so when creating an image called microfocus/vcdevhub:sles12sp3_5.0_x64 the interactive login image based on this image would be called microfocus/vcdevhub:sles12sp3_5.0_x64_login.

Parent topic: Key Concepts When Using Docker for COBOL Application Development


Overview of Creating Images to Use in the Development Process

The top-level approach to creating development images to work with COBOL applications is as follows:

  1. Create a base image containing Visual COBOL Development Hub.

    As described in Create Different Images for Different Development Tasks, you might want to consider creating a small number of base images rather than just one.

    Note: Remember that any image you create with Visual COBOL is for development use only. If you want to run your COBOL applications in containers in a production environment you must use containers that are based on COBOL Server.
  2. At this stage you have two options:
    1. Use the Visual COBOL base image and make available the application's files by mounting a volume into it when it runs.

      Using this approach, you first need to build your application locally using Visual COBOL to create the executable files and the files that are required in order to debug the application. You then run your Visual COBOL Development Hub base image in a container using the -v option to make available the debug files that you created.

      The -v option to the docker run command specifies a volume to be mounted. This mounts a specified directory on your computer into a specified directory in the container, meaning that the running container has access to the files in the specified directory on your computer. The folder you need to specify on your computer is the folder into which Visual COBOL created the debug files for your application.

      Using volume mounts in this way is very convenient when debugging as it enables you to make changes to your source code, rebuild the application, then test the changes running in a container without the overhead of creating a new image.

    2. Create an application-specific image that uses one of the images created in step 1 as a base, but also contains the files for your COBOL applications that you want to work with.

      Using this approach, the Dockerfile for the image must contain the commands that are required to create the executable files and the files that are required in order to debug the application. Once you have created your application-specific image you can then run it in a container and connect your debugger to that container.

Parent topic: Key Concepts When Using Docker for COBOL Application Development


Additional Information on Using Docker for COBOL Application Development

All of the concepts that are outlined in this section are illustrated in the Docker demonstrations. These demonstrations are supplied with Visual COBOL and illustrate how to build a range of images to perform different tasks, from being used as a base image for running Visual COBOL to debugging a sample application. See Docker Demonstrations for a list of all of the supplied Docker demonstrations as well as detailed line-by-line descriptions of the most significant files in them.

For more information see:

  • Building a Base Image Containing Visual COBOL Development Hub for a description of how to create a base image that includes Visual COBOL.
  • Building an Image Containing an Application to use with Visual COBOL Development Hub for a description of how to extend the Visual COBOL base image with applications of your own that you can run and debug using Visual COBOL.
  • The Docker Demonstration for the Visual COBOL Base Image for a detailed look at the Docker demonstration files supplied with Visual COBOL that show how to create a base image for Visual COBOL Development Hub.
  • The Hello World Docker Demonstration for a detailed look at how the Docker demonstration files supplied with Visual COBOL extend the Visual COBOL Development Hub base image with an application that you can debug, test, or run.
  • Key Concepts When Using Docker for COBOL Application Deployment for an overview of the concepts you need to be aware of before creating images in which you can run your COBOL applications using COBOL Server.
Parent topic: Key Concepts When Using Docker for COBOL Application Development


Key Concepts When Using Docker for COBOL Application Deployment

This topic outlines the key concepts you need to be aware of before you start using COBOL 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 Docker for COBOL Application Deployment
Parent topic: Key Concepts When Using Docker with COBOL Applications
Related information
Key Concepts When Using Docker for COBOL Application Development
Building a Base Image Containing Visual COBOL Development Hub
Building an Image Containing an Application to use with Visual COBOL Development Hub
Docker Demonstrations
The Docker Demonstration for the Visual COBOL Base Image
The Hello World Docker Demonstration


Create Different Images for Different Deployment Tasks

A key concept of Docker 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 you create an image containing COBOL Server you can use it to run your applications but you can't interact with it. Creating an interactive login image enables you to log in to a running container that contains your COBOL Server environment so that you can manually run commands and observe what is happening in the container.

    Images such as this typically have a suffix of _login in their repository name. For example, if you create an image called microfocus/cobolserver:rhel7_5.0_x64 the image that lets you log in would be called microfocus/cobolserver:rhel7_5.0_x64_login.

  • 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.
Parent topic: Key Concepts When Using Docker 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 COBOL 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 Docker for COBOL Application Deployment


Additional Information on Using Docker for COBOL Application Deployment

All of the concepts that are outlined in this section are illustrated in the Docker demonstrations. These demonstrations are supplied with COBOL Server and illustrate how to build a range of images to perform different tasks, from being used as a base image for running COBOL Server to debugging a sample application. See Docker Demonstrations for a list of all of the supplied Docker demonstrations as well as detailed line-by-line descriptions of the most significant files in them.

Parent topic: Key Concepts When Using Docker for COBOL Application Deployment


Building Images for COBOL Applications

The section Key Concepts When Using Docker 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 Visual COBOL, 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 Docker demonstrations supplied with Visual COBOL. These demonstrations include all the files that are needed to create example images for use with Visual COBOL, and the section Docker Demonstrations contains detailed descriptions of the files contained in some of the demonstrations.

After reading this section and Docker Demonstrations you should be able to create your own images for use with your COBOL applications.

  • Building a Base Image Containing Visual COBOL Development Hub
  • Building an Image Containing an Application to use with Visual COBOL Development Hub
Parent topic: Using Visual COBOL with Docker
Related information
Key Concepts When Using Docker with COBOL Applications
Docker Demonstrations


Building a Base Image Containing Visual COBOL Development Hub

This topic outlines the steps that a Dockerfile must carry out to create a base image for Visual COBOL Development Hub.

Once you have built your Visual COBOL Development Hub base image you can then build additional images, based on the base image, that include your COBOL applications as well as Visual COBOL Development Hub. For more information on creating those additional images see Building an Image Containing an Application to use with Visual COBOL Development Hub.

Note: Remember that Visual COBOL 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 COBOL Server.

Before building a base image for Visual COBOL Development Hub you need to ensure that you have available the following:

  • The installable executable file for Visual COBOL Development Hub. This is setup_visualcobol_devhub_for_docker_5.0_platform and is supplied in the Docker demonstration for the Visual COBOL Development Hub base image.
  • The appropriate license (.mflic) file for Visual COBOL Development Hub.
  • If you will be including Java support in the image, the relevant executable file to perform the installation of the JDK. You can get this file from your chosen JDK provider.

To build a base image that includes Visual COBOL Development Hub your Dockerfile needs to perform the following steps:

  1. Specify a base image to work from. This will typically be rhel7/rhel:latest or suse/sles12sp3 depending on whether you are using Red Hat Linux or SUSE Linux.
  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.
  4. Install any packages that are required for to install successfully.
  5. Copy the installable executable file for Visual COBOL Development Hub (setup_visualcobol_devhub_for_docker_5.0_platform) from your host machine to a temporary folder in the image's filesystem.
  6. Create the user and groups whose details will be used when installing Visual COBOL Development Hub.
  7. Ensure that the installable executable file for Visual COBOL Development Hub has execute permissions, then execute it.

    When running setup_visualcobol_devhub_for_docker_5.0_platform you need to specify the following parameters:

    -IacceptEULA
    to indicate that you accept the terms of the Micro Focus End User License Agreement (EULA).
    -ESadminID=user-name
    to set the Enterprise Server System Administrator Process User ID.
  8. Configure the dynamic linker run-time bindings to include the shared objects supplied with Visual COBOL.

    Doing this avoids the need to update the LD_LIBRARY_PATH environment variable.

  9. Perform any required clean-up. This includes tasks such as resetting variables and deleting temporary folders.
  10. Install a license for Visual COBOL Development Hub then remove the license file.
Note: You might also want to create an image that you can log in to and execute shell or Visual COBOL commands. This option is useful if you are not adding any application files to a base image but want to be able to use Visual COBOL commands from it.

All of the Docker demonstrations offer the option to create such a login image, and those images are tagged with the suffix "_login". See Running the Docker Demonstration for the Visual COBOL Base Image for information on how to specify that you want to create a _login image. For details on the commands required to build such an image, see the bld.sh script in any of the Docker demonstrations.

The above process is used by the Docker demonstration that creates a base image for Visual COBOL Development Hub. For more information on that demonstration, including information on all the files it contains and a detailed description of the Dockerfiles it contains, see The Docker Demonstration for the Visual COBOL Base Image.

Parent topic: Building Images for COBOL Applications
Related information
Building an Image Containing an Application to use with Visual COBOL Development Hub
Getting Ready to Use Visual COBOL with Docker
Running the Docker Demonstration for the Visual COBOL Base Image
The Docker Demonstration for the Visual COBOL Base Image


Building an Image Containing an Application to use with Visual COBOL Development Hub

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 Visual COBOL Development Hub.

Before you follow the steps in this topic you must have built a base image for Visual COBOL Development Hub. For information on creating a base image for Visual COBOL Development Hub see Building a Base Image Containing Visual COBOL Development Hub.

Note: Remember that Visual COBOL 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 COBOL Server.

Before building an image containing an application to use with Visual COBOL Development Hub you need to ensure that you have available the following:

  • A base image for Visual COBOL Development Hub. If you have not yet built such an image, see Building a Base Image Containing Visual COBOL Development Hub for information on how to build one.

To build an image that includes an application to use with Visual COBOL Development Hub your Dockerfile needs to perform the following steps:

  1. Specify a base image to work from. This should be an image containing only Visual COBOL Development Hub. See Building a Base Image Containing Visual COBOL Development Hub for more information.
  2. Create a new user under which the application will run.
  3. Create a folder to hold the application files then copy the application files into it. If you are using SUSE Linux you will need to change ownership to specify the new user as the owner of this new folder.
  4. Specify the user name to use when the image is run.
  5. Specify the name of the executable to run when the image is run.
Note: You might also want to create an image that you can log in to and execute shell or Visual COBOL commands. This option is useful if you are not adding any application files to a base image but want to be able to use Visual COBOL commands from it.

All of the Docker demonstrations offer the option to create such a login image, and those images are tagged with the suffix "_login". See Running the Docker Demonstration for the Visual COBOL Base Image for information on how to specify that you want to create a _login image. For details on the commands required to build such an image, see the bld.sh script in any of the Docker demonstrations.

The above process is used by the Docker demonstrations that create images for applications that you can use with Visual COBOL Development Hub. For more information on one of those demonstrations, including information on all the files it contains and a detailed description of the Dockerfiles it contains, see The Hello World Docker Demonstration.

Parent topic: Building Images for COBOL Applications
Related information
Building a Base Image Containing Visual COBOL Development Hub
The Hello World Docker Demonstration
Running the Docker Demonstration for the Visual COBOL Base Image


Debugging COBOL Applications Running in Containers

This section of the documentation presents detailed information describing how you debug your COBOL applications that are running in Docker containers.

Note:
  • The information in this section applies to both native and managed COBOL unless specifically indicated. However, to be able to debug managed COBOL running in a container you must be using Visual Studio 2017 (or later).
  • Most of the debugging functionality described in this section is provided through the Eclipse IDE. As a result, much of the functionality described in this section does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment. Where a feature in this section is not available when using Visual COBOL Development Hub as a stand-alone development environment, that is indicated in the description of the feature.

To debug a containerized COBOL application you use Visual COBOL's remote debugging features. Remote debugging is not a technique specifically for containerized COBOL applications, and information on remote debugging in general is covered elsewhere in this documentation. See Debugging Using a Remote Machine for more information.

This section of the documentation covers information on remote debugging that is specifically related to containerized COBOL applications.

As described in Key Concepts When Using Docker for COBOL Application Development, there are two ways in which you can debug a COBOL application running in a container:

  • Running the Visual COBOL base image and making the application's executable and debug files available using a volume mount.
  • Building and running an application-specific image that contains the Visual COBOL base image as well as the application's executable and debug files.

This section of the documentation assumes that you are using the first of these approaches, although the majority of the steps involved are the same for both approaches.

The process for debugging a COBOL application running in a container is as follows:

  1. Build the application (for debug) on the host computer using Visual COBOL.
  2. Run the Visual COBOL base image, making sure that you volume mount the directory containing the application's executable and debug files that you built in step 1.
  3. Find out the ID or IP address of the container.
  4. Start debugging remotely as you would normally (in a non-containerized environment), specifying the ID or IP address of the container to establish a connection between the debugger and the containerized application.

The following sections contain more information on each of these steps.

  • Building a COBOL Application that is to be Debugged in a Container
  • Running a Container that is to be Debugged
  • Finding the Details of a Container that is to be Debugged
  • Starting to Debug a COBOL Application in a Container
  • Using Character Animator to Debug COBOL Applications Running in Containers
Parent topic: Using Visual COBOL with Docker


Building a COBOL Application that is to be Debugged in a Container

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.

The first step in preparing a COBOL application to be debugged in a container is to use Visual COBOL to build the application for debugging as you would normally.

If you are working with the Docker demonstrations, project files are supplied to enable you to do this.

Parent topic: Debugging COBOL Applications Running in Containers


Running a Container that is to be Debugged

This topic describes how to run a base image and volume mount an application's executable and debug files so that you can debug the application.

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.

When you run the container, you must make sure that the docker run command specifies the following in addition to any parameters that you would normally specify:

  • If the application to be debugged is a native COBOL application, the entry point cobdebugremote (for 32-bit systems) or cobdebugremote64 (for 64-bit systems) to overwrite the default entry point for the container. This means that when the container runs it starts the process that is required to enable remote debugging rather than the entry point for the application that is to be debugged.
  • The port that the container will listen on. This must be specified by an EXPOSE command in the Dockerfile that was used to create the image.

For example, the following is a docker run command you could use to run the native COBOL Hello World Docker demonstration that had been built into an image for use on 64-bit Windows platforms:

docker run -p 6100 --rm
 --name helloworld-x64-debug
 -v %CD%\src\bin\x64\Debug:c:\app
 --workdir c:\app
 --entrypoint cobdebugremote64
 -it microfocus/edbuildtools:win_5.0_x64
 port=6100

The parameters specified in the above docker run command are as follows:

-p 6100
Publishes port number 6100. This must be specified by an EXPOSE command in the Dockerfile that was used to create the image.
--rm
Specifies that Docker will automatically remove the container when it finishes running.
--name helloworld-x64-debug
Specifies the name to be used for the container.
-v %CD%\src\bin\x64\Debug:c:\app
Mounts the local folder %CD%\src\bin\x64\Debug into the folder c:\app in the container. %CD% refers to the current directory and can only be used if you run the docker run command from a Windows batch file. If you run the command from the command line you can use the PowerShell automatic variable ${PWD} or specify the current directory in full.
--workdir c:\app
Sets the working directory for the container. This must be the same folder that is specified by the -v parameter.

--entrypoint cobdebugremote64
Specifies the 64-bit cobdebugremote64 module to enable remote debugging. This is only required for native COBOL applications.
-it
Specifies that the container runs interactively.
microfocus/edbuildtools:win_5.0_x64
Specifies the name of the image to run. In this case, this is the 64-bit Windows version of the Enterprise Developer Build Tools for Windows image.
port=6100
A command line paramter for the container.

When the container is running, if the application running is in native COBOL a message such as the following is displayed to indicate that the container is running and cobdebugremote (or cobdebugremote64) is ready to connect for debugging:

Waiting for a connection on machine IP-address/container-name using port port-number.
Press 'Q' to quit.
Parent topic: Debugging COBOL Applications Running in Containers
Related reference
Docker: Dockerfile Command Line
Related information
Key Concepts When Using Docker for COBOL Application Development


Finding the Details of a Container that is to be Debugged

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.

Once the container to be debugged is running you need to find out some identifying information about it that you can then specify to Visual COBOL so that you can connect to the container to start debugging it.

You can specify either of the following pieces of information to Visual COBOL:

  • The container's ID.

    To display summary information of all running containers (including their IDs) enter the following command:

    docker ps
  • The container's IP address.

    To find the IP address used by a running container you use the docker inspect command. The docker inspect command can return a wide range of information, but to return the IP address of a container the format of the docker inspect command is shown below:

    docker inspect -f "{{ .NetworkSettings.Networks.nat.IPAddress }}" container-name-or-id

    So, for example, to find the IP address of the container that would have been started by the docker run command in Running a Container that is to be Debugged you could use the following command:

    docker inspect -f "{{ .NetworkSettings.Networks.nat.IPAddress }}" helloworld-x64-debug
Parent topic: Debugging COBOL Applications Running in Containers


Starting to Debug a COBOL Application in a Container

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.

Once your base image is running and you have found out its ID or IP address you are ready to use Visual COBOL to connect to the container using remote debugging.

If you have followed the steps outlined in Building a COBOL Application that is to be Debugged in a ContainerRunning a Container that is to be Debugged and Finding the Details of a Container that is to be Debugged you will have a container that isn't yet running your COBOL application but is waiting for you to connect to it using Visual COBOL. See To start debugging a COBOL application that is not yet running in a container for full information on how to do this.

Note: If you have a debuggable COBOL application that is already running in a container you can still connect to the application and debug it. See To start debugging a COBOL application that is already running in a container for more information on how to do this.
  • To start debugging a COBOL application that is not yet running in a container
  • To start debugging a COBOL application that is already running in a container
Parent topic: Debugging COBOL Applications Running in Containers


To start debugging a COBOL application that is not yet running in a container

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.
  1. Open the application's project in Visual COBOL.

    If you are working with one of the Docker demonstrations, they include the relevant project files.

  2. Create a new debug configuration:
    1. Click Run > Debug configurations.
    2. In the left side pane of the Debug Configurations dialog box double-click COBOL Application.
    3. Change the name from New_configuration to something relevant to your application.
    4. In the Connection Properties section:
      1. Specify the IP address of the container in the Remote Host field.
        Note: You can specify the container's ID instead of its IP address.
      2. Check Specify the port on which the cobdebugremote process will listen on the remote host.
      3. In the cobdebugremote port field, specify the port that the container is listening on. This would be 6100 for the container that would have been started by the docker run command in Running a Container that is to be Debugged.
    5. In the Main Program section:
      1. Uncheck Program is part of project build configuration.
      2. In the field below, specify the application to be run in the container's Docker working directory.

        For example, for the container that would have been started by the docker run command in Running a Container that is to be Debugged you would specify the following:

        c:\app\exe-name.exe

    6. In the Debug Options section, ensure that the setting of Application is 64 bit reflects whether the application to be debugged is 32-bit or 64-bit.
  3. Click Debug.
Parent topic: Starting to Debug a COBOL Application in a Container
Related information
Finding the Details of a Container that is to be Debugged
Running a Container that is to be Debugged


To start debugging a COBOL application that is already running in a container

Note: This topic does not apply if you are using Visual COBOL Development Hub as a stand-alone development environment.
  1. Open the application's project in Visual COBOL.

    If you are working with one of the Docker demonstrations, they include the relevant project files.

  2. Set a breakpoint on the line where you want execution to pause when you connect to the application.
  3. Create a new debug configuration:
    1. Click Run > Debug configurations.
    2. In the left side pane of the Debug Configurations dialog box double-click COBOL Attach to Process.
    3. Change the name from New_configuration to something relevant to your application.
    4. In the COBOL Project section, specify the name of the project to be used while debugging.
    5. In the Connection Properties section:
      1. Specify the IP address of the container in the Remote Host field.
        Note: You can specify the container's ID instead of its IP address.
      2. Check Specify the port on which the cobdebugremote process will listen on the remote host.
      3. In the cobdebugremote port field, specify the port that the container is listening on. This would be 6100 for the container that would have been started by the docker run command in Running a Container that is to be Debugged.
    6. In the Debug Options section, ensure that the setting of Application is 64 bit reflects whether the application to be debugged is 32-bit or 64-bit.
  4. Click Debug.
  5. When the Select Process dialog box appears, select the application you want to the debug and wait until debugging starts.
Parent topic: Starting to Debug a COBOL Application in a Container
Related information
Finding the Details of a Container that is to be Debugged
Running a Container that is to be Debugged


Using Character Animator to Debug COBOL Applications Running in Containers

This topic describes how you can use Character Animator to debug a COBOL application running in a Docker container.

Note:
  • Micro Focus does not recommend the use of Character Animator in Visual COBOL because the Eclipse IDE provides an excellent environment in which to debug your applications. In certain circumstances, however, Character Animator can still provide useful functionality, so if you are familiar with using Animator you might want to continue to use it in such circumstances.

To use Character Animator to debug a COBOL application running in a Docker container:

  1. Run a Visual COBOL image and start a bash shell in it. You can use a command such as the following to do this:
    docker run -it --cap-add=SYS_PTRACE microfocus/vcdevhub:sles12sp3_5.0_x64 /bin/bash
    Note:
    • On Red Hat Linux the name of the image to run would be microfocus/vcdevhub:rhel7_5.0_x64.
  2. Compile the program that you want to debug:
    cob -a prog-name.cbl
  3. Animate the program:
    anim prog-name.int
Parent topic: Debugging COBOL Applications Running in Containers
Related information
The Docker Demonstration for the Visual COBOL Base Image
Compiling and Linking from the Command Line


Docker Demonstrations

Visual COBOL includes a number of Docker demonstrations that supplement the information in this documentation to illustrate how to create images to work with COBOL applications. This section lists the Docker demonstrations that are supplied, and for some of the supplied demonstrations provides detailed information such as descriptions of the files that are included and a line-by-line description of the supplied Dockerfiles.

  • Supplied Docker Demonstrations
  • Using the Docker Demonstrations
  • The Docker Demonstration for the Visual COBOL Base Image
  • The Hello World Docker Demonstration
Parent topic: Using Visual COBOL with Docker
Related reference
Docker: Best Practices for Writing Dockerfiles
Related information
Key Concepts When Using Docker with COBOL Applications
Building Images for COBOL Applications


Supplied Docker Demonstrations

This topic lists the different Docker demonstrations that are supplied with Visual COBOL, specifies the folder they are contained in, and provides a brief summary of what they do.

Docker Demonstration | Location | Summary
Base Image | DevHub | Creates a base image for Visual COBOL Development Hub.
Ant | Examples/Build_demo_ant | Uses Ant to create an image containing a sample (Hello World) application that can be run or debugged.
Hello World | Examples/Build_HelloWorld | Creates an image containing a sample (Hello World) application that can be run or debugged.
Hello World (JVM) | Examples/Build_JVM_HelloWorld | Creates an image containing a sample managed COBOL (Hello World) application that can be run or debugged.
JSON | Examples/Build_demo_json | Compiles the Visual COBOL JSON demo in a container and uses the results to produce a new image with the example.
MFUnit | Examples/Build_demo_mfunit | Compiles the Visual COBOL MFUnit demo in a container and uses the results to produce a new image with the example.
Multithreading | Examples/Build_demo_mthread | Compiles the Visual COBOL Mthread demo in a container and uses the results to produce a new image with the example.

For detailed information see The Docker Demonstration for the Visual COBOL Base Image and The Hello World Docker Demonstration.

Parent topic: Docker Demonstrations
Related information
Using the Docker Demonstrations
The Docker Demonstration for the Visual COBOL Base Image
The Hello World Docker Demonstration


Using the Docker Demonstrations

Visual COBOL includes a number of Docker demonstrations that illustrate typical uses of Docker with COBOL applications.

These Docker 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 Docker demonstrations (including detailed descriptions of the Dockerfiles themselves). After running the Docker 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 Docker demonstrations are supplied in the file devhub_dockerfiles_5.0_platform.tar which is accessible from the same place that you accessed the Visual COBOL installation file. Unzip devhub_dockerfiles_5.0_platform.tar into a folder of your choice to create a series of folders containing the Docker demonstrations.

Each Docker demonstration includes the following:

  • A readme.html file that summarizes what it does and explains how to use it.
  • A bld.sh file to run it. Execute bld.sh 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 Docker Demonstration for the Visual COBOL Base Image and Running the Hello World Docker Demonstration.

See Supplied Docker Demonstrations for information on the Docker demonstrations that are available.

Parent topic: Docker Demonstrations
Related information
The Docker Demonstration for the Visual COBOL Base Image
The Hello World Docker Demonstration
Running the Docker Demonstration for the Visual COBOL Base Image
Running the Hello World Docker Demonstration
Supplied Docker Demonstrations


The Docker Demonstration for the Visual COBOL Base Image

This section of the documentation introduces the Docker demonstration for the Visual COBOL base image, shows how to run it, describes the files it includes, and gives a detailed description of the Dockerfiles it contains.

  • Introduction to the Docker Demonstration for the Visual COBOL Base Image
  • Running the Docker Demonstration for the Visual COBOL Base Image
  • Files in the Docker Demonstration for the Visual COBOL Base Image
  • Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image
Parent topic: Docker Demonstrations
Related information
Supplied Docker Demonstrations
Using the Docker Demonstrations
The Hello World Docker Demonstration


Introduction to the Docker Demonstration for the Visual COBOL Base Image

The Docker demonstration for the Visual COBOL base image contains all the files that you need to build an image containing Visual COBOL. 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 Visual COBOL.

Parent topic: The Docker Demonstration for the Visual COBOL Base Image
Related information
Running the Docker Demonstration for the Visual COBOL Base Image
Files in the Docker Demonstration for the Visual COBOL Base Image
Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image


Running the Docker Demonstration for the Visual COBOL Base Image

The Docker demonstration to create the Visual COBOL base image includes a shell script (bld.sh) 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.sh.

Note: When using bld.sh to create a base image for Visual COBOL you need to ensure that the relevant installation files and licenses are available in the same folder as bld.sh. These are:
  • The installable executable file for Visual COBOL Development Hub. This is setup_visualcobol_devhub_for_docker_5.0_platform and is supplied in the Docker demonstration for the Visual COBOL Development Hub base image.
  • The appropriate license (.mflic) file for Visual COBOL Development Hub.
  • If you will be including Java support in the image, the relevant executable file to perform the installation of the JDK. You can get this file from your chosen JDK provider.

The command to execute the shell script to run the Docker demonstration for the Visual COBOL base image is as follows:

./bld.sh IacceptEULA
         [dryrun]
         [esadmgid=admin-gid]
         [esadminuser=admin-id]
         [esadmuid=admin-uid]
         [login|nologin]
         [logingid=login-gid]
         [loginid=login-id]
         [logingname=login-gname]
         [loginname=login-name]
         [nojava | (java | oraclejava) [javaversion=java-version]]
         [notools]
         [package]
         [rmi]
         [settings]
         [verbose]
IacceptEULA
Indicates that you accept the Micro Focus End User License Agreement (EULA).

You must specify IacceptEULA to create a base image containing Visual COBOL.

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.
java
Indicates that you want the image to include Java support provided by the AdoptOpenJDK OpenJDK. Use the javaversion parameter to specify the version of Java that you want support for.
javaversion=java-version
When specified with the java or oraclejava parameters, specifies the version of Java that you want support for. java-version can be 8, 9, or 10.
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 Visual COBOL commands.

This option is useful if you are not adding any application files to a base image but want to be able to use Visual COBOL 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 Visual COBOL. 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.
oraclejava
Indicates that you want the image to include Java support provided by the Oracle JDK. Use the javaversion parameter to specify the version of Java that you want support for.
package
Indicates that you want to rebuild the COBOL application in this image.
rmi
Indicates that you want to remove any previously-created Visual COBOL base images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove all Visual COBOL base images.
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 Visual COBOL, 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.
Parent topic: The Docker Demonstration for the Visual COBOL Base Image
Related information
Introduction to the Docker Demonstration for the Visual COBOL Base Image
Files in the Docker Demonstration for the Visual COBOL Base Image
Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image


Files in the Docker Demonstration for the Visual COBOL Base Image

The files contained in the Docker demonstration for the Visual COBOL base image are as follows:

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.funcs | Definitions of functions used in the bld.sh script.
bld.sh | Shell script to automate the process of building Visual COBOL images. For full details on the parameters you can specify to bld.sh see Running the Docker Demonstration for the Visual COBOL Base Image.
Dockerfile | Dockerfile used to build the Visual COBOL base image. For a detailed look at the commands used in this file, see Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image.
palic.env | Configuration file used to specify the name of the license (.mflic) file for Visual COBOL.
prodver.env | Configuration file containing a setting that specifies the version of Visual COBOL that this Docker demonstration is supplied with.
README*.* | Files for HTML and plain text documents containing instructions on how to build the Visual COBOL base image.
setup_visualcobol_devhub_for_docker_5.0_platform | The installable executable file for Visual COBOL Development Hub. There is also an associated .sum file for this file. You can ignore this file.
Note: The name of the Visual COBOL base image depends on the platform you are using:
  • On Red Hat Linux the base image is microfocus/vcdevhub:rhel7_5.0_x64.
  • On SUSE Linux the base image is microfocus/vcdevhub:sles12sp3_5.0_x64.
Parent topic: The Docker Demonstration for the Visual COBOL Base Image
Related information
Introduction to the Docker Demonstration for the Visual COBOL Base Image
Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image
Running the Docker Demonstration for the Visual COBOL Base Image


Dockerfiles in the Docker Demonstration for the Visual COBOL Base Image

This topic describes in detail the commands used by the Dockerfile in the Docker demonstration for the Visual COBOL base image. The Dockerfile is listed in its entirety and a following table describes the various Dockerfile commands. The line numbers in the listings of the Dockerfile have been added to aid readability. They are not present in the supplied Dockerfile.

Note: The Dockerfiles supplied for Red Hat Linux and SUSE Linux differ slightly. The Dockerfile shown below is the one supplied with Red Hat Linux. Where there are differences between the two versions they are described in the following table.
001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  FROM rhel7/rhel:latest
004
005  # PRODUCT_VERSION is product version associated with this Dockerfile
006  # ACCEPTEULA is the build-arg name for the acceptance of the end user license agreement
007  # SETUP_EXE is the build-arg name name of installer to used
008  # COBSRV_LOC is the build-arg name for the installation location
009  # MFLICFILE is the build-arg name for the license filename
010  ARG PRODUCT_VERSION=5.0.00
011  ARG ACCEPTEULA
012  ARG SETUP_EXE=setup_visualcobol_devhub_for_docker_5.0_redhat_x64
013  ARG LOGFILE=VisualCOBOLDevelopmentHub5.0.log
014  ARG MFLICFILE
015
016  ARG ESADM_UID=500
017  ARG ESADM_GID=500
018  ARG ESADM_USER=esadm
019  ARG ESADM_SHELL=/bin/bash
020
021  LABEL vendor="Micro Focus" \
022        com.microfocus.name="Visual COBOL" \
023        com.microfocus.version="$PRODUCT_VERSION" \
024        com.microfocus.eula.url="https://supportline.microfocus.com/licensing/agreements.aspx" \
025        com.microfocus.is-base-image="true"
026
027  ENV MFPRODBASE=/opt/microfocus/VisualCOBOL
028  ENV MFLICBASE=/var/microfocuslicensing
029
030  # install ed, pax, gcc, gcc-c++, make and glibc-devel.x86_64 as these are a pre-req for the installer
031  RUN yum -y --disablerepo=rhel-7-server-rt-beta-rpms install ed pax gcc gcc-c++.x86_64 gdb glibc-devel.x86_64 make file
032
033  # copy the installer from the local machine to the container
034  COPY ${SETUP_EXE} /tmp/${SETUP_EXE}
035
036  # Create user esadm
037  RUN groupadd -f -g $ESADM_GID $ESADM_USER && \
038      useradd -u $ESADM_UID -g $ESADM_GID -m -s $ESADM_SHELL $ESADM_USER
039
040  # ensure the setup exe has execute permissions and execute the setup
041  RUN chmod +x ./tmp/${SETUP_EXE} && \
042      (/tmp/$SETUP_EXE -${ACCEPTEULA} -ESadminID=$ESADM_USER || (echo ${LOGFILE} contains && touch ${LOGFILE} && cat ${LOGFILE} && exit 1)) && \
043      rm -f tmp/${SETUP_EXE} && \
044      echo "$MFPRODBASE/lib" >>/etc/ld.so.conf && \
045      ldconfig
046
047  # install a license and remove the license file
048  COPY ${MFLICFILE} /tmp/
049  RUN cd /tmp && $MFLICBASE/bin/MFLicenseAdmin -install "${MFLICFILE}" && rm -f "${MFLICFILE}"
050  #
051  # clean up for containers that use -network:host
052  #
053  RUN  $MFLICBASE/bin/clean_guid_file

The commands on the lines in this Dockerfile are as follows:

Lines | Description
003 Specifies the base image to use. For Red Hat this is the official Docker image for Red Hat Enterprise Linux.

For SUSE Linux this line is as follows:

FROM suse/sles12sp3

This specifies that the base image to use is the official Docker image for SUSE Linux Enterprise Server.

010 - 019 Define build arguments passed by the docker build command:
  • PRODUCT_VERSION.Indicates the version of Visual COBOL that this Dockerfile is supplied with.
  • SETUP.EXE. Specifies the name of the Visual COBOL installation file. The default setting is the name of the file supplied with Visual COBOL.
  • ACCEPTEULA. Indicates whether the terms of the Micro Focus End User License Agreement (EULA) have been accepted.
  • LOGFILE. Specifies the name to use for the log file created when installing Visual COBOL into the image.
  • MFLICFILE. Specifies the name of the license file to use for Visual COBOL.
  • ESADM_UID. Specifies the user ID to use for the Enterprise Server admin user.
  • ESADM_GID. Specifies the group ID to use for the Enterprise Server admin user.
  • ESADM_USER. Specifies the ID to be used for the Enterprise Server admin user.
  • ESADM_SHELL. Specifies the shell to use for the Enterprise Server admin user.
021 - 025 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
027 - 028 Create environment variables to be used in this Dockerfile:
  • MFPRODBASE. Specifies the folder into which Visual COBOL is installed.
  • MFLICBASE. Specifies the folder where the Micro Focus License Administration tool is installed.
031 | Install software that is required to be able to install Visual COBOL.
033 | Copy the installation file for Visual COBOL into a temporary folder.
037 - 038 | Run a series of concatenated commands to add the Enterprise Server admin user and set up the shell to be used by that user.
041 - 045 Run a series of concatenated commands to perform the following actions:
  1. Make the Visual COBOL installation file executable.
  2. Run the Visual COBOL installation file using options to indicate acceptance of the license agreement and to specify the System Administrator Process User ID.
  3. Delete the temporary folder that you created earlier (containing the Visual COBOL installation file).
  4. Configure the dynamic linker run-time bindings to include the shared objects supplied with Visual COBOL.

    Doing this avoids the need to update the LD_LIBRARY_PATH environment variable.

048 - 049 | Copy the license file to a temporary location, use it to license Visual COBOL, then delete the license file.
053 | Run a script to reset the temporary file used when applying the license for Visual COBOL.
Parent topic: The Docker Demonstration for the Visual COBOL Base Image
Related reference
Docker: Best Practices for Writing Dockerfiles
Related information
Introduction to the Docker Demonstration for the Visual COBOL Base Image
Running the Docker Demonstration for the Visual COBOL Base Image
Files in the Docker Demonstration for the Visual COBOL Base Image


The Hello World Docker Demonstration

This section of the documentation introduces the Hello World Docker demonstration, shows how to run it, describes the files it includes, and gives a detailed description of the Dockerfiles it contains.

  • Introduction to the Hello World Docker Demonstration
  • Running the Hello World Docker Demonstration
  • Files in the Hello World Docker Demonstration
  • Dockerfiles in the Hello World Docker Demonstration
Parent topic: Docker Demonstrations
Related information
Supplied Docker Demonstrations
Using the Docker Demonstrations
The Docker Demonstration for the Visual COBOL Base Image


Introduction to the Hello World Docker Demonstration

The Hello World Docker demonstration for Visual COBOL builds on the Visual COBOL base image and adds the source files for a sample (Hello World) application to illustrate how you can work with your COBOL applications in Docker containers.

Parent topic: The Hello World Docker Demonstration
Related information
Running the Hello World Docker Demonstration
Files in the Hello World Docker Demonstration
Dockerfiles in the Hello World Docker Demonstration


Running the Hello World Docker Demonstration

The Hello World Docker demonstration includes a shell script (bld.sh) 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.sh.

The command to execute the shell script to run the Hello World Docker demonstration is as follows:

./bld.sh IacceptEULA
         [dryrun]
         [esadmgid=admin-gid]
         [esadminuser=admin-id]
         [esadmuid=admin-uid]
         [login|nologin]
         [logingid=login-gid]
         [loginid=login-id]
         [logingname=login-gname]
         [loginname=login-name]
         [nojava | (java | oraclejava) [javaversion=java-version]]
         [notools]
         [package]
         [rmi]
         [settings]
         [verbose]
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.
java
Indicates that you want the image to include Java support provided by the AdoptOpenJDK OpenJDK. Use the javaversion parameter to specify the version of Java that you want support for.
javaversion=java-version
When specified with the java or oraclejava parameters, specifies the version of Java that you want support for. java-version can be 8, 9, or 10.
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 Visual COBOL commands.

This option is useful if you are not adding any application files to a base image but want to be able to use Visual COBOL 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 Visual COBOL. 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.
oraclejava
Indicates that you want the image to include Java support provided by the Oracle JDK. Use the javaversion parameter to specify the version of Java that you want support for.
package
Indicates that you want to rebuild the COBOL application in this image.
rmi
Indicates that you want to remove any previously-created Hello World images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove any Hello World images.
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 Visual COBOL, 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.
Parent topic: The Hello World Docker Demonstration
Related information
Introduction to the Hello World Docker Demonstration
Files in the Hello World Docker Demonstration
Dockerfiles in the Hello World Docker Demonstration


Files in the Hello World Docker Demonstration

The files contained in the Hello World Docker demonstration are as follows:

src folder | Folder containing the source file and script needed to rebuild the project in the Hello World Docker 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.
bld.funcs | Definitions of functions used in the bld.sh script.
bld.sh | Shell script to automate the process of building Hello World Docker demonstration images. For full details on the parameters you can specify to bld.sh see Running the Hello World Docker Demonstration.
bld_package.sh | Shell script to rebuild and package the Hello World application.
Dockerfile | Dockerfile used to build the Hello World Docker demonstration image. For a detailed look at the commands used in this file, see Dockerfiles in the Hello World Docker Demonstration.
Dockerfile.prod | Dockerfile used to build a production version of the Hello World Docker demonstration image. Dockerfile.prod uses the COBOL Server base image (which is suitable for production) whereas Dockerfile uses the Visual COBOL base image (which is for development only).
README*.* | Files for HTML and plain text documents containing instructions on how to build the Hello World images.
Note: The name of the Visual COBOL base image depends on the platform you are using:
  • On Red Hat Linux the base image is microfocus/vcdevhub:rhel7_5.0_x64.
  • On SUSE Linux the base image is microfocus/vcdevhub:sles12sp3_5.0_x64.
Parent topic: The Hello World Docker Demonstration
Related information
Introduction to the Hello World Docker Demonstration
Running the Hello World Docker Demonstration
Dockerfiles in the Hello World Docker Demonstration


Dockerfiles in the Hello World Docker Demonstration

This topic describes in detail the commands used by the Dockerfiles in the Hello World Docker demonstration.

Before reading this topic you should be familiar with the processes defined in Building a Base Image for Visual COBOL Development Hub and Building an Image Containing an Application to use with Visual COBOL Development Hub, and you need to have run the Docker demonstration to have created a base image for Visual COBOL.

The Hello World Docker demonstration includes two Dockerfiles:

Dockerfile
The Dockerfile used to create an image in which the Hello World application executes under Visual COBOL.
Dockerfile.prod
The Dockerfile used to create an image in which the Hello World application executes under COBOL Server.
  • The Dockerfile File in the Hello World Docker Demonstration
  • The Dockerfile.prod File in the Hello World Docker Demonstration
Parent topic: The Hello World Docker Demonstration
Related information
Introduction to the Hello World Docker Demonstration
Running the Hello World Docker Demonstration
Files in the Hello World Docker Demonstration


The Dockerfile File in the Hello World Docker Demonstration

This topic lists and describes the Dockerfile file from the Hello World Docker demonstration. The Dockerfile is listed in its entirety and a following table describes the various Dockerfile commands. The line numbers in the listings of the Dockerfile have been added to aid readability. They are not present in the supplied Dockerfile.

Note: The Dockerfiles supplied for Red Hat Linux and SUSE Linux differ slightly. The Dockerfile shown below is the one supplied with Red Hat Linux. Where there are differences between the two versions they are described in the following table.
001  # Copyright (C) Micro Focus 2019. All rights reserved.
002  # This sample code is supplied for demonstration purposes only
003  # on an "as is" basis and is for use at your own risk.
004
005  FROM microfocus/vcdevhub:rhel7_5.0_x64
006
007  LABEL com.microfocus.is-base-image="false"
008
009  RUN useradd -ms /bin/bash app
010  ADD HelloWorld.tar.gz /home/app/
011
012  USER app
013  WORKDIR /home/app
014  ENTRYPOINT ./HelloWorld

The commands on the lines in this Dockerfile are as follows:

Lines | Description
005 | Specifies the base image to use, which is the Visual COBOL base image. On SUSE Linux the tag specified in the Dockerfile is sles12sp3_5.0_x64.
007 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
009 | Runs the useradd command to add a new user called "app" with a login shell of /bin/bash. On SUSE Linux, the corresponding action is achieved by a the RUN useradd and RUN chown commands on lines 9 and 10.
010 | Copies the files for the Hello World application into the /home/app folder in the image's filesystem. On SUSE Linux this command is on line 11.
012 - 014 | Sets the user name to be used when running the image and specifies that running the image executes the Hello World application. On SUSE Linux these commands are on lines 13 through 15.
Parent topic: Dockerfiles in the Hello World Docker Demonstration
Related reference
Docker: Best practices for writing Dockerfiles


The Dockerfile.prod File in the Hello World Docker Demonstration

This topic lists and describes the Dockerfile.prod file from the Hello World Docker demonstration. The Dockerfile is listed in its entirety and a following table describes the various Dockerfile commands. The line numbers in the listings of the Dockerfile have been added to aid readability. They are not present in the supplied Dockerfile.

Note: The Dockerfiles supplied for Red Hat Linux and SUSE Linux differ slightly. The Dockerfile shown below is the one supplied with Red Hat Linux. Where there are differences between the two versions they are described in the following table.
001  # Copyright (C) Micro Focus 2019. All rights reserved.
002  # This sample code is supplied for demonstration purposes only
003  # on an "as is" basis and is for use at your own risk.
004
005  FROM microfocus/cobolserver:rhel7_5.0_x64
006
007  RUN useradd -ms /bin/bash app
008  ADD HelloWorld.tar.gz /home/app/
009
010  USER app
011  WORKDIR /home/app
012  ENTRYPOINT ./HelloWorld

The commands on the lines in this Dockerfile are as follows:

Lines | Description
005 | Specifies the base image to use, which is the COBOL Server base image. On SUSE Linux the tag specified in the Dockerfile is sles12sp3_5.0_x64.
007 | Runs the useradd command to add a new user called "app" with a login shell of /bin/bash. On SUSE Linux, the corresponding action is achieved by a the RUN useradd and RUN chown commands on lines 9 and 10.
008 | Copies the files for the Hello World application into the /home/app folder in the image's filesystem. On SUSE Linux this command is on line 11.
010 - 012 | Sets the user name to be used when running the image and specifies that running the image executes the Hello World application. On SUSE Linux these commands are on lines 13 through 15.
Parent topic: Dockerfiles in the Hello World Docker Demonstration
Related reference
Docker: Best practices for writing Dockerfiles


Programming

  • COBOL Programming
  • Compatibility
  • Data Access
  • Using COBOL and Java Together
  • Managed COBOL Programming
  • Multi-threaded Programming
  • Performance Programming
  • Problem Determination and Diagnostic Tools
  • Unit Testing from the Command Line
    For native COBOL applications and procedural applications compiled as JVM COBOL, you can create, compile, run and debug unit tests from the command line.
  • Programming Tips
Parent topic: Visual COBOL Development Hub 5.0


COBOL Programming

  • Getting Started with COBOL
  • Calling COBOL Programs
  • Internationalization Support
  • Preparing Applications for Enterprise Server
  • Web Services Support for Native COBOL
    Describes how Visual COBOL and Enterprise Server support Native COBOL applications as Web services.
  • Mixed Language Programming
    This section covers parameters, return codes and call conventions for mixed language development with native COBOL.
  • Using COBOL and XML together
  • 64-bit Native COBOL Programming
  • Embedded HTML
    Embedded HTML (EHTML) enables you to output HTML directly from a COBOL CGI program.
Parent topic: Programming


Getting Started with COBOL

COBOL (Common Business-Oriented Language) was developed in 1959 and, since then, has been used as the basis for many business and government applications. Reports show that over 80% of the world's business applications run on COBOL with billions more lines of code existing and billions being written annually.

Micro Focus has been the market leader and provider of distributed COBOL development tooling for nearly 40 years. Micro Focus's COBOL has evolved and today it differs significantly to the COBOL language of 1959, embracing object-orientation and enabling you to write code that takes full advantage of new operating systems and platforms such as Microsoft's .NET framework and the Java Virtual Machine (JVM).

Learn

To help you learn COBOL, Micro Focus provides a wide range of resources to help you get started with the basics of the language:

  • A Micro Focus course introducing you to COBOL programming, Visual COBOL: Modern COBOL for the Next Generation.

    This course is the ideal first step on your journey to learning about the COBOL language and how to take advantage of what Visual COBOL can do for you. After taking the course you will have a good knowledge of the basics of COBOL and Visual COBOL, and will be ready to build on that general knowledge by learning more about taking full advantage of Visual COBOL to meet the specific requirements of your applications.

    The course is available from a link in your Micro Focus Electronic Product Delivery email which you were sent about your license. Follow the link and click the Documentation tab.

  • Other training courses - available from Support & Services on the Micro Focus Web site.
  • Developing Applications in this product help - provides details about how to use Visual COBOL to create COBOL applications.
  • Training videos on the Micro Focus You Tube channel.

Practice

Check the available tutorials ranging from a basic tutorial showing you how to create your First Hello COBOL World Application to more advanced tutorials showing how to use various programming techniques.

Explore

Find more information on various aspects of COBOL programming in the rest of this section.

Also, explore our detailed COBOL Language Reference for in-depth information about the syntax and the usage of the COBOL language.

Explore the power of COBOL to prepare your applications for interaction with modern day technologies. Managed COBOL is COBOL with extensions to support the JVM and the .NET frameworks, respectively. It offers support for object orientation and access to the available Java class libraries or the .NET CLR. See:

  • Introduction to Object-Oriented Programming for COBOL Developers
  • Visual COBOL - A Developer's Guide to Modern COBOL - in PDF format, available from the Micro Focus Web site.

For more, see the resources available in the Related Information.

Parent topic: COBOL Programming
Related reference
COBOL Language Reference
Comparison of COBOL with Other Managed Languages
Managed COBOL Programming
Managed COBOL Reference
Micro Focus Community Forums
Micro Focus Support and Services
Micro Focus YouTube Channel
Object-Oriented Programming for COBOL Developers


Calling COBOL Programs

There are a variety of ways to call programs, each one being appropriate in a different situation.

  • Specifying the Program to Be Called
  • State of the Data when a Program is Called Again
  • Search Conventions Used for Calling Programs
  • Passing Parameters to a Called Program
  • Passing Return Codes Back to the Calling Program
  • Call Prototypes
Parent topic: COBOL Programming


Specifying the Program to Be Called

When you call one COBOL program from another, you specify the name of the program to call either in a data-name or as a literal. For example:

CALL progname USING ...
CALL "progname" USING ...

where progname (without quotation marks) is a data item that contains a valid program-name, and "progname" (with quotation marks) is a literal string and is the actual name of a valid program.

  • Naming a Program in its PROGRAM-ID Paragraph
  • Entry Point Mapping for COBOL Programs
  • Calling a Program Using an Implicit Program Name
  • Calling a Program Using an Explicit Program Name
  • Calling Entry Points in Subprograms
  • Calling Programs According to How They Are Linked
Parent topic: Calling COBOL Programs
Related information
State of the Data when a Program is Called Again
Search Conventions Used for Calling Programs
Passing Parameters to a Called Program
Passing Return Codes Back to the Calling Program
Call Prototypes


Naming a Program in its PROGRAM-ID Paragraph

The CALL statement identifies the program to be called, by giving either the program's filename or the program's program-name. This program-name is defined in its PROGRAM-ID paragraph.

In general, make the program-name the same as the filename. In other words, in the program's PROGRAM-ID paragraph, specify the program's filename without its extension. This enables you to call the program using this common name, without knowing whether the name is the filename or the program name. This gives you the flexibility to change how the program is linked, and yet still call it successfully.

The CALL statement locates called programs differently depending on how they are linked:

  • A dynamically loadable program can be located only by its filename (with or without its extension), because the program name is not yet known as the program is not yet loaded into memory. This means that the CALL statement must quote the filename of the program to call.

    If you make the program name the same as the filename, you can quote that name in the CALL statement, and it will call the program whether it is statically and dynamically linked.

Parent topic: Specifying the Program to Be Called
Related information
Limits on Names, Literals and PICTURE Character Strings


Entry Point Mapping for COBOL Programs

The Entry Point Mapper enables you to specify entry points in COBOL programs so that the application can find them at run time. You need to do this for any entry points in programs that will not have been loaded prior to them being called.

To appreciate why and when to use this facility, you need to understand how calls to entry points are resolved by the run-time system:

  • When a program makes a call to an entry point, the run-time system looks for the entry point to resolve it dynamically.
  • When the program is loaded, the name of the program and all the entry points in the program are recorded in a table. When a call to an entry point is made, the run-time system searches the table for the entry point name. If it does not find the entry point name, it looks on disk for an executable file of the same name.
  • Consequently, if your program calls an entry point that is not the name of an executable file and is not an entry point in a previously loaded program, the run-time system cannot find the entry point and your program fails. This is when you need to use the Entry Point Mapper.

Entry points are often not found when you take code that has been downloaded from a mainframe to the PC for further development. Mainframe programs often have several entry points in a single program. On the mainframe, entry points are resolved by linking, so calls can be made to a program and the entry point located whether or not the program has been called. Using your COBOL development system, if the program containing the entry point has not already been called, the call to that entry point fails.

To ensure the entry points are found, you use the Entry Point Mapper. You create an entry name map file containing an entry point table and make it available to the run-time system.

Parent topic: Specifying the Program to Be Called


Calling a Program Using an Implicit Program Name

A program name is considered implicit if you specify only the basename of the program's filename in the call. For example:

CALL "myprog" USING ...

refers to a file in the following formats:

  • myprog.gnt
  • myprog.int
  • myprog.dll
  • myprog.lbr.

In the case of myprog.lbr, the run-time system searches the .lbr file for an executable file with the same program-name as the .lbr file, for example myprog.gnt.

Additionally, you can specify the exact location of the program to be called, by qualifying the program call with a PC drive-letter or pathname. For example, to look in the directory c:\programs for the program myprog, use the statement:

CALL "c:\programs\myprog" USING ....

Note, however, that specifying the drive or pathname is not recommended, as unexpected results can occur where the referenced module exists in more than one file, or type of format, or if the application is ported to other environments.

Parent topic: Specifying the Program to Be Called


Calling a Program Using an Explicit Program Name

A program name is considered explicit if you specify the program's full filename including its extension in the call. For example:

CALL "abc.gnt" USING ....

This forces the run-time system to look for the exact filename that you specify, in this case abc.gnt. If the file is not located, a "program not found" error message is issued.

Additionally, you can specify the exact location of the program to be called, by qualifying the program call with a PC drive-letter or pathname. For example, to look in the directory c:\programs for the program abc.gnt, use the statement:

CALL "c:\programs\abc.gnt" USING ....

Note, however, that specifying the drive or pathname is not recommended, as unexpected results can occur where the referenced module exists in more than one file, or type of format, or if the application is ported to other environments.

Specifying the program extension in a call is not recommended.

Parent topic: Specifying the Program to Be Called


Calling Entry Points in Subprograms

You can execute called programs from a specified entry point, rather than the start of the Procedure Division. You define entry points in programs that you call, using the ENTRY statement. You can then execute a called program starting at an entry point by specifying the entry point in the CALL statement.

When a program containing entry points is loaded into the run-time system, all the entry points in the program are identified to the run-time system and are available to be called by any program that is loaded later.

However, the run-time system cannot locate entry points in programs that are not already loaded. For example, when you execute a CALL statement like this:

CALL "abc" USING ...

the run-time system first looks for a program or entry point called abc in all of the programs that have already been loaded. If the run-time system does not find one, it then looks for a file on disk called abc.ext where .ext is an executable file format. If abc is the name of an entry point in an unloaded program, the run-time system cannot find it.

Therefore, before calling an entry point, either the entry point must be preloaded, or the program containing the entry point must be loaded.

Parent topic: Specifying the Program to Be Called


Calling Programs According to How They Are Linked

When you call one COBOL program from another, you specify the name of the program to call either in a data-name or as a literal. For example:

CALL program-name USING ...
CALL "program-name" USING ...

where program-name (without quotation marks) is a data item that contains a valid program-name, and "program-name" (with quotation marks) is a literal string and is the actual name of a valid program.

Calling Dynamically Linked Programs

Use a CALL literal statement to call a dynamically linked program directly. If the program is not already in memory, the dynamic loader tries to find a dynamically loadable version of the program. If the program cannot be found, an RTS error message is issued.

Parent topic: Specifying the Program to Be Called


State of the Data when a Program is Called Again

When you call a program that has been called before and that has not been canceled, the data in the called program is in the same state as when it last exited. However, the data is reinitialized if:

  • The called program was canceled after it last ran
  • The called program has the INITIAL attribute in its PROGRAM-ID paragraph in the Identification Division.
Parent topic: Calling COBOL Programs
Related information
Specifying the Program to Be Called
Search Conventions Used for Calling Programs
Passing Parameters to a Called Program
Passing Return Codes Back to the Calling Program
Call Prototypes


Search Conventions Used for Calling Programs

Restriction: This information is not applicable to managed code.

When a program is called, the run-time system checks to see if the program has already been loaded or logically canceled. If the program is already available in memory, the run-time system passes control to it.

If the program is not available, the run-time system searches for it in the following sequence:
  1. Directories set in the COBPATH environment variable.
  2. If COBPATH is not set, current directory or PATH (.dll only).
  3. Application directory.
  4. Directory containing the calling program (unless the calling program is a .dll).

This search sequence only applies to called program files. It does not apply to other types of file, such as COBOL copybooks; use the COBCPY environment variable to locate copybooks.

At each stage of the search sequence, if the called program is named explicitly (name and extension specified), the specific file is searched for. If the called program is named implicitly, (base name only, no extension specified) the run-time system looks for executable files in the order:

  1. filename.so
  2. filename.gnt
  3. filename.int
  4. filename.lbr
  5. filename

If the search reaches the last directory without finding an executable file, the run-time system issues a "program not found" error message.

In the case of a library file (.lbr), the run-time system opens it, and searches it for an executable name filename.ext where .ext is one of the other executable file types listed above.

Note: If the dollar sign ($) is the first character of a program name, and that program is dynamically linked, or dynamically loadable, the first element of the program name is checked for filename mapping. The first element of the program name consists of all the characters before the first backslash character (\). For example, if the source program contains the statement:
 CALL "$MYLIB\A"
the subprogram A is loaded from the path as defined by the MYLIB environment variable when the program is run.
Parent topic: Calling COBOL Programs
Related information
Specifying the Program to Be Called
State of the Data when a Program is Called Again
Passing Parameters to a Called Program
Passing Return Codes Back to the Calling Program
Call Prototypes


Passing Parameters to a Called Program

You pass parameters to a program by specifying them in the USING phrase of the CALL statement. For example:

CALL "program-name" USING parameter-1, ..., parameter-n

Similarly the called program specifies the parameters in the USING phrase of its Procedure Division header or its ENTRY statement. The parameters need not have the same names in the called and calling programs, but they must be in the same order. Each parameter must also be declared with the same data type and size in both the called and calling programs.

You can pass parameters in the following formats. You can pass the:

  • Address of a data item, using the USING BY REFERENCE or USING BY CONTENT phrase. Any changes that the called program makes to a parameter passed BY REFERENCE are reflected in the calling program, whereas any changes made to a parameter passed BY CONTENT are not reflected in the called program.

    For example, the following statement passes the address of parameter-1:

    CALL "program-name" USING BY CONTENT parameter-1
  • Value of a data item, using the USING BY VALUE phrase. Any changes made to the parameter in the called program are not reflected in the calling program.

    Each binary computational item (COMP, BINARY, COMP-4, COMP-5, and COMP-X) is passed as a COMP-5 data item. That is, it appears in machine-order as a data item and not as a pointer to that data item. The size of the COMP-5 item depends on whether the SIZE qualifier of the USING BY VALUE phrase is used. If it is, the size of the COMP-5 data item is either four or eight bytes depending on the size of the original item. If the SIZE qualifier is not specified, the default size of 4 bytes is used.

    Floating point and decimal computational items (COMP-1, COMP-2, COMP-3 and PACKED DECIMAL) are copied intact to the stack without any conversion.

    For example, the following statement passes a two-byte value of 5:

    CALL "program-name" USING BY VALUE 5 SIZE 2.

The total size of all the parameters passed must not exceed 1020 bytes, where each BY REFERENCE and BY CONTENT parameter occupies 4 bytes.

Parent topic: Calling COBOL Programs
Related information
Specifying the Program to Be Called
State of the Data when a Program is Called Again
Search Conventions Used for Calling Programs
Passing Return Codes Back to the Calling Program
Call Prototypes


Passing Return Codes Back to the Calling Program

There are two methods for passing return codes back from the called program to the calling program. You can use the:

  • RETURN-CODE special register. The called program puts a value in the RETURN-CODE register before passing control back to the calling program with an EXIT PROGRAM or GOBACK statement. The RETURN-CODE register of the calling program is then automatically updated with the called program's return code and this register can be examined accordingly. The RETURN-CODE register is predefined as PIC S9(9) COMP; this can be changed using the RTNCODE-SIZE Compiler directive.
  • RETURNING or GIVING phrase. The preferred, and more flexible, way of handling return codes is to use the RETURNING or GIVING phrase of the CALL, EXIT PROGRAM, GOBACK, and STOP RUN statements. This phrase enables you to define the format of the return code yourself and so cope with whatever size of return code you require.
Parent topic: Calling COBOL Programs
Related information
Specifying the Program to Be Called
State of the Data when a Program is Called Again
Search Conventions Used for Calling Programs
Passing Parameters to a Called Program
Call Prototypes
Passing Return Codes Back to the Calling Program
Handling Return Codes in Mixed Language Applications
RTNCODE-SIZE
The PROCEDURE DIVISION Header
The CALL Statement
The ENTRY Statement
The EXIT Statement
The GOBACK Statement
The INVOKE Statement
The START Statement
The STOP Statement
The WAIT Statement
The ADD Statement
The DIVIDE Statement
The MERGE Statement
The MULTIPLY Statement
The SORT Statement
The SUBTRACT Statement
The USE Statement


Call Prototypes

  • About Call Prototypes
    Call prototypes are a relatively new feature of the COBOL language. Prototypes enable each CALL statement to be checked for correctness when the program is compiled.
  • The ANY Keyword
  • Relaxed Type-checking
  • Using Type Definitions
  • Using the Library Routine Type Definitions and Call Prototypes
Parent topic: Calling COBOL Programs
Related information
Specifying the Program to Be Called
State of the Data when a Program is Called Again
Search Conventions Used for Calling Programs
Passing Parameters to a Called Program
Passing Return Codes Back to the Calling Program


About Call Prototypes

Call prototypes are a relatively new feature of the COBOL language. Prototypes enable each CALL statement to be checked for correctness when the program is compiled.

Prototypes can help you write multi-program applications that function as you expect. For information on the CALL statement syntax see your Language Reference

When a COBOL program calls another program there is no validation of the type or the number of parameters provided in the CALL statement. If there is a mismatch between the parameter types provided on the CALL statement's USING clause and those of the called program's Linkage Section as referenced in the USING clause of the Procedure Division, then it is likely that either an application error or a run-time system error will occur.

For example, if you have the following program Mymain:

program-id. MYMAIN.
 working-storage section.
  01  .
     05 myhandle         pic x(4).
     05 othervalue       pic x(4) value "6x3b".
 procedure division.
     call 'MYROUTINE'   using myhandle
     display "Othervalue is " othervalue.

and the subprogram Myroutine:

program-id. MYROUTINE.
  linkage section.
  01  myhandle            usage pointer.
  procedure division using myhandle.
      set myhandle        to null
      exit program.

the program and its subprogram would work as you expected if compiled and run on a 32-bit system (where pointers are 4 bytes long), but would corrupt the value othervalue on a 64-bit system (where pointers are 8 bytes long).

You could be informed about this kind of problem when you compiled the programs, if the compiler had access to the data types expected by the called program Myroutine when it compiled the program Mymain. Call prototypes provide this information about called programs, and enable the compiler to check for semantic consistency between the parameters in both the calling program, and in the called subprogram.

A call prototype can be regarded as a cut-down version or model of the code of the called program. The prototype contains:

  • A full Linkage Section
  • A full PROCEDURE DIVISION header and/or ENTRY statements, and all associated USING parameters. These USING parameters should be defined in the Linkage Section.

No code is required in the Procedure Division.

A call prototype is identified by the use of the IS EXTERNAL clause in the Program-ID paragraph.

If you were to code the calling program above (Mymain) as follows:

  program-id. MYROUTINE is EXTERNAL.
  linkage section.
  01  myhandle            usage pointer.
  procedure division using myhandle.
  end program MYROUTINE.
  ******************************************************
  * Prototypes are usually defined in a copybook, but  *
  * here it is placed in-line                          *
  ******************************************************

  program-id. MYMAIN.
  working-storage section.
  01  .
      05 myhandle         pic x(4).
      05 othervalue       pic x(4) value "6x3b".
  procedure division.
      call 'MYROUTINE'   using myhandle
      display "Othervalue is " othervalue.
  end program MYMAIN.

when you compiled the program you would receive this warning message:

    14      call 'MYROUTINE'   using myhandle
*1059-E****************************************
**    Parameter is not consistent with that defined
      in prototype

Coding your programs in this way enables you to recognise programming errors without having to do run-time tests.

Ideally, all programs called from COBOL should be prototyped; however, this is not practical, as there is already a substantial body of COBOL code, and COBOL programmers are not used to type-checking programs. Even if the effort was expended to prototype all calls a program makes, it is likely that strict type-checking would cause a large number of Compiler errors on valid COBOL calls. For this reason, your COBOL system enables you to prototype called programs using a relaxed form of type-checking, and/or the keyword ANY with a USING statement.

For an extended example of using call prototypes, see the topic Call Prototypes in the section Examples in your Language Reference.

The COBOL system library routines are prototyped, enabling you to ensure that data items defined in your programs match those expected by the library routines. This is particularly useful if you are porting 32-bit applications to 64-bit systems, and want to ensure that data items are typed correctly.

Parent topic: Call Prototypes


The ANY Keyword

You can use the keyword ANY as a USING parameter. This enables any parameter to fill the corresponding parameter position on any CALL statement to the prototyped routine. For example, you can avoid producing the error shown in the example above by using this prototype:

program-id. MYROUTINE is EXTERNAL.
 procedure division using any.
 end program MYROUTINE.

For information on the ANY keyword, see the topic PROCEDURE DIVISION Header in the section Procedure Division in your Language Reference.

Parent topic: Call Prototypes
Related information
The PROCEDURE DIVISION Header
Call Prototypes
Relaxed Type-checking
Using Type Definitions
Using the Library Routine Type Definitions and Call Prototypes


Relaxed Type-checking

By default, the Compiler performs relaxed type-checking on BY VALUE binary data items. That is, even if binary data items have been defined with different sizes in the calling and called programs, the programs will compile with errors. If you specified a CALL statement that had a data item defined as PIC X(2) COMP in its USING list, that data item can correspond to a PIC X(n) COMP data item in a call prototype, where n on a 32-bit system can be from 1 through 4, and on a 64-bit system can be 1 through 8.

For example, the following program will compile successfully:

program-id. MYROUTINE is EXTERNAL.
 linkage section.
 01  callee-value             pic x(2) comp-5.
 procedure division using by value callee-value.
 end program MYROUTINE.

 program-id. MYMAIN.
 working-storage section.
 01  .
     05 caller-value          pic x(4) value 123.
 procedure division.
     call 'MYROUTINE' using by value caller-value
 end program MYMAIN.

In this example, if the actual value of caller-value was too big to fit a data item defined as PIC X(2) COMP-5, binary truncation would occur. Such truncations might cause problems with the logic of your program, so you might want to specify that type-checking is more strict so that you can identify such potential problems. You can do this by setting the Compiler directive PROTOTYPE"STRICT". If you were to set PROTOTYPE"STRICT" when you compiled the above program, the Compiler would produce a message warning you of the type mismatch.

Parent topic: Call Prototypes


Using Type Definitions

When you use call prototypes in your programs, an error occurs if there is a mismatch between data-types. To avoid this error, and to code the CALL statement and USING parameters correctly, the data description entry of the USING parameter in the call prototype must be duplicated in the program calling that prototype. If you were to do this manually, such duplication could lead to code maintenance problems, and perhaps lead to inconsistencies when you were creating programs.

To enable easy duplication of data description entries, you can create COBOL type definitions in the Linkage Section of the call prototype, which you can then reference in the calling and called programs. To create a COBOL type definition, you code a data description that includes the TYPEDEF clause. The name you give the data item then becomes a type definition. You can then code a data item with a USAGE clause that references the type definition. For example:

 01  callee-value-t           pic x(2) comp-5 is typedef.
 01  callee-value             usage callee-value-t.

In this example the type definition is callee-value-t.

Here is the complete call prototype and a program that calls a subroutine based on this prototype:

program-id. MYROUTINE is EXTERNAL.
 linkage section.
 01  callee-value-t           pic x(2) comp-5 is typedef.
 01  callee-value             usage callee-value-t.
 procedure division using callee-value.
 end program MYROUTINE.

 program-id. MYMAIN.
 working-storage section.
 01  .
     05 caller-value          usage callee-value-t.
 procedure division.
     call 'MYROUTINE' using caller-value
 end program MYMAIN.

You can use the TYPEDEF clause not only on elementary data descriptions, but also on group items and even on entire record structures. For example:

program-id. MYROUTINE is EXTERNAL.
 linkage section.
 01  callee-value-t is typedef.
     05  callee-value-item-1  pic x(2) comp-5.
     05  callee-value-item-2  pic x(4).
 01  callee-value             usage callee-value-t.

 procedure division using callee-value.
 end program MYROUTINE.

 program-id. MYMAIN.
 working-storage section.
 01  .
     05 caller-value          usage callee-value-t.
 procedure division.
     move 123      to callee-value-item-1 of caller-value
     move 'abcdef' to callee-value-item-2 of caller-value
     call 'MYROUTINE' using caller-value
 end program MYMAIN.

All data items defined as type definitions in a call prototype are available to any programs using that prototype.

For detailed information on the TYPEDEF clause, see the topic The TYPEDEF Clause in the section Data Division - File and Data Description in your Language Reference.

Parent topic: Call Prototypes


Using the Library Routine Type Definitions and Call Prototypes

Two copybooks are supplied with this system; one contains data items used by the library routines specified as type definitions, or TYPEDEFs, while the other contains call prototypes for the library routines. These can be used in your COBOL programs to enable the Compiler to validate all calls to these routines.

We provide the file cbltypes.cpy, which contains all types required by the system library routines. In order to avoid conflict with data-names contained within your program, all TYPEDEF names include the prefix CBLT-. Where the types are not elementary items, any subordinate elements have the prefix CBLTE-.

We also provide the file cblproto.cpy, which contains all prototypes of the system library routines. In some cases, these prototypes have parameters declared as ANY; this is usually when variable length data is required as input.

In the descriptions of the parameters for the library routines, references to the system-defined USAGE types have the prefix CBLT-, while subordinate items have the prefix CBLTE-. If you declare variables using the new USAGE types, you do not declare the subordinate items; you can, however, use the subordinate items anywhere that variable usage is allowed. If you declare more than one variable of the same type which contains subordinate items, then you must use qualification in order to tell the compiler which variable you intend to reference, as each group variable will have subordinate items of the same name.

In your programs, you need only specify the copybook cblproto.cpy; you must specify it before the Identification Division of your program. You do not need to specify the copybook cbltypes.cpy, as this is included in cblproto.cpy.

For an extended example of using call prototypes, see Call Prototypes.

If, for whatever reason, you decide not to use the new USAGE types defined in cbltypes.cpy, you must declare a group item and all the listed subordinate variables explicitly; in this case you can give the subordinate variables any name you want.

Some third party database preprocessors (such as Oracle Pro*COBOL) do not allow the use of nested programs, and so you cannot use the prototypes defined in cblproto.cpy if you are also using such a preprocessor; instead, you must explicitly set the data items used with the library routines.

Note:

The call prototypes apply only to call-by-name routines (those of the form CBL_name_name), not to the call-by-number routines (those of the form X"NN").

Below is an example of the use of these prototypes in a program. If the file mymain.cbl exists the program displays its size:

 copy "cblproto.cpy".

 program-id. MYMAIN.
 working-storage section.
 01  .
     05  file-details    cblt-fileexist-buf.
 procedure division.
     call 'CBL_CHECK_FILE_EXIST' using 'mymain.cbl '
                                       file-details
     if  return-code not = 0
       display 'File mymain.cbl does not exist (or error)'
     else
       display 'File mymain.cbl size is '
               cblte-fe-filesize of file-details
     end-if
 end program MYMAIN.
Parent topic: Call Prototypes
Related concepts
64-bit Native COBOL Programming
Related information
About Call Prototypes
Call Prototypes
The ANY Keyword
Relaxed Type-checking
Using Type Definitions
The CALL Statement
Data Description Entry Skeleton
The ANY LENGTH Clause
The OCCURS Clause
The PROCEDURE DIVISION Header
The ENTRY Statement
The EVALUATE Statement
The TYPEDEF Clause


Internationalization Support

  • National Locale Support
  • Unicode Support
Parent topic: COBOL Programming


National Locale Support

Restriction: National Locale Support is only supported for native COBOL code.

The National Locale Support (NLS) facility provides an automatic means of adapting your program to the character code set, collating sequence, and editing symbols associated with a particular country, without the need for your application to know what these are in advance. This facility is also useful in English-speaking countries for handling codepages, collating upper- and lower-case letters correctly and selecting the appropriate currency symbol.

If full-screen ACCEPTs are to be used, you must set the range of data keys to be accepted in the adisctrl database. Your COBOL development system attempts to provide the appropriate national language tables for the language, country and character set selected by the user.

The NLS facility provides you with the means to access the following features which are associated with particular countries and codepages:

  • Class condition tests (ALPHABETIC, ALPHABETIC-UPPER, ALPHABETIC-LOWER, NUMERIC and user-defined CLASS conditions), appropriate to codepages
  • Collating sequences, appropriate to codepages (for example, the correct handling of accented characters)
  • Linguistic collating sequences applied to sort or merge files

NLS can also be used to create message files for your applications. These message files can contain error messages, but can also contain any other messages that need to be displayed by your application.

If you want to sort index files according to the local collating sequence rather than the ASCII collating sequence, you must specify the IXNLSKEY directive.

  • Compiling Programs with NLS
  • Setting Up the National Locale Environment
  • Using the LANG Environment Variable
  • Running Your NLS Program
  • NLS Initialization
  • NLS Operations
  • Message Files
Parent topic: Internationalization Support
Related information
Unicode Support
Message Files


Compiling Programs with NLS

Restriction: National Locale Support is only supported for native COBOL code.

To use the NLS facility in your program, you must compile it with the NLS Compiler directive set. By default, the NLS Compiler directive is not set.

If you do set the NLS directive then, before checking the syntax of a program, you must ensure that it does not contain any of the following syntax:

  • In the Object-Computer paragraph, the phrase:

    PROGRAM COLLATING SEQUENCE IS alphabet-name

  • In the Special-Names paragraph, the phrases:
    • alphabet-name IS
    • STANDARD-1
    • NATIVE
    • literal-1 THRU literal-2, and so on
    • CURRENCY SIGN IS literal
    • DECIMAL-POINT IS COMMA
  • In the Procedure Division, the phrase:

    COLLATING SEQUENCE IS alphabet-name in MERGE or SORT statements

If your program contains any of the above syntax, and you want to use the NLS facility, you must either remove the syntax from your program, or mark it as a comment line. If you set the NLS directive and attempt to compile a program which contains any of the above syntax, compilation fails with the error:

136 Illegal use of phrase for National Language operation

You can compile any program in a COBOL application with the NLS directive set, providing it does not contain any of the above syntax. Thus some programs within an application might use NLS facilities, while others might not.

For more information, read Mixing programs with and without NLS.

Parent topic: National Locale Support
Related information
Setting Up the National Locale Environment
Using the LANG Environment Variable
Running Your NLS Program
NLS Initialization
NLS Operations
Message Files


Setting Up the National Locale Environment

Restriction: National Locale Support is only supported for native COBOL code.

Before you run a program with the facility, you must define your locale. A locale is the combination of language, territory and codepage. The locale used by the run-time system is initially set to the value of the regional settings for the operating system.

Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Using the LANG Environment Variable
Running Your NLS Program
NLS Initialization
NLS Operations
Message Files


Using the LANG Environment Variable

Restriction: National Locale Support is only supported for native COBOL code.

You define a locale using the LANG environment variable. LANG is set using the operating system command SET:

set LANG=language

Parameter

language The language environment in which you wish to run your program. This determines which message catalog is open so that if an error occurs, the error message is output in the selected language. language can take the following values:
  • en_US = American English
  • en_GB = English
  • jp_JP = Japanese (EUC encoding)
  • jp_JP.sjis = Japanese (Shift-JIS encoding)
  • jp_JP.utf8 = Japanese (UTF8 encoding)

The following example illustrates how to specify a language of English and use the operating system values for the territory and codepage:

set LANG=en_GB
export LANG
Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Setting Up the National Locale Environment
Running Your NLS Program
NLS Initialization
NLS Operations
Message Files


Running Your NLS Program

Restriction: National Locale Support is only supported for native COBOL code.

You run programs containing in the same way as you run programs without it. When the program runs:

  • The run-time system initializes the NLS. The initializes the NLS facility when it encounters the first program within the application which was compiled with the NLS directive set. The operating system's regional settings are used to determine which language environment to set up for this program. However, you can use the LANG environment variable to override the current settings.
  • The NLS facility performs various operations in accordance with the rules of the language specified in the LANG environment variable.
Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Setting Up the National Locale Environment
Using the LANG Environment Variable
NLS Initialization
NLS Operations
Message Files


NLS Initialization

Restriction: National Locale Support is only supported for native COBOL code.

The run-time system initializes the NLS facility only once during an application's run: when it encounters the first program within the application which was compiled with the NLS directive set. It uses the operating system's regional settings to determine which language environment to set up for this program; if the LANG environment variable is set, that is used instead.

The run-time system uses the same language environment for any subsequent programs within the application which are compiled to use NLS.

If an error occurs during this initialization process, for example the language specified in the LANG environment variable is not supported, the run-time system reports the error:

40  National Language initialization not set up correctly

and terminates its run.

You can also receive this error if the LANG environment variable was set up by a third party product in a format different from that used by this COBOL system. If this occurs, use the COBLANG environment variable instead of the LANG environment variable.

If the run-time system cannot find the NLS run-time support modules, it issues the message:

46  NLS support module not found

and terminates its run.

Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Setting Up the National Locale Environment
Using the LANG Environment Variable
Running Your NLS Program
NLS Operations
Message Files


NLS Operations

Restriction: National Locale Support is only supported for native COBOL code.

When you run a program which has been compiled with the NLS directive set, certain operations are carried out in accordance with the rules of the language specified in the LANG environment variable.

Other language-dependent features, such as the symbols used to denote the decimal points and the currency character, also appear in the format of the specified language. However, in languages that define the currency sign as trailing, this has no effect and the usual COBOL rules are observed.

Certain NLS definitions have characters other than the ASCII characters 0-9 defined as numerics. Such characters cannot be ACCEPTed into numeric picture strings, nor can they be used in numeric operations. Note that in all NLS operations in the COBOL environment, a numeric item must be formed only from the ASCII digits 0-9, with or without the ASCII operational signs "+" or "-". There is no means of automatically converting the NLS representation to the ASCII equivalent.

It is possible to enter European modifying characters into numeric ACCEPT fields. These are accepted as zero.

Note that the values assigned to figurative constants, for example LOW-VALUES, are not changed by using NLS features.

You can also use the Adis Flip Case Control key when using NLS characters. However, if you attempt to convert a European character to upper case using this key, the character will be replaced by spaces if it has no upper case equivalent.

  • String Comparisons
  • Class Condition Tests
  • SORT and MERGE Key Comparisons
  • Case Conversion
  • Collating Sequence Operations
  • Editing and De-editing Moves
  • Intrinsic Functions Numval and Numval-c
  • Using NLS Library Routines in Your Programs
  • Mixing Programs With and Without NLS
Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Setting Up the National Locale Environment
Using the LANG Environment Variable
Running Your NLS Program
NLS Initialization
Message Files


String Comparisons

Restriction: National Locale Support is only supported for native COBOL code.

For programs which have been compiled with the NLS directive set, the run-time system invokes the CBL_NLS_COMPARE routine when it needs to carry out string comparisons. This routine is also called for alphanumeric comparisons if the program uses the intrinsic functions Max, Min, Ord-max or Ord-min on alphanumeric operands.

During a MOVE operation of one alphanumeric item to another which is longer, padding with spaces occurs. Similar padding is also implied before the comparison of two such items. In both cases, an ASCII space is assumed.

Parent topic: NLS Operations
Related information
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Class Condition Tests

Restriction: National Locale Support is only supported for native COBOL code.

For programs which have been compiled with the NLS directive set, the run-time system invokes locale-specific tests when it needs to carry out class condition tests. These tests determine if a string of information is in ALPHABETIC, ALPHABETIC-UPPER, ALPHABETIC-LOWER or NUMERIC format. The numeric test always tests that all characters are in the range of ASCII 0-9.

Parent topic: NLS Operations
Related information
String Comparisons
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


SORT and MERGE Key Comparisons

Restriction: National Locale Support is only supported for native COBOL code.

If a program compiled with the NLS directive set performs a SORT or MERGE operation, it automatically uses NLS key comparisons. The run-time system invokes the CBL_NLS_COMPARE routine for all key comparisons used in SORT or MERGE operations.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Case Conversion

Restriction: National Locale Support is only supported for native COBOL code.

If a program compiled with the NLS directive set performs a case conversion, either by using the intrinsic functions Upper-case and Lower-case or by calling the library routines CBL_TOUPPER and CBL_TOLOWER, the run-time system invokes a routine to fold national characters correctly.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Collating Sequence Operations

Restriction: National Locale Support is only supported for native COBOL code.

When a program compiled with the NLS directive set is initialized, a collating sequence appropriate to the locale is set up. If the program performs a collating sequence operation by using the intrinsic functions Char and Ord, then this special collating sequence is used.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Editing and De-editing Moves

Restriction: National Locale Support is only supported for native COBOL code.

If a program compiled with the NLS directive set performs an editing or de-editing move, then the decimal point and thousands separator appropriate to the locale are used. Also, the currency symbol used is the first character of the currency symbol of the locale territory.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Intrinsic Functions Numval and Numval-c

Restriction: National Locale Support is only supported for native COBOL code.

If a program compiled with the NLS directive set attempts to convert a number or a monetary value in a display item to a numeric value by using the intrinsic functions Numval or Numval-c, then the run-time system uses the decimal point and thousands separator appropriate to the locale. Also, if no second argument is supplied for Numval-c, then the currency symbol used is the currency symbol of the locale territory.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Using NLS Library Routines in Your Programs
Mixing Programs With and Without NLS


Using NLS Library Routines in Your Programs

Restriction: National Locale Support is only supported for native COBOL code.

There are various library routines you can use in a program that uses NLS.

  • CBL_NLS_INFO
    Gets/sets national language information.
  • CBL_NLS_OPEN_MSG_FILE
    Open a National Locale Support (NLS) message file.
  • CBL_NLS_READ_MSG
    Reads a message from a National Locale Support (NLS) message file.
  • CBL_NLS_CLOSE_MSG_FILE
    Closes a National Locale Support (NLS) message file.
  • CBL_NLS_COMPARE
    Compares two strings.
Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Mixing Programs With and Without NLS
Message Files


Mixing Programs With and Without NLS

Restriction: National Locale Support is only supported for native COBOL code.

Programs in your application can be compiled with or without the NLS directive set. A program which is compiled without the NLS directive set can CALL programs which were compiled without this directive set and programs which were compiled with it set. The reverse is equally true; that is, a program compiled with the NLS directive set can CALL both programs compiled with this directive, and those compiled without it.

A program compiled with the NLS directive set has no particular language or locale associated with it. The locale it uses is the application locale, which is initialized along with the NLS facility when the first program that uses NLS in the application is called.

The library routines for NLS can be called from any program which has been compiled with the NLS directive set.

Programs in the application which were compiled without the NLS directive set can also call these routines, but only after the National Locale Support module has been loaded and initialized by calling a program which has been compiled with the NLS directive set.

You can pass parameters from a program with the NLS facility to a program without it. However, you must note that parameters that are dependent on the language environment in which they are created retain their format regardless of the language environment in which they are used. If you attempt to use a parameter that was created in a program with the NLS facility in a program without the NLS facility, the result might not be as you would expect. We recommend that you do not attempt to pass such parameters to programs other than those which have the same language environment.

Parent topic: NLS Operations
Related information
String Comparisons
Class Condition Tests
SORT and MERGE Key Comparisons
Case Conversion
Collating Sequence Operations
Editing and De-editing Moves
Intrinsic Functions Numval and Numval-c
Using NLS Library Routines in Your Programs


Message Files

Restriction: National Locale Support is only supported for native COBOL code.

National Locale Support (NLS) support can include message files, where language-specific messages can be output using the appropriate codeset for the environment that the application is running in. You write each message file as an ASCII file with the file extension .nls, compile it into a language file (which has the file extension .lng), and then deploy it with your application.

To make messages available in more than one language, create one message file per language, and compile them to separate .lng files.

Within your application, you can open, read and close message files using the CBL_NLS_* library routines.

  • Format of a Message File
  • Compiling and Deploying a Message File
Parent topic: National Locale Support
Related information
Compiling Programs with NLS
Setting Up the National Locale Environment
Using the LANG Environment Variable
Running Your NLS Program
NLS Initialization
NLS Operations
Using NLS Library Routines in Your Programs


Format of a Message File

Restriction: National Locale Support is only supported for native COBOL code.

When you write the message file, start it with the statements:

$quote x
$set 1

where x is the character you wish to use as a quote character.

Then, write each message in the format:

$ nnnnn  "your message here"

where the double-quote character (") is assumed to be the quote character set in the $quote statement above. You can change quote statements at any point in the message file; each change applies to all the messages which follow it up until the next $quote statement.

  • Example Error Message File
Parent topic: Message Files
Related information
Compiling and Deploying a Message File


Example Error Message File

Restriction: National Locale Support is only supported for native COBOL code.

This example shows an error message file. You can include comments by starting a line with the dollar sign ($) followed by a space.

$quote "
$
$set 1
1    "Invalid key type"
2    "Failed to open file for dictionary"
3    "Using a key of different size"
4    "Record exceeds maximum allowed length"
5    "Error reading control record"
6    "Indexed file has wrong key structure"
7    "Key not found in file"
8    "Attempt to write a record which has been deleted"
 ...
$ *****************************************************************
$ Copyright (c) 1981,1995 Micro Focus Ltd
$
$ Last modified on 95/08/01
$
$ ****************************************************************
Parent topic: Format of a Message File


Compiling and Deploying a Message File

Restriction: National Locale Support is only supported for native COBOL code.

In order to use a message file, you need to translate the .nls file into a .lng file. You do this by running the conversion program msgc.

Run the conversion from a shell prompt using the following syntax:

cobrun msgc /l filename

where filename is the name of the .nls file you created.

This validates your .nls file, and generates a .lng file from it.

You must then place the .lng file in a sub-directory to the directory containing the application's main executable in order for the run time system to pick it up when the application runs. The naming of the directory must be as follows:

lang\<locale-name>

lang/<locale-name>

where <locale-name> is one of:

locale-name | Language
en_US | American English
en_GB | English
ja_JP | Japanese
fr_CA | Canadian French
da_DK | Danish
nl_NL | Dutch
fi_FI | Finnish
fr_FR | French
de_DE | German
it_IT | Italian
nb-NO | Norwegian
pt_PT | Portuguese
es_ES | Spanish
sv_SE | Swedish
cs_CZ | Czech
kr_KO | Korean
zh_CN | Chinese
default | used for all other locales, or if required locale directory does not exist

For example, if you generate a msg-file.lng intended for Spanish, it should be placed in the /lang/es_ES sub-directory of the directory containing the application's main executable.

Parent topic: Message Files
Related information
Format of a Message File


Unicode Support

Unicode is the general name given to the collection of character encoding schemes that can be used to represent most national languages. The main encodings defined under Unicode are UTF-8, UTF-16 and UTF-32 (where UTF stands for Universal Transformation Format). The COBOL development system uses UTF-16 as its representation for national characters. This means that each national character takes up 2 bytes of memory, and there are 65536 possible character combinations available.

COBOL applications are increasingly moving towards the use of Unicode to manage application data from multiple national languages in a single application. The COBOL language support for Unicode is in compliance with the ISO2002 COBOL standard. National data can be stored in standard COBOL files or in an SQL database. In addition, the Unicode support can be used to pass national character strings directly between COBOL and Java. In DBCS environments, it can also be used side-by-side with the existing DBCS support, making it possible to incrementally transition existing DBCS applications over to Unicode as needed.

  • UTF-16 Byte Ordering
  • National Literals
  • National Hexadecimal Literals
  • National Data Items
Parent topic: Internationalization Support
Related information
National Locale Support
National Literals
UTF-16 Byte Ordering
National Data Items
National Hexadecimal Literals


UTF-16 Byte Ordering

A UTF-16 character can be stored in one of two byte orders. The computer’s default byte order is normally used. For example, on Intel-based machines, the least significant byte of the character pair is stored at the byte with the lowest memory address (lo-hi byte ordering). On most other machines the most significant byte is stored first (hi-lo byte ordering). When you have a COBOL program containing Unicode characters, and that program must be accessed by machines that use either byte-order, you must change the byte order on a lo-hi machine to force the data to be stored in hi-lo order. You achieve this using the UNICODE directive. This directive enables you to specify NATIVE (whatever the machine defaults to) or PORTABLE (always hi-lo) byte ordering. Use the following syntax:

unicode({native | portable})

For example, the character “A” is represented by (0x00, 0x41) in UTF-16. On an Intel machine this is stored as:

0x41 0x00

However, if you specify the UNICODE(PORTABLE) directive, it is stored as:

0x00 0x41
Parent topic: Unicode Support
Related information
Overview - Unicode Support
National Literals
National Data Items
National Hexadecimal Literals


National Literals

Specifiy a national literal using the following notation:

N"string"

If the NSYMBOL(DBCS) directive is enabled, then the literal is a DBCS literal. If the NSYMBOL(NATIONAL) directive is enabled, then the literal is a national literal. In this case, the string is converted to Unicode (UTF-16) at runtime according to the code page of the current locale.

See the section National Literals in the chapter Concepts of the COBOL Language in your Language Reference.

Parent topic: Unicode Support


National Hexadecimal Literals

National hexadecimal literals specify the Unicode (UTF-16) characters directly in hexadecimal, and enable the portability of code. Use the following format:

NX"string"

Each character in the string consists of two bytes and the most significant byte of the pair is specified first. For example, in UTF-16 the character "A" is represented by the byte pair (0x00, 0x41) and the character "B" is represented by (0x00, 0x42). The string "AB" could therefore be specified by the national hexadecimal literal:

NX"00410042"

See the section National Literals in the chapter Concepts of the COBOL Language in your Language Reference.

Parent topic: Unicode Support


National Data Items

Define COBOL data items that hold a Unicode string as USAGE NATIONAL. These must have a picture clause that consists of one or more N symbols. If the Usage clause is omitted then the usage is implied from the setting of the NSYMBOL directive.

When the NATIONAL"2" Compiler directive is in effect, numeric, edited, and external floating point items can also contain the USAGE NATIONAL clause. Any signed numeric data item must be described with the SIGN IS SEPARATE clause.

Examples

With NATIONAL"1" in effect:

01 N1 PIC n(20) USAGE NATIONAL.

With NATIONAL"2" in effect:

01 N1 PIC n(20) USAGE NATIONAL.
01 N2 PIC 9(4) USAGE NATIONAL.
01 N3 PIC +9.9 NATIONAL BLANK WHEN ZERO.
01 N4 PIC N/N NATIONAL.
01 N5 PIC +9.99E+99 NATIONAL.
01 N6 PIC s9(4) SIGN IS TRAILING SEPARATE USAGE NATIONAL.
Parent topic: Unicode Support
Related information
Overview - Unicode Support
Overview - National Literals
UTF-16 Byte Ordering
National Hexadecimal Literals
NATIONAL
NSYMBOL


Preparing Applications for Enterprise Server

The following topics explain the implications of exposing COBOL applications as services to be run under Enterprise Server:

  • The Application Container
  • Resource Management
  • Restrictions on the COBOL application
Parent topic: COBOL Programming


The Application Container

A COBOL application that is deployed as an enterprise server service is always run inside one of the server's service execution processes. The part of the service execution process that runs the application is a tightly managed COBOL run-time environment, or application container. Enterprise Server maintains a consistent state for this container between application invocations to ensure consistent execution behavior.

When a client request arrives, the application program to be invoked is loaded, and then the container sets up its execution environment prior to its invocation. This information includes environment variables, tunables and switches that the application requires. If no run-time configuration information was specified for the service at deployment time, a default environment will be set up for the application.

Client requests can be short-running or long-running. 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. Long-running client requests are either requests where the same client makes repeated requests of services and needs data to be preserved between invocations of the service, or where a client makes a request that is part of a transaction. So if the client is a stateful Java bean running in a J2EE server such as WebSphere, the service will run for as long as the bean runs.

  • Short-running Requests
  • Long-running Requests
Parent topic: Preparing Applications for Enterprise Server


Short-running Requests

If the application was invoked by a short-running request, when it terminates, whether normally or due to a run-time system error occurring, the application container returns itself to its initial state before a response is generated and sent back to the client.

Normally, having sent a response back to the client, the service execution process waits for the enterprise server to notify it to process another request. However, there are some circumstances where the service execution process is terminated following the execution of an application:

  • The integrity of the container has been compromised in some way (for example, a run-time system error, such as a 114 error, occurred or an executable file loaded by the application could not be unloaded; etc.).
  • You unchecked Reuse container after application termination on the Deployment Characteristics tab of the Enterprise Server Run-time Configuration dialog box before you deployed the service. You should uncheck this if the application is likely to leave the application container in a state that will compromise its ability to be safely reused, for example, if your application is mixed-language and the non-COBOL modules do not clean up resources before the application terminates.
  • You unchecked Reuse container after non-fatal run-time system error on the Deployment Characteristics tab of the Enterprise Server Run-time Configuration dialog box before you deployed the service, and the application has terminated due to a non-fatal run-time system error (for example. 173 error "Program not found"). You should uncheck this if you decide that any run-time error that occurs while running the application indicates a major failure that compromises the integrity of the container.

When such a circumstance occurs, the enterprise server will start a new service execution process to replace the one just terminated.

Parent topic: The Application Container


Long-running Requests

A long-running request starts when either a transaction begins, or when a request is made to invoke a stateful service. When in this mode, the connection between the client and the server is maintained until either the transaction ends, or the client indicates that stateful processing is no longer required. However, a transaction start request may occur when a long-running request is already in effect (for example, a request for a stateful request has been previously made), or when the first service request within a transaction is for a stateful service. In this situation, the end of transaction will not terminate the long-running request as the server is still running in stateful mode.

Once a long-running request has been initiated, the service execution process is only able to process requests made by this specific client. To maintain responsiveness to other clients, the enterprise server starts a new service execution process each time an existing service execution process starts processing a stateful request.

When stateful processing is in effect, the application container does not return to its initial state following successful execution of a service request. Instead it maintains the client state of the container across multiple service requests until it receives notification from the client indicating that stateful processing is no longer required. (For example, it does not cancel user programs; does not return environment variables, tunables, or switches back to their initial state; does not unload user libraries etc.) When it receives notification indicating that stateful processing is no longer required, the application container returns itself to its initial state.

Stateful mode is implicitly exited if a service request causes a run-time system error to occur.

Enterprise Server manages its service execution processes to maintain the configured number of processes. This may mean that the enterprise server terminates the service execution process when a stateful client request completes.

Parent topic: The Application Container


Resource Management

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.

You specify whether an application you are deploying is to be application-managed or container-managed

  • Application-managed Services
  • Container-managed Services
Parent topic: Preparing Applications for Enterprise Server


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.

A service in which the application accesses files in a non-transactional way (that is, it does not includes COMMITs and ROLLBACKs), should be application managed.

A transactional application-managed service must contain all the transactional logic it needs, that is, it must complete with all resources either committed or rolled back.

Application-managed services are executed in a similar way to applications in a conventional execution environment. One of the main differences is that the process is not terminated at the end of execution of the service.

Parent topic: Resource Management


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 resource managers in Enterprise Server. You can only define resource managers that are XA-compliant.

The application container decides whether to commit or roll back resources using information that you provide on the Deployment Characteristics tab of the Enterprise Server Run-time Configuration dialog. To reach this, Enable enterprise server run-time environment, and click Configure enterprise server run-time environment. You can specify whether or not the application uses the value of its return code to indicate success or failure, and what the maximum success value is. If you specify that the application does not use the value of its return code to indicate success or failure, the application container considers all application invocations to be successful.

Parent topic: Resource Management
Related information
Resource Managers


Restrictions on the COBOL application

There are certain restrictions on the COBOL application that mostly arise from the program being used as a self-contained component being called by remote users.

Before deciding to expose a COBOL application as a service, you must determine whether the application is suitable. Examine all the functions you intend to expose, and make sure they conform to the requirements in this section. You may need to do some restructuring.

  • User Interaction for COBOL Program Services
  • Run-time Errors and Completion
  • Multithreading
  • Preserving State
  • File Handling
  • Releasing Resources
  • Object-oriented COBOL
Parent topic: Preparing Applications for Enterprise Server


User Interaction for COBOL Program Services

A COBOL program service can receive and return data in two ways:
  • Using input and output parameters defined as data items in the Linkage Section.
  • Using ACCEPT and DISPLAY statements or the RETURN-CODE special register. Two forms of the ACCEPT statement are supported: ANSI ACCEPT and ACCEPT FROM COMMAND-LINE.

When the application runs as a service in an enterprise server, any ANSI ACCEPT or ACCEPT FROM COMMAND-LINE statements that are not mapped to interface fields return spaces, and any ANSI DISPLAY statements or RETURN-CODE values that are not mapped to interface fields are ignored. Any screen or keyboard operation other than an ANSI ACCEPT, ACCEPT FROM COMMAND-LINE or ANSI DISPLAY will generate the run-time system error 197 and the application will be terminated.

A service can also issue ACCEPT FROM CONSOLE and DISPLAY UPON CONSOLE statements. When execution reaches a DISPLAY UPON CONSOLE statement, the display text is displayed in the enterprise server 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.

Parent topic: Restrictions on the COBOL application


Run-time Errors and Completion

A service must be well-behaved, that is, it must run to completion, return its results to the client, and exit so that control returns to the server.

Therefore, the COBOL application must handle all errors by returning an error indication in the output parameter, never by stopping. You should make sure that all error conditions are detected, through the use of the FILE STATUS clause, declarative procedures, etc., so that the program does not crash or otherwise abort.

Similarly, the COBOL application should not contain a STOP RUN statement. When encountered during service execution, the STOP RUN statement is effectively a quit statement, making the program exit at once.

Parent topic: Restrictions on the COBOL application


Multithreading

Multi-threaded applications are not supported, since service execution processes in the enterprise server can only run applications that use the single-threaded run-time system.

Parent topic: Restrictions on the COBOL application


Preserving State

If your service will be invoked by short-running client requests, the application will run in an enterprise server with no memory of previous invocations by the same client. If you need to preserve state or data from one call to the next, you need to program this for yourself, for example, by saving data in a work file.

Parent topic: Restrictions on the COBOL application


File Handling

If the application uses the API of the Micro Focus File Handler for COBOL file operations, it must ensure that all files that it has opened using this interface are closed on its termination. Failure to do so will leave the files open for subsequent service requests and may lead to service execution failure.

Parent topic: Restrictions on the COBOL application


Releasing Resources

The application must release any resources it uses that are not managed by the COBOL run-time system before it terminates. Failure to do so will potentially result in undefined execution behavior for subsequent services invoked by the container. If it is not possible to release such resources (for example, third-party modules are being used by the application that acquire resources), you must indicate this when you deploy the service. This ensures that the service execution process in the enterprise server will be terminated once the application has terminated.

Parent topic: Restrictions on the COBOL application


Object-oriented COBOL

When deploying a COBOL service program that uses Object-oriented COBOL to an enterprise server, you must specify that any container used to run the service is not reused. You do this by unchecking Reuse container after application termination and Reuse container after non-fatal run-time system error on the Deployment Characteristics tab of the Enterprise Server Run-time Configuration dialog box when you deploy the service.

Parent topic: Restrictions on the COBOL application


Web Services Support for Native COBOL

Using Visual COBOL, you can choose from several methods provided to expose COBOL as Web services, and in some cases, deploy and run your Web services on Enterprise Server. In addition, you can also generate client applications to access your Web services.

COBOL JVM
COBOL deployed under a Java Virtual Machine (JVM) can take advantage of Java SDKs and frameworks such as the Web Tooling Platform (WTP). This enables Web services integration with Tomcat and other application servers.

Because Eclipse tools are configured to generate Java Web services and not COBOL Web services, you must use Java on the front end. A Java class receives the request and then calls COBOL to perform the back-end processing.

COBOL JVM supports all Web service protocols provided by the Java Web services framework, including REST, but does not support the generation of COBOL clients from WSDL or JSON.

Calling COBOL from Another Language
You can call COBOL using any of a wide variety of other programming languages. Some of these languages have direct Web services support through tooling and Application Server deployment.
CAUTION:
When developing a Web service using this method, be sure to include a failsafe to address the scenario in which the COBOL program crashes or issues a STOP RUN when executed in the same process of an Application Server. Failure to address this scenario introduces the risk of bringing down the Application Server.
Parent topic: COBOL Programming


Mixed Language Programming

This section covers parameters, return codes and call conventions for mixed language development with native COBOL.

Applications can contain programs written in both COBOL and other languages, such as C. COBOL programs call non-COBOL programs using the standard COBOL CALL ... USING statement.

Although you pass parameters to non-COBOL programs in broadly the same way as to COBOL programs, the interfaces to programs in different languages differ from each other and they need to correspond.

  • Ordering Parameters to Pass to Non-COBOL Programs
    The order in which the parameters are passed, since the calling program might not pass parameters in the order that the called program expects them.
  • Removing Parameters from the Stack
    Defining whether the called program removes the parameters from the stack before it returns to the calling program, or whether the calling program does it after receiving control back.
  • Storage Representation of Parameters
    The storage of parameters in mixed language applications, since different systems store data either with the most significant byte first or with it last.
  • Aligning Parameters on Word and Double Word Boundaries
    Aligning numeric parameters on word and double-word boundaries to match the alignment in the non-COBOL program.
  • Handling Return Codes in Mixed Language Applications
    COBOL can pass and receive return codes from other programs.
  • Call Conventions for Interfacing with Mixed Languages
    The conventions for passing parameters, and other details of the interface between the two programs.
  • Building a Mixed Language Application
    Compiling and linking a mixed language application, and preserving the COBOL run-time system when calling a non-COBOL program.
  • Interfacing with C Programs
  • Passing Data between C and COBOL
    Passing data using record layouts.
  • Header-to-COPY Utility
    The Header-to-COPY (H2cpy) utility is a self-contained application run from the command line or automatically invoked by the Headers preprocessor. It translates C-language header files into their COBOL-equivalent copyfiles. It can handle any valid ANSI or ISO C-language file.
  • Calling COBOL Programs from C
  • Error Messages when Calling Non-COBOL Programs
  • Signal Handling
    You can use signal handling in your application, especially if you are mixing COBOL and C in your application.
  • Examples of Mixed Language Programming
  • Avoiding data name conflicts
    Some data names are shortened when used in an external context.
Parent topic: COBOL Programming
Parent topic: Interoperability
Related information
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Call Conventions for Interfacing with Mixed Languages
Error Messages when Calling Non-COBOL Programs
Building a Mixed Language Application
Removing Parameters from the Stack
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications


Ordering Parameters to Pass to Non-COBOL Programs

The order in which the parameters are passed, since the calling program might not pass parameters in the order that the called program expects them.

You pass parameters to a non-COBOL program in much the same way as to a COBOL program, by specifying them in the USING phrase of the CALL statement. For example:

CALL call-convention "program-name" USING parameter-1, parameter-2

Just as when calling COBOL programs, the order of the parameters is important. However, some languages, such as Pascal, expect parameters in the opposite order from that expected by COBOL programs. You can use the call convention to define the order in which to pass the parameters.

COBOL programs pass parameters by pushing them onto the stack before calling the subprogram. The parameters can be pushed onto the stack either from right-to-left (reverse order) or from left-to-right (order specified). The first of these methods is the convention used by COBOL and by C. The second method is used by languages such as Pascal.

For example, on entry to a subprogram called with the statement:

CALL "sub-prog" USING  parameter-1
                       parameter-2
                        ...
                       parameter-n-1
                       parameter-n

the stack looks like one of the following illustrations. In both cases, parameters are pushed onto the stack from high memory to low memory. Stack Pointer is the register that points to the next vacant slot in the stack.

Figure 1. *
*
Parent topic: Mixed Language Programming
Related information
Storage Representation of Parameters
Number of Parameters in a USING Phrase
Number of Files for Sorting and Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming
Removing Parameters from the Stack
Optimizing Parameter Handling
Passing Parameters to a Called Program
Building a Mixed Language Application
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications


Removing Parameters from the Stack

Defining whether the called program removes the parameters from the stack before it returns to the calling program, or whether the calling program does it after receiving control back.

Different languages remove parameters from the stack at different times. In some languages, the called program removes the parameters before terminating and returning to the calling program. While in other languages, the calling program removes the parameters immediately after it receives control back.

In COBOL or C, the calling program removes the parameters, while in Pascal the called program removes them.

Specify the appropriate calling convention to ensure that the parameters are removed once and once only.

Parent topic: Mixed Language Programming
Related information
Optimizing Parameter Handling
Passing Parameters to a Called Program
Building a Mixed Language Application
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Number of Parameters in a USING Phrase
Number of Files for Sorting and Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming


Storage Representation of Parameters

The storage of parameters in mixed language applications, since different systems store data either with the most significant byte first or with it last.

The format in which parameters are stored can vary from one language to another. The following data types have implications for mixed-language programming:

USAGE | Storage Representation
COMP-X | Data is stored using big-endian byte ordering, where data is stored with the most significant byte first; that is, the most significant byte is at the lowest address. Although this is standard COBOL format, it is the reverse of the Intel standard of storing the most significant byte last (little-endian).
COMP-5 Data is stored in native order. On Intel x86 and little-endian PowerLinux platforms that is little-endian byte ordering, where data is stored with the least significant byte first; that is, the least significant byte is at the lowest address. On all other platforms, that is big-endian byte ordering, where data is stored with the most significant byte first; that is, the most significant byte is at the lowest address.

Using this data type enables you to pass parameters directly from COBOL to non-COBOL programs without parameter conversion.

POINTER and PROCEDURE-POINTER

Pointers are stored in native order.

If the AMODE Compiler directive is in effect, see AMODE for more details; otherwise, the size of a pointer or procedure-pointer is either 4 byte (32-bit platforms) or 8 byte (64-bit platforms).

Pointer variables are extremely useful for holding the address of a dynamically allocated memory area. COBOL programs can then access this memory using the SET ADDRESS statement.

Parent topic: Mixed Language Programming
Related information
Ordering Parameters to Pass to Non-COBOL Programs
Number of Parameters in a USING Phrase
Number of Files for Sorting and Merging
Call Conventions for Interfacing with Mixed Languages
Mixed Language Programming
Removing Parameters from the Stack
Optimizing Parameter Handling
Passing Parameters to a Called Program
Building a Mixed Language Application
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications
AMODE


Aligning Parameters on Word and Double Word Boundaries

Aligning numeric parameters on word and double-word boundaries to match the alignment in the non-COBOL program.

COBOL places no restrictions on the alignment of the addresses of data items, whereas in languages such as C and assembler, it is normal for numeric items to be aligned on word or double-word boundaries.

Make sure that you correctly align any numeric parameters that are not level-01 data items in the COBOL program, or that are in a parameter block passed as a single item.

To align numeric items, you can:

  • Modify group items to include additional filler items.
  • Use the ALIGN Compiler directive with a parameter that is a multiple of four. This aligns all level-01 and level-77 data items on double word boundaries. The Compiler uses ALIGN"8 OPT" by default.
  • Use the SYNCHRONIZED clause in conjunction with the IBM COMP Compiler directive.
Parent topic: Mixed Language Programming
Related information
Building a Mixed Language Application
Removing Parameters from the Stack
Handling Return Codes in Mixed Language Applications
Mixed Language Programming
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Call Conventions for Interfacing with Mixed Languages


Handling Return Codes in Mixed Language Applications

COBOL can pass and receive return codes from other programs.
Restriction: The following applies to native COBOL only.

Most languages are capable of passing a return code back to the calling program. COBOL can pass and receive them as follows:

  • To receive a return code from a non-COBOL program, use the RETURNING phrase in the CALL statement in the calling COBOL program.
  • To pass a return code back from a COBOL program, use the RETURNING phrase of the EXIT PROGRAM, GOBACK, or STOP RUN statement.

The RETURNING phrase enables you to define the format of the return code yourself and so cope with whatever size of return code you require.

Parent topic: Mixed Language Programming
Related information
Building a Mixed Language Application
Removing Parameters from the Stack
Aligning Parameters on Word and Double Word Boundaries
Mixed Language Programming
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Call Conventions for Interfacing with Mixed Languages


Call Conventions for Interfacing with Mixed Languages

The conventions for passing parameters, and other details of the interface between the two programs.

COBOL programs can call and be called by programs written in other languages. However, some languages handle calls differently from COBOL. For example, some language pass parameters in the opposite order from that expected by COBOL programs. To enable COBOL and non-COBOL programs to call each other, you can adjust the calling mechanisms that the COBOL program uses or that it expects to be used.

To specify the calling mechanisms you require, you first construct the call convention number that produces the required mechanisms. The call convention number is a 16-bit number defined as follows:

Bit 0
0 | Process parameters from right-to-left
1 | Process parameters from left-to-right
Note: This bit is ignored in JVM COBOL.
Bit 1
0 | Parameters removed from stack by calling program
1 | Parameters removed from stack by called program
Note: This bit is ignored in JVM COBOL.
Bit 2
0 | RETURN-CODE is updated on exit
1 | RETURN-CODE is not updated on exit
Any RETURNING phrase is not affected by this bit
Bit 3
0 | Normal linking behavior
1 | Call is resolved at link time
Bits 4 and 5
Reserved (always 0).
Bit 6
0 | The call does not conform to the Windows stdcall calling convention
1 | The call conforms to the Windows stdcall calling convention
This has no effect on dynamic calls.
Note: In JVM COBOL this bit is only supported on Windows.
Bit 7
Reserved (always 0).
Bit 8
0 | The parameter-count of individual entry-points is checked
1 | The parameter-count of individual entry-points is not checked
Note: This bit is ignored in JVM COBOL.
Bit 9
0 | The case of the program or call name is disregarded
1 | The case of the program or call name is significant
This call convention is an instruction to the generator on how to treat the text of a quoted program name or call name when litlinking. If this bit is 0 the case of the program or call name might still be significant depending on the CASE generator directive.
Note: This bit is ignored in JVM COBOL.
Bit 10
0 | Normal calling behavior
1 | The first parameter is always the RETURNING item for the CALL
Bits 11-15
Reserved (always 0).

When you have constructed the call convention number, you convert it to a decimal number, and then assign this decimal number to a name, by defining it the Special Names paragraph. You then use the call convention name in the CALL statement.

For example, if you define the following call conventions:

 SPECIAL-NAMES.
     CALL-CONVENTION 0 IS Microsoft-c
     CALL-CONVENTION 3 IS Pascal.

you can then use one convention when calling a C program as follows:

    CALL Microsoft-c "routine-name" USING parameter-1,parameter-2

and use the other convention when receiving a call from a Pascal program, such as:

 PROCEDURE DIVISION Pascal USING parameter-1,parameter-2

If you do not specify a call convention, the standard COBOL convention (call-convention 0) is assumed, unless the DEFAULTCALLS Compiler directive is used.

Parent topic: Mixed Language Programming
Related information
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Number of Parameters in a USING Phrase
Number of Files for Sorting and Merging
Mixed Language Programming
Interfacing with C Programs
Removing Parameters from the Stack
Optimizing Parameter Handling
Passing Parameters to a Called Program
Building a Mixed Language Application
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications


Building a Mixed Language Application

Compiling and linking a mixed language application, and preserving the COBOL run-time system when calling a non-COBOL program.

You can create applications that have both COBOL and non-COBOL programs calling each other. To do this:

  1. Make sure any non-COBOL program that runs preserves the COBOL run-time system, as follows:
    • The called program must preserve the local COBOL run environment (that is, the registers) according to C calling conventions
    • The global COBOL run environment (that is, data areas allocated by the COBOL system, open file, buffers, environment variables, and so on) must not be destroyed or altered, except under the direct control of the COBOL system.
  2. Compile the non-COBOL programs to standard Intel native object code.
Parent topic: Mixed Language Programming
Related information
Removing Parameters from the Stack
Aligning Parameters on Word and Double Word Boundaries
Handling Return Codes in Mixed Language Applications
Mixed Language Programming
Ordering Parameters to Pass to Non-COBOL Programs
Storage Representation of Parameters
Call Conventions for Interfacing with Mixed Languages


Interfacing with C Programs

This COBOL system provides a number of library functions that enable you to mix C and COBOL programs. These functions are intended primarily for use in C programs.

The functions are prototyped in C header files, which are located in by default.

The functions use portable data types, which have the naming convention cobtype_t. Definitions of these data types can be found in the cobtypes.h header file located in by default.

A C function can call a COBOL entry point in the same way as it would call another C function. For example, the following demonstrates C code that calls a COBOL entry point, cobep, using two arguments:

cobep(arg1, arg2);

A C function can call, and cancel, COBOL programs and entry points using the
        cobcall(),
        cobcancel() and
        cobfunc() routines, as described in the
        C Functions for Calling COBOL section.

Before calling a COBOL program, you must call cobinit(). In a threaded environment where you don't know if you're the first thread or not, each thread should call cobinit().

If a process calls fork(), without a corresponding exec(), then the child should call cobinit() before using any COBOL functionality. In such cases, the parent should not call COBOL, either before or after calling fork(), and should only have one thread at the time that fork() is called.

If your application has a C main() and the command line needs to be accessed from COBOL, then you must call cobcommandline().

Before exiting a thread that has called a COBOL program, but which was not created via COBOL multi-threading syntax or library routines, you must call cobthreadtidy().

Before exiting an application that has called a COBOL program you must call either cobtidy() or cobexit().

If the COBOL program and the C function that calls it are not contained in a callable DLL/shared object, nor linked together in a system executable file, then:

  • If the program on disk has a different name to the entry point being called, the program needs to be preloaded using cobgetfuncaddr()

All the C routines for calling COBOL are described in reference topics.

Parent topic: Mixed Language Programming
Related reference
cobget
cobput
Related information
C Functions for Calling COBOL
Call Conventions for Interfacing with Mixed Languages
Passing Data between C and COBOL
Signal Handling Overview


Passing Data between C and COBOL

Passing data using record layouts.

A COBOL record layout is similar to a C structure containing arrays of characters. When the Compiler assigns a COBOL record layout, it does not take into account the alignment of binary or pointer data items, or byte ordering of binary (COMP-X) data items, required by any specific hardware platform; because of this, COBOL applications are extremely portable. However, this portability can cause problems in mixed-language applications. C structure layout is not as rigidly defined as COBOL record layout and varies quite widely from operating system to operating system. For example, the structure is six bytes long in COBOL, no matter what platform it is compiled on:

01  mystruct is typedef.
        05  mystruct-key-1     pic x occurs 2.
        05  mystruct-bin-1     pic x(4) comp-5.

However, with the C compilers provided on most operating systems, a straightforward representation of this record layout in C would give different results. For example, the following would result in a structure eight bytes long on most 32-bit operating systems, and 16 bytes long on most 64-bit operating systems, due to alignment padding:

struct mystruct
 {
         char		mystruct_key_1[2];
         long		mystruct_bin_1;
     };

A better solution, because it is portable, is to represent the COBOL record mystruct using the C structure, as follows:

struct mystruct
 {
         char		mystruct_key_1[2];
         char		mystruct_bin_1[4];
     };

To enable conversion of COBOL data records into the C data types for a mixed-language application, a C include file is supplied. This file, cbltypes.h and located in , contains many of the basic types used in COBOL applications and in our CBL_ library routine interfaces. These types directly correspond to those types contained in the copybook cbltypes.cpy, found in $COBDIR/cpylib by default.

Revisiting the example above, the following COBOL record layout:

01  mystruct is typedef.
     05  mystruct-key-1  cblt_x1 occurs 2. *> aka. "PIC X"
     05  mystruct-bin-1  cblt_x4_comp5.    *> aka.
#                                       "PIC X(4) COMP-5"

can be correctly represented in C, using cbltypes.h, as:

#include "cbltypes.h"

    struct mystruct
 {
        cbl_x1_t          mystruct_key_1[2];
        cbl_x4_comp5_t    mystruct_bin_1;
    };

The type name conventions used in cbltypes.h are intended to naturally reflect the PICTURE strings of the corresponding COBOL type definition. The basic types provided in this include file are as follows:

cbl_x1_t  cobol character position - basis for all types

cbl_pointer_t   Equivalent to: USAGE POINTER
cbl_ppointer_t  Equivalent to: USAGE PROCEDURE-POINTER

cbl_sx1_comp5_t Equivalent to: PIC s9(n) COMP-5
                                         where n=1 or 2
cbl_sx2_comp5_t Equivalent to: PIC s9(n) COMP-5
                                         where n=3 or 4
cbl_sx4_comp5_t Equivalent to: PIC s9(n) COMP-5
                                         where n=7 through 9
cbl_sx8_comp5_t Equivalent to: PIC s9(18) COMP-5

cbl_x1_comp5_t  Equivalent to: PIC X(1) COMP-5
cbl_x2_comp5_t  Equivalent to: PIC X(2) COMP-5
cbl_x4_comp5_t  Equivalent to: PIC X(4) COMP-5
cbl_x8_comp5_t  Equivalent to: PIC X(8) COMP-5

cbl_x1_compx_t  Equivalent to: PIC X(1) COMP-X
cbl_x2_compx_t  Equivalent to: PIC X(2) COMP-X
cbl_x4_compx_t  Equivalent to: PIC X(4) COMP-X
cbl_x8_compx_t  Equivalent to: PIC X(8) COMP-X

Even though you can portably declare COBOL data in the C language, you still need to operate on that data in a C context. To enable you to do this, C library routines are provided. These routines enable many COBOL-based data types to be converted into a format suitable for use in the context of your C application component.

Parent topic: Mixed Language Programming
Related reference
cobget
cobput
Related information
Interfacing with C Programs
Signal Handling Overview


Header-to-COPY Utility

The Header-to-COPY (H2cpy) utility is a self-contained application run from the command line or automatically invoked by the Headers preprocessor. It translates C-language header files into their COBOL-equivalent copyfiles. It can handle any valid ANSI or ISO C-language file.
  • Overview
  • Converting Header Files Using the H2cpy Utility
  • Overview - H2cpy Messages
Parent topic: Mixed Language Programming


Overview

H2cpy is a utility program that converts C header files, such as those used when writing calls to the Win32 API, to their equivalent COBOL statements. The utility can convert:

C typedef | to COBOL type definition
C function prototype | to COBOL CALL prototype
#define | to Level-78 item

The Header-to-copy utility also converts the various standard call conventions and methods of passing parameters to their COBOL equivalents.

The COBOL system then uses the entries in the copyfile to verify that the parameters used in a COBOL program conform to the definition in the original C-language header file. H2cpy simplifies COBOL programming when you are using libraries of routines whose call interfaces are provided as C-language header files, such as when calling the Win32 API.

The Header-to-copy utility converts all the specified C header files into one COBOL copyfile; you cannot convert C header files into separate COBOL copyfiles and then use these copyfiles in your program.

As a result of its conversion process, the Header-to-copy utility produces two COBOL files which you can include in your COBOL program using the COPY statement. The main .cpy file contains type definitions and literals; the subsidiary .ext file contains any external data declarations. As well as being essential when using C interfaces, you might also find H2cpy helpful when rewriting C programs in COBOL.

If you want to convert several header files, you can either list them on the command line, or you can create your own wrapper header file that contains an #include statement for each header file. You need to consider whether the header files require macros to be set to predefined values. C compilers often implicitly set some macros, but you must explicitly set any such macros; either on the command line, or in your wrapper header file.

If you commonly convert particular types of header files, such as, for example, the Windows API header files, then you will use similar groups of H2cpy options. You can save time by putting such options in a file, h2cpy.dir (see the -G H2cpy command line option for details.)

The Header-to-copy utility accepts any valid ANSI or ISO standard C source file. H2cpy might fail or generate incorrect COBOL code if it encounters invalid C.

You can invoke the Header-to-copy utility:

  • from the command line
  • indirectly via the PREPROCESS"headers" Compiler directive
  • Examples
Parent topic: Header-to-COPY Utility


Examples

The examples in this topic are code fragments, and not the complete code generated by H2cpy.

The examples generate extra COBOL data items in addition to those specified in the code fragments. These extra data items are included in the output COBOL copy file because they are general COBOL typedefs that correspond to equivalent C data types. The size of these data items depends on the environment you are using.

       77 char                pic s9(2)   comp-5 is typedef.
       77 uns-char            pic  9(2)   comp-5 is typedef.
       77 short               pic s9(4)   comp-5 is typedef.
       77 uns-short           pic  9(4)   comp-5 is typedef.
       77 int                 pic s9(9)   comp-5 is typedef.
       77 uns-int             pic  9(9)   comp-5 is typedef.
       77 long                pic s9(9)   comp-5 is typedef.
       77 uns-long            pic  9(9)   comp-5 is typedef.
       77 l-long              pic s9(18)  comp-5 is typedef.
       77 uns-l-long          pic  9(18)  comp-5 is typedef.
       77 d-l-float                       comp-2 is typedef.
       77 d-float                         comp-2 is typedef.
       77 float                           comp-1 is typedef.
       77 proc-pointer        procedure-pointer is typedef.
       77 data-pointer                    pointer is typedef.
       77 void                pic  9(2)   comp-5 is typedef.
Note: C header files that require other header files that have been previously processed in the same run cannot be processed on their own by the C compiler. Similarly, H2cpy can only translate a standalone header file, or a complete set of header files. Any macro-names that need specifying in the C compiler command line, and any macros predefined by a particular compiler, might need specifying on the H2cpy command line. For example, Microsoft-specific predefined macros include:
  • CHAR_UNSIGNED
  • _CPPUNWIND
  • _DLL
  • _M_IX86
  • _MSC_VER
  • _MT
  • _WIN32
  • _CPPRTTI
  • _M_ALPHA
  • _M_MPPC
  • _M_MRXOOO
  • _M_MPPC
  • _MFC_VER
  • _MT

Do not specify the __cplusplus macro as H2cpy is not suitable for C++ headers.

ANSI C-predefined macros that might need to be specified on the command line using the -D option include:

  • __DATE__
  • __FILE__
  • __LINE__
  • __STDC__
  • __TIME__
  • __TIMESTAMP__
Parent topic: Overview


Converting Header Files Using the H2cpy Utility

You can run the Header-to-copy utility directly from the command line or invoke it automatically using the PREPROCESS(headers) Compiler directive. The Headers preprocessor allows C header files, with an extension of .h, to be specified in a COPY statement in a COBOL source file. The preprocessor recognizes these as C header files and uses the Header-to-copy utility to convert them. This can be very convenient for relatively small header files.

To invoke the Header-to-copy utility from the command line, type:

h2cpy {[filename] [option]} ...

where the parameters are:

filename | The C-language header file to be converted to a COBOL copybook
option | An H2cpy command-line option

If you do not specify filename or option, a list of available options is displayed.

  • H2cpy command-line options
  • H2cpy Translations
  • Translating Names
  • Translating Statements
Parent topic: Header-to-COPY Utility


H2cpy command-line options

An option begins with a hyphen (-) and is case sensitive. Single letter options that take no parameters can be grouped behind one hyphen. For example, the three options "-v -C -h" can also be written as "-vCh". Options can be entered in any order.

The forward slash (/) can be used in place of the hyphen. Options that begin with a hyphen must not be used before specifying the first filename.

The following list describes each option in detail. Options are listed in alphabetical order, with upper-case letters preceding lower-case letters. Spaces between the option letter and any parameter are optional.

Option | Description
-A Removes strict ANSI interpretation of C-language.

There are some obscure areas in which the current ANSI/ISO C standard differs from earlier C language implementations. If you have problems and suspect it is due to old fashioned C, try using this option.

-C Embeds C code within generated COBOL.

The embedded C source lines start with an asterisk (*) and space and are ignored by the COBOL Compiler. The embedded code has been through the C preprocessor.

-D name[=val] | Declare a macro name, optionally giving a value. The value can be a numeric or a string literal.
-E Expand all occurrences of structures and unions.

The COBOL for a structure or union is only given in full when it is first declared. Later references are by name.

-F name=val Equate a C function calling convention name to a COBOL CALL-CONVENTION value val for CALL protoypes, where name can be one of the following:
Name | Default value
cdecl | 0
default | 0
fastcall | 2
optlink | 16
pascal | 11
stdcall | 74
system | 16

These names match C keywords, possibly with one or more leading underscore characters, except for default which represents the default C calling convention when a convention is not explicitly specified.

-G name Use the group of options specified by name and process them before those options specified on the command line. The options must be held as one or more lines in the file h2cpy.dir, and preceded by the header [name]. The file can be located in the current directory but if name is not found, then H2cpy searches the $COBDIR directory for the file h2cpy.dir. The options in the h2cpy.dir file can include the -G option on the first line after the heading, as long as the name is a forward reference. Lines starting with hash (#) or semi-colon (;) are treated as comment lines and ignored. If verbose mode is selected, then the h2cpy command displays name and the file in which it was found.

For example, the h2cpy.dir file could contain the following:

[default]
-G win32
[win32]
# For generating a simple, general win32 header file
# from 32-bit windows.h
# This is set for the executable entry points, for dlls
# add -D DLL
-e 32 -D _MSC_VER=1000 -D CHAR_UNSIGNED -D _M_IX86=500
-D _WIN32 -D WINVER=0x0400 -D WIN32_LEAN_AND_MEAN

If -G option is not specified, the default is -G default. The -G option cannot be combined with other options behind a hyphen (-).

-I path Insert the path at the beginning of the include search path list. This option can be used to add entries until the search path list is full. The list can hold up to fourteen entries.

The search list is initially empty unless the INCLUDE environment variable is used.

-J | Change default for character type to unsigned
-K name | Specifies that name should be recognized (and ignored) as a keyword. This option is useful for header files tailored for C compilers that are not covered by the -M option.
-M Disables the Microsoft keywords that are normally recognized:
cdecl | dllexport | dllimport | except
far | finally | fortran | interrupt
huge | near | pascal | thread
_asm | _based | _cdecl | _far
_emit | _export | _fastcall | _fortran
_huge | _inline | _interrupt | _loadds
_near | _pascal | _saveregs | _segment
_segname | _self |  |
__asm | __based | __cdecl | __declspec
__export | __far | __fastcall | __fortran
__huge | __inline | __int8 | __int16
__int32 | __int64 | __leave | __loadds
__near | __pascal | __saveregs | __segname
__segment | __self | __stdcall | __try
-O Disable the IBM C (for OS/2) keywords that are normally recognized:
_Cdecl | _Far32 | _Optlink | _System
_Export | _Fastcall | _Packed | _Pascal
_Far16 | _Inline | _Seg16 |
-P Just preprocess the C, do not generate the COBOL copyfile.

This option is equivalent to the -C option but additionally suppresses COBOL generation. It is useful if you suspect that H2cpy preprocesses the C source differently from your C compiler.

-R name Add a COBOL reserved word to the dictionary

All current known reserved words are already built into H2cpy. This option enables you to add new ones.

-S | Generate COBOL for #define macro definitions into a separate file. The filename will be based on the output filename but with any extension replaced by .78.
-V Do not generate COBOL variable numbers of parameters

This option disables the generation of a provisional COBOL equivalent. (The C language ellipsis (...) has no standard COBOL equivalent at present, so H2cpy ignores it.)

-W | Remove COBOL context-sensitive reserved words
-X Extend the COBOL equivalence of string pointers from just char* to both char* and unsigned char*

An unsigned char* parameter to a function prototype will generate, by default, a BY REFERENCE uns-char. The type uns-char is numeric which is generally suitable except for header files, such as os2.h, that use the type unsigned char* to define string pointers. Use the -X option when converting such files so that H2cpy generates BY REFERENCE ANY and you can pass string parameters as PIC X(n) items.

-a type=n Set the alignment for C type, where type is one of: int, char, short, long, llong, pointer, float, dfloat or dlfloat.

There are default alignments for all these C types (see the -e option). This option enables them to be varied individually. Alignment is modified by the #pragma pack directive, if used, in the C header file.

-c Generate all names in COBOL in lower case

H2cpy generates the first occurrence of COBOL names to be as close to the original C names as possible. The case of each letter in the name is as in the original C.

-e n Target environment where n is:
16/ LP32 | int 16-bit, long & pointer 32-bit
32/ ILP32 | int, long and pointer 32-bit
LLP64 | int & long 32-bit, long long & pointer 64-bit
LP64 | int 32-bit, long and pointer 64-bit
ILP64 | int, long and pointer 64-bit
If this option is not specified, the default is 16 or 32 depending on the environment in which H2cpy is running.

The size and alignment of C types is dependent on the environment in which the code is to run. The 32-bit environment size and alignment for C types are:

char 1:1, short 2:2, int 4:4, long 4:4, long long 8:4, pointer 4:4, float 4:4, double float 8:8 or double long float 8:8.

You can modify the default values using the -a and -s options.

-f Pass #define floating point literals to COBOL

The COBOL Compiler validates the size and format of float literals. By default, if a #define directive specifies a macro as a floating constant, no COBOL is generated. Setting this option causes a COBOL equivalent to be generated; however, the COBOL Compiler may object to the size of the number.

If a floating constant is included in a constant expression and H2cpy evaluates that expression, then the floating constant is treated as zero and a warning given.

-h Convert hex #define value to decimal

By default, if a #define directive specifies a macro as a hexadecimal constant, H2cpy generates a COBOL hexadecimal constant. Setting this option causes H2cpy to generate the equivalent decimal value in the generated COBOL.

-o name Name the generated COBOL output file

By default, the names of the output files containing the generated COBOL are constructed from the basename of the first C header file, with extension .cpy for the main copyfile and .ext for the external declarations file. This option enables you to use an alternative name for the main file. The file containing generated external declarations always has the same basename as the main file.

-p Do not generate CALL prototypes

By default, H2cpy converts C function prototypes into COBOL CALL prototypes. The COBOL Compiler then ensures that any CALLs conform to the CALL prototypes. The checking for conformance is not always very flexible.

Set this option if you do not want H2cpy to generate CALL prototypes.

Beware of calls that pass a numeric literal (or level-78 item) as a parameter. The Compiler converts the item to COMP-5 format with the size being provided by the COBOL CALL prototype. If there is no CALL prototype present, then the default size of two bytes may be incorrect and the call may fail at run time. You must specify the correct size in bytes using the SIZE clause to the BY VALUE phrase in such cases.

-q | Do not ask for user response if #include file not found
-r Remove COBOL reserved word list

Use this option to reduce start-up time if you are not going to compile the generated COBOL.

-s type=n | Set the size for C type, where type is one of: int, char, short, long, llong, pointer, float, dfloat or dlfloat.
-v Toggle informational messages to screen on/off

This option switches the display of messages on the screen. Verbose mode displays the program banner and other messages, including a trace of nested #include files.

Silent mode displays only error messages. The default is verbose mode.

-w | Remove COBOL managed-only reserved words
-z name | Remove COBOL reserved word
Parent topic: Converting Header Files Using the H2cpy Utility


H2cpy Translations

Directives

The Header-to-copy utility translates the following types of directive:

  • preprocessor
  • macro
  • conditional
  • #error
  • #pragma

Statements

The Header-to-copy utility translates the following types of statement:

  • definitions
  • declarations

Calls

The Header-to-copy utility translates the following types of call:

  • call conventions
  • parameter passing

Other

The Header-to-copy utility does not generate COBOL for any other C construct.

Parent topic: Converting Header Files Using the H2cpy Utility


Translating Names

The Header-to-copy utility generally uses the same data and procedure names in the copyfile as in the original C header file. However, there are different standards in the way C and COBOL use names. The Header-to-copy utility generates a new name if the following occur in the C file:

  • The same name is used for two different items and the items are not different structures.
  • Two names are only differentiated by upper- or lower-case letters
  • A name starts with an underscore (automatically translated to hyphen)
  • The name is a reserved COBOL word
  • Two names are not unique over the first 30 characters

Some of these can be changed by setting the options available.

The new name generated by H2cpy is the old name with a number added to the front. The number is the number of synonyms encountered so far since the original name declaration.

  • Using the Headers Preprocessor
  • Translating Directives
Parent topic: Converting Header Files Using the H2cpy Utility


Using the Headers Preprocessor

Running the Header-to-copy utility from the command line is often most convenient when:

  • Converting large C header files
  • You want to modify the generated copyfile
  • You want to use a variety of command line flags

For simple header files it can be more convenient to reference the C header file directly from within your COBOL program and allow the Headers preprocessor to invoke the Header-to-copy utility automatically each time the progam is compiled.

To use the Header-to-copy utility in this way, simply include COPY statements that reference .h files within your COBOL program. There is no restriction on where the COPY statements can appear. In addition, ensure you use the directive PREPROCESS(headers). This can be done most conveniently in a $SET statement as in the following example:

$set preprocess(headers)
 working-storage section.
 01 data-item pic x(9).
     copy "cheader.h".
 01 cobol-b usage btype.
 procedure division.
     copy "cheader2.h".
     move 6 to c-long        of cobol-b
     move 7 to c-int         of cobol-b
     move "Show" to c-char   of cobol-b
     display "C struct= " c-long " " c-int " " c-char  level-78.

where cheader.h contains:

#define b B
int a;
typedef struct btype {
   long c_long;
   char c_char[5];
   int  c_int;
   } b;

cheader2.h contains:

#ifdef b
#define level_78 "C literal"
#else
typedef struct btype {
   signed char c_uchar;
   float  c_float[5];
   } b;
#endif

and when run, the program displays:

C struct= +0000000006 +00007 Show C literal
Parent topic: Translating Names


Translating Directives

H2cpy translates the following types of directive: preprocessor, macro, conditional, #error, and #pragma.

  • Preprocessor Directives
  • Expanding Macros and Creating String Literals
  • Translating Conditional Directives
  • Translating Other Directives
Parent topic: Translating Names


Preprocessor Directives

H2cpy handles both #include and #define directives.

Translating #include Directives

H2cpy handles #include directives of the form:

#include <name> | where name can be a simple filename with extension, or a filename that includes a relative path
#include "name" | where name can be a simple filename with extension, a filename that includes a relative path or a filename that includes an absolute path
#include macro | where macro expands to give one of the other two forms

H2cpy looks for the named file, and reads the C source from that. When it reaches the end of the file, it resumes reading the original file.

You do not need to enter the absolute path for a file when you use the #include directive. If you enter a non-absolute filename in quotation marks (" "), H2cpy searches for the file in the current directory first, followed by each directory in the include search path list.

If you enter the filename within angle brackets (<>), the filename is assumed to be a system header file and only the include search path list is searched. The current directory is not searched.

The search path list contains from zero to fourteen absolute directory names. The file is searched for in each of the directories in turn until it is found or the search list is exhausted. If H2cpy still cannot find the file, you receive an error message.

You can add additional directories to the front of the search path list using the -I option described in the section Command-line Options.

The include search path list initially has the one entry /usr/include. H2cpy assumes that the character that delimits directory-names in a path is the backslash (\). Any forward slashes (/) in the filename are converted to backslashes before the file is searched for.

For example, if you set the INCLUDE environment variable as follows:

include=d:\include;e:\sys\include

the directive:

#include <Xm/Xm.h>

causes H2cpy to look for d:\include\Xm\Xm.h. It then searches for e:\sys\include\Xm\Xm.h.

Using the default path of /usr/include, the directive:

#include <Xm/Xm.h>

causes H2cpy to search for /usr/include/Xm/Xm.h only.

Translating #define Directives

H2cpy handles macros with parameters as well as those without parameters. It stores them and expands them if the macro-name is encountered in the C source. A macro can contain any number of C tokens and in general will not be directly translatable to COBOL.

H2cpy translates the following macro definitions to COBOL level-78 items:

  • A single C string literal, character, integer or floating constant
  • A numeric constant expression that can be evaluated to a single integer constant.

If H2cpy encounters a macro that has been defined before in both cases with identical C tokens, H2cpy ignores it. If the definitions are different, you receive an error message.

The #undef directive can be used to undefine a macro-name that may previously have been defined.

Parent topic: Translating Directives


Expanding Macros and Creating String Literals

The Header-to-copy utility expands macros with parameters, using the string and concatenation operators # and ##. For example, the following #define directive:

#define DECLARE_HANDLE32(name) struct name##__ { int unused; }; \
  typedef const struct name##__ _far* name

produces no level-78 item, but if the C header then invokes the macro later, using:

DECLARE_HANDLE32(HHOOK);

it is expanded according to the rules for C and translated into the equivalent COBOL. COBOL does not provide typed pointers except for distinguishing between data and procedure pointers.

 01 HHOOK--  is typedef.
     02 unused     usage int.
 01 HHOOK   is typedef  usage data-pointer.
Parent topic: Translating Directives


Translating Conditional Directives

H2cpy interprets the following conditional directives, which can be nested:

  • #if
  • #else
  • #endif
  • #elif
  • #ifdef
  • #ifndef

The #if directive must be followed by a constant expression. Macros in the expression are expanded, the defined operator evaluated, unknown names replaced by zero and the resulting numeric expression evaluated to give a numeric value. If the result of evaluation of the expression is zero, then the condition is false; otherwise, it is true. If the condition is false, then the following lines are ignored; otherwise, they are translated.

The #else and #endif directives switch the sense and terminate the effect of the preceding #if, #ifdef or #ifndef directive.

The #elif directive is treated as equivalent to a #else directive followed by a #if directive, except that the nesting level is not increased and any following #endif directive applies to the preceding #if directive.

The #ifdef directive must be followed by a name. If the name has previously been defined, either in the header file or as a result of the -D option, then the condition is true; otherwise, it is false. If the condition is false, then following lines are ignored; otherwise, they are translated. The #ifndef directive is treated in the same way as the #ifdef directive except the sense of the condition is reversed.

Parent topic: Translating Directives


Translating Other Directives

The #error directive can be followed by any comment on the directive line. If you have specified the -C option to the H2cpy command, the Header-to-copy utility displays the entire line on the screen and lists it in the output file.

The #pragma directives are ignored, except for the Microsoft C pragma for packing structure or union members, which modifies the default alignments of C types. A directive of the form:

#pragma pack(n)

where the value of n is 1, 2 or 4, aligns any following structure or union members to 1,2 or 4-byte boundaries. The default alignments can be reinstated by a directive of the form:

#pragma pack()

The default alignments can be modified by the -e or -a options of the H2cpy command; see the Command-line Options topic for details.

The #pragma push directive stores the current alignment on a stack; #pragma pop restores the alignment from the stack.

The pack pragma is ignored if both the -M and -O options of the H2cpy command are specified.

The Header-to-copy utility ignores any other line which has a hash (#) character in the first character position.

Parent topic: Translating Directives


Translating Statements

H2cpy translates the following statements: declarations and definitions.

H2cpy does not generate COBOL for any other C construct.

  • External Data Declarations
  • Type Definitions
  • Structure, Union and Enumerator Declarations
  • Function Prototype Declarations
  • Call Parameters
  • H2cpy Limitations
Parent topic: Converting Header Files Using the H2cpy Utility


External Data Declarations

The Header-to-copy utility ignores any data declaration it encounters unless it is defined as being external. If a C data declaration is defined as extern then the Header-to-copy utility generates a COBOL declaration using the IS EXTERNAL phrase.

If such an item is declared within a C module and the COBOL application can be linked to it, then the declaration allows the COBOL application to reference this C data item.

The Header-to-copy utility generates all output into the .cpy file except for external data declarations which are output to a separate .ext file.

  • Example - Translating External Data Declarations
Parent topic: Translating Statements


Example - Translating External Data Declarations

The following example shows how the Header-to-copy utility translates external data declarations in C source code to their equivalent COBOL copyfile form.

C source:

typedef struct _WidgetClassRec *WidgetClass;
extern WidgetClass widgetClass;

COBOL output (to .cpy file)

 01  WidgetClass       is typedef       usage data-pointer.

COBOL output (to .ext file):

 01  1widgetClass      is external by "widgetClass"
                       usage data-pointer.

The names of the type definition and the external data item must be unique for COBOL which is why H2cpy has added a 1 to the front of the data-name. The symbolic name widgetClass is the name to be used by the Linker to resolve the reference to the external data item declared in C.

Parent topic: External Data Declarations


Type Definitions

The Header-to-copy utility treats a character as a numeric item if it is explicitly declared as signed or unsigned. If declared as an array, it is treated as a COBOL alphanumeric item. Otherwise, it is treated as a numeric item. Two-dimensional arrays generate a COBOL OCCURS clause.

Arrays which have no array size are translated as if they were a pointer to the given type.

Pointers to any C data type are mapped to COBOL data pointers via a type definition. Pointers to a C function type are similarly mapped to COBOL procedure pointers.

  • Example - Translating Type Definitions
Parent topic: Translating Statements


Example - Translating Type Definitions

The following example shows how the Header-to-copy utility translates type definitions in C source code to their equivalent COBOL copyfile form.

C source:

typedef char t_slab[12], cnt, c_list[], c_table[12][5];
typedef unsigned char BYTE, *BYTE_ptr;
typedef t_slab *t_slab_ptr;
typedef void _near _cdecl _export _dmsEVENT(short ent_type);
typedef _dmsEVENT *fptr;
typedef void (*XtActionProc)(
#if NeedFunctionPrototypes
  Widget  /* widget */,
  XEvent*  /* event */,
  String*  /* params */,
  Cardinal*  /* num_params */
#endif
);
typedef XtActionProc* XtBoundActions;

COBOL output:

 01  t-slab          is typedef pic x(12).
 01  cnt             is typedef usage char.
 01  c-list          is typedef usage data-pointer.
 01  c-table         is typedef.
     02  filler occurs 12   pic x(5).
 01  BYTE            is typedef usage uns-char.
 01  BYTE-ptr        is typedef usage data-pointer.
 01  t-slab-ptr      is typedef usage data-pointer.
 01  fptr            is typedef usage proc-pointer.
 01  XtActionProc    is typedef usage proc-pointer.
 01  XtBoundActions  is typedef usage data-pointer.

Other type definitions generate similar COBOL type definitions. For example:

typedef signed int I, AI[12], *PI, I_Table[12] [5];

produces the following COBOL code:

 01  I          is typedef usage int.
 01  AI         is typedef.
     02  filler occurs 12  usage int.
 01  PI         is typedef usage data-pointer.
 01  I-Table    is typedef.
     02  filler occurs 5.
         03  filler occurs 12 usage int.
Parent topic: Type Definitions


Structure, Union and Enumerator Declarations

Structure, union and enumerator declarations can be either named or unnamed. They can appear on their own or within type definitions or within structure or union declarations.

When a declaration is named, COBOL is generated in full for the item.

When a declaration is unnamed, COBOL is generated in full only for the items that use it.

The Header-to-copy utility generates level-78 items for the named values for an enumeration type. Enumeration items can be named within structures; bit fields can also be specified within structures.

  • Example - Translating Named Declarations
  • Example - Translating Unnamed Declarations
  • Example - Translating Enumerator Declarations
Parent topic: Translating Statements


Example - Translating Named Declarations

The following example shows how the Header-to-copy utility translates named declarations in C source code to their equivalent COBOL copyfile form.

C source:

typedef struct fsid { long val[2]; } fsid_t;
typedef unsigned long ino_t;  /* inode number (filesystem) */
typedef unsigned int  uint_t;
#define FHSIZE        32
#define MAXFIDSZ     (FHSIZE - sizeof(fsid_t) - sizeof(uint_t))
struct fileid {  /* this is for servers only! */
       uint_t  fid_len;
       ino_tfid_ino;
       uint_t  fid_gen;
       char fid_x[MAXFIDSZ - (sizeof(ino_t) + 2) - sizeof(uint_t)];
};

COBOL output:

 01  fsid           is typedef.
     02  val occurs 2     usage long.
 01  fsid-t         is typedef usage fsid.
 01  ino-t          is typedef usage uns-long.
 01  uint-t         is typedef usage uns-int.
 78  FHSIZE         value 32.
 78  MAXFIDSZ       value 28.
 01  fileid         is typedef.
     02  fid-len          usage uns-int.
     02  filler       pic x(2).
     02  fid-ino          usage uns-long.
     02  fid-gen          usage uns-int.
     02  fid-x        pic x(14).

H2cpy ensures the correct alignment of the field fid-ino (which is a long, alignment 4) by inserting a two-byte FILLER item after the two-byte fid-len field.

The correct alignment is subject to the -e and -a options as well as the #pragma pack directive.

Parent topic: Structure, Union and Enumerator Declarations


Example - Translating Unnamed Declarations

The following example shows how the Header-to-copy utility translates unnamed declarations in C source code to their equivalent COBOL copyfile form.

C source:

  typedef struct {
     int type;
     union {
        char b[20];
        short s[10];
        long l[5];
     } data;
  } XClientMessageEvent;

COBOL output:

 01  XClientMessageEvent is typedef.
     02  type                   usage int.
     02  filler          pic x(2).
     02  data.
         03  data.
             04  1b      pic x(20).
         03  filler redefines data.
             04  s occurs 10    usage short.
         03  filler redefines data.
             04  l occurs 5     usage long.
Parent topic: Structure, Union and Enumerator Declarations


Example - Translating Enumerator Declarations

The following example shows how the Header-to-copy utility translates enumerator declarations in C source code to their equivalent COBOL copyfile form.

C source:

enum input_type { GPICK = 0x0001, GANK= 0x0002, GPFK = 0x0004,
                  FP_NOINBUF = 0x10000, FP_WTMAX = 0x20000 };
typedef struct qqel {   /* queue element*/
   enum input_type type;  /* enum input_type value */
   int time;    /* timestamp */
   struct {
      unsigned bad_data :1;  /* extra data io failed  */
      unsigned no_data  :1;  /* queue empty (for K_POLL) */
      unsigned reserved :6;  /* reserved  */
      char rsvd[3];    /* reserved  */
   } flags;
   int data_len;    /* length of appended data */
} q_qel;

COBOL output:

 01  input-type  is typedef  usage uns-int.
 78  gpick           value  1.
 78  gank            value 2.
 78  gpfk            value 4.
 78  fp-noinbuf      value 65536.
 78  fp-wtmax        value 131072.
 01  qqel   is typedef.
     02  type        usage input-type.
     02  time        usage int.
     02  flags.
         03  bad-data.
             04  bad-data       usage uns-int. *>> 1 Bit
         03  filler redefines bad-data.
             04  no-data        usage uns-int. *>> 1 Bit
         03  filler redefines bad-data.
             04  reserved       usage uns-int. *>> 6 Bits
         03  rsvd               pic x(3).
         03  filler             pic x(1).
     02  data-len               usage int.
 01  q-qel   is typedef  usage qqel.

The field rsvd is three bytes long. An assumption has been made that the preceding eight bits allocate one byte of storage. In fact, the ANSI C standard says that bitfields are within an integer and so a 16-bit area will be allocated, requiring H2cpy to add a one-byte padding item on the end.

Parent topic: Structure, Union and Enumerator Declarations


Function Prototype Declarations

C function prototypes must always return a type of item and must always pass at least one parameter. If no parameters are shown, then the function declaration is not a function prototype and the Header-to-copy utility does not generate any COBOL CALL prototype. If no return type is shown, then the return type is assumed to be of type int.

If a function is not to return anything, then a function prototype uses a return type of void. The Header-to-copy utility translates this, omitting any RETURNING clause. If a function is not to have any parameters, the function prototype will have one parameter of type void. The Header-to-copy utility translates this by omitting the USING clause, together with any BY VALUE or BY REFERENCE clause.

  • Example - Translating Function Prototype Declarations
  • Example - Translating C Calling Conventions
Parent topic: Translating Statements


Example - Translating Function Prototype Declarations

The following example shows how the Header-to-copy utility translates function prototype declarations in C source code to their equivalent COBOL copyfile form.

C source:

extern XFontStruct *XLoadQueryFont(
);
extern void XrmInitialize(
);
extern char *XFetchBytes(
);
extern int (*XSetAfterFunction(
))();
extern XtAppContext XtCreateApplicationContext(
void
);
extern void XtInitializeWidgetClass(
WidgetClass
);
XmColorProc XmGetColorCalculation(void);

COBOL output:

 program-id. "c_typefefs" is external.
 special-names.
     call-convention default-convention-val is defaultconv.
$set constant XtCreateApplicationContext "XtCreateApplicationContext"
 entry XtCreateApplicationContext default-conv
  returning   data-pinter
     .
$set constant XtInitializeWidgetClass "XtInitializeWidgetClass"
 entry XtInitializeWidgetClass default-conv
  using       by value   data-pointer
     .
$set constant XmGetColorCalculation "XmGetColorCalculation"
 entry XmGetColorCalculation default-conv
  returning   proc-pointer
     .
end program "c_typedefs".

This output is slightly different to previous phases. The entry names are specified using constants rather than by literals, and the call conventions are specified by entries in the Special Names paragraph.

Parent topic: Function Prototype Declarations


Example - Translating C Calling Conventions

The following example shows how the Header-to-copy utility translates calling conventions in C source code to their equivalent COBOL copyfile form.

C source:

typedef HINSTANCE HMODULE;
DWORD _far _pascal GetVersion(void);
UINT _far _pascal GetFreeSystemResources(UINT);
#define GFSR_SYSTEMRESOURCES 0x0000
BOOL _far _pascal SetWinDebugInfo(const WINDEBUGINFO _far*
<_><_>lpwdi);
void _far _cdecl DebugOutput(UINT flags, LPCSTR lpsz, ...);
#define WDI_OPTIONS 0x0001

COBOL output:

 01  HMODULE    is typedef usage uns-int.
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention pascal-convention-val is pascal-conv.
$set constant GetVersion "GetVersion"
 entry GetVersion pascal-conv
  returning   uns-long
     .
$set constant GetFreeSystemResources "GetFreeSystemResources"
 entry GetFreeSystemResources pascal-conv using
  by value     uns-int
  returning    uns-int
     .
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention pascal-convention-val is pascal-conv.
 78  GFSR-SYSTEMRESOURCES     value h"0000".
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention pascal-convention-val is pascal-conv.
$set constant SetWinDebugInfo "SetWinDebugInfo"
 entry SetWinDebugInfo pascal-conv using
  by reference windebuginfo
  returning    int
     .
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention cdecl-convention-val is cdecl-conv.
$set constant DebugOutput "DebugOutput"
 entry DebugOutput cdecl-conv using
  by value     uns-int
  by reference any
  by value     any
     .
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention cdecl-convention-val is cdecl-conv.
 78  WDI-OPTIONS    value h"0001".
 end program "c-typedefs".

H2cpy starts generating COBOL within the default external program c_typedefs which uses the default calling convention. The routine GetVersion uses the Pascal convention which is different, so H2cpy generates a header for a new external program containing a Procedure Division ENTRY statement. The routine GetFreeSystemResources uses the same calling convention so a second entry statement is generated with no need for a new program header. H2cpy then needs to generate a level-78 item in the Data Division, so it generates another program header. The routine DebugOutput uses the cdecl calling convention, so another program header is needed.

Parent topic: Function Prototype Declarations


Call Parameters

C passes parameters, conceptually, via the stack. Parameters can be passed directly or indirectly via pointers. COBOL does not currently allow items greater than four bytes to be passed directly via the stack. It is considered bad C programming practice to pass structs or unions via the stack. If such items are greater than the size of a pointer (four bytes) it is also less efficient. The COBOL restriction will not normally cause any problem. If the Header-to-copy utility encounters such code it adds additional parameters to ensure that the stack retains its integrity.

The simple C types such as int, char, pointer are easily mapped to COBOL. When passed directly as parameters on the stack, the Header-to-copy utility generates a BY VALUE clause. But C also enables pointers to be typed as a means for indirectly passing parameters. COBOL also enables indirection, but only to one level. Where the Header-to-copy utility encounters a typed pointer, it generates a BY REFERENCE clause.

  • Example 1 - Parameter Passing in C and in COBOL
  • Example 2 - Parameter Passing in C and in COBOL
Parent topic: Translating Statements


Example 1 - Parameter Passing in C and in COBOL

The following example shows how the Header-to-copy utility translates parameter passing conventions in C source code to their equivalent COBOL copyfile form.

C source:

typedef unsigned char BYTE;
typedef char _far* LPSTR;
typedef int HFILE;
typedef Boolean (*XtFilePredicate)( /* String filename */ );
BYTE _far _pascal GetTempDrive(char);
long _far _pascal _llseek(HFILE, long, int);
long _far _pascal _hwrite(HFILE, const void _huge*, long);
LPSTR _far _pascal AnsiLower(LPSTR);
void _far _pascal Throw(const int _far*, int);
extern_pascal String XtFindFile(
   CONST String    /* path */,
   Substitution    /* substitutions */,
   Cardinal    /* num_substitutions */,
   XtFilePredicate  /* predicate */
);

COBOL output:

 01  BYTE             is typedef usage uns-char.
 01  LPSTR            is typedef usage data-pointer.
 01  HFILE            is typedef  usage int.
 01  XtFilePredicate  is typedef usage proc-pointer.
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention pascal-convention-val is pascal-conv.
$set constant GetTempDrive "GetTempDrive"
 entry GetTempDrive pascal-conv using
  by value     char
  returning    uns-char
     .
$set constant 1-llseek "_llseek"
 entry 1-llseek pascal-conv using
  by value     int
  by value     long
  by value     int
  returning    long
     .
$set constant 1-hwrite "_hwrite"
 entry 1-hwrite pascal-conv using
  by value     int
  by value     data-pointer
  by value     long
  returning    long
     .
$set constant AnsiLower "AnsiLower"
 entry AnsiLower pascal-conv using
  by reference any
  returning    data-pointer
.
$set constant Throw "Throw"
 entry Throw pascal-conv using
  by reference int
  by value     int
.
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention default-convention-val is default-conv.
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
     call-convention default-convention-val is default-conv.
$set constant XtFindFile "XtFindFile"
 entry XtFindFile default-conv using
  by reference any
  by value     data-pointer
  by value     uns-int
  by value     proc-pointer
  returning    data-pointer.
     .
 end program "c-typedefs".

Notice in the routine _hwrite that a pointer to a void generates a data pointer passed by value. However, in the routine AnsiLower the type LPSTR which is a pointer to a character generates a BY REFERENCE clause with any parameter being allowed. A char would be too restrictive as normally any COBOL alphabetic item would be suitable. For this reason H2cpy generates any.

In the routine Throw, we have an int passed both BY VALUE and BY REFERENCE. In the routine XtFindFile, we pass a procedure pointer BY VALUE.

Parent topic: Call Parameters


Example 2 - Parameter Passing in C and in COBOL

The following example shows how the Header-to-copy utility translates parameter passing conventions in C source code to their equivalent COBOL copyfile form.

C source:

typedef int (_far _pascal* FARPROC)();
typedef struct tagSEGINFO
{
   UINT offSegment;
   UINT cbSegment;
   UINT flags;
   UINT cbAlloc;
   HGLOBAL h;
   UINT alignShift;
   UINT reserved[2];
} SEGINFO;
typedef SEGINFO _far* LPSEGINFO;
typedef struct tagPOINT
{
   int x;
   int y;
} POINT;
void _far _pascal GetCodeInfo(FARPROC lpProc, SEGINFO _far*
                  <_><_>lpSegInfo);
BOOL _far _pascal PtInRect(const RECT _far*, POINT);
void _far _pascal ClientToScreen(HWND, POINT _far*);

COBOL output:

 01  FARPROC     is typedef  usage proc-pointer.
 01  tagSEGINFO  is typedef.
     02  offsegment     usage uns-int.
     02  cbsegment      usage uns-int.
     02  flags          usage uns-int.
     02  cballoc        usage uns-int.
     02  h              usage uns-int.
     02  alignshift     usage uns-int.
     02  reserved occurs 2    usage uns-int.
 01  SEGINFO     is typedef usage tagseginfo.
 01  LPSEGINFO   is typedef usage data-pointer.
 01  tagPOINT    is typedef.
     02  x              usage int.
     02  y              usage int.
 01  POINT   is typedef usage tagpoint.
 end program "c-typedefs".
 program-id."c-typedefs" is external.
 special-names.
      call-convention pascal-convention-val is pascal-conv.
$set constant GetCodeInfo "GetCodeInfo"
 entry GetCodeInfo pascal-conv using
  by value     proc-pointer
  by reference seginfo
     .
$set constant PtInRect "PtInRect"
 entry PtInRect pascal-conv using
  by reference rect
  by value     point
  returning    int
     .
$set constant ClientToScreen "ClientToScreen"
 entry ClientToScreen pascal-conv using
  by value     uns-int
  by reference point
      .
 end program "c-typedefs".

A parameter of data type POINT is passed both BY VALUE and BY REFERENCE.

Parent topic: Call Parameters


H2cpy Limitations

H2cpy stores macros with parameters for possible expansion later. If H2cpy encounters a macro with parameters and the macro definition extends over more than two or three physical lines, it may not have enough space to store all the macro details. This has no effect until H2cpy is called upon to expand that macro. If this happens, you get an error message.

If any problems occur with H2cpy not preprocessing a header file in the same way as the C compiler, this can be overcome by using the C compiler to just preprocess the header file and then use the preprocessed file as input to H2cpy.

Unlike COBOL, the C-language data types are not readily portable between environments. For this reason, H2cpy may need to be run more than once if you need to interface to the same library on different machines or operating systems.

H2cpy ignores the IBM C type _Packed rather than generating one-byte alignment for that structure or union. You will have to remove any filler items manually as necessary.
Parent topic: Translating Statements


Overview - H2cpy Messages

H2cpy generates the following three types of message:

  • Information

    Information messages tell you what is happening, and are self-explanatory, so are not documented here.

  • Warning

    Warning messages mean that the translated code will not cause an error when compiled, but it might not produce the results you expect.

  • Error

    Error messages mean there is something wrong, and the code will not compile correctly. They can be:

    • command line errors
    • invalid C source
Note: H2cpy can also produce several internal error messages. These are flagged as internal messages, and are generated if the C header file does not contain valid C code. You should not see these messges during normal operation. If you do receive such a message, please check that your C header file only contains valid ANSI C source code. If it does then contact your Technical Support representative.
  • Warning Messages
    Warning messages are always preceded by an asterisk (*). They indicate that H2cpy has found some unusual C source which it cannot process for some reason and therefore ignores it.
  • Error Messages - Command Line Errors
    Each of these messages mean that the command line given to H2cpy is invalid and translation has not taken place. The error must be corrected and H2cpy run again. Here are some of the most common messages:
  • Error Messages - Invalid C Source
    Each of these messages mean that the C header file given as input to H2cpy is invalid and contains C source that does not conform to the ANSI specification. Translation has not taken place.
Parent topic: Header-to-COPY Utility


Warning Messages

Warning messages are always preceded by an asterisk (*). They indicate that H2cpy has found some unusual C source which it cannot process for some reason and therefore ignores it.

The ignored C source does not directly affect the generation or use of the COBOL copyfile but might possibly affect it indirectly or indicate that the C header is incorrect. Here are some of the most common warning messages that H2cpy can generate:

  • * Warning, other return already defined for: name
  • * Warning, float has been evaluated as zero
  • * Warning, expression buffer overflow - ignored
  • * Warning, macro too long, ignored: name
  • * Warning, macro has too many parameters
  • * Warning, macro parameters too long - ignored
  • * Warning, neither whitespace nor ( after #define. Ignoring the line.
  • *Warning, redefinition ignored for #define
  • * Warning, struct/union 4 bytes (or 8) and passed by value cannot be directly accessed from COBOL
Parent topic: Overview - H2cpy Messages


* Warning, other return already defined for: name

A declaration for function name has been encountered in which the returned data type does not agree with a previous function prototype. The new declaration is ignored.

Parent topic: Warning Messages


* Warning, float has been evaluated as zero

A floating point literal has been encountered within a numeric expression. In evaluating the expression it has been replaced with the value zero.

Parent topic: Warning Messages


* Warning, expression buffer overflow - ignored

A numeric expression has been encountered that is too large and complex for H2cpy to handle. It is ignored. You should check the C source to ensure the expression is not used within a C definition that requires translation into COBOL.

Parent topic: Warning Messages


* Warning, macro too long, ignored: name

A definition for the macro name has been encountered that extends over several lines and is too large for H2cpy to handle. It is ignored. Generally it will not be referenced again within the header file and so will not affect the translation to COBOL.

Parent topic: Warning Messages


* Warning, macro has too many parameters

A macro definition has been encountered that specifies many too parameters. It is ignored. Generally it will not be referenced again within the header file and so will not affect the translation to COBOL.

Parent topic: Warning Messages


* Warning, macro parameters too long - ignored

A macro definition has been encountered that specifies a very large parameter. The macro is ignored. Generally it will not be referenced again within the header file and so will not affect the translation to COBOL.

Parent topic: Warning Messages


* Warning, neither whitespace nor ( after #define. Ignoring the line.

The C header file does not conform to the ANSI C specification as shown by an illegal use of #define. The offending line is ignored. Correct the C header file so that it conforms to ANSI C before using any translated COBOL code.

Parent topic: Warning Messages


*Warning, redefinition ignored for #define

The C header file does not conform to the ANSI C specification as shown by an illegal use of #define to define a macro a second time in a non-identical way. The offending line is ignored. Correct the C header file so that it conforms to ANSI C before using any translated COBOL code.

Parent topic: Warning Messages


* Warning, struct/union 4 bytes (or 8) and passed by value cannot be directly accessed from COBOL

On 32-bit systems, C allows data items greater than four bytes to be passed by value but the effects at run time are implementor dependent and so the items cannot be directly accessed from COBOL. This is considered by C programmers to be bad programming practice and indicates that the C header file should be modified. On 64-bit systems, the limit is eight bytes rather than four.

Parent topic: Warning Messages


Error Messages - Command Line Errors

Each of these messages mean that the command line given to H2cpy is invalid and translation has not taken place. The error must be corrected and H2cpy run again. Here are some of the most common messages:
  • Error, command line too long
  • Error, no input C header file given
  • Error, too many input filenames
  • Error, macro name already defined
  • Error, exceeded max number of include directories, max=14
  • Error, unknown C type: name
  • Error, no C type alignment value
  • Error, no C type size value
  • Error, no call convention value provided
  • Error, unknown environment (not 16 or 32)
  • Error, unknown option - flag
Parent topic: Overview - H2cpy Messages


Error, command line too long

You have specified too much on the command line. Specify header filenames and macro declarations in a small C header file using #include "filename" and #define declaredname instead of putting filename or the -D declaredname option on the command line.

Parent topic: Error Messages - Command Line Errors


Error, no input C header file given

You forgot to name the input header file.

Parent topic: Error Messages - Command Line Errors


Error, too many input filenames

You have specified too many filenames on the command line. Create a C header and use #include for each filename.

Parent topic: Error Messages - Command Line Errors


Error, macro name already defined

You have given the same name in two -D options.

Parent topic: Error Messages - Command Line Errors


Error, exceeded max number of include directories, max=14

You have specified a -I option that causes the include search list to overflow. Reduce the number of -I options specified or the number of directories specified in the INCLUDE environment variable.

Parent topic: Error Messages - Command Line Errors


Error, unknown C type: name

You have given an incorrect parameter in a -a or -s option.

Parent topic: Error Messages - Command Line Errors


Error, no C type alignment value

You have given an incorrect parameter in a -a option.

Parent topic: Error Messages - Command Line Errors


Error, no C type size value

You have given an incorrect parameter in a -s option.

Parent topic: Error Messages - Command Line Errors


Error, no call convention value provided

You have given an incorrect parameter in the -F option.

Parent topic: Error Messages - Command Line Errors


Error, unknown environment (not 16 or 32)

You have given an incorrect parameter in a -e option.

Parent topic: Error Messages - Command Line Errors


Error, unknown option - flag

You have specified an incorrect flag letter.

Parent topic: Error Messages - Command Line Errors


Error Messages - Invalid C Source

Each of these messages mean that the C header file given as input to H2cpy is invalid and contains C source that does not conform to the ANSI specification. Translation has not taken place.

You must modify the header file so that it contains only valid ANSI C before attempting to use H2cpy to translate it to COBOL. You must use C development tools with the correct C dialect checking enabled to determine the exact nature of the error. Here are some of the most common messages:

  • Error, type expected, found name: name
  • Error, type expected
  • Error, typedef found at inner level; check brackets
  • Unexpected token token
  • Error, type expected
  • Error, type expected, found name
  • Error, no unique typedef name!
  • Error, already declared this name
  • Error, undeclared enum name
  • Error, already defined name: name
  • Error, already defined struct/union as: name
  • Error, other params already defined for : name
  • Error, declaration buffer overflow
  • Error, no unique declarator name!
  • Error, no unique parameter name!
  • Error, invalid C code (missing token)
  • Error, too many digits for 4 bytes in name
Parent topic: Overview - H2cpy Messages


Error, type expected, found name: name

Parent topic: Error Messages - Invalid C Source


Error, type expected

Parent topic: Error Messages - Invalid C Source


Error, typedef found at inner level; check brackets

Parent topic: Error Messages - Invalid C Source


Unexpected token token

Parent topic: Error Messages - Invalid C Source


Error, type expected, found name

Parent topic: Error Messages - Invalid C Source


Error, no unique typedef name!

Parent topic: Error Messages - Invalid C Source


Error, already declared this name

Parent topic: Error Messages - Invalid C Source


Error, undeclared enum name

Parent topic: Error Messages - Invalid C Source


Error, already defined name: name

Parent topic: Error Messages - Invalid C Source


Error, already defined struct/union as: name

Parent topic: Error Messages - Invalid C Source


Error, other params already defined for : name

Parent topic: Error Messages - Invalid C Source


Error, declaration buffer overflow

Parent topic: Error Messages - Invalid C Source


Error, no unique declarator name!

Parent topic: Error Messages - Invalid C Source


Error, no unique parameter name!

Parent topic: Error Messages - Invalid C Source


Error, invalid C code (missing token)

Parent topic: Error Messages - Invalid C Source


Error, too many digits for 4 bytes in name

Parent topic: Error Messages - Invalid C Source


Error Messages when Calling Non-COBOL Programs

When calling non-COBOL programs, the following Run-time system error messages might be returned:

114  Attempt to access item beyond bounds of memory
115  Unexpected signal

Where C and COBOL modules are linked, these error messages are usually due to an error in the C code which causes a hardware interrupt for such conditions as segmentation violation. If you do receive these RTS errors, carefully check the C source routines using the system debugger. Pay particular attention to the format and byte order of parameters passed between the COBOL and C modules.

Parent topic: Mixed Language Programming
Related information
Mixed Language Programming


Signal Handling

You can use signal handling in your application, especially if you are mixing COBOL and C in your application.
  • Signal Handling Overview
  • Posting Signal Handlers
  • Writing Signal Handlers
  • More than One Handler for the Same Signal
  • Converting Signal Handlers Written for the signal() Function
  • Third Party Software that Uses Signals
Parent topic: Mixed Language Programming


Signal Handling Overview

The run-time system sets up default signal handlers for all signals whose operating system default action is to cause termination. These default handlers make sure that the COBOL system is properly cleaned up before terminating. Hence, any open files are closed (to prevent file corruption), the PC is reset to a sane state, user posted exit and error procedures are executed, and so on.

You can complement or override the signal handling used by the run-time system by using the following routines:

  • cobpostsighandler()
  • cobremovesighandler()

These routines allow multiple handlers for each signal and enable you to prioritize use of these handlers. You can use them from inside a C program only, not least because you need the C library include file <signal.h> for the signal values, which vary between platforms.

Use these routines instead of the operating system signal calls, (signal() and so on) which provide only the ability to post a single signal handler for each call and so often prevent multiple applications being able to work together reliably.

For example, if you use one of the C library signal calls to post a signal handler before invoking a COBOL program, your signal handler might be overridden. Whereas, if you use one of the C library signal calls after invoking a COBOL program, the default run-time system handler, additional COBOL functionality and user-posted signal handlers are all overridden, causing unexpected results.

Parent topic: Signal Handling
Related reference
signal_regime
cobremovesighandler
cobpostsighandler
cobget
cobput
cobpostsighandler
cobremovesighandler
Related information
Converting Signal Handlers Written for the signal() Function
Posting Signal Handlers
Writing Signal Handlers
More than One Handler for the Same Signal
Third Party Software that Uses Signals
Example of Posting a Signal Handler
Passing Data between C and COBOL
Interfacing with C Programs


Posting Signal Handlers

You use the cobpostsighandler() routine to post signal handlers.

The run-time system also uses the cobpostsighandler() routine to post all of its signal handling. Default handlers are posted for all signals whose operating system default action causes termination. The default handlers either make sure that the COBOL system has been cleaned up before terminating, or cause the signal to be ignored. These default handlers assume that the signals were generated by the operating system due to a serious error or that a signal has been unexpectedly raised. Hence, they usually produce a run-time system message, such as 114 or 115.

If the same handler is posted twice at the same priority, and neither of them is removed using the cobremovesighandler() routine, the handler is executed twice (assuming the handler, and all handlers executed in between, do not return a value of zero).

If you try to post the same signal handler for the same signal at the same priority twice and the first has not been removed using cobremovesighandler(), then cobpostsighandler() returns the handle for the old handler and does not post a new one.

If two different handlers are posted with the same priority, the last one posted is executed first.

Once you have posted a handler, you do not need to repost it. The handler is called each time that signal is received (assuming that the first receipt of the signal does not cause termination). If you want to execute your handler only once, you must remove it, using the cobremovesighandler() routine, in your signal handler.

While a signal handler is processing a signal, the signal is blocked. This prevents recursion if the same signal is received in rapid succession.

A signal handler must return normally. That is, you must not use any other function that terminates a signal handler function, such as longjmp() or coblongjmp(), and you must use the C syntax to return a value, as follows:

return(num);

If you do use another function to return, the signal remains blocked, preventing any further signals from being processed.

When the run-time system receives a signal it calls the handler posted with the highest priority for that signal. Your handler should take any appropriate action (such as setting a flag to be acted on later) and then return. If the handler returns a non-zero value, the run-time system calls the handler with the next highest priority for that signal. If the signal handler returns zero, the run-time system does nto call any further signal handlers.

The run-time system posts its default signal handlers with priority 127. So, to override them, or to process your signal handler before them, post your handler with priority 128. Use a priority of 126 (or less) if you want to make sure that your handler is processed after the default run-time system handler (if the default run-time system handler does not exit).

The run-time system provides various functionality using signal handlers. These handlers are posted with a priority in the range of 129 to 139.

Parent topic: Signal Handling
Related reference
cobremovesighandler
cobpostsighandler
Related information
Converting Signal Handlers Written for the signal() Function
Signal Handling Overview
Writing Signal Handlers
More than One Handler for the Same Signal
Third Party Software that Uses Signals
Example of Posting a Signal Handler


Writing Signal Handlers

A signal handler should do very little. A signal can be generated at any time so the routine that was being executed could be in an "unsafe" state (eg. in the middle of modifying global variables) and so trying to execute it in your signal handler could cause problems. The routine being executed could be a C library routine such as malloc().

There is a small subset of C library routines that are safe to call from signal handlers. Do not try to call any other C library routines, or any COBOL routines, from your signal handler. See your system documentation for more information on the safe C library routines.

Some signals are generated by the operating system when a serious error has occurred. Catching these signals can cause unexpected and potentially dangerous results. You should not catch any of the following signals:

  • SIGABRT
  • SIGBUS
  • SIGEMT
  • SIGFPE
  • SIGILL
  • SIGIOT
  • SIGSEGV
  • SIGSYS
  • SIGTRA

Preventing the run-time system from processing certain signals can break some run-time system functionality. If you catch any of these signals (with a priority of 140 or more), your signal handler must return a non-zero value so that the run-time system's handler is also executed. The signals concerned include:

  • SIGCHLD
  • SIGCONT
  • SIGPIPE
  • SIGTSTP
  • SIGTTIN
  • SIGTTOU
  • SIGUSR1
  • SIGUSR2
  • SIGVTALRM
  • SIGWINCH
Note: We reserve the right to change our default signal handlers or use extra signals in the future.

For an example, see Example of Posting a Signal Handler.

Parent topic: Signal Handling
Related reference
cobremovesighandler
cobpostsighandler
Related information
Converting Signal Handlers Written for the signal() Function
Signal Handling Overview
Posting Signal Handlers
More than One Handler for the Same Signal
Third Party Software that Uses Signals
Example of Posting a Signal Handler


More than One Handler for the Same Signal

The cobpostsighandler() routine enables two or more handlers to be posted for the same signal. When that signal is generated by the operating system (such as a SIGINT generated when the interrupt key is pressed), each handler can take appropriate action and then let other handlers be executed (by returning a non-zero value). Alternatively, they can decide to make the signal "ignored" by returning a value of zero to prevent other handlers from being executed. However, so that your handler can work with other handlers for the same signal, a handler of priority 140 (or more) should return non-zero to let other handlers have the opportunity to also be notified. A handler of priority 128 can return zero if you do not want the run-time system default action to be executed (which may cause termination).

When you raise a signal (such as by using CTRL+C to raise a SIGINT signal, or when raising a signal to a different run-unit or application), then it is probable that only your signal handler wants to be called and other posted signal handlers are not expecting the signal. Hence, in this case, you should set a global resource before raising the signal and then check that resource in your signal handler. If the resource is set (as expected), then the signal was raised by you, so you can take the appropriate action and return zero to prevent other handlers from being unexpectedly called. If the resource is unset, then someone else (or something else, such as the operating system) raised the signal and so you can take no action and should let other handlers execute by returning a non-zero value.

Examples of global resources are global variables (if in the same run unit), shared memory, pipes, files, and so on. Hence, in the above example, we could have set a global variable before raising the alarm() signal. We would then need to check the global variable in the signal handler, mysigcatch(). If it was set, we would carry out our action, reset the variable and return zero. However, if the global variable had not been set, then some other code is likely to have raised the signal. Hence, we would not want to carry out our action and would instead need to return a non-zero value immediately. This allows the appropriate action to be taken in some other handler.

Parent topic: Signal Handling
Related reference
cobremovesighandler
cobpostsighandler
Related information
Converting Signal Handlers Written for the signal() Function
Signal Handling Overview
Posting Signal Handlers
Writing Signal Handlers
Third Party Software that Uses Signals
Example of Posting a Signal Handler


Converting Signal Handlers Written for the signal() Function

If you have any signal handlers that are posted using a C library signal call, such as signal(), change them to use the cobpostsighandler() routine. This is so that your handler and any default run-time system handler, additional COBOL functionality and user-posted signal handlers can all co-exist without one overriding the other, causing unexpected results.

The cobpostsighandler() routine interface is very similar to the signal() interface. The two parameters you pass to signal() are also passed to the cobpostsighandler() routine, plus a priority.

The differences between signal() and the cobpostsighandler() routine are:

  • The return value from signal() is the previous signal handler that was posted for the signal. This is returned because signal() allows only one handler per signal. The cobpostsighandler() routine allows multiple handlers per signal.

    The return value from cobpostsighandler() is either a pointer or NULL. You use this pointer to remove your handler later using cobremovesighandler(). If the return value is NULL, the handler was not posted for the signal.

  • A signal handler function that you post using cobpostsighandler() needs to return an integer value, whereas a signal handler function that you install using signal() needs to return no value.
  • A signal handler posted using C library signal calls can be terminated by functions such as longjmp() and siglongjmp(), but a signal handler posted using the cobpostsighandler() routine cannot be terminated by these routines. If you try to do this, the signal is blocked, and further signals cannot be processed.
  • A signal handler function posted using signal() needs to repost itself, using another signal() call, if it wants to catch subsequent signals. This is because the operating system resets the signal to the operating system default handler before the signal handler function is called.

    By contrast, you do not need to repost a handler that you posted using cobpostsighandler() routine; it stays posted. If you want your handler to be executed only once, remove it using the cobremovesighandler() routine.

Parent topic: Signal Handling
Related reference
cobremovesighandler
cobpostsighandler
Related information
Signal Handling Overview
Posting Signal Handlers
Writing Signal Handlers
More than One Handler for the Same Signal
Converting Signal Handlers Written for the signal() Function
Third Party Software that Uses Signals
Example of Posting a Signal Handler


Third Party Software that Uses Signals

If you are using third party software that posts a signal handler using a C library signal routine, such as signal() or sigaction(), unexpected results may occur. For example, if the third party software posts its handler before COBOL has been invoked, then when COBOL is invoked the third party's handler might be overridden by a run-time system or COBOL handler. If the third party subsequently raises a signal, then a 115 error may occur.

To overcome this, you can use the run-time tunable signal_regime. This tunable prevents handlers from being posted for the specified signal if a signal handler is posted before the first COBOL invocation.

If handlers are prevented from being posted for a signal, due to this tunable, the cobpostsighandler() routine returns NULL. Hence, the default run-time system handlers and any additional COBOL functionality achieved using the signal is not available. It also means that you should check the value returned from any cobpostsighandler() routine calls for NULL.

We recommend that you use the signal_regime tunable only with third party software. You should always use the cobpostsighandler() routine in your own code.

Parent topic: Signal Handling
Related reference
signal_regime
cobremovesighandler
cobpostsighandler
cobpostsighandler
cobremovesighandler
Related information
Converting Signal Handlers Written for the signal() Function
Signal Handling Overview
Posting Signal Handlers
Writing Signal Handlers
More than One Handler for the Same Signal
Example of Posting a Signal Handler


Examples of Mixed Language Programming

  • Example of Calling C functions from COBOL
  • Example of Posting a Signal Handler
Parent topic: Mixed Language Programming


Example of Calling C functions from COBOL

The following example shows how C functions can be accessed from a COBOL program:

$set rtncode-size"4"
 working-storage section.
 01 str.
     03 str-text    pic x(10).
     03 filler      pic x  value x"00".
* Null terminate string for C function
 01 counter  pic 9(8) comp-5  value zero.

 procedure division.
 call-c section.
     call "cfunc" using str, counter
     if return-code not = zero
* RETURN-CODE set from return () in C

         display "ERROR"
     else
         display "OK"
     end-if
     stop run.
------------------------------------------------

cfunc  (st, c)
char  *st;
int   *c;
{
   ...
   return(0);
}
Parent topic: Examples of Mixed Language Programming


Example of Posting a Signal Handler

The following example illustrates posting a signal handler for the SIGABRT signal:

#include <stdio.h>
#include <signal.h>
#include "cobtypes.h"
#include "cobsignal.h"
#include "cobmain.h"

int
mysigcatch(int sig, cobsiginfo_t * mf_info)
{
     printf("In signal handler for sig %d\n", sig);
     return 0;  /* Do not process any further handlers. */
}

void
mysigexit(cobsigtype_t sighand)
{
    printf("Cancelling handler\n");
    cobremovesighandler(sighand);       /* Remove the handler. */
}

int
main(int argc, char *argv[])
{
    cobsigtype_t sighandle;

    cobinit();

    sighandle = cobpostsighandler(SIGABRT, 128, mysigcatch);
    if(sighandle)
    {
        /* Call a cobol program using cobfunc function. */
        cobfunc("cobolprog", argc, argv);

        raise(SIGABRT); /* Raise the signal. */
        mysigexit(sighandle);
    }

    cobexit(0); /* Cobexit - close down COBOL run-time environment. */
}
Parent topic: Examples of Mixed Language Programming
Related reference
cobremovesighandler
cobpostsighandler
cobpostsighandler
cobremovesighandler
Related information
Converting Signal Handlers Written for the signal() Function
Signal Handling Overview
Posting Signal Handlers
Writing Signal Handlers
More than One Handler for the Same Signal
Third Party Software that Uses Signals


Using COBOL and XML together

There are a number of ways for you to utilize COBOL and XML together in Visual COBOL:

  • XML Extensions
    Use XML Extensions to import and export XML documents to and from COBOL working storage. XML Extensions also has support for XSLT stylesheets, allowing you to apply XSLT transformations to the XML document during import, export, or a transformation from one XML document to another. Further support is provided for testing whether a document is well-formed (syntactically correct) or valid with respect to a provided schema document.
  • XML Syntax Extensions
    Use XML Syntax Extensions to import and export XML documents to and from COBOL working storage.
  • Generating COBOL Structures with XML Syntax from the Command Line
    From the command line, use the cbl2xml utility to generate COBOL data structures with XML syntax.
  • XML PARSE
    Visual COBOL fully supports the XML PARSE statement - the IBM syntax for XML handling.
  • Glossary of terms
    A glossary of terms used in an XML and COBOL context.
Parent topic: COBOL Programming


XML Extensions

Use XML Extensions to import and export XML documents to and from COBOL working storage. XML Extensions also has support for XSLT stylesheets, allowing you to apply XSLT transformations to the XML document during import, export, or a transformation from one XML document to another. Further support is provided for testing whether a document is well-formed (syntactically correct) or valid with respect to a provided schema document.

XML is the universal format for structured documents and data on the World Wide Web. Adding "structure" to documents facilitates searching, sorting, or any one of a variety of operations that can be performed on an electronic document.

XML Extensions has many capabilities. The major features support the ability to import and export XML documents to and from COBOL working storage. Specifically, XML Extensions allows data to be imported from an XML document by converting data elements (as necessary) and storing the results into a matching COBOL data structure. Similarly, data is exported from a COBOL data structure by converting the COBOL data elements (as necessary) and storing the results in an XML document.

XML Extensions runs on Microsoft Windows operating systems and selected UNIX platforms. Both 32-bit and 64-bit versions are available.

Note:
  • The term "Windows", "UNIX" and "Linux" in this document refer to any of the platforms supported by Visual COBOL, unless specifically stated - check the Product Availability section on the Micro Focus SupportLine Web site for a full list: http://supportline.microfocus.com/prodavail.aspx
  • XML Extensions makes use of underlying XML parsers from other vendors. On Windows, development uses a specific version and service pack of Microsoft's MSXML, which is included with your installation. Microsoft will occasionally ship updates to a given version and service pack that either enhance security or fix problems. You can monitor their web site for the latest updates, although it might not be advisable to update to a higher version or service pack. Contact Micro Focus SupportLine to ensure that the update is necessary.

    On UNIX or Linux systems, XML Extensions is developed and tested with specific libxml and libxslt shared libraries (*.so files) from the GNOME project for each release. Thus, these may be updated to later versions than the ones provided with Visual COBOL, but again you should contact Micro Focus SupportLine to determine if the later version is necessary and supported.

  • Installation and introduction
  • Getting started with XML Extensions
  • XML Extensions statements reference
  • COBOL considerations
  • XML considerations
  • Appendix A XML Extensions examples
  • Appendix B: XML Extensions sample application programs
  • Appendix C: XML Extensions error messages
Parent topic: Using COBOL and XML together


Installation and introduction

Note: You should have a basic understanding of XML in order to use XML Extensions. Depending on the complexity of your application, you may also need to know about XSLT (Extensible Stylesheet Language Transformations) stylesheets and XML Schema.

This chapter describes the system requirements and installation processes for development and deployment on both Windows and UNIX operating systems. It also provides a general overview of XML Extensions and the benefits it offers to the COBOL programmer.

  • Before you start
  • System requirements
  • XML Extensions components
  • Installing XML Extensions
  • Introducing XML Extensions
Parent topic: XML Extensions


Before you start

Before you follow the instructions for Installing XML Extensions, make sure that your computer configuration meets the following minimum hardware and software requirements for each of the supported architectures, and that your XML Extensions package contains the necessary components for development and deployment.

Note: You may wish to use Microsoft Internet Explorer, version 6 or greater, as a convenient tool for viewing XML documents.
Parent topic: Installation and introduction
Related reference
System requirements
Installing XML Extensions


System requirements

To run XML Extensions, you must have certain hardware and software installed on your computer.

The system requirements for UNIX include the following:

The XML Extensions hardware and software requirements are the same as Visual COBOL. Both 32-bit and 64-bit versions are available.

Shared objects libxml2.so, libxslt.so and libexslt.so, which are provided with Visual COBOL 2.3.1 and later. (A schema processor and an XSLT transformation processor are included in these shared objects.) For 64-bit UNIX, libxml264.so, libxslt64.so and libexslt64.so, which are also provided with Visual COBOL 2.3.1 and later, are required. (Before 2.3.1, these shared objects were statically linked into cobxmlext[64].so.)

Note:
  • The XML parser (libxml) and the XSLT transformation processor (libxslt) from the C libraries for the GNOME project are included in XML Extensions.
  • While the Windows implementation continues to support the use of schema files, the UNIX implementation does not currently support this capability. Schema support in the underlying XML parser (libxml) is still under development.
Parent topic: Installation and introduction


XML Extensions components

The XML Extensions package contains the following components for development and deployment.
  • Development components
  • Deployment components
Parent topic: Installation and introduction


Development components

The XML Extensions development system includes the following:

  • The Visual COBOL compiler. The XMLGEN compiler directive generates an XML representation of the COBOL program's WORKING-STORAGE data items into a model file used by XML Extensions.
  • Deployment files. These files are listed in Deployment.
  • Copybooks (lixmlall.cpy, lixmldef.cpy, lixmldsp.cpy, lixmlrpl.cpy, and lixmltrm.cpy). For more details, see copybooks.
  • Example files. These programs or program fragments illustrate how XML Extensions statements are used. For further information, see Appendix A: XML Extensions examples. The example programs can be found in the XML Extensions example directory Examples.
  • Sample files. These self-contained, working application programs, which include the complete source, can be used in your own applications by modifying or customizing them, as necessary. See Appendix B: XML Extensions sample application programs for more details. The sample application programs can be found in the XML Extensions sample directory Samples.
Parent topic: XML Extensions components
Related reference
Deployment components
Copybooks
Appendix A XML Extensions examples
Appendix B: XML Extensions sample application programs


Deployment components

The XML Extensions deployment system consists of the following files:

  • The XML Extensions COBOL-callable subprogram library (cobxmlext.dll in the 32- or 64-bit bin directory on Windows, and cobxmlext.so or cobxmlext64.so on UNIX). For more information, see XML Extensions Statements Reference.
  • For UNIX with Visual COBOL 2.3.1 and later: the parser and transformation support files libxml2.so, libxslt.so and libexslt.so, or, for 64-bit, libxml264.so, libxslt64.so and libexslt64.so.
Parent topic: XML Extensions components
Related reference
Development components
XML Extensions statements reference
Typical development process example


Installing XML Extensions

XML Extensions is part of and installed with Visual COBOL products. After Visual COBOL is successfully installed XML Extensions is ready for use.

For development, a Visual COBOL system that includes the Visual COBOL compiler is required.

For deployment, a Visual COBOL runtime system, such as COBOL Server, is required.

  • Installing on Windows or UNIX
Parent topic: Installation and introduction


Installing on Windows or UNIX

Simply follow the instructions for installing Visual COBOL onto your system. XML Extensions is installed as part of Visual COBOL.

Parent topic: Installing XML Extensions


Introducing XML Extensions

XML Extensions for Visual COBOL allows Visual COBOL applications to interoperate freely and easily with other applications that use the Extensible Markup Language (XML) standard. To accomplish this, XML Extensions leverages the similarities between the COBOL data model and the XML data model in order to turn COBOL into an "XML engine." Of primary importance to this goal is the ability to import and export XML documents to and from standard COBOL data structures.

Note: A COBOL data structure, as used in this document, is a COBOL data item. In general, it is a group data item, but in some cases, it may be a single elementary data item. The Visual COBOL compiler XMLGEN directive generates an XML-format symbol table into a file called a model file. The XML-format symbol table provides a map between the COBOL data structure specified in an XML Extensions statement and the XML representation of the COBOL data structure. This map can be used to move data in either direction at runtime. Extensible Stylesheet Language Transformations (XSLT) of the XML data representation can be used to match XML element names to COBOL data-names in cases where the names differ.

By allowing standard COBOL data structures to be imported from and exported to XML documents, XML Extensions enables the direct processing and manipulation of XML-based electronic documents by the COBOL application programmer. Furthermore, XML Extensions does this without requiring the application programmer to become thoroughly familiar with the numerous XML-related specifications and the time-consuming process required to emit and consume well-formed XML.

Specifically, an XML document may be imported into a COBOL data structure under COBOL program control using a single, simple COBOL statement, and, similarly, the content of a COBOL data structure may be used to generate an XML document with equal simplicity. XML Extensions' approach handles both simple and extremely complex structures with ease. Individual data elements are automatically converted as needed between their COBOL internal data types and the external coding used by XML. Not only can the transition to and from XML take place when this happens, but powerful transforms, which are coded using XSLT, can be applied at the same time. This powerful mechanism gives XML Extensions the capabilities needed to be useful in a wide range of e-commerce and Web applications.

In order to add this powerful document-handling capability to a COBOL application, the programmer need only describe the information to be received or transmitted to the external components as COBOL data definitions. In many cases, this description will simply be the already-existing data area defined in the COBOL application.

  • What is XML?
  • COBOL as XML
  • XML as COBOL
Parent topic: Installation and introduction


What is XML?

In this document, XML refers to the entire set of specifications and products related to a particular approach to representing structured information in text-based form. Specifically, the World Wide Web Consortium (W3C) has specified a markup-based language called XML. Closely related to HTML, XML was designed to build on what had been learned with that technology. Among other things, XML was designed to be much more generally useful than HTML, while exhibiting the simplest possible expression. HTML is about displaying information. It was designed to display data and to focus on how the data looks. XML, meanwhile, is about describing information. It was designed to describe data and focus on what the data is. Since XML's invention, a constellation of XML-related specifications has been produced and is in progress to leverage the power of this new form of information expression.

For the COBOL programmer, it is best to view XML not as a markup language for text documents, but rather as a text-based encoding of a general abstract data model. It is this data model, and its similarity to COBOL's data model, that yields its power as an adjunct to new and legacy COBOL applications needing to interact with other applications and systems in the most modern way possible.

XML is extremely important to the COBOL programmer for two key reasons. First, it is rapidly becoming the standard way of exchanging information on the Web, and second, the nearly perfect alignment of the COBOL way of manipulating data and the XML information model results in COBOL being arguably the best possible language for expressing business data processing functions in an XML-connected world.

Parent topic: Introducing XML Extensions


COBOL as XML

What does XML look like? Start with the assumption that it is a textual encoding of COBOL data (although this is not quite accurate, it is sufficient for now). Suppose you have the following COBOL definition in the Working-Storage Section:
01 contact.
   10 firstname pic x(10) value "John".
   10 lastname pic x(10) value "Doe".
   10 address.
      20 streetaddress pic x(20) value "1234 Elm Street".
      20 city pic x(20) value "Smallville".
      20 state pic x(2) value "TX".
      20 postalcode pic 9(5) value "78759".
   10 email pic x(20) value "jd@aol.com".

What does this information look like if you simply WRITE it out to a text file? It looks like this:

John Doe 1234 Elm Street Smallville TX78759jd@aol.com

You can see that all the "data" is here, but the "information" is not. If you received this, or tried to read the file and make sense out of it, you would need to know more about the data. Specifically, you would have to know how it is structured and the sizes of the fields. It would be helpful to know how the author named the various fields as well, since that would probably give you a clue as to the content.

This is not a new problem; it is one that COBOL programmers (as well as other application programmers) have had to deal with on an ad hoc basis since the beginning of the computer age. But now, XML gives us a way to encode all of the information in a generally understandable way.

Here is how this information would be displayed in an XML document:

<contact>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <address>
      <streetaddress>1234 Elm Street</streetaddress>
      <city>Smallville</city>
      <state>TX</state>
      <postalcode>78759</postalcode>
   </address>
   <email>jd@aol.com</email>
</contact>

In XML, the COBOL group-level item is coded in what is called an "element." Elements have names, and they contain both text and other elements. As you can see, an XML element corresponds to a COBOL data item. In this case, the 01-level item "contact" becomes the <contact> element, coded as a start "tag" ("<contact>") and an end tag (" </contact>") with everything in between representing its "content." In this case, the <contact> element has as its content the elements <firstname>, <lastname>, <address>, and <email>. This corresponds precisely to the COBOL Data Division declaration for "contact." Similarly, the 10-level group item, "address", becomes the element <address>, made up of the elements <streetaddress>, <city>, <state>, and <postalcode>. Each of the COBOL elementary items is coded with text content alone. Notice that in the XML form, much of the semantic information is missing from the raw COBOL output form of the data. As a bonus, you no longer have the extraneous trailing spaces in the COBOL elementary items, so they are removed. In other words, the XML version of this record contains both the data itself and the structure of the data.

Now, what if the COBOL data had looked like the following:

01 contact.
   10 email pic x(20)
   10 firstname pic x(10).
   10 lastname pic x(10).
   10 address.
      20 city pic x(20).
      20 state pic x(2).
      20 postalcode pic 9(5).
      20 streetaddresslines pic 9.
      20 streetaddresses.
         30 streetaddresses occurs 1 to 9 times
             depending on streetaddresslines pic x(20).

Two things have changed in this example: the initial values have been removed and there can now be up to nine "streetaddress" items. This is much more similar to what you might expect in a real application. After the application code sets the values of the various items from the Procedure Division, the XML coding of the result might look like this:

<contact>
    <email>bs@aol.com</email>
    <firstname>Betty</firstname>
    <lastname>Smith</lastname>
    <address>
          <city>Galesburg</city>
          <state>IL</state>
          <postalcode>61401</postalcode>
          <streetaddresslines>3</streetaddresslines>
          <streetaddresses>
           <streetaddress>Knox College</streetaddress>
           <streetaddress>Campus Box 9999</streetaddress>
           <streetaddress>2 E. South St.</streetaddress>
          </streetaddresses>
    </address>
</contact>

Notice the repeating item "streetaddress" has become three <streetaddress> elements. In this example, COBOL acts as an XML programming language, providing both the structure (schema) of the data and the data itself.

Even though these examples are very simple, they illustrate how powerful the compatibility between the COBOL data model and the XML information model can be. COBOL structures of arbitrary complexity have a straightforward XML representation. There are, it turns out, some things that you can specify in a COBOL data definition that cannot be coded as XML, but these can easily be avoided if you are programming your application for XML.

Parent topic: Introducing XML Extensions


XML as COBOL

In the previous cases, you saw how structured COBOL data could be coded as an XML document. In this section, you will examine how an arbitrary XML document can be represented as a COBOL structure. This requires that you look at some other aspects of the XML information model that are not needed to represent COBOL structures, but might be present in XML, nonetheless.

So far, you have seen that XML has elements and text. Although, these are the primary means of representing data in XML documents, there are some other ways of representing and structuring data in XML. Suppose you have the following XML document:

<contact type="student">
    <firstname>Betty</firstname>
    <lastname>Smith</lastname>
    <address form="US">
           <streetaddresses>
                  <streetaddress>Knox College</streetaddress>
                  <streetaddress>Campus Box 9999</streetaddress>
                  <streetaddress>2 E. South St.</streetaddress>
           </streetaddresses>
           <city>Galesburg</city>
           <state>IL</state>
           <postalcode zipplus4="N">61401</postalcode>
    </address>
    <email>bs@aol.com</email>
</contact>

In the example document shown here is now a new kind of data, known as an "attribute" in XML. Notice that the <contact> element tag has what appears to be some kind of parameter named "type." This is, in fact, an attribute whose value is set to the text string "student." In XML, attributes are another way of coding element content, but in a way that does not affect the text content of the element itself. In other words, attributes are "out-of-band" data associated with an element. This concept has no parallel in standard COBOL. In COBOL, all data associated with a data item is part of the COBOL record content. This means that if you are to capture all of the content of an XML document, you must have a way to capture and store attributes.

You do this with the help of an important XML tool called an external XSLT stylesheet. For now, assume that an XSLT stylesheet can transform an XML document into any desired alternative XML document. If this is true (and it is), you must code the incoming attributes as something that has a direct COBOL counterpart. This would be as a data item represented as a text element in XML.

The example document, after external XSLT stylesheet transformation, might look like this:

<contact>
    <email>bs@aol.com</email>
    <attr-type>student</attr-type>
       <firstname>Betty</firstname>
       <lastname>Smith</lastname>
       <address>
              <attr-form>US</attr-form>
              <city>Galesburg</city>
              <state>IL</state>
              <postalcodegroup>
                     <attr-zipplus4>N</attr-zipplus4>
                     <postalcode>61401</postalcode>
              </postalcodegroup>
    <streetaddresslines>3</streetaddresslines>
              <streetaddresses>
                     <streetaddress>Knox College</streetaddress>
                     <streetaddress>Campus Box 9999</streetaddress>
                     <streetaddress>2 E. South St.</streetaddress>
               </streetaddresses>
       </address>
</contact>

Several things have been changed. The attributes have been turned into elements, but with a special name prefixed by "attr-" and a new element, <streetaddresslines> has been added containing a count of the number of <streetaddress> elements. In the case of <postalcode>, a new element has been added to wrap both the real <postalcode> value, and the new attribute. All of these changes are very easy to make using a simple XSLT stylesheet, and you now have a document with a direct equivalent in COBOL:

01 contact.
   10 email pic x(20).
   10 attr-type pic x(7).
   10 firstname pic x(10).
   10 lastname pic x(10).
   10 address.
      20 city pic x(20).
      20 state pic x(2).
      20 postalcodegroup.
         30 attr-zipplus4 pic x.
         30 postalcode pic 9(5).
      20 attr-form pic xx.
      20 streetaddresslines pic 9.
      20 streetaddresses.
         30 streetaddress occurs 1 to 9 times
               depending on streetaddresslines pic x(20).
Parent topic: Introducing XML Extensions


Getting started with XML Extensions

This chapter presents the basic concepts used in XML Extensions by creating an example XML-enabled application. It also discusses how XML Extensions locates files.
  • Overview
  • Model files
  • XMLGEN Compiler directive
  • Typical development process example
  • How XML Extensions locates files
Parent topic: XML Extensions


Overview

Because the COBOL information model can largely be expressed by the XML information model, there is a natural relationship between XML documents and COBOL data structures. Both present similar views of the data; that is, the entire data is visible. You may view the content of a COBOL data record and you may view the text of an XML document. In XML, markup is used both to name and describe the text elements of a document. In COBOL, the data structure itself provides names and descriptions of the elements within a document.

XML Extensions has many capabilities. The major features support the ability to import and export XML documents to and from a COBOL program's Data Division. Note that data may be anywhere in the Data Division. Specifically, XML Extensions allows data to be imported from an XML document by converting data elements, as necessary, and storing the results into a matching COBOL data structure. Similarly, data is exported from a COBOL data structure by converting the COBOL data elements, as necessary, and storing the results in an XML document.

XML Extensions consists of the following main components:

  • The Visual COBOL compiler, using the XMLGEN compiler directive.
  • A COBOL-callable run-time library (cobxmlext.dll in either the 32-bit or 64-bit bin directory on Windows, and cobxmlext.so or cobxmlext64.so on UNIX). This library is used to implement a set of XML Extensions statements specified in a COBOL program that are available to the developer for directing the importing and exporting of COBOL data as XML. For more information, see XML Extensions statements reference.
Parent topic: Getting started with XML Extensions
Related reference
XML Extensions statements reference


Model files

XML Extensions for Visual COBOL employs a model template file to describe the COBOL data structures for export or import operations. Since XML Extensions for Visual COBOL has only the one model file, a reference in this help to 'model template file', 'model file' or 'template file' are all references to this one file.

The model template file is produced by the XMLGEN directive when a COBOL program that uses XML Extensions is compiled. This model file must be distributed with the application for use when the application is run. As produced by the XMLGEN directive, the extension is xml and the base name is the same as the base file-name of the compiled source program. For example, if the compiled program source is in file program01.cbl, the model template file is program01.xml.

Since an application can have multiple COBOL programs in its implementation, the term 'model files' refers to the set of model files produced for the multiple programs in the implementation.

The model template file contains an XML document that describes the COBOL data structures in the compiled application program. The XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE and XML IMPORT TEXT statements have a parameter ModelFileName#DataName that specifies the model file to be used for the statement and, separated by a "#", the DataName to be selected from the model file descriptions of data-names.

Parent topic: Getting started with XML Extensions


XMLGEN Compiler directive

Specifies whether the Compiler should produce an XML model file for either the file section or the working-storage section data items defined in the program.

Syntax:

>>-.--XMLGEN--.------------.---.---><
   |          +-(ws)-------+---|
   |          +-(WS)-------+---|
   |          +-(pathname)-+---|
   |          +-($env-var)--+--|
   |                           |
   +--NOXMLGEN-----------------+

Parameters

none
When you use XMLGEN without any parameters, it generates an XML model file in the project directory, containing a model for file section data items only (no working-storage section data items).
Note: The XML model file must be accessible to the XML extensions run-time environment. To make the file accessible, either add it to the system path, or move it to the directory from which the program is run.
WS and ws
Generate a model that includes working-storage section data items only (no file section data items).
pathname
An absolute or relative path to use as an alternative location for the generated XML model file.
Note: To specify a path that starts with the letters ws or WS, begin the path specification with a slash (/) or a dot slash (./) to prevent XMLGEN from misinterpreting the ws characters as a WS or ws parameter specification.
$env-var
An environment variable set to an absolute or relative path to use as an alternative location for the generated XML model file.

Properties:

Default: | NOXMLGEN
Phase: | Syntax check
$SET: | Any

Comments:

  • XMLGEN produces one XML model file containing either file section data items or working-storage data items depending on whether or not ws or WS is specified. It does not produce both the file section and working-storage section descriptions in one compilation.
  • The XML model output filename is:
    source-name.xml
    where source-name is the prefix of the specified COBOL file.
  • XMLGEN overwrites existing output files.
  • To generate an XML model file with working-storage section data descriptions in an alternative directory, specify the XMLGEN directive twice with the first XMLGEN providing the pathname or $env-var parameter, followed by the second providing the WS or ws parameter. Reversing this order results in an output file in the specified path but with file section data items instead of working-storage data items.

Examples:

To generate an XML model file in the project directory, containing file section data items:

XMLGEN

To generate an XML model file in the c:\users\bob directory, containing file section data items:

XMLGEN(c:\users\bob)

To generate an XML model file in the project directory, containing working-storage data items:

XMLGEN(ws)

To generate an XML model file in the c:\users\bob directory, containing working-storage data items:

XMLGEN(c:\users\bob) XMLGEN(ws)

To generate an XML model file in the directory specified by the XMLPATH environment variable, containing working-storage data items:

XMLGEN($XMLPATH) XMLGEN(ws)
Parent topic: Getting started with XML Extensions


Typical development process example

This section provides an example of how to produce an XML-enabled application.
Note: More examples and information about complete sample application programs can be found in Appendix A: XML Extensions Examples, Appendix B: XML Extensions Sample Application Programs, and in the XML Extensions samples directory, which is found via the Samples Browser (click on the Samples link under your installed Visual COBOL product).

The basic steps to developing an XML-enabled application are as follows:

  1. Design the COBOL Data Structure and Program Logic. Develop a COBOL program, or modify an existing one, using XML Extensions statements.
  2. Compile the Program. Use the Visual COBOL compiler with compiler directive XMLGEN(WS), which, by default, results in the production of the XML-format symbol table.
    Note: On the development machine, a large XML-format symbol table may necessitate an increase in system resources, including the addition of hardware (for example, memory and/or disc space) or system configuration modifications.
  3. Execute the COBOL Program. Test the program and repeat steps 1 and 2, as necessary.
  4. Deploy the Application. Distribute the XML Extensions deployable files.

    These files consist of the XML Extensions library and the underlying XML parser that this library uses. See Deployment Components for details.

There are further sections that describe each of the basic steps involved in the example provided, and they include explanations of how more functionality is added to the program.
  • Design the COBOL data structure and program logic
  • Compile the program
  • Execute the program
  • Making a program skeleton
  • Making a program that exports an XML document
  • Populating the XML document with data values
  • Deploy the application
Parent topic: Getting started with XML Extensions
Related reference
Appendix A XML Extensions examples
Appendix B: XML Extensions sample application programs
Deployment components


Design the COBOL data structure and program logic

The first step is to design a COBOL data structure that describes the data to be placed in a corresponding XML document. The following simple example illustrates this step using typical mailing address information. An adequate program skeleton has been included to allow the program to compile without error.

Identification Division.
Program-Id. Getting-Started.
Data Division.
Working-Storage Section.
01  Customer-Address.
    02  Cust-Name     Pic X(128).
    02  Address-1     Pic X(128).
    02  Address-2     Pic X(128).
    02  Address-3.
        03  City      Pic X(64).
        03  State     Pic X(2).
        03  Zip       Pic 9(5) Binary.

This structure contains only one numeric element: the zip code. For demonstration purposes, it is represented as binary.

Parent topic: Typical development process example
Related information
Compile the program
Execute the program
Making a program skeleton
Making a program that exports an XML document
Populating the XML document with data values
Deploy the application


Compile the program

The generation of an XML-format symbol table is controlled by the XMLGEN compiler directive of the Visual COBOL compiler.

Compile the program with the following command line:

cob getstarted.cbl xmlgen(ws) noobj

Note: If the data structure of interest is defined in the file section of the COBOL program, omit the "ws" parameter in the xmlgen directive.
Parent topic: Typical development process example
Related reference
XMLGEN Compiler directive
Related information
Design the COBOL data structure and program logic
Execute the program
Making a program skeleton
Making a program that exports an XML document
Populating the XML document with data values
Deploy the application


Execute the program

Next, you execute and test the program.

The following sections explain-in several stages-how you can build upon the preceding step by adding increasingly more functionality to the COBOL data structure (designed in step 1 of this example), and then compiling and running the program after each stage.

In the first stage, the original program fragment is developed into a working COBOL program that calls the XML Extensions library. Next, the XML EXPORT FILE statement is used to create an XML document from the content of the COBOL data structure. Finally, the XML document is fully populated with data values. With each iteration, the program is recompiled.

Parent topic: Typical development process example
Related reference
XML EXPORT FILE
Related information
Design the COBOL data structure and program logic
Compile the program
Making a program skeleton
Making a program that exports an XML document
Populating the XML document with data values
Deploy the application


Making a program skeleton

Step 1 started with just a fragment of the program in order to show the COBOL data structure.

The interface to the XML Extensions library, a COBOL-callable subprogram, is simplified by using some COBOL copybooks that perform source text replacement. This means that the developer may use XML Extensions statements, which are much like COBOL statements, rather than writing CALL statements that directly access entry points in the XML Extensions library. The COBOL copybooks also define program variables that are used in conjunction with the XML Extensions statements. The copybook, lixmlall.cpy (or at least the copybooks referenced by lixmlall.cpy), must be copied in the Working-Storage Section of the program in order to use XML Extensions. For more information, see copybooks.

To call the XML Extensions library, add the following lines (shown in bold) to the COBOL program fragment from step 1:

Identification Division.
Program-Id. Getting-Started.
Data Division.
Working-Storage Section.
01  Customer-Address.
    02  Cust-Name     Pic X(128).
    02  Address-1     Pic X(128).
    02  Address-2     Pic X(128).
    02  Address-3.
        03  City      Pic X(64).
        03  State     Pic X(2).
        03  Zip       Pic 9(5) Binary.
Copy "lixmlall.cpy".
Procedure Division.
A.
    XML INITIALIZE.
    If Not XML-OK Go To Z.

< insert COBOL PROCEDURE DIVISION logic here >

Z.
Copy "lixmltrm.cpy".
    GoBack.
Copy "lixmldsp.cpy".
End Program  Getting-Started.

The COPY statement is placed in the Working-Storage Section after the data structure.

The Procedure Division header is entered, followed by the paragraph-name, A.

The XML INITIALIZE statement produces a call to the XML Extensions library. The XML INITIALIZE statement may be thought of as similar to a COBOL OPEN statement.

Termination logic is placed at the end of the program. The paragraph-name, Z. , is used as a GO TO target for error or other termination conditions.

The copybook, lixmltrm.cpy, is used to generate a correct termination sequence. A call to XML TERMINATE (similar to a COBOL CLOSE statement) is in this copybook. If errors are present, the logic in this copybook will perform a procedure defined in the copybook, lixmldsp.cpy, which will display any error messages.

The original program fragment is now a working COBOL program that calls the XML Extension library. Its only function is to open and close the interface to the library.

Compile and run the program from the command line as follows:

cob -i -C 'xmlgen(ws)' -P getstarted.cbl; cobrun getstarted.int

Parent topic: Typical development process example
Related reference
Copybooks
XML INITIALIZE
XML TERMINATE
Related information
Design the COBOL data structure and program logic
Compile the program
Execute the program
Making a program that exports an XML document
Populating the XML document with data values
Deploy the application


Making a program that exports an XML document

The next stage is to create an XML document from the content of a COBOL data structure. To do this, more logic is added to the original COBOL program. The added text is shown in bold.

Identification Division.
Program-Id. Getting-Started.
Data Division.
Working-Storage Section.
01  Customer-Address.
    02  Cust-Name     Pic X(128).
    02  Address-1     Pic X(128).
    02  Address-2     Pic X(128).
    02  Address-3.
        03  City      Pic X(64).
        03  State     Pic X(2).
        03  Zip       Pic 9(5) Value 0 Binary.
Copy "lixmlall.cpy".
Procedure Division.
A.
    XML INITIALIZE.
    If Not XML-OK Go To Z.

     XML EXPORT FILE
         Customer-Address
         "Address"
         "getstarted#customer-address".
     If Not XML-OK Go To Z.

Z.
Copy "lixmltrm.cpy".
    GoBack.
Copy "lixmldsp.cpy".
End Program  Getting-Started.

The XML EXPORT FILE statement is used to create an XML document from the content of a COBOL data structure. This statement has three arguments: the data structure name, the desired filename, and the root name of the model files.

A value of zero is added to the zip code field so that the field has a valid numeric value.

As you would expect, the data structure name is customer-address. Almost all of the XML statements may set an unsuccessful or warning status value; that is, a status value for which the condition-name XML-OK is false following the execution of the XML statement. It is good practice to follow every XML statement with a status test, such as, If Not XML-OK Go To Z.

The program is again compiled and run from the command line as follows:

cobol getstarted.cbl xmlgen(ws) noobj; run getstarted

Parent topic: Typical development process example
Related reference
XML EXPORT FILE
Related information
Design the COBOL data structure and program logic
Compile the program
Execute the program
Making a program skeleton
Populating the XML document with data values
Deploy the application


Populating the XML document with data values

The next stage is to populate the COBOL program with data values. Changes to the program are again shown in bold

Identification Division.
Program-Id. Getting-Started.
Data Division.
Working-Storage Section.
01  Customer-Address.
    02  Cust-Name     Pic X(128).
    02  Address-1     Pic X(128).
    02  Address-2     Pic X(128).
    02  Address-3.
        03  City      Pic X(64).
        03  State     Pic X(2).
        03  Zip       Pic 9(5) Value 0 Binary.
Copy "lixmlall.cpy".
Procedure Division.
A.
    XML INITIALIZE.
    If Not XML-OK Go To Z.

    Move "Micro Focus" to Cust-Name.
    Move "8310 Capital of Texas Highway, North"
        to Address-1.
    Move "Building 2, Suite 100" to Address-2.
    Move "Austin" to City.
    Move "TX" to State.
    Move 78731 to Zip.

     XML EXPORT FILE
         Customer-Address
         "Address"
         "getstarted#customer-address".
     If Not XML-OK Go To Z.

Z.
Copy "lixmltrm.cpy".
    GoBack.
Copy "lixmldsp.cpy".
End Program  Getting-Started.

A series of simple MOVE statements is used to provide content for the data structure.

Again, the program is compiled and run from the command line as follows:

cobol getstarted.cbl xmlgen(ws) noobj; run getstarted

This time the XML document, in file Address.xml, is fully populated with data values, as shown below:

 <customer-address xmlns:xtk="http://www.microfocus.com/xcentrisity/
                             \xml-extensions/symbol-table/">
  <cust-name>Micro Focus</cust-name>
  <address-1>8310 Capital of Texas Highway, North</address-1>
  <address-2>Building 2, Suite 100</address-2>
  <address-3>
   <city>Austin</city>
   <state>TX</state>
   <zip>78731</zip>
  </address-3>
 </customer-address>

On UNIX, the commands are:

cob -i getstarted.cbl -C 'xmlgen(ws)' cobrun getstarted

Parent topic: Typical development process example
Related information
Design the COBOL data structure and program logic
Compile the program
Execute the program
Making a program skeleton
Making a program that exports an XML document
Deploy the application


Deploy the application

The final step is to deploy the application.

Deploy the model files that you generated. Normally, these files are stored in the same location as the COBOL program files.

Parent topic: Typical development process example
Related information
Design the COBOL data structure and program logic
Compile the program
Execute the program
Making a program skeleton
Making a program that exports an XML document
Populating the XML document with data values


How XML Extensions locates files

XML Extensions uses the PATH environment variable to locate executable programs. The Visual COBOL Command Prompt window already has PATH set up properly.

XML Extensions uses the CBL_LOCATE_FILE library routine to locate non-executable files, as explained in Searching for files.

Parent topic: Getting started with XML Extensions
Related reference
Searching for files
File naming conventions
UNIX character encoding
Windows character encoding


XML Extensions statements reference

XML Extensions statements allow you to process, manipulate, and validate XML documents. The statements are contained in the 32- or 64-bit dynamic link library on Windows (cobxmlext.dll) or the shared object on UNIX (cobxmlext.so or cobxmlext64.so) that is callable from Visual COBOL object programs.

On Windows, XML Extensions statements use the Microsoft MSXML 6.0 parser; on UNIX, XML Extensions statements use the XML parser (libxml or libxml264) and the XSLT transformation processor (libxslt or libxslt64) from the C libraries for the GNOME project. For additional information, see Installing XML Extensions and Deployment.

XML Extensions statements are grouped into the following categories:

  • Document Processing Statements. These statements are used to process, manipulate, or validate XML documents.
  • Document Management Statements. These statements are used to copy an XML document from an external file to an internal text string and vice versa.
  • Directory Management Statements. These statements are useful when implementing directory-polling schemes.
  • State Management Statements. These statements are used to control the state or condition of XML Extensions statements.
Note: Each statement contains zero or more positional parameters. These parameters are used to specify such items as the source or destination data item, source or destination XML document, flags, and any model files produced by the XMLGEN compiler directive. In some statements, trailing positional parameters are optional and may be omitted, as specified in the statement descriptions in this chapter.
  • Memory management with XML Extensions
  • Searching for files
  • Document processing statements
  • Document management statements
  • Directory management statements
  • State management statements
Parent topic: XML Extensions
Related reference
Deployment components
Overview


Memory management with XML Extensions

At execution time, XML Extensions allocates memory and caches stylesheets and other artifacts of the XML document handling process. This is a standard technique to enhance performance, trading reduced execution time for additional memory usage. However, it is possible for a long running program that processes a substantial number of different XML documents to cause enough additional memory allocation that performance degrades, typically due to virtual memory swapping. As an example, a program might sit in a loop, waiting for an XML document to arrive in a directory; see the example for XML FIND FILE.

The program may use the XML TERMINATE statement to cause all memory allocated by XML Extensions (with the exception of the document returned by the XML GET TEXT , XML EXPORT TEXT and XML TRANSFORM TEXT statements) for the run unit to be released. However, the XML INITIALIZE statement and any other XML Extensions statements that control optional behavior (for example, XML ENABLE ALL-OCCURRENCES) must be called to re-establish the XML environment before additional XML documents are processed.

Alternatively, you can use the XML FLUSH CACHE statement to flush cached documents, and the XML DISABLE CACHE statement to prevent caching of documents. These ways of managing memory usage are less sweeping than the XML TERMINATE statement.

The XML CLEAR XSL-PARAMETERS will free any memory used for parameter name/value pairs that have been set, and will not disturb caching or other memory usage. The XML FREE TEXT statement will free memory allocated by the XML EXPORT TEXT or the XML TRANSFORM TEXT statements.

Parent topic: XML Extensions statements reference
Related reference
State management statements
XML FIND FILE
XML TERMINATE
XML GET TEXT
XML IMPORT TEXT
XML INITIALIZE
XML ENABLE ALL-OCCURRENCES


Searching for files

Model files are the XML documents generated by the XMLGEN compiler directive. XML Extensions uses model files only as input files. When XML Extensions references a model file, the appropriate predetermined extension is added, regardless of the presence or lack of an extension on the model file parameter supplied by the COBOL program.

XML Extensions uses the CBL_LOCATE_FILE library routine to locate a model file (with the appropriate extension added) except when:

  • the model filename contains a directory separator character (such as "\" on Windows);
  • the file exists; or
  • the filename is a URL (that is, the name begins with http://, https://, or "file://").
Parent topic: XML Extensions statements reference
Related reference
External XSLT Stylesheet File Naming External XSLT stylesheet file naming conventions
CBL LOCATE FILE


Document processing statements

Document processing statements are used to process, manipulate, or validate XML documents. They are grouped by function as follows:

  • Export statements. XML EXPORT FILE and XML EXPORT TEXT are available to convert the content of a COBOL data item to an XML document that may be represented as an external file or an internal text string.
  • Import statements. XML IMPORT FILE and XML IMPORT TEXT are available to convert the content of an XML document-either an external file or an internal text string-to a COBOL data item.
  • Test and validation statements. XML TEST WELLFORMED-FILE, XML TEST WELLFORMED-TEXT, XML VALIDATE FILE, and XML VALIDATE TEXT are available to verify that an XML document-either an external file or an internal text string-is well-formed or valid.
  • Transformation statements. XML TRANSFORM FILE and XML TRANSFORM TEXT transform an XML document in an external file or internal text into a new external file or internal text by applying an XSLT stylesheet. The resulting file or internal text may have almost any form, including XML, HTML, PDF, RTF, and so forth.
  • XML EXPORT FILE
  • XML EXPORT TEXT
  • XML IMPORT FILE
  • XML IMPORT TEXT
  • XML TEST WELLFORMED-FILE
  • XML TEST WELLFORMED-TEXT
  • XML TRANSFORM FILE
  • XML TRANSFORM TEXT
  • XML VALIDATE FILE
  • XML VALIDATE TEXT
Parent topic: XML Extensions statements reference


XML EXPORT FILE

This statement has the following parameters:

Parameter | Description
DataItem | An identifier of the COBOL data item that contains the data to be exported. This is not necessarily the same data item as the one that produced the model template file description of the data to be exported, but must be at least as large as so described. The identifier may refer to a linkage data item that has been passed to a subprogram that does the export. The identifier may be that of a table element specified with any necessary subscripting or indexing when the application has a table of export areas.
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file that will receive the exported XML document.
ModelFileName#DataName A nonnumeric literal or an identifier of an alphanumeric data item, the value of which may be any of the following:
  • The name of the data structure. If the # (hash) character is missing, it is assumed that the hash character was intended to be placed at the beginning of the parameter (as the specified name is a data item name).

    Everything to the left of the "#" character is the filename. Everything to the right is the data structure name. Either component is optional; that is, model names of "file#", "file", "#data", "#" and "" are allowed. If the filename is omitted and a default has not been provided from the XML COBOL FILE-NAME statement|tag=XML COBOL FILE-NAME, then the current program is assumed. If the data name is not found, then calling programs are used (in order of the call stack).

    The data name must be found in the model template file; its description must not describe an area larger than the DataItem specified by the first parameter of the statement; otherwise an error 74 may happen during program execution. If the data name is omitted in this parameter, then the entire program's data definitions are used as determined by the model template file.

    If a hash "#" character is missing from the ModelFileName parameter, one will be assumed to be present at the beginning (the ModelFileName is assumed to be a data name).

    Furthermore, a hierarchical specification of data names may be used; that is, "a//b//c" is valid. It has the same meaning as the COBOL specification of "C of B of A". Either data names or program names may be specified in the data name hierarchy; that is, A and B could be the names of programs, assuming B is a program contained in A.

  • The name of the XML file produced by the XMLGEN compiler directive that describe the COBOL data item. For more information, see Model Files.
[StyleSheetName] | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the generated XML document before it is stored.

Description

The XML EXPORT FILE statement exports the content of the COBOL data item indicated by the DataItem parameter. The content of the data item is converted to an XML document using one or more files indicated by the ModelFileName#DataName parameter. The output of this conversion is to the file specified by the DocumentName parameter. If the optional StyleSheetName parameter is present, the external XSLT stylesheet is used to transform the document after it has been generated but before it is stored in the data file.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Examples

Without an External XSLT Stylesheet:

XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT"
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet:

XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z
Parent topic: Document processing statements
Related reference
State management statements
Execute the program
Making a program that exports an XML document
Model files
Empty occurrences
Related information
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML EXPORT TEXT

This statement has the following parameters:

Parameter | Description
DataItem | An identifier of the COBOL data item that contains the data to be exported. This is not necessarily the same data item as the one that produced the model template file description of the data to be exported, but must be at least as large as so described. The identifier may refer to a linkage data item that has been passed to a subprogram that does the export. The identifier may be that of a table element specified with any necessary subscripting or indexing when the application has a table of export areas.
DocumentPointer | An identifier of a COBOL pointer data item that will point to the generated XML document as a text string after successful completion of the statement.
DocumentLength | An identifier of a COBOL numeric data item that will contain the length of the generated XML document pointed to by DocumentPointer after successful completion of the statement.
ModelFileName#DataName A nonnumeric literal or an identifier of an alphanumeric data item, the value of which may be any of the following:
  • The name of the data structure. If the # (hash) character is missing, it is assumed that the hash character was intended to be placed at the beginning of the parameter (as the specified name is a data item name).

    Everything to the left of the "#" character is the filename. Everything to the right is the data structure name. Either component is optional; that is, model names of "file#", "file", "#data", "#" and "" are allowed. If the filename is omitted and a default has not been provided from the XML COBOL FILE-NAME statement (on page 41), then the current program is assumed. If the data name is not found, then calling programs are used (in order of the call stack).

    The data name must be found in the model template file; its description must not describe an area larger than the DataItem specified by the first parameter of the statement; otherwise an error 74 may happen during program execution. If the data name is omitted in this parameter, then the entire program's data definitions are used as determined by the model template file.

    If a hash "#" character is missing from the ModelFileName parameter, one will be assumed to be present at the beginning (the ModelFileName is assumed to be a data name).

    Furthermore, a hierarchical specification of data names may be used; that is, "a//b//c" is valid. It has the same meaning as the COBOL specification of "C of B of A". Either data names or program names may be specified in the data name hierarchy; that is, A and B could be the names of programs, assuming B is a program contained in A.

  • The name of the XML file produced by the XMLGEN compiler directive that describe the COBOL data item. For more information, see Model Files.
[StyleSheetName] | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the generated XML document before it is stored.

Description

The XML EXPORT TEXT statement exports the content of the COBOL data item indicated by the DataItem parameter. The content of the data item is converted to an XML document using one or more files indicated by the ModelFileName#DataName parameter, and then it is output as a text string. The address and size of the text string is placed in the COBOL data items specified by the DocumentPointer and DocumentLength parameters. If the optional StyleSheetName parameter is present, the external XSLT stylesheet is used to transform the document after it has been generated but before it is stored as a text string.

A block of memory is allocated to hold the generated XML document. The descriptor of this memory block overrides any existing address descriptor in the COBOL pointer data item. The COBOL application is responsible for releasing this memory when it is no longer needed by using XML FREE TEXT.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Examples

Without an External XSLT Stylesheet:

XML EXPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet:

XML EXPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML EXPORT TEXT
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related reference
State management statements
Model files
Empty occurrences
Related information
XML EXPORT FILE
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML IMPORT FILE

This statement has the following parameters:

Parameter | Description
DataItem | An identifier of the COBOL data item that is to receive the imported data. This is not necessarily the same data item as the one that produced the model template file description of the data to be imported, but must be at least as large as so described. The identifier may refer to a linkage data item that has been passed to a subprogram that does the import. The identifier may be that of a table element specified with any necessary subscripting or indexing when the application has a table of import areas.
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file that contains the XML document to be imported.
ModelFileName#DataName A nonnumeric literal or an identifier of an alphanumeric data item, the value of which may be any of the following:
  • The name of the data structure. If the # (hash) character is missing, it is assumed that the hash character was intended to be placed at the beginning of the parameter (as the specified name is a data item name).

    Everything to the left of the "#" character is the filename. Everything to the right is the data structure name. Either component is optional; that is, model names of "file#", "file", "#data", "#" and "" are allowed. If the filename is omitted and a default has not been provided from the XML COBOL FILE-NAME statement, then the current program is assumed. If the data name is not found, then calling programs are used (in order of the call stack).

    The data name must be found in the model template file; its description must not describe an area larger than the DataItem specified by the first parameter of the statement; otherwise an error 72 may happen during program execution. If the data name is omitted in this parameter, then the entire program's data definitions are used as determined by the model template file.

    If a hash "#" character is missing from the ModelFileName parameter, one will be assumed to be present at the beginning (the ModelFileName is assumed to be a data name).

    Furthermore, a hierarchical specification of data names may be used; that is, "a//b//c" is valid. It has the same meaning as the COBOL specification of "C of B of A". Either data names or program names may be specified in the data name hierarchy; that is, A and B could be the names of programs, assuming B is a program contained in A.

  • The name of the XML file produced by the XMLGEN compiler directive that describe the COBOL data item. For more information, see Model Files.
[StyleSheetName] | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the imported XML document before it is stored in the data item.

Description

The XML IMPORT FILE statement imports the content of the file indicated by the DocumentName parameter. If the optional StyleSheetName parameter is present, the external XSLT stylesheet is first used to transform the document. The content of the XML document is converted to COBOL format using the file specified by the ModelFileName#DataName parameter, and then is stored in the data item specified by the DataItem parameter.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Examples

Without an External XSLT Stylesheet:

XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT"
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet:

XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related reference
Model files
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML IMPORT TEXT

This statement has the following parameters:

Parameter | Description
DataItem | An identifier of the COBOL data item that is to receive the imported data. This is not necessarily the same data item as the one that produced the model template file description of the data to be imported, but must be at least as large as so described. The identifier may refer to a linkage data item that has been passed to a subprogram that does the import. The identifier may be that of a table element specified with any necessary subscripting or indexing when the application has a table of import areas.
DocumentPointer | An identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | An identifier of a COBOL numeric data item that contains the length of the XML document pointed to by DocumentPointer.
ModelFileName#DataName A nonnumeric literal or an identifier of an alphanumeric data item, the value of which may be any of the following:

  • The name of the data structure. If the # (hash) character is missing, it is assumed that the hash character was intended to be placed at the beginning of the parameter (as the specified name is a data item name).

    Everything to the left of the "#" character is the filename. Everything to the right is the data structure name. Either component is optional; that is, model names of "file#", "file", "#data", "#" and "" are allowed.

    If the filename is omitted and a default has not been provided from the XML COBOL FILE-NAME statement, then the current program is assumed. If the data name is not found, then calling programs are used (in order of the call stack).

    The data name must be found in the model template file; its description must not describe an area larger than the DataItem specified by the first parameter of the statement; otherwise an error 72 may happen during program execution. If the data name is omitted in this parameter, then the entire program's data definitions are used as determined by the model template file.

    If a hash "#" character is missing from the ModelFileName parameter, one will be assumed to be present at the beginning (the ModelFileName is assumed to be a data name).

    Furthermore, a hierarchical specification of data names may be used; that is, "a//b//c" is valid. It has the same meaning as the COBOL specification of "C of B of A". Either data names or program names may be specified in the data name hierarchy; that is, A and B could be the names of programs, assuming B is a program contained in A.

  • The name of the XML file produced by the XMLGEN compiler directive that describe the COBOL data item. For more information, see Model Files.
[StyleSheetName] | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the imported XML document before it is stored in the data item.

Description

The XML IMPORT TEXT statement imports the content of the text string indicated by the DocumentPointer and DocumentLength parameters. If the optional StyleSheetName parameter is present, the external XSLT stylesheet is used to transform the document before being converted to COBOL data format. The content of the XML document is converted to COBOL format using the file specified by the ModelFileName#DataName parameter, and then is stored in the data item specified by the DataItem parameter.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Examples

Without an External XSLT Stylesheet:

XML IMPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet:

XML IMPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML IMPORT TEXT
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related reference
Model files
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TEST WELLFORMED-FILE

This statement has the following parameters:

Parameter | Description
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the file name of the file containing the XML document to be tested.

Description

The XML TEST WELLFORMED-FILE statement tests the XML document specified by the DocumentName parameter to see if it is well-formed. A well-formed XML document is one that conforms to XML syntax rules, but is not necessarily valid with respect to any schema. See XML VALIDATE FILE and XML VALIDATE TEXT for testing whether a document is valid with respect to a schema.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

XML TEST WELLFORMED-FILE
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related reference
XML VALIDATE FILE
XML VALIDATE TEXT
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TEST WELLFORMED-TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | An identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | An identifier of a COBOL numeric data item that contains the length of the XML document pointed to by DocumentPointer.

Description

The XML TEST WELLFORMED-TEXT statement tests the XML document specified by the DocumentPointer and DocumentLength parameters to see if it is well-formed. A well-formed XML document is one that conforms to XML syntax rules, but is not necessarily valid with respect to any schema. See XML VALIDATE FILE and XML VALIDATE TEXT for testing whether a document is valid with respect to a schema.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

XML TEST WELLFORMED-TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH.
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related reference
XML VALIDATE FILE
XML VALIDATE TEXT
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TRANSFORM FILE

This statement has the following parameters:

Parameter | Description
InputDocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the file name of the file containing the XML document to be transformed.
StyleSheetName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the input document.
OutputDocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the file name of the file containing the transformed XML document after successful completion of the statement.

Description

The XML TRANSFORM FILE statement transforms the XML document specified by the InputDocumentName parameter using the XSLT stylesheet specified by the StyleSheetName parameter into a new document specified by the OutputDocumentName parameter. The new document may or may not be an XML document depending on the XSLT stylesheet.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Examples

With an External XSLT Stylesheet:

XML TRANSFORM FILE
    "MY-IN-DOCUMENT"
    "MY-STYLESHEET"
    "MY-OUT-DOCUMENT.
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML TRANSFORM FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TRANSFORM TEXT

This statement has the following parameters:

Parameter | Description
InputDocumentPointer | An identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string that is to be transformed.
InputDocumentLength | An identifier of a COBOL numeric data item that contains the length of the XML document pointed to by InputDocumentPointer.
StyleSheetName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XSLT stylesheet that will be used to transform the input document.
OutputDocumentPointer | An identifier of a COBOL pointer data item that will point to the transformed XML document as a text string after successful completion of the statement.
OutputDocumentLength | An identifier of a COBOL numeric data item that will contain the length of the transformed XML document pointed to by OutputDocumentPointer after successful completion of the statement.

Description

The XML TRANSFORM TEXT statement transforms the XML document specified by the InputDocumentPointer and InputDocumentLength parameters using the XSLT stylesheet specified by the StyleSheetName parameter into a new document specified by the OutputDocumentPointer and OutputDocumentLength parameters. The new document may or may not be an XML document depending on the XSLT stylesheet.

A block of memory is allocated to hold the generated XML document. The descriptor of this memory block overrides any existing address descriptor in the COBOL pointer data item. The COBOL application is responsible for releasing this memory when it is no longer needed by using XML FREE TEXT.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Examples

With an External XSLT Stylesheet:

XML TRANSFORM TEXT
    MY-IN-DOCUMENT-POINTER
    MY-IN-DOCUMENT-LENGTH
    "MY-STYLESHEET"
    MY-OUT-DOCUMENT-POINTER
    MY-OUT-DOCUMENT-LENGTH
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML TRANSFORM TEXT
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML VALIDATE FILE
XML VALIDATE TEXT


XML VALIDATE FILE

This statement has the following parameters:

Parameter | Description
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the file name of the file containing the XML document to be validated with the schema specified by the SchemaName parameter.
SchemaName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XML schema that will be used to validate the document specified by the DocumentName parameter.

Description

The XML VALIDATE FILE statement tests the XML document specified by the DocumentName parameter to see if it is well-formed and valid.

A well-formed XML document is one that conforms to XML syntax rules. A valid XML document is one that is both well-formed and has content that conforms to rules specified by an XML schema file. The schema file is supplied by the user.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Note: In the Windows implementation of XML Extensions, the Microsoft XML parser 4.0 ignores the document type definition (DTD) when validating an XML document against a schema file. Thus, any entities declared in the DTD will not be defined and cannot be referenced. Any XML document that contains entity references, other than the predefined XML entities, must be transformed with an XSLT stylesheet prior to validation against a schema file when using the Microsoft XML parser 4.0 so that any non-predefined entity references are removed. Otherwise, the document will fail validation.

Example

XML VALIDATE FILE
    "MY-DOCUMENT"
    "MY-SCHEMA".
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE TEXT


XML VALIDATE TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | An identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | An identifier of a COBOL numeric data item that contains the length of the XML document pointed to by DocumentPointer.
SchemaName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of a file containing an XML schema that will be used to validate the document specified by the DocumentPointer and DocumentLength parameters.

Description

The XML VALIDATE TEXT statement tests the XML document specified by the DocumentPointer and DocumentLength parameters to see if it is well-formed and valid.

A well-formed XML document is one that conforms to XML syntax rules. A valid XML document is one that is both well-formed and has content that conforms to rules specified by an XML schema file. The schema file is supplied by the user.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Note: In the Windows implementation of XML Extensions, the Microsoft XML parser 4.0 ignores the document type definition (DTD) when validating an XML document against a schema file. Thus, any entities declared in the DTD will not be defined and cannot be referenced. Any XML document that contains entity references, other than the predefined XML entities, must be transformed with an XSLT stylesheet prior to validation against a schema file when using the Microsoft XML parser 4.0 so that any non-predefined entity references are removed. Otherwise, the document will fail validation.

Example

XML VALIDATE TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-SCHEMA".
IF NOT XML-OK GO TO Z.
Parent topic: Document processing statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE


Document management statements

A number of statements are available to copy an XML document from an external file to an internal text string and vice versa.

A set of RESOLVE statements allows the developer to obtain a fully resolved pathname (for example, c:\mystuff\stuff.xml rather than stuff.xml), thus providing a globally unique name that can be passed as a parameter to a called sub-program. This is useful in cases where global resources are defined in the top-level program and then referenced in a called (possibly nested) subprogram that may include another resource having the same name.

  • XML COBOL FILE-NAME
  • XML FREE TEXT
  • XML GET TEXT
  • XML PUT TEXT
  • XML REMOVE FILE
  • XML RESOLVE DOCUMENT-NAME
  • XML RESOLVE SCHEMA-FILE
  • XML RESOLVE STYLESHEET-FILE
  • XML RESOLVE MODEL-NAME
Parent topic: XML Extensions statements reference


XML COBOL FILE-NAME

This statement has the following parameters:

Parameter | Description
[FileName] | Optional. A nonnumeric literal or an identifier of an alphanumeric data item, the value of which specifies the default ModelFileName value (the string before the #) in the ModelFileName#DataName parameter for subsequent statements that do not explicitly specify a ModelFileName. If omitted or specified with a value of spaces, the default ModelFileName value is reset to spaces, eliminating any previously set default ModelFileName value. If the parameter value is #, the name of the COBOL object file for the currently running COBOL program is used to set the default ModelFileName value. Otherwise, the current value of the parameter is used " as is" to set the default ModelFileName value.

Description

The XML COBOL FILE-NAME statement allows the developer to set the default ModelFileName (the string before the #) in the ModelFileName#DataName parameter of various subsequent XML Extensions statements. The default value will be used when the ModelFileName string is not specified in the ModelFileName#DataName parameter of those subsequent statements.

Example

XML COBOL FILE-NAME
            MY-FILE.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related information
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML FREE TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | An identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.

Description

The XML FREE TEXT statement releases the COBOL memory referred to by the COBOL pointer data item specified by the DocumentPointer parameter, which should have a value that has been set by the XML EXPORT TEXT, XML TRANSFORM TEXT, or the XML GET TEXT statements.

Example

XML FREE TEXT
    MY-POINTER
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related reference
XML EXPORT TEXT
XML GET TEXT
Related information
XML COBOL FILE-NAME
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML GET TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | An identifier of a COBOL pointer data item that will point to the in-memory text string after successful completion of the statement.
DocumentLength | An identifier of a COBOL numeric data item that will contain the length of the text string pointed to by DocumentPointer after successful completion of the statement.
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the filename of the file containing the text to load into memory. This text string is not necessarily an XML document. The content may even be a binary data; the term text in this context simply means in-memory instead of in-file.

Description

The XML GET TEXT statement copies the content from the file specified by the DocumentName parameter to COBOL memory. A block of memory is allocated to contain the document. The address and size of the memory block are returned in the DocumentPointer and DocumentLength parameters.

When the program has finished using the in-memory document, a call to XML FREE TEXT should be made to release the allocated memory.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

XML GET TEXT
    MY-POINTER
    MY-LENGTH
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related reference
XML FREE TEXT
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML PUT TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | An identifier of a COBOL pointer data item that points to the text to be written to a file. This text string is not necessarily an XML document and may be binary data.
DocumentLength | An identifier of a COBOL numeric data item that contains the length of the text pointed to by DocumentPointer.
DocumentName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the filename of the file which will contain the text after completion of the statement.

Description

The XML PUT TEXT statement copies the content of the in-memory XML document specified by the DocumentPointer and DocumentLength parameters to the external file specified by the DocumentName parameter. A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

XML PUT TEXT
    MY-POINTER
    MY-LENGTH
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML REMOVE FILE

This statement has the following parameters:

Parameter | Description
FileName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the filename of the file to be removed. The file does not necessarily contain an XML document.

Description

The XML REMOVE FILE statement deletes the file specified by the FileName parameter. If the specified filename does not contain an extension, then .xml is appended to the name. If the file does not exist, no error is returned.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

XML REMOVE FILE
    MY-FILE-NAME.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML RESOLVE DOCUMENT-NAME

This statement has the following parameters:

Parameter | Description
DocumentName | An identifier of an alphanumeric data item, the value of which is the document filename to be resolved. The resolved filename is stored in this same data item upon successful completion of the statement.

Description

The XML RESOLVE DOCUMENT-NAME statement is used to resolve the name of an XML document file. The resolution process is the same as that for the DocumentName parameter of an XML IMPORT statement.

If the name is a URL, it is used "as is". Otherwise, if the name does not contain an extension, the extension .xml is added.

Example

XML RESOLVE DOCUMENT-NAME
            MY-DOCUMENT.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML RESOLVE SCHEMA-FILE

This statement has the following parameters:

Parameter | Description
SchemaFileName | An identifier of an alphanumeric data item, the value of which is the schema filename to be resolved. The resolved schema filename is stored in this same data item upon successful completion of the statement.

Description

The XML RESOLVE SCHEMA-FILE statement is used to resolve the name of an XML schema file specified for the SchemaFileName parameter. The resolution process is similar to that for the ModelFileName#DataName parameter of an XML IMPORT FILE, XML IMPORT TEXT, XML EXPORT FILE, or XML EXPORT TEXT statement. The value of this parameter must specify an existing schema file.

XML Extensions uses the schema files only as input files. When XML Extensions references a schema file, the appropriate predetermined extension is added, regardless of the presence or lack of an extension on the schema file parameter supplied by the COBOL program.

XML Extensions uses the CBL_LOCATE_FILE library routine to locate a schema file (with the appropriate extension added) except when:

  • the schema filename contains a directory separator character (such as "\" on Windows);
  • the file exists; or
  • the filename is a URL (that is, the name begins with "http://", https://, or "file://"). If the name is a URL, it is used "as is". Otherwise, the file extension is forced to be .xsd.

Example

XML RESOLVE SCHEMA-NAME
       MY-SCHEMA-FILE.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE STYLESHEET-FILE
XML RESOLVE MODEL-NAME


XML RESOLVE STYLESHEET-FILE

This statement has the following parameters:

Parameter | Description
StyleSheetName | An identifier of an alphanumeric data item, the value of which is the stylesheet filename to be resolved. The resolved stylesheet filename is stored in this same data item upon successful completion of the statement.

Description

The XML RESOLVE STYLESHEET-FILE statement is used to resolve the name of an XML stylesheet file. The resolution process is the same as that for the StyleSheetName parameter of an XML IMPORT or XML EXPORT statement.

If the name is a URL, it is used "as is". Otherwise, if the name does not contain an extension, the extension .xsl is added.

Example

XML RESOLVE STYLESHEET-NAME
       MY-STYLESHEET-FILE.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related reference
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE MODEL-NAME


XML RESOLVE MODEL-NAME

This statement has the following parameters:

Parameter Description
ModelFileName#DataName A nonnumeric literal or an identifier of an alphanumeric data item, the value of which may be any of the following:
  • The name of the data structure. If the # (hash) character is missing, it is assumed that the hash character was intended to be placed at the beginning of the parameter (as the specified name is a data item name). Previously, it was assumed that the # character was placed at the end of the parameter (as the specified name was a filename.

    Everything to the left of the "#" character is the filename. Everything to the right is the data structure name. Either component is optional; that is, model names of "file#", "file", "#data", "#" and "" are allowed. If the filename is omitted and a default has not been provided from the XML COBOL FILE-NAME statement (on page 41), then the current program is assumed. If the data name is not found, then calling programs are used (in order of the call stack).

    If the data name is omitted, then the entire program is used.

    If a hash "#" character is missing from the ModelFileName parameter, one will be assumed to be present at the beginning (the ModelFileName is assumed to be a data name).

    Furthermore, a hierarchical specification of data names may be used; that is, "a//b//c" is valid. It has the same meaning as the COBOL specification of "C of B of A". Either data names or program names may be specified in the data name hierarchy; that is, A and B could be the names of programs, assuming B is a program contained in A.

  • The name of the XML file produced by the XMLGEN compiler directive that describe the COBOL data item. For more information, see Model Files.

The resolved ModelFileName#DataName value is stored in this same data item upon successful completion of the statement.

Description

The XML RESOLVE MODEL-NAME statement is used to resolve the name of a model file/data name combination. The resolution process is the same as that for the ModelFileName#DataName parameter of the XML IMPORT FILE, XML IMPORT TEXT, XML EXPORT FILE, or XML EXPORT TEXT statements.

If the name is a URL, it is used "as is". Otherwise, the name is examined with an .xtl extension and then a .cob extension. If the name component is absent, the current executing COBOL program is searched, followed by calling COBOL programs (if present). Whatever data name (following the "#" character) is present is carried forward.

Example

XML RESOLVE MODEL-NAME
          MY-MODEL-DATA-FILE.
IF NOT XML-OK GO TO Z.
Parent topic: Document management statements
Related reference
Model files
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
Related information
XML COBOL FILE-NAME
XML FREE TEXT
XML GET TEXT
XML PUT TEXT
XML REMOVE FILE
XML RESOLVE DOCUMENT-NAME
XML RESOLVE SCHEMA-FILE
XML RESOLVE STYLESHEET-FILE


Directory management statements

This section describes the statements that are useful when implementing directory-polling schemes.

Directory polling, as related to XML documents, allows two or more independent processes to pass XML documents between the processes. For example, one or more writer processes may place XML documents in a well-known directory (a well-known directory is a directory name that is known to all of the interested processes). Each XML document must have been given a unique name. A reader process finds, processes, and removes XML documents from the same well-known directory.

Directory polling may be used to communicate with message-driven communications systems. It is a technique that may also be used between various COBOL applications. Multiple COBOL runtime systems (perhaps running on separate machines on the same local area network) can use directory polling (perhaps to a directory that is available on the network) as a means of improving throughput in processing XML documents.

It is not feasible to use multiple reader processes on the same directory because the XML FIND FILE statement, invoked from separate processes, could find the same file. For the Windows implementation, a sample C language program (DirSplit) is provided that will poll a single directory and distribute files to subdirectories as they arrive. This will allow separate COBOL programs each to process a separate subdirectory.

Note: The following problems have been encountered on Windows systems running the older FAT32 file system:
  • When a program is adding XML document files to a directory concurrently with another program that is moving XML document files to different directory using the C library function rename or the Windows API function MoveFile, it is possible for the wrong file to be moved or for the file to be moved to the wrong location. This failure can occur without the participation of XML Extensions.
  • When a large number of XML document files are written to a directory by XML Extensions using XML EXPORT FILE (on page 30), it is possible that files will not be placed in the directory and no error will be returned by the operating system either to XML Extensions or to the program issuing the statement. It appears that the FAT32 file system may be limited to 65,535 files per directory (at least under certain conditions). Furthermore, if long filenames are used, multiple directory entries may be needed for each filename, further reducing the number of files per directory.
For these reasons, it is recommended that directory polling not be used on Windows running with FAT32 file systems. Windows with the NTFS file system and UNIX file systems do not demonstrate this problem.
  • XML FIND FILE
  • XML GET UNIQUEID
Parent topic: XML Extensions statements reference
Related reference
XML EXPORT FILE


XML FIND FILE

This statement has the following parameters:

Parameter | Description
DirectoryName | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the name of the directory to search for files.
FileName | An identifier of an alphanumeric data item that will contain the name of a found file upon successful completion of the statement.
[ExtensionName] | Optional. A nonnumeric literal or an identifier of an alphanumeric data item, the value of which is the extension having the format .aaa. The leading dot is required, but the extension is not limited in length other than reasonable file name length limits. When omitted, the default extension name is .xml.

Description

The XML FIND FILE statement looks in the directory specified by the DirectoryName parameter for an XML document (a file with the .xml extension, unless the Extension parameter is specified). If there are one or more XML documents in the specified directory, the name of one of the files will be returned in the FileName parameter.

If the statement succeeds (the condition XML-IsSuccess is true), the XML document specified by the FileName parameter may be processed by using XML IMPORT FILE.

Before calling XML FIND FILE again (to process the next file), you must call XML REMOVE FILE to delete the XML document that was just processed. Otherwise, the next call to the XML FIND FILE statement may return the same file.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy. The condition XML-IsDirectoryEmpty will be true if the directory is empty.

Example

FIND-DOCUMENT.
    PERFORM WITH TEST AFTER UNTIL 0 > 1
        XML FIND FILE
            "MY-DIRECTORY"
            MY-FILE-NAME
        IF XML-IsSuccess
            EXIT PERFORM
        END-IF
        IF XML-IsDirectoryEmpty
            CALL "C$DELAY" USING 0.1
        END-IF
        IF NOT XML-OK GO TO Z.
    END-PERFORM
*> Process found document
Parent topic: Directory management statements
Related reference
XML REMOVE FILE
XML IMPORT FILE
Related information
XML GET UNIQUEID


XML GET UNIQUEID

This statement has the following parameters:

Parameter | Description
UniqueID | An identifier of an alphanumeric data item that is at least 38 characters in length. The generated unique identifier is placed in this data item upon successful completion of the statement.

Description

The XML GET UNIQUEID statement generates a unique identifier that may be used to form a unique filename. Please note that the return value might not contain any alphabetic characters. Therefore, it would be a good programming practice to add an alphabetic character to the name for those systems where filenames require at least one alphabetic character (see the following example).

The unique value returned by this statement is a string representation having the same format as a UUID (Universal Unique Identifier). The string is a series of hexadecimal digits with embedded hyphen characters. The string is enclosed in brace characters ({ and }). The entire string is 38 characters in length. On Windows systems, the value is an actual UUID. On UNIX systems, the value is a string having the same format as a UUID, but constructed by an internal algorithm. This algorithm uses various components, including the system ID, the start time of the run unit, the current time, and an internal counter, to generate a unique value.

This statement may be used in conjunction with the COBOL STRING statement to generate a unique filename.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

Example

MOVE SPACES TO MY-FILE-NAME.
XML GET UNIQUEID
    MY-UNIQUEID.
IF NOT XML-OK GO TO Z.
STRING "mydir\a"   DELIMITED BY SIZE
       MY-UNIQUEID DELIMITED BY SPACE
       ".xml"      DELIMITED BY SIZE
    INTO MY-FILE-NAME.
Parent topic: Directory management statements
Related information
XML FIND FILE


State management statements

Calls to the following XML statements control several states or conditions, including:

Initialization and termination. Before issuing a call to any other XML Extensions statement, XML INITIALIZE must be called. (If XML INITIALIZE has not been called, any subsequent calls, for example, XML EXPORT FILE, will fail.) Similarly,

  • XML TERMINATE should be called when the COBOL application is finished using XML Extensions statements. (If XML TERMINATE has not been called prior to program termination, there are no consequences.)
  • Empty array occurrences. As an optimization, trailing "empty" occurrences of arrays are normally not generated by the statements, XML EXPORT FILE or XML EXPORT TEXT.

An empty occurrence of an array is defined to be one where the numeric items have a zero value and the nonnumeric items have a value equivalent to all spaces. This is the default state and is equivalent to calling XML DISABLE ALL-OCCURRENCES. It is possible to force all occurrences to be output by calling XML ENABLE ALL-OCCURRENCES.

  • COBOL attributes. For each element generated by the statements, XML EXPORT FILE or XML EXPORT TEXT, there is a series of COBOL attributes that describe that element.

    The default state is not to output these attributes. However, it is sometimes necessary for a following activity (such as an XSLT stylesheet transformation) to have access to these attributes (specifically, length and subscript are often important to a follow-on activity). Using XML DISABLE ATTRIBUTES prevents attributes from being written (this is the default). Using XML ENABLE ATTRIBUTES forces these attributes to be written.

  • Document caching. XML documents, such as XSLT stylesheets, templates, and schemas, are normally considered to be static during the use of a production version of the application. That is, they are generated when the application is developed and are not modified until the application is modified.

    To optimize performance, when XML Extensions loads an XSLT stylesheet, a template, or a schema, the document is cached (that is, retained in memory) for an indefinite period of time. This is the default behavior. However, even with the default behavior, a document in the cache may be flushed from memory if the cache is full and an XSLT stylesheet, template, or schema document not already in the cache is required for the current operation.

    If XSLT stylesheets, templates, or schemas are being generated dynamically, the user may selectively enable or disable caching. Executing XML ENABLE CACHE, which sets the default behavior, enables caching of documents. Executing XML DISABLE CACHE disables caching, thus forcing all documents to be loaded each time they are referenced. Executing XML FLUSH CACHE flushes all documents and local memory from the cache without changing the state of caching (that is, if caching was enabled it remains enabled). Executing any of the following statements causes the contents of the cache to be flushed: XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE. Executing XML ENABLE CACHE, XML DISABLE CACHE, or XML FLUSH CACHE also causes local memory to be flushed.

    For more information, see Memory Management with XML Extensions.

  • Flags. The data conversions performed by the statements, XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, and XML IMPORT TEXT, use the library (which is built into the XML Extensions runtime executable) to perform these conversions. By default, the following flags are set: PF_TRAILING_SPACES, PF_LEADING_SPACES, PF_LEADING_MINUS, and PF_ROUNDED.

    Note: The flags are C macros. They are case sensitive and require the use of the underscore character.

    XML GET FLAGS and XML SET FLAGS are available to alter these defaults.

  • Whitespace flags. The handling of whitespace by the statements XML IMPORT FILE and XML IMPORT TEXT use the whitespace handling flags built into XML Extensions. By default, the whitespace flags are set to

    WHITESPACE-DEFAULT-FLAGS (value 0).

    XML GET WHITESPACE-FLAGS and XML SET WHITESPACE-FLAGS are available to obtain or change, respectively, the setting of the whitespace flags. The XML Extensions handling of whitespace during import is explained in the topic Handling Spaces and Whitespace in XML.

  • Internal character encoding. Characters within alphanumeric data elements in a COBOL program are normally encoded using the conventions of underlying operating systems. Under some conditions, it may be desirable to encode these same data items using UTF-8 encoding. (UTF-8 is a format for representing Unicode.) XML SET ENCODING is provided to switch between the local encoding format and UTF-8.

    Note: Both the UNIX and Windows implementations of XML Extensions allow the in-memory representation of element content to use UTF-8 encoding. This may be useful for COBOL applications that wish to pass UTF-8-encoded data to other processes. XML documents are normally encoded using Unicode. XML Extensions always generates UTF-8 data. For more information, see COBOL and Character Encoding and XML and Character Encoding.
  • Tracing. Trace information can be generated to a designated file using the XML TRACE statement.
  • Stylesheet parameters. The passing of parameters to stylesheets can be controlled by the XML SET XSL-PARAMETERS and XML CLEAR XSL-PARAMETERS statements.
  • XML INITIALIZE
  • XML TERMINATE
  • XML DISABLE ALL-OCCURRENCES
  • XML ENABLE ALL-OCCURRENCES
  • XML DISABLE ATTRIBUTES
  • XML ENABLE ATTRIBUTES
  • XML DISABLE CACHE
  • XML ENABLE CACHE
  • XML FLUSH CACHE
  • XML GET FLAGS
  • XML GET WHITESPACE-FLAGS
  • XML TRACE
  • XML GET STATUS-TEXT
  • XML SET ENCODING
  • XML SET FLAGS
  • XML SET WHITESPACE-FLAGS
  • XML SET XSL-PARAMETERS
  • XML SET XSL-PARAMETERS-NEW
  • XML CLEAR XSL-PARAMETERS
Parent topic: XML Extensions statements reference


XML INITIALIZE

This statement has no parameters.

Description

The XML INITIALIZE statement opens a session with XML Extensions. The underlying XML parser is also initialized.

The execution of this statement causes the document cache to be flushed from memory.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy. Errors can occur if the Visual COBOL runtime system is incompatible, or the underlying XML parser initialization fails. It is not considered an error to execute an XML INTIALIZE statement when XML Extensions has already been initialized and not terminated.

Example

XML INITIALIZE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
Making a program skeleton
Related information
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML TERMINATE

This statement has no parameters.

Description

The XML TERMINATE statement flushes the document cache and closes a session with XML Extensions. The interface to the underlying XML parser is also closed. Any memory blocks that were allocated by XML Extensions are freed.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy. Errors can occur under the following circumstances:

The calls to free memory fail.

The underlying XML parser termination fails.

It is not considered an error to execute an XML TERMINATE statement when XML Extensions has not been initialized or has already been terminated.

Example

XML TERMINATE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
State management statements
Making a program skeleton
Related information
XML INITIALIZE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML DISABLE ALL-OCCURRENCES

This statement has no parameters.

Description

The XML DISABLE ALL-OCCURRENCES statement causes unnecessary empty array (COBOL table) occurrences not to be generated by the statements, XML EXPORT FILE and XML EXPORT TEXT. An empty array is one in which all numeric elements have a zero value and all nonnumeric elements have a value of all spaces.

There is some interoperation with the statements, XML DISABLE ATTRIBUTES and XML ENABLE ATTRIBUTES. If attributes are enabled (that is, XML ENABLE ATTRIBUTES has been called), then all empty occurrences are not generated. If attributes are disabled (the default state or if XML DISABLE ATTRIBUTES has been used), then all trailing empty occurrences are not generated. If attributes are enabled, then the subscript is present and so leading, or intermediate, empty occurrences are not needed as placeholders to ensure that the correct subscript is calculated.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML DISABLE ALL-OCCURRENCES.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
XML EXPORT FILE
XML EXPORT TEXT
Related information
XML INITIALIZE
XML TERMINATE
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML ENABLE ALL-OCCURRENCES

Description

This statement has no parameters.

The XML ENABLE ALL-OCCURRENCES statement causes all occurrence of an array (COBOL table) to be generated by the statements, XML EXPORT FILE and XML EXPORT TEXT, regardless of the content of the array.

All occurrences of an array are generated regardless of whether attributes are enabled or disabled.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML ENABLE ALL-OCCURRENCES.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
XML EXPORT FILE
XML EXPORT TEXT
Empty occurrences
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML DISABLE ATTRIBUTES

This statement has no parameters.

Description

The XML DISABLE ATTRIBUTES statement causes the COBOL attributes of an XML element to be omitted from an exported XML document. This is the default state.

See XML DISABLE ALL-OCCURRENCES regarding the behavior of array (COBOL table) output when attributes are enabled or disabled.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML DISABLE ATTRIBUTES.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML ENABLE ATTRIBUTES

This statement has no parameters.

Description

The XML ENABLE ATTRIBUTES statement causes the COBOL attributes of an XML element to be generated in an exported XML document

See XML DISABLE ALL-OCCURRENCES regarding the behavior of array (COBOL table) output when attributes are enabled or disabled.

Some of the COBOL attributes (such as length and subscript) may be useful to an external XSLT stylesheet.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

XML ENABLE ATTRIBUTES.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML DISABLE CACHE

This statement has no parameters.

Description

The XML DISABLE CACHE statement disables the caching of XSLT stylesheets, templates, and schemas. Besides disabling caching, executing this statement also flushes the document cache as well as local memory.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML DISABLE CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML ENABLE CACHE

This statement has no parameters.

Description

The XML ENABLE CACHE statement enables the caching of XSLT stylesheets, templates, and schemas, and flushes the document cache and local memory immediately, even if document caching was already enabled.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML ENABLE CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML FLUSH CACHE

This statement has no parameters.

Description

The XML FLUSH CACHE statement flushes the cache of XSLT stylesheet, templates, and schema documents, and flushes the document cache and local memory. The enabled or disabled state of caching is not changed by this statement.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML FLUSH CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML GET FLAGS

This statement has the following parameter:

Description

Parameter | Description
Flags | An identifier of a numeric integer data item where the current data conversion flag settings are to be stored upon successful completion of the statement.

The XML GET FLAGS statement retrieves the setting of the flags that are used for internal data conversion. Valid flag values are specified in the copybook, lixmldef.cpy. The initial setting of the flags has the following flag values set: PF-Leading-Spaces, PF-Trailing-Spaces, PF-Leading-Minus, and PF-Rounded. The setting of the flags can be changed with the XML SET FLAGS statement.

Note: These flag values are 78-level constants. They are case insensitive and require the use of the hyphen character.

In managed code the Flags argument is restricted to a PIC X(4) COMP-X data item or equivalent. See Managed Code Considerations for more information.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML GET FLAGS
 MY-FLAGS.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML GET WHITESPACE-FLAGS

This statement has the following parameter:

Description

Parameter | Description
WhitespaceFlags | An identifier of a numeric integer data item where the current whitespace flag settings are to be stored upon successful completion of the statement.

The XML GET WHITESPACE-FLAGS statement retrieves the setting of the XML Extensions flags that are used for whitespace handling during import. Valid flag values are specified in the copy file, lixmldef.cpy. The initial setting of the flags is WHITESPACE-DEFAULT-FLAGS (value 0). The XML SET WHITESPACE-FLAGS statement description lists and describes the possible whitespace flags settings.

Note: The whitespace flag values are provided as 78-level constant-names in lixmldef.cpy. The names are case insensitive and require the use of the hyphen character.

A status value is returned in the data item XML-data-group, which is defined in the copy file, lixmldef.cpy.

Example

XML GET WHITESPACE-FLAGS
   WHITESPACE-FLAGS-SAVE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
Handling spaces and whitespace in XML
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML TRACE

This statement has the following parameters:

Description

Parameter

Description

Flags

A numeric integer literal or an identifier of a numeric integer data item, with one of the following values:
  • 0 = Turn tracing off and keep any existing trace file.
  • 1 = Turn tracing on and keep any existing trace file.
  • 2 = Turn tracing off and delete any existing trace file.
  • 3 = Turn tracing on and delete any existing trace file.

The XML Extensions definitions copy file lixmldef.cpy defines the constant-names XML-TraceOffV (0), XML-TraceOnAppendV (1) and XML-TraceOnReplaceV (3) as a convenience for setting the flags.

[FileName]

Optional. A nonnumeric literal or an identifier of an alphanumeric data item, the value of which specifies the name of the trace file. If omitted, a value of XMLTrace.log is assumed.

The XML TRACE statement generates trace information to a designated file. The statement name and parameter values (as well as the calling program name and the time executed) are recorded on entry. Updated parameter values are displayed on exit.

Examples

Without Trace File Parameter:
XML TRACE
 MY-FLAGS.
IF NOT XML-OK GO TO Z.
Showing Optional Trace File Parameter:
XML TRACE
 MY-FLAGS
 MY-TRACE-FILE.
IF NOT XML-OK GO TO Z.
Showing Trace Output for the Execution of an XML IMPORT FILE Statement:
XMLImportFile - entry
 DocumentName[test83i1]
 ModelFileDataName[./code/test83.cob#test-83//test-83-n2-n2//cp1]
 StyleSheetName[]
Date-Time: Tue Apr 17 11:56:16 2007
Called from line 1151 in
TEST-83-N2-N2(C:\xmlext\root\rmc85\test\xmlext\code\TEST83.COB),
compiled
2007/04/17 11:55:24.
XMLImportFile - exit
 Status[0]
FullDocumentName[C:\xmlext\root\rmc85\test\xmlext\xml\test83i1.xml]
 FullModelFileName[C:\xmlext\root\rmc85\test\xmlext\code\TEST83_TEST-83.xtl]
 ModelDataName[test-83//test-83-n2-n2//cp1]
FullStyleSheetName[]
Parent topic: State management statements
Related reference
XML IMPORT FILE
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML GET STATUS-TEXT

This statement has no named parameters.

Description

A non-successful termination of an XML statement may cause one or more lines of descriptive text to be placed in a queue. The XML GET STATUS-TEXT statement fetches the next line of descriptive text.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy. The following condition names are also described in this copybook:

  • XML-IsSuccess. A successful completion occurred (no informative, warning, or error messages).
  • XML-OK. An OK (or satisfactory) completion occurred, including informative or warning messages.
  • XML-IsDirectoryEmpty. An informative status indicating that XML FIND FILE found no XML documents in the indicated directory.

An example of processing the status information in this item is found below and in the copybook, lixmldsp.cpy.

Example

Display-Status.
 If Not XML-IsSuccess
 Perform With Test After Until XML-NoMore
 XML GET STATUS-TEXT
 Display XML-StatusText
 End-Perform
 End-If.
Note: In the lixmldef.cpy copybook, the definition of the XML-StatusText field may be edited from the default of 80 to change the size of the buffer used to contain XML status information. See Displaying Status Information.
Parent topic: State management statements
Related reference
XML FIND FILE
Displaying status information
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML SET ENCODING

This statement has the following parameter:

Description

Parameter | Description
Encoding | A nonnumeric literal or an identifier of an alphanumeric data item, the value of which must be either 'local' or 'utf-8'. If the value is "local", then the character encoding used by the operating system is used. If the value is 'utf-8', then the data is treated as UTF-8 encoded. The parameter value is case insensitive. Any hyphen and underscore characters are optional. For example, 'LOCAL', 'Local', and 'local' are equivalent. 'UTF-8', 'Utf_8', and 'utf8' are also equivalent.

The XML SET ENCODING statement allows the developer to specify the character encoding of data within a COBOL data structure. The developer may use this statement to switch between the local character encoding and UTF-8. On Windows, the local character encoding matches the native character set of the runtime; that is, it is specified by the Windows ANSI code page or Windows OEM code page depending on the native character set of the runtime system. On UNIX, the local character encoding is specified by the value of the MF_XMLEXT_LOCAL_ENCODING environment variable, with a default of MF_LATIN_9 if the variable is not defined.

Note: If the value of the Encoding parameter specifies 'utf-8', the MF_XMLEXT_LOCAL_ENCODING environment variable is ignored. For more information on this environment variable, see COBOL and Character Encoding.

Although the XML SET ENCODING statement does not affect the character encoding of the XML document, it does affect the character encoding of the data in the COBOL program. For more information, see Data Representation for more information.

The XML SET ENCODING statement returns an error status value if the value of the Encoding parameter is not recognized.

Example

XML SET ENCODING "local".
IF NOT XML-OK GO TO EXIT-1.

The default value is 'local'. If XML SET ENCODING is never called, the default is used.

Parent topic: State management statements
Related reference
COBOL and character encoding
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML SET FLAGS

This statement has the following parameter:

Description

Parameter | Description
Flags | A numeric integer literal or an identifier of a numeric integer data item, the value of which is used to set the data conversion flags for XML Extensions.

The XML SET FLAGS statement establishes the setting of the flags that are used for internal data conversion. Valid flag values are specified in the copybook, lixmldef.cpy. The initial setting of the flags has the following flag values set: PF-Leading-Spaces, PF-Trailing-Spaces, PF-Leading-Minus, and PF-Rounded.

Note: These flag values are 78-level constants. They are case insensitive and require the use of the hyphen character.

In managed code the Flags argument is restricted to a PIC X(4) COMP-X data item or equivalent. See Managed Code Considerations for more information.

A status value is returned in the data item XML-data-group, which is defined in the copybook, lixmldef.cpy.

Example

XML SET FLAGS
 MY-FLAGS.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML SET WHITESPACE-FLAGS

This statement has the following parameter:

Description

Parameter | Description
WhitespaceFlags | A numeric integer literal or an identifier of a numeric integer data item, the value of which is used to set the whitespace flags for XML Extensions.
WhitespaceFlags
The lixmldef.cpy file defines the following whitespace flags constant-names, which can be combined in various ways and have the described purpose.
  • WHITESPACE-DEFAULT-FLAGS (value 0) - No flags set, which is the default when XML Extensions is first initialized and after termination (in case another initialization is done). When the whitespace flags have the default value, no characters, including whitespace characters, are removed when importing data from an XML document into the COBOL data items. This constant-name can be used to set the flags back to their default value.
  • WHITESPACE-STRIP-CONTROL (value 1) - On import, strips all characters less than space, as in previous XML Extensions implementation, unless one of the preserve flags is set.
  • WHITESPACE-PRESERVE-TAB (value 16) - When stripping control characters, preserve any TAB characters for import.
  • WHITESPACE-PRESERVE-LF (value 32) - When stripping control characters, preserve any LF characters for import.
  • WHITESPACE-PRESERVE-CR (value 64) - When stripping control characters, preserve any CR characters for import. (Note that XML parsers normally translate any CR/LF sequences and any CR not followed by LF to a single LF; thus, CR characters are not normally present and cannot be preserved by this flag setting.)
  • WHITESPACE-NORMALIZE (value 65536) - On import, collapse any whitespace character sequences (space, LF, TAB or CR) to a single space character. The WHITESPACE-STRIP-CONTROL flag, if set, takes precedence over this flag and this flag, if set, will be ignored in that case.

The setting of the whitespace flags only affects imported data using the XML IMPORT FILE or XML IMPORT TEXT statements.

An example of a meaningful combination of these flags would be 49 as defined by:

78 WHITESPACE-PRESERVE-TAB-LF value
        WHITESPACE-STRIP-CONTROL +
        WHITESPACE-PRESERVE-TAB +
        WHITESPACE-PRESERVE-LF.

Example

XML SET WHITESPACE-FLAGS
 WHITESPACE-NORMALIZE.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related reference
Handling spaces and whitespace in XML
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML SET XSL-PARAMETERS

This statement has the following parameter:

Description

Parameter | Description
Parameter list | Literals or identifiers of data items, which comprise a list containing at least one name/value pair to be used whenever transform operations are performed. Names in the list must be nonnumeric and must correspond to parameters specified in the XSLT stylesheet to have any effect. Values in the list can be numeric or nonnumeric.

The XML SET XSL-PARAMETERS statement passes a list of name/value pairs to XML Extensions, where they are stored until one of the following occurs:

  • They are replaced by a subsequent execution of an XML SET XSL-PARAMETERS statement.
  • They are cleared by executing an XML CLEAR XSL-PARAMETERS statement.
  • They are cleared by flushing the cache (the statements XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE all clear the cache).
  • The COBOL run-unit terminates.

The saved parameters are used whenever any of the following transform operations occur:

  • The XML TRANSFORM FILE or XML TRANSFORM TEXT statement is executed.
  • The XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, or XML IMPORT TEXT statements reference an optional stylesheet.

A maximum of 20 name/value pairs may be specified. If more than 20 pairs are specified or the parameters are not specified as pairs, an error will be reported.

Note: In managed code, the name/value arguments are restricted to alphanumeric (PIC X) data items or literals. To use numeric, numeric literal (as in the example below), or other data item types use the XML SET XSL-PARAMETERS-NEW statement instead. See Managed Code Considerations for more information.

Example

XML SET XSL-PARAMETERS
 "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS-NEW
XML CLEAR XSL-PARAMETERS


XML SET XSL-PARAMETERS-NEW

Note: This statement is for managed code only.

This statement has the following parameter:

Description

Parameter | Description
Parameter list | Literals or identifiers of data items, which comprise a list containing at least one name/value pair to be used whenever transform operations are performed. Names in the list must be nonnumeric and must correspond to parameters specified in the XSLT stylesheet to have any effect. Values in the list can be numeric or nonnumeric.

The XML SET XSL-PARAMETERS-NEW is for managed code only and must be paired with the XML END XSL-PARAMETERS-NEW statement. It allows any type of COBOL data items. It passes a list of name/value pairs to XML Extensions, where they are stored until one of the following occurs:

  • They are replaced by a subsequent execution of an XML SET XSL-PARAMETERS statement.
  • They are cleared by executing an XML CLEAR XSL-PARAMETERS statement.
  • They are cleared by flushing the cache (the statements XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE all clear the cache).
  • The COBOL run-unit terminates.

The saved parameters are used whenever any of the following transform operations occur:

  • The XML TRANSFORM FILE statement is executed.
  • The XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, or XML IMPORT TEXT statements reference an optional stylesheet.

A maximum of 20 name/value pairs may be specified. If more than 20 pairs are specified or the parameters are not specified as pairs, an error will be reported.

Example

XML SET XSL-PARAMETERS-NEW
 "MY-COUNT", 7
XML END XSL-PARAMETERS-NEW.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML CLEAR XSL-PARAMETERS


XML CLEAR XSL-PARAMETERS

This statement has no parameters.

Description

The XML CLEAR XSL-PARAMETERS statement clears all sets of name/value pairs that have been stored in XML Extensions by the XML SET XSL-PARAMETERS statement.

Example

XML CLEAR XSL-PARAMETERS.
IF NOT XML-OK GO TO Z.
Parent topic: State management statements
Related information
XML INITIALIZE
XML TERMINATE
XML DISABLE ALL-OCCURRENCES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML DISABLE CACHE
XML ENABLE CACHE
XML FLUSH CACHE
XML GET FLAGS
XML GET WHITESPACE-FLAGS
XML TRACE
XML GET STATUS-TEXT
XML SET ENCODING
XML SET FLAGS
XML SET WHITESPACE-FLAGS
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW


COBOL considerations

This chapter provides information specific to using COBOL when developing an XML-enabled application. The primary topics discussed in this chapter include the following:

  • File management
  • Data conventions
  • Copybooks
  • Anonymous COBOL data structures
  • Limitations
  • Optimizations
  • Managed code considerations
Parent topic: XML Extensions


File management

The management of data files when using XML Extensions is similar, but not identical, to other COBOL data file management issues. These issues include the following:
  • File naming conventions
  • External XSLT Stylesheet File Naming External XSLT stylesheet file naming conventions
  • Other input file naming conventions
  • Other output file naming conventions
Parent topic: COBOL considerations


File naming conventions

File extensions are either used "as is" or forced to be a predetermined value. The conventions governing particular filename extensions when using XML Extensions are described in the topics that follow.

Note: A filename extension is never added if the filename is a URL; that is, the filename begins with "http//:", "https://", or "file://".
Parent topic: File management


External XSLT Stylesheet File Naming External XSLT stylesheet file naming conventions

External XSLT stylesheets may be referenced by XML Extensions. If the filename parameter supplied by the COBOL program does not contain an extension, the value .xsl is added to the filename.

XML Extensions uses the CBL_LOCATE_FILE library routine to locate an external XSLT stylesheet file (with the .xsl extension added) except when:

  • the external XSLT stylesheet filename parameter supplied by the COBOL program contains a directory separator character (such as "\" on Windows);
  • the file exists; or
  • the filename is a URL (the name begins with "http//:", "https://", or "file://").
Parent topic: File management
Related reference
Searching for files
CBL LOCATE FILE


Other input file naming conventions

All other input files referenced by XML Extensions will have a value of .xml added if the filename parameter supplied by the COBOL program does not contain an extension.

Parent topic: File management


Other output file naming conventions

All other output files referenced by XML Extensions will have a value of .xml added if the filename parameter supplied by the COBOL program does not contain an extension.

If the filename supplied by the COBOL program is a URL, then an error is returned because it is not possible to write directly to a URL.

Parent topic: File management


Data conventions

In XML Extensions, several suppositions have been made about data transformations between COBOL and XML, including those relating to the following issues:
  • Data representation
  • COBOL and character encoding
  • MF_XMLEXT_LOCAL_ENCODING environment variable
  • Windows character encoding
  • UNIX character encoding
  • FILLER data items
  • Missing intermediate parent names
  • Sparse COBOL records
Parent topic: COBOL considerations


Data representation

COBOL numeric data items are represented in XML as numeric strings. A leading minus sign is added for negative values. Leading zeros (those appearing to the left of the decimal point) are removed. Trailing zeros (those appearing to the right of the decimal point) are likewise removed. If the value is an integer, no decimal point is present.

COBOL nonnumeric data items are represented as text strings and have trailing spaces removed (or leading spaces, if the item is described with the JUSTIFIED phrase). Note, however, that in edited data items, leading and trailing spaces are preserved. In addition, any embedded XML special characters are represented by escape sequences; the ampersand (&), less than (<), greater than (>), quote ("), and apostrophe (') characters are examples of such XML special characters.

Note: For more information, see Handling Spaces and Whitespace in XML.

On Windows platforms, nonnumeric displayable data are normally encoded using Microsoft's OEM or ANSI data format. On output, these data are converted to the standard Unicode 8-bit transformation format, UTF-8. On input, data is converted to the OEM or ANSI data format. If the XML SET ENCODING statement is used to specify "UTF-8", then the internal data format is UTF-8. For more information, see the discussion of Windows Character Encoding.

On UNIX platforms, nonnumeric displayable data are normally encoded using a "local" character encoding that the UNIX system uses. Typically, this may be Latin-1 or Latin-9. On output, these data are converted to the standard Unicode 8-bit transformation format, UTF-8. On input, data is converted to the systems internal format. If the XML SET ENCODING statement is used to specify "UTF-8", then the internal data format is UTF-8. For more information on selecting an appropriate "local" character encoding, refer to the discussion of UNIX Character Encoding.

Parent topic: Data conventions
Related reference
Handling spaces and whitespace in XML
XML SET ENCODING


COBOL and character encoding

XML Extensions uses UTF-8 character encoding for exporting XML documents. (UTF-8 is a byte-oriented encoding form of Unicode that has been designed for ease-of-use with existing ASCII-based systems.) Imported documents are interpreted according to the character encoding specified in the XML header, resulting in an internal Unicode representation of the characters. Because XML is Unicode-based and COBOL is not, a transcoding is generally required when moving character data between COBOL and XML. XML Extensions supports various means of specifying the transcoding that should occur in these cases. The following sections have related information regarding character encoding considerations.

Parent topic: Data conventions
Related reference
State management statements


MF_XMLEXT_LOCAL_ENCODING environment variable

The MF_XMLEXT_LOCAL_ENCODING environment variable is used to specify the "local" character encoding. This environment variable is ignored if the XML SET ENCODING statement sets the encoding to UTF-8. The interpretation of this environment variable also varies between Windows and UNIX character encoding, as discussed in Windows character encoding and UNIX character encoding.
Parent topic: Data conventions


Windows character encoding

Under Windows, the COBOL runtime uses OEM or ANSI character encoding. Therefore, the Windows implementation of XML Extensions also supports OEM or ANSI character encoding for local character encoding. The MF_XMLEXT_LOCAL_ENCODING environment variable is ignored by the Windows implementation of XML Extensions.

Note: Microsoft originally introduced OEM character encoding for MS-DOS. While there are multiple OEM code pages in use, the Windows operating system provides interfaces that allow conversion between the OEM code page in use and Unicode. XML Extensions does not need to differentiate between code pages. The ANSI code page can be selected as the native character set, in which case, XML Extensions uses the ANSI code page in use for the conversion to/from Unicode when using the local character encoding.
Parent topic: Data conventions


UNIX character encoding

On UNIX systems, the COBOL runtime is normally not concerned with the data encoding used by the underlying operating system. However, note that Latin-1 (ISO-8859-1) is important for the U.S. and Latin-9 (ISO-8859-15) is significant for Western Europe because it contains the Euro currency symbol.

The MF_XMLEXT_LOCAL_ENCODING Environment Variable may specify the built-in and predefined values of MF_LATIN_1 and MF_LATIN_9. These values are used to designate that either Latin-1 or Latin-9 is being used as the local character encoding. Internal translation functions convert between either Latin-1 or Latin-9 (in COBOL memory) and UTF-8 (in the XML document). The value of the environment variable is case insensitive, with hyphen and underscore characters being optional. For example, "MF_LATIN_9", "Mf-Latin-9", and "mflatin9" are equivalent.

If the value of the MF_XMLEXT_LOCAL_ENCODING environment variable is not specified, then MF_LATIN_9 is used as the default.

If the value of the MF_XMLEXT_LOCAL_ENCODING environment variable is specified with a value that is not MF_LATIN_1 or MF_LATIN_9, then the value that is passed must be a name recognized by the iconv library. The iconv library can perform other conversions. In this case, the spelling may need to be exact (for example, the value may be case sensitive, and hyphens and underscores would be required). The exact spelling of the value of the MF_XMLEXT_LOCAL_ENCODING environment variable is specific to the iconv library on the platform in use.

Note: Micro Focus does not provide an iconv library. The developer must acquire an appropriate package.

The value of the MF_ICONV_NAME environment variable, if one is defined, is used to locate the iconv library (which must be a shared object) on the local system. For example: MF_ICONV_NAME=/usr/local/bin/libiconv.so

If the MF_ICONV_NAME environment variable is not set, then the PATH environment variable is searched for either of the specific names, iconv.so or libiconv.so (in that order).

Parent topic: Data conventions


FILLER data items

Unnamed data description entries, referred to as FILLER data items in this section, may be used to generate XML text without starting a new XML element name. Specifying named and unnamed elementary data items subordinate to a named group generates XML mixed content for an element named by the group name.

Numeric FILLER data items will not reliably produce well-formed XML sequences. For this reason, FILLER data items should always be nonnumeric PIC X or PIC A.

For example, the following COBOL sequence:
 01 A.
 02 FILLER Value "ABC".
 02 B Pic X(5) Value "DEF".
 02 FILLER Value "GHI".
generates the following well-formed XML sequence:
 <a>ABC<b>DEF</b>GHI</a>

FILLER data items, however, are treated differently than named data. All leading and/or trailing spaces are preserved, so that the length of the data is the same as the COBOL data length. For more information, see Handling Spaces and Whitespace in XML.

In addition, the data is treated as PCDATA; that is, embedded XML special characters are preserved. This allows short XHTML sequences, such as "break" to be represented as FILLER (for example, <br/>). XHTML (eXtensible HyperText Markup Language) is based on HTML 4, but with restrictions such that an XHTML document is also a well-formed XML document. For example, the following COBOL sequence:
 01 A.
 02 FILLER Value "<br />".
 02 B Pic X(5) Value "DEF".
 02 FILLER Value "GHI".
generates the following well-formed XML sequence:
<a><br /><b>DEF</b>GHI</a>
Care must be taken in placing XML special characters in FILLER data items, since the resultant XML sequence might not be well-formed. For example, the following COBOL sequence:
01 A.
 02 FILLER Value "<br".
 02 B Pic X(5) Value "DEF".
 02 FILLER Value "GHI".
generates the following syntactically malformed XML sequence:
 <a><br<b>DEF</b>GHI</a>

Whenever FILLER data items are present in a data item that is referenced by the XML EXPORT statements, the resulting document is checked to ensure that the resultant XML document is well-formed. When the document is not well-formed, an appropriate status value is returned to the COBOL program.

Parent topic: Data conventions
Related reference
Handling spaces and whitespace in XML
XML EXPORT FILE
XML EXPORT TEXT


Missing intermediate parent names

A capability for handling missing intermediate parent names has been included to make programs that deal with "flattened" data items, such as Web services, less complicated.

Sometimes it is possible for XML Extensions to reconstruct missing intermediate parent names in a COBOL data structure. These missing names may be generated in either of two ways:

  • Unique Element Names. Use this technique to determine whether the element name is unique.
  • Unique Identifier. Use this method to determine whether the unique identifier (uid) attributes of the element name are provided. If this is true, then the intermediate parent names may also be generated.
  • Unique element names
  • Unique identifier
Parent topic: Data conventions


Unique element names

Consider the following COBOL data structure:
 01 Customer-Address.
    02 Name Pic X(64).
    02 Address-1 Pic X(64).
    02 Address-2 Pic X(64).
    02 Address-3.
       03 City Pic X(32).
       03 State Pic X(2).
       03 Zip Pic 9(5).
    02 Time-Stamp Pic 9(8).
A well-formed and valid XML document that could be imported into this structure is shown below:
<?xml version="1.0" encoding="UTF-8" ?>
<customer-address>
 <name>Micro Focus</name>
 <address-1> 8310 Capital of Texas Highway North </address-1>
 <address-2> Building 2, Suite 100 </address-2>
 <address-3>
  <city>Austin</city>
  <state>TX</state>
  <zip>78731</zip>
 </address-3>
 <time-stamp>13263347</time-stamp>
</customer-address >
A well-formed (but not valid) "flattened" version of an XML document that could also be imported into this structure is displayed here:
<? xml version="1.0" encoding="UTF-8" ?>
<customer-address>
 <name>Wild Hair Corporation</name>
 <address-1>8911 Hair Court</address-1>
 <address-2>Sweet 4300</address-2>
 <city>Lostin</city>
 <state>TX</state>
 <zip>70707</zip>
 <time-stamp>99999999</time-stamp>
</customer-address>
Parent topic: Missing intermediate parent names


Unique identifier

The unique identifier (uid) attribute is generated by an XML EXPORT FILE or XML EXPORT TEXT statement if XML attributes are enabled. Attributes may be enabled by using the XML ENABLE ATTRIBUTES statement before the XML EXPORT statements.

Using the same COBOL data structure illustrated for unique element names (described in the previous section), a well-formed XML document (generated by XML EXPORT), which contains attributes-including uids-that could be imported into this structure is shown below:
<?xml version="1.0" encoding="UTF-8" ?>
<customer-address uid ="V6" line="18" offset="0" length="239" category="group" kind="GRP" type="xsd:string" xmlns:xtk="http://www.microfocus.com/xcentricity/xml-extensions/symbol-table/">
<name uid="V7" line="19" offset="0" length="64" category="alphanumeric" kind="ANS" type="xsd:string">Wild Hair
Corporation</name>
<address-1 uid="V8" line="21" offset="64" length="64" category="alphanumeric" kind="ANS" type="xsd:string">8911 Hair
Court</address-1>
<address-2 uid="V9" line="23" offset="128" length="64" category="alphanumeric" kind="ANS" type="xsd:string">Sweet
4300</address-2>
<address-3 uid="V10" line="24" offset="192" length="39" category="group" kind="GRP" type="xsd:string">
 <city uid="V11" line="25" offset="192" length="32" type="alpha
 numeric" kind="ANS" type="xsd:string">Lostin</city><state uid="V12" line="26" offset="224" length="2" category="alphanumeric" kind="ANS" type ="xsd:string">TX</state>
<zip uid="V13" line="27" offset="226" length="5" category="numeric" kind="NSU" type="xsd:decimal" usage="display" scale="0" precision="5"> 70707</zip></address-3>
<time-stamp uid="V14" line="28" offset="231" length="8" category="numeric" kind="NSU" type="xsd:decimal" usage="display" scale="0" precision=" 8">99999999</time-stamp>
</customer-address>

A well-formed "flattened" version of an XML document that could also be imported into this structure is displayed below. The uid attributes were captured from an XML document (such as the one shown previously) that was generated by an XML EXPORT statement. These attributes may be captured by an XSLT stylesheet or other process, and then added again before the XML IMPORT FILE or XML IMPORT TEXT statement. This is accomplished by combining the element name and the uid attribute value to form a new element name. For example, <name uid="V7">, could be used to generate a new element name "name.V7".

    <?xml version="1.0" encoding="UTF-8" ?>
<customer-address>
  <name uid="V7">>Wild Hair Corporation</name>
  <address-1 uid="V8">>8911 Hair Court</address-1>
  <address-2 uid="V9">>Sweet 4300</address-2>
  <city uid="V11">Lostin</city>
  <state uid="V12">TX</state>
  <zip uid="V13">70707</zip>
  <time-stamp uid="V14">99999999</time-stamp>
</customer-address>
Parent topic: Missing intermediate parent names


Sparse COBOL records

An input XML document need not contain all data items defined in the original structure. This applies to both scalar and array elements. In order to place array elements correctly, a subscript must be supplied when array elements are not in canonical order.

For example, the following XML document uses the subscript attribute to position the array to the second element and then to the fourth element.

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <data-table>
    [
    <table-1 subscript="2">
      <x>B</x>
      <n>2</n>
    </table-1>
    <table-1 subscript="4">
      <x>D</x>
      <n>4</n>
    </table-1>
    ]
  </data-table>
</root>
Parent topic: Data conventions


Copybooks

Under most circumstances, you should make use of the copybooks that are provided in XML Extensions. Various points to consider, however, when using copybooks with XML Extensions include the following:

  • Statement definitions
  • REPLACE statement considerations
  • Displaying status information
  • Application termination
Parent topic: COBOL considerations
Related reference
Development components
Making a program skeleton


Statement definitions

The copybook, lixmlall.cpy, is required to define the XML statements and to define some data-items that are referenced. This copybook should be copied at the beginning of the Working-Storage Section of the source program. This copybook copies the remaining copybooks used by XML Extensions. In general, do not modify or edit the contents of this copybook or the copybooks that it copies (lixmdef.cpy and lixmlrpl.cpy).
Parent topic: Copybooks


REPLACE statement considerations

The copybook, lixmlall.cpy, contains a REPLACE statement to define the XML statements. A COBOL REPLACE statement overrides any lexically preceding REPLACE statement. Thus, in cases where the user's program contains a REPLACE statement, it may not be possible to use the lixmlall.cpy file. For this reason, the lixmlrpl.cpy copybook, which is copied by the lixmlall.cpy file, is provided as part of XML Extensions. The lixmlrpl.cpy file contains the operands of the REPLACE statement needed to define the XML statements, but not the REPLACE statement itself. Accordingly, the user's REPLACE statement may be augmented by copying lixmlrpl.cpy into the REPLACE statement as follows:
REPLACE
 *> include user's replacements here
 COPY "lixmlrpl.cpy". *> define XML statements
 . *> end of combined REPLACE statement
COPY "lixmldef.cpy". *> XML data definitions

When this is done, the lixmall.cpy file need not be copied in the source program.

Note: If there are multiple REPLACE statements in your source program, each REPLACE statement that precedes any XML statements needs to copy the lixmlrpl.cpy file into the REPLACE statement to preserve the statements for replacement.
The InstantSQL product has a copybook, lisqlall.cpy, which contains a REPLACE statement to define the SQL statements. In cases where InstantSQL is used with XML Extensions, neither the lixmlall.cpy nor the lisqlall.cpy copybook should be used. Instead, create a copybook (for example, named isqlxml.cpy) with the following contents:
REPLACE
 *> optionally include user's replacements
 COPY "lisqlrpl.cpy". *> define SQL statements
 COPY "lixmlrpl.cpy". *> define XML statements
 . *> end of combined REPLACE statement
COPY "lisqldef.cpy". *> SQL data definitions
COPY "lixmldef.cpy". *> XML data definitions

Use this copybook in place of lixmlall.cpy and lisqlall.cpy.

Parent topic: Copybooks


Displaying status information

The copybook, lixmldsp.cpy, is provided as an aid in retrieving and presenting status information. This copybook defines the Display-Status paragraph and contains the following text:
Display-Status.
 If Not XML-IsSuccess
 Perform With Test After Until XML-NoMore
 XML GET STATUS-TEXT
 Display XML-StatusText
 End-Perform
 End-If.

The DISPLAY statement, Display XML-StatusText, displays status information on the terminal display. You may edit this statement, as necessary, for your application. For example, the definition of the XML-StatusText field in the lixmldef.cpy copybook may be altered from the default of 80 to change the size of the buffer used to contain XML status information.

While this logic is normally used in the application termination logic, it may be used at any time in the program flow. For example:
XML TRANSFORM FILE "A" "B" "C".
 Perform Display-Status.
Parent topic: Copybooks
Related reference
XML GET STATUS-TEXT


Application termination

The copybook, lixmltrm.cpy, provides an orderly way to shut down an application. This copybook contains the following text:
Display "Status: " XML-Status.
Perform Display-Status.
XML TERMINATE.
Perform Display-Status.

The first line may be modified or removed, as you choose. The first PERFORM statement displays any pending status messages (from a previous XML statement). The XML TERMINATE statement shuts down XML Extensions. The second PERFORM statement displays any status from the XML TERMINATE statement.

The following logic is sufficient to successfully terminate XML Extensions:
Z.
Copy "lixmltrm.cpy".
Stop Run.
Copy "lixmldsp.cpy".

The Z. paragraph-name is where the exit logic begins. The flow of execution may reach here by falling through from the previous paragraph or as the result of a program branch. The STOP RUN statement is used to prevent the application from falling through to the Display-Status paragraph. An EXIT PROGRAM or GOBACK statement also may be used, if appropriate.

Parent topic: Copybooks
Related reference
XML TERMINATE


Anonymous COBOL data structures

XML Extensions now supports the use of an anonymous COBOL data structure when exporting and importing documents. An anonymous data structure is any data area that is the same size or larger than the data structure indicated by the ModelFileName#DataName parameter of various XML Extensions statements. This means that exporting or importing can be done to Linkage Section data items that are based on either arguments passed to a called program or a pointer using the SET statement (for example, into allocated memory). Importing and exporting can also occur with data items having the external attribute. (An external attribute is the attribute of a data item obtained by specification of the EXTERNAL clause in the data description entry of the data item or of a data item to which the subject data item is subordinate.)
Parent topic: COBOL considerations


Limitations

This section describes the limitations of XML Extensions and the way in which those limitations affect the development of an XML-enabled application. The topics discussed in this context include:
  • Data items (data structures)
  • Edited data items
  • Wide and narrow characters
  • Data item definitions and size
  • Data naming
  • OCCURS restrictions
  • Reading, writing, and the Internet
Parent topic: COBOL considerations


Data items (data structures)

The XML IMPORT FILE, XML IMPORT TEXT, XML EXPORT FILE, and XML EXPORT TEXT statements operate on a single COBOL data item. As you would expect, this data item may be (and usually will be) a group item. The COBOL program must move all necessary data to the selected data item before using the XML EXPORT FILE or XML EXPORT TEXT statements and retrieve data from the data item after using the XML IMPORT FILE or XML IMPORT TEXT statement.

The referenced data item-and any items contained within it, if it is a group item-has the following limitations:

  • REDEFINES and RENAMES clauses are not allowed.
  • FILLER data items must be nonnumeric.
  • The data item must be the same size or larger than the data item specified in the model files, but it is not required to be the same data item. For additional information, see Anonymous COBOL Data Structures.
Parent topic: Limitations
Related reference
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
Anonymous COBOL data structures


Edited data items

Numeric edited, alphabetic edited, and alphanumeric edited data items are allowed. The data items are represented in an XML document in the same format as the data items would exist in COBOL internal storage. That is, no editing or de-editing operations are performed for edited data items during import from XML or export to XML. Leading and trailing spaces are preserved. For more information, see Handling Spaces and Whitespace in XML.
Parent topic: Limitations
Related reference
Handling spaces and whitespace in XML


Wide and narrow characters

XML was developed to use wide (16-bit) Unicode characters as its natural mode. COBOL uses narrow (8-bit) ASCII characters. All XML data that is generated by XML Extensions is represented in UTF-8 format, which is essentially ASCII with extensions for representing 16-bit and larger characters and is compatible with Unicode. (UTF-8 is a form of Unicode.)
Parent topic: Limitations


Data item definitions and size

When defining a data item, the ACU-style COMP-2 data item (that is, a data item under the effect of COMP2"DECIMAL") is unsupported.

By its nature, XML has no limits on data item size. COBOL does have size limitations for its data items. Many XML documents have been standardized and such standards include limitations on data items, but the COBOL program must still be written to deal with data item size constraints. When a nonnumeric data item is truncated on import, a warning status value is produced by XML Extensions.
Parent topic: Limitations


Data naming

While the COBOL language allows a data-name to begin with a digit, XML does not allow an element name to begin with a digit. For example, the following line defines a valid COBOL data-name, but when using XML Extensions, the data-name will result in an invalid XML element name:

03 1099-something-field
The COBOL compiler will not detect the issue with the data-name with respect to XML Extensions. However, XML Extensions will detect the problem at runtime and report the error. A workaround that avoids the need to modify any COBOL Procedure Division code when data-names begin with a digit is to add a non-digit initial character to the data-name and then redefine that data item with the original data-name, as in the following:
03 x1099-something-field PIC X(10).
03 1099-something-field REDEFINES x1099-something-field
 SAME AS x1099-something-field.

The data-name 1099-something-field will result in the Procedure Division compiling successfully and the x1099-something-field will result in a valid element name for XML Extensions.

Parent topic: Limitations


OCCURS restrictions

Although, XML has no limits on the number of occurrences of a data item, COBOL does have such occurrence limits. As with data item size, the COBOL program must deal with this difference.
Parent topic: Limitations


Reading, writing, and the Internet

It is possible to read any XML document (including XML model files) from the Internet via a URL. However, it is not possible to write or export an XML document directly to the Internet via a URL.
Parent topic: Limitations


Optimizations

Some optimizations have been added to XML Extensions to improve performance and reduce the size of the generated documents. Refer also to XML Extensions Statements Reference for more information.
  • OCCURS DEPENDING
  • Empty occurrences
  • Cached XML documents
Parent topic: COBOL considerations
Related reference
XML Extensions statements reference


OCCURS DEPENDING

As expected, on output, the XML EXPORT FILE and XML EXPORT TEXT statements will limit the number of occurrences of a group to the value of the DEPENDING variable. Additional occurrences may be omitted if they contain no data. For more information, see Empty Occurrences.

On input, the XML IMPORT FILE and XML IMPORT TEXT statements will store the value of the DEPENDING variable. The XML IMPORT FILE and XML IMPORT TEXT statements will also store all occurrences in the document (up to the maximum occurrence limit), regardless of the value of the DEPENDING variable.

Parent topic: Optimizations
Related reference
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT


Empty occurrences

On output, the XML EXPORT FILE or XML EXPORT TEXT statements recognize occurrences within a group that contain only spaces and zeros. Specifically, an empty data item is an alphanumeric item that contains either all spaces or zero characters, or a numeric item that contains a zero value.

If all of the elementary data items in an occurrence of a group are empty, and if the occurrence is not the first occurrence, then no data is generated for that occurrence. This prevents the repetition of occurrences that contain only spaces and zeros.

You may enable all occurrences using the XML ENABLE ALL-OCCURRENCES statement, when generating the document (with XML export operations).

Parent topic: Optimizations
Related reference
XML ENABLE ALL-OCCURRENCES
XML EXPORT FILE
XML EXPORT TEXT


Cached XML documents

Since XSLT stylesheet, template, and schema documents are largely invariant, performance can usually be improved by caching previously loaded versions of these documents in memory.

For some applications, it may be useful to disable caching. If XSLT stylesheet, template, or schema files are generated or replaced in real time, then the cached documents would need to be replaced as well.

If system resource availability becomes critical because a large number of documents are occupying virtual memory, then caching may cause system degradation.

Several XML statements may be used to enable or disable document caching. These statements include: XML ENABLE CACHE, XML DISABLE CACHE, and XML FLUSH CACHE. By default, caching is enabled.

Parent topic: Optimizations
Related reference
XML ENABLE CACHE
XML DISABLE CACHE
XML FLUSH CACHE


Managed code considerations

XML Extensions is available in .NET managed code on Windows.
  • New XML statement
  • XML statement restrictions
Parent topic: COBOL considerations


New XML statement

One new statement has been added for managed code only. It must be terminated by the appropriate END statement as shown below.
XML SET XSL-PARAMETERS-NEW
 <name-value-pairs>
XML END XSL-PARAMETERS-NEW.

It functions just like the corresponding XML SET XSL-PARAMETERS statement except that it allows any data type for the value arguments in managed code. The XML SET XSL-PARAMETERS statement can be used in managed code but it only allows alphanumeric (PIC X) data items as arguments.

Parent topic: Managed code considerations
Related reference
XML SET XSL-PARAMETERS
XML SET XSL-PARAMETERS-NEW


XML statement restrictions

The XML GET FLAGS and XML SET FLAGS statements have a restriction in managed code. The Flags argument must be a PIC X(4) COMP-X data item or equivalent [for example, PIC 9(10) BINARY(4) is equivalent]. If you wish to use a different numeric type for Flags in your COBOL program then you can use the MOVE statement to or from the XML-Flags data item that is defined in the XML-data-group in lixmldef.cpy, as shown in the following examples.
XML GET FLAGS XML-Flags.
MOVE XML-Flags TO Your-Flags.
MOVE Your-Flags TO XML-Flags.
XML SET FLAGS XML-Flags.
Parent topic: Managed code considerations
Related reference
XML GET FLAGS
XML SET FLAGS


XML considerations

This chapter provides information specific to using XML when using XML Extensions with Visual COBOL to develop an XML-enabled application. The primary topics discussed in this chapter include:
  • XML and character encoding
  • Document type definition support
  • XSLT stylesheet files
  • Handling spaces and whitespace in XML
  • Schema files
Parent topic: XML Extensions


XML and character encoding

For internal representation, XML documents use the Unicode character encoding standard. Unicode represents characters as 16-bit items. For external representation, most XML documents are encoded using the standard Unicode transformation formats, UTF-8 or UTF-16. XML documents created by XML Extensions are always encoded for external presentation using the UTF-8 representation. UTF-8 is a method of encoding Unicode where most displayable characters are represented in 8-bits. Characters in the range of 0x20 to 0x7e (the normal displayable character set) are indistinguishable from standard ASCII.

The XML SET ENCODING statement allows the developer to specify the character encoding of data within a COBOL data structure. The developer may use this statement to switch between the local character encoding and UTF-8. Note that even though the XML SET ENCODING statement does not affect the character encoding of the XML document, it does affect the character encoding of the data in the COBOL program. For more information, see Data Representation.

Parent topic: XML considerations
Related reference
XML SET ENCODING


Document type definition support

A DTD is required in an external XSLT stylesheet that uses entity references other than the predefined XML entity references. Using non-predefined entity references commonly occurs when the XSLT stylesheet is generated by tools for generating transformations from XML to HTML or XHTML, that is, to generate a page to be displayed by a browser. Often the tool will not add the DTD. A DTD that defines the entities must be added after the XSLT stylesheet is generated and before it is used by XML Extensions. Here is an example of such a DTD for XHTML entities:
<!DOCTYPE root [
 <!ENTITY % HTMLlat1 PUBLIC
 "-//W3C//ENTITIES Latin 1 for XHTML//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent">
%HTMLlat1;
 <!ENTITY % HTMLsymbol PUBLIC
 "-//W3C//ENTITIES Symbols for XHTML//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent">
%HTMLsymbol;
 <!ENTITY % HTMLspecial PUBLIC
 "-//W3C//ENTITIES Special for XHTML//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent">
%HTMLspecial;]>
Parent topic: XML considerations


XSLT stylesheet files

XSLT (Extensible Stylesheet Language Transformations) stylesheet files are used to transform an XML document into another XML document or another type of document-not necessarily in XML format; for example, HTML, PDF, RTF, and so forth. An XSLT stylesheet is an XML document. XML Extensions has specific statements, XML TRANSFORM FILE and XML TRANSFORM TEXT, which are used for performing XSLT stylesheet transformations. In addition, the import and export statements, XML IMPORT FILE, XML IMPORT TEXT, XML EXPORT FILE, and XML EXPORT TEXT, allow an external XSLT stylesheet to be specified as a parameter, making it possible to transform a document while importing or exporting XML documents.

The format of XML documents generated by XML Extensions matches the form of the specified COBOL data structure. Often the COBOL developer must process XML documents that are defined by an external source. It is likely that the format of the COBOL-generated XML document will not conform to the document format that meets the external requirements.

The recommended course of action is to use an external XSLT stylesheet file to transform between the COBOL-generated XML document format and the expected document format. XSLT stylesheets are extremely powerful.

Keep in mind that XSLT stylesheets are unidirectional. Therefore, it is possible that you will have to design two external XSLT stylesheets for each COBOL data structure: one for input, which converts the required document format to COBOL format, and one for output, which converts COBOL format to the required external format.

Parent topic: XML considerations
Related reference
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT


Handling spaces and whitespace in XML

XML Extensions normally strips trailing spaces from COBOL data items when exporting data and restores trailing spaces to COBOL data items when importing data. Leading spaces are also removed and added for justified data items.

This default behavior can be modified using the XML SET FLAGS statement, but the default behavior is generally best. The normal treatment of leading and trailing spaces does not apply to FILLER data items or edited data items.

Once the data is in XML, further consideration must be given to XML treatment of whitespace, which includes spaces, carriage returns, and line feeds. XML provides a built-in attribute named xml:space, which takes a value of "preserve" or "default". The value "preserve" specifies that whitespace in an element should be preserved. The value "default" specifies that leading and trailing whitespace may be removed and embedded whitespace may be normalized to a single space wherever it occurs. The value "default" is the default treatment of whitespace in XML and is generally not changed unless one is trying to produce poetry or other special output.

XML Extensions has various rules for handling of the individual whitespace characters during import or export as follows:

  • Space characters are preserved by XML Extensions during import and export, except for leading and trailing spaces as described in the first paragraph of this topic.
  • During import, all characters received from the parser for XML text nodes for import are preserved. Preserving all characters is the default behavior, unless the XML SET WHITESPACE-FLAGS statement is used to change the whitespace flags from their default value of 0. Since the introduction of XML SET WHITESPACE-FLAGS, this is a change in behavior. Before this new behavior, characters less than space, which include line feed, carriage return and tab characters, were unconditionally removed on import. The new statement XML SET WHITESPACE-FLAGS can set various whitespace handling behaviors, one of which is the old behavior if that behavior is desired.
  • During export, line feed, carriage return and tab characters present in the exported COBOL data item are preserved in the exported text node. Export to a file may cause LF characters to be translated to a CR/LF sequence on some operating systems (for example, Windows).

The value, "preserve" or "collapse" of the XML reserved attribute XML-space is ignored by XML Extensions unless the parser acts on this attribute.

When using XSLT stylesheets, the xsl:strip-space and xsl:preserve-space elements indicate how whitespace should be handled while transforming a document. Preserving whitespace is the default, but tools that generate XSLT stylesheets might insert xsl:strip-space elements.

Be aware that when documents are transformed to HTML for display by a browser, many browsers strip whitespace as they are allowed to do. Displaying data in tables is generally necessary to align data in columns rather than using whitespace as is generally done in COBOL report output without XML support.

Parent topic: XML considerations
Related reference
XML GET WHITESPACE-FLAGS
XML SET WHITESPACE-FLAGS


Schema files

Schema files are used to assure that the data within an XML document conforms to expected values. For example, an element that contains a zip code may be restricted to a numeric integer. Schema files can also limit the length or number of occurrences of an element as well as guarantee that elements occur in the expected order.

A schema file may be applied to an XML document using any of the following methods:

  • The entire schema file may reside within the document. (This situation is infrequent.)
  • A link to the schema file may be placed in the document. (This technique is more common.)
  • A process that loads a given XML document may also load a schema file that controls the document.
Note: In the Windows implementation, the Microsoft MSXML parser 6.0 ignores the document type definition (DTD) when validating an XML document against a schema file. Any entities declared in the DTD will not be defined and cannot be referenced. If any entities other than the predefined XML entities are referenced, the document is not well-formed and will fail to load, much less validate. Thus, when a DTD is generated to define entities in an exported document, the exported document should be transformed prior to being imported so as not to contain entity references. For information on generating a DTD to define entity references, see Document Type Definition Support.
Parent topic: XML considerations


Appendix A XML Extensions examples

This appendix contains a collection of programs or program fragments that illustrate how the XML Extensions statements are used. These examples are tutorial in nature and offer useful techniques to help you become familiar with the basics of using XML Extensions. More examples can be found in the XML Extensions examples directory, Examples.

Note: You will find it instructive to examine these examples first before referring to Appendix B: XML Extensions Sample Application Programs , which describes how to use and access the more complete application programs that are included with the XML Extensions development system.

The following example programs are provided in this appendix:

  • Example 1 Import file and export file
  • Example 2 Export file and import file with XSLT stylesheets
  • Example 3 Export file and import file with OCCURS DEPENDING
  • Example 4 Export file and import file with sparse arrays
  • Example 5 Export and import text
  • Example 6 Export file and import file with directory polling
  • Example 7 Export file, test well-formed file, and validate file
  • Example 8 Export text, test well-formed text, and validate text
  • Example 9 Export file, transform file, and import file
  • Example 10 Diagnostic messages
  • Example 11 Import file with missing intermediate parent names
  • Example batch files
Parent topic: XML Extensions
Related reference
Development components
Typical development process example
Appendix B: XML Extensions sample application programs


Example 1 Import file and export file

This program first writes (or exports) an XML document file from the content of a COBOL data item. Then the program reads (or imports) the same XML document and places the content in the same COBOL data item.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 1
  • Batch file for example 1
  • Program description for example 1
  • Data item for example 1
  • Other definitions for example 1
  • Program structure for example 1
  • Execution results for example 1
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE


Development for example 1

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 1 Import file and export file
Related information
Batch file for example 1
Program description for example 1
Data item for example 1
Other definitions for example 1
Program structure for example 1
Execution results for example 1


Batch file for example 1

The following DOS commands may be entered into a batch file. These commands build and execute example01.int.

Line | Statement
1 | cobol example01.cbl xmlgen(ws) noobj;
2 | start /w run example01

Line 1 compiles the example01.cbl source file and generates an XML-format model file named example01.xml.

Line 2 executes example01.int. On line 2, the start /w sequence is included only as good programming practice.

Parent topic: Example 1 Import file and export file
Related information
Development for example 1
Program description for example 1
Data item for example 1
Other definitions for example 1
Program structure for example 1
Execution results for example 1


Program description for example 1

This COBOL program illustrates how an XML document is generated from a COBOL data item, and then how the content of an XML document may be converted into COBOL data format and stored in a COBOL data item.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an XML document with the filename of address01.xml using the XML EXPORT FILE statement.

Next, the content of the XML document is imported from the file, address01.xml, and placed in the same data item using the XML IMPORT FILE statement.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 1 Import file and export file
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML INITIALIZE
XML TERMINATE
XML GET STATUS-TEXT
Related information
Development for example 1
Batch file for example 1
Data item for example 1
Other definitions for example 1
Program structure for example 1
Execution results for example 1


Data item for example 1

The content of the COBOL data item defined in the copybook, s-struct.cpy, is as follows:

*
* Title: s-struct.cpy: XML Extensions sample data structure.
*
* Copyright  © Micro Focus 2008-2013.
* All rights reserved.
*
* Version Identification:
* $Revision$
* $Date$
* $URL$
*
 01 Address-Struct.
 02 Name Pic X(64)
 Value "Specialty Cowboy Boots Company".
 02 Address-1 Pic X(64)
 Value "1050 North San Antonio Street".
 02 Address-2 Pic X(64) Value "Suite 200".
 02 Address-3.
 03 City Pic X(32) Value "Austin".
 03 State Pic X(2) Value "TX".
 03 Zip Pic 9(5) Value 78701.
 02 Country Pic X(64)
 Value "United States of America".
 02 Time-Stamp Pic X(23).

This data item stores company address information. The last field of the item is a time stamp containing the time that the program was executed. This item is included to assure the person observing the execution of the example that the results are current. The time element in the generated XML document should change each time the example is run and should contain the current time.

Parent topic: Example 1 Import file and export file
Related information
Development for example 1
Batch file for example 1
Program description for example 1
Other definitions for example 1
Program structure for example 1
Execution results for example 1


Other definitions for example 1

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy , defines a data item named XML-data-group. The content of this COBOL data item is as follows:
01 XML-data-group.
 03 XML-Status PIC S9(4) COMP-5.
 88 XML-IsSuccess VALUE XML-Success.
 88 XML-OK VALUE XML-WarningLimit
 THROUGH XML-StatusNonFatal.
 88 XML-IsDirectoryEmpty
 VALUE XML-InformDirectoryEmpty.
 03 XML-Status-Edited PIC +9(4).
 03 XML-StatusText PIC X(80).
 03 XML-MoreFlag PIC X COMP-X VALUE 0.
 88 XML-NoMore VALUE 0.
 03 XML-UniqueID PIC X(40).
 03 XML-Flags PIC X(4) COMP-X.
 03 XML-COBOL-Version PIC X(4) COMP-X VALUE 12. *>Used by XMLSetVersion
 03 XML-XMLIF-Version PIC X(4) COMP-X VALUE 0. *>Set by XMLSetVersion

Various XML statements may access one of more fields of this data item. For example, the XML EXPORT FILE statement returns a value in the XML-Status field. The XML GET STATUS-TEXT statement accesses the XML-StatusText and XML-MoreFlag fields.

Parent topic: Example 1 Import file and export file
Related reference
XML EXPORT FILE
XML GET STATUS-TEXT
Related information
Development for example 1
Batch file for example 1
Program description for example 1
Data item for example 1
Program structure for example 1
Execution results for example 1


Program structure for example 1

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example01.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML Document

COBOL Statement

Description

Move … To Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT FILE Address-Struct
             "address01.xml" "Address-Struct".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML Document

COBOL Statement

Description

Initialize Address-Struct.

Ensure that the Address-Struct item contains no data.

XML IMPORT FILE Address-Struct
             "address01.xml" "Address-Struct".

Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program Exit Logic

COBOL Statement

Description

Z.

Paragraph-name that is a target of error condition GO TO statements.

Copy "lixmltrm.cpy".

Copy in the termination test logic (see the Termination Test Logic table).

Stop Run.

Terminate the COBOL program.

Copy "lixmldsp.cpy".
 Copy in the status display logic (see the Status Display Logic table).

Termination Test Logic

This code is found in the copybook, lixmltrm.cpy.

This code occurs after the paragraph named Z, so that any error condition is obtained here via a GO TO Z statement. If there are no errors, execution "falls through" to these statements.

COBOL Statement

Description

Display "Status: " XML-Status.

Display the most recent return status value (if there are no errors, this should display zero).

Perform Display-Status.

Perform the Display-Status paragraph to display any error messages.

XML TERMINATE.

Terminate the XML interface.

Perform Display-Status.

Perform the Display-Status paragraph again to display any error encountered by the XML TERMINATE statement.

Status Display Logic

This code is found in the copybook, lixmldsp.cpy.

This code is called twice by the termination test logic: the first time to report any error condition that exists, and the second time to report an error (if one occurs) from the XML TERMINATE statement. If there are no errors (the condition XML-IsSuccess is true), this paragraph displays no information.

COBOL Statement

Description

Display-Status.

This is the paragraph-name.

If Not XML-IsSuccess

Do nothing if XML-IsSuccess is true.

Perform With Test After Until XML-NoMore

Perform as long as there are status lines available to be displayed (until XML-NoMore is true).

XML GET STATUS-TEXT

Get the next line of status information from the XML interface.

Display XML-StatusText

Display the line that was just obtained.

End-Perform

End of the perform loop.

End-If.

End of the IF statement and the paragraph.

Parent topic: Example 1 Import file and export file
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
Related information
Development for example 1
Batch file for example 1
Program description for example 1
Data item for example 1
Other definitions for example 1
Execution results for example 1


Execution results for example 1

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Note: Pressing a key will terminate the program.

Running the program (run example01) produces the following display:

    Example-01 - Illustrate EXPORT FILE & IMPORT FILE

address01.xml exported by XML EXPORT FILE

Name:        Specialty Cowboy Boots Company
Address-1:   1050 North San Antonio Street
Address-2:   Suite 200
Address-3:   Austin                          TX78701
Country:     United States of America
Time-Stamp:  2013/06/28  15:07:27.69

address01.xml imported by XML IMPORT FILE

Name:        Specialty Cowboy Boots Company
Address-1:   1050 North San Antonio Street
Address-2:   Suite 200
Address-3:   Austin                          TX78701
Country:     United States of America
Time-Stamp:  2013/06/28  15:07:27.69

You may inspect 'address01.xml'

Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address01.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

Parent topic: Example 1 Import file and export file
Related information
Development for example 1
Batch file for example 1
Program description for example 1
Data item for example 1
Other definitions for example 1
Program structure for example 1


Example 2 Export file and import file with XSLT stylesheets

This program first writes (or exports) an XML document file from the content of a COBOL data item. Then the program reads (or imports) the same XML document and places the content in the same COBOL data item.

This example is almost identical to Example 1 Export file and import file. However, an external XSLT stylesheet is used to transform the exported document into a different format. Similarly, when the document is imported, an external XSLT stylesheet is used to reformat the document into the form that is expected by COBOL. For more information on stylesheets, see XSLT stylesheet files.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
Note: In this example, the XML EXPORT FILE and XML IMPORT FILE statements each contain an additional parameter: the name of the external XSLT stylesheet being used for the transformation.
  • Development for example 2
  • Batch file for example 2
  • Program description for example 2
  • Data item for example 2
  • Other definitions for example 2
  • Program structure for example 2
  • Execution results for example 2
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE


Development for example 2

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related reference
XMLGEN Compiler directive
Related information
Batch file for example 2
Program description for example 2
Data item for example 2
Other definitions for example 2
Program structure for example 2
Execution results for example 2


Batch file for example 2

Use the same commands as for example 1 except substitute example01 with example02.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related information
Development for example 2
Program description for example 2
Data item for example 2
Other definitions for example 2
Program structure for example 2
Execution results for example 2


Program description for example 2

This COBOL program illustrates how an XML document is generated from a COBOL data item, and then how the content of an XML document may be converted into COBOL data format and stored in a COBOL data item.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct to an XML document with the filename of address02.xml using the XML EXPORT FILE statement.

Next, the content of the XML document is imported from the file, address02.xml, and placed in the same data item using the XML IMPORT FILE statement.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML INITIALIZE
XML TERMINATE
XML GET STATUS-TEXT
Related information
Development for example 2
Batch file for example 2
Data item for example 2
Other definitions for example 2
Program structure for example 2
Execution results for example 2


Data item for example 2

The content of the COBOL data item defined in the copybook is the same as example 1.

This data item stores company address information. The last field of the structure is a time stamp containing the time that the program was executed. This item is included to assure the person observing the execution of the example that the results are current. The time element in the generated XML document should change each time the example is run and should contain the current time.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related information
Development for example 2
Batch file for example 2
Program description for example 2
Other definitions for example 2
Program structure for example 2
Execution results for example 2


Other definitions for example 2

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy , which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as example 1.

Various XML statements may access one of more fields of this data item. For example, the XML EXPORT FILE statement returns a value in the XML-Status field. The XML GET STATUS-TEXT statement accesses the XML-StatusText and XML-MoreFlag fields.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related reference
XML EXPORT FILE
XML GET STATUS-TEXT
Related information
Development for example 2
Batch file for example 2
Program description for example 2
Data item for example 2
Program structure for example 2
Execution results for example 2


Program structure for example 2

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example02.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML -OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement

Description

Move … To Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT FILE Address-Struct "address02.xml"
                      "Address-Struct" "toext".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, the ModelFileName#DataName parameter value, and the external XSLT stylesheet name.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML document

COBOL Statement

Description

Initialize Address-Struct.

Ensure that the Address-Struct structure contains no data.

XML IMPORT FILE Address-Struct "address02.xml"
                      "Address-Struct" "toint".

Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, the ModelFileName#DataName parameter value, and the external XSLT stylesheet name.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

COBOL Statement

Description

Z.

Paragraph-name that is a target of error condition GO TO statements.

Copy "lixmltrm.cpy".
 Copy in the termination test logic (see the Termination Test Logic table).
Stop Run.

Terminate the COBOL program.

Copy "lixmldsp.cpy".
 Copy in the status display logic (see the Status Display Logic table).

Termination test logic

Same as in example 1.

Status display logic

Same as in example 1.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
Related information
Development for example 2
Batch file for example 2
Program description for example 2
Data item for example 2
Other definitions for example 2
Execution results for example 2


Execution results for example 2

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Note: Pressing a key will terminate the program.

Running the program (run example02) produces the following display:

Example-02 - Illustrate EXPORT FILE & IMPORT FILE with XSLT stylesheets

address02.xml exported by XML EXPORT FILE

Name:        Specialty Cowboy Boots Company
Address-1:   1050 North San Antonio Street
Address-2:   Suite 200
Address-3:   Austin                          TX78701
Country:     United States of America
Time-Stamp:  2013/06/28  16:40:30.07

address02.xml imported by XML IMPORT FILE

Name:        Specialty Cowboy Boots Company
Address-1:   1050 North San Antonio Street
Address-2:   Suite 200
Address-3:   Austin                          TX78701
Country:     United States of America
Time-Stamp:  2013/06/28  16:40:30.07

You may inspect 'address02.xml'

Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address02.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

This XML document differs from the document generated in Example 1 Export File and Import File. Items that were shown as individual data elements in Example 1 are now shown as attributes of higher-level elements. Notice that this document contains no text. All of the information is contained in the markup.

Parent topic: Example 2 Export file and import file with XSLT stylesheets
Related information
Development for example 2
Batch file for example 2
Program description for example 2
Data item for example 2
Other definitions for example 2
Program structure for example 2


Example 3 Export file and import file with OCCURS DEPENDING

This program first writes (or exports) an XML document file from the content of a COBOL data item. Then the program reads (or imports) the same XML document and places the content in the same COBOL data item.

This program is very similar to Example 1 Export File and Import File. However, the data item has been modified so that an OCCURS DEPENDING clause is present.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 3
  • Batch file for example 3
  • Program description for example 3
  • Data item for example 3
  • Other definitions for example 3
  • Program structure for example 3
  • Execution results for example 3
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE


Development for example 3

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related reference
XMLGEN Compiler directive
Related information
Batch file for example 3
Program description for example 3
Data item for example 3
Other definitions for example 3
Program structure for example 3
Execution results for example 3


Batch file for example 3

Use the same commands as for example 1 except substitute example01 with example03..

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related information
Development for example 3
Program description for example 3
Data item for example 3
Other definitions for example 3
Program structure for example 3
Execution results for example 3


Program description for example 3

This COBOL program illustrates how an XML document is generated from a COBOL data item, and then how the content of an XML document may be converted into COBOL data format and stored in a COBOL data item.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct3 (as defined in the copybook, s-struct3.cpy) to an XML document with the filename of address03.xml using the XML EXPORT FILE statement.

Next, the content of the XML document is imported from the file, address03.xml, and placed in the same data structure using the XML IMPORT FILE statement.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML INITIALIZE
XML TERMINATE
XML GET STATUS-TEXT
Related information
Development for example 3
Batch file for example 3
Data item for example 3
Other definitions for example 3
Program structure for example 3
Execution results for example 3


Data item for example 3

The content of the COBOL data item defined in the copybook, s-struct3.cpy, is as follows:

*
* Title: s-struct3.cpy: XML Extensions sample data structure.
*
* Copyright © Micro Focus 2008-2013.
*     All rights reserved.
*
* Version Identification:
*   $Revision$
*   $Date$
*   $URL$
*
01  Address-Struct3.
    02  Time-Stamp    Pic X(23).
    02  Name          Pic X(64)
             Value "Cowboy Hats and More Company".
    02  City          Pic X(32) Value "San Marcos".
    02  State         Pic X(2) Value "TX".
    02  Zip           Pic 9(5) Value 78666.
    02  Country       PIC X(64)
              Value "United States of America".
    02  Address-Lines Pic 9.
    02  Address-Line  Pic X(64)
              Occurs 1 to 5 times Depending on Address-Lines.
01 Struct-Name       Pic X(15) Value "Address-Struct3".
01 Street            PIC X(64) Value
                 "504 Broadway Street".
01 Building          PIC X(64) Value "Building 1".
01 Suite             PIC X(64) Value "Suite 142".

This data item stores company address information. This structure differs from Example 1 Export file and import file in that an OCCURS DEPENDING phrase has been added to the structure. Instead of having separate data-names for Address-1 and Address-2, a variable-length array named Address-Line has been defined. Since Address-Line is variable length, it must be the last data item in the structure. A new data item named Address-Lines has been added just prior to the Address-Line array. Address-Lines is the depending variable for the array Address-Line.

The first field of the structure is a time stamp containing the time that the program was executed. This item is included to assure the person observing the execution of the example that the results are current. The time element in the generated XML document should change each time the example is run and should contain the current time.

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related information
Development for example 3
Batch file for example 3
Program description for example 3
Other definitions for example 3
Program structure for example 3
Execution results for example 3


Other definitions for example 3

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the COBOL program.

The copybook, lixmldef.cpy , which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as examples 1 and 2.

Various XML statements may access one of more fields of this data item. For example, the XML EXPORT FILE statement returns a value in the XML-Status field. The XML GET STATUS-TEXT statement accesses the XML-StatusText and XML-MoreFlag fields.

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related reference
XML EXPORT FILE
XML GET STATUS-TEXT
Related information
Development for example 3
Batch file for example 3
Program description for example 3
Data item for example 3
Program structure for example 3
Execution results for example 3


Program structure for example 3

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example03.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement

Description

Move … To Time-Stamp.

Populate the Time-Stamp field.

Move 3 to Address-Lines. Move … to Address-Line(1).
Move … to Address-Line(2).
Move … to Address-Line(3).

Ensure that Address Lines contain proper information.

XML EXPORT FILE Address-Struct3
                 "address03.xml" "Address-Struct3".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML document

COBOL Statement

Description

Initialize Address-Struct3.

Ensure that the address structure contains no data.

XML IMPORT FILE Address-Struct3
                  "address03.xml" "Address-Struct3".

Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
Related information
Development for example 3
Batch file for example 3
Program description for example 3
Data item for example 3
Other definitions for example 3
Execution results for example 3


Execution results for example 3

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Example-03 - Illustrate EXPORT FILE & IMPORT FILE with OCCURS DEPENDING

address03.xml exported by XML EXPORT FILE

Name:             Cowboy Hats and More Company
Address-Line(1):  504 Broadway Street
Address-Line(2):  Building 1
Address-Line(3):  Suite 142
City State Zip:   San Marcos                      TX78666
Country:          United States of America
Time-Stamp:       2013/07/01  16:57:14.16

address03.xml imported by XML IMPORT FILE

Name:             Cowboy Hats and More Company
Address-Line(1):  504 Broadway Street
Address-Line(2):  Building 1
Address-Line(3):  Suite 142
City State Zip:   San Marcos                      TX78666
Country:          United States of America
Time-Stamp:       2013/07/01  16:57:14.16

You may inspect 'address03.xml'

Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address03.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

Parent topic: Example 3 Export file and import file with OCCURS DEPENDING
Related information
Development for example 3
Batch file for example 3
Program description for example 3
Data item for example 3
Other definitions for example 3
Program structure for example 3


Example 4 Export file and import file with sparse arrays

This example illustrates how XML Extensions may work with sparse arrays. XML Extensions distinguishes between an empty occurrence and a non-empty occurrence. An occurrence is an empty occurrence when all of its numeric elementary data items have a zero value and all of its nonnumeric elementary data items contain spaces; otherwise, the occurrence is a non-empty occurrence. A sparse array is an array that contains a combination of empty and non-empty occurrences. Empty occurrences need not be exported unless they are needed to locate (determine the subscript) of a subsequent non-empty occurrence. Normally, this means that trailing empty occurrences, that is, a contiguous series of empty occurrences at the end of the array, are not exported. Sparse arrays may also be imported.

This program first writes (or exports) several XML document files from the content of a COBOL data item (using various combinations of the XML ENABLE ATTRIBUTES, XML DISABLE ATTRIBUTES, XML ENABLE ALL-OCCURRENCES, and XML DISABLE ALL-OCCURRENCES statements). Then the program reads (or imports) the same XML documents (plus a couple of pre-existing documents) and places the content in the same COBOL data item.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML ENABLE ATTRIBUTES, which causes exported XML document to contain descriptive (COBOL-oriented) attributes.
    Note: Although the default is not to add descriptive attributes to an XML document (see XML DISABLE ATTRIBUTES in the next item), among the attributes that may be added is the "subscript" attribute. This attribute contains the one-relative index of the occurrence within the array. When an XML document is imported, this subscript attribute is used (if present) to place the occurrence correctly within the array. If the subscript attribute is not present, then occurrences are assumed to occur sequentially.
  • XML DISABLE ATTRIBUTES, which causes exported XML documents not to contain descriptive attributes.
    Note: The default is not to add descriptive attributes to an XML document.
  • XML ENABLE ALL-OCCURRENCES, which causes all occurrences of a data item to be exported to an XML document.
  • XML DISABLE ALL-OCCURRENCES, which causes only certain occurrences to be exported to the XML document.
    Note: The default is to export only certain occurrences to the XML document.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 4
  • Batch file for example 4
  • Program description for example 4
  • Data item for example 4
  • Other definitions for example 4
  • Program structure for example 4
  • Execution results for example 4
Parent topic: Appendix A XML Extensions examples
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ALL-OCCURRENCES


Development for example 4

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 4 Export file and import file with sparse arrays
Related reference
XMLGEN Compiler directive
Related information
Batch file for example 4
Program description for example 4
Data item for example 4
Other definitions for example 4
Program structure for example 4
Execution results for example 4


Batch file for example 4

Use the same commands as for example 1 except substitute example01 with example04.

Parent topic: Example 4 Export file and import file with sparse arrays
Related information
Development for example 4
Program description for example 4
Data item for example 4
Other definitions for example 4
Program structure for example 4
Execution results for example 4


Program description for example 4

This COBOL program illustrates how several similar XML documents are generated from a single COBOL data item. It also illustrates how the content of several similar XML documents may be converted into COBOL data format and stored in a COBOL data item.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Data-Table to several XML documents with the filenames of table1.xml, table2.xml, table3.xml, and table4.xml using the XML EXPORT FILE statement. All four combinations of the XML ENABLE ATTRIBUTES, XML DISABLE ATTRIBUTES, XML ENABLE ALL-OCCURRENCES, and XML DISABLE ALL-OCCURRENCES statements are used to alter the content of the generated XML documents.

Next, the content of these four XML documents (plus two additional "pre-created" XML documents, table5.xml and table6.xml) is imported and placed in the same data item using the XML IMPORT FILE statement. This example does not use a schema file to validate the input because the array is fixed size and not all of the XML documents that will be input contain all of the occurrences of the array. These XML documents and their content are described in Execution results for example 4.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 4 Export file and import file with sparse arrays
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ALL-OCCURRENCES
Related information
Development for example 4
Batch file for example 4
Data item for example 4
Other definitions for example 4
Program structure for example 4
Execution results for example 4


Data item for example 4

The content of the COBOL data item is as follows:
01 Data-Table.
 02 Value "[".
 02 Table-1 Occurs 6.
 03 X Pic X.
 03 N Pic 9.
 02 Value "]".

This data item contains an array with six occurrences. Each occurrence consists of a one-character, nonnumeric data item followed by a one-digit numeric data item. Note that the structure also contains two FILLER data items: the left brace ([) character at the beginning and the right brace(]) character at the end. The values of the FILLER data items are output as text in the XML document without associated tags.

Parent topic: Example 4 Export file and import file with sparse arrays
Related information
Development for example 4
Batch file for example 4
Program description for example 4
Other definitions for example 4
Program structure for example 4
Execution results for example 4


Other definitions for example 4

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Various XML statements may access one of more fields of this item. For example, the XML EXPORT FILE statement returns a value in the XML-Status field. The XML GET STATUS-TEXT statement accesses the XML-StatusText and XML-MoreFlag fields.

Parent topic: Example 4 Export file and import file with sparse arrays
Related reference
XML EXPORT FILE
XML GET STATUS-TEXT
Related information
Development for example 4
Batch file for example 4
Program description for example 4
Data item for example 4
Program structure for example 4
Execution results for example 4


Program structure for example 4

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example04.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement

Description

XML DISABLE ATTRIBUTES If Not XML-OK Go To Z.
XML DISABLE ALL-OCCURRENCES If Not XML-OK Go To Z.

Selectively ENABLE or DISABLE ATTRIBUTES and ALL-OCCURRENCES. All four combinations of ENABLE and DISABLE are used for tables 1 - 4.

Initialize Data-Table. Move "B" to X (2).
Move 2 to N (2).
Move "D" to X (4).
Move 4 to N (4).

Initialize the Data-Table structure to the preferred values.

XML EXPORT FILE Data-Table "table1" "Data-Table".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename (table1 - table4), and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML document

COBOL Statement

Description

Initialize Data-Table.

Ensure that the data item contains no data.

XML IMPORT FILE Data-Table "table1" "Data-Table".

Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename (table1 - table6), and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 4 Export file and import file with sparse arrays
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML DISABLE ATTRIBUTES
XML ENABLE ATTRIBUTES
XML ENABLE ALL-OCCURRENCES
XML DISABLE ALL-OCCURRENCES
Related information
Development for example 4
Batch file for example 4
Program description for example 4
Data item for example 4
Other definitions for example 4
Execution results for example 4


Execution results for example 4

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Note: Pressing a key will terminate the program.

Running the program produces the following display:

 Example-04 - Illustrate EXPORT FILE &
IMPORT FILE with sparse arrays
table1.xml exported by XML EXPORT FILE: [ 0B2 0D4 0 0]
table2.xml exported by XML EXPORT FILE: [ 0B2 0D4 0 0]
table3.xml exported by XML EXPORT FILE: [ 0B2 0D4 0 0]
table4.xml exported by XML EXPORT FILE: [ 0B2 0D4 0 0]
 table1.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
table2.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
table3.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
table4.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
table5.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
table6.xml imported by XML IMPORT FILE: [ 0B2 0D4 0 0]
 You may inspect 'table1.xml' - 'table6.xml'
 Status: +0000
Press a key to terminate:

XML documents

Microsoft Internet Explorer may be used to view the XML documents that are associated with this example. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

The files table1.xml, table2.xml, table3.xml, and table4.xml are generated with XML EXPORT FILE statements. All of these documents were generated from the same COBOL content. The files, table5.xml and table6.xml, which are supplied with the example, describe the same COBOL content.

The only non-empty occurrences are for the second and fourth elements of the array. The content of the six files should appear as follows:

  • Table1.xml
  • Table2.xml
  • Table3.xml
  • Table4.xml
  • Table5.xml
  • Table6.xml
Parent topic: Example 4 Export file and import file with sparse arrays
Related reference
XML EXPORT FILE
Related information
Development for example 4
Batch file for example 4
Program description for example 4
Data item for example 4
Other definitions for example 4
Program structure for example 4


Table1.xml

The XML DISABLE ATTRIBUTES and XML DISABLE ALL-OCCURRENCES statements are used to determine the content of this file. Trailing empty occurrences are deleted. However, some empty occurrences were generated so that the two non-empty occurrences are positioned correctly.

This example also uses FILLER data items. The left brace ([) and right brace (]) characters were defined within the data item as FILLER. The text associated with the FILLER is placed in the XML document without any tags.

Parent topic: Execution results for example 4
Related reference
XML DISABLE ATTRIBUTES
XML DISABLE ALL-OCCURRENCES
Related information
Table2.xml
Table3.xml
Table4.xml
Table5.xml
Table6.xml


Table2.xml

The XML ENABLE ATTRIBUTES and XML DISABLE ALL-OCCURRENCES statements are used to determine the content of this file. Since each non-empty occurrence now contains a subscript attribute, none of the empty occurrences are generated.

Parent topic: Execution results for example 4
Related reference
XML ENABLE ATTRIBUTES
XML DISABLE ALL-OCCURRENCES
Related information
Table1.xml
Table3.xml
Table4.xml
Table5.xml
Table6.xml


Table3.xml

The XML DISABLE ATTRIBUTES and XML ENABLE ALL-OCCURRENCES statements are used to determine the content of this file. These statements cause all occurrences, whether empty or non-empty, to be generated.

Parent topic: Execution results for example 4
Related reference
XML DISABLE ATTRIBUTES
XML ENABLE ALL-OCCURRENCES
Related information
Table1.xml
Table2.xml
Table4.xml
Table5.xml
Table6.xml


Table4.xml

The XML ENABLE ATTRIBUTES and XML ENABLE ALL-OCCURRENCES statements are used to determine the content of this file. These statements produce the most verbose listing of occurrences possible. Every occurrence is listed with its attributes.

Parent topic: Execution results for example 4
Related reference
XML ENABLE ATTRIBUTES
XML ENABLE ALL-OCCURRENCES
Related information
Table1.xml
Table2.xml
Table3.xml
Table5.xml
Table6.xml


Table5.xml

This file was manually generated using a text editor program in order to contain the minimum amount of information possible. Of all the attributes, only the subscript attribute is included. This allows all empty occurrences to be suppressed. In practice, an XSLT stylesheet or other software could generate this kind of document.

Parent topic: Execution results for example 4
Related information
Table1.xml
Table2.xml
Table3.xml
Table4.xml
Table6.xml


Table6.xml

The only difference between this file and table5.xml is that the subscript reference has been moved from the occurrence level down to an element within the occurrence.

Parent topic: Execution results for example 4
Related information
Table1.xml
Table2.xml
Table3.xml
Table4.xml
Table5.xml


Example 5 Export and import text

This program first writes (or exports) an XML document as a text string from the content of a COBOL data item. Then the program reads (or imports) the same XML document and places the content in the same COBOL data item. Finally, the text string representation of the XML document is copied to a disk file and the memory block that it occupied is released.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT TEXT, which constructs an XML document (as a text string) from the content of a COBOL data item.
  • XML IMPORT TEXT, which reads an XML document (from a text string) into a COBOL data item.
  • XML PUT TEXT, which copies an XML document from a text string to a data file.
  • XML FREE TEXT, which releases the memory that was allocated by XML EXPORT TEXT to hold the XML document as a text string.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 5
  • Batch file for example 5
  • Program description for example 5
  • Data item for example 5
  • Other definitions for example 5
  • Program structure for example 5
  • Execution results for example 5
Parent topic: Appendix A XML Extensions examples
Related reference
XML IMPORT TEXT
XML EXPORT TEXT
XML TERMINATE
XML INITIALIZE
XML PUT TEXT
XML FREE TEXT


Development for example 5

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 5 Export and import text
Related information
Batch file for example 5
Program description for example 5
Data item for example 5
Other definitions for example 5
Program structure for example 5
Execution results for example 5


Batch file for example 5

Use the same commands as for example 1 except substitute example01 with example05.

Parent topic: Example 5 Export and import text
Related information
Development for example 5
Program description for example 5
Data item for example 5
Other definitions for example 5
Program structure for example 5
Execution results for example 5


Program description for example 5

This COBOL program illustrates how an XML document is generated from a COBOL data item, and then how the content of an XML document may be converted into COBOL data format and stored in a COBOL data item. This program is similar to Example 1 Export file and import file, except that the XML document is stored as a text string instead of a disk file.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an in-memory XML document as defined by the variables, DocumentPointer and DocumentLength, using the XML EXPORT TEXT statement.

Next, the content of the XML document is imported from the in-memory text string, and placed in the same data item using the XML IMPORT TEXT statement.

Then, the contents of the text string are written to a disk file using the XML PUT TEXT statement. The memory block is deallocated using the XML FREE TEXT statement. The primary aim of using the XML PUT TEXT statement is to make the content of the XML document available as an external file for viewing.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 5 Export and import text
Related reference
XML IMPORT TEXT
XML EXPORT TEXT
XML TERMINATE
XML INITIALIZE
XML PUT TEXT
XML FREE TEXT
Related information
Development for example 5
Batch file for example 5
Data item for example 5
Other definitions for example 5
Program structure for example 5
Execution results for example 5


Data item for example 5

The content of the COBOL data item, Address-Struct, is the same as in example 1.

Parent topic: Example 5 Export and import text
Related information
Development for example 5
Batch file for example 5
Program description for example 5
Other definitions for example 5
Program structure for example 5
Execution results for example 5


Other definitions for example 5

The copybook, lixmlall.cpy , should be included in the Working-Storage Section of the program.

The copybook lixmldef.cpy , which is copied in by lixmlall.cpy , defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 5 Export and import text
Related information
Development for example 5
Batch file for example 5
Program description for example 5
Data item for example 5
Program structure for example 5
Execution results for example 5


Program structure for example 5

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example05.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement

Description

Move … Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT TEXT Address-Struct
    Document-Pointer Document-Length "Address-Struct".

Execute the XML EXPORT TEXT statement specifying: the data item address, the XML document text pointer, the XML document text length, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML document

COBOL Statement

Description

Initialize Address-Struct.

Ensure that the address structure contains no data.

XML IMPORT TEXT Address-Struct
    Document-Pointer Document-Length "Address-Struct".

Execute the XML IMPORT TEXT statement specifying: the data item address, the XML document text pointer, the XML document text length, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Copying an XML document to a file

COBOL Statement

Description

XML PUT TEXT Document-Pointer Document-Length "address05".

Execute the XML PUT TEXT statement specifying: the XML document text pointer the XML document text length, and the XML document filename.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Releasing the XML document memory

COBOL Statement

Description

XML FREE TEXT Document-Pointer.

Execute the XML FREE TEXT statement specifying the XML document text pointer.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 5 Export and import text
Related reference
XML IMPORT TEXT
XML EXPORT TEXT
XML TERMINATE
XML INITIALIZE
XML PUT TEXT
XML FREE TEXT
Related information
Development for example 5
Batch file for example 5
Program description for example 5
Data item for example 5
Other definitions for example 5
Execution results for example 5


Execution results for example 5

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Note: Pressing a key will terminate the program.
Running the program (run example05) produces the following display:
 Example-05 - Illustrate EXPORT TEXT &
IMPORT TEXT
 Document exported by XML EXPORT TEXT
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 18:37:38.72
 Document imported by XML IMPORT TEXT
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 18:37:38.72
 Document memory written by XML PUT TEXT
Document memory released by XML FREE TEXT
 You may inspect 'address05.xml'
 Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address05.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

Parent topic: Example 5 Export and import text
Related information
Development for example 5
Batch file for example 5
Program description for example 5
Data item for example 5
Other definitions for example 5
Program structure for example 5


Example 6 Export file and import file with directory polling

This COBOL program illustrates how a series of XML documents may be placed in a specific directory and how directory polling may be used to process XML documents as they arrive in that specified directory. For more information on directory-polling schemes, see Directory Management Statements.

The program first writes (or exports) five XML document files from the content of a COBOL data item. Each document has a unique name and is written to the same directory. Then the program polls the directory looking for an XML document. When one is found, the program reads (or imports) each XML document and places the content in the COBOL data item.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • XML GET UNIQUEID, which is used to generate a unique identifier that can be used to form a filename.
  • XML FIND FILE, which finds a XML document file in the specified directory (if one is available).
  • XML REMOVE FILE, which deletes a file.
  • Development for example 6
  • Batch file for example 6
  • Program description for example 6
  • Data item for example 6
  • Other definitions for example 6
  • Program structure for example 6
  • Execution results for example 6
Parent topic: Appendix A XML Extensions examples
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML FIND FILE
XML REMOVE FILE
XML GET UNIQUEID


Development for example 6

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 6 Export file and import file with directory polling
Related information
Batch file for example 6
Program description for example 6
Data item for example 6
Other definitions for example 6
Program structure for example 6
Execution results for example 6


Batch file for example 6

The following commands build and execute example06.int.

Line | Statement
1 | cobol example06.cbl xmlgen(ws) noobj;
2 | mkdir stamp
3 | start /w run example06

This is very similar to example 1 except that mkdir is used to create the stamp subdirectory used by this example prior to executing the program.

Parent topic: Example 6 Export file and import file with directory polling
Related information
Development for example 6
Program description for example 6
Data item for example 6
Other definitions for example 6
Program structure for example 6
Execution results for example 6


Program description for example 6

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

The current time, which will become the content of an XML document, is recorded in a COBOL data item. Note that for this example, an elementary data item is used instead of a data item.

Because the name of each file within a directory must be unique, a unique filename is generated using the XML GET UNIQUEID statement. The returned value is combined with other text strings to form a path name using the STRING statement. The current time is placed in the Time-Stamp data item using the ACCEPT FROM TIME statement. The XML EXPORT FILE statement is used to output the data item as an XML document. This sequence is repeated until five XML documents have been placed in the specified directory.

Next, the program goes into a loop polling the specified directory. The XML FIND FILE statement is used. If the return status is XML-IsSuccess, then a file has been found and the program proceeds to process the file. If the return status is XML-IsDirectoryEmpty, then the directory is empty and the program issues a slight delay and then re-issues the XML FIND FILE statement. Any other status indicates an error.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 6 Export file and import file with directory polling
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML FIND FILE
XML REMOVE FILE
XML GET UNIQUEID
Related information
Development for example 6
Batch file for example 6
Data item for example 6
Other definitions for example 6
Program structure for example 6
Execution results for example 6


Data item for example 6

The content of the COBOL data item defined in the example, which in this case, is a single data item, is as follows:
01 Time-Stamp Pic 9(8).

This data item stores a time stamp acquired by using the ACCEPT FROM TIME statement.

Parent topic: Example 6 Export file and import file with directory polling
Related information
Development for example 6
Batch file for example 6
Program description for example 6
Other definitions for example 6
Program structure for example 6
Execution results for example 6


Other definitions for example 6

The copybook, lixmlall.cpy , should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 6 Export file and import file with directory polling
Related information
Development for example 6
Batch file for example 6
Program description for example 6
Data item for example 6
Program structure for example 6
Execution results for example 6


Program structure for example 6

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example06.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

COBOL Statement

Description

Perform 5 Times
 XML GET UNIQUEID
 Unique-Name
 If Not XML-OK Go To Z.

Iterate to export 5 files. Generate a unique identifier. If the statement terminates unsuccessfully, go to the termination logic.

Move Spaces to Unique-File-Name
 String "stamp/a" delimited by size
 Unique-Name delimited by SPACE
 ".xml" delimited by size
 into Unique-File-Name.

Convert the unique identifier into a path name.

Move … To Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT FILE
 Time-Stamp
 Unique-File-Name
 "Time-Stamp".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.
 End-Perform.

If the statement terminates unsuccessfully, go to the termination logic.

COBOL Statement

Description

Perform Until 0 > 1

Outer perform loop. Iterate until Exit Perform.

Perform Compute-Curr-Time
 Compute Stop-Time
 = Curr-Time + 100

The paragraph Compute-Curr-Time ACCEPTs the current time and converts it to an integer value. Compute Stop-Time to be 1 second after current time.

Perform Until 0 > 1
 XML FIND FILE
 "stamp"
 Unique-File-Name
If XML-IsSuccess
 Exit Perform
End-If
If XML-IsDirectoryEmpty
 Perform Compute-Curr-Time
If Curr-Time > Stop-Time
 Exit Perform
End-If
 Call "CBL_THREAD_SLEEP" …
End-If
If Not XML-OK
 Go To Z
End-If
End-Perform

Inner perform loop. Iterate until Exit Perform. Execute XML FIND FILE parameters: directory name and filename. If the statement returned success, exit the paragraph. If the statement returns directory empty, compute new current time, and if the current time is greater than the stop time, exit the perform. Otherwise, do a short time delay. If the statement terminates unsuccessfully, go to the termination logic. The end of the inner perform loop.

If Curr-Time > Stop-Time
 Exit Perform
End-If

Check to see if the outer perform loop should terminate.

XML IMPORT FILE
 Time-Stamp
 Unique-File-Name
 "Time-Stamp"
 If Not XML-OK Go To Z
 End-If

Import the file that was found using: the data item, the filename, and the ModelFileName#DataName parameter value. If the statement terminates unsuccessfully, go to the termination logic.

XML REMOVE FILE
 Unique-File-Name
 If Not XML-OK Go To Z
 End-If

Remove the file that has just been processed; otherwise, find it again. If the statement terminates unsuccessfully, go to the termination logic.

End-Perform

The end of the outer perform loop.

COBOL Statement

Description

Z.

Paragraph-name that is a target of error condition GO TO statements.

Copy "lixmltrm.cpy".

Copy in the termination test logic (see the Termination Test Logic table).

Stop Run.

Terminate the COBOL program.

Copy "lixmldsp.cpy".

Copy in the status display logic (see the Status Display Logic table).

This code is found in the copybook, lixmltrm.cpy.

This code occurs after the paragraph named Z, so that any error condition is obtained here via a GO TO Z statement. If there are no errors, execution "falls through" to these statements.

COBOL Statement

Description

Display "Status: " XML-Status.

Display the most recent return status value (if there are no errors, this should display zero).

Perform Display-Status.

Perform the Display-Status paragraph to display any error messages.

XML TERMINATE.

Terminate the XML interface.

Perform Display-Status.

Perform the Display-Status paragraph again to display any error encountered by the XML TERMINATE statement.

This code is found in the copybook, lixmldsp.cpy.

This code is called twice by the termination test logic: the first time to report any error condition that exists, and the second time to report an error (if one occurs) from the XML TERMINATE statement. If there are no errors (the condition XML-IsSuccess is true), this paragraph displays no information.

COBOL Statement

Description

Display-Status.

This is the paragraph-name.

If Not XML-IsSuccess

Do nothing if XML-IsSuccess is true.

 Perform With Test After
         Until XML-NoMore

Perform as long as there are status lines available to be displayed (until XML-NoMore is true).

  XML GET STATUS-TEXT

Get the next line of status information from the XML interface.

  Display XML-StatusText

Display the line that was just obtained.

 End-Perform

End of the perform loop.

End-If.

End of the IF statement and the paragraph.

Parent topic: Example 6 Export file and import file with directory polling
Related reference
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
XML INITIALIZE
XML FIND FILE
XML REMOVE FILE
XML GET UNIQUEID
Related information
Development for example 6
Batch file for example 6
Program description for example 6
Data item for example 6
Other definitions for example 6
Execution results for example 6


Execution results for example 6

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Running the program (run example06) produces two displays. The first display occurs after exporting five documents to the stamp directory. The second display takes place after polling the stamp directory and importing the five documents.

First Display

Note: Pressing a key will cause the program to continue.
 Example-06 - Illustrate EXPORT FILE &
IMPORT FILE with directory polling
stamp/a{a258c50d-a15e-493b-a29d-cc0e782b5f54}.xml exported by
XMLExport
Contents: 2013/07/01 19:22:39.07
stamp/a{9318803d-1b46-486c-a59b-f7dcc92c4d2f}.xml exported by
XMLExport
Contents: 2013/07/01 19:22:39.07
stamp/a{3a2b7d60-6065-4785-bdf3-ab388992079d}.xml exported by
XMLExport
Contents: 2013/07/01 19:22:39.07
stamp/a{4a4e8482-d3a4-492e-a79d-ec6d967cd4e6}.xml exported by
XMLExport
Contents: 2013/07/01 19:22:39.07
stamp/a{30cd08ac-0edf-4885-a106-4acdcb8caada}.xml exported by
XMLExport
Contents: 2013/07/01 19:22:39.07
 You may display the 'stamp' directory
 Press a key to continue:

Second Display

Note: Pressing a key will terminate the program.
stamp\a{30cd08ac-0edf-4885-a106-4acdcb8caada}.xml
imported by XMLImport
Contents: 2013/07/01 19:22:39.07
 stamp\a{3a2b7d60-6065-4785-bdf3-ab388992079d}.xml imported by
XMLImport
Contents: 2013/07/01 19:22:39.07
 stamp\a{4a4e8482-d3a4-492e-a79d-ec6d967cd4e6}.xml imported by
XMLImport
Contents: 2013/07/01 19:22:39.07
 stamp\a{9318803d-1b46-486c-a59b-f7dcc92c4d2f}.xml imported by
XMLImport
Contents: 2013/07/01 19:22:39.07
 stamp\a{a258c50d-a15e-493b-a29d-cc0e782b5f54}.xml imported by
XMLImport
Contents: 2013/07/01 19:22:39.07
 You may now verify that the 'stamp' directory has been
emptied
 Status: +0001
Informative: 1[0] - indicated directory contains no documents
Press a key to terminate.
Parent topic: Example 6 Export file and import file with directory polling
Related information
Development for example 6
Batch file for example 6
Program description for example 6
Data item for example 6
Other definitions for example 6
Program structure for example 6


Example 7 Export file, test well-formed file, and validate file

This COBOL program illustrates how an XML document is generated from a COBOL data item and then how the syntax and content of an XML document may be verified.

The program first writes (or exports) an XML document file from the content of a COBOL data item. Then the program verifies that the generated document is well-formed. Finally, the program verifies that the content of the document conforms to the schema file.

Note: On UNIX systems, the underlying XML parser, libxml, does not support schema validation.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML TEST WELLFORMED-FILE, which verifies that an XML document conforms to XML syntax rules.
  • XML VALIDATE FILE, which verifies that the content of an XML document conforms to rules specified by an XML schema file.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 7
  • Batch file for example 7
  • Program description for example 7
  • Data item for example 7
  • Other definitions for example 7
  • Program structure for example 7
  • Execution results for example 7
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML EXPORT FILE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE


Development for example 7

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related information
Batch file for example 7
Program description for example 7
Data item for example 7
Other definitions for example 7
Program structure for example 7
Execution results for example 7


Batch file for example 7

Use the same commands as for example 1 except substitute example01 with example07.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related information
Development for example 7
Program description for example 7
Data item for example 7
Other definitions for example 7
Program structure for example 7
Execution results for example 7


Program description for example 7

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an XML document with the filename of address07.xml using the XML EXPORT FILE statement.

Next, the syntax of address07.xml is verified using the XML TEST WELLFORMED-FILE statement.

Following this, the content of address07.xml is verified using the XML VALIDATE FILE statement.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

For the purposes of this example, both the XML TEST WELLFORMED-FILE and XML VALIDATE FILE statements were used. However, the XML VALIDATE FILE statement also tests an XML document for well-formed syntax.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related reference
XML INITIALIZE
XML EXPORT FILE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE
Related information
Development for example 7
Batch file for example 7
Data item for example 7
Other definitions for example 7
Program structure for example 7
Execution results for example 7


Data item for example 7

The content of the COBOL data item, Address-Struct is the same as in example 1.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related information
Development for example 7
Batch file for example 7
Program description for example 7
Other definitions for example 7
Program structure for example 7
Execution results for example 7


Other definitions for example 7

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related information
Development for example 7
Batch file for example 7
Program description for example 7
Data item for example 7
Program structure for example 7
Execution results for example 7


Program structure for example 7

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example07.cbl.

Initialization

COBOL Statement

Description

XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement

Description

Move … To Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT FILE
 Address-Struct
 "address07"
 "Address-Struct".

Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Verifying syntax

COBOL Statement

Description

XML TEST WELLFORMED-FILE
 "address07".

Execute the XML TEST WELLFORMED-FILE statement specifying the XML document filename.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Verifying content

COBOL Statement

Description

XML VALIDATE FILE
 "address07"
 "example07".

Execute the XML VALIDATE FILE statement specifying: the XML document filename and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related reference
XML INITIALIZE
XML EXPORT FILE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE
Related information
Development for example 7
Batch file for example 7
Program description for example 7
Data item for example 7
Other definitions for example 7
Execution results for example 7


Execution results for example 7

COBOL display

The following sections display the output of the COBOL program that is run and the XML document that is generated.

Note: Pressing a key will terminate the program.
Running the program (run example07) produces the following display:
 Example-07 - Illustrate TEST-WELLFORMED FILE
& VALIDATE FILE
 address07.xml exported by XML EXPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 20:02:32.99
 address07.xml checked by XML TEST WELLFORMED-FILE
 address07.xml validated by XML VALIDATE FILE
 address07.xml imported by XML IMPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 20:02:32.99
 You may inspect 'address07.xml'
 Status: +0000
Press a key to terminate:

Microsoft Internet Explorer may be used to view the generated XML document address07.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

Parent topic: Example 7 Export file, test well-formed file, and validate file
Related information
Development for example 7
Batch file for example 7
Program description for example 7
Data item for example 7
Other definitions for example 7
Program structure for example 7


Example 8 Export text, test well-formed text, and validate text

This COBOL program illustrates how an XML document is generated from a COBOL data item and then how the syntax and content of an XML document may be verified. Next, the program verifies that the generated document is well-formed. Finally, the program verifies that the content of the document conforms to the schema file.

Note: On UNIX systems, the underlying XML parser, libxml, does not support schema validation.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT TEXT, which constructs an XML document (as a text string) from the content of a COBOL data item.
  • XML TEST WELLFORMED-TEXT, which verifies that an XML document conforms to XML syntax rules.
  • XML VALIDATE TEXT, which verifies that the content of an XML document conforms to rules specified by an XML schema file.
  • XML PUT TEXT, which copies an XML document from a text string to a data file.
  • XML FREE TEXT, which releases the memory that was allocated by XML EXPORT TEXT to hold the XML document as a text string.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 8
  • Batch file for example 8
  • Program description for example 8
  • Data item for example 8
  • Other definitions for example 8
  • Program structure for example 8
  • Execution results for example 8
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML EXPORT TEXT
XML TEST WELLFORMED-TEXT
XML VALIDATE TEXT
XML PUT TEXT
XML FREE TEXT
XML TERMINATE


Development for example 8

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related information
Batch file for example 8
Program description for example 8
Data item for example 8
Other definitions for example 8
Program structure for example 8
Execution results for example 8


Batch file for example 8

Use the same commands as for example 1 except substitute example01 with example08.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related information
Development for example 8
Program description for example 8
Data item for example 8
Other definitions for example 8
Program structure for example 8
Execution results for example 8


Program description for example 8

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an in-memory XML document as defined by the variables, Document-Pointer and Document-Length, using the XML EXPORT TEXT statement.

Next, the syntax of the generated XML document is verified using the XML TEST WELLFORMED-TEXT statement.

Following this, the content of the generated XML document is verified using the XML VALIDATE TEXT statement.

Next, the contents of the text string are written to a disk file using the XML PUT TEXT statement. The memory block is deallocated using the XML FREE TEXT statement. The primary aim of using the XML PUT TEXT statement is to make the content of the XML document available as an external file for viewing.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

For the purposes of this example, both the XML TEST WELLFORMED-TEXT and XML VALIDATE TEXT statements were used. However, the XML VALIDATE TEXT statement also tests an XML document for well-formed syntax.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related reference
XML INITIALIZE
XML EXPORT TEXT
XML TEST WELLFORMED-TEXT
XML VALIDATE TEXT
XML PUT TEXT
XML FREE TEXT
XML TERMINATE
Related information
Development for example 8
Batch file for example 8
Data item for example 8
Other definitions for example 8
Program structure for example 8
Execution results for example 8


Data item for example 8

The content of the COBOL data item, Address-Struct, is the same as in example 1.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related information
Development for example 8
Batch file for example 8
Program description for example 8
Other definitions for example 8
Program structure for example 8
Execution results for example 8


Other definitions for example 8

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related information
Development for example 8
Batch file for example 8
Program description for example 8
Data item for example 8
Program structure for example 8
Execution results for example 8


Program structure for example 8

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example08.cbl.

Initialization

COBOL Statement Description
XML INITIALIZE.

Execute the XML INITIALIZE statement (no parameters).

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement Description
Move … To Time-Stamp.

Populate the Time-Stamp field.

XML EXPORT TEXT
 Address-Struct
 Document-Pointer
 Document-Length
 "Address-Struct".

Execute the XML EXPORT TEXT statement specifying: the data item address, the XML document text pointer, the XML document text length, and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Verifying syntax

COBOL Statement Description
XML TEST WELLFORMED-TEXT
 Document-Pointer
 Document-Length.

Execute the XML TEST WELLFORMED-TEXT statement specifying the XML document text pointer.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Verifying content

COBOL Statement Description
XML VALIDATE TEXT
 Document-Pointer
 Document-Length
 "example08".

Execute the XML VALIDATE TEXT statement specifying: the XML document text pointer the XML document text length and the ModelFileName#DataName parameter value.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Copying an XML document to a file

COBOL Statement Description
XML PUT TEXT
 Document-Pointer
 Document-Length
 "address08".

Execute the XML PUT TEXT statement specifying: the XML document text pointer the XML document text length and the document filename.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Releasing the XML document memory

COBOL Statement Description
XML FREE TEXT
 Document-Pointer.

Execute the XML FREE TEXT statement specifying the XML document text pointer.

If Not XML-OK Go To Z.

If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related reference
XML INITIALIZE
XML EXPORT TEXT
XML TEST WELLFORMED-TEXT
XML VALIDATE TEXT
XML PUT TEXT
XML FREE TEXT
XML TERMINATE
Related information
Development for example 8
Batch file for example 8
Program description for example 8
Data item for example 8
Other definitions for example 8
Execution results for example 8


Execution results for example 8

COBOL display

The following sections display the output of the COBOL program that is run and the XML document that is generated.

Note: Pressing a key will terminate the program.
Running the program (run example08) produces the following display:
Example-08 - Illustrate TEST-WELLFORMED TEXT
& VALIDATE TEXT
 Document exported by XML EXPORT TEXT
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 20:20:14.48
 Document checked by XML TEST WELLFORMED-TEXT
 Document validated by XML VALIDATE TEXT
 Document memory imported by XML IMPORT TEXT
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 20:20:14.48
 Document memory written by XML PUT TEXT
 Document memory released by XML FREE TEXT
 address08.xml imported by XML IMPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/01 20:20:14.48
 You may inspect 'address08.xml'
 Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address08.xml. The content of this document should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

Parent topic: Example 8 Export text, test well-formed text, and validate text
Related information
Development for example 8
Batch file for example 8
Program description for example 8
Data item for example 8
Other definitions for example 8
Program structure for example 8


Example 9 Export file, transform file, and import file

This COBOL program illustrates how an XML document is generated from a COBOL data item, and then how the content of an XML document may be converted into COBOL data format and stored in a COBOL data item.

The program first writes (or exports) an XML document file from the content of a COBOL data item. Next, the document is transformed into another format (the same format as described in Example 2: Export File and Import File with XSLT Stylesheets and then transformed back into the original output format. Then the program reads (or imports) the same XML document and places the content in the same COBOL data item. One additional transform is applied to add in the COBOL attributes to the input document.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the contents of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TRANSFORM FILE, which uses an XSLT stylesheet to modify (transform) an XML document into another format.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 9
  • Batch file for example 9
  • Program description for example 9
  • Data item for example 9
  • Other definitions for example 9
  • Program structure for example 9
  • Execution results for example 9
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML EXPORT FILE
XML IMPORT FILE
XML TRANSFORM FILE
XML TERMINATE


Development for example 9

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 9 Export file, transform file, and import file
Related information
Batch file for example 9
Program description for example 9
Data item for example 9
Other definitions for example 9
Program structure for example 9
Execution results for example 9


Batch file for example 9

Use the same commands as for example 1 except substitute example01 with example09.

Parent topic: Example 9 Export file, transform file, and import file
Related information
Development for example 9
Program description for example 9
Data item for example 9
Other definitions for example 9
Program structure for example 9
Execution results for example 9


Program description for example 9

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an XML document with the filename of address09a.xml using the XML EXPORT FILE statement.

Next, the content of the XML document is transformed from the format that was used in Example 2 with an XML TRANSFORM FILE statement producing the file, address09b.xml, and then transformed back into the original output format.

Next, the content of the XML document is imported from the file, address09c.xml, and placed in the same data item using the XML IMPORT FILE statement.

Subsequently, the content of the XML document, address09c.xml, is transformed using the example09.xsl stylesheet to create the file, address09d.xml. This adds all of the COBOL attributes to address09d.xml.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 9 Export file, transform file, and import file
Related reference
XML INITIALIZE
XML EXPORT FILE
XML IMPORT FILE
XML TRANSFORM FILE
XML TERMINATE
Related information
Development for example 9
Batch file for example 9
Data item for example 9
Other definitions for example 9
Program structure for example 9
Execution results for example 9


Data item for example 9

The content of the COBOL data item, Address-Struct, is the same as in example 1.

Parent topic: Example 9 Export file, transform file, and import file
Related information
Development for example 9
Batch file for example 9
Program description for example 9
Other definitions for example 9
Program structure for example 9
Execution results for example 9


Other definitions for example 9

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 9 Export file, transform file, and import file
Related information
Development for example 9
Batch file for example 9
Program description for example 9
Data item for example 9
Program structure for example 9
Execution results for example 9


Program structure for example 9

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example09.cbl.

Initialization

COBOL Statement Description
XML INITIALIZE.
 Execute the XML INITIALIZE statement (no parameters).
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Exporting an XML document

COBOL Statement Description
Move … To Time-Stamp.
 Populate the Time-Stamp field.
XML EXPORT FILE
 Address-Struct
 "address09a"
 "Address-Struct".
 Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Transforming to external XML format

COBOL Statement Description
XML TRANSFORM FILE
 "address09a"
 "toext"
 "address09b".
 Execute the XML TRANSFORM FILE statement specifying: the input XML document filename, the XSLT stylesheet filename, and the output XML document filename.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Transforming to internal XML format

COBOL Statement Description
Initialize Address-Struct.
 Ensure that the address item contains no data.
XML TRANSFORM FILE
 "address09b"
 "toint"
 "address09c".
 Execute the XML TRANSFORM FILE statement specifying: the input XML document filename, the XSLT stylesheet filename, and the output XML document filename.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Importing an XML document

COBOL Statement Description
XML IMPORT FILE
 Address-Struct
 "address09c"
 "Address-Struct".
 Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Transforming to include COBOL attributes

COBOL Statement Description
XML TRANSFORM FILE
 "address09c"
 "example09"
 "address09d ".
 Execute the XML TRANSFORM FILE statement specifying: the input XML document filename, the XSLT stylesheet filename, and the output XML document filename.
If Not
XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 9 Export file, transform file, and import file
Related reference
XML INITIALIZE
XML EXPORT FILE
XML IMPORT FILE
XML TRANSFORM FILE
XML TERMINATE
Related information
Development for example 9
Batch file for example 9
Program description for example 9
Data item for example 9
Other definitions for example 9
Execution results for example 9


Execution results for example 9

COBOL display

The following sections display the output of the COBOL program that is run and the XML document that is generated.

Note: Pressing a key will terminate the program.

Running the program (run example09) produces the following display:

 Example-09 - Illustrate TRANSFORM FILE
 address09a.xml exported by XML EXPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/02 12:45:11.29
 address09a.xml transformed into address09b.xml by XML TRANSFORM
FILE
 address09b.xml transformed into address09c.xml by XML TRANSFORM
FILE
 address09c.xml imported by XML IMPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/02 12:45:11.29
 address09c.xml transformed into address09d.xml by XML TRANSFORM
FILE
 You may inspect 'address09a.xml' - 'address09d.xml'
 Status: +0000
Press a key to terminate:

Microsoft Internet Explorer may be used to view the generated XML documents, address09a.xml, address09b.xml, address09c.xml, and address09d.xml. Their content of these documents should appear as follows. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

address09a.xml - Internal format (similar to address01.xml)

address09b.xml - External format (similar to address02.xml)

address09c.xml - Internal format restored

address09d.xml - Internal format plus COBOL attributes

Parent topic: Example 9 Export file, transform file, and import file
Related information
Development for example 9
Batch file for example 9
Program description for example 9
Data item for example 9
Other definitions for example 9
Program structure for example 9


Example 10 Diagnostic messages

This program illustrates the diagnostic messages that may be displayed for XML documents that are not well-formed or valid. The program uses the XML TEST WELLFORMED-FILE and XML VALIDATE FILE statements to test and validate a series of XML documents. (These predefined XML documents are detailed in the Program Description section.)

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML TEST WELLFORMED-FILE, which verifies that an XML document conforms to XML syntax rules.
  • XML VALIDATE FILE, which verifies that the content of an XML document conforms to rules specified by an XML schema file.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 10
  • Batch file for example 10
  • Program description for example 10
  • Data item for example 10
  • Other definitions for example 10
  • Program structure for example 10
  • Execution results for example 10
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE


Development for example 10

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 10 Diagnostic messages
Related information
Batch file for example 10
Program description for example 10
Data item for example 10
Other definitions for example 10
Program structure for example 10
Execution results for example 10


Batch file for example 10

Use the same commands as for example 1 except substitute example01 with example10.

Parent topic: Example 10 Diagnostic messages
Related information
Development for example 10
Program description for example 10
Data item for example 10
Other definitions for example 10
Program structure for example 10
Execution results for example 10


Program description for example 10

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

In this example, three different predefined XML documents are processed:

The x-addressa1.xml file is not well-formed and will cause the XML TEST WELLFORMED-FILE statement to return with an error status. Since this function fails, the XML VALIDATE FILE statement is not used to process this file.

The x-addressa2.xml file is well-formed but not valid. The XML TEST WELLFORMED-FILE statement will return success. The XML VALIDATE FILE statement will return with an error status.

The x-addressa3.xml file is both well-formed and valid. Both the XML TEST-WELLFORMED-FILE statement and the XML VALIDATE FILE statement will return a successful status.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 10 Diagnostic messages
Related reference
XML INITIALIZE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE
Related information
Development for example 10
Batch file for example 10
Data item for example 10
Other definitions for example 10
Program structure for example 10
Execution results for example 10


Data item for example 10

The content of the COBOL data item, Address-Struct, is the same as in example 1.

Parent topic: Example 10 Diagnostic messages
Related information
Development for example 10
Batch file for example 10
Program description for example 10
Other definitions for example 10
Program structure for example 10
Execution results for example 10


Other definitions for example 10

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 10 Diagnostic messages
Related information
Development for example 10
Batch file for example 10
Program description for example 10
Data item for example 10
Program structure for example 10
Execution results for example 10


Program structure for example 10

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example10.cbl.

Initialization

COBOL Statement Description
XML INITIALIZE.
 Execute the XML INITIALIZE statement (no parameters).
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Testing for a well-formed document

COBOL Statement Description
XML TEST WELLFORMED-FILE
 "x-addressa1".
 Execute the XML TEST WELLFORMED-FILE statement specifying the XML document filename.
If Not XML-OK Perform Display-Status.
 If the statement terminates unsuccessfully, perform the Display-Status paragraph to display any error messages.
XML TEST WELLFORMED-FILE
 "x-addressa2".
 Execute the XML TEST WELLFORMED-FILE statement specifying the XML document filename.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Testing for a valid document

COBOL Statement Description
XML VALIDATE FILE
 "x-addressa2"
 "example10".
 Execute the XML VALIDATE FILE statement specifying: the XML document filename and the ModelFileName#DataName parameter value.
If Not XML-OK Perform Display-Status.
 If the statement terminates unsuccessfully, perform the Display-Status paragraph to display any error messages.

Testing for a well-formed document

COBOL Statement Description
XML TEST WELLFORMED-FILE
 "x-addressa3".
 Execute the XML TEST WELLFORMED-FILE statement specifying the XML document filename.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Testing for a valid document

COBOL Statement Description
XML VALIDATE FILE
 "x-addressa3"
 "example10".
 Execute the XML VALIDATE FILE statement specifying: the XML document filename and the ModelFileName#DataName parameter value.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 10 Diagnostic messages
Related reference
XML INITIALIZE
XML TEST WELLFORMED-FILE
XML VALIDATE FILE
XML TERMINATE
Related information
Development for example 10
Batch file for example 10
Program description for example 10
Data item for example 10
Other definitions for example 10
Execution results for example 10


Execution results for example 10

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Running the program (run example10) produces three displays: the first is shown after the first diagnostic message, the second is shown after the second diagnostic message, and the third is displayed after some successful tests.

Note: Because of differences in the underlying XML parsers, the results of running Example 10 vary between Windows and UNIX. When a parser error occurs, the current UNIX implementation does not display the offending line of XML text in error (as shown in the first display) because on UNIX systems, the underlying XML parser, libxml, does not support schema validation. Under UNIX, errors that would be detected by a schema are not reported (as illustrated in the second display). The third display, however, is the same under both implementations.

First display

Note: Pressing a key will cause the program to continue.

For Windows, the first display would be illustrated as:

Example-10 - Illustrate diagnostics for invalid
documents
 and documents that are not well-formed
 XML TEST WELLFORMED-FILE - not well-formed ...
Error: 28[34] - in function: LoadDocument
MSXML 6.0 parse error code: 0xc00cee3b
The name in the end tag of the element must match the element type
in the start\
 tag.
line 13, position 21
</non-address-struct> <!-- intentional tag mismatch
-->
--------------------|
C:\xmlext\examples\x-addressa1.xml
HRESULT: 0x80004005
 ... wellformedness test failed (as it should).
 Press a key to continue:

For UNIX, the first display would be shown as follows:

 Example-10 - Illustrate diagnostics for invalid
documents
 and documents that are not well-formed
 XML TEST WELLFORMED-FILE - not well-formed ...
Error: 28[2] - in function: LoadDocument
/usr/xmlext/examples/x-addressa1.xml
13: parser error : Opening and ending tag mismatch: address-struct
line 2 and n\
on-address-struct
</non-address-struct> <!-- intentional tag mismatch
-->
 ^
 ... wellformedness test failed (as it should).
 Press a key to continue:

Second display

Note: Pressing a key will cause the program to continue.
For Windows, the second display would be illustrated as:
XML TEST WELLFORMED-FILE - well-formed &
invalid ...
 ... wellformedness test succeeeded.
 XML VALIDATE FILE - well-formed - invalid ...
Error: 28[34] - in function: LoadDocument
MSXML 6.0 parse error code: 0xc00ce201
Error parsing 'ABCDE' as decimal datatype. The element 'zip' with
value 'ABCDE\
' failed to parse.
line 9, position 20
 <zip>ABCDE</zip> <!-- intentional nonnumeric zip
code -->
-------------------|
C:\xmlext\examples\x-addressa2.xml
HRESULT: 0x80004005
 ... validation failed (as it should).
 Press a key to continue:
For UNIX, the second display would be shown as follows:
XML TEST WELLFORMED-FILE - well-formed &
invalid ...
 ... wellformedness test succeeeded.
 XML VALIDATE FILE - well-formed - invalid ...
Error: 28[4] - in function: LoadDocument
/usr/xmlext/examples/x-addressa2.xml
9: element zip: Schemas validity error : Element 'zip': 'ABCDE' is
not a valid \
value of the atomic type 'type_Q8_example-a'.
 ... validation failed (as it should).
 Press a key to continue:

Third Display

Note: Pressing a key will terminate the program.
 XML TEST WELLFORMED-FILE - well-formed - valid
...
 ... wellformedness test succeeeded.
 XML VALIDATE FILE - well-formed - valid ...
 ... validation successful.
 Status: +0000
Press a key to terminate:

For UNIX, the third display would be the same, but the XML document has only been verified to be well-formed and might not conform to the schema; however, for this example, the document does conform to the schema.

Parent topic: Example 10 Diagnostic messages
Related information
Development for example 10
Batch file for example 10
Program description for example 10
Data item for example 10
Other definitions for example 10
Program structure for example 10


Example 11 Import file with missing intermediate parent names

This COBOL program illustrates how an XML document with some missing intermediate parent names may be converted into COBOL data format and stored in a COBOL data item. (This capability of handling missing intermediate parent names has been included to make programs that deal with "flattened" data items, such as Web services, less complicated.) A COBOL program and an XML document file may contain the same elementary items, but may not have the identical structure. XML Extensions offers a way to handle such cases where there is not a one-to-one match between the COBOL data item and the XML document structure. Consider the following situation, in which the COBOL program imports a predefined XML document that has some missing intermediate parent names.

A missing intermediate parent name is an XML element name that corresponds to an intermediate-level COBOL group name. For example, in the following COBOL data item, the XML element name, address-3, is an intermediate parent name.
 01 MY-ADDRESS.
 02 ADDRESS-1 PIC X(64) VALUE "101 Main St.".
 02 ADDRESS-2 PIC X(64) VALUE "Apt 2B".
 02 ADDRESS-3.
 03 CITY PIC X(32) VALUE "Smallville".
 03 STATE PIC X(2) VALUE "KS".
The structure of the corresponding XML document would be:
<my-address> <address-1>101 Main St.</address-1>
             <address-2>Apt 2B</address-2>
             <address-3><city>Smallville</city>
                         <state>KS</state> </address-3>
</my-address>

In cases where the intermediate parent name is not needed to resolve ambiguity, XML Extensions will attempt to reconstruct the document structure on input. For example, if the input XML document contained the following information, then the intermediate parent names of address-3 and my-address would be added to produce an XML document compatible with the above document.

<root> <address-1>101 Main St.</address-1> <address-2>Apt 2B</address-2>
       <city>Smallville</city> <state>KS</state>
</root>

Example 11 illustrates this situation more fully.

This example uses the following XML statements:

  • XML INITIALIZE, which initializes or opens a session with XML Extensions.
  • XML EXPORT FILE, which constructs an XML document (as a file) from the content of a COBOL data item.
  • XML IMPORT FILE, which reads an XML document (from a file) into a COBOL data item.
  • XML TERMINATE, which terminates or closes the session with XML Extensions.
  • Development for example 11
  • Batch file for example 11
  • Program description for example 11
  • Data item for example 11
  • Other definitions for example 11
  • Program structure for example 11
  • Execution results for example 11
Parent topic: Appendix A XML Extensions examples
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE


Development for example 11

The COBOL program must be compiled with a Visual COBOL compiler using the XMLGEN compiler directive to generate an XML-format model file.

After the successful compilation, you may then execute the COBOL program.

Parent topic: Example 11 Import file with missing intermediate parent names
Related information
Batch file for example 11
Program description for example 11
Data item for example 11
Other definitions for example 11
Program structure for example 11
Execution results for example 11


Batch file for example 11

Use the same commands as for example 1 except substitute example01 with example11.

Parent topic: Example 11 Import file with missing intermediate parent names
Related information
Development for example 11
Program description for example 11
Data item for example 11
Other definitions for example 11
Program structure for example 11
Execution results for example 11


Program description for example 11

This COBOL program illustrates how an XML document with some missing intermediate parent names may be converted into COBOL data format and stored in a COBOL data item.

Before any other XML statement may be executed, the XML INITIALIZE statement must be successfully executed. Since it is possible for XML INITIALIZE to fail, the return status must be checked before continuing.

Data is exported from the data item Address-Struct (as defined in the copybook, s-struct.cpy) to an XML document with the filename of address11.xml using the XML EXPORT FILE statement.

Next, the content of the XML document is imported from the file, address11.xml, and placed in the same data item using the XML IMPORT FILE statement.

Additionally, the content of the predefined XML document named x?address11.xml, which has some missing intermediate parent names, is also imported using the XML IMPORT FILE statement.

Finally, the XML interface is terminated with the XML TERMINATE statement.

If any of the statements terminate unsuccessfully, the XML GET STATUS-TEXT statement is called.

Parent topic: Example 11 Import file with missing intermediate parent names
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
Related information
Development for example 11
Batch file for example 11
Data item for example 11
Other definitions for example 11
Program structure for example 11
Execution results for example 11


Data item for example 11

The content of the COBOL data item, Address-Struct, is the same as in example 1.

Parent topic: Example 11 Import file with missing intermediate parent names
Related information
Development for example 11
Batch file for example 11
Program description for example 11
Other definitions for example 11
Program structure for example 11
Execution results for example 11


Other definitions for example 11

The copybook, lixmlall.cpy, should be included in the Working-Storage Section of the program.

The copybook, lixmldef.cpy, which is copied in by lixmlall.cpy, defines a data item named XML-data-group. All of this is the same as in previous examples.

Parent topic: Example 11 Import file with missing intermediate parent names
Related information
Development for example 11
Batch file for example 11
Program description for example 11
Data item for example 11
Program structure for example 11
Execution results for example 11


Program structure for example 11

The following tables show COBOL statements that relate to performing XML Extensions statements. Some COBOL statements (mostly the DISPLAY statements) have been omitted. The source of this example is in the file, example11.cbl.

Initialization

COBOL Statement Description
XML INITIALIZE.
 Execute the XML INITIALIZE statement (no parameters).
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.
COBOL Statement Description
Move … To Time-Stamp.
 Populate the Time-Stamp field.
XML EXPORT FILE
 Address-Struct
 "address11"
 "Address-Struct".
 Execute the XML EXPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.
If Not
XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.
COBOL Statement Description
Initialize Address-Struct.
 Ensure that the address item is initialized.
XML IMPORT FILE
 Address-Struct
 "address11"
 "Address-Struct".
 Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.
COBOL Statement Description
Initialize Address-Struct.
 Ensure that the address item is initialized.
XML IMPORT FILE
 Address-Struct
 "x-address11"
 "Address-Struct".
 Execute the XML IMPORT FILE statement specifying: the data item address, the XML document filename, and the ModelFileName#DataName parameter value.
If Not XML-OK Go To Z.
 If the statement terminates unsuccessfully, go to the termination logic.

Program exit logic

Same as example 1.

Termination test logic

Same as example 1.

Status display logic

Same as example 1.

Parent topic: Example 11 Import file with missing intermediate parent names
Related reference
XML INITIALIZE
XML IMPORT FILE
XML EXPORT FILE
XML TERMINATE
Related information
Development for example 11
Batch file for example 11
Program description for example 11
Data item for example 11
Other definitions for example 11
Execution results for example 11


Execution results for example 11

The following sections display the output of the COBOL program that is run and the XML document that is generated.

COBOL display

Note: Pressing a key will terminate the program.

Running the program (run example11) produces the following display:

 Example-11 - Illustrate IMPORT with missing
intermediate names
 address11.xml exported by XML EXPORT FILE
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/02 13:58:13.62
 address11.xml imported by XML IMPORT FILE:
 Name: Specialty Cowboy Boots Company
Address-1: 1050 North San Antonio Street
Address-2: Suite 200
Address-3: Austin TX78701
Country: United States of America
Time-Stamp: 2013/07/02 13:58:13.62
 x-address11.xml imported by XML IMPORT FILE:
 Name: Wild Hair Corporation
Address-1: 3543 Hair Court
Address-2: Sweet 800
Address-3: Lostin TX78787
Country: United States of America
Time-Stamp: 00:00:00.00
 You may inspect 'address11.xml' & 'x-address11.xml'
 Status: +0000
Press a key to terminate:

XML document

Microsoft Internet Explorer may be used to view the generated XML document, address11.xml and the predefined XML document x-address11.xml. (Note that Internet Explorer will differentiate among the various syntactical elements of XML by displaying them in different colors.)

address11.xml

xaddress11.xml

Parent topic: Example 11 Import file with missing intermediate parent names
Related information
Development for example 11
Batch file for example 11
Program description for example 11
Data item for example 11
Other definitions for example 11
Program structure for example 11


Example batch files

Three batch files are provided to facilitate use of the example programs: cleanup.bat, example.bat, and examples.bat.
  • Cleanup.bat
  • Example.bat
  • Examples.bat
Parent topic: Appendix A XML Extensions examples


Cleanup.bat

This batch file will remove various files that were created by executing the example programs. This file contains a series of delete file commands similar to the following:

 @echo off
echo Cleanup started ...
if exist example*.int del example*.int
if exist example*.exe del example*.exe
if exist example*.lst del example*.lst
if exist example*.xml del example*.xml
if exist address*.xml del address*.xml
if exist table1.xml del table1.xml
if exist table2.xml del table2.xml
if exist table3.xml del table3.xml
if exist table4.xml del table4.xml
if exist stamp\*.xml rmdir stamp /q /s
echo finished cleanup.

This batch file has no parameters. Run it by entering the following on the command line:

cleanup

Parent topic: Example batch files
Related information
Example.bat
Examples.bat


Example.bat

This batch file will compile a COBOL source program, and execute the COBOL program. The content of this file is as follows:
 @echo off
setlocal
REM %1 == example program file name (without extension)
 REM Compile the example program given by %1
set COBCPY=..;%COBCPY%
cobol %1 list() xmlgen(ws) noobj;
REM To compile for .NET managed code comment out the above line and
uncomment the following line
REM cobol %1 list() xmlgen(ws) ilgen iltarget(x86)
ilref(MicroFocus.COBOL.XmlExtensions)
ilref(MicroFocus.COBOL.XmlExtensions.Interop);
 REM Run example program
REM COBPATH needs to include the location of cobxmlext.dll.
run %1
endlocal

This batch file uses parameters that are specified by the caller of the batch file. The parameter is the filename of the COBOL program (without the .cbl extension).

To build and run Example 1 Export file and import file using this batch file, enter the following on the command line:

example example01

Parent topic: Example batch files
Related information
Cleanup.bat
Examples.bat


Examples.bat

This batch file will clean up files that were created from a previous run and then compile and run each example. The content of this file is similar to the following:

@echo off
call cleanup
echo Example01 - Export / Import File.
call example example01
echo Example02 - Export / Import with XSLT stylesheets.
call example example02
echo Example03 - Export / Import with Occurs Depending.
call example example03
echo Example04 - Export / Import with sparse arrays.
call example example04
echo Example05 - Export / Import Text.
call example example05
echo Example06 - Export / Import with directory polling.
mkdir stamp
call example example06
echo Example07 - Export / Well-Formed File / Validate File.
call example example07
echo Example08 - Export / Well-Formed Text / Validate Text.
call example example08
echo Example09 - Export / Transform / Import.
call example example09
echo Example10 - Well-Formed / Validate diagnostics.
call example example10
echo Example11 - Import with missing intermediate names.
call example example11

This batch file has no parameters. Run it by entering the following on the command line:

examples

Note: On UNIX systems, the script named examples.sh is provided for the same purpose as examples.bat on Windows.
Parent topic: Example batch files
Related information
Cleanup.bat
Example.bat


Appendix B: XML Extensions sample application programs

XML Extensions provides several complete and useful sample application programs. The purpose of these self-contained programs is to demonstrate and explain how to perform typical application-building tasks in XML Extensions within a realistic context so that you can better see how to integrate them into your own applications.

Accessing the sample application programs

The sample application programs are included in the XML Extensions samples directory, Samples. Click on the Samples link installed by Visual COBOL to use the Samples Browser to locate the XML Extensions samples and examples.

Each sample application program is intended to reside in a separate subdirectory. For example, the XFORM sample resides in the directory named Samples/xform. Documentation for the sample is contained in the directory in the form of an HTML file.

On UNIX systems, the applications were extracted when the samples were installed. The XFORM sample in Samples/xform contains the files, xform.cbl and xform.htm.

Parent topic: XML Extensions
Related reference
Development components
Typical development process example


Appendix C: XML Extensions error messages

This appendix lists and describes the messages that can be generated during the use of XML Extensions.

Error message format

XML Extensions error messages may be several lines long. The general format of an error message includes the text of the message, and, if available, the COBOL traceback information, the name of the file or data item, and the parser information.

Message Text

The first line of the error message has the following format:

<severity> - <message number> <message text>
  • Severity indicates the gravity and type of message: Informative, Warning, or Error.
  • Message number is the documented message number followed by an internal message number in bracket characters. The internal number provides information for technical support to use in diagnosing problems.
  • Message text is a brief explanation for the cause of the error.

An example of the first line of an error message is shown below:

Error: 28[12] - in function: LoadDocument

COBOL Traceback Information

The second line of the error message, present if the information is available, contains COBOL traceback information such as the following:

Called from line 421 in TEST15.COB(C:\DEV\TEST15.COB), compiled 2003/05/14 09:42:06.

The error-reporting facility will try to break up lines that are too long for the line buffer provided in the COBOL program. This prevents long lines from being truncated. A backward slash character (\) is placed in the last position of the buffer and the line is continued on the subsequent line. For example, the traceback line shown above may be broken up as follows:

Called from line 421 in TEST15.COB(C:\DEV\TEST15.COB), co\

mpiled 2003/05/14 09:42:06.

Filename or Data Item in Error

The third line of the error message, present if the information is available, normally contains the name of the file or data item in error being referenced.

Parser Information

Note: This section applies to the Windows implementation of XML Extensions only.

Additional lines may be present that contain parser or schema diagnostics from the underlying XML parser, such as:

Error parsing 'a9' as number datatype. line 5, position 25 <ItemCount>a9</ItemCount> ----------- --|

The first line of parser or schema diagnostic information contains an error message. The second line contains the line number and column position within the XML document. The third line contains the line of XML text in error. The fourth line contains an indicator that draws attention to the column position.

  • Summary of error messages in XML Extensions
Parent topic: XML Extensions
Related reference
Summary of error messages in XML Extensions


Summary of error messages in XML Extensions

The following table describes the messages that may be generated when an error occurs in XML Extensions:

Message Number | Severity and Message Text | Description
-6 | Warning - ambiguous import name. | An element name in an imported XML document is defined more than once in the symbol table determined by the ModelFileName#DataName parameter of the XML IMPORT statement. Further, the element name is defined more than once subordinate to the model data name. XML Extensions assumes the first of the duplicates found, which is the lexically last defined duplicate, should be used and continues. If that name already has an imported value for the current import and is not a table (array) element, the next duplicate is assumed; that is, a lexically previous duplicate definition. For arrays, the array is consecutively filled before moving on to look for another duplicate. If there is no duplicate name without a previously imported value, a -02 extraneous element warning is produced and the imported text value is discarded. This warning is not produced if the XML document does not have any text content, after ignoring whitespace, for the element. This warning is also not produced if the XML document contains sufficient qualification, that is, parent element names, to make the reference unique. When a duplicate name is not subordinate to the model data name, this warning is not produced unless all duplicate names are not subordinate to the model data name.
-5 | Warning - ambiguous model data name | More than one matching data name was found in the document. The most recently found data name is used.
-4 | Warning - subscript out of range | A subscript is out of range on import. The offending item is not imported.
-3 | Warning - data truncation | A nonnumeric import item has been truncated to fit the associated COBOL data item.
-2 | Warning - extraneous element | The import data contains one or more elements that do not belong anywhere in the COBOL data structure; the element(s) have been ignored.
0 | Success | A normal completion occurred. No informative, warning, or error message was detected.
1 | Informative - directory contains no documents | An XML FIND FILE statement did not find any XML documents (files with an .xml extension) in the specified directory.
2 | Informative - document file - no data | An XML EXPORT FILE or an XML EXPORT TEXT statement generated a document that contained no element values.
3 | Warning - internal logic - memory not deallocated | During process cleanup, memory blocks that should have already been deallocated were still allocated.
9 | Error - in function: CreateDocument | The underlying XML parser detected an error while trying to create an XML document.
10 | Error - cannot create URL | The XML Extensions library detected that a URL (a string beginning with the sequence http://, https://, or file://) was used as an output document name.
12 | Error - data item - not found | The XML Extensions library detected that there are no occurrences of the specified data item name in the model template file.
13 | Error - document file - create failure | An attempt to create an XML document file failed.
14 | Error - document file - file open failure | The XML Extensions library detected an error while attempting to open an XML document file.
15 | Error - extraneous element | The XML Extensions library detected an extra occurrence of a scalar data element.
17 | Error - in function: GetFirstChild | The XML Extensions library detected an error in the function GetFirstChild while parsing an XML document.
18 | Error - in function: GetNextSibling | The XML Extensions library detected an error in the function GetNextSibling while parsing an XML document.
19 | Error - in function: GetNodeData | The XML Extensions library detected an error in the function GetNodeData while parsing an XML document.
20 | Error - in function: GetRootNode | The XML Extensions library detected an error in the function GetRootNode while parsing an XML document.
21 | Error - internal logic - memory allocation | An attempt to allocate a block of memory failed.
22 | Error - internal logic - memory corruption | An attempt to deallocate (free) a block of memory failed either because the block header or trailer was corrupted or because the free memory call returned an error.
23 | Error - internal logic - node not found | The XML Extensions library detected an inconsistency in its internal tables. Specifically, an expected entry in the Document Object Model is missing.
24 | Error - in function: Initialization | Either an XML statement (other than XML INITIALIZE) was executed without first executing the XML INITIALIZE statement or the XML INITIALIZE statement failed.
25 | Error - invalid data address | The XML Extensions library detected that the data structure address specified in an XML IMPORT or an XML IMPORT statement does not match the data address specified in the template file. This normally means that the COBOL program has been re-compiled but the model files produced by the XMLGEN compiler directive were not re-generated and are outdated.
28 | Error - in function: LoadDocument | An error was detected while trying to load an XML document. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions). Occasionally, XML Extensions generates documents that are then loaded as input documents. In the unlikely event that the generated document contains errors, a load document error will be encountered.
29 | Error - in function: LoadSchema | An error was detected while trying to load an XML schema file. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions) or that the schema itself is in error.
30 | Error - in function: LoadStyleSheet | An error was detected while trying to load an internal or external XSLT stylesheet. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions). Another possible cause is that the XML parser software is not properly installed.
32 | Error - in function: LoadTemplate | An error was detected while trying to load an XML template file. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions). Another possible cause is that the XML parser software is not properly installed.
35 | Error - subscript out of range | While executing an XML IMPORT FILE or an XML IMPORT TEXT statement, the XML Extensions library detected that a subscript reference is out of range (the subscript value is greater than the maximum for the array). This may occur either when the subscript is explicitly supplied in an attribute or when the subscript is generated implicitly (when an extra occurrence is present).
36 | Error - temporary file access error | The XML Extensions library encountered an error while attempting to access a temporary intermediate file. This error can occur during the XML IMPORT TEXT, XML EXPORT TEXT, XML VALIDATE TEXT, or XML TEST WELLFORMED-TEXT statements.
37 | Error - in function: TransformDOM | An unexpected error occurred while performing an XSLT transform of an XML document. This might be an internal error, but can be caused by an error in an external stylesheet.
38 | Error - in function: TransformText | An error occurred while performing an XSLT transform of an XML document using an external (user-supplied) XSLT stylesheet. This error may occur in the XML Extensions library.
39 | Error - symbol table - not present in model file | The symbol table was not found in the specified model file. The model file was probably not produced by the XMLGEN compiler directive.
42 | Error - in function: WriteDocument | An error occurred while attempting to write an XML document from the internal Document Object Model representation.
45 | Error - invalid encoding selection | The value of the Encoding parameter of the XML SET ENCODING statement was neither "local" nor "utf-8".
46 | Error - invalid UTF-8 data | An XML export operation failed because the data supplied was not valid for UTF-8.
47 | Error - invalid MF_XMLEXT_LOCAL_ENCODING value | The value of the MF_XMLEXT_LOCAL_ENCODING environment variable on UNIX is not any of "mflatin1", "mflatin9", or a name recognized by the available iconv library.
48 | Error - unable to locate iconv library | The value of the MF_XMLEXT_LOCAL_ENCODING environment variable on UNIX is not "mflatin1" nor "mflatin9", but an iconv library for character conversions could not be found.
49 | Error - directory open failure | The XML FIND FILE statement was not able to locate and open the specified directory.
50 | Error - missing XML parser (MSXML6) | The XML parser could not be found. This error occurs only on Windows and indicates the MSXML 6.0 parser is not installed in the Windows system. The MSXML 6.0 parser is normally installed when Visual COBOL is installed on Windows, but could not be found. MSXML 6.0 can be obtained by downloading it from Microsoft's web site.
51 | Error - data item - illegal name format | A data-name being exported does not begin with an initial name character (letter, colon or underscore). This error should not occur; XML Extensions prepends an underscore to COBOL data-names that begin with a digit when creating XML names.
52 | Error - CodeBridge conversion failure | The attempted conversion of data to or from a COBOL data type and a displayable string acceptable to XML failed.
53 | Error - Name specified is not a data-item | When specifying a data structure name, a name was provided that is not a data item. For example, it might be a file-name, an index-name, a constant-name, and so forth. A data item name is required.
62 | Error - requested template file cannot be found | Requested template file specified by the model file data name parameter cannot be found.
63 | Error - resolved file name is too long | The resolved filename from one of the following statements is too large to fit in the buffer provided: XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, XML IMPORT TEXT, XML RESOLVE DOCUMENT-FILE, XML RESOLVE SCHEMA-FILE, XML RESOLVE STYLESHEET-FILE, XML RESOLVE MODEL-FILE
64 | Error - resolved file name does not exist | The file name passed to one of the following statements cannot be resolved. It may not exist and is not accessible. XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, XML IMPORT TEXT, XML RESOLVE DOCUMENT-FILE, XML RESOLVE SCHEMA-FILE, XML RESOLVE STYLESHEET-FILE
65 | Error - name / value pair required | The XML SET XSL-PARAMETERS statement requires an even number of parameters (name / value pairs).
66 | Error - excessive number of XSL parameters | The XML SET XSL-PARAMETERS statement is limited to a maximum of 40 parameters (20 name / value pairs).
67 | Error - unique identifier too long for buffer | The buffer supplied in the XML GET UNIQUEID statement is too small. Unique identifiers require 38 character positions.
68 | Error - add attribute node failed | Adding an attribute to the document failed.
69 | Error - add element node failed | Adding an element to the document failed.
70 | Error - add text node failed | Adding a text mode to the document failed.
71 | Error - validate DOM document | Validating the DOM document failed.
72 Error - import offset outside target data structure

An attempt to store outside the target data structure determined by the DataItem parameter of the XML IMPORT statement has been detected. This can happen because of a model template file that is out-of-date with the executing COBOL program; in this case, the model template file needs to be regenerated from the revised COBOL program. Another cause can be duplicate data names in the symbol table and insufficient qualification (parent elements) in the imported XML document to choose the correct data item target for the import.

The attempted import is suppressed along with any further import operations for the affected XML IMPORT statement.

73 | Error - trace file open failed | The trace file name specified in an XML TRACE statement could not be opened. The most common cause of this error is that a directory name that does not exist is specified as part of the file name. Other errors that could cause this are access denied (because the file is read-only or the user does not have permissions to the file) or the program does not have permission to write to the directory specified. The program can continue, but tracing will be disabled. This error is only returned when the XML TRACE statement opens the trace file for the first time. Subsequent trace file open failures while the program is running other XML Extensions statements cause tracing to be suppressed.
74 | Error - exported DataItem smaller than data structure in ModelFile | The COBOL data item being exported is smaller than the data structure described by the data-name specified for export. This would cause an attempt to access data beyond the end of the data item in the COBOL program, possibly causing a memory access violation. Make sure that the data item name, sometimes referred to as the data structure name, references an area in the COBOL program that is at least as large as the data-name.
75 | Error - incorrect XML statement parameters | One or more of the parameters passed into the XML statement are invalid. This includes errors such as too few or too many parameters in the XML statement. This error also can indicate an invalid type of parameter, such as a POINTER data item specified where a pointer is not allowed or a nonnumeric or numeric parameter specified where a POINTER data item is required. Additional information, which can be obtained with XML GET STATUS-TEXT, describes the specific problem with the parameter or parameters. Only the first detected parameter error is described by the additional information. An incorrect number of parameters is always detected first.
Parent topic: Appendix C: XML Extensions error messages
Related information
ACUCOBOL


XML Syntax Extensions

Your COBOL development system supports the creation of relationships between COBOL data structures and element definitions in XML schemas. You can create COBOL XML syntax extensions, which enable you to code references to XML structures right into your COBOL definitions. These XML structures are used to input and output information in an XML format.

  • XML Implementation
  • Syntax for Handling XML in COBOL
  • Compiling XML-enabled COBOL
Parent topic: Using COBOL and XML together
Related information
Generating COBOL Structures with XML Syntax from the Command Line
Generating a Copybook and Schema
Accessing an XML-enabled Record


XML Implementation

XML data encoding is record-based and the vast majority of possible encodings can be easily represented as COBOL data records. For example, this XML stream:

<?xml version="1.0"?>
<group elementNumber=1235 >
   <elementAlpha>Alpha value</elementAlpha>
</group>

Can be received directly by COBOL code using syntax extensions as follows:

01  xmls-group                    identified by "group".
    05  xmls-Number     pic 9(18) identified by
        "elementNumber" is attribute.
    05  xmls-Alpha      pic x(80) identified by
        "elementAlpha".

This is a simple example. However, we support a number of more complex syntax scenarios, including variable tag specifications, non-regular and nested occurrences, mixed data, and optional elements.

Once you are able to encode XML records in your application, you can originate or receive these records in your COBOL application. Do this using standard file input/output verbs including OPEN, READ, WRITE, and CLOSE. The run-time support automatically converts, encodes, and performs all of the necessary I/O. For example, the following code is all that is necessary to generate the XML stream depicted in the example above into the file out.xml:

$set preprocess(prexml) endp
 select xml-stream assign "out.xml"
           organization  is xml
           document-type is "group"
           file status is xml-bookdb-status.
     xd xml-stream.
     01  xmls-group                identified by "group".
         05  xmls-Number pic 9(18)
             identified by "elementNumber" is attribute.
         05  xmls-Alpha  pic x(80)
             identified by "elementAlpha".
     working-storage section.
     01  xml-bookdb-status         pic s9(9) comp.

     move 1235                     to xmls-Number
     move "Alpha value"            to xmls-Alpha
     open output xml-stream
     write xmls-group
     close xml-stream
     stop run.
Parent topic: XML Syntax Extensions


Syntax for Handling XML in COBOL

Syntax is provided specially designed to XML-enable COBOL. The following paragraph and clause descriptions are specifically for reading and writing XML from COBOL.

Note: If you want to compile the examples in this section, be sure to place the line numbers starting in column 3.
  • SELECT Paragraph
  • XML Description Paragraph (XD)
  • IDENTIFIED BY and IS ATTRIBUTE Clauses
  • PROCESSING-INSTRUCTION Clause
  • COUNT IN Clause
  • NAMESPACE Clause
  • COBOL Verbs
Parent topic: XML Syntax Extensions


SELECT Paragraph

The SELECT paragraph has been extended to enable you to assign a file name to an XML stream using the ASSIGN clause. The ASSIGN clause determines the routing of the XML stream and declares the schema that the stream conforms to. The actual format of the stream is solely determined by the record definitions contained in the XML Descriptor (XD) paragraph in the File Section.

Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - SELECT Clause


XML Description Paragraph (XD)

For every file with an organization of XML, a set of record definitions is required to define the format of the XML stream being manipulated. These record definitions are contained in the XD paragraph in the File Section of the source program.

The following are not supported in the XD paragraph:

  • TYPEDEF
  • IS EXTERNAL
  • IS THREAD-LOCAL
  • VALUE
  • ANY LENGTH
Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - XD File Description


IDENTIFIED BY and IS ATTRIBUTE Clauses

Use this syntax when declaring a COBOL data record to map the record to an XML element (tag) or an XML attribute that is defined in an XML schema or document.

You match up an XML tag with a COBOL data record using IDENTIFIED BY, and match up attributes for the XML tags with the addition of IS ATTRIBUTE. For example:

If you had an XML document that contained the following:

<company_name type="accounting">Webber Lynch</company_name>

a matching COBOL record using the IDENTIFIED BY and IS ATTRIBUTE clauses would be as follows:

    05  company identified by "company_name".
        10  company-name-value   pic X(30).
        10  company-type    pic x(10)
            identified by "type" is attribute.

You can work with variable tag and attribute names in your XML-enabled program, as well as known tag names. Using this method, you specify tags and attributes by substituting a COBOL data-name for a tag or an attribute name. On an XML file opened for output, this allows you to write purely dynamic and arbitrarily complex XML documents. On a file opened for input this allows you to read such complex documents. For example, the following program reads any XML stream that has a single root tag, any number of single nested tags and any number of attributes per tag:

Using the IDENTIFIED BY and IS ATTRIBUTE clauses

0010 $set preprocess(prexml) o(foo.pp) warn endp
0030
0040 select doc           assign address of mybuf
0050                      organization is xml
0060                      document-type is external doc-type
0070                      file status is doc-status.
0080 xd doc.
0090 01  root-tag            identified by root-tag-name.
0100     10  root-tag-name   pic x(80).
0110     10  root-tag-val    pic x(80).
0120     10  root-tag-attr   identified by root-tag-attr-name
0130                         is attribute.
0140         15  root-tag-attr-name pic x(80).
0150         15  root-tag-attr-val  pic x(80).
0160
0170     10  sub-tag              identified by sub-tag-name.
0180         15  sub-tag-name pic x(80).
0190         15  sub-tag-val  pic x(80).
0200         15  sub-tag-attr identified by sub-tag-attr-name
0210                          is attribute.
0220             20  sub-tag-attr-val  pic x(80).
0230             20  sub-tag-attr-name pic x(80).
0240
0250 working-storage section.
0260 01  doc-type            pic x(80).
0270 01  doc-status          pic s9(9) comp.
0280 01  mybuf.
0290     10  pic x(300) value
0300     '<library location="here" '
0310     &    'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" '
0320     &    'xsi:schemaLocation="library.xsd">'
0330     &  '<book published="yes" goodreading="ok">'
0340     &   'booktext'
0350     &  '</book>'
0360     &  'is a place'
0370     & '</library>'.
0380
0390 procedure division.
0400     open input doc
0410     read doc
0420     display "Document type is: " doc-type
0430     display "Tag name: " root-tag-name
0440     display "Tag value:" root-tag-val
0450     start doc key root-tag-attr
0460     *>
0470     *> Loop through all attributes dumping names
0480     *>
0490
0500     perform until exit
0510        read doc next key root-tag-attr
0520        if  doc-status not = 0
0530            exit perform
0540        end-if
0550        display "Attribute name : " root-tag-attr-name
0560        display "Attribute value: " root-tag-attr-val
0570     end-perform
0580
0590     *> Loop through all sub-tags
0600     start doc key sub-tag
0610     perform until exit
0620        read doc
0630          next key sub-tag *> index is 1 is default
0640        if  doc-status not = 0
0650            exit perform
0660        end-if
0670        display " Sub tag name: " sub-tag-name
0680        display " Sub tag value:" sub-tag-val
0690
0700        start doc key sub-tag-attr index is 1
0710        perform until exit
0720            read doc next key sub-tag-attr
0730            if  doc-status not = 0
0740                exit perform
0750            end-if
0760            display " Sub tag attribute name : "
0770              sub-tag-attr-name
0780            display " Sub tag attribute value: "
0790              sub-tag-attr-val
0800        end-perform
0810    end-perform
0820
0830    close doc
0840
0850    stop run.

Lines 0040 - 0070:

0040 select doc           assign address of mybuf
0050                      organization is xml
0060                      document-type is external doc-type
0070                      file status is doc-status.

Assigns a filename and the buffer mybuf as the source of the XML input, specifies the organization of the file (XML), provides a data-name that variably specifies the XML schema name, and provides a data-name for the file status.

Lines 0080 - 0230:

0080 xd doc.
0090 01  root-tag            identified by root-tag-name.
0100     10  root-tag-name   pic x(80).
0110     10  root-tag-val    pic x(80).
0120     10  root-tag-attr   identified by root-tag-attr-name
0130                         is attribute.
0140         15  root-tag-attr-name pic x(80).
0150         15  root-tag-attr-val  pic x(80).
0160
0170     10  sub-tag              identified by sub-tag-name.
0180         15  sub-tag-name pic x(80).
0190         15  sub-tag-val  pic x(80).
0200         15  sub-tag-attr identified by sub-tag-attr-name
0210                          is attribute.
0220             20  sub-tag-attr-val  pic x(80).
0230             20  sub-tag-attr-name pic x(80).

Sets up the record structure of the buffer area.

Lines 0280 - 0370:

0280 01  mybuf.
0290     10  pic x(300) value
0300     '<library location="here" '
0310     &         'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" '
0320     &         'xsi:schemaLocation="library.xsd">'
0330     &    '<book published="yes" goodreading="ok">'
0340     &       'booktext'
0350     &    '</book>'
0360     &    'is a place'
0370     & '</library>'.

Codes the XML stream to be read into a static buffer. While this example has the XML stream coded directly into the program, you could also place the XML into the buffer (mybuf) using any standard input.

Lines 0400 - 0440:

0400     open input doc
0410     read doc
0420     display "Document type is: " doc-type
0430     display "Tag name: " root-tag-name
0440     display "Tag value:" root-tag-val

Opens the buffer area, reads in the XML record, and displays the document type, the name of the root tag, and the value of the root tag.

Line 0450:

0450     start doc key root-tag-attr

Sets the starting point in the buffer to the first attribute for the root tag.

Lines 0500 - 0570:

0500     perform until exit
0510        read doc next key root-tag-attr
0520        if  doc-status not = 0
0530            exit perform
0540        end-if
0550        display "Attribute name : " root-tag-attr-name
0560        display "Attribute value: " root-tag-attr-val
0570     end-perform

Loops through information in the root tag, reading each attribute for the root tag and displaying the attribute names and values.

Line 0600:

0600     start doc key sub-tag

Sets the starting point in the buffer to the first nested tag (non-root tag).

Lines 0610 - 0810:

0610     perform until exit
0620        read doc
0630          next key sub-tag *> index is 1 is default
0640        if  doc-status not = 0
0650            exit perform
0660        end-if
0670        display " Sub tag name: " sub-tag-name
0680        display " Sub tag value:" sub-tag-val
0690
0700        start doc key sub-tag-attr index is 1
0710        perform until exit
0720            read doc next key sub-tag-attr
0730            if  doc-status not = 0
0740                exit perform
0750            end-if
0760            display " Sub tag attribute name : "
0770              sub-tag-attr-name
0780            display " Sub tag attribute value: "
0790              sub-tag-attr-val
0800        end-perform
0810    end-perform

Loops through all non-root tags, displaying each XML tag name and value, and all its attribute names and values.

Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - IDENTIFIED BY Clause
Related information
COUNT IN Clause


PROCESSING-INSTRUCTION Clause

The PROCESSING-INSTRUCTION clause is provided simply to allow XML processing instructions to be embedded directly within the data associated with a tag. For example, the following code:

    01  my-tag    identified by "my_tag".
        05  my-tag-data1    pic x(80).
        05  my-tag-pi       pic x(80)
            IS PROCESSING-INSTRUCTION.
        05  my-tag-data2    pic x(80).
    ...
        move 'data' to my-tag-data1 my-tag-data2
        move 'somepi' to my-tag-pi
        write my-tag

Would yield:

    <my_tag>data<?somepi?>data</my_tag>
Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - PROCESSING-INSTRUCTION Clause


COUNT IN Clause

As shown in the section IDENTIFIED BY and IS ATTRIBUTE Clauses, it is possible to deal with unlimited multiple occurrences of known or unknown tag names through the use of various XML-extended verbs. In less complicated cases where the number of occurrences is known in advance, there are very simple syntax extensions that allow direct addressing.

You can deal with a known number of tag or attribute occurrences using the OCCURS and COUNT IN clauses. The number of acceptable occurrences of a tag or attribute is limited by the OCCURS clause. The COUNT IN clause enables you to determine the number of occurrences received or to specify the number to be sent.

The following example shows how to use the COUNT IN clause:

Using OCCURS and COUNT IN clauses

0010  $set preprocess(prexml) warn endp
0020  $set sourceformat(free) case
0030
0040  select library-file
0050        assign address of mybuf
0060        organization  is xml
0070        document-type is "library.xsd"
0080        file status is library-status.
0090
0100  data division.
0110
0120  xd library-file.
0130  01  library            identified by "library".
0140    05  book             identified by "book"
0150                           occurs 10 times
0160                           count in library-book-count.
0170        10  book-title  pic x(80) identified by "title".
0180        10  book-author pic x(80) identified by "author".
0190        10  book-toc              identified by "toc".
0200            15  book-toc-section  occurs 20 times
0210                              count in book-section-count
0220                              identified by "section"
0230                              pic x(20).
0240
0250  working-storage section.
0260  01  library-status  pic s999.
0270  01  mybuf.
0280      10  pic x(150) value
0290     '<library>'
0300     & '<book><title>book1</title>'
0310     &'       <toc><section>b1section1</section>'
0320     & '           <section>b1section2</section>'
0330     & '</toc></book>'.
0340      10 pic x(150) value
0350       '<book><title>book2</title>'
0360     & '      <toc><section>b2section1</section>'
0370     & '           <section>b2section2</section>'
0380     & '</toc></book>'
0390     & '</library>'.
0400
0410  open input library-file
0420  read library-file
0430  perform until library-book-count = 0
0440    display
0450     "Book title = '" book-title(library-book-count) "'"
0460    display "Number of Sects = "
0470     book-section-count(library-book-count)
0480     subtract 1 from library-book-count
0490  end-perform
0500  close library-file
0510  stop run.

Lines 0040 - 0080:

0040  select library-file
0050        assign address of mybuf
0060        organization  is xml
0070        document-type is "library.xsd"
0080        file status is library-status.

Assigns a filename and the buffer mybuf as the source of the XML input, specifies the organization of the file (XML) and provides a filename for the XML schema (library.xsd) and a data-name for the file status.

Lines 0120 - 0230:

0120  xd library-file.
0130  01  library            identified by "library".
0140    05  book             identified by "book"
0150                           occurs 10 times
0160                           count in library-book-count.
0170        10  book-title  pic x(80) identified by "title".
0180        10  book-author pic x(80) identified by "author".
0190        10  book-toc              identified by "toc".
0200            15  book-toc-section  occurs 20 times
0210                              count in book-section-count
0220                              identified by "section"
0230                              pic x(20).

Sets up the record structure of the buffer area. Notice the use of OCCURS and COUNT-IN. In this example, the book data-name is identified by the XML tag <book>, it occurs 10 times, and the occurrences are counted in the library-book-count field, which is defined implicitly. The book-toc-section data item is defined similarly, with book-section-count defined implicitly.

Lines 0270 - 0390:

0270  01  mybuf.
0280      10  pic x(150) value
0290     '<library>'
0300     & '<book><title>book1</title>'
0310     &'       <toc><section>b1section1</section>'
0320     & '           <section>b1section2</section>'
0330     & '</toc></book>'.
0340      10 pic x(150) value
0350       '<book><title>book2</title>'
0360     & '      <toc><section>b2section1</section>'
0370     & '           <section>b2section2</section>'
0380     & '</toc></book>'
0390     & '</library>'.

Codes the XML stream to be read in a static buffer. While this example has the XML stream coded directly into the program, you could also place the XML into the buffer (mybuf) using any standard input.

Lines 0430 - 0490:

0430  perform until library-book-count = 0
0440    display
0450     "Book title = '" book-title(library-book-count) "'"
0460    display "Number of Sects = "
0470     book-section-count(library-book-count)
0480     subtract 1 from library-book-count
0490  end-perform

Loops through all records, displaying all book titles and the number of sections contained in each. Notice that book-section-count uses library-book-count as an index.

The COUNT IN clause is also very useful to determine if the tag associated with an element definition was present in the XML stream. A very common use of this is determining which of a set of XD records is read during the execution of a READ statement. For example:

Using COUNT IN to determine which record has been read

0010  select book-or-author-file
0020        assign address of mybuf
0030        organization  is xml
0040        document-type is "bookdb.xsd"
0050        file status is xml-bookdb-status.
0060
0070  data division.
0080  xd book-or-author-file.
0090  01  book-rec        identified by "book"
0100                      count in book-count.
0110      05  price-val   pic 999.99 identified by "price"
0120                       is attribute
0130                       count in price-count.
0140      05  title-val   pic x(80) identified by "title".
0150
0160  01  author-rec      identified by "author"
0170                       count in author-count.
0180      05  author-val  pic x(80).
0190
0200  working-storage section.
0210  01  xml-bookdb-status  pic s999.
0220  01  mybuf  pic x(256) value
0230     '<book price="123.00"><title>A title</title></book>'.
0240
0250  procedure division.
0260     open input book-or-author-file
0270     read book-or-author-file
0280     evaluate true
0290     when book-count = 1
0300         if  price-count not = 0
0310             display "got <book price=" price-val ">
0320               <title>" title-val "</title></book>"
0330         else
0340             display "got <book><title>" title-val
0350               "</title></book>"
0360         end-if
0370     when author-count = 1
0380         display "got <author>" author-val "</author>"
0390     end-evaluate
0400     close book-or-author-file
0410     stop run.

Lines 0010 - 0050:

0010  select book-or-author-file
0020        assign address of mybuf
0030        organization  is xml
0040        document-type is "bookdb.xsd"
0050        file status is xml-bookdb-status.

Assigns a filename and the buffer mybuf as the source of the XML input, specifies the organization of the file (XML) and provides a filename for the XML schema (bookdb.xsd) and a data-name for the file status.

Lines 0080 - 0180:

0080  xd book-or-author-file.
0090  01  book-rec        identified by "book"
0100                      count in book-count.
0110      05  price-val   pic 999.99 identified by "price"
0120                       is attribute
0130                       count in price-count.
0140      05  title-val   pic x(80) identified by "title".
0150
0160  01  author-rec      identified by "author"
0170                       count in author-count.
0180      05  author-val  pic x(80).

Defines two 01 level items, one for a book record, and one for an author record. Later, the program uses the information defined by COUNT IN to determine which record is being read.

Lines 0220 - 0230:

0220  01  mybuf  pic x(256) value
0230     '<book price="123.00"><title>A title</title></book>'.

Codes the XML stream to be read in a static buffer. While this example has the XML stream coded directly into the program, you could also place the XML into the buffer (mybuf) using any standard input.

Lines 0260 - 0390:

0260     open input book-or-author-file
0270     read book-or-author-file
0280     evaluate true
0290     when book-count = 1
0300         if  price-count not = 0
0310             display "got <book price=" price-val ">
0320               <title>" title-val "</title></book>"
0330         else
0340             display "got <book><title>" title-val
0350               "</title></book>"
0360         end-if
0370     when author-count = 1
0380         display "got <author>" author-val "</author>"
0390     end-evaluate

The EVALUATE clause determines which record is being read based on the value of book-count or author-count.

Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - COUNT IN Clause
Related information
IDENTIFIED BY and IS ATTRIBUTE Clauses


NAMESPACE Clause

XML documents often contain namespaces. The NAMESPACE clause enables you to set or identify those namespaces in your COBOL. Specify the NAMESPACE clause in a data description entry. The following example shows how to use the NAMESPACE clause:

Using NAMESPACE

0010  xd book-file.
0020  78  book-ns value "http://xml.microfocus.com/book.xsd".
0030  01  book                identified by "book"
0040                          namespace is book-ns.
0050      05  publisher pic x(80)
0060              identified by "name"
0070              namespace is
0080              "http://xml.microfocus.com/publisher.xsd".
0090
0100      05  author identified by "name"
0110                 namespace is
0120                 "http://xml.microfocus.com/author.xsd".
0130          10  author-first identified by "firstname"
0140                           pic x(80).
0150          10  author-last  identified by "lastname"
0160                           pic x(80).
0170      05  title            identified by "title"
0180                           pic x(80).

Line 0020:

0020  78  book-ns value "http://xml.microfocus.com/book.xsd".

Defines a namespace and its value.

Lines 0030 - 0040:

0030  01  book                identified by "book"
0040                          namespace is book-ns.

Defines a data record with a namespace equivalent to the value in book-ns.

Lines 0050 - 0080:

0050      05  publisher pic x(80)
0060              identified by "name"
0070              namespace is
0080              "http://xml.microfocus.com/publisher.xsd".

Sets a namespace to a fixed URI (Uniform Resource Identifier), which is a specific point of contact on the World Wide Web - in this case an XML schema file.

Lines 0100 - 0120:

0100      05  author identified by "name"
0110                 namespace is
0120                 "http://xml.microfocus.com/author.xsd".

Sets a namespace to a fixed URI.

Lines 0130 - 0160:

0130          10  author-first identified by "firstname"
0140                           pic x(80).
0150          10  author-last  identified by "lastname"
0160                           pic x(80).

Because these data items are in the author group, they take on the same namespace as author.

Lines 0170 - 0180:

0170      05  title            identified by "title"
0180                           pic x(80).

Title inherits the same namespace as book because it is in the book group but does not specify a namespace.

On input, both tags and namespaces must match those in the XML stream. On output, XML tags are qualified by the indicated namespace. The code in the example Using Namespace would yield an XML stream similar to:

<?xml version="1.0" encoding="utf-8" ?>
<book xmlns="http://xml.microfocus.com/book.xsd">
   <name xmlns="http://xml.microfocus.com/publisher.xsd">
      Just a publisher
   </name>
   <name xmlns="http://xml.microfocus.com/author.xsd">
      <firstname>AuthorFirstname</firstname>
      <lastname>AuthorFirstname</lastname>
   </name>
   <title>
      This is the title
   </title>
</book>

You can replace a specific NAMESPACE value with a data-name. This facilitates dynamic discovery of a namespace in XML. In this case, namespace matching is not performed on input. Instead, the namespace of the matching tag is populated into the data item specified by NAMESPACE. On output, the value of the namespace referenced by the data-name is used to qualify the output tag. The following record:

     xd generic-file.
     01  generic-tag identified by generic-tag-name
                     namespace is generic-tag-namespace.
         05  generic-tag-name           pic x(80).
         05  generic-tag-namespace      pic x(80).
         05  generic-tag-value          pic x(80).

and XML stream input:

   <name xmlns="http://xml.microfocus.com/publisher.xsd">
      Just a publisher
   </name>

yields the value of "name" for generic-tag-name, the value of "http://xml.microfocus.com/publisher.xsd" for generic-tag-namespace and the value of "Just a publisher" for generic-tag-value.

Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - NAMESPACE clause


COBOL Verbs

The following familiar COBOL verbs have also been extended to handle XML:
  • START statement
  • OPEN statement
  • READ statement
  • WRITE statement
  • REWRITE statement
  • DELETE statement
  • CLOSE statement
Parent topic: Syntax for Handling XML in COBOL
Related reference
XML Syntax - CLOSE Statement
XML Syntax - DELETE Statement
XML Syntax - OPEN Statement
XML Syntax - READ Statement
XML Syntax - REWRITE Statement
XML Syntax - START Statement
XML Syntax - WRITE Statement


Compiling XML-enabled COBOL

To compile or build COBOL that has been XML-enabled using XML syntax extensions, the code must be preprocessed by the XML preprocessor in your COBOL development system. This is a necessary step that enables the Compiler to recognize the XML syntax you've coded into your program.

There are two ways you can compile or build XML-enabled COBOL.

  • Building XML-enabled COBOL from Visual COBOL
    This requires that you put additional code into your program that specifies use of the XML preprocessor.
  • Compiling XML-enabled COBOL from the Command Line
    This requires that you use command-line arguments that invoke the XML preprocessor before compiling the COBOL.
Parent topic: XML Syntax Extensions


Building XML-enabled COBOL from Visual COBOL

Before you build your XML-enabled COBOL, you must insert the following code on the first line of your program before the Identification Division:

$set {preprocess | p}(prexml) [{out | o} (outname)] [warn] [outenc (input)]
     [{preprocess | p} (ppname)] endp

where the parameters are:

{preprocess | p}
The pre-processor to be used.
{out | o} outname
The fully preprocessed output source file, outname. This output source file contains native COBOL processed from the XML syntax.
warn
Cause diagnostic warnings on parsing to be presented by PREXML.
outenc(input)
The encoding of the output text is the same as the input encoding specified in the XML declaration.
ppname
The preprocessor name you want to use to read source files and process COPY statements. Preprocessors can be nested.

For example:

$set p(prexml) warn endp
Parent topic: Compiling XML-enabled COBOL


Compiling XML-enabled COBOL from the Command Line

If you have the $set statement coded into your program, then you compile from the command line just as you would a program that is not XML enabled. However, if you do not have the $set statement coded into your program, or you would like to override all of the parameters specified in your $set statement, specify a command line as follows:

cob programname.cbl -C "{preprocess | p}(prexml)
        [{out | o} (outname)]
        [warn]
                             [outenc (input)]
        [{preprocess | p} (ppname)]
        endp"

where programname is the file prefix of the COBOL program you are compiling, and the other parameters are the same as those used with the $set statement.

For example:

cob foo.cbl -C "p(prexml) warn endp"
Parent topic: Compiling XML-enabled COBOL


Generating COBOL Structures with XML Syntax from the Command Line

  • CBL2XML Utility
  • Generating a Copybook and Schema
  • Generating XML-enhanced COBOL from an XML Schema
  • Mapping COBOL Data to XML Elements
  • Accessing an XML-enabled Record
  • Validate an XML Document
Parent topic: Using COBOL and XML together
Related information
XML Syntax Extensions


CBL2XML Utility

You can use the cbl2xml utility to:

  • Generate COBOL records with XML syntax and a corresponding XML schema from an existing COBOL record
  • Generate COBOL records with XML syntax based on an existing XML schema
  • Validate XML schemas and instance documents

cbl2xml runs at a command prompt, reads a COBOL record, and generates several files. Use the following command-line syntax:

cbl2xml filename
        [-c cpyBook]
        [-x schemaFile]
        [-m mapFile]
        [-p prefix]
        [-d directiveFile]
        [-v validationFile]
        [-noprompt]
        [-nocountin]

Where the parameters are:

filename The input file for cbl2xml.
  • When converting traditional COBOL data structures to COBOL with XML syntax, this is the filename of a COBOL file being read by cbl2xml. It can be a program with the file extension .cbl, or a copybook with the file extension .cpy.
  • When converting an XML schema to COBOL with XML syntax, this is the filename of an XML schema file being read by cbl2xml. Schema files usually have an .xsd file extension.
cpyBook | The filename of a COBOL copybook (.cpy file). cbl2xml generates this file to contain COBOL with XML syntax extensions. If you do not specify this parameter, cbl2xml names the generated file using the name of the COBOL or copybook with -cbl2xml appended to it. For example, if you specify a COBOL program file named account.cbl, the default filename for the copybook containing XML syntax extensions created by cbl2xml is account-cbl2xml.cpy.
schemaFile | The filename of a schema file to be created. If you do not specify this parameter, cbl2xml names the schema file the same as the COBOL file, but with an .xsd extension. For example, if you specify a COBOL program file named account.cbl, the default filename for the schema created by cbl2xml is account.xsd.
mapFile The filename of a map file to be created, or the name of an existing map file. The following rules apply:
  • If the map file you specify does not exist, cbl2xml creates a map file based on the information in the specified COBOL file.
  • If the map file you specify does exist, cbl2xml first asks if you want to overwrite it. If you anwer no, it applies the information in the map file to the generated COBOL file. If you answer yes, cbl2xml generates a new map file overwriting the previous contents of that file.

For more information on map files, see the section Mapping COBOL Data to XML Elements.

prefix Specify a prefix to prepend to generated data names. Use this parameter to create data records that are structured the same as the data records in your COBOL file, but that have different data names. This is useful when you want to keep the original data records intact and supply alternative data names for XML use.

The prefix takes the form of a character string. For example, if you specify -p xml-, cbl2xml prepends xml- to the beginning of each data name it generates.

directiveFile If you normally use a Compiler directive file to compile the COBOL program or copybook you are XML-enabling, specify that directive file each time you use cbl2xml.

For more information on directive files, see the topic Compiler Directives.

validationFile The filename of an XML schema or instance document you want to validate. The following rules apply:
  • If you specify a schema, cbl2xml validates that schema based on W3C XML conventions specified at http://www.w3.org/2001/XMLSchema, that is, it validates that the schema itself is a valid schema.
  • If you specify an XML instance document, cbl2xml validates that document against the XML schema specified in the document.
-noprompt Specify this argument when you want cbl2xml to overwrite existing files automatically.
CAUTION:
-noprompt overwrites all files generated by cbl2xml, including map files you have edited, and schema files supplied by third parties. Do not use this parameter unless you are sure you want to overwrite these.
-nocountin | Specify this argument to prevent the generation of COUNT IN clauses for generated COBOL data items. This option overrides any values specified in a CBL2XML mapping file.
Parent topic: Generating COBOL Structures with XML Syntax from the Command Line
Related information
Mapping COBOL Data to XML Elements


Generating a Copybook and Schema

You can generate a copybook with XML syntax extensions and an XML schema from an existing copybook or COBOL program. You can use the generated copybook to XML-enable your COBOL program. You can use the generated schema to create an XML document that conforms to the schema and contains data, and use that document as input to your COBOL. Use the following command-line format for cbl2xml to generate the copybook and the schema:

cbl2xml filename
        [-c cobolFile]
        [-x schemaFile]
        [-d directiveFile]
        [-nocountin]

To enable your COBOL program to access XML information that conforms to the schema generated, cbl2xml generates a new record in a separate copybook. This new record contains the XML syntax extensions necessary for XML operation. The following example assumes that you have not specified the -c or -x parameters:

Generated copybook with XML syntax extensions

cbl2xml takes the following copybook record contained in the file record.cpy:

01 A-FILE-RECORD.
   05 A-FILE-ITEM PIC XX.

and generates the following XML-enhanced copybook, filename record-cbl2xml.cpy:

01 a-file-record identified by "a-file-record"
   count in a-file-record-count.
   02 a-file-item pic X(2) identified by "a-file-item"
      count in a-file-item-count.

For detailed information on XML syntax extensions, see the topic XML Syntax Extensions.

To XML-enable your program, you need to either rename record-cbl2xml.cpy to record.cpy, or replace the original record in record.cpy with the record in record-cbl2xml.cpy.

The process of XML-enabling an entire COBOL program is the same as that of XML-enabling a copybook. In this case, cbl2xml generates a schema and program that contain equivalent information for each record found in the program.

The schema produced by running cbl2xml on record.cpy, record.xsd, is as follows:

Generated XML schema from a COBOL file definition

<schema xmlns="http://www.w3.org/2001/XMLSchema"
   elementFormDefault="qualified">
   <element name="a-file-record">
      <complexType>
         <sequence>
            <element name="a-file-item">
               <simpleType>
                  <restriction base="string">
                     <length value="2"/>
                  </restriction>
               </simpleType>
            </element>
         </sequence>
      </complexType>
   </element>
</schema>

The following table explains the purpose of each schema tag in the context of the record it represents:

Schema Tag Description
<element name="a-file-record">
 This defines the group-level data name A-FILE-RECORD. It serves as the parent element to all elements that define data items contained in the group.
<complexType>
 This indicates that the group record has one or more subordinate data items.
<sequence>
 This indicates the beginning of the sequence of tags that defines the subordinate record.
<element name="a-file-item">
 This defines the data name of the subordinate data item A-FILE-ITEM. We know it is subordinate because this element tag is a child to a parent element tag.
<simpleType>
 This indicates that the data item has no subordinate data items.
<restriction base="string">
 This defines any restrictions on the data. In this case, the data must be a string, as indicated by the PIC XX clause in the COBOL data record.
<length value="2"/>
 This defines the length of the record, which in this case is 2, as defined by the PIC XX in the COBOL data record.
Parent topic: Generating COBOL Structures with XML Syntax from the Command Line
Related information
XML Syntax Extensions


Generating XML-enhanced COBOL from an XML Schema

The schema produced by cbl2xml using the format described in Generating a Copybook and Schema conforms to your existing COBOL record, and contains element names derived from your COBOL record. In practical application, a schema of this sort is limited because to exchange XML information with another party, you must use element names recognized by the other party. For example, many industries publish industry-standard schemas, which contain a specific set of elements used to exchange information throughout the industry. To generate COBOL records that contain XML syntax extensions that conform to a third-party schema, use the following cbl2xml format:

cbl2xml XMLschema
                 [-c cobolFile]
                 [-d directiveFile]
                 [-prompt | -noprompt]

In this example, we use a fictional industry-standard schema named widgets.xsd. This schema enables companies to exchange ordering information for the Widget product. The contents of widgets.xsd is as follows:

Industry-standard XML schema for "widgets"

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 elementFormDefault="qualified">
    <xsd:element name="Availability" type="xsd:string"/>
    <xsd:element name="Base_Price" type="xsd:string"/>
    <xsd:element name="Base_Price_And_Unit">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="Base_Price"/>
                <xsd:element ref="Unit"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="Catalogue_Id" type="xsd:int"/>
    <xsd:element name="widgets">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="Product_Id" minOccurs="0"/>
                <xsd:element ref="Company_Id"/>
                <xsd:element ref="Catalogue_Id"/>
                <xsd:element ref="SKU"/>
                <xsd:element ref="Product_Series" minOccurs="0"/>
                <xsd:element ref="Availability"/>
                <xsd:element ref="Sale"/>
                <xsd:element ref="Base_Price_And_Unit"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="Company_Id" type="xsd:int"/>
    <xsd:element name="Product_Id" type="xsd:int"/>
    <xsd:element name="Product_Series" type="xsd:string"/>
    <xsd:element name="SKU" type="xsd:string"/>
    <xsd:element name="Sale" type="xsd:string"/>
    <xsd:element name="Unit" type="xsd:string"/>
</xsd:schema>

cbl2xml reads this schema and generates a copybook, widgets.cpy, as follows:

XML-enabled COBOL generated from widgets.cpy

       01 Widgets identified by "Widgets".
        02 Product-Id PIC X(80) identified by "Product_Id"
           count in Product-Id-count.
        02 Company-Id PIC X(80) identified by "Company_Id"
           count in Company-Id-count.
        02 Catalogue-Id PIC X(80) identified by "Catalogue_Id"
           count in Catalogue-Id-count.
        02 SKU PIC X(80) identified by "SKU" count in SKU-count.
        02 Product-Series PIC X(80)
            identified by "Product_Series"
            count in Product-Series-count.
        02 Availability PIC X(80) identified by "Availability"
           count in Availability-count.
        02 Sale PIC X(80) identified by "Sale"
           count in Sale-count.
        02 Base-Price-And-Unit
           identified by "Base_Price_And_Unit"
           count in Base-Price-And-Unit-count.
         03 Base-Price PIC X(80)
            identified by "Base_Price"
            count in Base-Price-count.
         03 Unit PIC X(80)

            identified by "Unit"
            count in Unit-count.

You can then include this copybook in a COBOL program you want to use to send and receive information about widgets.

Parent topic: Generating COBOL Structures with XML Syntax from the Command Line
Related information
Mapping COBOL Data to XML Elements


Mapping COBOL Data to XML Elements

The example shown in the topic Generating XML-enhanced COBOL from an XML Schema generates COBOL data records based on the element names found in the schema. However, you might have an existing COBOL record you want to use specifically to communicate with a third-party schema. To do this, you must create a direct relationship between a COBOL record and the elements of the schema by means of a map file.

Use this format to generate a map file that you can customize.

cbl2xml filename -m mapFile

The process of XML-enabling an application to exchange information with XML documents based on an existing COBOL record and an existing schema is as follows:

  1. Generate a map file using cbl2xml. To produce a new map file, specify a map filename that does not exist. When cbl2xml does not find an existing map file with the name you specify, it generates a new file.
  2. Edit the map file, changing the names of generated elements to element names that exist in the schema you want to use for data exchange.
  3. Rerun cbl2xml using the same format you used in step 1 of this process. However, this time specify the existing, edited map file. When cbl2xml does find a map file of the name you specified, it applies the mappings in the file to the COBOL record.

The remainder of this section explains the details of this process.

If the mapfile you specify does not exist, cbl2xml takes data structures from the COBOL file, translates them into XML, and writes that information into the map file.

For example:

COBOL record and XML schema communication

Product_info.cpy contains the following record:

       01  PRODUCT-INFO.
           05 PROD-ID     PIC 9(6).
           05 COMPANY-ID  PIC 9(4).
           05 CATALOG-NUM PIC 9(8).
           05 SKU-REF     PIC X(10).

The following is the element definition from widget.xsd with which you want to communicate:

    <xsd:element name="Widgets">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="Product_Id" minOccurs="0"/>
                <xsd:element ref="Company_Id"/>
                <xsd:element ref="Catalogue_Id"/>
                <xsd:element ref="SKU"/>
                <xsd:element ref="Product_Series" minOccurs="0"/>
                <xsd:element ref="Availability"/>
                <xsd:element ref="Sale"/>
                <xsd:element ref="Base_Price_And_Unit"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

Cbl2xml generates the following map file from product_info.cpy:

Generated map file

<xml-cobol-mapping-file
   xmlns="http://xml.microfocus.com/schema/xml/v1.0/mfxmlmap.xsd"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation=
    "http://xml.microfocus.com/schema/xml/v1.0/mfxmlmap.xsd
    mfxmlmap.xsd">
   <xml-cobol-mapping>
      <cobol-name>product-info</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>product-info</xml-name>
      <xml-type>group</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.prod-id</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>prod-id</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.company-id</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>company-id</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.catalog-num</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>catalog-num</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.sku-ref</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>sku-ref</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
</xml-cobol-mapping-file>

The map file is an XML document. The tags generated by cbl2xml contain specific information about the COBOL record as follows:

Map file tag name | Meaning
<xml-cobol-mapping-file> | Indicates that this is a mapping file to be used to create XML structure in a COBOL program. It is the root element of the map file.
<xml-cobol-mapping> | Contains information for one COBOL data item. It is the parent element to <cobol-name>, <xml-name>, <xml-type>, <xml-attribute>, and <xml-namespace>.
<cobol-name> | Contains the name of a data item from a COBOL record, including the parent name of the data item. The parent name comes first, followed by the data item name, separated by a period (.). For example: a-file-record.a-file-item.
<cobol-count-in> | Specifies whether or not the COBOL XML COUNT IN clause is generated for the COBOL item in <cobol-name>. Acceptable values are “true” and “false”. The default value is “true.” This value is ignored when the –nocountin command-line option is used.
<xml-name> | Specifies an equivalent XML element name to be used to correspond to the record named in <cobol-name>.
<xml-type> | The XML simple type that the COBOL item is being mapped to. This parameter is applicable only when a COBOL data item has a PIC clause.
<xml-attribute> | Specifies whether or not the element specified in <xml-name> is to be treated as an attribute in the XML schema. Values are “true” or “false.”
<xml-namespace> | An optional element that specifies the XML namespace for the element specified in <xml-name>. A namespace specified at a group level is inherited automatically by child elements.

You can then create user-defined mappings by editing the map file and matching the XML element names found in the schema to the COBOL names found in your COBOL record. To do this, change the <xml-name>s in the map file to match the element names in the schema. In this example, you would edit the <xml-name>s in the map file shown in example Generated Map File as follows:

Change... | To...
<xml-name>product-info</xml-name> | <xml-name>Widgets</xml-name>
<xml-name>prod-id</xml-name> | <xml-name>Product_Id</xml-name>
<xml-name>company-id</xml-name> | <xml-name>Company_Id</xml-name>
<xml-name>catalog-num</xml-name> | <xml-name>Catalogue_Id</xml-name>
<xml-name>sku-ref</xml-name> | <xml-name>SKU</xml-name>

At this point, run cbl2xml again, specifying the edited map file, and cbl2xml produces a schema and a copybook. The schema will be similar to your existing schema, depending on how much of that existing schema you edited into your map file. You do not need to use this schema; it is created by default and is not critical. The copybook contains your original COBOL record with the appropriate XML syntax extensions appended to it, based on the information found in the map file. In this example, cbl2xml generates the following copybook:

        01 product-info identified by "Widgets"
           count in widgets-count.
         02 prod-id pic 9(6) identified by "Product_Id"
            count in Product_Id-count.
         02 company-id pic 9(4) identified by "Company_Id"
            count in Company_Id-count.
         02 catalog-num pic 9(8) identified by "Catalogue_Id"
            count in Catalogue_Id-count.
         02 sku-ref pic X(10) identified by "SKU"
            count in SKU-count.

Paste this new record into your COBOL program, replacing the original record. Your COBOL record is now XML-enabled to communicate with XML documents that conform to the widgets.xsd schema.

Parent topic: Generating COBOL Structures with XML Syntax from the Command Line
Related information
Generating XML-enhanced COBOL from an XML Schema
CBL2XML Utility


Accessing an XML-enabled Record

Once you have an XML-enabled record, you'll need to access it from the Procedure Division of your program. You can use existing COBOL verbs to do this and the XML-enhanced syntax for these verbs. See the topic XML Syntax Extensions for more information.

The following is a sample program with a Procedure Division that writes the contents of the widgets.xml file:

Sample COBOL program using XML

        $set p(prexml) endp
        select xml-stream assign "widgets.xml"
                          organization is xml
                          document-type is "widgets.xsd"
                          file status is file-status-spec.

        xd xml-stream.
           copy "widgets.cpy".

        data division.
        working-storage section.
        01 file-status-spec PIC S9(9).

        procedure division.
          open output xml-stream
          write widgets
          display file-status-spec
          close xml-stream
        stop run.
Parent topic: Generating COBOL Structures with XML Syntax from the Command Line
Related information
XML Syntax Extensions


Validate an XML Document

You can use cbl2xml to validate an XML schema (.xsd file) or instance document (.xml file) to determine if it is well formed. In the case of an instance document, cbl2xml checks the contents of the document against the schema referenced by the document. Use the following syntax:

cbl2xml -v filename

where filename is a schema file or an XML instance document file.

Parent topic: Generating COBOL Structures with XML Syntax from the Command Line


XML PARSE

The XML PARSE statement provides a mechanism for processing XML. The statement causes XML document data to be split into component fragments by the system's XML parser, and to be made available to a user-defined routine. Each fragment is labeled with a tag or "event" to indicate the nature of the fragment.

  • Special Registers
  • User Routine
Parent topic: Using COBOL and XML together
Related reference
The XML PARSE Statement


Special Registers

Communication between the parser and the user routine is handled through these special registers:

  • XML-CODE to determine the status of the XML parsing.
  • XML-EVENT to receive the name of each XML event; for example, START-OF-DOCUMENT.
  • XML-INFORMATION to provide additional information to an XML PARSE processing procedure about the status of the parse.
  • XML-NAMESPACE is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION.
  • XML-NAMESPACE-PREFIX is defined during XML parsing to contain the prefix, if any, of the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier.
  • XML-NNAMESPACE is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION.
  • XML-NNAMESPACE-PREFIX is defined during XML parsing to contain the prefix, if any, of the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier.
  • XML-NTEXT to receive XML document fragments from a national document.
  • XML-TEXT to receive XML document fragments from an alphanumeric document.
Parent topic: XML PARSE
Related information
Special Registers


User Routine

You need to include a user routine in your program. This routine typically contains an EVALUATE statement that handles the XML-EVENT values. The parser continually provides fragment information to the user routine until the entire document has been processed or until a fatal error is encountered. If malformed XML is encountered by the parser, an error code is placed into the special register XML-CODE, and control is transferred to an imperative statement. For non-fatal errors however, the user routine has the option of resetting XML-CODE to zero and and thus continuing execution. It also has the option of setting XML-CODE to -1 for a normal event. This causes the parser to terminate, but without generating an exception event.

Parent topic: XML PARSE


Glossary of terms

The following terms are used in an XML and COBOL context.

Array
A COBOL table, that is, a data item described with the OCCURS clause.
Caching

Caching is a means of increasing performance by keeping loaded XSLT stylesheets, templates, and schema documents in memory for reuse without the need to reload them. If the application dynamically generates new copies of such documents, caching may be permanently or selectively disabled by the application. Caching is enabled by default at the beginning of an application.

COBOL data structure

A COBOL data structure is a COBOL data item. In general, it is a group data item, but in some cases, it may be a single elementary data item. The Visual COBOL compiler's XMLGEN directive generates a file containing an XML representation of a COBOL data structure. This map can be used move data in either direction at runtime. Extensible Stylesheet Language Transformations (XSLT) of the XML data representation can be used to match XML element names to COBOL data-names in cases where the names differ.

Document Type Definition (DTD)

The document type definition occurs between the XML header and the first element of an XML document. It optionally declares the document structure and entities. Declared entities may be referenced in the document.

DOM

Acronym for Document Object Model. XML documents are parsed and stored in the DOM for processing.

External XSLT stylesheet

An XSLT stylesheet that is provided by the user and referenced as a parameter in the XML EXPORT FILE/TEXT, XML IMPORT FILE/TEXT, or XML TRANSFORM FILE/TEXT statements. See also XSLT stylesheet.

HTML

An acronym for Hypertext Markup Language. A text description language related to SGML; it mixes text format markup with plain text content to describe formatted text. HTML is ubiquitous as the source language for Web pages on the Internet. Starting with HTML 4.0, the Unicode Standard functions as the reference character set for HTML content. See also SGML, XHTML, and XML.

iconv

A character conversion library available on some UNIX systems for converting between UNICODE characters and local characters. When an iconv library is available, the MF_XMLEXT_LOCAL_ENCODING environment variable may specify the name of a conversion supported by that iconv library and the xmlif library will use that conversion. Otherwise, the only conversions supported are "rmlatin1" and "rmlatin9".

Model files

XML document files created by the XMLGEN compiler directive. The model file is usually named the same as the COBOL program source file but with an extension of .xml.

Schema valid XML document

An XML document that conforms to a particular XML schema.

SGML

An acronym for Standardized Generalized Markup Language. A standard framework, defined in ISO 8879, for defining particular text markup languages. The SGML framework allows for mixing structural tags that describe format with the plain text content of documents, so that fancy text can be fully described in a plain text stream of data. See also HTML, and XML.

Structured document

The term "structured document" describes the concept that a document can contain content, such as words, numbers, pictures, and so forth., as well as information describing the role of content elements and substructures. Adding "structure" to documents facilitates searching, sorting, or any one of a variety of operations to be performed on an electronic document. The benefits of adding structure to electronic documents include portability, re-usability, inter-system operability, ease-of-storage and retrieval, longevity, quick access, and low distribution costs. XML is a set of rules for structuring a document using hierarchical markup. See also XML.

Stylesheet
See XSLT stylesheet.
UNC

An acronym for Universal Naming Convention. UNC is a filename format that is used to specify the location of files, folders, and resources on a local area network (LAN). For example, a UNC address may look something like this:

\\server-name\directory\filename

UNC also can be used to identify peripheral devices shared on the network, including scanners and printers. It provides each shared resource with a unique address, which allows operating systems that support UNC (such as Windows) to access specific resources quickly and efficiently.

Unicode

Unicode was developed to support the worldwide interchange, processing, and display of diverse languages and technical disciplines of the world. Unicode is a character coding system that assigns a unique number to each character in each of the world's principal written languages. There exist several alternatives for how a sequence of such characters or their respective integer values can be represented as a sequence of bytes. The two most obvious encodings store Unicode text as either 2- or 4-byte sequences. The official terms for these encodings are UCS-2 and UCS-4, respectively. The current version of the Unicode Standard, developed by the Unicode Consortium, is v4.0.0. For an alternative encoding of Unicode, see also UTF-8.

URL

An acronym for Universal Resource Locator, which is a unique identifier (address) of a specific resource, or file, that is available on the World Wide Web (WWW) and other Internet resources. The URL contains the protocol (the method of access) to be used to access the file resource (for example, http:// for World Wide Web pages, ftp:// for file transfers, mailto:// for e-mail, and so forth), the domain name that identifies a specific host computer on the Internet for the file, and the path that specifies the location of the file on that computer.

A URL is a type of URI (Uniform Resource Identifier, formerly called Universal Resource Identifier).

For XML Extensions purposes, a filename specification is considered to be a URL if it begins with http://, https://, or file://.

UTF-8

UTF stands for Unicode Transformation Format. UTF-8 is an encoding scheme (that is, a method of mapping the Unicode code points to a digital representation), which is commonly used under UNIX-style operating systems and in XML documents. Unicode is defined in ISO 10646-1:2000 Annex D and is also described in RFC 2279, as well as section 3.8 of the Unicode 3.0 standard. It is a variable length encoding scheme from 1 to 6 bytes per character. See also Unicode.

Valid XML document

See Schema valid XML document.

Well-formed XML document

A well-formed XML document is one that conforms to the syntax requirements of XML. A well-formed XML document may or may not be a valid document with respect to a particular XML schema.

XHTML

An acronym for Extensible HyperText Markup Language. When HTML 4.0 is expressed as XML, it is called XHTML. See also HTML.

XML

An acronym for Extensible Markup Language. A subset of SGML constituting a particular text markup language for interchange of structured data. The Unicode Standard is the reference character set for XML content. See also Unicode.

XML Instance document
XML instance documents (.xml files) are built using the elements declared in a schema, and also contain data. You use XML syntax extensions to read from and write to XML instance documents.
XML schema
An XML schema (usually an .xsd file) is made up in part of element definitions. These definitions dictate the structure and content of an XML instance document that references the schema. XML elements can have attributes associated with them. These attributes further describe the data contained in the element.
XSL

An acronym for Extensible Stylesheet Language. A W3C standard defining XSLT stylesheets for (and in) XML. See also XSLT and W3C.

XSLT

An acronym for Extensible Stylesheet Language for Transformations. XSLT is the "Transformations" part of the Extensible Stylesheet Language (XSL). A W3C standard, it is used to transform XML documents to other formats, including HTML, other forms of XML, and plain text. This powerful stylesheet language allows for more complex processing of the XML document's data. See also XSL and W3C.

XSLT stylesheet

An XML document that is written in the Extensible Stylesheet Language for Transformations. Note that XSLT stylesheets should not be confused with Cascading Stylesheets (CSS), which are a simple method for adding style, such as fonts, color, and spacing, to a document for final output to a browser; cascading stylesheets are closely related to HTML and XHTML.

W3C

An acronym for World Wide Web Consortium. The main standards body for the World-Wide Web (WWW). W3C works with the global community to establish international standards for client and server protocols that enable online commence and communications on the Internet.

Parent topic: Using COBOL and XML together


64-bit Native COBOL Programming

Restriction: The following information applies to native COBOL only.

For information about managed COBOL applications running on a 64-bit platform, see 64-Bit Applications in the .NET Environment.

As 64-bit architecture is becoming increasingly prevalent, the consideration of moving towards producing 64-bit applications is also increasing. Many of the major operating system vendors now default to 64-bit support, and whilst still supporting the running of 32-bit applications, have signalled intent to stop supporting the building of 32-bit applications on future platforms. In fact, certain platforms (for example, SUSE SLES 12, service pack 2) are only supported in 64-bit by Micro Focus products.

Visual COBOL makes it easy for you to take advantage of the benefits that 64-bit programming offers. The IDE and command line tools both enable you to compile your source code to target both a 64-bit and a 32-bit run-time environment, and Enterprise Server provides both a 32-bit and 64-bit execution environment.

Existing 32-bit applications (applications compiled with the 32-bit Compiler) can still run in a 64-bit run-time environment, but they will not be taking advantage of the benefits of 64-bit programming. When you compile a native COBOL program with the 64-bit Compiler, its elements are addressed using 64-bit pointers, which enables you to point to virtual address ranges in memory that are greater than 4GB in size (a limit of 32-bit pointers). The increased range can result in significantly improved processing times for certain types of programs (for example, computational programs). 64-bit programs are only designed to run in 64-bit run-time environments.

If you intend to transition your existing code to a 64-bit environment, Visual COBOL contains a number of features that help make it easier, such as prototyping of library routines..

There are other considerations when preparing to move your applications to a 64-bit environment, such as the compatibility of third-party applications, plugins, hardware, etc.... You will almost certainly need to ensure that a 64-bit driver is used to interact with that software or hardware; for example, if connecting to a database or printer, you will now need a 64-bit driver in order to interact. This consideration is not just limited to Visual COBOL, but when moving to a 64-bit environment as a whole.

  • Compiling Native COBOL Programs for 64-bit
  • Transitioning Native COBOL Programs to 64-bit
  • Single Sourcing and Compiling Native COBOL Programs for 64-Bit
Parent topic: COBOL Programming
Related information
Using the Library Routine Type Definitions and Call Prototypes


Compiling Native COBOL Programs for 64-bit

Restriction: The following information applies to native COBOL only.

You can use the IDE or the command line tools to compile programs for a 64-bit environment.

You can also compile from the command line by using the 64-bit Command Line Tool that is supplied with your product. You use the same compilation syntax as you would to produce 32-bit output; see Compiling from the Command Line (Windows) for more information.

Parent topic: 64-bit Native COBOL Programming
Related information
Transitioning Native COBOL Programs to 64-bit


Transitioning Native COBOL Programs to 64-bit

Restriction: The following information applies to native COBOL only.

In general, you can take programs that ran in a 32-bit environment, and recompile them to run in a 64-bit environment; they should run without any problems as 64-bit applications.

However, there are certain circumstances that may require additional development to create a 64-bit-compatible program:

  • Programs Using Pointers
  • Programs with a Directly Coded File Control Description
Parent topic: 64-bit Native COBOL Programming
Related information
Compiling Native COBOL Programs for 64-bit


Programs Using Pointers

If your program uses pointers, you need to ensure that they are not redefined or modified by reference. There should also be no assumptions in your record definitions about the sizes of pointers, as the pointer size increases from 4 bytes to 8 bytes in a 64-bit environment.

To mitigate against potential problems, that usually only become apparent at run time, you should consider using call prototyping for multi-program applications. It ensures that each CALL statement is checked for correctness at compile time, and will flag situations such as when a called program is expecting a pointer of one size (for example, a 64-bit, 8-byte pointer) but is receiving the wrong sized pointer (a 32-bit, 4-byte pointer); see About Call Prototypes for more information about how to convert your existing programs to use this functionality.

Tip: If you use any of the Micro Focus library routines, use the cbltypes.cpy and cblproto.cpy copy files supplied with your system to easily implement call prototyping for these calls.

To help you find invalid manipulations of the data-type POINTER in your programs, use the 64 bit readiness rule set of the code analysis tools; this can be run from the IDE or the command line.

You also need to be careful about making assumptions about the length of groups, especially when using them with information passed to and from a Micro Focus library routine. Some fields within groups can differ in size between 32-bit and 64-bit; for example, CBL_GET_PROGRAM_INFO contains the parameter block cblt-prog-info-params, which contains a length field (cblte-gpi-size) that differs in size based on 32- and 64-bit compilation. When using such groups, use the conditional compilation technique (discussed in Single Sourcing), or use the length of syntax.

If you are also using pointers with the RETURN-CODE special register, you must ensure that the size of the return code matches the size of the pointer if you place the pointer into the special register. You can do this by using the RTNCODE-SIZE Compiler directive: set it to RTNCODE-SIZE"8" for your 64-bit programs, as the default is RTNCODE-SIZE"4".

Parent topic: Transitioning Native COBOL Programs to 64-bit
Related reference
About Call Prototypes


Programs with a Directly Coded File Control Description

If your program directly calls the File Handler API (also referred to as the Callable File Handler), then you would have had to directly code an FCD block. If the program codes an FCD block using the FCD2 format (or relies on the xfhfcd2.cpy copybook), it will need to be modified to use the 64-bit FCD3 format instead (as defined in the xfhfcd3.cpy copybook); see File Control Description (FCD) for full details of the required format.

Tip: To modify your programs for dual FCD support, making them compatible with 32- and 64-bit run-time environments, see Single Sourcing and Dual FCD Support in 64-Bit Native COBOL Programs.
Parent topic: Transitioning Native COBOL Programs to 64-bit
Related reference
File Control Description (FCD)
Single Sourcing and Dual FCD Support in Native COBOL Programs


Single Sourcing and Compiling Native COBOL Programs for 64-Bit

Restriction: The following information applies to native COBOL only.

When using the appropriate command line tools or IDE settings to compile to 64-bit, this is effectively setting a Compiler directive (P64) to indicate that the Compiler compiles your program for 64-bit. You are discouraged from setting this directive directly within your code, but you can use it in the following technique in order to create source code that can easily be compiled to 32- and 64-bit with minimal to no code changes.

The following conditional compilation construction can be used to compile code based on the presence of the P64 directive. See the $IF Statement in the Language Reference Manual for more details.

      $if P64 set
      *> perform 64-bit specific code
      $else
      *> perform 32-bit specific code
      $end.

Conditional compilation techniques can also be used to create dual FCD programs, making the same source code compatible for environments where different FCD versions are required.

  • Single Sourcing and Dual FCD Support in Native COBOL Programs
Parent topic: 64-bit Native COBOL Programming
Related reference
Conditional Compilation
IF Statement


Single Sourcing and Dual FCD Support in Native COBOL Programs

Restriction: The following information applies to native COBOL only.

All system components supplied with the 32-bit development system support the File Control Description formats FCD2 and FCD3. System components supplied with the 64-bit development system only support FCD3; they do not support FCD2 due to the incompatibilities in pointer size.

The system components that are supplied with your development system are single sourced, which means that they are compatible with FCD3 on 64-bit systems when compiling for 64-bit, or work with both FCD2 and FCD3 on 32-bit systems when compiling for 32-bit.

If your applications cannot solely use either FCD3 or FCD2, then we recommend that you take this single-sourcing approach in your applications. If you can only use one FCD format, you need make no further provisions to handle the extended FCD structure.

However, some programs in your application might provide interfaces to other components in your application, which might include FCD structures. In these cases, you might need to provide gradual transition to full FCD3 support; at run time, therefore, your program will need to accept both FCD2 and FCD3 formats, and to distinguish them as necessary.

For example, if there are few references to FCD fields within your code, the following source code model might be suitable:

       linkage section.
       01  fcd-user  pic x.
       01  fcd2.
           copy "xfhfcd2".
       01  fcd3.
           copy "xfhfcd3".
       procedure division using fcd-user.
       set address of fcd3  to address of fcd-user
       if  fcd-version of fcd3 = 0
         *> Code to deal with FCD2...
      $if P64 set
       display "Error: cannot accept FCD2 on 64 bit platform"
       goback
      $end
         set address of fcd2  to address of fcd-user
       end-if

Every time a field of the FCD is referenced you must add code that does something like the following:

       if  ( fcd-version of fcd3 not = 0
          and fcd--line-sequential of fcd3)
       or  ( not fcd-version of fcd3 = 0
       and fcd--line-sequential of fcd2 )
        *> Do line sequential manipulation
       end-if

If, however, the bulk of the code in your component directly references the FCD structure, you could internally use only the FCD3 structure and, if necessary, establish mappings, to and from FCD2 at entry and exit gateways to the component. For example:

       working-storage section.
       78  78-fcd3-map-to-fcd3         value 0.
       78  78-fcd3-map-from-fcd3       value 1.
       78  78-fcd3-map-error-none      value 0.
       78  78-fcd3-map-error-64bit     value -1.
       78  78-fcd3-map-error-func      value -2.
       78  78-fcd3-map-error-reladdr   value -3.
       01  fcd3-work.
       copy "xfhfcd3".
       linkage section.
       01  fcd-user            pic x.
       procedure division using fcd-user.
      *> Entry Gate map FCD2 (if necessary) to FCD3
       call 'fcd3map' using fcd-user fcd3-work
                      by value 78-fcd3-map-to-fcd3 size 1
       if  return-code not = 0
        display "Error: cannot convert FCD formats"
        goback
       end-if

      *> Operate on the FCD as FCD3 only
      *> ....
      *> Exit Gate map FCD3 (if necessary) to FCD2
       call 'fcd3map' using fcd-user fcd3-work
                      by value 78-fcd3-map-from-fcd3 size 1
     goback.
Parent topic: Single Sourcing and Compiling Native COBOL Programs for 64-Bit


Embedded HTML

Embedded HTML (EHTML) enables you to output HTML directly from a COBOL CGI program.

Using EHTML, you can output HTML statements, complete or partial HTML pages, or a combination of both, without including any special data declarations. This provides tremendous flexibility in that it enables you to customize the HTML output generated by your programs.

To achieve customized HTML output, you embed HTML statements or references to one or more copybooks that contain HTML into a COBOL program using the EXEC HTML statement. This is translated by the EHTML preprocessor, htmlpp, which outputs your HTML statements directly to the Web server that initiated your COBOL CGI program.

You can also pass variable data from your COBOL program directly into the HTML output by coding substitution markers into your embedded HTML.

  • Enabling CGI support
    You need to enable CGI support to generate applications that use Embedded HTML.
  • EXEC HTML statement
    Enables you to embed HTML into a COBOL CGI program for output to a Web browser via the EHTML preprocessor.
  • Substitution Markers
    Substitution markers enable you to pass variable data from your COBOL program directly into HTML output by coding specifications into your embedded HTML markup.
  • EHTML Preprocessor
    EHTML is an integrated preprocessor provided with this system and designed to work closely with the Micro Focus COBOL Compiler. It identifies HTML embedded in COBOL code as delineated by EXEC HTML statements, and outputs the HTML to your Web server.
  • EHTML Preprocessor Directives
  • Deploying a CGI Application with Embedded HTML
    This topic describes the requirements for deploying a CGI application that uses Embedded HTML.
  • Debugging a CGI Application
    You can debug a CGI applications using the Just-In-Time Debugger with an embedded call to CBL_DEBUGBREAK, or using the .
Parent topic: COBOL Programming


Enabling CGI support

You need to enable CGI support to generate applications that use Embedded HTML.

To use Embedded HTML, you must have the following in place:

  • Project Specifications
  • Server Specifications

    If using Apache 2.4, configure the server with the following specifications:

    • Enable mod_cgi
      LoadModule cgi_module modules/mod_cgi.so
    • Enable mod_env
      LoadModule env_module modules/mod_env.so
    • Specify a /cgi-bin script alias. For example:
      <IfModule alias_module>
 ScriptAlias /cgi-bin/ "${SRVROOT}/cgi-bin/"
</IfModule>
    • Enable ExecCGI for the directory that contains your cgi executable. For example:
      <Directory "${SRVROOT}/cgi-bin">
    AllowOverride None
    Options None
    Require all granted
</Directory>
    • Micro Focus Licensing Specifications
      If you are using a version of the COBOL run time earlier than the one supplied with the latest Visual COBOL, you must set the MFCES_INIT_LOCATION environment variable to point to your ces.ini file. For example:
      SetEnv MFCES_INIT_LOCATION "c:\programdata\micro focus\ces.ini"
Parent topic: Embedded HTML


EXEC HTML statement

Enables you to embed HTML into a COBOL CGI program for output to a Web browser via the EHTML preprocessor.

General Format

EXEC HTML
  [htmloutput]
  [copy "file.htm"]
END-EXEC

Parameters

htmloutput
HTML statements (markup) for output to a Web browser.
file.htm
A file containing HTML markup.

Comments

EXEC and HTML must be on the same line.

Do not specify EXEC HTML in a copybook that is used by a COPY ... REPLACING statement. Similarly, do not place an EXEC HTML statement in the scope of a REPLACE statement. Using EXEC HTML statements in either of these ways results in unexpected behavior and syntax errors.

The EHTML preprocessor does not validate or parse your HTML markup - it just outputs it directly to the Web server that started the CGI program.

With fixed format COBOL source code, the EHTML preprocessor treats column 8 as a virtual column 1 when outputting embedded HTML. This simplifies use of the HTML <PRE> tag. However, if you include a copybook with an extension of .htm, the preprocessor treats the copybook as free format source. You can override this behavior with the preprocessor directive, NOAUTOFORMAT.

Optionally, you can output variable data from your COBOL program by coding substitution markers into your embedded HTML markup.

Parent topic: Embedded HTML
Related reference
AUTOFORMAT (AF)
Related information
Substitution Markers
EHTML Preprocessor


Substitution Markers

Substitution markers enable you to pass variable data from your COBOL program directly into HTML output by coding specifications into your embedded HTML markup.

Format 1, unqualified substitution marker

:cobol-data-name

Format 2, qualified substitution marker

:group-data-name.elementary-data-name

Parameters

cobol-data-name
Any data name defined to the COBOL program.
group-data-name
The name of a group-level qualifer for the elementary-data-name.
elementary-data-name
A data name defined to the COBOL program and qualified by the group-data-name.

Syntax Rules

  1. A colon followed by a space is treated as a colon, not as the beginning of a substitution marker.
  2. A colon preceded by a backslash (\) character is treated as a colon, not as a substitution marker.
  3. A :data-name reference is not treated as a substitution marker if it is preceded by any of the following:
    • data
    • clsid
    • layout
    • javascript
    • about
    • http
    • https
    • file
    • ftp
    • mailto
    • news
    • gopher
  4. A :data-name reference is not treated as a substitution marker if it is preceded by any of the following style sheet attributes supported by Internet Explorer 4.0 and above:
    !important | border-top-style | margin-bottom
    @font-face | border-top-width | margin-left
    @import | border-width | margin-right
    active | clear | margin-top
    background | clip | overflow
    background-attachment | color | padding
    background-color | cursor | padding-bottom
    background-image | display | padding-left
    background-position | filter | padding-right
    background-repeat | float | padding-top
    border | font | page-break-after
    border-bottom | font-family | page-break-before
    border-bottom-color | font-size | position
    border-bottom-style | font-style | text-align
    border-bottom-width | font-variant | text-decoration
    border-color | font-weight | text-indent
    border-left | height | text-transform
    border-left-color | hover | top
    border-left-style | left | vertical-align
    border-left-width | letter-spacing | visibility
    border-right | line-height | visited
    border-right-color | link | white-space
    border-right-style | list-style | width
    border-right-width | list-style-image | word-spacing
    border-style | list-style-position | z-index
    border-top | list-style-type
    border-top-color | margin

General Rules

  1. Use display items inside EHTML; if you use binary data items the data displayed on the form is not human-readable.
  2. Reference modification on substitution markers is allowed. See Example 3.

Example 1, Unqualified substitution marker

 working-storage section.
 01 acct-code    pic 9(8).
 ...
 procedure division.
 ...
*> First colon is followed by a space, so it is
*> not treated as a substitution marker by
*> EXEC HTML. Second colon is followed by a
*> data-name, so it is treated as a
*> substitution marker. The third colon is preceded
*> by a backslash, so it is treated as a colon
     EXEC HTML
         Account Code: :acct-code <BR>
         \:acct-code
     END-EXEC

Example 2, Qualified substitution marker

 working-storage section.
 01 customer.
   03 name         pic x(80).
   03 acct-code    pic 9(8).
 ...
 procedure division.
 ...
*> customer.acct-code equivalent inside EXEC HTML
*> block to acct-code of customer in COBOL source.
     EXEC HTML
         Account Code: :customer.acct-code <BR>
     END-EXEC

Example 3, Substitution marker with reference modification

 working-storage section.
 01 acct-code    pic 9(8).
 ...
 procedure division.
 ...
*> Reference modification outputs first four characters of
*> acct-code.
     EXEC HTML
         Account Code: :acct-code(1:4) <BR>
     END-EXEC
Parent topic: Embedded HTML
Related information
EXEC HTML statement
EHTML Preprocessor


EHTML Preprocessor

EHTML is an integrated preprocessor provided with this system and designed to work closely with the Micro Focus COBOL Compiler. It identifies HTML embedded in COBOL code as delineated by EXEC HTML statements, and outputs the HTML to your Web server.

To run the EHTML preprocessor, set the PREPROCESS Compiler directive to htmlpp using one of the following methods:
  • Code a $SET statement before the first line in your COBOL program file using the following syntax :
    $SET preprocess(htmlpp) [EHTML-directive(s)] endp
  • On the command line as part of your compile syntax:
    preprocess(htmlpp) [EHTML-directive(s)] endp
  • In the htmlpp.dir file, located in ???; must be in your path statement.
    preprocess(htmlpp) [EHTML-directive(s)] endp

Where EHTML-directive(s) is one or more EHTML preprocessor directives. See EHTML Preprocessor Directives for more information.

Parent topic: Embedded HTML
Related reference
EHTML Preprocessor Directives
Related information
EXEC HTML statement
Substitution Markers


EHTML Preprocessor Directives

  • AUTOFORMAT (AF)
    For fixed-format COBOL source programs (the default unless you use compiler directive SOURCEFORMAT(FREE)), AUTOFORMAT changes the margins from 8-71 to 1-250 for any copybook included inside an EXEC HTML block. This preserves any HTML formatting created with the <PRE> tag.
  • CONFIRM
    Causes the preprocessor to echo directives.
  • DEBUG (D)
    Causes the preprocessor to write extra information to the file specified by DEBUGFILE or OUT.
  • DEBUGFILE
    Causes the preprocessor to output a file source.deb where source is the name of your source file. This file contains the expanded source code produced by the preprocessor.
  • OUT
    Causes the preprocessor to output a file containing the expanded source code produced by the preprocessor.
  • PREPROCESS (P)
    Calls a nested preprocessor to read the source file and process COPY statements.
  • STEPEXEC
    Causes the Debugger to output an entire EXEC HTML...END-EXEC block as a single step.
  • STEPHTML
    Causes the Debugger to output each separate line of HTML in a separate Debugger step.
  • TRACE
    Causes the preprocessor to output a file source.trc where source is the name of your source file.
  • WARN
    Causes the preprocessor to output warnings for any errors it finds, either to the .lst file if one is being produced or to the screen.
Parent topic: Embedded HTML
Related information
EHTML Preprocessor


AUTOFORMAT (AF)

For fixed-format COBOL source programs (the default unless you use compiler directive SOURCEFORMAT(FREE)), AUTOFORMAT changes the margins from 8-71 to 1-250 for any copybook included inside an EXEC HTML block. This preserves any HTML formatting created with the <PRE> tag.

Syntax:

>>-.---.-.----.-AUTOFORMAT-.--.----------><
   +-/-+ |    +-AF---------+  |
         |                    |
         +-NO-.-AUTOFORMAT-.--+
              +-AF---------+

Parameters:

None

Properties:

Default: | AUTOFORMAT
Phase: | Syntax check
$SET: | Initial
Parent topic: EHTML Preprocessor Directives
Related information
EXEC HTML statement


CONFIRM

Causes the preprocessor to echo directives.

Syntax:

>>-.---.-.----.--CONFIRM-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCONFIRM
Phase: | Syntax check
$SET: | Initial
Parent topic: EHTML Preprocessor Directives


DEBUG (D)

Causes the preprocessor to write extra information to the file specified by DEBUGFILE or OUT.

Syntax:

>>-.---.-.----.---.--DEBUG-.-------------><
   +-/-+ +-NO-+   +--D-----+

Parameters:

None

Properties:

Default: | NODEBUG
Phase: | Syntax check
$SET: | Initial

Dependencies:

If DEBUGFILE is specified, writes the extra information to the file source.deb, where source is the name of your source file.

If OUT is specified, writes the extra information to the file specified as a parameter to OUT.

If neither DEBUGFILE nor OUT is specified, writes the expanded source code with extra debug information to the file debug.lst.

Parent topic: EHTML Preprocessor Directives


DEBUGFILE

Causes the preprocessor to output a file source.deb where source is the name of your source file. This file contains the expanded source code produced by the preprocessor.

Syntax:

>>-.---.-.----.--DEBUGFILE---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NODEBUGFILE
Phase: | Syntax check
$SET: | Initial

Comments:

This file output by this directive is for use in debugging preprocessor problems.

Parent topic: EHTML Preprocessor Directives


OUT

Causes the preprocessor to output a file containing the expanded source code produced by the preprocessor.

Syntax:

>>-.---.--OUT--"fname"-------------------><
   +-/-+

Parameters:

fname Name of the file to contain the expanded source.

Properties:

Default: | None
Phase: | Syntax check
$SET: | Initial

Dependencies:

NODEBUGFILE turns off the OUT directive if it has been specified previously.

Comments:

This file output by this directive is for use in debugging preprocessor problems.

Parent topic: EHTML Preprocessor Directives


PREPROCESS (P)

Calls a nested preprocessor to read the source file and process COPY statements.

Syntax:

>>-.---.-----.-PREPROCESS-.--"pname"-----><
   +-/-+     +-P----------+

Parameters:

pname Name of preprocessor

Properties:

Default: | None
Phase: | Syntax check
$SET: | Initial
Parent topic: EHTML Preprocessor Directives


STEPEXEC

Causes the Debugger to output an entire EXEC HTML...END-EXEC block as a single step.

Syntax:

>>-.---.--STEPEXEC-----------------------><
   +-/-+

Parameters:

None

Properties:

Default: | None
Phase: | Syntax check
$SET: | Initial

Comments:

STEPEXEC is a synonym for NOSTEPHTML.

Parent topic: EHTML Preprocessor Directives


STEPHTML

Causes the Debugger to output each separate line of HTML in a separate Debugger step.

Syntax:

>>-.---.-.----.--STEPHTML----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSTEPHTML
Phase: | Syntax check
$SET: | Initial
Parent topic: EHTML Preprocessor Directives


TRACE

Causes the preprocessor to output a file source.trc where source is the name of your source file.

Syntax:

>>-.---.-.----.--TRACE-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOTRACE
Phase: | Syntax check
$SET: | Initial

Comments:

The file created contains a trace of information passed between the preprocessor and the COBOL compiler, for use in debugging preprocessor problems.

Parent topic: EHTML Preprocessor Directives


WARN

Causes the preprocessor to output warnings for any errors it finds, either to the .lst file if one is being produced or to the screen.

Syntax:

>>-.---.-.----.-WARN---.----.------------><
   +-/-+ |    +-W------+    |
         |                  |
         +-NO-.-WARN---.----+
              +-W------+

Parameters:

None

Properties:

Default: | NOWARN
Phase: | Syntax check
$SET: | Initial
Parent topic: EHTML Preprocessor Directives


Deploying a CGI Application with Embedded HTML

This topic describes the requirements for deploying a CGI application that uses Embedded HTML.

You can deploy your built executable manually or by specifying a post-build event that copies the executable to your Web server. The following is an example post-build event:

copy $(TargetDir)\*.* c:\Apache2.2\cgi-bin

Parent topic: Embedded HTML


Debugging a CGI Application

You can debug a CGI applications using the Just-In-Time Debugger with an embedded call to CBL_DEBUGBREAK, or using the .

Tip: If the Debugger fails to find the symbols for your program, you can add the path to the CGI symbols to your symbol path.
Parent topic: Embedded HTML
Related reference
CBL_DEBUGBREAK


Compatibility

  • Compatibility with ACUCOBOL-GT
  • Compatibility with DG Interactive COBOL
  • Compatibility with RM/COBOL
  • OO COBOL Class Library Reference
Parent topic: Programming


Compatibility with ACUCOBOL-GT

The following sections describe supported ACUCOBOL-GT features and how to enable them.

  • Converting ACUCOBOL-GT Applications
    With Visual COBOL you can build, compile and debug ACUCOBOL-GT applications. Certain Compiler directives are provided to enable compatibility with some of ACUCOBOL-GT's language extensions, data files, and other behaviors.
  • ACUCOBOL-GT File Handling
    Visual COBOL allows you to continue to use your existing ACUCOBOL-GT data files, including Vision indexed data files.
  • ACUCOBOL-GT Library Routines
    This COBOL development system provides a number of ACUCOBOL-GT library routines in native and managed code.
  • ACUCOBOL-GT Windowing Syntax
    Your COBOL system provides some support for ACUCOBOL-GT windowing syntax that enables you to draw lines and boxes on the terminal screen, and create virtual terminal windows on a physical terminal. All ACCEPT and DISPLAY statements then act within the current window (except for ACCEPT format 1, 2, or 3 statements, DISPLAY format 1 statements, and DISPLAY WINDOW/LINE/BOX statements). The syntax also enables underlying displays to be kept and restored.
Parent topic: Compatibility


Converting ACUCOBOL-GT Applications

With Visual COBOL you can build, compile and debug ACUCOBOL-GT applications. Certain Compiler directives are provided to enable compatibility with some of ACUCOBOL-GT's language extensions, data files, and other behaviors.

After you have converted your application, you must run, license, and distribute your programs in the same manner as other Micro Focus programs. There is currently no clone of the ACUCOBOL-GT runtime known as .

This section describes the ACUCOBOL-GT compatibility features, such as how they are enabled within Visual COBOL, and also the potential problems you may encounter with some aspects of the converted source code.

  • Enabling ACUCOBOL-GT Compatibility
    Compile your ACUCOBOL-GT source code with certain Compiler directives that enable support for ACUCOBOL-GT syntax, data types, and other behaviors. A number of traditional ACUCOBOL-GT compiler options are also available.
  • ACUCOBOL-GT Conversion Issues
    Information on issues you might encounter when running ACUCOBOL-GT source programs in this COBOL system.
Parent topic: Compatibility with ACUCOBOL-GT


Enabling ACUCOBOL-GT Compatibility

Compile your ACUCOBOL-GT source code with certain Compiler directives that enable support for ACUCOBOL-GT syntax, data types, and other behaviors. A number of traditional ACUCOBOL-GT compiler options are also available.
  • Compiler Directives for ACUCOBOL-GT Compatibility
    There are a number of Compiler directives that provide compatibility with ACUCOBOL-GT. Use the DIALECT"ACU" directive to set all of these directives at once.
  • Compiler Option Support
    You can use many of the traditional ACUCOBOL-GT compiler options with the Micro Focus compiler by using the ACUOPT Compiler directive or command line options.
Parent topic: Converting ACUCOBOL-GT Applications


Compiler Directives for ACUCOBOL-GT Compatibility

There are a number of Compiler directives that provide compatibility with ACUCOBOL-GT. Use the DIALECT"ACU" directive to set all of these directives at once.

By setting DIALECT"ACU" you enable certain reserved words, data type storage behavior, and more. See ACU DIALECT setting for full details of the directives that are set.

You can set this directive in your source code directly, through the COBOL project options interface in your IDE or from the command line.

Parent topic: Enabling ACUCOBOL-GT Compatibility
Related reference
ACU DIALECT setting
Related information
Setting Directives Outside the IDE


Compiler Option Support

You can use many of the ACUCOBOL-GT compiler options when compiling, by setting then with the ACUOPT Compiler directive. A list of the supported options is listed in this section.

Alternatively, you can compile using a clone of the ACUCOBOL-GT compiler known as ccbl. This executable is located in the bin directory found here: $COBDIR. ccbl compiles to .int code unless you specify one of the ccbl's native code options, in which case it produces .gnt code.

  • Setting Compiler Options
    You can set the ACUCOBOL-GT compiler options by using the ACUOPT Compiler directive, or from a command line utility.
  • Supported ACUCOBOL-GT Compiler Options
    There are a number of ACUCOBOL-GT Compiler options supported in Visual COBOL, which you enable using the ACUOPT Compiler directive.
  • 32- and 64-Bit Code Generation
    When compiling with the DIALECT"ACU" directive, the Compiler generates intermediate code that is bit independent. By using ccbl, you can specify 32 or 64-bit intermediate code.
Parent topic: Enabling ACUCOBOL-GT Compatibility


Setting Compiler Options

You can set the ACUCOBOL-GT compiler options by using the ACUOPT Compiler directive, or from a command line utility.

This COBOL system supports many of the compiler options available with the ACUCOBOL-GT (Acu) compiler. To specify these options use the ACUOPT Compiler directive along with the traditional ACU compiler option name.

For example:

ACUOPT(-option)

Or:

ACUOPT(--option)

ACUOPT automatically sets the ACU directive, which turns on overall ACUCOBOL-GT compatibility.

NOACU or NOACUOPT are not allowed.

Alternatively, you can compile using a clone of the ACUCOBOL-GT compiler known as ccbl. This executable is located in the bin directory found here: $COBDIR. ccbl compiles to .int code unless you specify one of the ccbl's native code options, in which case it produces .gnt code.

Parent topic: Compiler Option Support
Related reference
ACUOPT
Related information
Supported ACUCOBOL-GT Compiler Options


Supported ACUCOBOL-GT Compiler Options

There are a number of ACUCOBOL-GT Compiler options supported in Visual COBOL, which you enable using the ACUOPT Compiler directive.

General Support Notes

Visual COBOL supports the following ACUCOBOL-GT compiler functionality:

  • Grouping of options
  • CBLFLAGS environment variable
  • Replacement of @ by the base name of the source file.

The following compiler options are available:

  • Standard Options
  • Native Object Code Options
  • Listing Options
  • Internal Table Options
  • Compatibility Options
  • Source Options
  • Reserved Word Options
  • Data Storage Options
  • Truncation Options
  • Video Options
  • Warning and Error Options
  • Debugging Options
  • Miscellaneous Options
Parent topic: Compiler Option Support
Related concepts
Setting Compiler Options
Related reference
ACUOPT


Standard Options

The standard options enable you to control certain compile time options, such as verbose output and renaming the object file.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-e | This option must be followed by a file name (as the next separate argument). When specified, this option causes the error listing to be written to the specified file instead of the screen. This file is removed if no errors are found.
-o | This option must be followed by a file name (as the next separate argument), which becomes the name of the object file instead of source-name.acu. This file is removed if the compiler detects errors in the source.
-v

This option has multiple applications:

  • If it is the first and only option on the command line, then the compiler runs in "Version" mode. Using -v, you can display version information, the copyright notice, and other information.

  • Otherwise, if it is used in combination with other options, it causes the compiler to be verbose about its progress.

Because -v is the lead-in sequence for the video options, this option should be specified by itself.

-w | This option causes warning messages to be suppressed (a warning condition is never a fatal compilation error). Suppressing warning messages can be helpful when you are converting programs from another COBOL dialect that uses slightly different syntaxes.
-x | This causes the CBLFLAGS environment variable to be ignored.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Native Object Code Options

The native object code option enables you to execute object files that contain native instructions for select families of processors.

The following compiler option is supported in Visual COBOL when using ccbl32 and ccbl64 from the command line.

Option | Definition
-n | The Compiler produces native code specific to the bit arrangement and local machine. There is no support for cross-generation of native code.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Listing Options

The listing options enable you to control listing information generated with an object file.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Note: The results of these options will differ from how they appear in ACUCOBOL-GT COBOL, as they map to listing Compiler directives in Visual COBOL.
Option | Definition
-La | This option maps to the ERRLIST Compiler directive.
-Lc | This option maps to the XREF and RESEQ Compiler directives.
-Lf | This option maps to the COPYLIST Compiler directive.
-Li | This option maps to the ERRLIST Compiler directive.
-Ll | This option maps to the FORM Compiler directive.
-Lo | This option maps to the LIST Compiler directive.
-Ls | This option maps to the DATAMAP Compiler directive.
-Lw | This option maps to the LISTWIDTH Compiler directive.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Internal Table Options

The Internal Table options available in ACUCOBOL-GT are not required in Visual COBOL. The following options are accepted by the compiler, but are ignored.

Option | Definition
-Td | Identifier and statement table — sets the maximum number of items in each statement. The default value is 4096.
-Te | Subscript statement table — sets the maximum size for OCCURS statements. The default value is 256.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Compatibility Options

The compatibility options enable you to control the compatibility with certain other COBOL systems.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Ca | This option causes simple ACCEPT and DISPLAY statements to be treated in accordance with ANSI semantics. Specifying this option is the same as specifying FROM CONSOLE for all simple ACCEPT statements and UPON CONSOLE for all simple DISPLAY statements. You can control this behavior for individual ACCEPT or DISPLAY statements by specifying an explicit FROM/UPON phrase.
-Ci | This option sets the compiler to be compatible with ICOBOL for certain COBOL constructs.
-Cr | This option sets the compiler to RM/COBOL compatibility mode.
-Cv | This option sets the compiler to IBM DOS/VS compatibility mode.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Source Options

The source options enable you to modify the way that the Compiler treats the physical source files.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Sa | This causes the compiler to assume that the input source is in the standard ANSI source format.
-Sd | Setting this option causes debugging lines marked with D in the indicator area to be treated as normal source lines instead of comment lines. This is equivalent to supplying the phrase WITH DEBUGGING MODE in the SOURCE-COMPUTER paragraph.
-Sp | With this option you can specify a series of directories to be searched when the compiler is looking for COPY libraries. This option is followed (as the next separate argument) by the set of directories to search.
-St | This option forces the compiler to use the terminal source format.
-S1..-S9 | Specifying a digit with -S uses alternate tab stops in source files. When this option is used, tabs will be set every # columns apart, where # is the number specified. For example, -S4 will set tab stops at every fourth column. Tab stops always start in column 1.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Reserved Word Options

The reserved word options enable you to override the behavior of reserved words and synonyms.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Rc Allows you to change a reserved word. This option must be followed by two separate arguments: The first is the reserved word you want to change. The second is the word that you want to use instead. For example,
-Rc TITLE NAME

will allow you to use "TITLE" as a user-defined word and will cause the word NAME to be treated as the reserved word TITLE. You may not specify a word that is already reserved as the new reserved word. This option may be repeated to transform multiple reserved words.

-Rn Allows you to make a reserved word a synonym for another reserved word. This option must be followed by two separate arguments: The first is the reserved word for which you want a synonym. The second is the word that functions as the synonym. For example,
-Rn COMP COMP-5
causes COMP-5 to be treated the same as the reserved word COMP. This option may be repeated to make multiple synonyms.
-Rw | This option allows you to suppress a particular reserved word. The option must be followed (as the next separate argument) by the reserved word you want to suppress. This option may be repeated to suppress multiple reserved words. This option also allows you to suppress some non-reserved words, such as control names (for example, entry-field and label) or property names (for example, max-text and bitmap-number).
Parent topic: Supported ACUCOBOL-GT Compiler Options


Data Storage Options

The data storage options control the behavior of certain data items and how they are stored.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-D1 | This option causes any data item whose underlying type is binary to be stored in one byte if that data item has only one or two digits. Normally, such a data item would be stored in two bytes.
-D2 | This option causes COMPUTATIONAL data items to be treated as if they were declared as COMPUTATIONAL-2. This is the default when you are using RM/COBOL compatibility mode.
-D5 | This option causes data items declared as BINARY to be treated as if they were declared as COMPUTATIONAL-5. This causes the values to be stored in the host machine's native byte-ordering instead of the machine-independent byte-ordering normally used. This option should be used with caution, because it can lead to programs that are not portable.
-D6 | This option causes unsigned data items declared as PACKED-DECIMAL to be treated as if they were declared as COMPUTATIONAL-6. This saves one-half of a byte because the compiler will not generate any storage for the sign.
-D7 This option allows you to match one of the binary storage conventions used by Micro Focus COBOL. That convention is identical to the ACUCOBOL-GT -Dm convention, except that a PIC 9(7) data item (unsigned) is stored in 3 bytes instead of 4 and a PIC 9(12) data item (unsigned) is stored in 5 bytes instead of 6. When you use this option, the size of a binary item is determined as follows (the value in the table is the number of bytes occupied by the data item):
Number of          Signed             Unsigned
9's in PIC         Storage            Storage
1 - 2              1                  1
3 - 4              2                  2
5 - 6              3                  3
7                  4                  3
8 - 9              4                  4
10 - 11            5                  5
12                 6                  5
13 - 14            6                  6
15 - 16            7                  7
17 - 18            8                  8
-Da | This allows you to specify the data alignment modulus for level 01 and level 77 data items. Normally, level 01 and level 77 data items are aligned on a 4-byte boundary (modulus 4). This is optimal for 32-bit architectures. You can specify an alternate alignment boundary by following this option with the desired modulus. This should be specified as a single digit that immediately follows the -Da as part of the same argument. For example, -Da8 specifies that data should be aligned on 8-byte boundaries, which can provide improved performance on a 64-bit machine.
-Db | This causes COMPUTATIONAL data items to be treated as if they were declared as BINARY data items. This is the default when you are using VAX COBOL compatibility mode.
-DCa | This selects the ACUCOBOL-GT storage convention. It is the default setting. This convention is also compatible with data produced by RM/COBOL (not RM/COBOL-85) and previous versions of ACUCOBOL-GT. It also produces slightly faster code.
-DCb This selects the MBP COBOL sign storage convention.Note that the MBP COBOL sign storage convention for USAGE DISPLAY directly conflicts with that used by IBM COBOL and some other COBOLs. As a result, signed USAGE DISPLAY items in the MBP format are correctly understood only when the program is compiled with -Dcb. This is unlike the other sign conventions in which the runtime can usually extract the correct value even when a mismatched sign convention is specified at compile time.

Also note that MBP COBOL does not have the COMP-2 storage type. The convention that ACUCOBOL-GT implements (Positive: X"0C"; Negative: X"0D") was chosen because MBP COBOL most closely matches the sign storage of other COBOLs that use that convention.

-DCi | This selects the IBM storage convention. It is compatible with IBM COBOL, as well as with several others including RM/COBOL-85. It is also compatible with the X/Open COBOL standard.
-DCm | This selects the Micro Focus storage convention. It is compatible with Micro Focus COBOL when the Micro Focus ASCII sign-storage option is used (this is the Micro Focus default).
-DCn | This causes a different numeric format to be used. The format is the same as the one used when the -Dci option is used, except that positive COMP-3 items use X"0B" as the positive sign value instead of X"0C". This option is compatible with NCR COBOL.
-DCr | This selects the Realia sign storage convention. Sign information for S9(n) variables is stored using the conventions for Realia COBOL, and their conversion to binary decimal is the same as that performed by the Realia compiler.
-DCv This creates numeric sign formats that are compatible with VAX COBOL. These are identical to the IBM formats, except that unsigned COMP-3 fields place X"0C" in the sign position, instead of X"0F". The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). As a result, different COBOL vendors use different conventions. By using the options -Dca, -Dci, -Dcm, -Dcn, or -Dcv, you may select alternate sign-storage conventions. Doing so is useful in the following cases:
  • If you need to export data to another COBOL system and need to match its sign-storage convention.
  • If you are importing data from another COBOL system, and that data contains key fields with signed data. Keys are treated alphanumerically, so if you use the incorrect sign-storage convention, ACUCOBOL-GT will not find a matching key when it is doing a READ.
The storage-convention affects how data appears in USAGE DISPLAY, COMP-2, and COMP-3 data types.
-Dd31 | This option supports data items with up to 31-digits or 16 bytes. When this option is in effect, you may use as many as 31 X or 9 symbols in a PIC, instead of the usual 18. The maximum number of bytes in a COMP-X or COMP-N data item, whose picture contains only "X" symbols, is 16, instead of the usual 8. Intermediate results are calculated to 33 digits instead of the usual 20.
-Df This option changes the way the compiler treats data items declared as COMP-1 and COMP-2. Some compilers use COMP-1 and COMP-2 to specify single- and double-precision floating-point data items. ACUCOBOL-GT, however, assigns a different meaning to COMP-1 and COMP-2 and uses FLOAT and DOUBLE to specify floating-point data items.When the -Df option is used, the compiler treats data items declared as COMP-1 as if they were declared FLOAT and data items declared as COMP-2 as if they were declared DOUBLE. With the -Df option, you have the following correspondence:
COMP-1   FLOAT    single precision
COMP-2   DOUBLE   double precision
The -Df option makes it easier to compile code originally written for another compiler — one that used COMP-1 and COMP-2 to specify floating point data items. The -Df option lets you compile such code without having to change COMP-1 and COMP-2 to FLOAT and DOUBLE.
-Di

This option causes the compiler to initialize Working-Storage. Normally, the compiler will initialize all data items to spaces or the value specified with the -Dv option, except for those items given a VALUE clause. If this option is specified, data items are initialized according to their type:

  • Alphabetic, alphanumeric, alphanumeric edited, and numeric edited items are initialized to spaces.
  • Numeric items are initialized to zero.
  • Pointer items are initialized to null.
  • Index items are initialized to 1.

Automatic initialization applies only to Working-Storage and does not apply to any item that (a) is given a VALUE clause, (b) is EXTERNAL, or (c) is subordinate to a REDEFINES phrase.

-Dl1/2/4/8 | This option allows you to limit the maximum alignment modulus that will be used for SYNCHRONIZED data items. Normally, a synchronized data item is aligned on a 2-, 4-, or 8-byte boundary depending on its type. This option allows you to specify an upper bound to the modulus used. This is specified as a single digit that immediately follows the -Dl as part of the same argument. For example, -Dl4 specifies that the maximum synchronization boundary is a 4-byte boundary. If you want to make programs that are compliant with the 88/Open COBOL specification, you should specify -Dl4.
-Dm | This option causes any data item whose underlying type is binary to be stored in the minimum number of bytes needed to hold it. Normally, binary types are stored in two, four, or eight bytes. This option allows storage in any number of bytes ranging from one to eight.
-Dq | Causes the QUOTE literal to be treated as an apostrophe, or single quotation mark, rather than as a double quotation mark ("). One exception to this is the HP COBOL TRANSFORM verb, in which QUOTE is always treated as a double quotation mark.
-Ds | This causes USAGE DISPLAY numeric items with no SIGN clause to be treated as if they were described with the SIGN IS TRAILING SEPARATE clause. Several versions of RM/COBOL behave this way (all versions before 2.0, and some versions afterward).
-Dv | This option allows you to specify the default byte (initial value) used to initialize any data item not otherwise initialized when the program is loaded. The option must be followed by an equals sign (=) and the decimal value of the byte to use (for all current platforms, this is the ASCII value of the desired character). For example, to fill memory with the NULL character, use -Dv=0. To fill memory with the ASCII space character, use -Dv=32.
-Dw32 | This option is checked for compatibility with the system's bit arrangement.
-Dw64 | This option is checked for compatibility with the system's bit arrangement.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Truncation Options

The truncation options enable you to control the truncation of certain data items.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Dz | All binary and packed-decimal data types ignore their PICTURE when determining the largest value they can hold. The PICTURE is not used when moving to a nonnumeric destination (the largest possible value determines the number of digits moved instead).
-noTRUNC | All binary data types ignore their PICTURE when determining the largest value they can hold. However, the PICTURE is used when moving data from a binary number to a nonnumeric data item. The name of this option is similar to the name used by some other COBOL systems that behave this way.
-truncANSI | Full ANSI COBOL rules are in place. Each numeric data item stores values up to its PICTURE in size. A small number of USAGE types provide exceptions (such as COMP-X and COMP-5). Values larger than allowed by the PICTURE are truncated using the standard size rules when the data item is the target of a MOVE statement; however, COMP-5 items do use their PICTURE when moving a value to a nonnumeric data item. The results of an arithmetic overflow (without the SIZE phrase) are undefined.

Comments:

The -Dz truncation option is not supported in Managed COBOL.

Parent topic: Supported ACUCOBOL-GT Compiler Options


Video Options

The video options enable you to control the behavior of certain items displayed to screen.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Vc | This option causes any ACCEPT statement that contains a numeric or numeric edited receiving field to be treated as if the CONVERT phrase were also specified.
-Vd | This option causes non-USAGE DISPLAY numeric items to be converted to USAGE DISPLAY before the screen display occurs. This option is always on.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Warning and Error Options

The warning and error options enable you to set the error threshold before a object file will stop executing.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-a | This flag is now obsolete and should not be used.
-Qm | This option specifies the number of errors the compiler reports before it exits. The option must be followed by a positive numeric argument, which is the maximum number of errors the compiler reports before it exits. The default value is 100.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Debugging Options

The debugging options enable you to generate and execute object files suitable for debugging.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Note: The results of these options may differ slightly from how they appear in ACUCOBOL-GT COBOL, as they map to the debugging Compiler directives in Visual COBOL.
Option | Definition
-Ga, -Gd, -Gl, -Gs, -Gy | These options map to the ANIM Compiler directive setting.
-Gz | This option maps to the NOANIM Compiler directive setting.
Parent topic: Supported ACUCOBOL-GT Compiler Options


Miscellaneous Options

The miscellaneous options enable you to control a number of aspects of the generated object files, such as bounds checking and optimization.

The following compiler options are supported in Visual COBOL when using ccbl32 and ccbl64 from the command line or the ACUOPT Compiler directive.

Option | Definition
-Za | Causes the compiler to generate code to test array references at runtime. If an index is used which is out-of-bounds, the runtime system displays an error message showing the index value and the allowed bounds. (This causes some extra code to be generated and prevents certain table optimizations from occurring, so it should be turned off once a program is fully debugged.) With this option, the compiler does not re-use previously computed index values.
-Zc This compact option optimizes for smaller code instead of faster code.

This option is accepted by the compiler, but is ignored.

-Zd | Although still supported, this option has been replaced by the -Gd option. Both options produce the same results.
-Zg Enables the use of segmentation (overlays) in the source. If this option is not used, section numbers will be ignored.

This option is accepted by the compiler, but is ignored.

-Zi | Causes the program to be compiled as if it had the IS INITIAL PROGRAM phrase specified in its PROGRAM-ID paragraph.
-Zl | All data items may be larger than 64 KB. This option is obsolete.
-Zn This turns off ACUCOBOL-GT's local optimizer. This is useful primarily to see if the optimizer is introducing errors in the generated object code. This option also prevents the compiler from re-using previously computed index values.

This option is accepted by the compiler, but is ignored.

-Zs | Although still supported, this option has been replaced by the -Gy option. Both options produce the same results.
-Zy This option lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. If you use this option, the 4-digit year format will be used for ACCEPT FROM DATE providing that:
  • The receiving field is numeric or numeric edited and contains eight or more integer digits; or
  • The receiving field is not numeric or numeric edited and contains eight or more character positions.
If neither of the above conditions applies, then ACCEPT FROM DATE will return its normal 6-digit format even if you use -Zy.
-Zr0 | This option tells the compiler not to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.
-Zr1 | This option tells the compiler to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.
Parent topic: Supported ACUCOBOL-GT Compiler Options


32- and 64-Bit Code Generation

When compiling with the DIALECT"ACU" directive, the Compiler generates intermediate code that is bit independent. By using ccbl, you can specify 32 or 64-bit intermediate code.

When compiling for generated code you must specify 32 or 64-bit. Visual COBOL is bit-specific and does not support cross-bit generation.

ccbl is sensitive to the current COBMODE setting. There are also the ccbl32 and ccbl64 commands, which generate 32 or 64-bit code respectively. This is all analogous to cob.

Parent topic: Compiler Option Support


ACUCOBOL-GT Conversion Issues

The syntax of most ACUCOBOL-GT source programs when submitted to run on this COBOL system will be accepted and run successfully. However, sometimes this COBOL system might reject some of the syntax in the original source program, or might cause your program to behave unexpectedly at run-time.

The following is not an exhaustive list of the restrictions of using ACUCOBOL-GT source code in Visual COBOL. In most cases, if your code includes ACUCOBOL-GT features not supported by Visual COBOL, you will receive a Compiler error.

  • Complementary ACUCOBOL-GT Technologies
    In ACUCOBOL-GT, you can utilize a number of complementary technologies in your applications. In Visual COBOL, there are a number of technologies that provide equivalent or similar functionality.
  • Configuration Files and Configuration Variables
    ACUCOBOL-GT configuration files and configuration variables are not supported in Visual COBOL.
  • Multi-threading Implementation
    The ACUCOBOL-GT multi-threading model differs from the multi-threading model implemented in Visual COBOL.
  • Screen Descriptions
    Visual COBOL and extend® differ in their support for some of the Screen Description phrases.
  • Truncation Options in Managed Code
    The -Dz truncation option is not supported in Managed COBOL.
  • Unsupported Library Routines
    Not all ACUCOBOL-GT library routines are supported in Visual COBOL. You should remove unsupported routines from your source code.
  • Using Pipes to Assign Filenames When Using the Vision File Handler
    When assigning filenames, you cannot use certain pipes to assign a filename in the ASSIGN clause of the SELECT statement if you are using the Vision file handler.
Parent topic: Converting ACUCOBOL-GT Applications


Complementary ACUCOBOL-GT Technologies

In ACUCOBOL-GT, you can utilize a number of complementary technologies in your applications. In Visual COBOL, there are a number of technologies that provide equivalent or similar functionality.
You should compile your source code with the DIALECT"ACU" Compiler directive to give the fullest ACUCOBOL-GT emulation in Visual COBOL. If problems persist relating to any of the ACUCOBOL-GT technologies listed below, refer to the documentation for the corresponding Micro Focus technology to help remediate your code.
ACUCOBOL-GT technology | Corresponding technology | Notes
AcuConnect Thin Client | None | All syntax relating to this technology should be removed from your source.
AcuServer | Fileshare | You can connect to your Vision files through AcuServer, but the functionality is limited.
Acu4GL | Database Connectors | Full documentation is available from the Product Documentation section of the SupportLine website ( https://www.microfocus.com/support-and-services/documentation/).
AcuXDBC and AcuODBC | XDBC | Full documentation is available from the Product Documentation section of the SupportLine website ( https://www.microfocus.com/support-and-services/documentation/).
Xcentrisity for BIS | Xcentrisity for BIS | Full documentation is available from the Product Documentation section of the SupportLine website ( https://www.microfocus.com/support-and-services/documentation/).
XML Extensions | XML Extensions | Full documentation is available from the RM/COBOL product documentation set in the Product Documentation section of the SupportLine website ( https://www.microfocus.com/support-and-services/documentation/).
AcuSQL | OpenESQL preprocessor | Set the DIALECT"ACU" Compiler directive in your source to enable this preprocessor.
Graphical Technology (GT) |  |
Parent topic: ACUCOBOL-GT Conversion Issues
Related information
Fileshare Guide
OpenESQL


Configuration Files and Configuration Variables

ACUCOBOL-GT configuration files and configuration variables are not supported in Visual COBOL.

Visual COBOL uses different configuration files and variables. You need to review your existing ACUCOBOL-GT configuration to determine which settings are relevant for use and which settings have Visual COBOL equivalents.

For example, some configuration settings for handling Vision files can be set in the default File Handler in Visual COBOL.

Some ACU configuration variables are not necessary or applicable in Micro Focus COBOL (for example, PERFORM_STACK), and the functionality of others is covered by the Micro Focus compile and run-time options (for example, A_CHECKDIV).

Parent topic: ACUCOBOL-GT Conversion Issues


Multi-threading Implementation

The ACUCOBOL-GT multi-threading model differs from the multi-threading model implemented in Visual COBOL.

The ACUCOBOL-GT model contains some additional syntax not supported in Visual COBOL. Refer to Multi-threaded Programming for details of supported syntax and concepts in Visual COBOL.

Parent topic: ACUCOBOL-GT Conversion Issues
Related information
Multi-threaded Programming


Screen Descriptions

Visual COBOL and extend® differ in their support for some of the Screen Description phrases.
In Visual COBOL, the following phrases of the Screen Description entry are not supported and should be removed from your programs:
  • AFTER
  • BEFORE
  • EXCEPTION
Parent topic: ACUCOBOL-GT Conversion Issues


Truncation Options in Managed Code

The -Dz truncation option is not supported in Managed COBOL.

It is, however, supported in native COBOL, using the ACUOPT Compiler directive.

Parent topic: ACUCOBOL-GT Conversion Issues
Related reference
ACUOPT
Truncation Options


Unsupported Library Routines

The following ACUCOBOL-GT library routines are not (or will ever be) supported in Visual COBOL and will produce a COBRT097 Acu library routine is and will remain unimplemented error. You should remove any calls to the following routines from your source code to avoid producing the error.
Note: This list may contain customer-specific routines that are not found in the ACUCOBOL-GT product documentation.
  • C$ASYNCPOLL
  • C$ASYNCRUN
  • C$CHAIN
  • C$CHARTERR
  • C$CONFIG
  • C$EXCEPINFO
  • C$GETVARIANT
  • C$GETEVENTDATA
  • C$GETEVENTPARAM
  • C$GETERRORFILE
  • C$GETNETEVENTDATA
  • C$KEYMAP
  • C$PRODKEY
  • C$RESOURCE
  • C$SERVER-EXTENSION
  • C$SETERRORFILE
  • C$SETEVENTDATA
  • C$SETEVENTPARAM
  • C$SETVARIANT
  • C$TOJIS
  • KEISEN1
  • KEISEN2
  • KEISEN-SELECT
  • SYSID
  • W$BROWSERINFO
  • W$FORGET
  • W$GETC
  • W$GETCHAR
  • W$GETCGI
  • W$GETURL
  • W$INPUTMODE
  • W$KEYBUF
  • W$MENU
  • W$MOUSE
  • W$PALETTE
  • W$POSTURL
  • W$STATUS
  • $HP-CURRENT-DATE
  • $HP-TIME-OF-DAY

There is also another list of library routines that are not currently supported, but may be in the future. These also produce a run-time error COBRT098 The library routine is not available in Visual COBOL (routine-name) Please contact Micro Focus Customer Care for information and must be removed from your source code whilst they are not supported.

  • ASCII2HEX
  • ASCII2OCTAL
  • HEX2ASCII
  • KEISEN
  • OCTAL2ASCII
  • C$CODESET
  • C$DISCONNECT
  • C$EXTINFO
  • C$FILESYS
  • C$JAVA
  • C$KEYPROGRESS
  • C$LOCALPRINT
  • C$OPENSAVEBOX
  • C$PARSEXFD
  • C$PING
  • C$RCONVERT
  • C$RECOVER
  • C$REDIRECT
  • C$SOCKET
  • C$SYSLOG
  • R$IO
  • REG_OPEN_KEY
  • REG_CLOSE_KEY
  • REG_CREATE_KEY
  • REG_DELETE_KEY
  • REG_ENUM_KEY
  • REG_QUERY_VALUE
  • REG_SET_VALUE
  • REG_OPEN_KEY_EX
  • REG_CREATE_KEY_EX
  • REG_DELETE_VALUE
  • REG_ENUM_VALUE
  • REG_QUERY_VALUE_EX
  • REG_SET_VALUE_EX
  • S$io
  • $WINHELP
  • W$BITMAP
  • W$FLUSH
  • W$FONT
  • W$PROGRESSDIALOG
  • W$TEXTSIZE
  • WIN$PLAYSOUND
  • WIN$PRINTER

For a list of currently supported library routines, refer to ACUCOBOL-GT Library Routines.

Parent topic: ACUCOBOL-GT Conversion Issues
Related information
ACUCOBOL-GT Library Routines


Using Pipes to Assign Filenames When Using the Vision File Handler

When assigning filenames, you cannot use certain pipes to assign a filename in the ASSIGN clause of the SELECT statement if you are using the Vision file handler.
The ACUCOBOL-GT syntax of assigning a file using the -P, -D, and -F syntax is not supported in Visual COBOL; for example:
select test-file assign to "-P ls *"

If your applications use this syntax, you should remove it from your SELECT statements.

For more information on the pipes that are supported, read Programming > File Handling > File Handling Guide > Filenames > Setting Up Pipes.

Parent topic: ACUCOBOL-GT Conversion Issues


ACUCOBOL-GT File Handling

Visual COBOL allows you to continue to use your existing ACUCOBOL-GT data files, including Vision indexed data files.

Those files can also continue to be used through AcuServer, with minimal changes to your code required.

Alternatively, you can convert your Vision files to Micro Focus format. There is no need to convert your sequential data files.

  • Configuring Access to Vision Files
    You can access Vision data and database files by mapping the filename to a compatible index format in the Micro Focus File Handler.
  • File Limits
    When using Vision files in Visual COBOL, there are a number of file limits that affect file handling operations.
  • Vision Related Utilities
    Explains the utilities from the Vision indexed file system that are supported in Visual COBOL.
  • Converting Vision Files
    You can convert your Vision files to the Micro Focus format using the Classic Data File Tools or the ACU2MFDataMigration utility.
  • Configuring Access to Data Files Through AcuServer
    Configure your converted applications to access data files through AcuServer.
Parent topic: Compatibility with ACUCOBOL-GT


Configuring Access to Vision Files

Note: For these options to take effect, the ACUFH configuration option must be set ON; by default, this is ON. For these options to take effect under Enterprise Server, ESACUFH must also be set ON; by default, this is OFF.

To handle Vision files, you map a file to a compatible IDXFORMAT in the File Handler configuration file.

Within the configuration file, you can map an IDXFORMAT to all files in a particular folder, all files with a specific file extension, or a single file. See Format of the Configuration File for the tags that you can use for the mapping, and the order in which settings in these tags are applied.

The order that the mapping is applied is important, as conflicting settings can be overwritten; for example, the following excerpt of the configuration file sets all files in usr/files/rmfiles to IDXFORMAT 21 and all files with a .DAT extension to IDXFORMAT 17:

[FOLDER:usr/files/rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

If there is a .DAT file in usr/files/rmfiles, the mappings are applied according to the type of tag. In the case above, mappings in the extension tag are applied after mappings in the FOLDER tag, and so the .DAT file in that directory has an IDXFORMAT of 17.

By default, the File Handler handles all sequential and relative data files, but if you want to handle them through the Vision file handler, use the INTEROP=ACU configuration option; however, in cases where the INTEROP and IDXFORMAT mappings conflict, the INTEROP setting will override IDXFORMAT for your Vision indexed data files.

Parent topic: ACUCOBOL-GT File Handling
Related reference
Format of the Configuration File
IDXFORMAT
INTEROP
ACUFH
ESACUFH


File Limits

When using Vision files in Visual COBOL, there are a number of file limits that affect file handling operations.

The following limits are in addition to the ones imposed in Visual COBOL; see Limits in the File Handling Reference section.

Note: The limits listed on this page override any listed in the File Handling Reference section when handling Vision files.
Maximum record size: | 64 MB (67,108,864)
Maximum number of indexed keys: | 1 primary + 119 alternates
Maximum number of segments per key: | 16
Maximum indexed key size: | 250 bytes
Parent topic: ACUCOBOL-GT File Handling
Related reference
Limits


Vision Related Utilities

Vision provides a series of utilities that enable you to manipulate Vision files from the command line.

Each utility is available in a 32-bit and a 64-bit version, located in $COBDIR/bin. The version executed is determined by the COBMODE environment variable.

Commands

mfvutil
Rebuilds a file that has become corrupt, or one that contains a large number of deleted records that you want to remove from the file.
mfvio
Enables you to collect a group of files together into archives, and allows you to extract some or all of these files from these archives.
mflogutil
Enables you to examine and edit an ACUCOBOL-GT transaction log file.
mfvissort
Enables you to sort or merge Vision files.
Parent topic: ACUCOBOL-GT File Handling


Converting Vision Files

You can access your Vision files using the File Handler, but if you prefer to convert them to Micro Focus format, as part of a migration, usingthe following:
Data File Converter
Use the Micro Focus Data File Converter to convert your Vision files to Micro Focus format.

Parent topic: ACUCOBOL-GT File Handling
Related reference
Using the Data File Converter
Data Tools


Configuring Access to Data Files Through AcuServer

Configure your converted applications to access data files through AcuServer.
Note: It is assumed that your environment and server is already configured correctly for using AcuServer.

Syntax:

To access a data file through AcuServer, the following syntax must be passed to the file handler:

acurfap://servername:[port]:/path/to/file
acurfap://
The protocol to use for AcuServer. This does not change.
servername
The name of the AcuServer server.
port
The server port to use when connecting to AcuServer. This is optional, and if omitted, the default port number is used.
path/to/file
The path name to the file.

Specifying the file explicitly:

You can specify the full syntax in the SELECT statement. For example, the following statement connects to the server asvr1, on port 3011, then locates the file idx1 at /home/idx/.

...
select acusvridx assign to acurfap://asvr1:3011:/home/idx/idx1.
...

Specifying the file implicitly:

If you are not explicitly using the AcuServer syntax in your SELECT statement, for example:

...
select acusvridx assign to idx1.
...

you must specify it in the COBDATA environment variable using the syntax described above:

set COBDATA=%COBDATA%; "acurfap://servername:port:path/to/file"
export COBDATA=$COBDATA: '"acurfap://servername:port:path/to/file"'

The following example connects to the server asvr2, on the default port, then locates the file in the SELECT statement at /home/idx/.

set COBDATA=%COBDATA%; "acurfap://asvr2::c:\idx"
export COBDATA=$COBDATA: '"acurfap://asvr2::/home/idx"'

Note: An additional set of quotation marks is required around the AcuServer syntax to preserve the original quotation marks.

If a path name is specified in COBDATA, it is prepended to the file name before file name mapping takes effect.

You must also compile with FILETYPE=17 if you are using a sequential file, or if your file handling configuration file does not specify IDXFORMAT=17 for the Vision file.

File name mapping:

If you have used any ACUCOBOL file name mapping techniques to specify an AcuServer file, you will need to update the configuration to use Micro Focus file name mapping. Use the following table as a guide to some of the equivalents in this COBOL system.

ACUCOBOL variable | Replace with
FILE_CASE | FILECASE configuration option
FILE_PREFIX | COBDATA environment variable
FILE_SUFFIX | FILESUFFIX configuration option
APPLY_FILE_PATH | n/a
FILE_ALIAS_PREFIX | dd_ mapping

Restrictions

The encryption and password protection features are not supported in Visual COBOL.

Parent topic: ACUCOBOL-GT File Handling
Related concepts
Configuration Files and Configuration Variables
Related reference
FILETYPE
IDXFORMAT
COBDATA
FILECASE
FILESUFFIX
Filename Mapping


ACUCOBOL-GT Library Routines

This COBOL development system provides a number of ACUCOBOL-GT library routines in native and managed code.
  • C$CALLEDBY
    Returns the name of the caller of the currently running COBOL program or spaces if no caller exists or if the caller is unknown.
  • C$CALLERR
    Retrieves the reason why the last CALL statement failed. For accurate information, it must be called before any other CALL statement is executed.
  • C$CHDIR
    Changes the current working directory.
  • C$COPY
    Creates a copy of an existing file.
  • C$DELETE
    Deletes a file.
  • C$FILEINFO
    Retrieves some operating system information about a given file.
  • C$GetLastFileOp
    Retrieves the last COBOL I/O operation performed.
  • C$JUSTIFY
    C$JUSTIFY performs left or right justification of data and centering of data.
  • C$LIST-DIRECTORY
    The C$LIST-DIRECTORY routine lists the contents of a selected directory. Each operating system has a unique method for performing this task. C$LIST-DIRECTORY provides a single method that will work for all operating systems.
  • C$LOCKPID
    This routine returns the Process ID (PID) of the process holding the lock responsible for the previous file lock or record locked condition encountered. This library routine works only with the Vision file system and the UNIX platform.
  • C$MAKEDIR
    Creates a new directory.
  • C$MEMCPY (Dynamic Memory Routine)
    Copies bytes between any two memory locations.
  • C$MYFILE
    Returns the filename of the disk file containing the currently executing program.
  • C$NARG
    This routine returns the number of parameters passed to the current program.
  • C$PARAMSIZE
    This routine returns the number of bytes actually passed by the caller for a particular parameter.
  • C$REGEXP
    This routine allows you to search strings using regular expressions.
  • C$RERR
    Returns extended file status information for the last I/O statement.
  • C$RERRNAME
    Returns the name of the last file used in an I/O statement.
  • C$RUN
    ACUCOBOL-GT for Windows supports an alternate method for running other programs. This is through the library routine C$RUN. This library routine works identically to the SYSTEM library routine, except that the calling program does not wait for the called program to finish. Instead, both programs run in parallel.
  • C$SLEEP
    This routine causes the program to pause in a machine efficient fashion.
  • C$SYSTEM
    This routine combines the functionality of "SYSTEM" and "C$RUN". It allows you to run other programs from inside a COBOL application in a variety of ways.
  • C$TOUPPER and C$TOLOWER
    These routines translate text to upper- or lower-case.
  • I$IO
    The I$IO routine provides an interface to the file handler.
  • M$ALLOC (Dynamic Memory Routine)
    Allocates a new area of dynamic memory.
  • M$COPY (Dynamic Memory Routine)
    Copies a region of memory from one location to another.
  • M$FILL (Dynamic Memory Routine)
    Sets a region of memory to a constant value.
  • M$FREE (Dynamic Memory Routine)
    Frees a previously allocated piece of memory.
  • M$GET (Dynamic Memory Routine)
    Retrieves data from an allocated memory block.
  • M$PUT (Dynamic Memory Routine)
    Stores data in an allocated memory block.
  • RENAME
    Renames a file.
  • WIN$VERSION
    Returns version information for Windows and Windows NT host platforms.
Parent topic: Compatibility with ACUCOBOL-GT


C$CALLEDBY

Returns the name of the caller of the currently running COBOL program or spaces if no caller exists or if the caller is unknown.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$CALLEDBY"
    USING CALLING-PROGRAM
    GIVING CALL-STATUS

Parameters

CALLING-PROGRAM PIC X(n) | Contains the name of the calling program or spaces if no caller exists or if the caller is unknown. The runtime will use as much space for the name or spaces as the COBOL program allows. If the object being called is in an object library, the program returns the PROGRAM-ID. If the object is not in an object library, the disk name is returned.
CALL-STATUS PIC S99 | This parameter receives one of the following values: 1 - Routine called by another COBOL program 0 - Routine is the main program; no caller exists -1 - Caller unknown; routine not called by a COBOL program

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


C$CALLERR

Retrieves the reason why the last CALL statement failed. For accurate information, it must be called before any other CALL statement is executed.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$CALLERR"
    USING ERR-CODE, ERR-MESSAGE

Parameters

ERR-CODE PIC X(2)

This parameter receives one of the following values:

01 | Program file missing or inaccessible
02 | Called file not a COBOL program
03 | Corrupted program file
04 | Inadequate memory available to load program
05 | Unsupported object code version number
06 | Recursive CALL of a program
07 | Too many external segments
08 | Large-model program not supported (returned only by runtimes that do not support large-model programs)
09 | Exit Windows and run "share.exe" to run multiple copies of "wrun32.exe" (returned only by Windows runtimes)
14 | Japanese objects are not supported (returned only by runtimes that do not support Japanese objects)

ERR-MESSAGE PIC X(n) (optional)

This routine may optionally be passed a second alphanumeric parameter. This parameter is filled in with a descriptive message about the error encountered.

Compatibility Issues

  • Only ERR-CODE 01 is returned in this COBOL system.
  • ERR-MESSAGE is always set to SPACES.
Parent topic: ACUCOBOL-GT Library Routines


C$CHDIR

Changes the current working directory.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$CHDIR"
    USING DIR-NAME, ERR-NUM

Parameters

DIR-NAME PIC X(n) Contains the name of the new directory, or spaces.

The "@[DISPLAY]:" for Thin Client support is allowed. For example:

C$CHDIR "@[DISPLAY]:C:\path"

In Thin Client environments, to get the current default directory on the display host, DIR_NAME should contain "@[DISPLAY]:" followed by spaces.

ERR-NUM PIC 9(9) COMP-4 (optional) Holds the returned error number, or zero on success.

Comments

If a second USING parameter is passed, it must be described as PIC 9(9) COMP-4. This parameter will be set to ZERO if the directory change is successful. Otherwise, it will contain the operating system's error number.

If DIR-NAME contains spaces, then the current default directory is returned in it. In this case, ERR-NUM is not used. Otherwise, DIR-NAME should contain the name of a directory to make the new default directory. On Windows machines, this can include a drive letter. If you pass ERR-NUM, it will be set to zero if the change was successful. Otherwise, ERR-NUM will contain the error value returned by the operating system.

On some systems (such as VMS), it is legal to switch to a directory that does not exist, while other systems (Windows, UNIX) do not allow it.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name.

IMPORTANT

If you use C$CHDIR, create a CODE_PREFIX configuration entry to locate your object files. Ensure that all of the search locations specified by the CODE-PREFIX are full path names. Do not use the current directory or any relative path names in the CODE_PREFIX. Without a full path name, the runtime system may be unable to find your object files if it needs to re-open them.

For example, the runtime system must occasionally re-open an object file when:

  • you are using the source debugger
  • the program contains segmentation (overlays)
  • you are using object libraries

If the object file was initially found in the current directory or a directory specified relative to the current directory, and you then change the current directory with the C$CHDIR routine, the runtime system will not be able to find the object file if it needs to re-open it. This will cause a fatal error and your program will halt.

If you use C$CHDIR and you are running in debug mode, be sure to set CODE_PREFIX in the configuration file, not in the environment. You may set CODE_PREFIX in the environment when you are not in debug mode.

Compatibility Issues

  • In JVM COBOL, this routine is not supported.
  • "@[DISPLAY]" is not supported in this COBOL system.
  • The FILENAME_SPACES configuration variable is not supported in this COBOL system. To use filenames that contain spaces, enclose them in quotation marks.
  • The CODE_PREFIX configuration variable is not supported in this COBOL system.
Parent topic: ACUCOBOL-GT Library Routines


C$COPY

Creates a copy of an existing file.

Syntax:

CALL "C$COPY"
   USING source-file, dest-file, [file-type,]
   [GIVING status]

Parameters:

source-file
PIC X(n)
dest-file
PIC X(n)
file-type
PIC X
status
Any numeric type

On Entry:

source-file
The path name of the file to be copied
dest-file
The path name of the destination file
file-type
The file organization of the source file.It must be one of: S (for sequential), R (for relative) or I (for indexed).

This defaults to S if not specified.

On Exit:

copy-status
Returns zero if the copy is successful, or non-zero if not.

Comments:

To obtain an extended file status code for this operation, define status as comp xx comp-x and follow the example in Extended File Status Codes.

Parent topic: ACUCOBOL-GT Library Routines


C$DELETE

Deletes a file.

Syntax:

CALL "C$DELETE"
   USING file-name, [file-type,]
   [GIVING status]

Parameters:

file-name
PIC X(n)
file-type
PIC X
status
Any numeric type

On Entry:

file-name
The pathname of the file to be deleted
file-type
The file organization of the filename. It must be one of: S (for sequential), R (for relative) or I (for indexed).

This defaults to S if not specified.

On Exit:

status
Returns zero if the delete is successful, or non-zero if not.

Comments:

To obtain an extended file status code for this operation, define status as comp xx comp-x and follow the example in Extended File Status Codes.

Parent topic: ACUCOBOL-GT Library Routines


C$FILEINFO

Retrieves some operating system information about a given file.

Syntax:

CALL "C$FILEINFO"
   USING file-name, file-info
   GIVING status

Parameters:

file-name
PIC X(n)
file-info
Define the following group
01 file-info
  03 file-size  pic x(8) comp-x.
  03 file-date  pic 9(8) comp-x.
  03 file-time  pic 9(8) comp-x.
status
Any numeric type

On Entry:

file-name
The name of the file

On Exit:

file-info
The group item to receive the file information
status
Returns zero if the delete is successful, or non-zero if not.

Comments:

To obtain an extended file status code for this operation, define status as comp xx comp-x and follow the example in Extended File Status Codes.

Parent topic: ACUCOBOL-GT Library Routines


C$GetLastFileOp

Retrieves the last COBOL I/O operation performed.

Syntax:

Use this library routine within a declarative procedure after an I/O error has occurred.

CALL "C$GetLastFileOp" USING operation

Parameters:

operation
PIC X(20)

On Exit:

operation
The name of the last I/O operation performed. The valid operations returned are:
  • Close
  • Commit
  • Delete
  • DeleteFile
  • Open
  • ReadLock
  • ReadNextLock
  • ReadNextNoLock
  • ReadNoLock
  • ReadPreviousLock
  • ReadPreviousNoLock
  • Rewrite
  • Rollback
  • Start
  • StartTransaction
  • Unlock
  • UnlockAll
  • Write

Comments:

If the operation is longer than 20 characters, it is truncated to the right.

If the value SPACES is returned that indicates that no operation is available.

Parent topic: ACUCOBOL-GT Library Routines


C$JUSTIFY

C$JUSTIFY performs left or right justification of data and centering of data.

Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$JUSTIFY"
    USING DATA-ITEM, JUSTIFY-TYPE

Parameters

This data item contains the data to be justified.

This optional parameter contains one of three literal values:

L | indicates left justification
R | indicates right justification
C | indicates centering

If this parameter is omitted, then "R" is implied.

Description

This routine removes all leading and trailing spaces from DATA-ITEM and justifies the remaining data as indicated by JUSTIFY-TYPE. The resulting string is returned in DATA-ITEM. If centering is chosen, there will be one more space on the right than on the left if an odd number of spaces is used.

Compatibility Issues

None
Parent topic: ACUCOBOL-GT Library Routines


C$LIST-DIRECTORY

The C$LIST-DIRECTORY routine lists the contents of a selected directory. Each operating system has a unique method for performing this task. C$LIST-DIRECTORY provides a single method that will work for all operating systems.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$LIST-DIRECTORY"
    USING OP-CODE, parameters

Parameters

OP-CODE PIC 99 COMP-X

Indicates which C$LIST-DIRECTORY operation to perform. The operations are described below.

Parameters vary depending on the op-code chosen.

Parameters provide information and hold results for the op-code specified. These parameters are described below.

Description

C$LIST-DIRECTORY allows you to get the names of files residing in a given directory. It accomplishes this through three distinct operations. The first operation opens the specified directory. The second operation returns the filenames in the list, one-at-a-time. The third operation closes the directory and deallocates all memory used by the routine. C$LIST-DIRECTORY has the following operation codes (defined in acucobol.def):

LISTDIR-OPEN (VALUE 1)
Opens the specified directory. It has two parameters:
Directoryname PIC X(n)
Contains the name of the directory to open. This directory must exist, and you must have permissions to read the directory. You may use remote name syntax if AcuServer is installed on the remote machine. The "@[DISPLAY]:" for Thin Client support may be used. For example:
C$LIST-DIRECTORY using listdir-open,
"@[DISPLAY]:C:\path", pattern
Pattern PIC X(n)
Specifies the type of filename for which to search. This routine supports "wildcards," meaning that the character "*" will match any number of characters, and the character "?" will match any single character. For example, you can search by file suffix (*.def) or by a common part of a file name (acu*).

If the call to LISTDIR-OPEN is successful, RETURN-CODE contains a handle to the list. The value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. That data item should be passed as the directory handle to the other C$LISTDIRECTORY operations. If the call to LISTDIR-OPEN fails (if the directory does not exist, contains no files, or you do not have permission to read the directory), RETURN-CODE is set to a NULL handle.

LISTDIR-NEXT (VALUE 2)
Reads each filename from the open directory. It has two parameters:
Handle USAGE HANDLE
The handle returned in the LISTDIR-OPEN operation.
Filename PIC X(n)
The location of the next filename to be returned. If the directory listing is finished, it is filled with spaces.

The call to LISTDIR-NEXT can include an additional argument, LISTDIR-FILE-INFORMATION (defined in "acucobol.def"), which receives information about the returned file name. This is an optional group item which returns information about the following data items:

LISTDIR-FILE-TYPE
The file type can be one of the following:

B = block device
C = character device
D = directory
F = regular file
P = pipe (FIFO)
S = socket
U = unknown

LISTDIR-FILE-CREATION-TIME
The creation time is the date (and time) that the file was originally created.
LISTDIR-FILE-LAST-ACCESS-TIME
The last access time is the date (and time) that the file was last accessed by some application (usually when the file was queried in some way).
LISTDIR-FILE-LAST-MODIFICATION-TIME
The last modification time is the date (and time) the file was last written to.
LISTDIR-FILE-SIZE
The size of the file is given in bytes.
LISTDIR-CLOSE (VALUE 3)
Releases the resources used by the other operations. It must be called to avoid memory leaks. It has one parameter, handle, which is the same data item used by the LISTDIR-NEXT operation.
Handle USAGE HANDLE
The handle returned in the LISTDIR-OPEN operation.
Note: Because the supported file types vary by operating system, The data items in the above list have slightly different meanings depending on your operating system. Even on operating systems that support these values, some file systems may not. Some versions of the UNIX® operating system may change these values when permissions are changed. Refer to your operating system documentation for specific definitions.

Example

The following example lists the contents of a directory with repeated calls C$LISTDIRECTORY:

WORKING-STORAGE SECTION.
copy "def/acucobol.def".
01  pattern       pic x(5) value "*.vbs".
01  directory     pic x(20) value "/virusscan".
01  filename      pic x(128).
01  mydir         usage handle.
PROCEDURE DIVISION.
MAIN.
* CALL LISTDIR-OPEN to get a directory handle.
    call "C$LIST-DIRECTORY"
       using listdir-open, directory, pattern.
    move return-code to mydir.
    if mydir = 0
       stop run
    end-if.
* CALL LISTDIR-NEXT to get the names of the files.
* Repeat this operation until a filename containing only
* spaces is returned.  The filenames are not necessarily
* returned in any particular order.  Filenames may be
* sorted on some machines and not on others.
    perform with test after until filename = spaces
       call "C$LIST-DIRECTORY"
          using listdir-next, mydir, filename
    end-perform.
* CALL LISTDIR-CLOSE to close the directory and deallocate
* memory. Omitting this call will result in memory leaks.
    call "C$LIST-DIRECTORY" using listdir-close, mydir.
    stop run.

Compatibility Issues

  • You must compile with the DIALECT"ACU" Compiler directive when using this library routine.
  • "@[DISPLAY]" is not supported in this COBOL system.
Parent topic: ACUCOBOL-GT Library Routines


C$LOCKPID

This routine returns the Process ID (PID) of the process holding the lock responsible for the previous file lock or record locked condition encountered. This library routine works only with the Vision file system and the UNIX platform.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$LOCKPID"
    GIVING PROCESS-ID.

Parameter

PROCESS-ID PIC 9(n) This contains a numeric data item large enough to hold a PID. On most platforms, PIC 9(5) is sufficient. On 64-bit systems, PIC 9(7) is recommended.

Comments

C$LOCKPID returns a PROCESS-ID of 0 if you have not yet encountered a locked file or record, if the PID is otherwise not found, or if you've used this routine with a non-UNIX runtime.

Compatibility Issues

None
Parent topic: ACUCOBOL-GT Library Routines


C$MAKEDIR

Creates a new directory.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

C$MAKEDIR can make a directory only one level lower than an existing directory and cannot create more than one level at a time.

Usage

CALL "C$MAKEDIR"
    USING DIR-NAME GIVING STATUS-CODE

Parameters

DIR-NAME PIC X(n) Contains the name of the directory to be created. This should be either a full path name or a name relative to the current directory. You may use remote name syntax in combination with AcuServer to create a directory on a remote machine.

The "@[DISPLAY]:" annotation for Thin Client support may also be specified. For example:

C$MAKEDIR "@[DISPLAY]:C:\path"
STATUS-CODE Numeric data item. Receives the return status of the call to create a directory. A return status of zero indicates that the directory was successfully created; a status of one ("1") indicates otherwise.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name.

Compatibility Issues

  • "@[DISPLAY]" is not supported in this COBOL system.
  • The FILENAME_SPACES configuration variable is not supported in this COBOL system. To use filenames that contain spaces, enclose them in quotation marks.
Parent topic: ACUCOBOL-GT Library Routines


C$MEMCPY (Dynamic Memory Routine)

Copies bytes between any two memory locations.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$MEMCPY"
    USING, BY VALUE, DEST-PTR, SRC-PTR, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER or USING BY REFERENCE | Contains the address of the first byte of the destination.
SRC-PTR USAGE POINTER or USING BY REFERENCE | Contains the address of the first byte of the source.
NUM-BYTES USAGE UNSIGNED-INT or an unsigned numeric literal | Indicates the number of bytes to copy.

Description

This routine copies NUM-BYTES bytes of memory from the address contained in SRC-PTR to the address contained in DEST-PTR. This routine is functionally similar to the M$COPY (Dynamic Memory Routine) routine except that parameters are passed by value instead of by reference. This routine can be used in cases where M$PUT and M$GET are not adequate. Note that this routine is relatively dangerous to use. It does not perform any error checking and can easily cause memory access violations if you pass it incorrect data. In other words, this routine is a very low-level routine and should be used cautiously.

You do not need to pass POINTER data items for SRC-PTR and DEST-PTR. If you prefer, either or both can be replaced by a data item passed BY REFERENCE. If you do this, then the address of the data item is passed to C$MEMCPY. For example, you can copy 10 bytes to DEST-ITEM from the memory address contained in SRC-PTR with:

     CALL "C$MEMCPY"
        USING BY REFERENCE DEST-ITEM, BY VALUE SRC-PTR, 10

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


C$MYFILE

Returns the filename of the disk file containing the currently executing program.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

This is especially useful if the disk file is an object library.

Usage

CALL "C$MYFILE"
    USING PROGRAM-NAME
    GIVING CALL-STATUS

Parameters

PROGRAM-NAME PIC X(n) | Indicates the name of the disk file containing the currently executing program, if known. The runtime will use as much space for the name of the file as the COBOL program allows. This parameter will contain the filename just as the runtime received it. For example, if an object library is loaded as ../ardir/myarlib.lib, and a program in myarlib.lib calls this routine, PROGRAM-NAME will have a value of ../ardir/myarlib.lib.
CALL-STATUS PIC S99. | This parameter receives one of the following values: 1 - PROGRAM-NAME was filled successfully -1 - Program name unknown

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


C$NARG

This routine returns the number of parameters passed to the current program.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$NARG"
    USING NUM-PARAM

Parameter

NUM-PARAM COMP-1

Description

This routine must be called with one USING parameter that must be a COMP-1 data item. This data item is filled in with the number of parameters. If the calling program is a subprogram, then this will be the number of USING items in the CALL statement that initiated the program. If the calling program is a main program, then this will be the number of CHAINING parameters passed from the runcbl command line or the CHAIN statement that initiated the program. C$NARG works only when the program is a called subroutine. It does not work with the "CALL RUN" form of the CALL verb.

Compatibility Issues

  • This routine is not supported in managed COBOL.
  • Set the Compiler directive COMP1(BINARY) to set ACUCOBOL-GT behavior for COMP-1 data items.
  • The "CALL RUN" statement is not supported in this COBOL system.
  • In ACUCOBOL-GT COBOL, the number of parameters passed is calculated by the number of parameters specified in the USING phase of the CALL statement in the calling program. In this COBOL system, the number of parameters passed is calculated by the number of parameters the calling program actually receives.
Parent topic: ACUCOBOL-GT Library Routines
Related reference
COMP1


C$PARAMSIZE

This routine returns the number of bytes actually passed by the caller for a particular parameter.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$PARAMSIZE"
    USING PARAM-NUM,
    GIVING PARAM-SIZE

Parameters

PARAM-NUM numeric parameter | This value is the ordinal position in the Procedure Division's USING phrase of the parameter whose size you want to know.
PARAM-SIZE any numeric data item | This item receives the number of bytes in the data item actually passed by the caller.

Description

This routine returns the actual size (in bytes) of a data item passed to the current program by its caller. You pass the number (starting with 1) of the data item in the Procedure Division's USING phrase, and C$PARAMSIZE will return the size of the corresponding item that was actually passed. This can be useful for handling data items of unknown size.

For example, suppose that you wanted to write a routine that could convert any data item to upper-case, up to 10000 bytes in size. This routine could look like this:

IDENTIFICATION DIVISION.
PROGRAM-ID.  MAKE-UPPERCASE.

DATA DIVISION.
WORKING-STORAGE SECTION.
77  PARAM-SIZE    PIC 9(5).

LINKAGE SECTION.
77  PASSED-ITEM   PIC X(10000).

PROCEDURE DIVISION USING PASSED-ITEM.
MAIN-LOGIC.
   CALL "C$PARAMSIZE" USING 1, GIVING PARAM-SIZE
   INSPECT PASSED-ITEM( 1 : PARAM-SIZE )
      CONVERTING "abcdefghijklmnopqrstuvwxyz"
      TO "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  EXIT PROGRAM.

In this example, if you do not use C$PARAMSIZE, you have to pass a full 10000 bytes to this routine or you get a memory usage error. By using C$PARAMSIZE and reference modification, only the memory actually passed is referenced, and there is no error. C$PARAMSIZE works only when the program is a called subroutine. It does not work with the "CALL RUN" form of the CALL verb.

If you pass a subitem of a linkage item in a CALL statement and the subprogram calls C$PARAMSIZE with requesting the size of the parameter, it will get the size as described in the linkage section of the calling program, unless that subitem is the first item of the linkage item. In that case, the size returned will be the size of the original item.

Compatibility Issues

  • This routine is not supported in managed COBOL.
  • In this COBOL system, the size of the item as specified in the calling program is always returned.
Parent topic: ACUCOBOL-GT Library Routines


C$REGEXP

This routine allows you to search strings using regular expressions.

Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$REGEXP"
    USING OP-CODE, parameters
    GIVING return-value

Parameters

Op-codes specify the operation to perform. Each operation is defined in acucobol.def and is described in detail below. Op-codes include:
Code | Operation
1 | AREGEXP-GET-LEVEL
2 | AREGEXP-COMPILE
3 | AREGEXP-MATCH
4 | AREGEXP-RELEASE-MATCH
5 | AREGEXP-RELEASE
6 | AREGEXP-NUMGROUPS
7 | AREGEXP-GETMATCH
20 | AREGEXP-LAST-ERROR

Parameters vary depending on the operation selected. They provide information and hold results.

return-value: Numeric data item.

Unless otherwise noted, each operation returns a value or a status in return-value. Its contents vary by operation and the result of the operation.

Description

This routine allows you to use a regular expression to search a text string.

A regular expression is a formula for matching strings that have a certain pattern. For a complete description of regular expressions, see the POSIX 1003.2 standard appropriate for your platform. Windows platforms use the CAtlRegExp library; UNIX platforms use the POSIX C routines native to the platform.

A simple use of C$REGEXP is outlined in the following steps.

  1. Use the AREGEXP-GET-LEVEL op-code to validate that the host platform provides support for regular expressions.
  2. Validate and compile your regular expression with op-code AREGEXP-COMPILE. Your program should include an error handling routine in the event that the compiler finds an error in the expression.
  3. Use op-code AREGEXP-MATCH to apply a compiled regular expression to a string to search for a match. You may want to do this iteratively to find all matches in the string.
  4. Use op-codes AREGEXP-NUMGROUPS and AREGEXP-GETMATCH to work with subexpression matches.
  5. Manage the memory used by this routine with op-codes AREGEXP-RELEASE-MATCH and AREGEXP-RELEASE.

Op-codes and Parameters

AREGEXP-GET-LEVEL (op-code 1)

This operation indicates whether regular expression support is available on the host. Its usage is:

CALL "C$REGEXP" USING AREGEXP-GET-LEVEL GIVING return-value

The value of return-value can be one of the following (defined in acucobol.def):

AREGEXP-NONE | 0 | regular expression processing is not available
AREGEXP-WINDOWS | 1 | Windows regular expressions supported
AREGEXP-POSIX | 2 | POSIX regular expressions supported

AREGEXP-COMPILE (op-code 2)

This operation compiles a regular expression to ensure that it has a valid form, returning a handle to the compiled regular expression or NULL if there is an error. Its usage is:

CALL "C$REGEXP" USING AREGEXP-COMPILE, reg-expr, flags
                GIVING return-value

reg-expr

Must be a NULL-terminated regular expression. It must be NULL-terminated because trailing spaces are allowed in regular.

flags

(Optional) is the sum of one or more of the following values (defined in acucobol.def):
AREGEXP_COMPILE_IGNORECASE | 1 | Ignore case when matching patterns. (Windows or UNIX)
AREGEXP_COMPILE_BASIC | 2 | Change the type of regular expression from extended to basic. (UNIX only) (For an explanation of extended and basic, see the POSIX 1003.2 standard.)
AREGEXP_COMPILE_NO_SPECIAL | 4 | Treat all characters as ordinary characters with no special meaning. (UNIX only)
AREGEXP_COMPILE_NO_SUB | 8 | When matching, determine only if there is a match, without returning the offsets of the match. (UNIX only)
AREGEXP_COMPILE_NEWLINE | 16 | Treat newlines as special (end-of-line marker) characters. (UNIX only)
AREGEXP_COMPILE_NO_REGEXP | 32 | Treat reg-expr as text, not as a regular expression.

return-value contains a handle to the compiled expression, or NULL if an error occurred.

AREGEXP-MATCH (op-code 3)

This operation applies a regular expression to a string, and returns a handle. The match-start parameter must be initialized before AREGEXP-MATCH is attempted, as it specifies the start position in which matching should begin. To see if there is a match you need to check match-start; If it is 0, there is no match. Its usage is:

CALL "C$REGEXP" USING AREGEXP-MATCH,
   reg-expr-handle, string, length, match-start, match-end
   GIVING return-value
reg-expr-handle | is a handle to a regular expression returned by AREGEXP-COMPILE.
string | is the string to test for a match.
length | is the length of string. If length is zero, the size of string is used.
match-start | as an input parameter, match-start indicates where the matching should begin. As an output parameter, it returns the index of the start of the pattern that matched.
match-end | returns one byte beyond the pattern that matched. To test the string for additional matches, start a new AREGEXP-MATCH after setting match-start to match-end.
return-value | contains a handle to the match or zero if no match is found or an error occurred.

AREGEXP-RELEASE-MATCH (op-code 4)

This operation frees memory that is allocated when AREGEXP-MATCH is called. Return-value is not used. Its usage is:

CALL "C$REGEXP" USING AREGEXP-RELEASE-MATCH match-handle
match-handle is a handle to a match returned by AREGEXP-MATCH.

AREGEXP-RELEASE (op-code 5)

This operation frees the memory allocated when AREGEXP-COMPILE is called. Return-value is not used. Its usage is:

CALL "C$REGEXP" USING AREGEXP-RELEASE reg-expr-handle
reg-expr-handle is a handle to a regular expression returned by AREGEXP-COMPILE.

AREGEXP-NUMGROUPS (op-code 6)

This operation returns the number of substrings that matched any subgroups in the regular expression. Its usage is:

CALL "C$REGEXP" USING AREGEXP-NUMGROUPS match-handle
                GIVING return-value
match-handle | is a handle returned by AREGEXP-MATCH.
return-value | returns the number of matches.

Depending on the construction of a regular expression, it is possible for a subgroup of the regular expression to match multiple substrings. This operation reports the number of instances found in the last AREGEXP-MATCH operation. For more information, rules, and examples, see the POSIX 1003.2 documentation or one of the many books available on regular expressions.

AREGEXP-GETMATCH (op-code 7)

This operation returns a set of indices into a string passed to AREGEXP-MATCH that match the subexpression of the regular expression. Its usage is:

CALL "C$REGEXP"
    USING AREGEXP-GETMATCH, match-handle, group,
    idx-start, idx-end
    GIVING return-value

The parameters are defined as follows:

match-handle | is a handle returned by AREGEXP-MATCH.
group | is a number between 1 and the value returned by AREGEXP-NUMGROUPS.
idx-start | returns an index into the beginning of the string that matches the subexpression of the regular expression.
idx-end | returns an index to the end of the string that matches the subexpression of the regular expression.
return-value | returns 1 if the operation succeeds, and zero if there is an error.

AREGEXP-LAST-ERROR (op-code 20)

This operation returns the last error code returned by a call to C$REGEXP. Its usage is:

CALL "C$REGEXP" USING AREGEXP-LAST-ERROR GIVING return-value

The error value is returned in return-value. The possible error values (described in acucobol.def) have the following meanings:

AREGEXP-ERROR-NO-ERROR | 0 | No error
AREGEXP-ERROR-NO-MEMORY | 1 | Insufficient memory to handle the request
AREGEXP-ERROR-BRACE-EXPECTED | 2 | A closing brace is missing
AREGEXP-ERROR-PAREN-EXPECTED | 3 | A closing parenthesis is missing
AREGEXP-ERROR-BRACKET-EXPECTED | 4 | A closing bracket is missing
AREGEXP-ERROR-UNEXPECTED | 5 | An unknown error occurred
AREGEXP-ERROR-EMPTY-RANGE | 6 | An empty range was given
AREGEXP-ERROR-INVALID-GROUP | 7 | The group provided was invalid
AREGEXP-ERROR-INVALID-RANGE | 8 | An invalid range was given
AREGEXP-ERROR-EMPTY-REPEATOP | 9 | A repeat operator was given on an empty subexpression
AREGEXP-ERROR-INVALID-INPUT | 10 | The input was invalid
AREGEXP-ERROR-INVALID-HANDLE | 11 | The handle is not a regular expression handle or a match handle
AREGEXP-ERROR-INVALID-ARGUMENT | 12 | One of the arguments given is invalid
AREGEXP-ERROR-INVALID-CALL-SEQ | 13 | The order of C$REGEXP operations is an invalid sequence.
AREGEXP-ERROR-NO-MATCH | 14 | The regular expression did not find a match in the given string.
Note: If the error code returned does not match a value in the list, it may be that the value is coming from the host's regular expression library. See the documentation for the host's regular expression library.

Compatibility Issues

None.
Parent topic: ACUCOBOL-GT Library Routines


C$RERR

Returns extended file status information for the last I/O statement.

Syntax:

CALL "C$RERR" USING extend-stat [text-message, status-type]

Parameters:

extend-stat
PIC X(5) or larger
text-message
PIC X(n)
Note: This optional parameter is ignored in this COBOL system.
status-type
PIC 9
Note: This optional parameter is ignored in this COBOL system.

On Exit:

extend-stat
Returns the extended file status caused by the last file I/O

Comments:

The statuses returned are listed in the file status table found in Appendix E of the ACUCOBOL-GT product documentation. If the file status (first two characters) is 30, the remainder of the information is the operating system's status code explaining what caused the error. On some systems, the operating system requires more than two digits for its status codes. That is why the C$RERR routine may be passed a field that is larger than four characters.

Whenever an error 30 occurs, the operating system's status value is returned in this extended field. The number returned is a left-justified decimal value. If the receiving field is too small, the right-most digits are returned. If the receiving field is too large, the excess characters are filled with spaces.

Parent topic: ACUCOBOL-GT Library Routines
Related reference
C$RERRNAME


C$RERRNAME

Returns the name of the last file used in an I/O statement.

Use it in conjunction with C$RERR to diagnose file errors.

Syntax:

CALL "C$RERRNAME" USING file-name

Parameters:

file-name
PIC X(n)

On Exit:

file-name
The name of the last file that was involved in an I/O statement.
Note: The filename is the one specified in the ASSIGN clause.
Parent topic: ACUCOBOL-GT Library Routines
Related reference
C$RERR


C$RUN

ACUCOBOL-GT for Windows supports an alternate method for running other programs. This is through the library routine C$RUN. This library routine works identically to the SYSTEM library routine, except that the calling program does not wait for the called program to finish. Instead, both programs run in parallel.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$RUN"
    USING COMMAND-LINE,
    GIVING STATUS-VAL

Parameters

COMMAND-LINE PIC X(n) | Contains the operating system command line to execute.
STATUS-VAL Any numeric data item | Returns 0 if successful or -1 if not.

Description

C$RUN sets STATUS-VAL to -1 if the call fails or to 0 if it succeeds.

C$RUN is implemented only under the Windows version of ACUCOBOL-GT. On other systems, it always returns 1.

C$RUN is supported in Thin Client environments. To execute a program on the display host in a thin client environment, add the prefix @[DISPLAY]: to the name of any program that resides on the client machine. For example:

C$RUN "@[DISPLAY]:C:\notepad myfile.txt

Compatibility Issues

"@[DISPLAY]" is not supported in this COBOL system.
Parent topic: ACUCOBOL-GT Library Routines


C$SLEEP

This routine causes the program to pause in a machine efficient fashion.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$SLEEP"
    USING NUM-SEC

Parameter

NUM-SEC Numeric or alphanumeric parameter The number of seconds to sleep.

This parameter is a an unsigned fixed-point numeric parameter, or an alphanumeric data item containing an unsigned fixed-point number.

Description

This routine can be used to impose slight delays in loops. For example, you might want to introduce a delay in a loop that is waiting for a record to become unlocked. Calling C$SLEEP will allow the machine to execute other programs while you wait.

The C$SLEEP routine is passed one argument. This argument is the number of seconds you want to pause. For example, to pause the program for five and a half seconds, you could use either of the following:

CALL "C$SLEEP" USING 5.5
CALL "C$SLEEP" USING "5.5"

The amount of time paused is only approximate. Depending on the granularity of the system clock and the current load on the machine, the time paused may actually be shorter or longer than the time requested. Typically, the time paused will be within one second or one-tenth of a second of the amount requested (unless the machine is excessively loaded).

If the sleep duration is zero, this function does nothing. If the sleep duration is signed, this function generates a runtime error.

Compatibility Issues

None
Parent topic: ACUCOBOL-GT Library Routines


C$SYSTEM

This routine combines the functionality of "SYSTEM" and "C$RUN". It allows you to run other programs from inside a COBOL application in a variety of ways.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

C$SYSTEM adds the following capabilities to the original capabilities of SYSTEM and C$RUN:

  1. Uniform programming interface for all options
  2. Asynchronous operation (C$RUN) added to UNIX hosts
  3. Windows hosts can specify minimized, maximized, or hidden windows
  4. Smart shell selection for Windows

Usage

CALL "C$SYSTEM"
    USING CMD-LINE, FLAGS
    GIVING EXIT-STATUS

C$SYSTEM can be used to execute a program in Thin Client environments. To execute a program on the display host in a thin client environment, add the prefix "@[DISPLAY]:" to the name of any program that resides on the client machine. For Example:

C$SYSTEM "@[DISPLAY]:C:\notepad myfile.txt"

Parameters

CMD-LINE PIC X(n) | Contains the operating system command line to execute.
FLAGS Numeric unsigned (optional) | Supplies the options for the operation. If omitted, acts as if "0" was specified.
EXIT-STATUS Any numeric data item | Returns the called program's exit status.

Flags

The FLAGS field specifies various options about how the command should be run. Determine the value of the FLAGS field by adding together the values corresponding to the following options:

CSYS-ASYNC (value 1) This option causes the command to run independently of the COBOL program. After starting the command, the COBOL program continues. When this option is specified, EXIT-STATUS returns undefined results. When this flag is not used, the COBOL program waits for the command executed to finish before the COBOL program continues. CSYS-ASYNC is functional only on Windows and UNIX systems.
Note: On UNIX machines, specifying CSYS-ASYNC with a program that tries to do input or output to the terminal is not supported.
CSYS-NO-IO (value 2) For character-based systems, the runtime normally sets the terminal to its default state prior to running the command, and resets it back to the state needed by the runtime when the command finishes. This option ensures that the called application runs correctly if the application uses the screen. However, CSYS-NO-IO also causes the runtime to "forget" the contents of the screen. This happens because the command executed may display information on the screen that ACUCOBOL-GT is not aware of. Because of this, windows created after a call to C$SYSTEM may not correctly restore the screen contents when these windows are closed. You can avoid this problem by re-initializing the screen after C$SYSTEM returns. You can do this by erasing the screen or closing a floating or pop-up window that covers the entire screen (the window must have been created by the C$SYSTEM call).

If the command to be executed will not perform any screen I/O, then you can request that C$SYSTEM retain ACUCOBOL-GT's memory of the original screen by using the CSYS-NO-IO option. This will avoid the problem described above. The option has no effect in Windows, where the command runs in its own window.

CSYS-MAXIMIZED (value 4) | This option causes the command to run in a maximized window. This is functional only when you are running under Windows.
CSYS-MINIMIZED (value 8) | This option causes the command to run in a minimized window. In addition, the COBOL program remains the active program retaining the keyboard focus and keeping the active appearance. This is functional only when you are running under Windows.
CSYS-COMPATIBILITY (value 16) | This option causes the command to run in a window that is compatible with the way the SYSTEM library routine works. Use this option if you want to modify a call to SYSTEM and change this call to C$SYSTEM. There are very few differences between the default behavior of SYSTEM and C$SYSTEM, so this option is rarely needed. The only known difference involves the Microsoft Word application. If you use SYSTEM to start Microsoft Word, it always starts in a "normal" sized window, that is, the window size suggested by Windows. If you use C$SYSTEM to start Microsoft Word (with no FLAGS specified), then Word adopts the last window size it previously used. Supplying a flag of CSYS-COMPATIBILITY causes C$SYSTEM to behave the same as SYSTEM. Of course, if you prefer the behavior of C$SYSTEM, the flag should not be used. In comparison with SYSTEM, C$SYSTEM generally conforms more closely to the way Windows itself launches programs. The CSYS-COMPATIBILITY flag is recommended only if you change a SYSTEM call to a C$SYSTEM call and you observe a difference you do not like.
CSYS-HIDDEN (value 32) | This option runs the command in a hidden window. Note that some applications, particularly those that routinely interact with the user, may get confused if you "hide" the command. This works well, however, for executing system tasks that do not have a user interface, such as executing a batch file that renames a series of files. This option is functional only when you are running under Windows.
CSYS-SHELL (value 64) When this option is specified, C$SYSTEM uses the host's command-line processor (the host's shell) to execute the command. Otherwise, the command may be executed without the command-line processor. This option affects only Windows (non-Windows versions always use the host's shell). For Windows applications that create their own windows, you should avoid using the shell the application will not receive the initial window size request specified in FLAGS. For ".COM" and ".BAT" programs, and other built-in shell commands such as COPY and DIR, you must use the shell or the command may not execute.

The effect of this option is to prefix the command with the value of the COMSPEC environment variable and "/C". Under Windows, this will usually result in a prefix like "C:\COMMAND.COM /C".

CSYS-DESKTOP (value 128) This option is for applications running in the thin client environment. It indicates that the application wants to run the command on the client system rather than the application server. When the command executes, unless the CSYS-ASYNC option is also specified, the thin client appears to "hang" while the application waits for the command's termination status. This behavior can be avoided with the CSYS-ASYNC flag. The CSYS-ASYNC flag causes the command to be run asynchronously.

If CSYS-DESKTOP is specified but the calling program is not running under thin client, the flag is ignored and the command is run on the same machine as the calling application.

CSYS-INHERIT-HANDLES (value 256) This option causes the new process to inherit each inheritable handle owned by the calling process. This includes stdin, stdout, stderr, and other file handles that the calling process has open.

Note that because the called process inherits many open files, it is vulnerable to running out of file handles.

This option is needed when an Alternate Terminal Manager runtime calls C$SYSTEM to run a batch program which in turn calls another Alternate Terminal Manager runtime. Without this option, the called program will not display any output to the screen.

Comments

The C$SYSTEM routine submits CMD-LINE to the host operating system as if it were a command keyed in from the terminal. The maximum allowable length for the command line is 1024 bytes.

Note: Applications that run under Windows but that do not create their own windows should use the CSYS-SHELL flag to execute .COM, .BAT, and built-in shell commands such as COPY and DIR.

You should specify only one window size flag (CSYS-MAXIMIZED, CSYS-MINIMIZED, CSYS-COMPATIBILITY, or CSYS-HIDDEN). In the absence of any window size flag, the command runs in a normal window whose size is determined by the operating system. Windows programs can set their own window size. This will override the window size suggested by FLAGS. Essentially, the value of FLAGS is only a suggestion to the application.

Options that are not meaningful to the host system are ignored. Meaningful options in the same FLAGS setting are still applied.

The status of a call to C$SYSTEM is placed in EXIT-STATUS. This is usually the exit status of the executed program, or is -1 if C$SYSTEM failed. Note that Windows will return 1 from commands that are built into COMMAND.COM because COMMAND.COM does not return an exit status for built-in functions.

Compatibility Issues

  • CYS-NO-IO (value 2) is ignored
  • The following op-codes are Windows only: CSYS-MAXIMIZED (value 4), CSYS-MINIMIZED (value 8), CSYS-HIDDEN (value 32), CSYS-SHELL (value 64), CSYS-INHERIT-HANDLES (value 256).
  • CSYS-INHERIT-HANDLES (value 256) only has an effect when the program is run from the command prompt.
  • Thin client functionality is not supported in this COBOL system; therefore:
    • "@[DISPLAY]" syntax is not supported.
    • Flag CSYS-DESKTOP (value 128) is not supported.
Parent topic: ACUCOBOL-GT Library Routines


C$TOUPPER and C$TOLOWER

These routines translate text to upper- or lower-case.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "C$TOUPPER"
    USING TEXT-DATA, VALUE TEXT-LEN

CALL "C$TOLOWER"
    USING TEXT-DATA, VALUE TEXT-LEN

Parameters

TEXT-DATA PIC X(n) | Contains the data to translate to upper- or lower-case.
TEXT-LEN USAGE UNSIGNED-INT, or a numeric literal | Contains the number of characters to translate.

Description

C$TOUPPER translates the first TEXT-LEN characters in TEXT-DATA to upper-case. C$TOLOWER translates them to lower-case. No size checking is done on TEXT-DATA, so you must ensure that TEXT-LEN has a valid value. VALUE must be included in the calling statement. If it is omitted, the program will very likely encounter memory errors. These routines only translate characters with a numeric value of 0-128. Anything above that (such as é, with a value of 130) must be mapped to its associated upper- or lower-case character using the configuration variable UPPER-LOWER-MAP.

Compatibility Issues

  • Calls to these routines immediately call the Micro Focus library routines CBL_TOUPPER and CBL_TOLOWER.
Parent topic: ACUCOBOL-GT Library Routines
Related concepts
CBL TOLOWER
CBL TOUPPER


I$IO

The I$IO routine provides an interface to the file handler.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

An operation code and some number of additional parameters (depending on the operation called) are passed to the routine. The return code is set automatically after the call. The external variable F-ERRNO is set according to any errors found. F-ERRNO may not be reset on entry to I$IO, and should be checked only if I$IO returns an error condition.

Usage

CALL "I$IO"
    USING OP-CODE, parameters

Parameters

  • OP-CODE Numeric parameter

    Specifies the file handling routine to be performed. This table shows which operation corresponds to each operation code. The operations are detailed in the description below:

    Code | Operation
    1 | OPEN-FUNCTION
    2 | CLOSE-FUNCTION
    3 | MAKE-FUNCTION
    4 | INFO-FUNCTION
    5 | READ-FUNCTION
    6 | NEXT-FUNCTION
    7 | PREVIOUS-FUNCTION
    8 | START-FUNCTION
    9 | WRITE-FUNCTION
    10 | REWRITE-FUNCTION
    11 | DELETE-FUNCTION
    12 | UNLOCK-FUNCTION
    13 | REMOVE-FUNCTION
    14 | SYNC-FUNCTION
    15 | EXECUTE-FUNCTION
    16 | BEGIN-FUNCTION
    17 | COMMIT-FUNCTION
    18 | ROLLBACK-FUNCTION
    19 | RECOVER-FUNCTION
    21 | IN-TRANSACTION-FUNCTION
  • parameters vary depending on the op-code chosen

    The remaining parameters vary depending on the operation selected. They provide information and hold results for the operations specified. All parameters are passed by reference. Parameters may be omitted from those operations that do not require them.

Description

All parameters passed to I$IO are passed by reference. This applies even to parameters that are integer values in the corresponding file handling routines. All numeric parameters should be passed to I$IO as SIGNED-SHORT values. The I$IO routine provides any necessary addressing conversions. Note that a parameter must be in the correct format for its type. Parameters that are PIC X must be terminated by a LOW-VALUES character.

Except for the MAKE function, I$IO will automatically terminate any PIC X parameters with a LOW-VALUES byte for you. Also, you do not have to specify SYNC for level 01 or level 77 parameters because they are automatically synchronized by ACUCOBOL-GT.

The file filesys.def is a COBOL COPY file that contains many useful definitions for use with I$IO. It contains definitions for the I$IO codes along with the F-ERRNO error values and many useful pre-declared variables that are of the proper type and usage.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name.

Note: The runtime configuration variable FILE_PREFIX is ignored by the I$IO routine.

Compatibility Issues

  • filesys.def is not supplied in this COBOL system.
  • The FILENAME_SPACES configuration variable is not supported in this COBOL system.
Parent topic: ACUCOBOL-GT Library Routines


M$ALLOC (Dynamic Memory Routine)

Allocates a new area of dynamic memory.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$ALLOC"
    USING ITEM-SIZE, MEM-ADDRESS

Parameters

ITEM-SIZE Numeric parameter | This indicates the number of bytes to allocate. This must be greater than zero.
MEM-ADDRESS USAGE POINTER | This holds the return value, either the address of the allocated memory or NULL if the allocation fails.

Comments

The maximum amount of memory you may allocate in one call depends on the host machine, but is at least 65260 bytes for all machines (providing that much memory is available). M$ALLOC adds some overhead to each memory block allocated. This ranges between 4 and 16 bytes depending on the machine architecture. Also, each operating system will typically add its own overhead. The debugger's U command reports the amount of memory you have currently allocated via M$ALLOC. The overhead added by M$ALLOC is included in the total shown, but the operating system's overhead is not. Memory allocated by M$ALLOC is initialized to binary zeros (LOW VALUES).

If you try to allocate more memory than the environment can give you, M$ALLOC will return NULL, and no memory will be allocated.

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


M$COPY (Dynamic Memory Routine)

Copies a region of memory from one location to another.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$COPY"
    USING DEST-PTR, SRC-PTR, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER | Contains the address of the first byte of the destination region.
SRC-PTR USAGE POINTER | Contains the address of the first byte of the source region.
NUM-BYTES Numeric parameter | Indicates the size of the memory region to be copied.

Description

This routine copies NUM-BYTES from the address contained in SRC-PTR to the address contained in DEST-PTR. Note that this routine is relatively dangerous to use. No boundary checking is performed to ensure that the address range is valid, so memory access violations may result if you pass it incorrect data.

This routine is functionally similar to the C$MEMCOPY routine except that parameters are passed by reference instead of by value. For example, you can copy 10 bytes to DEST-PTR from the memory address contained in SRC-PTR with:

     CALL "M$COPY"
        USING DEST-PTR, SRC-PTR, 10

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


M$FILL (Dynamic Memory Routine)

Sets a region of memory to a constant value.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$FILL"
    USING DEST-PTR, BYTE-VALUE, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER | Contains the address of the first byte of the region to be filled.
BYTE-VALUE Alpha-numeric parameter | Contains the value with which to fill the memory region.
NUM-BYTES Numeric parameter | Indicates the size of the memory region.

Description

This routine fills NUM-BYTES with BYTE-VALUE starting at address DEST-PTR. The parameters are passed BY REFERENCE. This routine does not do any boundary checking to make sure that the address range is valid.

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


M$FREE (Dynamic Memory Routine)

Frees a previously allocated piece of memory.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$FREE"
    USING MEM-ADDRESS

Parameter

MEM-ADDRESS USAGE POINTER Must point to a memory area previously allocated by M$ALLOC.

Comments

Use M$FREE to release a memory block allocated by M$ALLOC. This memory is returned to the pool of memory available for use by the runtime. On most operating systems, this memory is still associated with the runtime's process, so it cannot be used by any other processes. On a few systems, this memory may be made available to the operating system for re-use by other processes.

It is an error to attempt to use a block of memory once it has been freed. It is also an error to free a block of memory more than once or to free a memory address that has never been allocated. Any of these errors can lead to memory access violations. The runtime attempts to detect these errors and avoid them, but it cannot detect all such errors.

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


M$GET (Dynamic Memory Routine)

Retrieves data from an allocated memory block.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$GET"
    USING MEM-ADDRESS, DATA-ITEM, DATA-SIZE, DATA-OFFSET

Parameters

MEM-ADDRESS USAGE POINTER | Must point to a memory area previously allocated by M$ALLOC.
DATA-ITEM Any data item | Data from the memory block will be stored in this item.
DATA-SIZE Numeric parameter (optional) | The number of bytes to move from the memory block. If omitted, then the number of bytes is set to the size of the memory block (excluding overhead bytes).
DATA-OFFSET Numeric parameter (optional) | The location within the memory block from which to start the move. The first location is position 1. If omitted, this value defaults to 1.

Description

This routine retrieves data from the memory block at MEM-ADDRESS and stores it in DATA-ITEM. Regardless of the value of DATA-SIZE, no bytes are copied from past the end of the memory block. Note that the size of DATA-ITEM is not checked.

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


M$PUT (Dynamic Memory Routine)

Stores data in an allocated memory block.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Usage

CALL "M$PUT"
    USING MEM-ADDRESS, DATA-ITEM, DATA-SIZE, DATA-OFFSET

Parameters

MEM-ADDRESS USAGE POINTER | Must point to a memory area previously allocated by M$ALLOC.
DATA-ITEM Any data item | This is the data that will be stored in the memory block.
DATA-SIZE Numeric parameter (optional) | The number of bytes to move to the memory block. If omitted, then the number of bytes is set to the size of the memory block (excluding overhead bytes).
DATA-OFFSET PIC 9(n), USAGE DISPLAY or COMP-4 (optional) | The location within the memory block from which to start the move. The first location is position 1. If omitted, this value defaults to 1.

Description

This routine copies DATA-ITEM into the memory pointed to by MEM-ADDRESS for DATA-SIZE bytes. Regardless of the value of DATA-SIZE, no bytes are copied that exceed the size of the memory block at MEM-ADDRESS.

Compatibility Issues

None.

Parent topic: ACUCOBOL-GT Library Routines


RENAME

Renames a file.

Syntax:

CALL "RENAME"
   USING source-file, dest-file, [status,] [file-type]

Parameters:

source-file
PIC X(n)
dest-file
PIC X(n)
status
Any numeric type
file-type
PIC X

On Entry:

source-file
The path name of the file to be copied
dest-file
The path name of the destination file
file-type
The file organization of the source file. It must be one of: S (for sequential), R (for relative) or I (for indexed).

This defaults to S if not specified.

On Exit:

status
Returns zero if the rename is successful, or non-zero if not.

Comments:

To obtain an extended file status code for this operation, define status as comp xx comp-x and follow the example in Extended File Status Codes.

Parent topic: ACUCOBOL-GT Library Routines


WIN$VERSION

Returns version information for Windows and Windows NT host platforms.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

This routine provides more information about the system than is returned by the ACCEPT FROM SYSTEM-INFO statement.

Usage

CALL "WIN$VERSION"
    USING WINVERSION-DATA

Parameters

WINVERSION-DATA Group item as follows:
01  WINVERSION-DATA.
    03  WIN-MAJOR-VERSION     PIC X COMP-X.
    03  WIN-MINOR-VERSION     PIC X COMP-X.
    03  WIN-PLATFORM          PIC X COMP-X.
        88  PLATFORM-WIN-31   VALUE 1.
        88  PLATFORM-WIN-95   VALUE 2.
        88  PLATFORM-WIN-9X   VALUE 2.
        88  PLATFORM-WIN-NT   VALUE 3.
    03  WIN-WORDSIZE          PIC X COMP-X.
        88  WIN-WORDSIZE-16   VALUE 1.
        88  WIN-WORDSIZE-32   VALUE 2.
        88  WIN-WORDSIZE-64   VALUE 3.
    03  WIN-BUILDNUMBER                 PIC X(4) COMP-X.
    03  WIN-CSDVERSION                  PIC X(128).
    03  WIN-SERVICEPACK-MAJOR           PIC X COMP-X.
    03  WIN-SERVICEPACK-MINOR           PIC X COMP-X.
    03  WIN-SUITEMASK                   PIC X(4) COMP-X.
    03  WIN-PRODUCTTYPE                 PIC X COMP-X.
        88 WIN-NT-WORKSTATION           VALUE 1.
        88 WIN-NT-DOMAIN-CONTROLLER     VALUE 2.
        88 WIN-NT-SERVER                VALUE 3.

WINVERSION-DATA is found in the COPY library winvers.def.

Comments

Upon return from WIN$VERSION, all of the data elements contained in WINVERSION-DATA are filled in. If you call WIN$VERSION and the host machine is not a Windows or Windows NT system, the fields are set to zero.

The WINVERSION-DATA fields have the following meaning:

  • WIN-MAJOR-VERSION - The major version number reported by Windows. See table below for possible values.
  • WIN-MINOR-VERSION - The minor version number reported by Windows. See table below for possible values.
Windows Version | WIN-MAJOR-VERSION | WIN-MINOR-VERSION | Other
Windows XP | 5 | 1 | Not applicable.
Windows XP Professional x64 Edition | 5 | 2 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION) && (SYSTEM_INFO.wProcessorArchitecture==PROCESSOR_ARCHITECTURE_AMD64
Windows Vista | 6 | 0 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows 7 | 6 | 1 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows Server 2012 | 6 | 2 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows Server 2008 R2 | 6 | 1 | OSVERSIONINFOEX.wProductType != VER_NT_WORKSTATION
Windows Server 2008 | 6 | 0 | OSVERSIONINFOEX.wProductType != VER_NT_WORKSTATION
Windows Server 2003 R2 | 5 | 2 | GetSystemMetrics(SM_SERVERR2) != 0
Windows Home Sever | 5 | 2 | OSVERSIONINFOEX.wSuiteMask & VER_SUITE_WH_SERVER
Windows Server 2003 | 5 | 2 | GetSystemMetrics(SM_SERVERR2) == 0
  • WIN-PLATFORM - Provides a general description of the host system. If the host is Windows NT/Windows 2000, the value is set to PLATFORM-WIN-NT. If the host is Windows 98, the value is set to PLATFORM-WIN-9X.
  • WIN-WORDSIZE - This item is set to WIN-WORDSIZE-32 for a 32-bit operating system, and WIN-WORDSIZE-64 for a 64-bit operating system.
  • WIN-BUILDNUMBER - Identifies the build number of the operating system.
  • WIN-CSDVERSION - Indicates the latest Service Pack installed on the system. If no Service Pack has been installed the string is empty.
  • WIN-SERVICEPACK-MAJOR - Indicates the major version number of the latest Service Pack installed on the system. If no Service Pack has been installed the value is 0.
  • WIN-SERVICEPACK-MINOR - Indicates the minor version number of the latest Service Pack installed on the system. If no Service Pack has been installed the value is 0.
  • WIN-SUITEMASK - This is a bit mask that identifies the product suites available on the system. Refer to the operating system documentation for a list of possible values.
  • WIN-PRODUCTTTYPE - Identifies additional information about the system.

Compatibility Issues

The copybook winvers.def is not available in this COBOL system.

The following fields are not supported in this COBOL system:

  • WIN-BUILDNUMBER
  • WIN-CSDVERSION
  • WIN-SERVICEPACK-MAJOR
  • WIN-SERVICEPACK-MINOR
  • WIN-SUITEMASK
  • WIN-PRODUCTTTYPE

These fields will return spaces or zeroes, as appropriate.

Parent topic: ACUCOBOL-GT Library Routines


ACUCOBOL-GT Windowing Syntax

Your COBOL system provides some support for ACUCOBOL-GT windowing syntax that enables you to draw lines and boxes on the terminal screen, and create virtual terminal windows on a physical terminal. All ACCEPT and DISPLAY statements then act within the current window (except for ACCEPT format 1, 2, or 3 statements, DISPLAY format 1 statements, and DISPLAY WINDOW/LINE/BOX statements). The syntax also enables underlying displays to be kept and restored.
Note: This functionality is supported in native COBOL only.
  • Windowing Syntax Summary
  • Enabling Windowing Support
  • Windowing Support Syntax
  • Windowing Restrictions
  • ACUCOBOL-GT Windowing Error Messages
  • Windowing Supplementary Information
Parent topic: Compatibility with ACUCOBOL-GT


Windowing Syntax Summary

Your COBOL system includes the following syntax to support windowing:

  • BEFORE TIME phrase in ACCEPT statement

    Format 5 of the ACCEPT statement has the BEFORE TIME phrase, which enables you to specify a timeout period. If the user does not enter data during this period, the statement is terminated automatically.

  • DISPLAY WINDOW

    DISPLAY WINDOW creates a terminal window (a rectangular region of the screen) and makes it the current window. This is like a virtual terminal, in which screen positions used by subsequent ACCEPT/DISPLAY statements are relative to the top left corner of the window.

  • DISPLAY LINE

    DISPLAY LINE enables you to draw lines on the terminal (real or virtual). The best mode available on the terminal is used automatically. Used with the DISPLAY BOX statement, the DISPLAY LINE statement enables you to draw forms on the terminal.

  • DISPLAY BOX

    DISPLAY BOX enables you to draw boxes on the terminal. The best mode available on the terminal is used automatically. Used with the DISPLAY LINE statement, the DISPLAY BOX statement enables you to draw forms on the terminal.

  • CLOSE WINDOW

    CLOSE WINDOW removes a window. If you specify the window as being a POP-UP window, the underlying display can be restored.

Parent topic: ACUCOBOL-GT Windowing Syntax


Enabling Windowing Support

In order to use the windowing syntax, you must use the PREPROCESS"window1" Compiler directive.

You can specify this directive in one of two ways.

  • In your source file, use the following line:
    $SET preprocess"window1"
  • From the command line, include the PREPROCESS"window1" directive:
    cob -C preprocess=window1 prog.cbl

The PREPROCESS "window1" directive must be the last Compiler directive apart from NOERRQ, AUTOCLOSE or COLOR. If an error is encountered, the Compiler asks if you wish to continue, and waits for your response. In order to disable this function, you must specify the NOERRQ directive after PREPROCESS"window1".

Parent topic: ACUCOBOL-GT Windowing Syntax
Related information
To set project-wide build properties and compiler directives
Setting Directives Outside the IDE


Windowing Support Syntax

The following sections give details of the windowing syntax enabled by the PREPROCESS"window1" directive.

  • The ACCEPT Statement
    Format 5 of the ACCEPT statement as described in your Language Reference includes the phrase
  • The CLOSE WINDOW Statement
    The CLOSE WINDOW statement closes the current video terminal window.
  • The DISPLAY Statement
    This section explains COBOL windowing, which provides three additional formats of the DISPLAY verb for creating windows and drawing lines and boxes. Other formats are described in your Language Reference.
Parent topic: ACUCOBOL-GT Windowing Syntax


The ACCEPT Statement

BEFORE TIME time-out

General Rules:

  1. The BEFORE TIME phrase allows you to automatically terminate an ACCEPT statement after a certain amount of time has passed. The timeout value specifies the time to wait in hundredths of a second. For example, "BEFORE TIME 500" specifies a timer value of 5 seconds.
  2. The user must enter data to the ACCEPT statement before the timer elapses. As soon as the user starts entering data, the timer is canceled and the user may take as much time as desired to complete the entry. If the user does not enter any data before the timer elapses, then the ACCEPT statement terminates.
Parent topic: Windowing Support Syntax


The CLOSE WINDOW Statement

Format:

CLOSE WINDOW window-save-area

Syntax Rules:

  1. window-save-area must be an elementary data item described with a PIC X(10) clause. It must have been the object of a POP-UP AREA phrase in a DISPLAY WINDOW statement.

General Rules:

  1. The CLOSE WINDOW statement is used to remove popup windows created by the POP-UP AREA option of the DISPLAY WINDOW statement.
  2. window-save-area must have been the object of a POP-UP phrase of a DISPLAY WINDOW statement that has been executed in this run unit. Furthermore, since that execution, it must not have been the object of a CLOSE WINDOW statement, nor can it have been modified by any other statement. Violation of these rules causes undefined results.
  3. The CLOSE WINDOW statement restores the contents of the terminal screen that was in the active window when the corresponding DISPLAY WINDOW statement executed. In other words, the window that was created by that DISPLAY WINDOW statement is removed from the screen and replaced by the contents of the screen which were under that popup window.
  4. The window that was active when the corresponding DISPLAY WINDOW statement executed becomes the active window, thereby becoming the top window and overlaying any other windows that might be present.

Comments:

The current window is selected by closing windows identified by their respective window-save-area data items, as in the following example:

If five popup windows are created, a, b, c, d and e in that order:

  • If d is closed, c becomes current.
  • If b is then closed, a becomes current.
  • If e is subsequently closed, c becomes current again.
Parent topic: Windowing Support Syntax


DISPLAY (ACUCOBOL-GT Windowing Syntax )

The DISPLAY Statement

Format: for Format 1

DISPLAY WINDOW syntax diagram

Format: for Format 2

DISPLAY LINE syntax diagram

Format: for Format 3

DISPLAY BOX syntax diagram

Syntax Rules:

  1. line-num is a numeric literal or data item that specifies the line position on the terminal screen. It must be a non-negative integer.
  2. col-num is a numeric literal or data item that specifies the column position on the terminal screen. It must be a non-negative integer.
  3. length is a numeric literal or data item that specifies the window-width, line-width or box-width in character positions. It must be a non-negative integer.
  4. height is a numeric literal or data item that specifies the number of lines in the window, line or box. It must be a non-negative integer.
  5. title is a non-numeric literal or alphanumeric data item.
  6. save-area is an elementary data item described by a PIC X(10) clause.
  7. COLUMN and COL are equivalent.
  8. REVERSE and REVERSED and REVERSE-VIDEO are equivalent.
  9. The COLOR phrase is supported only when the preprocessor directive COLOR is used. This adds support for existing non-Micro Focus syntax.
  10. Exactly one of the SIZE or LINES phrases must be specified for a Format 2 DISPLAY statement.
  11. identifier-1, identifier-2, integer-1 and integer-2 must take a value in the range 0 through 7 as follows:
    0 | black
    1 | blue
    2 | green
    3 | cyan
    4 | red
    5 | magenta
    6 | brown or yellow
    7 | white
  12. identifier-3 and integer-3 must take a value which is obtained by adding together the appropriate values from the following:
    Color | Foreground | Background
    Black | 1 | 32
    Blue | 2 | 64
    Green | 3 | 96
    Cyan | 4 | 128
    Red | 5 | 160
    Magenta | 6 | 192
    Brown | 7 | 224
    White | 8 | 25
    Note:

    The foreground color values for use with the COLOR phrase are different from the standard Micro Focus color values for FOREGROUND-COLOR, BACKGROUND-COLOR and so on.

    In addition you can specify the following video attributes with the following values:

    Reverse video | 1024
    Low intensity | 2048
    High intensity | 4096
    Underline | 8192
    Blink | 16384
  13. If a COLOR phrase is present at the same time as FOREGROUND-COLOR and/or BACKGROUND-COLOR, then the colors defined in the COLOR phrase are ignored, but any non-color attributes are actioned (where appropriate).

General Rules: for All Formats

  1. The LINE and COLUMN phrases must specify a line or column on the physical screen.
  2. On color systems, both the settings given in COLOR or FOREGROUND-COLOR and BACKGROUND-COLOR and other attribute settings (for example blink) are used. On monochrome systems, all color information supplied is ignored, and only other attribute settings used.
  3. Not all combinations of attributes are supported on all systems. For example, on a standard DOS PC, set to monochrome mode, REVERSE and UNDERLINE are mutually exclusive - only one of these attributes is actioned.

General Rules: for DISPLAY WINDOW statement Format 1 (DISPLAY WINDOW)

  1. The DISPLAY WINDOW statement creates and makes current a terminal window. The terminal window is a rectangular region of your screen. Any ACCEPT or DISPLAY statements (apart from another DISPLAY WINDOW/LINE/BOX or a Format 1, 2 or 3 ACCEPT or Format 1 DISPLAY as described in your Language Reference) affect only the current window. Furthermore, line and column numbers for all ACCEPT and DISPLAY statements (apart from another DISPLAY WINDOW/LINE/BOX or a Format 1, 2 or 3 ACCEPT or Format 1 DISPLAY as described in your Language Reference) are computed from the upper left-hand corner of the current window. That is, the current window defines a virtual terminal screen which occupies some area of your physical screen.
  2. The initial window is set to the entire screen.
  3. The only way to change the current window is with another DISPLAY WINDOW statement or with the CLOSE WINDOW statement.
  4. The LINE NUMBER phrase sets the top line of the window. Line number one refers to the top line of the screen. Line numbers are relative to the screen, and not to the current window.
  5. If the LINE NUMBER phrase is not specified, is specified as zero, or is off the physical screen, the top line of the screen is used.
  6. The COLUMN NUMBER phrase sets the left-most column of the window. Column number one refers to the left side of the screen. Column numbers are relative to the screen, and not to the current window.
  7. If the COLUMN NUMBER phrase is not specified, is specified as zero, or is off the physical screen, column number one is used.
  8. The SIZE phrase sets the number of columns the window contains. If this causes the window to extend past the right edge of the screen, the window's width extends off the screen.
  9. If the SIZE phrase is not specified or is specified as zero, the window extends to the right edge of the screen.
  10. The LINES phrase sets the number of rows the window contains. If this causes the window to extend past the bottom of the screen, the window extends off the screen.
  11. If the LINES phrase is not specified or is specified as zero, the window extends to the bottom edge of the screen.
  12. When the ERASE phrase is specified, the window is cleared immediately after it is created. Otherwise the window's contents are not changed. Clearing a window sets it to spaces.
  13. The BOXED phrase causes a box to be drawn around the new window. The box is drawn outside the window. Any portions of the box that lie off the screen are not drawn.
  14. The terminal's line drawing set is used to draw the box. If the terminal does not have a line drawing set, equivalent ASCII characters are used. If the POP-UP phrase is also specified, the box overlays any other boxes on the screen. If this phrase is not specified, the box drawn is attached to any other boxes it intersects. When a boxed non-popup window intersects a boxed popup window, if the popup window is created first, when it is closed the points where the two window boxes intersected is not redrawn. That is, intersection characters remain even though there is no longer an intersection.
  15. The ERASE phrase is implied by the BOXED phrase.
  16. The REVERSED phrase exchanges the window's foreground and background colors. This affects every ACCEPT and DISPLAY statement in the new window.
  17. The REVERSED phrase implies the ERASE phrase. This usually causes the entire window to be set to reverse video spaces when it is initially created.
  18. The SHADOW phrase causes the window to appear to float over the screen giving a three-dimensional effect.
  19. If the color value for either foreground or background is set to 0 in the COLOR field, then the corresponding color of the default system attribute is used.
  20. The TITLE phrase causes the title to be printed in the window's border. This has its effect only if the BOXED phrase is also specified.
  21. Titles can be placed in one of six positions in the border region: top left, top center, top right, bottom left, bottom center and bottom right. If TOP or BOTTOM is not specified, TOP is used. If LEFT, CENTERED or RIGHT is not specified, CENTERED is used.
  22. The NO SCROLL phrase is treated as documentary only; the Windows preprocessor displays a message confirming this.
  23. The NO WRAP phrase is treated as documentary only; the Windows preprocessor displays a message confirming this.
  24. The POP-UP AREA phrase causes your COBOL system to save system information prior to creating the new window. This information can be used by the CLOSE WINDOW statement to subsequently remove the new window and restore the underlying windows. This gives a popup window.
  25. The save-area data item is filled in with system information. This data item must not be subsequently modified in any way or results are undefined. It can be referenced in a CLOSE WINDOW statement to restore an earlier window to the screen and re-establish that window as the current window.

General Rules: for DISPLAY LINE statement Format 2 (DISPLAY LINE)

  1. The DISPLAY LINE statement enables you to draw vertical and horizontal lines in a machine- and terminal-independent manner. The lines are drawn using the best mode available on the display device. Used together with the DISPLAY BOX statement, this provides the ability to draw forms on your screen. The DISPLAY LINE statement does not affect the positioning of full screen ACCEPT and DISPLAY statements.
  2. Lines are drawn so that when they intersect other lines on the screen, the appropriate intersection character is used. This is done so that when the end of a line intersects another line, the appropriate corner or three-way intersection is used.
  3. If the SIZE phrase is specified, the line drawn is horizontal. The value of length gives the size of the line in screen columns. If the LINES phrase is used instead, the line drawn is a vertical line and height describes the number of screen rows to use.
  4. Lines never wrap around or cause scrolling. If the LINES or SIZE phrase would cause the line to leave the current window, the line is truncated at the edge of the window. If LINES or SIZE is zero, no line is drawn.
  5. The value of line-num gives the starting row of the line. The value of col-num gives the starting column. Lines are always drawn to the right or downward as appropriate. line-num and col-num must specify a position that is contained in the current window.
  6. If the LINE NUMBER or COLUMN NUMBER phrases specify a point outside the physical screen, that is, line-num = 0 or 24 (or your screen's maximum), or col-num = 0 or > 80, no line is drawn.
  7. The TITLE phrase has effect only when drawing horizontal lines. When specified, title-string is printed in part of the line.
  8. The title can be printed near the right side, near the left side or in the center of the line depending on the RIGHT, LEFT or CENTERED phrase specified. If none is specified, CENTERED is used.
  9. The REVERSE phrase exchanges the foreground and background color of the line.

General Rules: for DISPLAY BOX statement Format 3 (DISPLAY BOX)

  1. The DISPLAY BOX statement enables you to draw a box in a machine- and terminal-independent manner. The boxes are drawn using the best mode available on the display device. If the lines used in drawing a box intersect other lines already present on the screen, the appropriate intersection characters are used. The DISPLAY BOX statement does not affect the positioning of full screen ACCEPT and DISPLAY statements.
  2. The location of the box is specified by providing the location of the upper-left corner. The size of the box is specified by providing a height and a width.
  3. If the LINE NUMBER or COLUMN NUMBER phrases specify a point outside the physical screen no box is drawn.
  4. The SIZE phrase specifies the width of the box. The LINES phrase specifies its height. If the SIZE phrase is not specified, or zero, or such that the box would extend beyond the physical screen or the edge of the window, the box extends to the right edge of the current window. If the LINES phrase is not specified, or zero, or such that the box would extend beyond the physical screen, the box extends to the bottom of the current window.
  5. The REVERSE phrase operates in the same manner as it does for a DISPLAY WINDOW statement.
  6. The TITLE phrase operates in the same manner as it does for the DISPLAY WINDOW statement.
Parent topic: Windowing Support Syntax
Related reference
The DISPLAY Statement - SRs and GRs


Windowing Restrictions

  • This feature is not guaranteed to be intermediate code compatible, so you might need to recompile your source code between product releases.
  • When using the ACCEPT or DISPLAY statements with this windowing syntax, you must include the AT LINE NUMBER syntax (see your Language Reference) or items do not appear in the windows.
  • You should not use cobprintf() with these DISPLAY statements.
  • You should not use COPY REPLACING or REPLACE statements.
  • The windowing syntax is supported only for fixed format COBOL source.
  • The following reserved words have been introduced by the windowing syntax, so you should avoid specifying them as user-defined words:

    BOX BOXED CENTERED COLOR (if COLOR directive used) POP-UP SCROLLSHADOW WINDOW WRAP

  • You should use only the ACCEPT and DISPLAY statements documented in your Language Reference with this windowing syntax.
  • When using windowing syntax, the ANS85 Compiler directive is implied. You must not unset this directive either explicitly or implicitly.
  • Alphanumeric literals must not be continued over the end of any line which includes a windowing statement.
  • Some syntax errors, for example, spelling PROCEDURE DIVISION incorrectly, are flagged, but might result in spurious error messages for following source lines.
  • Windowing syntax errors are serious errors, but are flagged in the form:
     xnnn-P*******
  • The -P cob flag should not be used with windowing syntax . You should instead use "-C list".
  • Column 73 must not be used within source programs which use windowing syntax, as this column is always treated as being set to a space character.
  • The Compiler asks if you wish to continue after any error occurs. You can disable this function by using the NOERRQ directive. You should not, however, use the NOERRQ directive when compiling from within the Development Environment.

    If no error occurred, or if an error occurred but you replied "no" to the question "do you wish to continue", the Compiler returns a zero error return code.

  • Each of the following statements must appear on a line by itself:

    DISPLAY WINDOW DISPLAY BOX DISPLAY LINE CLOSE WINDOW EXIT PROGRAM

  • The windowing subsystem is initialized automatically upon encountering the first windowing statement.
  • If an application switches between using windowing syntax and other types of Accept/Display syntax, it must close down the windowing system completely before starting to use other types of Accept/Display syntax; otherwise the ACCEPT and DISPLAY statements may not have the desired effects.

    You can create a subroutine to explicitly close the windowing system by compiling the following subprogram:

    $set preprocess "window1" autoclose
procedure division
para-1.
exit program.

    You then call this subprogram before switching to another type of Accept/Display syntax. The AUTOCLOSE preprocessor directive causes the EXIT PROGRAM statement to close down the windowing system before exiting the subprogram. The windowing subsystem is reinitialized upon encountering another windowing statement. Each time the windowing subsystem initializes, the background screen and contents are redisplayed.

  • When a window is active, or has been active in the run unit, use of the DISPLAY SPACES UPON CRT statement clears the window to spaces but leaves attributes unchanged.
Parent topic: ACUCOBOL-GT Windowing Syntax


ACUCOBOL-GT Windowing Error Messages

The following errors might be encountered during preprocessing.

Unexpected numeric literal
Unexpected alphanumeric literal
Unsupported keyword or noise word
Unrecognized clause to DISPLAY WINDOW
Unrecognized clause to DISPLAY LINE
Unrecognized clause to DISPLAY BOX
Unrecognized clause to ACCEPT FROM SCREEN
This keyword has already been used
This keyword conflicts with another
This reserved word is used incorrectly
Wrongly formed or ordered clause with keyword
Error during preprocessing - no further details
Unknown COPY file specified
WINDOW1 preprocessor cannot handle free format
SCROLL/WRAP clause processed as comment
The edit/compile/animate loop returns to an incorrect line within your source program after returning an error.
Parent topic: ACUCOBOL-GT Windowing Syntax
Related information
ACUCOBOL


Windowing Supplementary Information

When the first windowing statement in your program is encountered the screen is redisplayed. This is expected behavior and does not affect your program in any way.

Parent topic: ACUCOBOL-GT Windowing Syntax


Compatibility with DG Interactive COBOL

  • Introduction
    Introduction to compatibility with DG Interactive COBOL.
  • Compatibility Directives
    This COBOL system provides compatibility with Data General Interactive COBOL rev 1.30 and 1.30 through the use of a Compiler directive.
  • Compatibility with DG Interactive COBOL
    Converting your DG Interactive COBOL application so that it is suitable for input to this COBOL system.
Parent topic: Compatibility


Introduction

Visual COBOL provides compatibility with the DG Interactive COBOL programming language.

This enables you to migrate programs from this environment.

You can:
  • Convert applications written in DG Interactive COBOL to the Micro Focus COBOL language, and enhance them using the advanced language and development features offered by Visual COBOL.
  • Retain the use of the selected COBOL on some machine environments while moving to Visual COBOL on others. You might want to maintain a common set of source programs which are suitable for all environments.
Note: Any error messages and numbers that are returned when you compile your program in Visual COBOL or when you execute the resulting code are different in the two environments. This should present no problems, but is something of which you should be aware.
Parent topic: Compatibility with DG Interactive COBOL


Compatibility Directives

This COBOL system provides compatibility with Data General Interactive COBOL rev 1.30 and 1.30 through the use of a Compiler directive.
  • DG
    Changes the behavior of certain features to be compatible with Data General Interactive COBOL rev 1.30.
Parent topic: Compatibility with DG Interactive COBOL
Related reference
Reserved Words Table
Data General Interactive COBOL V1.3 Syntax Support


DG

Changes the behavior of certain features to be compatible with Data General Interactive COBOL rev 1.30.

Syntax:

>>-.---.-.----.--DG------------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NODG
Phase: | Syntax check
$SET: | Initial

Comments:

See your Language Reference for details of syntax support for Data General Interactive COBOL rev 1.30.

Parent topic: Compatibility Directives
Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related concepts
The DG Directive
Related reference
Data General Interactive COBOL V1.3 Syntax Support


Compatibility with DG Interactive COBOL

Converting your DG Interactive COBOL application so that it is suitable for input to this COBOL system.
  • Overview
  • Compatibility with DG Interactive COBOL Source
  • Reformatting a DG COBOL Source File
Parent topic: Compatibility with DG Interactive COBOL


Overview

You need to take the steps listed below in order to convert your DG Interactive COBOL application so that it is suitable for input to this COBOL system:

  1. Reformat the DG Interactive COBOL source programs
  2. Submit your DG Interactive COBOL source programs to this COBOL system
  • DG Interactive COBOL Source Programs
  • Enhancing your Converted Application
Parent topic: Compatibility with DG Interactive COBOL


DG Interactive COBOL Source Programs

Your COBOL system includes certain language enhancements that enable you to submit programs written in DG Interactive COBOL directly to this COBOL system. Provided your DG Interactive COBOL source programs conform to the standard file format for your operating system, there should be no problems in submitting most of these programs to this COBOL system. You should ensure that the expansion of tab characters in literals is not significant to the operation of your program before it is processed by this COBOL system.

However, if your program is written in DG CRT format, you must reformat the source file before you submit it to your COBOL system.

You must set the DG directive when you submit your source code to this COBOL system if your source code contains DG Interactive COBOL features that are not supported in the standard Micro Focus COBOL language, or if user-defined words are reserved words in the Micro Focus COBOL language. Refer to the Language Reference help for a list of Micro Focus COBOL reserved words, and for a full definition of all the syntax supported in the standard Micro Focus COBOL language. See the chapter Data General Interactive COBOL V1.3 Syntax Support in your Language Reference for details of syntax support for Data General Interactive COBOL V1.3. This manual also contains a full list of the additional DG Interactive COBOL features enabled in the Micro Focus COBOL language when you set the DG system directive. See the chapter Compatibility Directives for details of the DG directive.

Parent topic: Overview
Related reference
Reserved Words Table
Data General Interactive COBOL V1.3 Syntax Support


Enhancing your Converted Application

Once you have successfully submitted your DG Interactive COBOL source programs to this COBOL system, you can enhance it to take advantage of any of the advanced features offered to you by this COBOL development system.

Parent topic: Overview


Compatibility with DG Interactive COBOL Source

All of the DG Interactive COBOL syntax as defined in revision 02, dated August 1984, of The Data General Interactive COBOL Programmer's Reference Manual is supported by your COBOL system, with the exception of:

UNDELETE RECORD

Support is not guaranteed for any of the syntax of the DG Interactive COBOL language that is not documented in the above revision of The Data General Interactive COBOL Programmer's Reference Manual.

If your DG Interactive COBOL programs perform any screen-handling operations you must run the Adiscf facility and select the DG screen-handling configuration option before you run them. See your Character User Interfaces book for full details of this utility.

  • The DG Directive
  • Reserved Words
  • DG International Character Set
  • DG File Status and other Exception Values
  • Calls
  • Linkage Section Access
  • Arithmetic of Group Level Items
  • Run-time Switches
  • Program Identification and Data-names
Parent topic: Compatibility with DG Interactive COBOL


The DG Directive

Your DG Interactive COBOL source programs can contain:

  • DG Interactive COBOL syntax which is not found in the standard Micro Focus COBOL language
  • DG Interactive COBOL syntax which is found in Micro Focus COBOL, but has a different interpretation at run time.

In either case you must specify the DG Compiler directive when you submit such source programs to this COBOL system.

The chapter Data General Interactive COBOL V1.3 Syntax Support in your Language Reference contains the DG syntax which is not found in the standard Micro Focus COBOL language

Features which are syntactically the same as Micro Focus COBOL features but have different behavior at run time, are described in the following sections of this chapter. Unless you set the DG directive at the time the object code is produced, this syntax behaves in the standard Micro Focus COBOL manner, as documented in the Language Reference. You do not need to amend DG Interactive COBOL source programs which contain these features, but if you try to submit them to this COBOL system without setting the DG directive they might not behave as you expect.

Parent topic: Compatibility with DG Interactive COBOL Source
Related reference
DG
Data General Interactive COBOL V1.3 Syntax Support


Reserved Words

The Language Reference lists all the words that are reserved in your version of the COBOL system. If you have included any of these words as user-defined words in your DG Interactive COBOL program, we advise that you use the REMOVE directive to disable the relevant reserved words in this COBOL system.

Parent topic: Compatibility with DG Interactive COBOL Source
Related reference
Reserved Words Table
REMOVE


DG International Character Set

The environment dependent feature of DG Interactive COBOL which allows you to use an extra 69 characters in addition to the 96 characters in the ASCII set, is not supported by this COBOL system.

Parent topic: Compatibility with DG Interactive COBOL Source


DG File Status and other Exception Values

DG Interactive COBOL file status and other exception values are not supported by this COBOL system, as they are environment dependent. If you wish to maintain a common source for programs used by both systems, you should maintain COPY-files of the file status values returned by each system.

Parent topic: Compatibility with DG Interactive COBOL Source


Calls

DG Interactive COBOL system calls are environment dependent, and are not supported by this COBOL system. Under this COBOL system you cannot pass a switch in a CALL statement; you should use Linkage Section items to communicate between programs.

Parent topic: Compatibility with DG Interactive COBOL Source


Linkage Section Access

DG Interactive COBOL allows a main program to access its Linkage Section but this facility is not supported by this COBOL system. We recommend that if a program is to be accessed as a main program, you transfer the Linkage Section entries into Working-Storage.

Parent topic: Compatibility with DG Interactive COBOL Source


Arithmetic of Group Level Items

DG Interactive COBOL allows arithmetic of group level items, but this is not supported by this COBOL system. We recommend that you redefine such fields into numeric items to overcome this problem.

Parent topic: Compatibility with DG Interactive COBOL Source


Run-time Switches

DG Interactive COBOL run-time switches A to Z, inclusive, are mapped onto switches 1 to 26, respectively, in this COBOL system.

Parent topic: Compatibility with DG Interactive COBOL Source


Program Identification and Data-names

The DG Interactive COBOL system allows the Program-ID and a data item in that program to have the same name. However, this COBOL system does not allow the use of the same name for the Program-ID and a data item in a program, requiring instead that each should be unique. We recommend that you either change the program-name in the Program-ID and in any programs that call this program, or change the name of the data item.

Parent topic: Compatibility with DG Interactive COBOL Source


Reformatting a DG COBOL Source File

Source programs written in DG Interactive COBOL CRT format cannot be accepted by this COBOL system unless you first amend the format, using a formatter or editor. This must alter the margins in these programs, and split any lines in them containing more than 72 characters, into lines of 72 characters or fewer.

  • Reformatting Rules
Parent topic: Compatibility with DG Interactive COBOL


Reformatting Rules

You should amend your source program according to the following rules:

  1. If the character in column 1 is an indicator (*/-), append six spaces to the beginning of a line.
  2. If the character in column 1 is any non-space character not mentioned in rule 1, append seven space characters to the beginning of the line.
  3. If area A (columns 1 to 4 inclusive) contains all spaces, append seven additional space characters to the beginning of the line. However, if the entire line contains spaces, it outputs a single 72 character line containing spaces.
  4. If a line is too long to fit onto a single 72 character line, break it onto subsequent lines, up to a maximum of three. Where possible, these breaks occur at a space character to preserve the program's readability.
  5. If a line is expanded beyond 132 characters, truncate the line to 132 characters. This prevents any pseudo-comment areas from being included in the program source.
Parent topic: Reformatting a DG COBOL Source File


Compatibility with RM/COBOL

Visual COBOL provides compatibility with the RM/COBOL programming language, enabling you to migrate RM/COBOL programs to this COBOL environment.

You can:
  • Convert applications written in RM/COBOL to the Micro Focus COBOL language, and enhance them using the advanced language and development features offered by Visual COBOL.
  • Retain the use of the selected COBOL on some machine environments while moving to Visual COBOL on others. You might want to maintain a common set of source programs which are suitable for all environments.

A COBOL dialect setting (DIALECT"RM") provides most of the compatibility required to migrate; however, it should only be used in a native COBOL environment.

Note: Any error messages and numbers that are returned when you compile your program in Visual COBOL or when you execute the resulting code are different in the two environments. This should present no problems, but is something of which you should be aware.
  • Converting RM/COBOL Applications
    This COBOL system supports certain extensions that enable you to submit source programs written in the RM/COBOL language.
  • RM/COBOL Library Routines
    A list of RM/COBOL standard library routines supported in this COBOL system.
  • RM/COBOL File Handling
    This COBOL system enables you to access the data files used in your RM/COBOL applications.
  • RM/Panels
    RM/COBOL's RM/Panels is a graphical user interface that uses panels (screens) and controls defined in a Panel Library file. You can configure your existing RM/Panels syntax to be compatible with Micro Focus COBOL.
  • Compatibility with XML Extensions
    Compatibility issues when using XML Extensions in Visual COBOL when producing native code.
Parent topic: Compatibility
Related reference
RM/COBOL Syntax Support


Converting RM/COBOL Applications

By default, this COBOL system already supports much of the RM/COBOL syntax and behavior. Additional RM/COBOL-specific syntax that has been added for compatibility is documented in the section RM/COBOL Syntax Support in your Language Reference.

You can also enable additional RM/COBOL behavior using certain Compiler directives. Using these directives when you submit your RM/COBOL source programs to this COBOL system ensures that most of the programs are accepted the first time they are submitted; however, they are only intended for use in a native COBOL environment. There are still certain compatibility issues between the two COBOL systems, which are detailed, with any possible work-arounds, in the RM/COBOL Conversion Issues section.

  • Configuring Your Application for
    As an RM/COBOL user, you can modernize your applications for Visual COBOL by using the DIALECT"RM" Compiler directive, which enables compilation and run-time behavior highly compatible with RM/COBOL.
  • Compiler Directives for RM/COBOL Compatibility
    You can set a number of Compiler directives in your RM/COBOL source programs that enable a program to emulate RM/COBOL behavior.
  • Compiling RM/COBOL Programs Without DIALECT"RM"
    It is possible to compile your RM/COBOL programs without the DIALECT"RM" Compiler directive, but there are a number of compatibility problems that may arise without the directive being set.
  • RM/COBOL Data Types
    Behavior of RM/COBOL data types can be emulated in Visual COBOL by using Compiler directives.
  • RM/COBOL Conversion Issues
    Information on issues you might encounter when running RM/COBOL source programs in this COBOL system.
Parent topic: Compatibility with RM/COBOL
Related reference
RM/COBOL Syntax Support


Configuring Your Application for

As an RM/COBOL user, you can modernize your applications for Visual COBOL by using the DIALECT"RM" Compiler directive, which enables compilation and run-time behavior highly compatible with RM/COBOL.
Note: If your RM/COBOL source code uses RM/Panels syntax, refer to the RM/Panels Conversion Example for your IDE instead.

This tutorial demonstrates migrating your RM/COBOL source code to Visual COBOL using the IDE. It takes you through creating a new project, setting the Compiler directive, and then importing the RM/COBOL source into the project.

There are three additional files included in your Visual COBOL installation that are intended for RM/COBOL modernizations: ADISCTRL, cobkeymp, and a .dir (directives) file. The first two files configure the Micro Focus enhanced ACCEPT/DISPLAY syntax run-time support module (Adis) for interactive programs. The directives file contains REMOVE directives, which un-reserves many Micro Focus COBOL reserved words that may be used within your RM/COBOL programs. This tutorial also takes you through utilizing those in your application.

  1. Appendices
Parent topic: Converting RM/COBOL Applications


Appendices

  • Appendix A - RM/COBOL Source File
    If you do not want to test the conversion process using one of your RM/COBOL source files, you can use the source listed in this appendix.
  • Appendix B - ADISCTRL Settings for RM2VCOB
    The complete settings of the Adis configuration intended for use with RM/COBOL modernizations.
  • Appendix C - Adis Key Mappings for RM2VCOB
    The complete settings of the Adis key mappings intended for use with RM/COBOL modernizations.
  • Appendix D - Adis Key Function Mapping for RM2VCOB
    The complete settings of the Adis key functions intended for use with RM/COBOL modernizations.
Parent topic: Configuring Your Application for


Appendix A - RM/COBOL Source File

If you do not want to test the conversion process using one of your RM/COBOL source files, you can use the source listed in this appendix.
       identification division.
       program-id. RmProgram1.

       environment division.
       configuration section.

       data division.
        Working-Storage section.
        01 singleChar  PIC X.

       PROCEDURE DIVISION.

       Main.

           DISPLAY "Simple Display Tests in RM" ERASE
           DISPLAY "ABC FCOLOR BLUE" AT 0203 CONTROL "FCOLOR=BLUE"
           DISPLAY "ABC BCOLOR CYAN" AT 0304
                     CONTROL "BCOLOR=CYAN"
           DISPLAY "ABC FCOLOR MAGENTA" AT 0405
                     CONTROL "FCOLOR=MAGENTA"
           DISPLAY "ABC FCOLOR GREEN"    AT 0506
                     CONTROL "FCOLOR=GREEN"
           DISPLAY "ABC BCOLOR BROWN"   AT 0607
                     CONTROL "BCOLOR=BROWN"
           DISPLAY "Any Key to Continue..." AT 1002
                     CONTROL "BCOLOR=BLACK, FCOLOR=WHITE"

           ACCEPT singleChar at 1025.
           goback.
       end program RmProgram1.
Parent topic: Appendices
Related tasks
Appendix B - ADISCTRL Settings for RM2VCOB
Appendix C - Adis Key Mappings for RM2VCOB
Appendix D - Adis Key Function Mapping for RM2VCOB


Appendix B - ADISCTRL Settings for RM2VCOB

This is a complete list of the Adis options and settings for the RM2VCOB configuration used in the tutorial. The settings in bold are the ones that differ from the default Adis configuration.

Setting no. | Description | Value
1 | User function keys enable/disable - function keys are enabled. | 2
2 | Range of data keys accepted. | 3
3 | Prompt character. | [_] x'5F'
4 | Prompt character used in PIC G fields. | [ iQ] x'8151'
5 | Pre-display of fields before an accept - enables the predisplay of numeric-edited fields with numeric editing when the cursor moves into them. No other predisplay occurs. | 1
6 | Accept in a SECURE field. | 2
7 | Auto-skip between fields. | 2
8 | Termination of an accept - keying or retyping a data character in the last available character position of an ACCEPT operation, provided auto-skip between fields is enabled. | 3
9 | Validation control if accept is terminated by a function key. | 1
10 | End of field effects - the cursor stays at the end of field, and overtyping is rejected. | 2
11 | Filed overflow buffers enable/disable - displaced data is not saved in an overflow buffer. | 2
12 | Auto-restore during backspace in replacement editing mode - RM backspace. Deleted characters are removed and characters to the right are shifted left, same as when in insertion editing mode. | 3
13 | Accepts into numeric edited fields - input is accepted as for alphanumeric fields and is normalized to remove illegal characters on exit from the field. | 1
14 | Accepts in non-edited numeric fields - all non-edited numeric fields are treated as alphanumeric fields. | 3
15 | Enable/disable auto-clear or pre-clear - pre-clear mode: the field is cleared to spaces or zeroes. Pressing the Undo key does not restore the original contents of the field. | 4
16 | Force field to be updated if it is not altered - the data item is always updated even if the field is not altered. This setting has effect only if the field is numeric or numeric-edited and the original data item did not contain any numeric data, or if the field is right justified and the original contents of the field were not. | 2
17 | Remembering where the end of field is - the enhanced ACCEPT/DISPLAY syntax notes the position of the last character entered into a field during an ACCEPT operation. This setting provides justification of RM-style numeric fields. | 2
18 | Rm style numeric data entry - the RM/COBOL 85 style of numeric and numeric-edited data entry is enabled. | 3
19 | Restricting maximum field size to one line. | 1
20 | Control of cursor positioning after an accept - the cursor is left at its current position. | 2
21 | Control of whether UPDATE clauses perform implicit CONVERTs - the CONVERT clause is implied. | 2
22 | Selection of the function key list to be used. | 1
23 | Select of the action for COLUMN + n clauses - a 'COLUMN + 1' clause leaves a one-character gap between the two fields. | 2
24 | Selection of the default action if no color specified. | 1
25 | Control of whether cursor left/right keys can exit a field - the keys cannot exit a field. | 2
26 | left justification of free-format edited numerics - the field is left-justified, provided RM-numeric handling is switched off. This is controlled by ACCEPT/DISPLAY option 18. | 2
27 | Validation control on FULL/REQUIRED fields. | 1
28 | Control of Adis keys defined as function keys. | 2
29 | Control of the read screen option for an accept. | 1
30 | Control of whether protected fields are skipped. | 1
31 | Control of special action for Kanji modifier characters. | 1
32 | Selection of the units used when calculating timeout. | 1
33 | Control of whether timeout is reset on each keystroke - the timer is reset each time a character is entered. | 2
34 | Control of line feed before first DISPLAY on a screen. | 2
Parent topic: Appendices
Related tasks
Appendix A - RM/COBOL Source File
Appendix C - Adis Key Mappings for RM2VCOB
Appendix D - Adis Key Function Mapping for RM2VCOB


Appendix C - Adis Key Mappings for RM2VCOB

This is a complete list of the Adis key mappings for the RM2VCOB configuration used in the tutorial. The settings in bold are the ones that differ from the default Adis configuration.

No. | Function | Setting | No. | Function | Setting
0 | Terminate accept | Enabled | 14 | Backspace character | Enabled
1 | Terminate program | Enabled | 15 | Retype character | Disabled
2 | Carriage Return | Enabled | 16 | Insert single character | Disabled
3 | Cursor left | Enabled | 17 | Delete character | Enabled
4 | Cursor right | Enabled | 18 | Restore character | Disabled
5 | Cursor up | Enabled | 19 | Clear to end of field | Enabled
6 | Cursor down | Enabled | 20 | Clear field | Enabled
7 | Move to start of screen | Enabled | 21 | Clear to end of screen | Disabled
8 | Move to next tab stop | Enabled | 22 | Clear screen | Disabled
9 | Move to previous tab stop | Enabled | 23 | Set insert mode | Enabled
10 | Move to end of screen | Enabled | 24 | Set replace mode | Enabled
11 | Move to next field | Enabled | 25 | Reset field (Undo) | Disabled
12 | Move to previous field | Enabled | 26 | Move to start of field | Function
13 | Change case of character | Disabled | 27 | Move to mouse position | Disabled
Parent topic: Appendices
Related tasks
Appendix A - RM/COBOL Source File
Appendix B - ADISCTRL Settings for RM2VCOB
Appendix D - Adis Key Function Mapping for RM2VCOB


Appendix D - Adis Key Function Mapping for RM2VCOB

This is a complete list of the Adis key function mappings for the RM2VCOB configuration used in the tutorial. The settings in bold are the ones that differ from the default Adis configuration.

Function |  |  |  | Mapped to
Number | Name | Validate | Align | Number | Name
0 | Terminate accept | - | - | 255 | Undefined
1 | Terminate program | Y | N | 1 | Terminate program
2 | Carriage Return | Y | N | 0 | Terminate accept
3 | Cursor left | Y | N | 3 | Cursor left
4 | Cursor right | Y | N | 4 | Cursor right
5 | Cursor up | Y | N | 12 | Move to previous field
6 | Cursor down | Y | N | 11 | Move to next field
7 | Move to start of screen | Y | N | 7 | Move to start of screen
8 | Move to next tab stop | Y | N | 11 | Move to next field
9 | Move to previous tab stop | Y | N | 12 | Move to previous field
10 | Move to end of screen | Y | N | 10 | Move to end of screen
11 | Move to next field | - | - | 255 | Undefined
12 | Move to previous field | - | - | 255 | Undefined
13 | Change case of character | Y | N | 13 | Change case of character
14 | Backspace character | Y | N | 14 | Backspace character
15 | Retype character | Y | N | 15 | Retype character
16 | Insert single character | Y | N | 16 | Insert single character
17 | Delete character | Y | N | 17 | Delete character
18 | Restore character | Y | N | 18 | Restore character
19 | Clear to end of field | Y | N | 19 | Clear to end of field
20 | Clear field | Y | N | 55 | RM Clear Field
21 | Clear to end of screen | Y | N | 21 | Clear to end of screen
22 | Clear screen | Y | N | 22 | Clear screen
23 | Set insert mode | Y | N | 58 | Insert toggle
24 | Set replace mode | - | - | 255 | Undefined
25 | Reset field (Undo) | Y | N | 21 | Reset field (Undo)
26 | Move to start of field | Y | N | 26 | Move to start of field
27 | Move to mouse position | Y | N | 27 | Move to mouse position
Parent topic: Appendices
Related tasks
Appendix A - RM/COBOL Source File
Appendix B - ADISCTRL Settings for RM2VCOB
Appendix C - Adis Key Mappings for RM2VCOB


Compiler Directives for RM/COBOL Compatibility

You can set a number of Compiler directives in your RM/COBOL source programs that enable a program to emulate RM/COBOL behavior.

The main directive that sets the majority of RM/COBOL behavior is DIALECT"RM". Setting this directive automatically sets additional Compiler directives; see the topic RM Dialect Settings for full details of the directives set.

Previously, compatibility was achieved by compiling with the RM Compiler directive. The newer DIALECT"RM" directive sets and extends the compatibility given by RM, but you should only use it in a native COBOL environment. It is recommended that you use DIALECT"RM" for all new migrations from RM/COBOL to native MF COBOL, unless you normally set the ANSI switch when you submit your RM/COBOL source programs to the RM/COBOL system. If you do, set the RM"ANSI" directive when you compile your programs.

We also recommend that you set the NOMF directive when you submit your RM/COBOL source programs to this COBOL system. This ensures that only those words which are treated as reserved words under the ANSI '74 COBOL standard are regarded as reserved words by this COBOL system.

Setting the NORM directive disables the syntax enabled when the RM directive was set, and automatically resets the additional Compiler directives and syntax that RM originally set.

The final states of the additional directives set when you use the NORM directive are not necessarily the same as their initial default states.

Parent topic: Converting RM/COBOL Applications
Related reference
DIALECT
RM DIALECT setting
RM


Compiling RM/COBOL Programs Without DIALECT"RM"

The following issues may occur when compiling your RM/COBOL programs without the DIALECT"RM" Compiler directive:

  • Directive settings will revert to Visual COBOL defaults. Refer to the MF Dialect setting and RM Dialect setting sections of the DIALECT Compiler directive topic for the differences; you can explicitly set any of the directives to override the default set by the MF dialect. You can also use the SETTINGS directive to output a list of directive settings in effect.
  • RM/COBOL reserved words that are not reserved in Visual COBOL will not be treated as reserved words: this can cause errors such as "verb expected" or other such syntax errors. In some cases, you can use an ADDRSV directive to resolve this. In other cases, you must modify the syntax in the source to avoid the RM/COBOL reserved word; often there is an equivalent syntax in Visual COBOL that uses a different reserved word.
  • The CRT STATUS value for ACCEPT statements will not be converted to RM/COBOL numeric values. The CRT STATUS for an ACCEPT statement will be the Visual COBOL three-byte value, where each byte has a different meaning - the second byte frequently contains the RM/COBOL numeric value.
  • In the ASSIGN clause of a file control entry, the device types SORT-WORK, CARD-PUNCH, CARD-READER, CASSETTE and DISC will not be recognized as valid device types. You must modify the program to specify an equivalent device type supported by Visual COBOL. Device types with a prefix of PRINTER and an additional character, for example, PRINTER1 or PRINTER?, will not be treated as printers; you must shorten the device type to just PRINTER.
  • The ASSIGN clause of a file control entry will not assume DYNAMIC when the ASSIGN directive specifies "EXTERNAL". You must either override the ASSIGN"EXTERNAL" directive, or modify the program to specify DYNAMIC explicitly in the ASSIGN clause.
  • Indexed file key-name references will not be implicitly qualified by the file-name in the file control entry or READ/START statements. Ambiguous reference errors may occur if the qualification is required for uniqueness of reference when the same key-name has been used for more than one file; in this case you must explicitly add the qualification OF file-name to the reference for Visual COBOL.
  • The CODE-SET clause is not allowed in the file control entry; it can be specified only in the file description entry. Move any CODE-SET clause specified in the file control entry to the file description entry.
  • COLLATING SEQUENCE clauses may be repeated in the file control entry for an indexed file and the lexically last such clause specified takes precedence.
  • Constant-expressions are fully supported for RM/COBOL syntax in Visual COBOL, but Visual COBOL computes a 64-bit result, as opposed to RM/COBOL's 32-bit result. This is only a problem if the expression or any sub-expression result exceeds 32 bits in the RM/COBOL program; in this case, Visual COBOL will likely have a different result.
  • Empty groups are not allowed. Modify the program to eliminate empty groups by including a subordinate data item in the group or by removing the group itself. A warning message COBCH0217 or COBCH0256 is produced for an empty group when DIALECT"RM" is set, but a severe error COBCH0217 or COBCH0256 is produced when DIALECT"RM" is not set.
  • Byte-storage mode is used for binary data items, which can result in different length file records and redefinition issues. The IBMCOMP directive will restore word-storage mode, but will also cause length specifiers in data description entries to increase to the word size that is at least as large as the length specifier, which is different from RM/COBOL behavior. A better solution might be to provide length specifiers for all binary data item usage clauses.
  • RECORD DELIMITER IS LINE-SEQUENTIAL or BINARY-SEQUENTIAL does not set the record delimiting technique for the file. Specify the record delimiting technique in the ORGANIZATION clause or with the SEQUENTIAL directive.
  • VALUE OF LABEL data-name-1 is allowed, but treated as documentary. If data-name-1 is not defined in the program, it will not be defined implicitly. In this case, any references to data-name-1 will receive compilation errors, and you must change the program to remove the reference or define data-name-1 explicitly.
  • Records are not variable length unless records of different length are explicitly defined, even if there are OCCURS DEPENDING ON clauses in the record description entry, or the RECORD CONTAINS clause specifies a range of record sizes. You can use the RECMODE"RMCOBOL" directive to cause records to be variable length in the same manner as RM/COBOL.
  • Implicit data-name definition for forward references does not take place without the DIALECT"RM" directive, except for the external file-name data-name specified in the ASSIGN clause or the FILE-ID clause. Implicit definition relates to forward references in clauses such as CRT STATUS, CURSOR, FILE STATUS and others. The explicit definition must be added to the program to avoid compilation errors. Even with DIALECT"RM" set, an E-level error message, which can be ignored or suppressed, is generated; this error indicates that the implied definition might not be the desired definition.
  • The ERASE clause in a screen description entry cannot be specified without EOS or EOL. A simple ERASE clause must be changed to BLANK SCREEN. An ERASE LINE clause must be changed to ERASE EOL or BLANK LINE.
  • The SYNCHRONIZED clause follows Visual COBOL specifications instead of RM/COBOL specifications. This may result in file record size differences or redefinition issues. It may be necessary to insert explicit definition of slack characters in record descriptions for groups that have an odd length, especially if the group or elementary items of odd length are subject to an OCCURS clause.
  • The USAGE COMP/COMPUTATIONAL clause in a data description entry does not produce the informational message COBCH1210 COMP processed as DISPLAY (future occurrences not indicated).
  • Procedure Division headers that specify a nonnumeric returning or giving data item are not permitted unless there is a prototype that specifies the RM call-convention (1024).
  • Procedure-names cannot be the same as data-names. When DIALECT"RM" is set, a procedure-name that is the same as a data-name produces an informational COBCH0305 message; when DIALECT"RM" is not set, a procedure-name that is the same as a data-name produces a serious COBCH0305 message and the two categories of names must be disjoint in the source program.
  • A comparison of a nonnumeric literal that contains only digits to a display unsigned numeric data item or literal does not preserve RM/COBOL behavior.
  • Character set handling for files does not preserve RM/COBOL behavior.
  • I/O statements that result in a serious error at run time do not terminate the program when there is no applicable declarative but a file status data item is declared. The file status data item must be checked after each I/O statement to see if a serious error has occurred.
  • I/O defaults to expect Visual COBOL file formats. You need to set the FILETYPE"21" directive for I/O with existing RM/COBOL format files or convert those files to Micro Focus format files.
    Note: Converting the file format does not convert the format of data items in the file. If the data items are not also converted, directives that define data format may be required, such as COMP"UNPACKED", COMP1"BINARY", COMP6"3", IBMCOMP and SIGN"EBCDIC".

    If FILETYPE"21" is not specified, I/O status values will be different than in RM/COBOL.

  • ACCEPT/DISPLAY syntax and behavior differs significantly, requiring revision of the source program to achieve behavior expected from the RM/COBOL program. Some of the revisions for behavior might not be necessary if the RM/COBOL ADISCTRL and COBKEYMAP files are used, but Visual COBOL does not send all the forms of ACCEPT/DISPLAY to ADIS; the CONSOLE IS CRT clause or the DISPLAY"CRT" directive might resolve this issue. Also:
    • Pop-up windows are not available without setting DIALECT"RM".
    • The TAB syntax for ACCEPT can be restored with an ADDRSV"TAB" directive.
    • The reverse syntax for ACCEPT/DISPLAY can be restored with an ADDRSV"REVERSE" directive.
    • The ACCEPT statement will not allow the ERASE phrase; a separate DISPLAY SPACE ERASE statement before the ACCEPT is required.
    • The Visual COBOL defaults will apply with respect to the MODE IS BLOCK, HIGH-LIGHT, BEEP and ECHO.
    • The UNIT and ECHO phrases are not supported without setting DIALECT"RM".
  • ACCEPT/DISPLAY statements with a group operand for the primary operand produce a COBCH1654 Should be elementary; MODE IS BLOCK assumed when certain phrases are used. When the error does not occur, the group operand will be treated similar to a screen ACCEPT/DISPLAY, with elementary items being the fields and FILLER items treated as empty space between fields on the screen. You must add the MODE IS BLOCK phrase to such ACCEPT/DISPLAY statements to obtain RM/COBOL behavior of treating the group as a single field.
  • ACCEPT/DISPLAY statements position fields on the screen as explained for Visual COBOL and not as they are for RM/COBOL. The program must be modified to make the positioning behave as desired.
  • ACCEPT statements that specify the ON EXCEPTION identifier-1 syntax do not compile. The identifier-1 item in the ON EXCEPTION phrase must be removed. The data item referenced by the CRT status clause, which may need to be added, can be used to obtain the status of the ACCEPT statement, but be aware that its format is not the same as identifier-1 as specified in the ON EXCEPTION phrase. When DIALECT"RM" is set, the format of the CRT status data item is converted to match RM/COBOL's format if the ON EXCEPTION phrase is specified in the ACCEPT statement.
  • ACCEPT statements that specify UPDATE or CONVERT revert to Visual COBOL behavior for these phrases.
  • ACCEPT statements cannot specify ERASE. The ERASE must be performed in a separate DISPLAY statement preceding the ACCEPT statement. This is also true of using the CONTROL phrase to specify ERASE in the control-string specified in the CONTROL phrase.
  • ACCEPT statements do not beep by default. The RM"BEEP" directive can be specified to restore the RM/COBOL default beep, but that will also set old RM compatibility. Instead, you should modify the program to specify BEEP in ACCEPT statements where BEEP is desired.
  • CALL statements cannot specify figurative constants or symbolic characters in the USING phrase.
  • CALL statements with numeric literals as arguments might not preserve the original form of the literal as specified in the source for the actual argument value.
  • CALL statements do not use an alignment of 1 for BY CONTENT temporaries, but instead align the temporary variable per the value of the ALIGN directive.
  • CALL statements must have a numeric RETURNING/GIVING argument. The RM/COBOL feature of any type for RETURNING/GIVING arguments is not supported except when the 1024 call-convention is specified.
  • CALL "SYSTEM" is not RM/COBOL compatible unless the call-convention is set to 1024, either by the DEFAULTCALLS"1024" directive, a prototype for SYSTEM that specifies the 1024 call-convention, or an explicit call-convention specified in the CALL statement.
  • CANCEL of non-nested program behaves as if the program were nested in an IL program.
  • CLOSE statements for a line sequential file cannot specify the NO REWIND phrase.
  • DELETE FILE statements do not perform a USE procedure declared for the file when an error occurs.
  • DISPLAY statements that specify a figurative constant with positioning information and do not specify the SIZE phrase are not converted to a single-byte literal.
  • The WITH NO ADVANCING phrase for simple (ANSI) ACCEPT and DISPLAY statements is not handled in the same way as in RM/COBOL when the DISPLAY"CRT" directive is set and DIALECT"RM" is not.
  • MOVE statements that move a nonnumeric literal, including a figurative constant, that contains non-digit characters to a numeric item, substitute 0 for the sending item and produce a COBCH1026 Source literal is nonnumeric - substituting zero error. The nonnumeric literal should be changed to contain only digits or not be used as the sending item in a MOVE operation to a numeric data item.
  • MOVE statements that move a nonnumeric data item to a display unsigned numeric item do not preserve RM/COBOL behavior.
  • OPEN statements set retry lock unconditionally, which differs from RM/COBOL behavior, where this is conditional on there being a USE procedure and file status data item.
  • By default, Visual COBOL's default file locking mode is EXCLUSIVE, whilst RM/COBOL's default locking mode is AUTOMATIC. Use the Compiler directive FILESHARE to change the default behavior, or change the file's SELECT statement and add the LOCK MODE AUTOMATIC clause.
Parent topic: Converting RM/COBOL Applications
Related reference
ADDRSV
ASSIGN
DIALECT
RECMODE
Reserved Words Table


RM/COBOL Data Types

When you compile your programs with the DIALECT"RM" Compiler directive, all data types behave in the same way that they do in RM/COBOL.

If you do not compile with the DIALECT directive, you can still preserve RM/COBOL behavior for certain data types by using certain other Compiler directives: COMP, COMP1, COMP2, and COMP-6.

Parent topic: Converting RM/COBOL Applications
Related reference
COMP
COMP1
COMP2
COMP-6
SIGN


RM/COBOL Conversion Issues

The syntax of most RM/COBOL source programs when submitted to run on this COBOL system will be accepted and run successfully. However, sometimes this COBOL system might reject some of the syntax in your original RM/COBOL source program, or might cause your program to behave unexpectedly at run-time.

This section contains the known problems which you may encounter. Hints are also given on how you can either rectify the cause of such errors, or emulate the RM/COBOL type of behavior in this COBOL system.

  • Producing Executable Code
  • Running the Code
Parent topic: Converting RM/COBOL Applications


Producing Executable Code

The following section covers the known issues when submitting RM/COBOL source programs to this COBOL system. Where possible, work-arounds and resolutions are also provided.

  • Perform Statements
    PERFORM statements are not treated in the same way by both COBOL systems. This COBOL system uses a stack-based perform handling system, while the RM/COBOL system associates a return address with a specific procedure name.
  • ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY
    In Visual COBOL, to use the FROM CENTURY-DATE and FROM CENTURY-DAY phrases with the ACCEPT statement, set the RM Compiler directive.
  • CURSOR phrase not available in ACCEPT statement
    Visual COBOL and RM/COBOL differ in the way that they allow you to obtain the cursor position after an ACCEPT statement.
  • Nested COPY statements with REPLACING phrase
    In Visual COBOL, you cannot specify text replacement as part of a nested COPY statement when text replacement is already active as part of a COPY statement.
  • Duplicate Paragraph-names
    Visual COBOL and RM/COBOL differ in the way that they reference paragraph-names when two or more duplicate paragraph names exist differs.
  • Figurative Constants and the USING Phrase
    In Visual COBOL, to use figurative constants in the USING phrase of a CALL statement or as values of level 78 constants, set the DIALECT"RM" Compiler directive.
  • File Not Found Errors
    Visual COBOL and RM/COBOL differ in the environment variables that they use to locate program and data files.
  • Indexed File Error on Open
    Visual COBOL and RM/COBOL differ in how they handle record length fields and some data fields when you open an RM/COBOL indexed file.
  • LIKE Relational-operator Not Available
    Visual COBOL and RM/COBOL differ in the way that they allow you to use regular expressions.
  • Linkage Section in Main Program
    Visual COBOL and RM/COBOL differ in their ability to reference the Linkage Section items in the main program.
  • Nested OCCURS DEPENDING Clauses
    In Visual COBOL, if you are using nested OCCURS DEPENDING clauses, you must set the ODOSLIDE Compiler directive.
  • Numbering of Segments
    Visual COBOL and RM/COBOL differ in the number of segments that they permit you to specify.
  • Program Identification and Data Names
    In Visual COBOL, ensure that the Program-ID name does not share the same name as any data items in the program.
  • REMARKS Paragraph
    In Visual COBOL, if your program uses the REMARKS paragraph in the Identification Division, you must set the DIALECT"RM" Compiler directive.
  • Reserved Words
    In Visual COBOL, setting certain Compiler directives (such as RM and ANS85) activates certain reserved words that you cannot use as names for your data items.
  • SAME AS Clause Not Available When Defining Data Structures
    Visual COBOL and RM/COBOL differ in the way that they allow you to reuse existing data structures.
  • Source Code in Columns 73 to 80
    Visual COBOL ignores any of the code in your source programs which lies within columns 73-80 inclusive.
  • START WHILE LIKE Not Available
    Visual COBOL and RM/COBOL differ in the way that they allow you to select records from and indexed organization file.
  • Undeclared Data Items in Clauses
    In Visual COBOL, if the data item used in a clause (for example, the File Status clause) is not declared, you receive an error.
  • User-names Longer than 127 Bytes are Truncated
    In RM/COBOL, you can specify user-names (data-names, procedure-names, program-names, etc) up to 240 characters long. In this COBOL system, user-names longer than 127 bytes in length are truncated and a warning message is produced.
  • Using Relative Path Names
    If your RM/COBOL application relies on the EXPANDED-PATH-SEARCH configuration option to locate files specified with a relative path name, you must set the COPYSEARCH"RM-EXPANDED" Compiler directive in Visual COBOL for equivalent behavior.
Parent topic: RM/COBOL Conversion Issues


Perform Statements

PERFORM statements are not treated in the same way by both COBOL systems. This COBOL system uses a stack-based perform handling system, while the RM/COBOL system associates a return address with a specific procedure name.

As a result, under the RM/COBOL system, all end-points to PERFORM statements are always active until they are used. However, under this system, only the end-point of the last PERFORM statement is active at any one time.

You must set the PERFORM-TYPE directive with the RM parameter if this COBOL system is to emulate the behavior of RM/COBOL PERFORM statements.

Parent topic: Producing Executable Code
Related reference
The PERFORM Statement


ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY

In Visual COBOL, to use the FROM CENTURY-DATE and FROM CENTURY-DAY phrases with the ACCEPT statement, set the RM Compiler directive.

Alternatively, use the following equivalent phrases with the ACCEPT statement:

  • FROM DATE YYYYMMDD, which is the equivalent of FROM CENTURY-DATE.
  • FROM DAY YYYYDDD, which is the equivalent of FROM CENTURY-DAY.
procedure division.
ACCEPT data-name-1 FROM DATE YYYYMMDD.
ACCEPT data-name-2 FROM DAY YYYYDDD.
Parent topic: Producing Executable Code
Related reference
The ACCEPT Statement


CURSOR phrase not available in ACCEPT statement

The CURSOR phrase from RM/COBOL is not supported in Visual COBOL. In Visual COBOL, you must use the data item specified in the CURSOR clause in the special-names paragraph. To obtain the offset in the accepted field as returned by RM/COBOL for the CURSOR phrase of the ACCEPT statement, do the following:

  1. Set the data item specified in the CURSOR clause to have the line and column where the ACCEPT statement begins. If the ACCEPT statement is not positioned and will start at the current cursor location, the CBL_GET_CRSR library routine can be used to get the current cursor position; note that CBL_GET_CRSR returns zero-relative position information, which must be adjusted to one-relative position information when setting the location in the data item specified by the CURSOR clause.
  2. Save the start column in another data item.
  3. Execute the ACCEPT statement (without a CURSOR phrase since it is not supported).
  4. Subtract the original start column from the current column in the data item specified in the CURSOR clause and store this as the offset.
Parent topic: Producing Executable Code


Nested COPY statements with REPLACING phrase

In Visual COBOL, you cannot specify text replacement as part of a nested COPY statement when text replacement is already active as part of a COPY statement.

If you attempt to use COPY REPLACING in a file copied with a COPY REPLACING statement, an error code COBCH0062 COPY replacement not supported is displayed on compilation.

Parent topic: Producing Executable Code
Related information
COBCH0062 Nested COPY replacement causes termination of parent COPY replacement
The COPY Statement


Duplicate Paragraph-names

In Visual COBOL, if you have duplicate paragraph-names, in different sections, and then call a paragraph-name from outside its section, an error is produced unless you have explicitly referenced the paragraph-name and its section. In RM/COBOL, by just calling the paragraph-name, it assumes you are calling the next declaration of the paragraph-name found.

To ensure that references to duplicate paragraph-names are correctly resolved, you must qualify a reference to a duplicate paragraph-name by adding the section-name in which it is declared.

Example

If your source code contains the following:

      ....
      perform para-2.
      ....
 sect-1 section.
      para-1.
      ....
      para-2.
      ....
 sect-2 section.
      para-2.
      ....

RM/COBOL will resolve the reference to para-2 in the PERFORM statement by using the declaration of para-2 in the sect-1 SECTION. In Visual COBOL, however, you must qualify the reference to the duplicate paragraph-name in your source code by using the PERFORM para-2 OF sect-1 statement.

Parent topic: Producing Executable Code
Related reference
The PERFORM Statement


Figurative Constants and the USING Phrase

In Visual COBOL, to use figurative constants in the USING phrase of a CALL statement or as values of level 78 constants, set the DIALECT"RM" Compiler directive.

Alternatively, the figurative constant can be replaced by the equivalent non-numeric literal, such as " " for SPACE or "0" for ZERO.

Parent topic: Producing Executable Code
Related reference
DIALECT


File Not Found Errors

Visual COBOL and RM/COBOL differ in the environment variables that they use to locate program and data files.

If your source code produces a file not found error, ensure the correct paths are set in the correct environment variables. In Visual COBOL, set COBPATH to locate program files and COBDATA to locate data files. The RUNPATH environment variable used in RM/COBOL, is not used in Visual COBOL.

Parent topic: Producing Executable Code


Indexed File Error on Open

Visual COBOL and RM/COBOL differ in how they handle record length fields and some data fields when you open an RM/COBOL indexed file.

In Visual COBOL, when you try to open an RM/COBOL indexed file, you may receive either a run-time error COBRT161 Illegal intermediate code or a file status code 39 A conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.

You must ensure that you read in the same size records that were created in RM/COBOL.

If the length of the file description does not match that which was processed in RM/COBOL, check the following:

  • In RM/COBOL, you can set the RECORD CONTAINS nn CHARACTERS clause to be a different length than the actual length specified in the record description. If this clause is greater than the actual description, you must pad the record description with filler bytes to match the RECORD CONTAINS clause.
  • If you have signed numeric display data in your file, Visual COBOL will treat the sign as a separate byte if you are using the RM directive without "ANSI" specified. If these fields are stored as sign internal, you must use RM"ANSI" or do not use the RM directive at all.
Parent topic: Producing Executable Code
Related information
COBRT161 Illegal intermediate code (Fatal)
RM/COBOL File Status Codes


LIKE Relational-operator Not Available

Visual COBOL and RM/COBOL differ in the way that they allow you to use regular expressions.

RM/COBOL has a LIKE relational-operator. Visual COBOL does not support the LIKE relational-operator. Instead, use the C$REGEXP library routine. C$REGEXP uses a call convention of zero, so when using it in a DIALECT"RM" program, where the default call convention is 1024, the call convention must be specified in the CALL statement for C$REGEXP.

The regular expressions supported by C$REGEXP differ somewhat from those used by the RM/COBOL LIKE relational-operator and between Windows and UNIX, so adjustments may be required in the regular expression syntax used.

Parent topic: Producing Executable Code


Linkage Section in Main Program

In RM/COBOL, if the main program has a Linkage Section, it is initialized by the parameter passed on the command line. In Visual COBOL, you must use the command_line_linkage tunable or the COMMAND-LINE-LINKAGE Compiler directive to pass parameters from the command line to the Linkage Section.

Parent topic: Producing Executable Code
Related reference
Linkage Section
COMMAND-LINE-LINKAGE


Nested OCCURS DEPENDING Clauses

In Visual COBOL, if you are using nested OCCURS DEPENDING clauses, you must set the ODOSLIDE Compiler directive.
Parent topic: Producing Executable Code
Related reference
The OCCURS Clause
ODOSLIDE


Numbering of Segments

In Visual COBOL, you can only specify segment numbers in the range 0 to 99 inclusive, which conforms to segment number limit specified in the ANS X3.23-1985 COBOL standard. In RM/COBOL, you can specify segment numbers greater than 99.

If your source code has segment numbers greater than 99, recode the program. Make sure that any new segment numbers you allocate do not clash with an already existing segment number. Segment numbers between 0 and 49 inclusive are used by Visual COBOL to indicate fixed portions of your object program, while segment numbers 50 to 99 inclusive indicate independent segments.

For details on the use of segmentation and segment numbers in your source programs, see COBOL Language Reference in the product Help.

Parent topic: Producing Executable Code


Program Identification and Data Names

In Visual COBOL, you cannot use the same name for the Program-ID and a data item in the program; each name should be unique. RM/COBOL permits the name of the Program-ID paragraph and a data item to share the same name.

Parent topic: Producing Executable Code
Related information
The Program-ID Paragraph
Segmentation


REMARKS Paragraph

In Visual COBOL, if your program uses the REMARKS paragraph in the Identification Division, you must set the DIALECT"RM" Compiler directive.

Alternatively, mark the paragraph as comment lines.

Parent topic: Producing Executable Code
Related reference
DIALECT


Reserved Words

In Visual COBOL, setting certain Compiler directives (such as RM and ANS85) activates certain reserved words that you cannot use as names for your data items.

If you attempt to use a reserved word, you receive a COBCH0666 ("Reserved word used as data name or unknown data description qualifier") COBOL syntax error.

To continue to use the reserved word as a data name, you can:

  • Use the REMOVE Compiler directive, to unreserve that particular keyword.
  • Set the MFLEVEL Compiler directive to an appropriate level, to unreserve all keywords above that level.

    See Compiler Directives in the product Help.

Example

Your RM/COBOL source program may contain the following lines of code:

     ....
     03 sort   pic 99.
     ....
     move 1 to sort

If you submit this to Visual COBOL, you will receive an error because the SORT verb is reserved. However, if you specify the REMOVE"SORT" Compiler directive when you submit this source program, you will not receive the error.

Parent topic: Producing Executable Code
Related information
COBCH0666 Reserved word used as data-name or unknown data description qualifier
REMOVE


SAME AS Clause Not Available When Defining Data Structures

Visual COBOL and RM/COBOL differ in the way that they allow you to reuse existing data structures.

In Visual COBOL, use the TYPEDEF clause to define your base data structure, and then use the USAGE clause to create data structures of the same type.

data division.
working-storage section.
01 atype is typedef.
   03 var1 pic x(10) value "brown".
   03 var2 pic x(10) value "blue".
   03 var3 pic x(10) value SPACE.
01 a1 usage atype.
procedure division.
display var2 of a1.

The result of the display statement is blue.

The SAME AS clause used in RM/COBOL is not supported in Visual COBOL.

Parent topic: Producing Executable Code
Related reference
The TYPEDEF Clause
The USAGE Clause


Source Code in Columns 73 to 80

Visual COBOL ignores any of the code in your source programs which lies within columns 73-80 inclusive.

Code in these columns could be the result of expanding TAB characters in your source program, instead of standard TAB stops. If your source program contains TAB stops, convert them to spaces.

If your RM/COBOL program used the >>IMP MARGIN-R AFTER END OF RECORD directive for long source records, remove that directive from the source and use the Visual COBOL SOURCEFORMAT"variable" directive. Note that source lines longer than 256 bytes are not supported and will be truncated with a message at compile-time.

RM/COBOL implementor defined directives >>IMP for source format, >>LISTING ON/OF and >>PAGE are not supported.

Parent topic: Producing Executable Code


START WHILE LIKE Not Available

Visual COBOL and RM/COBOL differ in the way that they allow you to select records from and indexed organization file.

RM/COBOL allows a WHILE LIKE filter in the START statement. The filter is passed to the file manager and only records that match the filter are returned to the COBOL program for processing. Visual COBOL does not support such a filtering mechanism. The COBOL program must retrieve all the records and filter them in the program, which is less efficient, but at least emulates the RM/COBOL feature. The C$REGEXP library routine can be used to apply a regular expression filter similar to what the WHILE LIKE phrase in RM/COBOL would apply in the file manager.

Parent topic: Producing Executable Code


Undeclared Data Items in Clauses

In Visual COBOL, you receive a COBCH0250 STATUS field data-name missing or illegal error if a data item used in the File Status clause is not declared in the Working-Storage section. In RM/COBOL, you do not have to declare the data item in Working Storage.

With the DIALECT"RM" directive, serious error COBCH0250 is no longer generated by Visual COBOL for the undeclared items. Instead, a non-serious COBCH1787 is generated. This error can be suppressed or ignored. It indicates that a default definition has been provided. The default definition is the same as the one supplied by RM/COBOL, but it might not be the desired definition. If it is not the desired definition, modify your program to define the data item as desired.

Parent topic: Producing Executable Code
Related information
COBCH0250 STATUS field data-name missing or illegal
RM/COBOL File Status Codes


User-names Longer than 127 Bytes are Truncated

In RM/COBOL, you can specify user-names (data-names, procedure-names, program-names, etc) up to 240 characters long. In this COBOL system, user-names longer than 127 bytes in length are truncated and a warning message is produced.

Solution:

Results may be affected if the truncated user-name is used with XML Extensions, to export or import XML documents; therefore, we recommend that you keep user-names to 127 bytes or less.

Parent topic: Producing Executable Code
Parent topic: Compatibility with XML Extensions


Using Relative Path Names

If your RM/COBOL application relies on the EXPANDED-PATH-SEARCH configuration option to locate files specified with a relative path name, you must set the COPYSEARCH"RM-EXPANDED" Compiler directive in Visual COBOL for equivalent behavior.

When running your application under the DIALECT"RM" emulation, COPYSEARCH"RM" is set by default, which only emulates the standard RM/COBOL directory search sequence when trying to resolve relative path names. You must override this setting with the COPYSEARCH"RM-EXPANDED" Compiler directive on your individual programs or application.

Parent topic: Producing Executable Code
Related reference
COPYSEARCH


Running the Code

Once you have successfully submitted your RM/COBOL source program to this COBOL system and produced executable code, you might encounter difficulties when you try to run this code under this system. Alternatively, the code might run but you might find that its behavior under this COBOL system is not exactly the same as under the RM/COBOL system. The following sections detail known areas of difficulty you might encounter, and offer hints on how you can avoid them.

  • Table Bound Checking
    If you try to run a program under this COBOL system which contains a subscript value greater than the size of the table to which it refers, the run-time system will produce an error indicating this. Under the RM/COBOL system, however, no such table bound checking is done.
  • ACCEPT Fields at the Edge of the Screen
    Visual COBOL and RM/COBOL differ in their alignment of numeric data items from an ACCEPT statement that would result in the data going beyond the right-hand edge of the screen.
  • C$CARG Not Supported
    The RM/COBOL C$CARG library routine is not supported.
  • Display of Input Data in Concealed ACCEPT Fields
    Visual COBOL and RM/COBOL differ in the way that they treat data entered as part of an ACCEPT statement when the OFF and ECHO clauses are specified.
  • Embedded Control Sequences in DISPLAY Statements
    In Visual COBOL, you cannot embedded control sequences within data items that you want to be displayed.
  • End of File Notification
    After an unsuccessful READ on a sequential file, due to reaching the end of the file, Visual COBOL will indicate that there is still no next logical record if you attempt to read the file without closing and opening it again.
  • The EXCEPTION STATUS Clause
    Visual COBOL and RM/COBOL differ in their treatment of the EXCEPTION STATUS clause during an ACCEPT statement.
  • File Status Codes
    Programs that do not use a file status or declaratives may not seem to produce an accurate file status code in the event of a run-time error.
  • Field Wrap-Around
    Visual COBOL and RM/COBOL differ when performing arithmetic operations on binary data items (that is, RM/COBOL COMPUTATIONAL-1 format items) which result in the value exceeding the capacity of the target data item and there is no ON SIZE ERROR clause specified.
  • File and Record Locking
    Certain versions of RM/COBOL contain some software errors in the way in which locks for files and records are handled. These errors do not occur in Visual COBOL.
  • Initialization of Working Storage
    Visual COBOL and RM/COBOL differ in the way that they initialize data items without values in Working Storage.
  • Numeric Fields Containing Illegal Characters When Using a DEPENDING ON Phrase of an OCCURS Clause
    In Visual COBOL, if you fail to initialize a numeric data item that is used in a DEPENDING ON phrase of an OCCURS clause appropriately, a COBRT163 Illegal character in numeric field error is displayed at run time.
  • ON SIZE ERROR Phrase
    Visual COBOL and RM/COBOL differ in their treatment of the ON SIZE ERROR condition.
  • Open EXTEND of Nonexistent File
    Visual COBOL when you have the RM Compiler directive set and RM/COBOL differ in the result of attempting to open a non-existent file for EXTEND.
  • Printer Output is Written to Disk
    By default, Visual COBOL writes all output intended for a printer to disk.
  • Screen Column Number Specification
    Visual COBOL and RM/COBOL differ in the number of screen columns you are able to specify.
  • Trailing Blanks in Line Sequential Files
    Visual COBOL and RM/COBOL differ in the way that they deal with trailing blanks from line sequential records before writing the record.
  • Undefined Results of MOVE and Arithmetic Operations
    Visual COBOL and RM/COBOL differ in the results of MOVE statements, arithmetic operations, and comparisons that involve numeric and alphanumeric data items.
  • Using the Correct Calling Convention
    The library routines provided for RM/COBOL compatibility use a different calling convention to the Visual COBOL library routines. Therefore, programs that contain both types of library routine must explicitly specify the appropriate calling convention for one type or the other.
Parent topic: RM/COBOL Conversion Issues


Table Bound Checking

If you try to run a program under this COBOL system which contains a subscript value greater than the size of the table to which it refers, the run-time system will produce an error indicating this. Under the RM/COBOL system, however, no such table bound checking is done.

Therefore, if you wish to disable table bound checking in this COBOL system, you must use the NOBOUND directive.

If you use the NOBOUND directive when running intermediate code, you will be able to access data beyond a table's bounds by using a subscript value greater than the table size. Use of the NOBOUND directive when you are producing intermediate code will also disable bound checking when running generated code. However, if you wish to access data beyond a table's bounds when running generated code, you must also use the directive NOBOUNDOPT.

Note: When you use the NOBOUNDOPT directive, performance will be impaired.

Parent topic: Running the Code
Related reference
BOUND
BOUNDOPT


ACCEPT Fields at the Edge of the Screen

If your program contains an ACCEPT statement for a numeric data item at a position on the screen where the definition of the numeric data item would cause the ACCEPT field to go beyond the right-hand edge of the screen, both COBOL systems will truncate the input value. In RM/COBOL, the input value will be aligned into the ACCEPT field as an alphanumeric field, whereas in Visual COBOL, the input value is aligned as a numeric field.

Change the definition of the relevant PICTURE clause from numeric to alphanumeric. Alternatively, change the PICTURE clause so that the field does not go beyond the edge of the screen.

Example

If your program contains the following statement:

ACCEPT data-item AT COLUMN NUMBER 75.

where data-item is a numeric data item defined as PIC 9(10), a value of 123456 entered into the ACCEPT field will be held under Visual COBOL as "0000123456". However, in RM/COBOL, the value in the ACCEPT field would be held as "1234560000". To allow Visual COBOL to emulate the RM/COBOL behavior, alter the definition of the data item in your program to PIC X(10) or PIC 9(6).

Parent topic: Running the Code
Related reference
The ACCEPT Statement


C$CARG Not Supported

The RM/COBOL C$CARG library routine is not supported.

Calls to C$CARG must be changed to use C$DARG, which is supported and provides equivalent functionality.

Parent topic: Running the Code
Related reference
C$DARG


Display of Input Data in Concealed ACCEPT Fields

If you have specified OFF and ECHO clauses for the same ACCEPT statement in your program, RM/COBOL will conceal any data entered during input for that statement but on completion of input will display the data. Visual COBOL will not display the data for this ACCEPT statement once input has been completed.

If you want to display the data input for an ACCEPT statement with the OFF and ECHO clauses specified, you must add a DISPLAY statement after the ACCEPT statement.

Parent topic: Running the Code
Related reference
The ACCEPT Statement


Embedded Control Sequences in DISPLAY Statements

In Visual COBOL, you cannot embedded control sequences within data items that you want to be displayed.

Such characters are ignored at run time as they are hardware dependent.

Remove the control sequences from your source program and replace with the equivalent Micro Focus COBOL syntax; for example, use the syntax WITH UNDERLINE to replace <left-arrow>]4m.

Parent topic: Running the Code
Related information
COBOL Language Reference


End of File Notification

The first time you unsuccessfully try to READ a sequential file in either COBOL system because you have reached the end of the file, status key 1 in the FILE STATUS is set to 1 and status key 2 is set to 0. This indicates that there is no next logical record. If you try to READ the same file again, without it either having been previously closed and reopened, or it having been successfully started, Visual COBOL continues to indicate that there is no next logical record. However, if you try to READ the same file again under RM/COBOL, status key 1 is set to 9 and status key 2 is set to 6.

A solution to the different file statuses returned for the circumstances given above will depend on the way in which your source program is coded. We suggest that you include tests for the values 1 and 0 in status key 1 and 2 of the file status, respectively, at the same time as you test for the values 9 and 6 in these status keys.

Parent topic: Running the Code
Related reference
The READ Statement


The EXCEPTION STATUS Clause

Visual COBOL and RM/COBOL differ in their treatment of the EXCEPTION STATUS clause during an ACCEPT statement.

The EXCEPTION STATUS values returned differ between the two COBOL languages. See The ACCEPT Statement for a list of statuses returned in Visual COBOL.

In Visual COBOL, the EXCEPTION STATUS value is undefined if the preceding CALL statement does not contain the ON EXCEPTION or ON OVERFLOW phrase. In RM/COBOL, it will always return a value of zero in those cases.
Parent topic: Running the Code
Related reference
The ACCEPT Statement


File Status Codes

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: Running the Code
Related reference
RMCOBOL File Status Codes


Field Wrap-Around

If, when using binary data items (that is, RM/COBOL COMPUTATIONAL-1 format items) an arithmetic operation gives a value which exceeds the capacity of the data item, and there is no ON SIZE ERROR clause, Visual COBOL wraps-around the value of the item. However, in RM/COBOL, the data item is set to the limit of its capacity.

You should specify an ON SIZE ERROR clause to highlight such problems.

Example

In RM/COBOL, the following lines of code result in the value +32767 being stored in the data item, CALC-ITEM. However, Visual COBOL sets CALC-ITEM to -32768:

01 calc-item         pic s9(4)  comp-1.

 procedure division.
      ....
     move 32767 to calc-item.
     add 1 to calc-item.
Parent topic: Running the Code


File and Record Locking

Certain versions of RM/COBOL contain some software errors in the way in which locks for files and records are handled. These errors do not occur in Visual COBOL.

The errors fixed when upgrading to Visual COBOL are:

  • Indexed files do not detect or acquire locks if they are opened for output. This is regardless of whether you specify the WITH LOCK phrase
  • Relative and sequential files cannot be locked exclusively
  • Files which are opened for input can detect record locks, although the RM/COBOL documentation states that they cannot. When the RM directive is set in Visual COBOL, record locks can still be detected by files opened for input
  • The first record in a sequential file opened for input-output is locked whenever any other record in that file is locked
Parent topic: Running the Code
Related reference
The OPEN Statement


Initialization of Working Storage

Visual COBOL initializes all working storage items without VALUE clauses to SPACES .The RM/COBOL system initializes all working storage items to SPACES, unless you have placed numeric data items between data items with VALUE clauses.

If this feature causes you any problems, because your program relies on the initial value given to the system, add a VALUE clause with the appropriate value to your source program and resubmit it.

Example

The RM/COBOL system initializes the following group item to SPACES:

01 group-item.
     03 item-1     pic x.
     03 item-2     pic 99.
     03 item-3     pic x.

However, if item-1 and item-3 have value clauses associated with them, the RM/COBOL system initializes the second byte of item-2 to hexadecimal value 0 when item-2 is defined as USAGE COMP (signed or unsigned) or USAGE DISPLAY (unsigned only).

Parent topic: Running the Code
Related reference
The VALUE Clause


Numeric Fields Containing Illegal Characters When Using a DEPENDING ON Phrase of an OCCURS Clause

In Visual COBOL, if you fail to initialize a numeric data item that is used in a DEPENDING ON phrase of an OCCURS clause appropriately, a COBRT163 Illegal character in numeric field error is displayed at run time, because the data item is initialized to SPACES if no value is specified. In RM/COBOL, the data item is initialized to ZERO, and therefore, the error does not occur.

Parent topic: Running the Code
Related information
COBRT163 Illegal character in numeric field (Fatal)
The OCCURS Clause


ON SIZE ERROR Phrase

In Visual COBOL, the ON SIZE ERROR condition exists when the value resulting from an arithmetic operation exceeds the capacity of the specified picture-string. In RM/COBOL, the ON SIZE ERROR condition exists when the value resulting from an arithmetic operation exceeds the capacity for the associated data item.

Ensure that the capacity of any data items in your source programs is specified by a picture-string; for example, COMPUTATIONAL-1 data items.

Parent topic: Running the Code
Related information
The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase


Open EXTEND of Nonexistent File

In Visual COBOL, because setting the RM Compiler directive sets the NOOPTIONAL-FILE Compiler directive, if you try to open a non-existent file for I-O or EXTEND the run-time system will give an error message. For I-O, RM/COBOL does the same. However, for EXTEND, RM/COBOL creates the file and opens it as if you had specified OUTPUT.

The following options are available:

  • Add the keyword OPTIONAL to the SELECT statement. This makes Visual COBOL create the file and open it for OUTPUT
  • Create the empty file before running your program
  • Specify the OPTIONAL-FILE Compiler directive. This makes Visual COBOL create the file and open it for OUTPUT. However, the behavior with files opened for I-O will now differ from RM/COBOL
Parent topic: Running the Code
Related reference
OPTIONAL-FILE


Printer Output is Written to Disk

By default, Visual COBOL writes all output intended for a printer to disk.
To send output to a physical printer, you must map the filename using the dd_LPT1 environment variable or, if your system supports the lp printer spooler, you should use:
dd_LPT1=">lp";export dd_LPT1

With the DIALECT"RM" directive, the ASSIGN-PRINTER"" directive is set. In this case, a file assigned to a printer without a file-name in the ASSIGN clause is given a file-name that matches the file-name specified in the SELECT clause. Thus, to redirect the output file, set an environment variable dd_file-name to the desired destination.

Parent topic: Running the Code
Related information
Filename Mapping


Screen Column Number Specification

Visual COBOL permits you to specify screen column numbers up to and including 999, but RM/COBOL permits you to specify column numbers greater than 999. If you try to run an RM/COBOL source program containing a column number greater than 999 in Visual COBOL, the column number is truncated so that only the last three digits are used. If truncation of the column number occurs for an item to be displayed on the screen, the position of that item on the screen in Visual COBOL will differ from its position in RM/COBOL.

Parent topic: Running the Code
Related information
COBOL Language Reference


Trailing Blanks in Line Sequential Files

Visual COBOL always removes trailing blanks from line sequential records before writing the record. RM/COBOL removes trailing blanks from such records only if the FD entry contains 01 level records of different sizes. This will not cause you any problems when you run your converted RM/COBOL programs in Visual COBOL. However, you may receive errors at run time if any REWRITE operations on line sequential files change the length of the records.

Change the file organization to sequential, or move an alternative padding character (for example, LOW-VALUES) to the end of the record before it is written. This ensures that full-length records are written.

You also need to ensure that the T run-time switch is not set, as this might also change the size of the record. See Run-time Switches in the product Help.

Parent topic: Running the Code
Related reference
T run-time switch


Undefined Results of MOVE and Arithmetic Operations

Visual COBOL and RM/COBOL differ in the results of MOVE statements, arithmetic operations, and comparisons that involve numeric and alphanumeric data items.

You can overcome most of these incompatibilities by redefining the data items involved, or by recoding the comparisons. If you submit a program in Visual COBOL containing an alphanumeric to numeric data item MOVE statement, a warning message will be displayed indicating this.

Example

If you submit a source program containing the following data items and procedural statements, the specified test will fail at run time:

 01 numeric-field        pic 9(5).
 procedure division.
     move "abc" to numeric-field.
     if numeric-field = "00abc"
         ....

When the RM Compiler directive is set, Visual COBOL partially emulates the behavior of RM/COBOL for alphanumeric to numeric MOVEs by treating the numeric item as an alphanumeric item which is right justified. However, the above example will still fail because RM/COBOL treats the literal ABC as numeric, and places 00ABC in the numeric item. To make the statement run successfully in Visual COBOL, amend the test in the source program to:

     if numeric-field = " abc"

and resubmit the source program.

Parent topic: Running the Code
Related information
The MOVE Statement
Arithmetic Operators


Using the Correct Calling Convention

We recommend that to use the RM/COBOL library routines provided in Visual COBOL, you explicitly set the 1024 call-convention in the CALL statement.

program-id. Program1.
Special-Names.
call-convention 1024 is RM.
...

procedure division.

call RM "SYSTEM" using "cmd.exe /c mkdir sys02".

goback.
end program Program1.
Parent topic: Running the Code


RM/COBOL Library Routines

The following RM/COBOL routines are available in this COBOL system.

  • C$Century
    Updates your COBOL programs to handle the year 2000 issue.
  • C$ConvertAnsiToOem
    Converts a buffer containing ANSI characters to a buffer containing the corresponding OEM characters.
  • C$ConvertOemToAnsi
    Converts a buffer containing OEM characters to a buffer containing the corresponding ANSI characters.
  • C$DARG
    Returns information about a parameter passed in the USING or GIVING phrases of the CALL statement that called a subprogram.
  • C$Delay
    Relinquishes the CPU for a length of time specified in seconds.
  • C$GetEnv
    Returns the value of an environment variable.
  • C$GetLastFileName
    Retrieves the last filename used in a COBOL I/O statement (including OPEN and CLOSE).
  • C$GetLastFileOp
    Retrieves the last COBOL I/O operation performed.
  • C$GetNativeCharset
    Retrieves information about the native character set in effect for the current run unit.
  • C$LogicalAnd
    Performs a bitwise logical AND operation on two or more non-numeric or numeric operands.
  • C$LogicalComplement
    Performs a bitwise logical One's Complement operation on a non-numeric or numeric operand.
  • C$LogicalOr
    Performs a bitwise logical OR operation on two or more non-numeric or numeric operands.
  • C$LogicalXor
    Performs a bitwise logical exclusive OR operation on two or more non-numeric or numeric operands.
  • C$LogicalShiftLeft
    Performs a logical shift left operation on a non-numeric or numeric operand.
  • C$LogicalShiftRight
    Performs a logical shift right operation on a non-numeric or numeric operand.
  • C$NARG
    Returns the number of parameters passed in the USING phrase of a CALL statement to the subprogram that contains the call to C$NARG.
  • C$OSLockInfo
    Returns the process ID of the process that has the record locked when a lock request fails. This routine should be called immediately after a lock request has failed.
  • C$SecureHash
    Produces a 20-byte message digest from an input text string using the secure hash algorithm (SHA-1).
  • C$SetEnv
    Sets or clears the value of an environment variable.
  • C$RERR
    Returns the expanded I/O completion status, based on an error code received at run-time.
  • DELETE
    Deletes a file.
  • RENAME
    Renames a file.
  • SYSTEM
    Executes an arbitrary operating system command.
Parent topic: Compatibility with RM/COBOL


C$Century

Updates your COBOL programs to handle the year 2000 issue.
Note: When calling this routine, ensure you are using the 1024 calling convention.

This library routine retrieves the first two digits of the current year.

Syntax:

CALL "C$Century" USING value-buffer

Parameters:

value-buffer
A two-byte data item with a format of either unsigned numeric display (NSU) or alphanumeric display (ANS).

On Exit:

value-buffer
The first two digits of the current year.

Comments:

You can achieve the same result using the standard COBOL command ACCEPT data-name FROM DATE YYYYMMDD and then referencing the data name.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$ConvertAnsiToOem

Converts a buffer containing ANSI characters to a buffer containing the corresponding OEM characters.

When calling this routine, ensure you are using the 1024 calling convention.

This is supported on Windows only.

Syntax:

CALL "C$ConvertAnsiToOem" USING ansi-buffer, oem-buffer
[, char-count]

Parameters:

ansi-buffer
PIC X(n)
oem-buffer
PIC X(n)
char-count
PIC 9(n)

On Entry:

ansi-buffer
The ANSI characters to be converted to OEM characters.
char-count
The number of characters to be converted.
Note: If omitted or if the value is invalid, the actual size of the shorter of ansi-buffer and oem-buffer is used.

On Exit:

oem-buffer
The converted OEM characters.
Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$ConvertOemToAnsi

Converts a buffer containing OEM characters to a buffer containing the corresponding ANSI characters.
Note: When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$ConvertOemToAnsi" USING oem-buffer, ansi-buffer
[, char-count]

Parameters:

oem-buffer
PIC X(n)
ansi-buffer
PIC X(n)
char-count
PIC 9(n)

On Entry:

oem-buffer
The OEM characters to be converted to ANSI characters.
char-count
The number of characters to be converted.
Note: If omitted or if the value is invalid, the actual size of the shorter of ansi-buffer and oem-buffer is used.

On Exit:

ansi-buffer
The converted ANSI characters.
Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$DARG

Returns information about a parameter passed in the USING or GIVING phrases of the CALL statement that called a subprogram.
Restriction: This routine is supported in native COBOL only.

When calling this routine, ensure you are using the 1024 calling convention.

This information identifies the type and length of the argument and, when the argument is numeric or numeric edited, the number of digits and scale factor for the argument.

Syntax:

CALL "C$DARG" USING argument-number, argument-description

Parameters:

argument-number
pic 9(n)
argument-description
01 ARGUMENT-DESCRIPTION.
    02 ARGUMENT-TYPE PIC 9(2) BINARY(2).
    02 ARGUMENT-LENGTH PIC 9(8) BINARY(4).
    02 ARGUMENT-DIGIT-COUNT PIC 9(2) BINARY(2).
    02 ARGUMENT-SCALE PIC S9(2) BINARY(2).
    02 ARGUMENT-POINTER POINTER.
    02 ARGUMENT-PICTURE POINTER.

On Entry:

argument-number
The ordinal position of the argument in the USING phrase of the CALL statement. The value zero returns the description of the GIVING phrase of the CALL statement.

On Exit:

argument-description
Details of the passed parameter. Those details include:
argument-type
The type of data item; see the table in the Comments section.
argument-length
The number of character positions of the data item.
argument-digit-count
The number of digits defined in the PICTURE character-string for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. The digit count for a numeric or numeric edited data item does not include any positions defined by the PICTURE symbol P, which represents a scaling position.
argument-scale
The power of 10 scale factor (that is, the position of the implied or actual decimal point) for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. If the PICTURE symbol P was used in the description of the data item, the absolute value of the ARGUMENTSCALE value will exceed the ARGUMENT-DIGIT-COUNT value; in this case, a positive scale value indicates an integer with P scaling positions on the right of the PICTURE character-string and a negative scale value indicates a fraction with P scaling positions on the left of the PICTURE character-string
argument-pointer
This parameter is not returned in this COBOL system.
argument-picture
This parameter is not returned in this COBOL system.

Comments:

Use the C$NARG library routine to obtain the number of arguments passed in the CALL statement.

The actual number of arguments may exceed the number of formal arguments declared in the Procedure Division header of the program that calls C$DARG. All of the actual arguments can be accessed using C$DARG even though there is no formal argument name available for accessing the actual arguments beyond the number of formal arguments.

The following table is used to indicate the data type specified in the ARGUMENT TYPE field:

Type Number | RM/COBOL Data Type | Type Number | RM/COBOL Data Type
0 | NSE | 16 | ANS
1 | NSU | 17 | ANS (justified right)
2 | NTS | 18 | ABS
3 | NTC | 19 | ABS (justified right)
4 | NLS | 20 | ANSE
5 | NLC | 21 | ABSE
6 | NCS | 22 | GRP (fixed length)
7 | NCU | 23 | GRPV (variable length)
8 | NPP | 25 | PTR
9 | NPS | 26 | NBSN
10 | NPU | 27 | NBUN
11 | NBS | 32 | OMITTED
12 | NBU |  |
Restriction: Data type OMITTED (type number 32) is not supported in this COBOL system.
Parent topic: RM/COBOL Library Routines
Related reference
The CALL Statement
Related information
Call Conventions for Interfacing with Mixed Languages


C$Delay

Relinquishes the CPU for a length of time specified in seconds.
Note: When calling this routine, ensure you are using the 1024 calling convention.

This library routine allows other programs to run while the current program waits.

Syntax:

CALL "C$Delay" USING seconds

Parameters:

seconds
PIC 9(n)v999, where n is a digit from 1 to 7

On Entry:

seconds
The number of seconds.

Comments:

The amount of delay is not exact. It depends upon the particular machine configuration and the load on the machine.
Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$GetEnv

Returns the value of an environment variable.
Note: When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$GetEnv" USING name, value [, return]

Parameters:

name
PIC X(n)
value
PIC X (n)
return
PIC 9(n) BINARY, where n can be a digit from 1 to 9

On Entry:

name
The name of the environment variable.

On Exit:

value
The value of the environment variable, returned from the call.
return
The result code returned from the call: zero for success and non-zero for failure.

Comments:

On UNIX, environment variable names are case-sensitive. On Windows, environment variable names are not case-sensitive.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$GetLastFileName

Retrieves the last filename used in a COBOL I/O statement (including OPEN and CLOSE).

Syntax:

Note: When calling this routine, ensure you are using the 1024 calling convention.
CALL "C$GetLastFileName" USING filename

Parameters:

filename
PIC X(30)

On Exit:

filename
The name of the filename used in the last I/O operation.

Comments:

For REWRITE and WRITE statements, the COBOL filename associated with the specified file record-name is provided.

If the filename is longer than 30 characters, it is truncated to the right.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$GetLastFileOp

Retrieves the last COBOL I/O operation performed.

Syntax:

Note: When calling this routine, ensure you are using the 1024 calling convention.

Use this library routine within a declarative procedure after an I/O error has occurred.

CALL "C$GetLastFileOp" USING operation

Parameters:

operation
PIC X(20)

On Exit:

operation
The name of the last I/O operation performed. The valid operations returned are:
  • Close
  • CloseUnit
  • Delete
  • DeleteFile
  • DeleteRandom
  • Open
  • ReadNext
  • ReadPrevious
  • ReadRandom
  • Rewrite
  • RewriteRandom
  • Start
  • Unlock
  • Write
  • WriteRandom

Comments:

If the operation is longer than 20 characters, it is truncated to the right.

If the value SPACES is returned that indicates that no operation is available.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$GetNativeCharset

Retrieves information about the native character set in effect for the current run unit.
Note: When calling this routine, ensure you are using the 1024 calling convention.

The native character set specifies how non-numeric data is encoded in memory and on data files.

Syntax:

CALL "C$GetNativeCharset" USING charset-name [, codepage-number]

Parameters:

charset-name
PIC X(n)
codepage-number
PIC 9(n)

On Exit:

charset-name
The name of the character set in use for the current run unit after the call.
Note: For Windows, the name will have a value of “ANSI” or “OEM”. On UNIX, the value will be “NONE”.
codepage-number
The codepage number of the character set in use for the current run unit after the call.
Note: For Windows, the codepage number will be the system ANSI codepage number if charset-name contains “ANSI” and will be the system OEM codepage number if charset-name contains “OEM”. On UNIX, the value will be 0.

Comments:

The native character set for a run unit on Windows can be either ANSI or OEM.

The native character set for a run unit on UNIX is determined by the locale settings for the system.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalAnd

Performs a bitwise logical AND operation on two or more non-numeric or numeric operands.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalAnd"
[GIVING result]
 USING operand1 {operand2} ...

Parameters:

result
PIC 9(n)
operand1
A non-numeric or numeric operand
operand2, 3, etc
A non-numeric or numeric operand that must be of the same data type as operand1
Note: If any non-numeric operand2 is shorter than operand1, it is assumed to be padded on the right with binary zeroes.

On Entry:

operand1, 2, 3, etc
Non-numeric or numeric operands, which must be of the same data type as operand1.

On Exit:

result
The result of the operation or operand1.

Comments:

For non-numeric USING operands, the bitwise logical AND of all the operands replaces the value of operand1. The value of result is set to a non-zero value if any character of operand1 is non-zero after the operation completes and zero otherwise.

For numeric USING operands, each operand is converted, if necessary, to a 32-bit binary integer. These 32-bit binary values are logically ANDed together. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand1 is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand1.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalComplement

Performs a bitwise logical One's Complement operation on a non-numeric or numeric operand.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalComplement"
[GIVING result]
 USING operand

Parameters:

result
PIC 9(n)
operand
A non-numeric or numeric operand

On Entry:

operand
A non-numeric or numeric operand.

On Exit:

result
The result of the operation or operand.

Comments:

If operand refers to a non-numeric data item, the bitwise logical One’s Complement of the value of operand replaces the value of operand. The value of result is set to a non-zero value if any character of operand is non-zero after the operation completes and zero otherwise.

If operand refers to a numeric data item, the operand is converted, if necessary, to a 32-bit binary integer. The 32-bit binary value is logically One’s Complemented. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalOr

Performs a bitwise logical OR operation on two or more non-numeric or numeric operands.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalOr"
    [GIVING result]
     USING operand1 {operand2} ...

Parameters:

result
PIC 9(n)
operand1
A non-numeric or numeric operand
operand2, 3, etc
A non-numeric or numeric operand that must be of the same data type as operand1
Note: If any non-numeric operand2 is shorter than operand1, it is assumed to be padded on the right with binary zeroes.

On Entry:

operand1, 2, 3, etc
Non-numeric or numeric operands, which must be of the same data type as operand1.

On Exit:

result
The result of the operation or operand1.

Comments:

For non-numeric USING operands, the bitwise logical inclusive OR of all the operands replaces the value of operand1. The value of result is set to a non-zero value if any character of operand1 is non-zero after the operation completes and zero otherwise.

For numeric USING operands, each operand is converted, if necessary, to a 32-bit binary integer. These 32-bit binary values are logically inclusive OR'd together. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand1 is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand1.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalXor

Performs a bitwise logical exclusive OR operation on two or more non-numeric or numeric operands.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalXor"
    [GIVING result]
     USING operand1 {operand2} ...

Parameters:

result
PIC 9(n)
operand1
A non-numeric or numeric operand
operand2, 3, etc
A non-numeric or numeric operand that must be of the same data type as operand1
Note: If any non-numeric operand2 is shorter than operand1, it is assumed to be padded on the right with binary zeroes.

On Entry:

operand1, 2, 3, etc
Non-numeric or numeric operands, which must be of the same data type as operand1.

On Exit:

result
The result of the operation or operand1.

Comments:

For non-numeric USING operands, the bitwise logical exclusive OR of all the operands replaces the value of operand1. The value of result is set to a non-zero value if any character of operand1 is non-zero after the operation completes and zero otherwise.

For numeric USING operands, each operand is converted, if necessary, to a 32-bit binary integer. These 32-bit binary values are logically exclusive OR'd together. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand1 is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand1.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalShiftLeft

Performs a logical shift left operation on a non-numeric or numeric operand.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalShiftLeft"
[GIVING result]
 USING operand [shiftcount]

Parameters:

result
PIC 9(n)
operand
A non-numeric or numeric operand
shiftcount
PIC 9(n)

On Entry:

operand
A non-numeric or numeric operand.
shiftcount
The number of positions to shift during the operation.

On Exit:

result
The result of the operation.

Comments:

If operand refers to a non-numeric data item, the value of the data item is shifted left by the number of bit positions specified by shiftcount. Any bits shifted off the left end are lost and zero-valued bits are shifted into the right end. The value of result is set to a non-zero value if any character of operand is non-zero after the operation completes and zero otherwise.

If operand refers to a numeric data item, the operand is converted, if necessary, to a 32-bit binary integer. The 32-bit binary value is logically shifted left by the number of bit positions specified by shiftcount. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$LogicalShiftRight

Performs a logical shift right operation on a non-numeric or numeric operand.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$LogicalShiftRight"
[GIVING result]
 USING operand [shiftcount]

Parameters:

result
PIC 9(n)
operand
A non-numeric or numeric operand
shiftcount
PIC 9(n)

On Entry:

operand
A non-numeric or numeric operand.
shiftcount
The number of positions to shift during the operation.

On Exit:

result
The result of the operation.

Comments:

If operand refers to a non-numeric data item, the value of the data item is shifted right by the number of bit positions specified by shiftcount. Any bits shifted off the right end are lost and zero-valued bits are shifted into the left end. The value of result is set to a non-zero value if any character of operand is non-zero after the operation completes and zero otherwise.

If operand refers to a numeric data item, the operand is converted, if necessary, to a 32-bit binary integer. The 32-bit binary value is logically shifted right by the number of bit positions specified by shiftcount. If the GIVING phrase is specified, the result of this operation is stored in result and the value of operand is not modified. If the GIVING phrase is not specified, the result of this operation is stored in operand.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$NARG

Returns the number of parameters passed in the USING phrase of a CALL statement to the subprogram that contains the call to C$NARG.

Arguments specified explicitly as OMITTED in the USING list of the CALL statement are included in the count. The GIVING argument is not included in the count.

Note: When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "C$NARG" USING parameter-count

Parameters:

parameter-count
PIC 9(3) BINARY, COMP-4 or COMP-1

On Exit:

parameter-count
The number of parameters passed.
Parent topic: RM/COBOL Library Routines
Related reference
The CALL Statement
Related information
Call Conventions for Interfacing with Mixed Languages


C$OSLockInfo

Returns the process ID of the process that has the record locked when a lock request fails. This routine should be called immediately after a lock request has failed.
Note: When calling this routine, ensure you are using the 1024 calling convention.
Note: This routine is supported on UNIX only.

Syntax:

CALL "C$OSLockInfo" USING processid

Parameters:

processid
A four-byte, unsigned COMP-4 numeric item.

On Exit:

processid
The ID of the process that has the record locked.

Comments:

This routine will return a zero if run on Windows.

Parent topic: RM/COBOL Library Routines


C$SecureHash

Produces a 20-byte message digest from an input text string using the secure hash algorithm (SHA-1).
Note: When calling this routine, ensure you compile using DIALECT"RM".

Syntax:

CALL "C$SecureHash" USING message-text [message-length]
                    GIVING message-digest

Parameters:

message-text
PIC X(n)
message-length
PIC 9(n)
message-digest
PIC X(n)

On Entry:

message-text

Its value is the input text string to the secure hash algorithm. While the secure hash algorithm supports messages of length 2**64 or less bits (2**61 or less bytes), this implementation is limited to messages of length 2**32 or less bits (2**29 or less bytes).

message-length

Its value specifies the number of bytes of message-text to be considered when producing the message digest. Thus, the value must be less than or equal to the length of data item referenced by message-text. If message-length is omitted, the entire value of the data item referenced by message-text is used, as if LENGTH OF message-text had been specified for message-length.

On Exit:

message-digest

It must be an identifier that references a nonnumeric data item of exactly 20 bytes in length. The message digest result from the secure hash algorithm is returned in the referenced data item. The message digest value is stored in the form most significant byte at lowest address to least significant byte at highest address regardless of the memory architecture of the machine on which C$SecureHash is called.

When there is insufficient memory for C$SecureHash to do its work, the contents of message-digest are set to all binary zeroes. This only occurs when a memory area slightly larger than the size of the message text cannot be allocated. The secure hash algorithm used by C$SecureHash, other than the length limitation, is the one defined as the secure hash standard by Federal Information Processing Standard (FIPS) Publication 180-1, which is often referred to as SHA-1.

Comments:

One example of the usefulness of a message digest is storing a password in a secure form. Since message-digest is produced using a one-way hash of the password, it is computationally infeasible to recover the password from the message-digest value. (However, if the password is easy to guess or find in a dictionary, a computer program can be used to search for a password that hashes to a given message-digest value.)
Note: The input text string “abc” (length = 3 bytes) produces the hash value:

x"A9993E364706816ABA3E25717850C26C9CD0D89D"

Since this is a well-known test result for the secure hash algorithm (documented in FIPS Pub 180-1), “abc” is not recommended as a password value. Message digests are also often used to verify that a message has not been changed from its original value. This involves computing the message-digest of the original message-text and transmitting it in a secure manner, either on a separate secure channel or by using encryption of message-digest to guarantee that it is not modified during transmission. The receiver of the message can then compute the message digest from the received message-text and verify that the resulting message-digest matches the one supplied. If they match, it is extremely unlikely that the message text has been modified during transmission.

Parent topic: RM/COBOL Library Routines


C$SetEnv

Sets or clears the value of an environment variable.
Note: When calling this routine, ensure you are using the 1024 calling convention.

Setting the value of an environment variable with C$SetEnv updates the corresponding environment variable immediately in the process space of the current run unit. Thus, when the RM/COBOL runtime system uses environment variables for such actions as file access name resolution, the call to C$SetEnv will have an immediate effect on that run unit.

Syntax:

CALL "C$SetEnv" USING name, value [, return]

Parameters:

name
PIC X(n)
value
PIC X(n)
return
PIC 9(n) BINARY, where n can be a digit from 1 to 9

On Entry:

name
The name of the environment variable to set or clear.
value
The value to which the environment variable is set. A value of SPACES indicates that the environment variable should be deleted.

On Exit:

return
The result code returned from the call: zero for success and non-zero for failure.

Comments:

On UNIX, environment variable names are case-sensitive. On Windows, environment variable names are not case-sensitive.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


C$RERR

Returns the expanded I/O completion status, based on an error code received at run-time.

This routine returns either a four-character or an eleven-character extended status code, depending upon the length of the data item specified in the USING phrase. This status is for the last attempted I/O operation. The value returned conforms to ANSI COBOL 1985.

Syntax:

CALL "C$RERR" USING extended-status

Parameters:

extended-status
PIC X(4) or PIC X(11)

On Exit:

extended-status
The data item into which the expanded I/O completion status is stored in ASCII characters.

Comments:

If extended-status is four characters in length, the first two character positions contain the same digits as would the file status data item on completion of the I/O operation. The last two character positions provide additional information about the file status. In cases where only two digits for a status are shown, the last two character positions will contain ASCII zeroes. Although most statuses contain only the decimal digits 0 to 9, note that the hexadecimal digits A to F are possible in some character positions. Refer to Appendix A: Runtime Messages of the RM/COBOL User's Guide for a full list of status codes.

If extended-status is eleven characters in length, the first two character positions (positions one and two) contain the same digits as would the file status data item on completion of the I/O operation. In cases where Appendix A shows only two digits for a status, the remaining nine character positions contain ASCII blanks. In cases where Appendix A shows four digits for a status, character position three contains an ASCII comma, character positions four and five contain the last two digits of the status, and the remaining six character positions contain ASCII blanks. For permanent errors, that is, when the first two digits are 30, character position three contains an ASCII comma, character positions four and five contain a two-digit OS code (see the table below), character position six contains an ASCII comma, and character positions seven through eleven contain a five-digit, OS-specific error code. Refer to the Input/Output Errors section of the RM/COBOL User's Guide.

Table 1. The two-digit OS codes
Code | Description
00 | Unknown OS error
01 | File Manager Detected error
04 | UNIX error
06 | Btrieve error
10 | Open File Manager error
11 | C Library error
12 | MS-Windows error
15 | RM/InfoExpress Server error
16 | RM/InfoExpress Client error
21 | RM/InfoExpress WinSock error
Parent topic: RM/COBOL Library Routines


DELETE

Deletes a file.
Note: When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "DELETE" USING file-name [exit-code]

Parameters:

file-name
PIC X(n)
exit-code
PIC S9(4) BINARY

On Entry:

file-name
The full or relative pathname of the file to be deleted.

On Exit:

exit-code
The exit code of the command upon return from the operating system: zero for success and non-zero for failure.

Comments:

The values for the old-name parameter may be quoted with double quotes (") or single quotes ('). When the name is quoted, the quotes are removed, but the name is not otherwise modified. If the name is not quoted, the first control character terminates the name on Windows and the first white space character terminates the name on UNIX. On Windows, trailing spaces are removed from unquoted names.

The old-name data item must be less than 1024 characters in length.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


RENAME

Renames a file.
Note: When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "RENAME" USING old-name new-name [exit-code]

Parameters:

old-name
PIC X(n)
new-name
PIC X(n)
exit-code
PIC S9(4) BINARY

On Entry:

old-name
The source filename.
new-name
The target filename.

On Exit:

exit-code
The exit code of the command upon return from the operating system: zero for success and non-zero for failure.

Comments:

The values for the old-name and new-name parameters may be quoted with double quotes (") or single quotes ('). When the name is quoted, the quotes are removed, but the name is not otherwise modified. If the name is not quoted, the first control character terminates the name on Windows and the first white space character terminates the name on UNIX. On Windows, trailing spaces are removed from unquoted names.

The old- and new-name data item must be less than 1024 characters in length.

Parent topic: RM/COBOL Library Routines
Related information
Call Conventions for Interfacing with Mixed Languages


SYSTEM

Executes an arbitrary operating system command.
Restriction: This routine is supported in native COBOL only.

When calling this routine, ensure you are using the 1024 calling convention.

Syntax:

CALL "SYSTEM" USING command-line [repaint-screen] [exit-code]

Parameters:

command-line
PIC X(n)
repaint-screen
PIC X
exit-code
PIC S9(4) BINARY

On Entry:

command-line
An alphanumeric data item that contains the command line to be passed to the operating system. The command is the contents of command-line with trailing white spaces suppressed. The command does not need to be null-terminated.
repaint-screen
This parameter is ignored in this COBOL system.

On Exit:

exit-code
The exit code for the command, returned from the operating system. The value returned is dependent on the underlying operating system. A value of 0, however, indicates success and a non-zero value indicates an error.

Comments:

The implementation of this library routine is identical to the existing Micro Focus version of SYSTEM.

This version of the SYSTEM command is used when the calling convention is 1024. This may be specified explicitly in the CALL, by using the DEFAULTCALLS Compiler directive, or by specifying the DIALECT"RM" Compiler directive.

Parent topic: RM/COBOL Library Routines
Related reference
SYSTEM


RM/COBOL File Handling

When you migrate your RM/COBOL applications to Visual COBOL, you can continue to use the same data files.

  • Configuring Access to RM/COBOL Indexed Data Files
    You can access RM/COBOL indexed data files by mapping the filename to a compatible index format in the Micro Focus File Handler configuration file.
  • File Limits
    When using RM/COBOL indexed files in Visual COBOL, there are a number of file limits that affect file handling operations.
  • RM/COBOL File Status Codes
    You can set the file handler to return 2-digit RM/COBOL file status codes. You can also return 4-character or 11-character extended file status code, using the C$RERR standard library routine.
  • Debugging JVM COBOL Using RM/COBOL Indexed Files
    When debugging managed COBOL applications containing RM/COBOL indexed files, you must set the RMFM_PRETEND_FORCE_CLOSED environment variable to avoid the file becoming corrupt when debugging ends.
  • Enabling CTF to Trace RM/COBOL Data Files
    Enable the Micro Focus Consolidated Tracing Facility (CTF) to trace activity with your RM/COBOL data files.
  • Data File Utilities
    Run utilities against your RM/COBOL data files, for example, to fix data corruption.
Parent topic: Compatibility with RM/COBOL


Configuring Access to RM/COBOL Indexed Data Files

Note: For these options to take effect, the ACUFH configuration option must be set ON; by default, this is ON. For these options to take effect under Enterprise Server, ESACUFH must also be set ON; by default, this is OFF.

To handle RM/COBOL indexed data files, you map a file to IDXFORMAT=21 in the File Handler configuration file.

Within the configuration file, you can apply IDXFORMAT 21 to all files in a particular folder, all files with a specific file extension, or a single file. See Format of the Configuration File for the tags that you can use for the mapping, and the order in which settings in these tags are applied.

The order that the mapping is applied is important, as conflicting settings can be overwritten; for example, the following excerpt of the configuration file sets all files in usr/files/rmfiles to IDXFORMAT 21 and all files with a .DAT extension to IDXFORMAT 17:

[FOLDER:usr/files/rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

If there is a .DAT file in usr/files/rmfiles, the mappings are applied according to the type of tag. In the case above, mappings in the extension tag are applied after mappings in the FOLDER tag, and so the .DAT file in that directory has an IDXFORMAT of 17.

By default, the File Handler handles all sequential and relative data files, but if you want to handle them through the RM/COBOL file handler, use the INTEROP=RM configuration option; however, in cases where the INTEROP and IDXFORMAT mappings conflict, the INTEROP setting will override IDXFORMAT for your RM/COBOL indexed data files.

Parent topic: RM/COBOL File Handling
Related reference
Format of the Configuration File
IDXFORMAT
INTEROP
Debugging JVM COBOL Using RM/COBOL Indexed Files
ACUFH
ESACUFH


File Limits

When using RM/COBOL indexed files in Visual COBOL, there are a number of file limits that affect file handling operations.

The following limits are in addition to the ones imposed in Visual COBOL; see Limits in the File Handling Reference section.

Note: The limits listed on this page override any listed in the File Handling Reference section when handling RM/COBOL indexed files.
Maximum record size: | 64 MB (67,108,864)
Maximum number of indexed keys: | 1 primary + 119 alternates
Maximum number of segments per key: | 16
Maximum indexed key size: | 250 bytes
Parent topic: RM/COBOL File Handling
Related reference
Limits


RM/COBOL File Status Codes

RM/COBOL file status codes take a 2-digit form in the file status data item (by combining the values of the Status Key 1 and Status Key 2 columns), or a 4-character or 11-character extended file status code that can be retrieved using the C$RERR standard library routine.

RM/COBOL file status codes are always returned when the FILETYPE=21 Compiler directive is in effect. If you set the DIALECT"RM" Compiler directive, this automatically sets FILETYPE=21, thus producing RM/COBOL file status codes.

If you are running under a different dialect or FILETYPE setting, but want to continue to return RM/COBOL file status codes, do the following:
  • Set environment variable COBFSTATCONV to the RM/COBOL setting:
    set COBFSTATCONV=rmstat
  • Set the COBFSTATCONV Compiler directive.

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.

Status Key 1 | Status Key 2 | Extended File Status Code | Description
3 | 5 | 9/013 | File not found.
3 | 5 | 9/188 | Filename too large.
3 | 7 | 9/035 | Incorrect access permission.
3 | 7 | 9/037 | File access denied.
3 | 8 | 9/138 | File is closed with lock - cannot open.
3 | 8 | 9/210 | File is closed with lock.
4 | 1 | 9/141 | File already open - cannot be opened.
4 | 2 | 9/142 | File not open - cannot be closed.
4 | 3 | 9/143 | REWRITE/DELETE not after successful READ
4 | 6 | 9/146 | No current record defined for sequential read.
4 | 7 | 9/147 | Wrong open or access mode for READ/ START.
4 | 8 | 9/148 | Wrong open or access mode for WRITE.
4 | 9 | 9/149 | Wrong open or access mode for REWRITE/ DELETE.
9 | 3 | 9/065 | File locked.
9 | 8 | 9/071 | Bad indexed file format.
9 | 8 | 9/139 | Record length or key inconsistent.
9 | 9 | 9/068 | Record is locked.
Parent topic: RM/COBOL File Handling
Related concepts
C$RERR
Related information
Data Related


Debugging JVM COBOL Using RM/COBOL Indexed Files

When you debug a JVM COBOL application, there is a danger that an RM/COBOL indexed file will become corrupted when debugging ends, as the file is not closed correctly by default.

To ensure the file is closed correctly when debugging ends, you must set the RMFM_PRETEND_FORCE_CLOSED=YES environment variable.

Parent topic: RM/COBOL File Handling
Related reference
Configuring Access to RM/COBOL Indexed Data Files


Enabling CTF to Trace RM/COBOL Data Files

Enable the Micro Focus Consolidated Tracing Facility (CTF) to trace activity with your RM/COBOL data files.

To enable CTF:

  • Set the following environment variables:

    set MFTRACE_CONFIG=ctf.cfg
set MFTRACE_LOGS=pathname   *> if not set, logs are stored in the current folder.

  • In ctf.cfg, set the following:

    mftrace.dest                = textfile
mftrace.level.mf.rts        = info
mftrace.comp.mf.rts#eprintf = true
  • Set the following environment variable:
    set A_CONFIG=rmfm.cfg    *> rmfm is your RMFM configuration file

  • In rmfm.cfg, set the following:

    DEFAULT_FILESYSTEM RMFM
FILE_TRACE 3   *> values 0-9 set amount of activity traced.

When you run your program, a log-file is produced that includes the activity with the RM/COBOL data files.

For more information on CTF, see Introduction to the Consolidated Tracing Facility.

Parent topic: RM/COBOL File Handling
Related information
The Consolidated Tracing Facility


Data File Utilities

The following utilities are available to use with your RM/COBOL data files:

  • Indexed File Recovery (recover1) utility
    The recover1 utility is a standalone program that recovers data stored in an RM/COBOL indexed file.
Parent topic: RM/COBOL File Handling


Indexed File Recovery (recover1) utility

The recover1 utility recovers data stored in an RM/COBOL indexed file . It is a standalone program; that is, it does not require use of the Runtime Command to be executed.

Note:
  • Unless specifically stated otherwise, the name recover1 refers to both the UNIX (recover1) and Windows (recover1.exe) versions of the recover1 program.
  • If the output window of the Windows version of the recover1 program disappears upon successful completion and you want that window to remain visible, set the Persistent property to True for the recover1 program.
  • The recover1 utility does not use the environment variable RUNPATH to locate files. It is best to specify the full pathname of the indexed file to be recovered or to run recover1 from the current directory in which the indexed file resides.
  • Recovery command
  • Recovery command options
  • Recovery process description
  • Recovery support module version errors
  • Recovery example
  • Recovery program error messages
Parent topic: Data File Utilities


Recovery command

The Indexed File Recovery (recover1) utility is executed by issuing the following command:

recover1 indexed-file drop-file [options] ...
indexed-file
The filename of the indexed file to be recovered. The name is not resolved through any environment variables.
drop-file
The name of the file where recover1 places any unrecoverable records found in the indexed file, as discussed in Recovery process description. If drop-file specifies an environment variable name, the environment variable value will be resolved before opening the dropped record file.
options
Zero or more command line options, as described in Recovery command options. Options are specified with letters that must be preceded with a hyphen (-) or a slash (/). Option letters may be specified in uppercase or lowercase. Certain option letters allow an optional pathname as part of the option format. The presence or absence of the pathname is determined by whether or not the next non-white space character following the option letter is a hyphen or slash, whichever one was used preceding the option letter.
Note: The option introducer character slash is supported for Windows compatibility and should not be used on UNIX, where it can be confused with an absolute pathname; that is, a pathname that begins with a slash. Nevertheless, either the hyphen or the slash may be used to introduce option letters on Windows and UNIX. In the option formats given, only the hyphen is shown, but the hyphen may be replaced with a slash.
Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command options
Recovery process description
Recovery support module version errors
Recovery example
Recovery program error messages


Recovery command options

Recovery command options can be specified in either of the following two ways:

  • Depending on the operating system, they can be placed into the Windows registry or the UNIX resource file:
    • In the Windows registry, the Command Line Options property provides command line options for the Indexed File Recovery utility when Recovery is selected on the Select File tab of the RM/COBOL Properties dialog box.
    • In the UNIX resource file, the Options keyword, described in Command Line Options, provides command line options for the Indexed File Recovery utility in the global resource file /etc/default/recover1rc and the local resource file ~/.recover1rc.
  • They can be specified in the Recovery Command itself.

The following options may be specified to modify the behavior of the Indexed File Recovery (recover1) utility.

I
Use the I option to cause recover1 to test only the file integrity and then stop. The file will not be modified in any way. Specifying the I option causes both the T and Z options to be ignored. If no problems are discovered, the exit code is set to 0. If a problem is discovered, the exit code is set to 1. The I option has the following format:
-I

The default is for recover1 to do a complete recovery of the indexed file if the file is marked as needing recovery. See the Y and Z options in this topic for additional options that modify the behavior of the Indexed File Recovery utility.

Note: The integrity scan is a quick test of the file and is not comprehensive. Some problems, such as records with invalid duplicate keys, will not be detected. Indexed files with no errors detected by the integrity scan may still receive “98” errors or other I/O errors.
K
Use the K option to indicate that the Key Information Block (KIB) should be assumed to be invalid and, optionally, to specify a template file for recovering the KIB. The K option has the following format:
-K [template-file]

If no template-file is specified, the user will be prompted either for a template file or for enough information to rebuild the KIB. If template-file is specified, it should be the name of a valid indexed file with the same format as the file being recovered. This file will be used as a template. The required KIB information is read from the KIB of the template file. The template file can be a backup copy of the file being recovered, if the backup occurred before the file was damaged, or, it can be a file created by performing an OPEN OUTPUT in a COBOL program with the proper file control entry and file description entry for the file being recovered. An OPEN OUTPUT must have been performed on the template file, but it need not contain any records. A template file must be specified if the KIB is corrupt and the file uses either an enumerated code set or an enumerated collating sequence. The default is to check the KIB for validity and, if it is found to be invalid, prompt for either a template file or information to rebuild the KIB. The name of the template file is not resolved through any environment variables.

Warning: A template file with the wrong block size can cause the loss of a large percentage of the recoverable records in your file.
L
Use the L option to write information about errors encountered while recovering the file to a log file. The L option has the following format:
-L [log-file]

Only the first 100 errors will be logged. In addition to errors, a number of informational lines about the indexed file and its recovery are written to the log file, including information about sort memory (see the M option regarding sort memory). If log-file specifies an environment variable name, the environment variable value will be resolved before opening the log file; this allows the use of the name PRINTER to send the log information to the print device. If log-file is omitted in the L option, the default value of log-file is PRINTER. If the L option is not specified, the default is not to write a log file.

Note: Environment variables can be set using synonyms set in the Windows registry or the UNIX resource file.
M
Use the M option to specify the number of megabytes of memory to allocate to the sort algorithm used in phase 4, build node blocks. The M option has the following format:
-M [MB-of-memory]

where MB-of memory is a number in the range 0 to 2000. Allocating more memory generally results in faster execution of recover1 and causes fewer node blocks to be built. If this option is not specified, a suitable number will be computed; in this case, sort memory is limited to no more than 40 million bytes. When a log file is written (see the L option), a line is written into the log file to show the maximum effective sort-memory size. If the M option is specified without a number of megabytes, the default value of 50 is used.

Note: Specifying a number for MB-of-memory that is too large for your system may result in very poor system performance.
Q
Use the Q option to cause recover1 to perform its work without displaying information or asking the operator questions. The Q option has the following format:
-Q

If the file is marked as needing recovery, or has a non-zero Open For Modify Count, then it will be recovered. Otherwise, no action occurs. This behavior can be modified by using the Y option. The default is to display information and ask questions, which must be answered by the operator.

T
Use the T option to indicate that unused space should be truncated and returned

to the operating system. The T option has the following format:

-T

Specifying the T option will result in a minimal size indexed file, but may reduce performance if records are subsequently added to the indexed file. The default is not to truncate the file. When the file is not truncated, any empty blocks remain part of the file and are available for use in adding new records to the file.

Note: Some versions of UNIX do not support the operating system call required to

truncate a file.

Y
Use the Y option to cause recover1 to assume that the operator wants to answer “y” to all possible questions and therefore not stop to wait for a response. The Y option has the following format:
-Y

Using the Y option will cause a file to be recovered even if it is not marked for recovery, including the case of when the Q option is also specified. The default is to wait for a response from the operator after a question is displayed.

Z
Use the Z option to reset the Open For Modify Count to zero, without performing a full recovery. The Z option has the following format:
-Z

If the file is marked as needing recovery, the Z option is ignored. The default is to treat a non-zero Open For Modify Count as indicating that the file needs recovery.

Note: Use the Z option with caution. Resetting the Open For Modify Count to zero without performing a full recovery may leave the file in a corrupted state.
Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command
Recovery process description
Recovery support module version errors
Recovery example
Recovery program error messages


Recovery process description

If the recover1 program is successful, the exit code is set to 0. If the recover1 program is canceled by the operator, the exit code is set to 2. Otherwise, the exit code is set to 1.

You may produce a list of the support modules loaded by the recover1 program by defining the environment variable RM_DYNAMIC_LIBRARY_TRACE. The listing will indicate which Terminal Interface support module is used, only the terminfo module is included with Visual COBOL. The Automatic Configuration File module is not included with Visual COBOL. This information is most helpful when attempting to diagnose a problem with support modules.

Note: The information will be visible only if you enter the recover1 command without any parameters. In this case, recover1 will show the proper form for the command and the list of support modules.

The recover1 program attempts to recover the indexed file in place; that is, the program rebuilds the internal file structure in the actual file being recovered. If necessary, the Key Information Block (KIB) is rebuilt and any corrupted data blocks are repaired. Corrupt data blocks may result in loss of some data records. Because of this feature, it is strongly recommended that you either backup the file or copy the indexed file to be recovered to some other directory or pathname as additional security. Any records that cannot be successfully reindexed into the file due to invalid duplicate key values, or invalid record sizes, are decompressed (if compression is selected for the file), converted to the native code set, and then written to drop-file. recover1 should be able to handle most kinds of indexed file corruption problems, but some fatal errors may still cause the recovery to fail. Any fatal error is displayed and causes the program to terminate. Broken hardware should be suspected in many of these cases.

drop-file can be in fixed- or variable-length format; this is set by recover1 based on whether indexed-file is fixed- or variable-length format. Records placed in drop-file were those undergoing change at the time of the system failure that required recovery or have invalid record sizes. Investigate any records appearing in drop-file and make the appropriate corrections to indexed-file.

  • The four phases of processing
Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command
Recovery command options
Recovery support module version errors
Recovery example
Recovery program error messages


The four phases of processing

The recover1 program’s processing consists of up to four separate phases, which are run in the following order:

  1. Integrity Scan. If the Q option or Y option is specified, the Integrity Scan phase is disregarded unless it is forced to occur by the specification of the I option or L option. This phase reads the entire file in a forward direction checking for simple errors, and produces a summary report showing the state of the file and an estimate of the number of records recover1 can recover. The indexed file is not modified during this phase.
  2. Repair Blocks. The Repair Blocks phase, which is always run, reads and writes the file in a backward direction repairing corrupt data blocks, converting non-data blocks to empty blocks, and rebuilding some internal file structures.
  3. Move Data Blocks. The Move Data Blocks phase is run only when the truncate file

    option (T) is specified. This phase reads and writes parts of the file moving highnumbered data blocks (near the end of the file) to lower-numbered available blocks to maximize the amount of space at the end of the file that can be truncated and returned to the operating system when recover1 finishes.

  4. Build Node Blocks. The Build Node Blocks phase, which is always run, reads data blocks and writes node blocks in the file in a forward direction, rebuilding the entire node structure for each key of the file.
Note:
  • After the Integrity Scan phase, if the Estimated Recoverable records value is zero or very low, and the number of corrupt data blocks is very close to the total number of data blocks found, the number of keys that allow duplicates may be incorrect, either because the KIB is corrupt or the user provided incorrect key information to recover1.
  • After the Integrity Scan phase, if most of the blocks are invalid, the Disk Block Size or the Disk Block Increment may have been incorrectly specified or the KIB may be corrupt.
  • During the Repair Blocks phase, a count of blocks that could be read but not written may be displayed. This count may indicate the presence of a hardware problem with your disk.
Parent topic: Recovery process description


Recovery support module version errors

During initialization, the recovery utility locates and loads various support modules, and, on UNIX, the terminfo Terminal Interface support module. Also, at initialization, the recovery utility verifies that each support module is the correct version for the recovery utility. If a support module is not the correct version, the following message is displayed:

RM/COBOL: module-name version mismatch, expected 12.0n.nn,found n.nn.nn.

When the previous message is displayed, the recovery utility terminates with the following message:

Recover1: Error invoking mismatched recover1 and support module.
Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command
Recovery command options
Recovery process description
Recovery example
Recovery program error messages


Recovery example

An example run through the Indexed File Recovery utility is described in Figure 1 through Figure 4. The recovery session is started in this example by the following command:

recover1 master.inx dropout1

Figure 1 shows information about the file master.inx.

Under the name of the file to be recovered, a description of the state of the file is displayed. Any of the following messages may appear:

  • This file has not been marked as needing recovery!
  • The Open For Modify Count for this file is not zero: count
  • File has been marked as corrupted due to a previous error.
  • KIB is corrupt. Using template file: template-file
  • KIB is corrupt. Enter a template filename (press Enter for manual entry).

If the KIB is corrupt, and a template filename is not entered, recover1 will prompt the user for the required KIB information before continuing.

If more keys exist than can appear on this screen, as many as possible appear, after which you are asked if you want to see the remaining key descriptors. This continues until all keys are shown. You are then asked to verify that this is the file you want to recover. Entering N terminates the program. Entering Y continues the program.

                 Indexed File Recovery Utility
                   Recover1 for Visual COBOL
Indexed File: master.inx

This file has not been marked as needing recovery!

Disk Block Size:        1024   Minimum Record Length:  80
Disk Block Increment:   1024   Maximum Record Length:  80
Number of Index Blocks:  170   Number of Records:     150

  Key  Position Size Remarks
PRIME     1      8
    1     9      8
    2     17     8   duplicates allowed

Is this the file you wish to recover (y/n)?

Figure 1: Indexed File Recovery Utility: File Recovery Verification

Figure 2 shows a summary of the information that is gathered during the file integrity scan.

You are then asked if you would like to proceed with the recovery process. Entering N terminates the program. Entering Y continues the program. The “Average record length” is computed by adding the length of all the records in the file and dividing by the number of records. The “Average data size” is computed by adding the size that the record actually occupies in the file and dividing by the number of records. This size allows you to determine how much your data can be compressed.

                Indexed File Recovery Utility
                  Recover1 for Visual COBOL
Indexed File: master.inx

Drop File: dropout1

This file has not been marked as needing recovery!

Disk Block Size:        1024 Minimum Record Length:  80
Disk Block Increment:   1024 Maximum Record Length:  80
Number of Index Blocks:  170 Number of Records:     150
Phase: Integrity Scan        Estimated Recoverable: 150

           |   Total |   Total |   First |   Last  |
Block Type | Found   | Corrupt | Corrupt | Corrupt |
KIB        |     1   |       0 |         |         |
Data       |   102   |       0 |         |         |
Node       |    61   |       0 |         |         |
Empty      |     6   |       0 |         |         |
Invalid    |     0   |       0 |         |         |
Unreadable |     0   |       0 |         |         |

Average data size: 14, Average record length: 80
Do you wish to proceed with recovery (y/n)?

Figure 2: Indexed File Recovery Utility: recover1 Summary

Figure 3 shows the information that is displayed while recover1 is rebuilding the node blocks for the prime key.

                Indexed File Recovery Utility
                  Recover1 for Visual COBOL
Indexed File: master.inx

Drop File: dropout1

This file has not been marked as needing recovery!

Disk Block Size:        1024 Minimum Record Length:  80
Disk Block Increment:   1024 Maximum Record Length:  80
Number of Index Blocks:  170 Number of Records:     150
Phase: Build Node Blocks     Estimated Recoverable: 150

Key being processed:                        PRIME
Records recovered:                            100
Records written to drop file:
Block being processed:                         13
Number of data blocks moved (for truncate):     5

Figure 3: Indexed File Recovery Utility: recover1 Statistics

Figure 4 shows the information that is displayed after recover1 terminates successfully. The two lines regarding truncation are shown only when the T option is specified.

             Indexed File Recovery Utility
               Recover1 for Visual COBOL
Indexed File: master.inx

Drop File: dropped

This file has not been marked as needing recovery!

Disk Block Size:        1024 Minimum Record Length: 126
Disk Block Increment:   1024 Maximum Record Length: 126
Number of Index Blocks:  120 Number of Records:     100
Phase: Build Node Blocks     Estimated Recoverable: 100

Key being processed:                        PRIME
Records recovered:                            100
Records written to drop file:
Block being processed:                        120
Truncate option specified - number of data blocks moved:   4
Truncate action successful - new Number of Index Blocks: 112

Recovery successful.

Figure 4: Indexed File Recovery Utility: recover1 Finished Successfully

In the example shown in Figure 5, the KIB of the file has been corrupted, and key information must be entered for the file to be recovered. This example shows manual entry of KIB information, however, it is recommended that a template file be used with the -K option to recover the KIB information. Underlined characters have been entered by the user.

The recovery session is started by the following command:

recover1 master.inx dropout1 -k
Note: Entering incorrect information about how many keys, or which keys, can have duplicate values may cause unpredictable results.
             Indexed File Recovery Utility
                Recover1 for Visual COBOL
Indexed File: master.inx

Last error was 98,38 at 9:29 on 03-21-2008

Are any of the keys in this file segmented (split) (y/n)? y
Key #: PRIME Segment #: 2 Starting Position? 10 Length? 5
             Another Segment (y/n)? n
             Total Key Length = 13 Duplicates Permitted (y/n)? n
Another Key (y/n)? n

Figure 5: Indexed File Recovery Utility: Entering Key Information

Figure 6 shows an example of entering the remainder of the KIB information. Underlined characters have been entered by the user.

              Indexed File Recovery Utility
                 Recover1 for Visual COBOL
Indexed File: master.inx

Last error was 98,38 at 9:29 on 03-21-2008

Minimum Record Length (in bytes)? 80
Maximum Record Length (in bytes)? 80
Disk Block Size (in bytes)? 1024
User Block Size (1=none/2=in bytes/3=in records)? 1
Data Compression (y/n)? y    Space Character Value? 32   Zero Character Value? 48
Key Compression  (y/n)? y    Space Character Value? 32
File Version Number (0/2/3/4)? 4   Atomic I/O Enabled (y/n) y
File Lock Limit (in GB)? 2
Disk Block Increment (in bytes)?  1024
Allocation Increment (in blocks)? 8
Force Write Data Blocks (y/n)? n    Force Write Index Blocks (y/n)? n
Force to Disk (y/n)? n              Force File Closed (y/n)? n
Code Set (1=none/2=ASCII/3=EBCDIC)? 1
Collating Sequence (1=none/2=ASCII/3=EBCDIC)? 1

Is this information correct (proceed with recovery) (y/n)? y

Figure 6: Indexed File Recovery Utility: Entering KIB Information

After the key and KIB information has been successfully entered, the recovery process proceeds the same as before, beginning with Figure 1. If a template file had been specified on the command line or a template filename had been entered when prompted, the screens prompting for the key and KIB information would not have been displayed. A template file must be specified if the KIB is corrupt and the file uses either an enumerated code set or an enumerated collating sequence.

Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command
Recovery command options
Recovery process description
Recovery support module version errors
Recovery program error messages


Recovery program error messages

Error status initializing file manager

recover1 was unable to initialize the RM/COBOL file management system for the reason indicated by status. The usual cause for this error is that a buffer pool has been configured that is too large to be allocated. See the BUFFER-POOL-SIZE keyword of the RUN-FILES-ATTR configuration record for instructions on changing the buffer pool size.

Truncate option not supported

recover1 detected that the truncated function was not supported on the system when the user requested file truncation. Truncation of the file is not possible.

recovery terminating - no records recoverable!

recover1 detected corruption in the indexed file and no records could be recovered. In this case, recover1 terminates at the end of the integrity scan to protect the user from erroneously deleting all the records from the file. This error may indicate that the block size, the block size increment, or the number of keys that allow duplicates has been incorrectly specified, or the KIB may be corrupt.

Error status on template file

recover1 was unable to initialize the RM/COBOL file management system for the reason indicated by status. The usual cause for this error is that a buffer pool has been configured that is too large to be allocated. See the BUFFER-POOL-SIZE keyword of the RUN-FILES-ATTR configuration record for instructions on changing the buffer pool size. recover 1 detected an error in the KIB of the template file specified by the user. The user may enter another template file, may enter the KIB information manually, or may enter a Ctrl- C to terminate recover 1.

Cannot write near end of file - check "ulimit"

recover1 detected that blocks near the end of the file can be read but not written, but other blocks of the file may be both read and written. This error may indicate that the operating system file size limit (ulimit) may be smaller than the size of the file. Set the file size limit correctly or use an account with sufficient privileges and run recover1 again.

Parent topic: Indexed File Recovery (recover1) utility
Related concepts
Recovery command
Recovery command options
Recovery process description
Recovery support module version errors
Recovery example


RM/Panels

RM/COBOL's RM/Panels is a graphical user interface that uses panels (screens) and controls defined in a Panel Library file. The RM/Panels application interacts with the panels and controls through a RM/COBOL program runpan2.cob. The runpan2 application has been converted to be compatible with Micro Focus COBOL, so that RM/COBOL applications that use RM/Panels can be converted to run in Visual COBOL, when compiled with the Dialect"RM" Compiler directive.

An RM/Panels application has the following:

  • Panel Library: The panel library file is a binary file. It is loaded at run time by the runpan2 program. Each panel definition within the file includes information on sizes, background text, attributes, and controls. The name of the library file is passed to runpan2 by setting the value of RMP-LIBRARY. The RM/COBOL library file is used without any modifications because runpan2 expects the file format to be in RM/COBOL format. Refer to your RM/Panels Reference Manual for information on the RM/Panels Designer and the creation and editing of the Panel Library.
  • Working Storage definition for each panel: Generally, each panel will have a <panelname>.ws file associated with it. The fields in the file represent the data for the controls defined on the panel. This file should not be edited manually; the fields are generated by the RM/Panels Designer.
  • Procedural code for each panel: Each panel will also have procedural code in a <panelname>.prc file that defines the functions for interacting with the panel. This file can be edited manually, if necessary.
  • rmpanels.ws: This copybook contains the fields for controlling the panels and controls, such as the current and next field values. This file also specifies the name of the program that loads the library file. The RMP--RUNTIME field value should be set to either:
    • runpan2.dll on Windows; or
    • cobrunpan2 (32-bit), or cobrunpan264 (64-bit) on UNIX

In addition to these elements taken from the original RM/COBOL application, the following additional elements are required for the application to run correctly in Visual COBOL:

  • ADISCTRL: This file specifies a number of settings that control how ADIS handles ACCEPT and DISPLAY commands. The instance of the file in the application's path needs to have the RM-Panels configuration selected.
  • The Dialect"RM" Compiler directive: This directive will most likely already be set as part of the conversion process from RM/COBOL. If this is not set, some features of ADIS and runpan2 may not behave as expected.

For more details on the actual conversion process, see Conversion Example.

  • Restrictions and Limitations
  • Converting RM/Panels Applications
  • Conversion Example: Using
  • Writing Programs
  • Appendix A: Master Copy File RMPANELS.WS
  • Appendix B Standard Utility, and Extended Runtime Functions and Parameters
Parent topic: Compatibility with RM/COBOL


Restrictions and Limitations

The following restrictions apply when using applications that contain RM/Panels

No Panel Editor in Visual COBOL
The RM/Panels product includes both a runtime and a designer/editor of the panels. The RM/Panels Designer, the application that enables you to create or modify RM/Panels library files, is not available in Visual COBOL. However, the RM/COBOL version can still be used to modify the library files.
No End-User Panel Editor
In RM/COBOL, you can enable an option to bring up the Panel Editor at run-time. This is not supported in the Visual COBOL version of RM/Panels.
Character-based controls only
On Windows, controls are always character-based. In some versions of RM/COBOL, certain controls could be converted on-the-fly to Windows controls. This is not supported in the Visual COBOL version of RM/Panels. (UNIX versions have never had this feature.)
Mouse support
On UNIX platforms, there is no mouse support for RM/Panels applications.
RM/Panels applications not interchangeable between platforms
RM/Panels applications designed for Windows are not compatible on UNIX platforms and vice versa. This is because of the difference in line terminators and line draw characters between the two platforms.
Panels 2.0 support only
There were significant changes to the Panels library file between versions 1.0 and 2.0. The runpan2 program will support the Panels 2.0 library file only. Refer to the RM/Panels Reference Manual for instruction on converting from version 1.0 to 2.0.
Parent topic: RM/Panels


Converting RM/Panels Applications

Converting an existing RM/COBOL program to run in Visual COBOL can be simple or complex, depending on the portability of the syntax and data types used in the program. Generally, the Dialect"RM" Compiler directive is sufficient to allow an RM/COBOL program to compile in Visual COBOL.

See the section Converting RM/COBOL Applications for details about converting the application to run under Visual COBOL.

The additional steps you need to take for applications that include RM/Panels are:

ADISCTRL
The ADISCTRL configuration file controls how the Micro Focus Adis routine handles ACCEPT and DISPLAY statements. It contains a configuration required for applications using RM/Panels syntax.
The default location for this file is /opt/microfocus/VisualCOBOL/etc. If this location is not writable, copy the file to another location, and edit and use that copy in your application.
The first ADISCTRL file in the executable path should be set to the predefined configuration RM-Panels in order for the display and keyboard behaviour to function correctly. This is done by running the adiscf.exe utility while in the directory of the ADISCTRL file you plan to use.
Note: ADISCTRL also contains a general RM2VCOB configuration for modernizing RM/COBOL applications, but it is the RM-Panels configuration that you must use if your application contains RM/Panels syntax.
RMP--RUNTIME
This is a field declared in the rmpanels.ws copybook that specifies the runpan2 library. You need to edit this value in the copybook from your RM/COBOL application and ship it with the other converted files for the application.
RMP--RUNTIME is set to runpan2 in the original RM/COBOL rmpanels.ws copybook. In Visual COBOL, the value needs to identify the library that contains the runpan2 entry point. On Windows, that is runpan2.dll (the .dll extension is required to locate the library file); on UNIX, that is cobrunpan2 (32-bit) or cobrunpan264 (64-bit) (do not include the .so suffix of the library file).
Parent topic: RM/Panels


Conversion Example: Using

The following is an example conversion from RM/COBOL to Visual COBOL using as the IDE.

The application in this example is called qdemo, and has two panels: custinfo and message.

The following files are from the original RM/COBOL application:

  • qdemo.cbl: Main COBOL program file
  • custinfo.prc: Procedural code for the custinfo panel
  • cusinfo.ws: Data for the custinfo panel
  • message.prc: Procedural code for the message panel
  • message.ws: Data for the message panel
  • rmpanels.ws: Control data for RM/Panels
  • qdemo.lib: RM/Panels library file

The following files are available from Visual COBOL:

  • ADISCTRL: The ADIS configuration file for ACCEPT/DISPLAY statements.
  1. Download the Tutorial Files
    The files required for this tutorial are available on the Micro Focus Community web site.
  2. Configure Adis Support for RM/Panels
    After importing the Adis configuration file, you must configure it to handle the enhanced ACCEPT and DISPLAY statements in a way that RM/Panels is expecting it to.
Parent topic: RM/Panels


Download the Tutorial Files

The source files required to run the tutorial are available from the Micro Focus Community web site.

Note: To download the files, you do not need to be a registered user of the Community web site, but to post comments or questions about the tutorial, on the forum, you will need to register and join the Visual COBOL group.
  1. Visit the Micro Focus Community web site.
  2. Click Select Product, then choose Visual COBOL.

    The Visual COBOL group appears.

  3. Click the Visual COBOL Files tab.

    A list of Articles appears.

  4. Click the appropriate Visual COBOL RM/Panels Conversion entry for your platform.
  5. Click the Download icon to the right of the zip filename in the Attachments list, and save the .zip file.
  6. Extract the contents of the .zip file to the project directory.
Parent topic: Conversion Example: Using
Next topic: Configure Adis Support for RM/Panels


Configure Adis Support for RM/Panels

After importing the Adis configuration file, you must configure it to handle the enhanced ACCEPT and DISPLAY statements in a way that RM/Panels is expecting it to.

Visual COBOL ships with a version of Adis that contains a configuration intended for applications that include RM/Panels syntax.

  1. Using a Visual COBOL command or shell prompt, navigate to the project directory (that is, the directory containing ADISCTRL).
  2. Enter ADISCF.

    The adiscf.exe window appears.

  3. Press F6, then ensure that the RM-Panels configuration is selected.

  4. Press Esc twice to exit.
    Note: if you are prompted to exit without saving, press N, F4, then Esc twice again.
Parent topic: Conversion Example: Using
Previous topic: Download the Tutorial Files


Writing Programs

RM/Panels provides a powerful set of standard runtime functions for writing application programs. To use RM/Panels effectively, you must understand the general approach to using these standard runtime functions and have some familiarity with the specific usage of each one. Utility functions, which allow you to control the overall behavior of the RM/Panels runtime system, rather than manipulate individual panels, are also described.

This section discusses the basic processes of activating a panel library, setting parameters, executing standard runtime functions, including required copy files, error detection, and the appropriate screen handling strategy, followed by a detailed description of each RM/Panels standard runtime and utility function.

  • Standard Runtime Function Basics
  • Standard Runtime Functions
  • Utility Functions
Parent topic: RM/Panels


Standard Runtime Function Basics

Activating a Panel Library

Before your application can use or access individual panels, it must activate the library in which they are contained. The panel library remains active until a different library is activated. Related panels should be grouped into libraries so that RM/Panels does not have to repeatedly change from one library to another.

A library is activated by moving the filename of the library into the variable RMP--LIBRARY. The library becomes active the next time an RM/Panels standard runtime function is used.

Example:

MOVE "libraryname.LIB" TO RMP--LIBRARY.
  • Setting Runtime Parameters
  • Executing Standard Runtime
  • Required Copy Files
  • Error Detection
  • Screen Handling
Parent topic: Writing Programs


Setting Runtime Parameters

Parameters are variables that are set to control the execution of RM/Panels. Two types of parameters are used with RM/Panels standard runtime functions:

  • Required, which are those parameters that must be set to valid values in order for a standard runtime function to execute correctly.
  • Optional, which are those parameters that can be set to override the default behavior specified for the panel. Optional parameters are always reset to their default values by the RM/Panels runtime system after the function is executed. This prevents later executions of the standard runtime function from inheriting the overridden behavior.

Some optional parameters are controlled by SET statements. The following example sets an optional parameter for the DISPLAY PANEL standard runtime function that displays field/control values along with panel text.

Example

SET RMP--SHOW-FIELDS TO TRUE.

Other optional parameters are controlled by MOVE statements. The following example sets a required parameter for the DISABLE FIELD FOR INPUT standard runtime function. This parameter identifies which field/control to disable.

Example

MOVE "CUSTOMER-NUMBER" TO RMP--FIELD-NAME.

All the parameters for RM/Panels standard runtime functions are listed in Appendix B, Standard, Utility, and Extended Runtime Functions and Parameters, and are contained in the master copy file, RMPANELS.WS; see Appendix A, Master Copy File RMPANELS.WS for a description of RMPANELS.WS.

Parent topic: Standard Runtime Function Basics
Related reference
Appendix A: Master Copy File RMPANELS.WS
Appendix B Standard Utility, and Extended Runtime Functions and Parameters


Executing Standard Runtime

Use the PERFORM statement to execute RM/Panels standard runtime functions. The following example demonstrates the execution of the DISPLAY PANEL standard runtime function for a panel called MYPANEL.

Example

PERFORM RMP--DP-MYPANEL.

(The procedure RMP--DP-MYPANEL is contained in a panel-specific copy file, MYPANEL.PRC; see Required Copy Files for more information.

The naming of RM/Panels standard runtime functions follows a strict pattern. The name is made up of three parts:

  • The prefix, RMP--.
  • An abbreviation for the desired RM/Panels standard runtime function. (See Appendix B, Standard, Utility, and Extended Runtime Functions and Parameters for a complete list of standard runtime function abbreviations.)

    Examples are DP (DISPLAY PANEL) and RP(REMOVE PANEL).

  • The panel name.

This naming convention makes it easy to use the RM/Panels standard runtime functions, even in programs using multiple panels.

Parent topic: Standard Runtime Function Basics
Related reference
Required Copy Files
Appendix B Standard Utility, and Extended Runtime Functions and Parameters


Required Copy Files

Each application program that uses RM/Panels requires the master copy file RMPANELS.WS.

Note In some situations you may wish to use one of the other versions of RMPANELS.WS (RMPANELS.LNK and RMPANELS.EXT). See Appendix A, Master Copy File RMPANELS.WS for details on using these copy files.

RMPANELS.WS must be copied into the Working-Storage Section of the application program. The master copy file contains a parameter block used to pass parameters between the application program and the RM/Panels runtime system. Appendix A contains a complete description of RMPANELS.WS.

Each application program must also contain a pair of panel-specific copy files for each panel it uses. These two copy files are the interface between your application program and the RM/Panels runtime system. The Panel Editor automatically produces these copy files when you create a panel. The copy files are named with the first eight characters of the panel name, followed by the extensions, .WS and .PRC. For example, a program that used a panel named MYPANEL would require the copy files:

  • MYPANEL.WS
  • MYPANEL.PRC

These panel-specific copy files are described below, with MYPANEL representing the panel name variable.

MYPANEL.WS

MYPANEL.WS sets up a 100-byte work area for the panel that never needs to be directly modified or referenced by your application program. This work area exists solely for the use of RM/Panels.

MYPANEL.WS also contains declarations for each field/control on the panel. This area is called MYPANEL-WS. These fields are declared in the same manner as any other data item in the Working-Storage Section of a COBOL program. These field declarations are used both as the source of field/control values for RM/Panels displays and as the destination for RM/Panels accepts. The order of these fields/controls is dictated by the Panel Configuration and should not be changed manually. Values, however, can be moved in or out of the fields/controls at any time.

MYPANEL.WS must be copied into the Working-Storage Section of your application program.

Example of contents of MYPANEL.WS:

01MYPANEL-WS.
  03 FILLER      PIC X(100) VALUE "MYPANEL    0050".
  03 CUST-CITY   PIC X(15).
  03 CUST-NAME   PIC X(30).
  03 CUST-NUMBER PIC 9(5).

MYPANEL.PRC

MYPANEL.PRC contains procedures that execute RM/Panels standard runtime functions, such as displaying or removing panels and entering panel fields/controls. MYPANEL.PRC must be copied into the Procedure Division of your application program.

Example of partial contents of MYPANEL.PRC:

RMP--AF-MYPANEL.
     CALL RMP--RUNTIME USING RMP--AF
     RMP--PARAMETERS MYPANEL-WS
RMP--EE-MYPANEL.
     CALL RMP--RUNTIME USING RMP--EE
     RMP--PARAMETERS MYPANEL-WS

Sample Program

The following sample program shows the minimum requirements for an RM/Panels program. This program, which displays a panel and then removes it, is called MINIMUM. It uses a panel called MYPANEL in the panel library called MYPANEL.LIB.

IDENTIFICATION DIVISION.
PROGRAM-ID. MINIMUM.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
  COPY "RMPANELS.WS".
  COPY "MYPANEL.WS".
PROCEDURE DIVISION.
MAIN-PROCEDURE.
  MOVE "MYPANEL.LIB" TO RMP--LIBRARY.
  PERFORM RMP--DP-MYPANEL.
  PERFORM RMP--RP-MYPANEL.
  STOP RUN.

  COPY "MYPANEL.PRC".
Parent topic: Standard Runtime Function Basics
Related reference
Appendix A: Master Copy File RMPANELS.WS


Error Detection

Every RM/Panels standard runtime function sets a status value. This value is contained in the variable RMP--STATUS in master copy file RMPANELS.WS. The possible status values and error conditions are as follows:

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
3 | The function number is invalid.
4 | The attribute is invalid.
5 | The panel is not in this library
6 | The library does not exist.
7 | The library configuration is invalid.
8 | The panel does not contain any fields/controls.
9 | The panel contains no input fields/controls.
10 | The panel is not displayed.
11 | The palette number is invalid.
12 | Help message is not defined.
13 | Error message is not defined.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. user's guide
15 | The field/control is disabled.
16 | A window error has occurred.
20 | The menu command name is invalid.
22 | There is no pulldown menu on this panel.
1001 | API parameter is missing.
1002 | API message is not defined.
1003 | API pulldown option is invalid.
1004 | API pulldown option is uncheckable.

The following condition-names are declared in RMPANELS.WS to help in interpreting errors.

05 RMP--STATUS PIC 9(4).
   88 RMP--VALID-FUNCTION        VALUE 0.
   88 RMP--FIELD-INVALID         VALUE 1.
   88 RMP--OCCUR-INVALID         VALUE 2.
   88 RMP--FUNCTION-INVALID      VALUE 3.
   88 RMP--ATTRIBUTE-INVALID     VALUE 4.
   88 RMP--PANEL-INVALID         VALUE 5.
   88 RMP--LIBRARY-INVALID       VALUE 6.
   88 RMP--CONFIG-INVALID        VALUE 7.
   88 RMP--NO-FIELDS             VALUE 8.
   88 RMP--NO-INPUT-FIELDS       VALUE 9.
   88 RMP--PANEL-NOT-DISPLAYED   VALUE 10.
   88 RMP--PALETTE-INVALID       VALUE 11.
   88 RMP--NO-HELP-DEFINED       VALUE 12.
   88 RMP--NO-ERROR-DEFINED      VALUE 13.
   88 RMP--IO-ERROR              VALUE 14.
   88 RMP--CONTROL-DISABLED      VALUE 15.
   88 RMP--WINDOW-ERROR          VALUE 16.
   88 RMP--MENU-COMMAND-INVALID  VALUE 20.
   88 RMP--NO-PULLDOWN           VALUE 22.
   88 RMP--API-PARAM-MISSING     VALUE 1001.
   88 RMP--API-MSG-NOT-DEFINED   VALUE 1002.
   88 RMP--API-PD-OPTION-INVALID VALUE 1003.
   88 RMP--API-UNCHECKABLE       VALUE 1004.
Parent topic: Standard Runtime Function Basics
Related reference
C$RERR


Screen Handling

RM/Panels supports three different methods of handling screens in COBOL application programs. In addition to the two common approaches of coding individual fields or accepting an entire screen definition, RM/Panels uses a third approach based on a programming technique called the event loop.

The event loop is common in programming graphical user interfaces. It frees you from having to direct all the activity of complex screens. The basic activities of the screen are performed automatically, but every event is reported to the application program to allow special processing when desired. RM/Panels applies this concept to COBOL screen handling to provide full-screen entry with field level control and a minimum of coding. The three methods are contrasted in the following sections.

In summary, remember the following steps when writing pop-up panels:

  1. Create the pop-up panel as a window or set RMP--WINDOW to TRUE before displaying.
  2. Reset the keyboard focus when returning to the main panel.
  3. Do not let terminating condition(s) of the pop-up panel fall back to the main panel.
  • Individual Field Method
  • Entire Screen Method
  • Event Loop Method
  • Using Multiple Panels
Parent topic: Standard Runtime Function Basics


Individual Field Method

The individual field method of COBOL screen handling requires that you write or generate all the code needed to control each input field individually. This method requires a series of ACCEPT statements, as shown in the following example:

ACCEPT FIELD-1 LINE 10 POSITION 40.
ACCEPT FIELD-2 LINE 11 POSITION 40.
ACCEPT FIELD-3 LINE 12 POSITION 40.

This approach is usually embellished with code allowing the user to select or move between input fields. Help messages, prompts, validations, and special features may also be added. However, what begins as a simple series of ACCEPT statements soon grows into unmanageable code.

The benefit of building input logic in this method is that total control is possible at the field level. The disadvantage is that all screen handling responsibility is borne by the programmer, who must produce a cumbersome amount of code to add or modify the field level logic, add or delete fields, or move existing fields on the screen.

Parent topic: Screen Handling


Entire Screen Method

The second common method of COBOL screen handling is to do an enhanced ACCEPT statement of an entire screen definition through the Screen Section or some other extension. This approach eliminates the need for extensive coding involved in controlling each individual field, but it also removes the ability to smoothly integrate field level logic and special features because the application program only gains control under a limited set of circumstances.

Parent topic: Screen Handling


Event Loop Method

The event loop method enables sophisticated screen handling with tremendous flexibility and greatly reduced coding.

There are three components in an event loop:

  • Loop control. This specifies the condition or conditions that terminates the loop.
  • Execution of an event. One event occurs on each repetition of the loop, until the loop control conditions are met.
  • Event testing. One or more checks by the application program to evaluate events. Rather than dictating each event, the application program responds to the current event.

Example of an RM/Panels Event Loop

PERFORM UNTIL F3-KEY-PRESSED    (Loop Control)
     PERFORM RMP--EE-PANELNAME  (Execution)
     EVALUATE RMP--LAST-FIELD
        WHEN "CUSTOMER-NUMBER"  (Event Test)
           PERFORM VALIDATE-CUSTOMER-NUMBER
        WHEN "CUSTOMER-STATE"   (Event Test)
           PERFORM VALIDATE-CUSTOMER-STATE
     END-EVALUATE
END-PERFORM.

The event is input to a field/control on the screen, which is performed by the procedure RMP--EE-PANELNAME. This procedure executes the RM/Panels EXECUTE EVENT standard runtime function. The EXECUTE EVENT standard runtime function accomplishes the following:

  • Checks the parameters passed to it to see what event to perform
  • Performs the event (field/control input)
  • Sets parameters to indicate what event was executed and what event should be executed next
  • Returns control to the application program

Each time the EXECUTE EVENT standard runtime function is performed, only one event is executed, thus the application program can always intercept control after any event. It then has the ability to perform special processing or force a particular event to occur.

There are many advantages to using the event loop method:

  1. Writing tedious screen handling code is eliminated.
  2. Adding special field/control level logic is made easier.
  3. Field/control level logic is insulated from changes in field/control entry order and position.
  4. Size of screen handling code is dependent upon the amount of special processing to be done, rather than the number of fields/controls on the screen.
  5. Adding new fields/controls does not affect the event loop unless the fields/controls require special processing.
  6. Event loops can be nested, which allows multiple panels to be used on the screen. The following section describes the use of multiple panels and special considerations in nesting event loops.
Parent topic: Screen Handling
Related reference
EXECUTE EVENT


Using Multiple Panels

RM/Panels is designed to support windowed applications, where panels can be displayed (or “pop-up”) at different locations on the screen. While simple to produce, this type of application requires a few special considerations. The following describes the three steps to writing pop-up applications.

  1. Detect a request for a pop-up panel. The first step in coding a windowed application is detecting the conditions that indicate the need to display the pop-up panel. This can be any condition, but is commonly a special keystroke, push button, or menu command. The detection is usually a test inside an event loop based on the EXECUTE EVENT standard runtime function. This is illustrated by the following code fragment:

    DEMONSTRATE-FUNCTION.
   PERFORM RMP--EE-PANEL5.
   IF F3-KEY AND (RMP--LAST-FIELD = "CUST-SHIP-CODE")
      PERFORM SHIP-CODE-DETAILS

    When the F3 key is pressed during the entry of the CUST-SHIP-CODE field, the SHIP-CODE-DETAILS procedure, which controls the pop-up panel, is performed.

  2. Display, use, and remove the pop-up panel. A pop-up panel is used like any other panel, but with one important difference. The “Make panel a window” parameter must be selected, or at runtime execution, RMP--WINDOW should be set to TRUE before the panel is displayed. Failure to do one of these will prevent the panel from being removed from the display properly.

    The following code fragment shows how the pop-up panel is displayed, used, and removed:

    SHIP-CODE-DETAILS.
    PERFORM RMP--DP-PANEL6.
    SET RMP--FIRST-FIELD TO TRUE.
    PERFORM RMP--EE-PANEL6
       WITH TEST AFTER UNTIL ESCAPE-KEY.
    PERFORM RMP--RP-PANEL6.

    Since this panel was created with the windowing option selected, the code is no different from the usage of a normal panel. The panel is displayed, an event loop is used for user input, and then the panel is removed, restoring the screen contents.

  3. Resume execution of the original event loop. The event loop is based on the ability of the EXECUTE EVENT standard runtime function to perform an input event and set up the next input event. Because the previous step includes an event loop that actually executes inside the original event loop, the internal variables determining which field/control should be entered next are set for the pop-up panel. One of these must be reset so that the keyboard focus moves to a field/control on the main panel. There are three ways to do this:

    1. Set RMP--REPEAT-EVENT to TRUE.

      This returns keyboard focus to the last field/control that had it on the panel.

    2. Set RMP--FIRST-FIELD to TRUE.

      This sets keyboard focus to the first enabled field/control on the panel.

    3. Move the name of a field to RMP--NEXT-FIELD.

      This specifically moves keyboard focus to that field/control.

    Also, care must also be taken not to allow the terminating condition from the inner loop to terminate the original loop. The following program prevents this problem by moving zero to RMP--EXCEPTION-NUMBER, so that the Escape key condition is false upon resuming the original loop. The following code follows the sample shown in the first step.

       SET RMP--REPEAT-EVENT TO TRUE
   MOVE 0 TO RMP--EXCEPTION-NUMBER.
Parent topic: Screen Handling
Related reference
EXECUTE EVENT


Standard Runtime Functions

The RM/Panels runtime system is an RM/COBOL-85 object program that must be available to and distributed with your application.

Note: In version 1.0 of RM/Panels, there was only one RM/Panels runtime system program, runpanel.cob. Version 1.1 introduced an additional runtime system program, rmputil.cob. Both of these programs must be distributed with applications written using RM/Panels version 1.1. In version 2.1 of RM/Panels, there is only one runtime system program, runpan2.cob.

The RM/Panels runtime system provides a powerful set of standard runtime functions that allows the application to manipulate panels. The following table gives the name and abbreviation of each RM/Panels standard runtime function.

Function | Abbreviation
ACCEPT FIELD | AF
CHANGE PANEL PALETTE | CPP
CHECK MENU OPTION | CMO
CLEAR ALL FIELDS | CAF
DISABLE ALL FIELDS | DA
DISABLE FIELD FOR INPUT | DFI
DISABLE MENU OPTION | DMO
DISPLAY ALL FIELDS | DAF
DISPLAY FIELD | DF
DISPLAY PANEL | DP
ENABLE ALL FIELDS | EA
ENABLE FIELD FOR INPUT | EFI
ENABLE MENU OPTION | EMO
EXECUTE EVENT | EE
INITIALIZE ALL FIELDS | IAF
INITIALIZE FIELD | IF
POPUP MENU | PUM
REMOVE PANEL | RP
SET FIELD ATTRIBUTE | SFA
SET SCROLL BAR RANGE | SSR
SHOW FIELD ERROR | SFE
SHOW FIELD HELP | SFH
SHOW PANEL ERROR | SPE
SHOW PANEL HELP | SPH
UNCHECK MENU OPTION | UMO
VALIDATE ALL FIELDS | VAF
VALIDATE FIELD | VF

Each standard runtime function is described in the following section. All parameters for RM/Panels standard runtime functions are defined in Appendix B, Standard, Utility, and Extended Runtime Functions and Parameters.

  • Configurable Keys
  • ACCEPT FIELD
  • CHANGE PANEL PALETTE
  • CHECK MENU OPTION
  • CLEAR ALL FIELDS
  • DISABLE ALL FIELDS
  • DISABLE FIELD FOR INPUT
  • DISABLE MENU OPTION
  • DISPLAY ALL FIELDS
  • DISPLAY FIELD
  • DISPLAY PANEL
  • ENABLE ALL FIELDS
  • ENABLE FIELD FOR INPUT
  • ENABLE MENU OPTION
  • EXECUTE EVENT
  • INITIALIZE ALL FIELDS
  • INITIALIZE FIELD
  • POPUP MENU
  • REMOVE PANEL
  • SET FIELD ATTRIBUTE
  • SET SCROLL BAR RANGE
  • SHOW FIELD ERROR
  • SHOW FIELD HELP
  • SHOW PANEL ERROR
  • SHOW PANEL HELP
  • UNCHECK MENU OPTION
  • VALIDATE ALL FIELDS
  • VALIDATE FIELD
Parent topic: Writing Programs
Related reference
Appendix B Standard Utility, and Extended Runtime Functions and Parameters


Configurable Keys

The RM/Panels runtime system takes special action on several keys. The field termination codes that RM/Panels recognizes as each key can be controlled by the application program. If the key values are set to zero, RM/Panels assumes the key is not to be used. The seven configurable keys and their interpretation by RM/Panels are as follows:

Help
This key causes the automatic help facility to display help information for the field/control during the ACCEPT FIELD or EXECUTE EVENT standard runtime functions.
Enter
This key is interpreted as the termination of normal input into a field/control. If a validation test fails, the user is forced to reenter the field/control, and an error message is displayed (if created). In the EXECUTE EVENT standard runtime function, preparations are made to enter the next field/control.
Next Field
This key is interpreted as the termination of normal input into the current field/control and as a request to move to the next field/control. The default key is the Down Arrow key.
Prev Field
This key is interpreted as the termination of normal input into the current field/control and as a request to move to the previous field/control. The default key used is the Up Arrow key.
Next Group
This key is interpreted as the termination of normal input into the current field/control and as a request to move to the first field/control in the next group of fields/controls. The default key is the Tab key.
Prev Group
This key is interpreted as the termination of normal input into the current field/control and as a request to move to the first field/control in the previous group of fields. The default key is the Shift-Tab key combination.
Pulldown
This key is interpreted as a request to shift input focus to the pulldown menu, if present.

See Appendix A, Master Copy File RM/PANELS.WS for more information.

Parent topic: Standard Runtime Functions
Related reference
Appendix A: Master Copy File RMPANELS.WS


ACCEPT FIELD

Execution

PERFORM RMP--AF-PANELNAME

Description

This standard runtime function performs the entry of a single panel field/control by the user. It is similar to a standard COBOL ACCEPT statement, except that RM/Panels sets all the parameters and can perform many supporting activities automatically. Many characteristics of the field/control can then be modified through the Panel Editor, without requiring program changes or recompilation.

Note: While much more powerful than an ACCEPT statement, this standard runtime function is not the preferred method of allowing user input in RM/Panels. Use the EXECUTE EVENT standard runtime function as the primary method to allow user input. Use ACCEPT FIELD when only one field/control is needed.

Required Parameters

The program must set the name of the field/control to be accepted in RMP--FIELD-NAME. If the field/control occurs more than once, the occurrence number must be specified in RMP--FIELD-OCCUR. The occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Returned Values

The value entered by the user is stored in the appropriate field/control within panelname.WS. The field/control termination code indicating the ending key is returned in RMP--EXCEPTION-NUMBER.

Additional Usage Notes

  • Before this standard runtime function can be executed, the panel must be displayed.
  • User Input Errors. If validation is specified for the field/control and an error is detected, the behavior of RM/Panels depends on the way in which user input was terminated. If the input was terminated by the auto-exit property or by pressing the Enter key, the error message is displayed and the user is forced to reenter the field/control. If input was terminated in any other way, control is returned to the application program and RMP--INVALID-INPUT is TRUE. If you want the error message displayed under these circumstances, you must execute the SHOW FIELD ERROR standard runtime function. This approach differs somewhat from the handling of invalid input during the execution of the EXECUTE EVENT function. During the execution of the ACCEPT FIELD function, RM/Panels assumes that the auto-exit property and the Enter key indicate a normal termination of input. The user should not be allowed to proceed if the input is invalid. During the EXECUTE EVENT function, RM/Panels assumes that many other keys also indicate normal termination of input.
    Note: If accelerator values are used for any fields/controls, check both the exception value and RMP--VALID-INPUT. Accelerator keys can affect code logic.
  • Disabled Fields/Controls. In the Panel Editor or at runtime execution, a field/control can be specified as not allowing entry. This characteristic does not apply to the ACCEPT FIELD standard runtime function. It only applies to standard runtime functions that allow input of more than one field/control. RM/Panels assumes that if a field/control is specifically identified for the ACCEPT FIELD standard runtime function, it should allow input regardless of the allow input characteristic. This can be quite useful. For example, ACCEPT FIELD might be used to allow input of a key field/control in a maintenance program, and then EXECUTE EVENT might be used to allow updating of the non-key fields/controls.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
5 | The panel is not in this library
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
EXECUTE EVENT
C$RERR


CHANGE PANEL PALETTE

Execution

PERFORM RMP--CPP-PANELNAME

Description

This standard runtime function redisplays a panel and all its fields/controls using a new palette.

Required Parameters

RMP--PALETTE must be set with the number of the palette to be used. You must have previously defined the palette number in the panel library with a value ranging from 1 to 99. A value of 0 causes the panel to display using the default palette for the panel.

Additional Usage Notes

Before this standard runtime function can be executed, the panel must be displayed. However, the default panel palette can be overridden at the time the panel is displayed.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
6 | The library does not exist.
10 | The panel is not displayed.
11 | The palette number is invalid.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


CHECK MENU OPTION

Execution

PERFORM RMP--CMO-PANELNAME

Description

This standard runtime function places a check next to a pulldown menu command when it is displayed.

Required Parameters

The application program must set the name of the menu command to be checked in RMP--COMMAND-NAME.

Returned Values

None.

Additional Usage Notes

This standard runtime function is valid only for pulldown menu commands that can be checked.

An inverse standard runtime function, UNCHECK MENU OPTION is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
20 | The menu command name is invalid.
Parent topic: Standard Runtime Functions
Related reference
UNCHECK MENU OPTION
C$RERR


CLEAR ALL FIELDS

Execution

PERFORM RMP--CAF-PANELNAME

Description

This standard runtime function inserts spaces in all alphanumeric fields/controls and zeros in all numeric and date fields/controls on the panel. It is the equivalent of issuing an INITIALIZE statement to each field defined in panelname.WS.

Required Parameters

None.

Returned Values

The value for each field/control in the panel is stored within panelname.WS.

Additional Usage Notes

  • The panel does not need to be displayed before clearing the fields/controls.
  • This standard runtime function is similar to the INITIALIZE ALL FIELDS standard runtime function. However, the INITIALIZE ALL FIELDS standard runtime function sets all fields/controls to their default values, which may not be zero or spaces.
  • This standard runtime function does not display the fields/controls on the screen.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
INITIALIZE ALL FIELDS
INITIALIZE FIELD
C$RERR


DISABLE ALL FIELDS

Execution

PERFORM RMP--DA-PANELNAME

Description

This standard runtime function causes all fields/controls on the panel to be disabled for input.

Required Parameters

None.

Additional Usage Notes

This function does not redisplay the fields/controls with their disabled attributes. Use the DISPLAY ALL FIELDS or DISPLAY PANEL standard runtime function after the DISABLE ALL FIELDS standard runtime function to show the change in their status.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
DISPLAY ALL FIELDS
DISPLAY PANEL
C$RERR


DISABLE FIELD FOR INPUT

Execution

PERFORM RMP--DFI-PANELNAME

Description

This standard runtime function prevents input to a field/control that was specified as allowing input in the Panel Editor. Many times a certain field/control should be input, or not input, based on the value of another field/control. This standard runtime function allows a field/control to be disabled for input at runtime execution, rather than at panel creation time, increasing the flexibility of the EXECUTE EVENT standard runtime function.

Required Parameters

The program must set the name of the field/control to be disabled in RMP--FIELD-NAME. If the field/control occurs more than once, all occurrences of the field/control will be disabled.

Optional Parameters

RMP--SUPPRESS-EVENT-RESET can be set to TRUE to prevent RMP--NEXT-FIELD and RMP--NEXT-OCCUR from being reset.

Returned Values

The values of RMP--NEXT-FIELD and RMP--NEXT-OCCUR are reset, based upon the new input status of the fields/controls on the panel.

Additional Usage Notes

  • This standard runtime function resets the next field/control to be entered because generally the standard runtime function is used within an event loop and the new input status of the field/control should take effect immediately.
  • An inverse standard runtime function, ENABLE FIELD FOR INPUT, is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
EXECUTE EVENT
Event Loop Method
ENABLE FIELD FOR INPUT
C$RERR


DISABLE MENU OPTION

Execution

PERFORM RMP--DMO-PANELNAME

Description

This standard runtime function disables a command on a pulldown menu. It does not apply to menu titles. The command appears on the menu with the disabled attribute, but the user is not able to select it.

Required Parameters

The application program must set the name of the menu item to be disabled in RMP--COMMAND-NAME.

Returned Values

None.

Additional Usage notes

An inverse standard runtime function, ENABLE MENU OPTION is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
20 | The menu command name is invalid.
Parent topic: Standard Runtime Functions
Related reference
ENABLE MENU OPTION
C$RERR


DISPLAY ALL FIELDS

Execution

PERFORM RMP--DAF-PANELNAME

Description

This standard runtime function displays the values of all fields/controls on the panel. It should be used as the primary method of displaying field/control values. Use a related standard runtime function, DISPLAY FIELD when only one field/control is to be displayed.

Required Parameters

None.

Additional Usage Notes

  • This standard runtime function is intended primarily for displaying only field/control values. When you want to display both the panel text and graphics at the same time, you need to use the DISPLAY PANEL standard runtime function.
  • Before this standard runtime function can be executed, the panel must be displayed.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
DISABLE ALL FIELDS
DISPLAY FIELD
ENABLE ALL FIELDS
C$RERR


DISPLAY FIELD (RM/Panels Standard Runtime Functions)

DISPLAY FIELD

Execution

PERFORM RMP--DF-PANELNAME

Description

This standard runtime function displays the value of a single field/control on the panel. It is similar to a standard DISPLAY statement, except that RM/Panels sets all the parameters. Many characteristics of the field/control can then be modified solely through the Panel Editor, without requiring program changes or recompilation.

Note: While much more powerful than a standard DISPLAY statement, this standard runtime function is not the preferred method of displaying field/control values in RM/Panels. Use the DISPLAY ALL FIELDS and DISPLAY PANEL standard runtime functions as the primary method of displaying field/control values. Use DISPLAY FIELD when only one field/control is to be displayed.

Required Parameters

The program must set the name of the field/control to be displayed in RMP--FIELD-NAME. If the field/control occurs more than once, the occurrence number must be specified in RMP--FIELD-OCCUR. The occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Additional Usage Notes

  • Before this standard runtime function can be executed, the panel must be displayed.
  • Setting RMP--FIELD-OCCUR to 0 will display all occurrences of a repeating field/control.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
5 | The panel is not in this library
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
DISPLAY ALL FIELDS
DISPLAY PANEL
C$RERR


DISPLAY PANEL

Execution

PERFORM RMP--DP-PANELNAME

Description

This standard runtime function displays a panel on the screen.

Required Parameters

RMP--LIBRARY must be set to the name of the panel library which contains the panel.

Note: Since this value is never changed by RM/Panels, it does not need to be set for each panel used in the same library.

Optional Parameters

RMP--BEEP can be set to TRUE to produce a beep when displaying the panel.

RMP--CLEAR can be set to TRUE to erase the entire video screen and set the color of the screen to the background color of the panel.

RMP--PALETTE can be set to select a specific palette other than the default for the panel.

RMP--PANEL-LINE can be set to 999 to center the panel vertically or it can be set to any non-zero value to display the panel on a specific starting line.

RMP--PANEL-POS can be set to 999 to center the panel horizontally or it can be set to any non-zero value to display the panel on a specific starting column position.

RMP--SHOW-FIELDS can be set to TRUE to display all field/control values with the panel.

RMP--WINDOW can be set to TRUE or FALSE to override the default windowing characteristic of the panel.

Additional Usage Notes

  • If the value in RMP--PALETTE is 0 or invalid, the panel is displayed using the default palette for the panel.
  • Displaying the field/control values with the panel is much faster than displaying the panel, then the fields/controls.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
11 | The palette number is invalid.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
DISABLE ALL FIELDS
DISPLAY FIELD
ENABLE ALL FIELDS
C$RERR


ENABLE ALL FIELDS

Execution

PERFORM RMP--EA-PANELNAME

Description

This standard runtime function causes all fields/controls on the panel to be enabled for input.

Required Parameters

None.

Additional Usage Notes

This standard runtime function does not redisplay the fields/controls with their enabled attributes. Use the DISPLAY ALL FIELDS or DISPLAY PANEL standard runtime function after the ENABLE ALL FIELDS standard runtime function to show the change in their status.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
DISPLAY ALL FIELDS
DISPLAY PANEL
C$RERR


ENABLE FIELD FOR INPUT

Execution

PERFORM RMP--EFI-PANELNAME

Description

This standard runtime function allows input to a field/control that was specified as not allowing input in the Panel Editor. Many times a certain field/control should be input, or not input, based on the value of another field/control. This standard runtime function allows a field/control to be enabled for input at runtime execution, rather than at panel creation time, increasing the flexibility of the EXECUTE EVENT standard runtime function.

Required Parameters

The application program must set the name of the field/control to be enabled in RMP--FIELD-NAME. If the field/control occurs more than once, all occurrences of the field/control are enabled.

Optional Parameters

RMP--SUPPRESS-EVENT-RESET can be set to TRUE to prevent RMP--NEXT-FIELD and RMP--NEXT-OCCUR from being reset.

Returned Values

The values of RMP--NEXT-FIELD and RMP--NEXT-OCCUR are reset, based upon the new input status of the fields/controls on the panel.

Additional Usage Notes

  • This standard runtime function resets the next field/control to be entered because generally the standard runtime function is used within an event loop and the new input status of the field/control should take effect immediately.
  • An inverse standard runtime function, DISABLE FIELD FOR INPUT, is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
EXECUTE EVENT
DISABLE FIELD FOR INPUT
Event Loop Method
C$RERR


ENABLE MENU OPTION

Execution

PERFORM RMP--EMO-PANELNAME

Description

This standard runtime function enables a command on a pulldown menu. It does not apply to menu titles. The command appears with the normal attribute and the user is able to select it.

Required Parameters

The application program must be set to the name of the menu item to be enabled in RMP--COMMAND-NAME.

Returned Values

None.

Additional Usage Notes

  • The next time the command is displayed, it is shown with the enabled attribute.
  • An inverse standard runtime function, DISABLE MENU OPTION, is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
20 | The menu command name is invalid.
Parent topic: Standard Runtime Functions
Related reference
DISABLE MENU OPTION
C$RERR


EXECUTE EVENT

Execution

PERFORM RMP--EE-PANELNAME

Description

This standard runtime function performs the entry of a single panel field/control, but when placed in an event loop it allows entry of all fields/controls on the panel. Use the EXECUTE EVENT standard runtime function as the standard method of allowing user input with RM/Panels. It provides the power of multiple field entry with the flexibility of field-by-field control. Use a related standard runtime function, ACCEPT FIELD when only one field/control is to be entered.

Required Parameters

There are three ways to specify which field/control receives input focus on each execution of the EXECUTE EVENT standard runtime function:

  1. If you want to begin entry on the first field/control of the panel, RMP--FIRST-FIELD must be set to TRUE.
  2. If you want to specify the next input field/control, RMP--NEXT-FIELD must be set to the field/control name, and RMP--NEXT-OCCUR must be set to the field/control occurrence number. The RM/Panels runtime system resets these parameters after each execution of the EXECUTE EVENT standard runtime function, thereby preparing for the next execution.
  3. If you want to resume entry on the last field/control of the panel that the user entered, RMP--REPEAT-EVENT must be set to TRUE. This is useful if multiple panels are in use and the user is returning to a previously accessed panel, or if invalid user input is detected.

Returned Values

The value entered for each field/control in the panel is stored within panelname.WS. The field termination code indicating the terminating key is returned in RMP--EXCEPTION- NUMBER.

The values of RMP--LAST-FIELD, RMP--LAST-OCCUR, RMP--NEXT-FIELD, and RMP--NEXT-OCCUR are also set to the appropriate values for the next event. Occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Under modeless operation, the following parameters are also returned:

  • RMP--LAST-PANEL contains the name of the panel for which the last EXECUTE EVENT standard runtime function was performed.
  • RMP--REQUESTED-PANEL contains the name of the panel that the user requested for the next event. To support modeless behavior, the application program must be written so that the next EXECUTE EVENT standard runtime function is performed for the panel named by this parameter.

Additional Usage Notes

  • Before this standard runtime function can be executed, the panel must be displayed.
  • User Input Errors. If validation is specified for the field/control and an error is detected, the behavior of RM/Panels depends on the way in which user input was terminated. If the input was terminated by the auto-exit property or by pressing any of the keys defined in RMPANELS.WS as having a special function, the error message is displayed and the user is forced to reenter the field/control. If input was terminated in any other way, control is returned to the application program and RMP--INVALID-INPUT is TRUE. If you want the error message displayed under these circumstances, you must execute the SHOW FIELD ERROR standard runtime function. This approach differs somewhat from the handling of invalid input during the execution of the ACCEPT FIELD function. During the execution of the EXECUTE EVENT function, RM/Panels assumes that the auto-exit property and any of the keys defined in RMPANELS.WS indicate a normal termination of input. The user should not be allowed to proceed if the input is invalid. During the ACCEPT FIELD function, RM/Panels assumes that only the auto-exit property and the Enter key indicate normal termination of input.
  • The simplest usage of this standard runtime function is as follows:
    PERFORM RMP--EE-PANELNAME WITH TEST AFTER UNTIL F3-KEY.

    This allows the user to operate all enabled panel fields/controls until the F3 key is pressed. The WITH TEST AFTER phrase ensures that the standard runtime function is executed at least once before testing the condition-name F3 KEY, in case the F3 key has just been pressed in another routine.

  • The many parameters provided to interpret and control events make it possible to construct sophisticated input routines. The following sample demonstrates one such routine and is followed by an explanation of the numbered areas.

Example

1 SET RMP--FIRST-FIELD TO TRUE.
2 PERFORM WITH TEST AFTER UNTIL F3-KEY
3    PERFORM RMP--EE-PANELNAME
4      EVALUATE RMP--LAST-FIELD
5         WHEN "CUSTOMER-NUMBER"
             PERFORM CUSTOMER-VALIDATION
             IF CUST-NOT-VALID
6               SET RMP--REPEAT-EVENT TO TRUE
             END-IF
7         WHEN "CUST-BAL"
             IF CUST-BAL = 0
8               MOVE "SHIP-CODE" TO RMP--NEXT-FIELD
             END-IF
9         WHEN "SHIP-CODE"
             IF SHIP-CODE NOT = OLD-SHIP-CODE
                PERFORM VALIDATE-SHIP-CODE
                IF SHIP-CODE-NOT-VALID
10                 SET RMP--REPEAT-EVENT TO TRUE
                END-IF
             END-IF
11     END-EVALUATE
12     EVALUATE RMP--NEXT-FIELD
13        WHEN "SHIP-CODE"
             MOVE SHIP-CODE TO OLD-SHIP-CODE
14     END-EVALUATE
15 END-PERFORM.
  1. Setting RMP--FIRST-FIELD to TRUE tells RM/Panels to begin user input with the first field/control on the panel.
  2. This is the loop control, specifying the condition that terminates the event loop.
  3. This is the execution of the event, the entry of a field/control. It is done with the EXECUTE EVENT standard runtime function.
  4. This is the first of the event tests. The EVALUATE statement is used to determine the field/control on the panel that was just entered by the user.
  5. This statement checks to see if the customer number was just entered. If it was entered, a validation routine contained in the application program is performed.
  6. Setting RMP--REPEAT-EVENT to TRUE forces the customer number to be reentered as the next event, rather than moving on to the next field/control.
  7. This statement checks to see if the customer balance was just entered.
  8. Moving SHIP-CODE to RMP--NEXT-FIELD forces the next event to be the entry of the SHIP-CODE field/control, rather than the next field/control on the panel.
  9. This statement checks to see whether the SHIP-CODE field/control was just entered. If so, the statement checks to see if the value changed and validates the new value.
  10. Setting RMP--REPEAT-EVENT to TRUE forces reentry of the SHIP-CODE field/control.
  11. This statement ends the evaluation of the last field/control entered.
  12. This statement begins evaluation of the next field/control to be entered.
  13. This statement checks to see whether the SHIP-CODE field/control is about to be entered. If so, it saves the current value allowing the operations, described previously in #9, to detect a change in the value.
  14. This statement ends the evaluation of the next field/control to be entered.
  15. This statement ends one iteration of the loop.

    This type of flexibility provides limitless possibilities. For more conceptual information on event loops, see the discussion of Event Loop Method.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
5 | The panel is not in this library
6 | The library does not exist.
8 | The panel does not contain any fields/controls.
9 | The panel contains no input fields/controls.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
ACCEPT FIELD
Event Loop Method
C$RERR


INITIALIZE ALL FIELDS

Execution

PERFORM RMP--IAF-PANELNAME

Description

This standard runtime function initializes all fields/controls to the default values specified in the panel. It is useful because the default value can be modified with the Panel Editor and does not require program changes or recompilation. Use the INITIALIZE ALL FIELDS standard runtime function as the primary method to initialize fields/controls.

Use a related standard runtime function, INITIALIZE FIELD when only one field/control is to be initialized.

Required Parameters

None.

Returned Values

The default value for each field/control in the panel is stored within panelname.WS.

Additional Usage Notes

  • The panel does not need to be displayed before initializing all fields/controls.
  • This standard runtime function is similar to the CLEAR ALL FIELDS standard runtime function which inserts spaces in all alphanumeric fields/controls and zeros in all numeric and date fields/controls on the panel.
  • This standard runtime function does not display the fields/controls on the screen.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
CLEAR ALL FIELDS
INITIALIZE FIELD
C$RERR


INITIALIZE FIELD

Execution

PERFORM RMP--IF-PANELNAME

Description

This standard runtime function initializes a single field/control or field/control occurrence to the default value specified in the panel. It is useful because the default value can be modified with the Panel Editor and does not require program changes or recompilation.

Note This standard runtime function is not the preferred method of initializing fields in RM/Panels. Use the INITIALIZE ALL FIELDS standard runtime function as the primary method to initialize fields/controls. Use INITIALIZE FIELD when only one field/control is to be initialized.

Required Parameters

The program must set the name of the field/control to be entered in RMP--FIELD-NAME. If the field/control occurs more than once, the occurrence number must be specified in RMP--FIELD-OCCUR. The occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Returned Values

The default value for each field/control in the panel is stored within panelname.WS.

Additional Usage Notes

  • The panel does not need to be displayed before initializing a field/control.
  • This standard runtime function does not display the field/control on the screen.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
CLEAR ALL FIELDS
INITIALIZE ALL FIELDS
C$RERR


POPUP MENU

Execution

PERFORM RMP--PUM-PANELNAME

Description

This standard runtime function displays or “pops up” one of the pulldown menus as an isolated menu, that is, without the menu bar. The popup menu looks and works just like the pulldown menu, including enabled, disabled, and checked options, accelerators, and mnemonics. Commands are chosen in the same way as from the pulldown menu.

The popup menu is modal. You must make a choice or cancel the menu with the pulldown menu Cancel button or by clicking the mouse outside the border of the menu. If a command is not selected, none of the event type conditions reported in RMPANELS.WS is set. The popup menu does not affect the setting of RMP--LAST-FIELD, RMP--NEXT-FIELD, or any of the other event parameters.

Required Parameters

RMP--COMMAND-NAME must be set to the name of one of the commands on the pulldown menu for this panel.

Optional Parameters

RMP--PANEL-LINE can be set as follows:

Value | Description
0 | Display the pop-up menu on the same line on which it would be displayed if selected from the pulldown menu
999 | Center the pop-up menu vertically on the screen

Any other value indicates a specific line on which the pop-up menu should be displayed.

RMP--PANEL-POS may be set as follows:

Value | Description
0 | Display the pop-up menu on the same column on which it would be displayed if selected from the pulldown menu
999 | Center the pop-up menu horizontally on the screen

Any other value indicates a specific column on which the pop-up menu should be displayed.

Additional Usage Notes

  • This standard runtime function is only valid for panels that have a pulldown menu.
  • The menu, which is to display or “pop up”, is identified by a command name rather than a menu title because the command name is language independent and the menu title is not.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
16 | A window error has occurred.
20 | The menu command name is invalid.
22 | There is no pulldown menu on this panel.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


REMOVE PANEL

Execution

PERFORM RMP--RP-PANELNAME

Description

This standard runtime function removes a panel from the screen. If the panel was displayed with the default windowing option, the original contents of the screen are restored; otherwise, the area of the screen occupied by the panel is cleared and the color of that area is set to the attribute set represented by the A attribute code for the panel.

Required Parameters

None.

Optional Parameters

RMP--CLEAR can be set to TRUE to clear the entire screen and set the screen color to the attribute set represented by the A attribute code for the panel.

Additional Usage Notes

Before this standard runtime function can be executed, the panel must be displayed.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


SET FIELD ATTRIBUTE

Execution

PERFORM RMP--SFA-PANELNAME

Description

This standard runtime function alters the enabled attribute code assigned to a field/control through the Panel Editor. The attribute value remains altered until the panel is removed. This standard runtime function allows a field/control to be displayed with different attributes based on its value or other runtime system conditions.

Required Parameters

The program must set the name of the field/control to be changed in RMP--FIELD-NAME. If the field/control occurs more than once, the occurrence number must be specified in RMP--FIELD-OCCUR. The occurrence numbers are equivalent to COBOL subscripts and begin at 1.

RMP--ATTRIBUTE must be set to space or to a value in the range A through P to indicate the new attribute for the field/control. A value of space restores the default attribute value.

Additional Usage Notes

  • Before this standard runtime function can be executed, the panel must be displayed.
  • This standard runtime function displays the field/control with the new attribute. However, if it is a repeating field/control, it displays only the specified occurrence. Setting RMP--FIELD-OCCUR to 0 displays all occurrences of a repeating field/control.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
4 | The attribute is invalid.
5 | The panel is not in this library
6 | The library does not exist.
10 | The panel is not displayed.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


SET SCROLL BAR RANGE

Execution

PERFORM RMP--SSR-PANELNAME

Description

This standard runtime function changes the minimum, maximum, step, and page values for a scroll bar. In some instances, these values are unknown until the RM/Panels runtime system and this function can be used to reset them.

Required Parameters

The application program must set the name of the scroll bar in RMP--FIELD-NAME.

RMP--SB-MIN must be set to the new minimum value. RMP--SB-MAX must be set to the new maximum value.

Optional Parameters

RMP--SB-STEP may be set to the new step value or zero to keep the current value. RMP--SB-PAGE may be set to the new page value or zero to keep the current value.

Additional Usage Notes

  • This standard runtime function always sets the minimum and maximum value for a scroll bar.
  • If RMP--SB-STEP is set to 0, the step value is not changed. If RMP--SB-STEP is set to any non-zero value, that value becomes the new step value.
  • If RMP--SB-PAGE is set to 0, the page value will not be changed. If RMP--SB-PAGE is set to any non-zero value, that value will become the new page value.
  • The scroll bar thumb needs special consideration when resetting the scroll bar range. To avoid the possibility of having two scroll bar thumbs displayed simultaneously, always do the following before using this standard runtime function.
  • Set the scroll bar value to the minimum.
  • Display the scroll bar with the DISPLAY FIELD standard runtime function.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


SHOW FIELD ERROR

Execution

PERFORM RMP--SFE-PANELNAME

Description

This standard runtime function displays the error message, if any, that you have defined for a field/control. It complements the ACCEPT FIELD, EXECUTE EVENT, VALIDATE ALL FIELDS, and VALIDATE FIELD standard runtime functions by allowing the application program to display the error message under circumstances that prevent RM/Panels from displaying it automatically.

SHOW FIELD ERROR displays the message, waits for the user to press any key, erases the message, and then returns control to the application program.

Required Parameters

The application program must set the name of the field/control for which the error message is to be displayed in RMP--FIELD-NAME. No occurrence number is required, even for fields/controls with multiple occurrences, as the error message applies to each occurrence.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
ACCEPT FIELD
EXECUTE EVENT
VALIDATE ALL FIELDS
VALIDATE FIELD
C$RERR


SHOW FIELD HELP

Execution

PERFORM RMP--SFH-PANELNAME

Description

This standard runtime function displays the help message, if any, that you defined for a field/control. It allows you to display, rather than re-create, existing help messages in situations other than those involving user input. (Help messages are displayed automatically when the Help key is pressed during user input.)

SHOW FIELD HELP displays the message, waits for the operator to press any key, erases the message, and then returns control to the application program.

Required Parameters

The application program must set the name of the field/control for which the help message is to be displayed in RMP--FIELD-NAME. No occurrence number is required, even for fields/controls with multiple occurrences, as the help message applies to each occurrence.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
5 | The panel is not in this library
6 | The library does not exist.
12 | Help message is not defined.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


SHOW PANEL ERROR

Execution

PERFORM RMP--SPE-PANELNAME

Description

This standard runtime function displays the error message, if any, that you defined for a panel. It complements the ACCEPT FIELD, EXECUTE EVENT, VALIDATE ALL FIELDS, and VALIDATE FIELD standard runtime functions by allowing the application program to display the existing error message in situations other than those involving user input. (RM/Panels automatically displays error messages during user input.)

SHOW PANEL ERROR displays the message, waits for the operator to press any key, erases the message, and then returns control to the application program.

Required Parameters

None.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
13 | Error message is not defined.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
ACCEPT FIELD
EXECUTE EVENT
VALIDATE ALL FIELDS
VALIDATE FIELD
C$RERR


SHOW PANEL HELP

Execution

PERFORM RMP--SPH-PANELNAME

Description

This standard runtime function displays the help message, if any, that you defined for a panel. It allows you to display, rather than re-create, existing help messages in situations other than those involving user input. (Help messages are displayed automatically when the Help key is pressed during user input.)

SHOW PANEL HELP displays the message, waits for the operator to press any key, erases the message, and then returns control to the application program.

Required Parameters

None.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
12 | Help message is not defined.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
C$RERR


UNCHECK MENU OPTION

Execution

PERFORM RMP--UMO-PANELNAME

Description

This standard runtime function removes a check from a pulldown menu command when it is displayed.

Required Parameters

The application program must be set to the name of the menu command to be unchecked in RMP--COMMAND-NAME.

Returned Values

None.

Additional Usage Notes

  • This standard runtime function is valid only for pulldown menu commands that can be, and are currently, checked.
  • An inverse standard runtime function, CHECK MENU OPTION, is also available.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
20 | The menu command name is invalid.
Parent topic: Standard Runtime Functions
Related reference
CHECK MENU OPTION
C$RERR


VALIDATE ALL FIELDS

Execution

PERFORM RMP--VAF-PANELNAME

Description

This standard runtime function validates values of all fields/controls on the panel. This is the same validation RM/Panels performs when a user enters a value into a field/control. VALIDATE ALL FIELDS provides a way to validate the values of fields/controls that the user has not yet entered or fields/controls that acquired values from some means other than user input.

VALIDATE ALL FIELDS validates each field/control in sequence of entry order until all fields/controls have been validated or an invalid field/control is found. If an invalid field/control is found, its name and occurrence number are reported to the application program. The application program determines what action to take next, either displaying an error message or reentering the field/control.

Required Parameters

None.

Returned Values

If no fields/controls are found to be invalid, RMP--VALID-INPUT is TRUE. If an invalid field/control is found, RMP--INVALID-INPUT is TRUE; RMP--FIELD-NAME is set to the name of the field/control; and RMP--FIELD-OCCUR is set to the field/control occurrence. Occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Additional Usage Notes

This standard runtime function provides the ability to validate all panel fields/controls when the user has completed input. It is especially useful to detect required fields/controls that have not been entered.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
VALIDATE FIELD
C$RERR


VALIDATE FIELD

Execution

PERFORM RMP--VF-PANELNAME

Description

This standard runtime function performs any validations you defined for the named panel field/control. It does not display any error message for the field/control, but simply reports the validity of the field/control data to the application program through RMP--VALID-INPUT.

Note This standard runtime function is not the preferred method of validating fields/controls in RM/Panels. Use the VALIDATE ALL FIELDS standard runtime function as the primary method to validate fields/controls. Use VALIDATE FIELD when only one field/control is to be validated.

Required Parameters

The application program must set the name of the field/control to be validated in RMP-- FIELD-NAME. If the field/control occurs more than once, the occurrence number must be specified in RMP--FIELD-OCCUR. The occurrence numbers are equivalent to COBOL subscripts and begin at 1.

Returned Values

If the field/control data is valid, RMP--VALID-INPUT is TRUE; otherwise RMP--INVALID-INPUT is TRUE.

Additional Usage Notes

This standard runtime function is not commonly used since field/control validation is performed whenever a panel field/control is input.

RMP--STATUS Values

Status value | Description
0 | The function executed successfully.
1 | The field/control name is invalid.
2 | The occurrence number is invalid.
5 | The panel is not in this library
6 | The library does not exist.
14 | A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact nature of the I/O error, use the C$RERR subprogram.
Parent topic: Standard Runtime Functions
Related reference
VALIDATE ALL FIELDS
C$RERR


Utility Functions

The RM/Panels utility functions are provided to allow you to control the overall behavior of the RM/Panels runtime system, rather than manipulate individual panels. Unlike the RM/Panels standard runtime functions described previously, the utility functions are not related to individual panels, are not generated into the panelname.PRC files, and do not require a panel work area parameter. These functions are included in your program through CALL statements.

The following table gives the name and abbreviation of each RM/Panels utility function.

Function | Abbreviation
DELETE TEMPORARY FILE | DTF
END MODELESS OPERATION | EMD
END POLLING | EP
HIDE MOUSE CURSOR | HMC
SET COLOR | SCO
SET MONOCHROME | SMO
SHOW MOUSE CURSOR | SMC
START MODELESS OPERATION | SMD
START POLLING | SP

Each utility function is described in the following sections. All parameters for RM/Panels utility functions are defined in Appendix B, Standard, Utility, and Extended Runtime Functions and Parameters.

  • DELETE TEMPORARY FILE
  • END MODELESS OPERATION
  • END POLLING
  • HIDE MOUSE CURSOR
  • SET COLOR
  • SET MONOCHROME
  • SHOW MOUSE CURSOR
  • START MODELESS OPERATION
  • START POLLING
Parent topic: Writing Programs
Related reference
Appendix B Standard Utility, and Extended Runtime Functions and Parameters


DELETE TEMPORARY FILE

Execution

CALL RMP--RUNTIME USING RMP--U-DTF RMP--PARAMETERS

Description

This utility function removes the temporary file that may have been created by the RM/Panels runtime system.

If dynamic changes are made to a panel during execution of an application, RM/Panels may create a temporary file to store the altered panel information. This file may also be created if modeless operation is used. The temporary file should be deleted before exiting from COBOL back to the operating system to prevent wasted disk space.

This utility function should not be performed when a CALLed program is exited, but when the COBOL run unit itself is about to be terminated.

Note: It is recommended to always perform this utility function before terminating a COBOL run unit that uses RM/Panels. If no temporary file has been created, the utility function does not perform any action.
Parent topic: Utility Functions


END MODELESS OPERATION

Execution

CALL RMP--RUNTIME USING RMP--U-EMD RMP--PARAMETERS

Description

This utility function tells the RM/Panels runtime system to end modeless operation, which was started with the START MODELESS OPERATION utility function.

Parent topic: Utility Functions
Related reference
START MODELESS OPERATION


END POLLING

Execution

CALL RMP--RUNTIME USING RMP--U-EP RMP--PARAMETERS

Description

This utility function instructs the RM/Panels runtime system to end the polling process, which was started with the START POLLING utility function.

Parent topic: Utility Functions
Related reference
START POLLING


HIDE MOUSE CURSOR

Execution

CALL RMP--RUNTIME USING RMP--U-HMC RMP--PARAMETERS

Description

This utility function removes the mouse cursor from the monitor.

When RM/Panels opens a panel library, it checks for the presence of a mouse. If a mouse is found, the mouse cursor is displayed. The mouse cursor remains visible until you remove it. You may wish to hide the mouse cursor temporarily while performing some lengthy process, or you may wish to hide it while executing a portion of the application that does not support the mouse. While the mouse cursor is hidden, RM/Panels disregards any mouse events.

If your application does not wish to support the mouse at all, simply do not include rmpmouse.exe with your application. If this file is not present, RM/Panels does not recognize the mouse.

Before exiting from COBOL back to the operating system, you should perform this utility function to hide the mouse cursor. If you fail to do this, the mouse cursor is displayed at the operating system prompt.

Note: Mouse support is not available for UNIX systems. The HIDE MOUSE CURSOR has no effect under Windows.
Parent topic: Utility Functions
Related reference
SHOW MOUSE CURSOR


SET COLOR

Execution

CALL RMP--RUNTIME USING RMP--U-SCO RMP--PARAMETERS

Description

This utility function instructs the RM/Panels runtime system to perform all subsequent screen output with color specifications.

This utility function does not automatically redisplay any information that is on the monitor. After executing this function, the application program should redisplay any information it wants to have redisplayed in color.

Use this utility function to cancel the effects of a previous SET MONOCHROME utility function or the setting of RMP--FORCE-MONO to TRUE in RMPANELS.WS. However, if RMP--FORCE-MONO remains TRUE, the runtime system reverts to monochrome output when a different panel library is opened, because RMP--FORCE-MONO is checked every time a library is opened. If the SET COLOR function is used to cancel the effects of RMP--FORCE-MONO, RMP--FORCE-MONO should be set to FALSE.

Parent topic: Utility Functions
Related reference
SET MONOCHROME


SET MONOCHROME

Execution

CALL RMP--RUNTIME USING RMP--U-SMO RMP--PARAMETERS

Description

This utility function instructs the RM/Panels runtime system to perform all subsequent screen output without color specifications.

RMPANELS.WS contains a parameter that can be set to force monochrome operation (RMP--FORCE-MONO), but this parameter is only checked when a panel library is opened. This utility function allows the application program to change to monochrome operation at any time.

This utility function does not automatically redisplay any information that is on the monitor. After executing this utility function, the application program should redisplay any information it wants to have redisplayed in monochrome.

Parent topic: Utility Functions
Related reference
SET COLOR


SHOW MOUSE CURSOR

Execution

CALL RMP--RUNTIME USING RMP--U-SMC RMP--PARAMETERS

Description

This utility function makes the mouse cursor visible on the monitor.

When RM/Panels opens a panel library, it checks for the presence of a mouse. If a mouse if found, the mouse cursor is displayed. This mouse cursor remains visible until you remove it with the HIDE MOUSE CURSOR utility function. After hiding the mouse cursor, you can use the SHOW MOUSE CURSOR utility function to make the mouse cursor visible again.

When the RM/Panels runtime system opens a panel library, it automatically makes the mouse cursor visible if it recognizes the mouse. The SHOW MOUSE CURSOR utility function is only needed if you hide the mouse cursor and then want to restore it.

Note: Mouse support is not available for UNIX systems. The SHOW MOUSE CURSOR function has no effect under Windows.
Parent topic: Utility Functions
Related reference
HIDE MOUSE CURSOR


START MODELESS OPERATION

Execution

CALL RMP--RUNTIME USING RMP--U-SMD RMP--PARAMETERS

Description

This utility function instructs the RM/Panels runtime system to begin modeless operation. Modeless behavior differs from modal behavior, which is the default.

In modal operation, a panel is displayed, information is entered on that and only that panel, then the panel is removed or possibly overlaid by another panel. In modal operation, the topmost panel is the only panel that can be accessed.

However, in modeless operation, the user can choose between a number of displayed panels. The chosen panel is displayed again on top of the other panels, and the user can work with that panel.

By default, RM/Panels works in a modal state. When an EXECUTE EVENT standard runtime function is performed, RM/Panels recognizes only events for the panel for which the function was performed. In a modeless state, RM/Panels recognizes a mouse click on any displayed panel as a request to access that panel, informs the application program which panel was chosen, and if the application program allows it, redisplays that panel on top of the others.

This process does not complicate RM/Panels programming nearly as much as you might think. It really just requires that a check be added to the event loop to see which panel was requested.

The following limitations apply to modeless behavior:

  • This utility function should be executed before any panels that are to be modeless are displayed. Any panels already displayed when this utility function is performed will be ignored.
  • DISPLAY statements should not be used to place information on panels that will be modeless. The RM/Panels runtime system will be automatically redisplaying these panels and you will not get an opportunity to display your information.
  • There is a limit of 2000 bytes of data for each panel that will be used in modeless operation.
Note: Modeless operation is not supported under Windows.
Parent topic: Utility Functions
Related reference
END MODELESS OPERATION


START POLLING

Execution

CALL RMP--RUNTIME USING RMP--U-SP RMP--PARAMETERS

Description

This utility function instructs the RM/Panels runtime system to begin a polling process, during which the EXECUTE EVENT standard runtime function will report a polling event to the application program whenever a specified amount of time has elapsed.

At first this might seem similar to the time-out event that is available for fields/controls, but the time-out interval is relative to the time at which the field/control gained keyboard focus. The polling interval is relative to actual clock time.

The polling event is reported only by the EXECUTE EVENT standard runtime function and is subject to limitations. Internal processes of the RM/Panels runtime system are not interrupted to report the event, therefore, the polling event is reported as soon as possible after the polling interval has passed. You should allow for some delay in receiving these events. It would be unwise to count polling intervals to determine total elapsed time, especially when a very short polling period is set, as some could be missed.

Required Parameters

RMP--POLLING-INTERVAL must be set to the polling interval in seconds. The value must be in the range 1–999999.

Parent topic: Utility Functions
Related reference
END POLLING
EXECUTE EVENT


Appendix A: Master Copy File RMPANELS.WS

RMPANELS.WS is a master copy file that must be copied into the Working-Storage Section of each application program that uses RM/Panels. It contains a parameter block used to pass parameters between the program and the RM/Panels runtime system.

Appendix B lists the contents of RMPANELS.WS and describes each field contained in the file.

Note: The RM/Panels parameter block contained in RMPANELS.WS may also be passed to CALLed programs. This allows changes to the key configuration information to be made in a “high level” program and affect all the programs it calls.

To declare the parameter block in a called program, use RMPANELS.LNK instead of RMPANELS.WS. RMPANELS.WS is a copy of RMPANELS.WS with the value clauses removed (but the 88-level items not removed) so that it compiles cleanly in the Linkage Section. Never use RMPANELS.WS in the Working-Storage Section.

Another strategy can be used to make changes in the RM/Panels parameter block available to all programs. You can use a file called RMPANELS.EXT to declare the RMPANELS parameter block as an external variable in the Working-Storage Section of all programs. (RMPANELS.EXT is identical to RMPANELS.WS, but with a declaration of EXTERNAL.)

You must initialize certain variables when using RMPANELS.EXT before any program calls the RM/Panels runtime system. The initialization needs to be done only once by one program no matter how many programs are involved. The external declaration of the parameter block causes the values to be retained. The following statements initialize the necessary variables.

These statements must be included exactly as shown:

MOVE 200 TO RMP--VERSION.
MOVE X"0102030405060708090A0B0C0D0E0F"
    TO RMP--FUNCTION-CODES (1:15).
MOVE X"101112131415161718191A1B1C1D"
    TO RMP--FUNCTION-CODES (16:14).
MOVE X"F1F2F3F4F5F6F7F8F9"
    TO RMP--FUNCTION-CODES (30:9).
MOVE X"808182838485868788898A8B8C8D8E8F"
    TO RMP--FUNCTION-CODES (39:16).
MOVE X"909192939495969798999A9B9C9D"
    TO RMP--FUNCTION-CODES (55:14).
MOVE X"A0A1A2A3"
    TO RMP--FUNCTION-CODES (69:4).
MOVE X"B0B1B3B4B7B8B9BA"
    TO RMP--FUNCTION-CODES (73:8).

These statements can be tailored to your preferences:

MOVE "runpan2" TO RMP--RUNTIME.
MOVE SPACE TO RMP--TEMP-FILE-NAME RMP--TEMP-FILE-DIRECTORY.
SET RMP--DEBUG RMP--PROT-PREVENT-CHAR TO TRUE.
SET RMP--GEN-HELP-SUP RMP--FORCE-MONO TO FALSE.
MOVE "001000000000000" TO RMP--HELP-KEY-VALUES.
MOVE "013000000000000" TO RMP--RETURN-KEY-VALUES.
MOVE "053000000000000" TO RMP--NEXT-FIELD-KEY-VALUES.
MOVE "052000000000000" TO RMP--PREV-FIELD-KEY-VALUES.
MOVE "058000000000000" TO RMP--NEXT-GROUP-KEY-VALUES.
MOVE "056000000000000" TO RMP--PREV-GROUP-KEY-VALUES.
MOVE "027000000000000" TO RMP--PULLDOWN-KEY-VALUES.
  • Contents of RMPANELS WS
  • RMPANELS WS Field Definitions
Parent topic: RM/Panels


Contents of RMPANELS WS

01 RMP--PARAMETERS.
   03 RMP--INTERNAL-VALUES.
     05 RMP--VERSION PIC 9(4) VALUE 200.
   03 RMP--CONFIGURATION-PARAMETERS.
     05 RMP--RUNTIME PIC X(80) VALUE "runpan2".
     05 RMP--TEMP-FILE-NAME PIC X(12) VALUE SPACE.
     05 RMP--TEMP-FILE-DIRECTORY PIC X(80) VALUE SPACE.
     05 RMP--DEBUG-SW PIC X VALUE "N".
        88 RMP--DEBUG VALUE "Y" WHEN FALSE "N".
     05 RMP--PROT-CHAR-SW PIC X VALUE "N".
        88 RMP--PROT-ALLOW-CHAR VALUE "Y".
        88 RMP--PROT-PREVENT-CHAR VALUE "N".
     05 RMP--FORCE-MONO-KEY PIC 9(3).
     05 RMP--USER-EDIT-KEY PIC 9(3).
     05 RMP--BACKSPACE-KEY PIC 9(3).
     05 RMP--GEN-HELP-SUP-SW PIC X VALUE "N".
        88 RMP--GEN-HELP-SUP VALUE "Y" WHEN FALSE "N".
     05 RMP--KEY-CONFIGURATION.
        07 RMP--HELP-KEY-VALUES PIC X(15)
                                VALUE "001000000000000".
        07 RMP--RETURN-KEY-VALUES PIC X(15)
                                VALUE "013000000000000".
        07 RMP--NEXT-FIELD-KEY-VALUES PIC X(15)
                                VALUE "053000000000000".
        07 RMP--PREV-FIELD-KEY-VALUES PIC X(15)
                                VALUE "052000000000000".
        07 RMP--NEXT-GROUP-KEY-VALUES PIC X(15)
                                VALUE "058000000000000".
        07 RMP--PREV-GROUP-KEY-VALUES PIC X(15)
                                VALUE "056000000000000".
        07 RMP--PULLDOWN-KEY-VALUES PIC X(15)
                                VALUE "027000000000000".
   03 RMP--GENERAL-FUNCTION-PARAMS.
      05 RMP--LIBRARY PIC X(80).
      05 RMP--FIELD-NAME PIC X(30).
      05 RMP--FIELD-OCCUR PIC 9(4).
      05 RMP--FIELD-SEQ PIC 9(3).
      05 RMP--ATTRIBUTE PIC X.
      05 RMP--PALETTE PIC 99.
      05 RMP--SUPPRESS-EVENT-RESET-SW PIC X VALUE "N".
         88 RMP--SUPPRESS-EVENT-RESET VALUE "Y" WHEN FALSE "N".
      05 RMP--FORCE-MONO-SW PIC X VALUE "N".
         88 RMP--FORCE-MONO VALUE "Y" WHEN FALSE "N".
      05 RMP--POLLING-INTERVAL PIC 9(6).
   03 RMP--PANEL-DISPLAY-PARAMS.
      05 RMP--SHOW-FIELDS-SW PIC X VALUE "N".
         88 RMP--SHOW-FIELDS VALUE "Y" WHEN FALSE "N".
      05 RMP--CLEAR-SW PIC X VALUE "N".
         88 RMP--CLEAR VALUE "Y" WHEN FALSE "N".
      05 RMP--WINDOW-SW PIC X VALUE SPACE.
         88 RMP--WINDOW VALUE "Y" WHEN FALSE "N".
      05 RMP--PANEL-LINE PIC 9(3).
      05 RMP--PANEL-POS PIC 9(3).
      05 RMP--BEEP-SW PIC X VALUE "N".
         88 RMP--BEEP VALUE "Y" WHEN FALSE "N".
   03 RMP--EXECUTE-EVENT-PARAMS.
      05 RMP--EE-CONTROL-PARAMS.
         07 RMP--REPEAT-EVENT-SW PIC X VALUE "N".
            88 RMP--REPEAT-EVENT VALUE "Y" WHEN FALSE "N".
         07 RMP--FIRST-FIELD-SW PIC X VALUE "N".
            88 RMP--FIRST-FIELD VALUE "Y" WHEN FALSE "N".
         07 RMP--NEXT-FIELD PIC X(30).
         07 RMP--NEXT-OCCUR PIC 9(3).
         07 RMP--NEXT-CURSOR-POS PIC 9(4).
         07 RMP--NEXT-FIELD-SEQ PIC 9(3).
         07 RMP--SUPPRESS-SELECTION-SW PIC X VALUE "N".
            88 RMP--SUPPRESS-SELECTION VALUE "Y" WHEN FALSE "N".
      05 RMP--EE-RETURNED-PARAMS.
         07 RMP--LAST-FIELD PIC X(30).
         07 RMP--LAST-OCCUR PIC 9(3).
         07 RMP--LAST-CURSOR-POS PIC 9(4).
         07 RMP--LAST-FIELD-SEQ PIC 9(3).
         07 RMP--EVENT-TYPE PIC X VALUE SPACE.
            88 RMP--BUTTON-PRESS VALUE "B".
            88 RMP--BOX-CHANGED VALUE "C".
            88 RMP--MENU-COMMAND VALUE "M".
            88 RMP--RADIO-BTN-PRESSED VALUE "R".
            88 RMP--LB-CHOICE-SELECTED VALUE "L".
            88 RMP--SB-MOVED VALUES ARE "S" "D" "d" "U" "u".
            88 RMP--SB-PAGE-UP VALUE "U".
            88 RMP--SB-PAGE-DOWN VALUE "D".
            88 RMP--SB-STEP-UP VALUE "u".
            88 RMP--SB-STEP-DOWN VALUE "d".
            88 RMP--SB-DRAG VALUE "S".
            88 RMP--TIME-OUT-OCCURRED VALUE "T".
            88 RMP--POLLING-OCCURRED VALUE "P".
            88 RMP--PANEL-MOVED VALUE "F".
         07 RMP--DATA-CHANGED-SW PIC X VALUE "N".
            88 RMP--DATA-CHANGED VALUE "Y" WHEN FALSE "N".
         07 RMP--PULLDOWN-PARAMETERS.
            09 RMP--COMMAND-NAME PIC X(30).
            09 RMP--COMMAND-TEXT PIC X(30).
         07 RMP--MOUSE-CLICK-TYPE PIC X VALUE SPACE.
            88 RMP--DOUBLE-CLICK VALUE "D".
            88 RMP--SINGLE-CLICK VALUE "S".
         07 RMP--LAST-PANEL PIC X(20).
         07 RMP--REQUESTED-PANEL PIC X(20).
         07 RMP--PROT-CHAR PIC X.
         07 FILLER PIC X(96).
   03 RMP--RETURNED-VALUES.
      05 RMP--EXCEPTION-NUMBER PIC 9(3).
         88 F10-KEY VALUE 10.
         88 ESCAPE-KEY VALUE 27.
      05 RMP--MOUSE-PRESENT-SW PIC X VALUE SPACE.
         88 RMP--MOUSE-PRESENT VALUE "Y" WHEN FALSE "N".
      05 RMP--VALID-INPUT-SW PIC X VALUE SPACE.
         88 RMP--VALID-INPUT VALUE "Y".
         88 RMP--INVALID-INPUT VALUE "N".
      05 RMP--STATUS PIC 9(4) VALUE 0.
         88 RMP--VALID-FUNCTION VALUE 0.
         88 RMP--FIELD-INVALID VALUE 1.
         88 RMP--OCCUR-INVALID VALUE 2.
         88 RMP--FUNCTION-INVALID VALUE 3.
         88 RMP--ATTRIBUTE-INVALID VALUE 4.
                  88 RMP--PANEL-INVALID VALUE 5.
                  88 RMP--LIBRARY-INVALID VALUE 6.
                  88 RMP--CONFIG-INVALID VALUE 7.
                  88 RMP--NO-FIELDS VALUE 8.
                  88 RMP--NO-ENABLED-FIELDS VALUE 9.
                  88 RMP--PANEL-NOT-DISPLAYED VALUE 10.
                  88 RMP--PALETTE-INVALID VALUE 11.
                  88 RMP--NO-HELP-DEFINED VALUE 12.
                  88 RMP--NO-ERROR-DEFINED VALUE 13.
                  88 RMP--IO-ERROR VALUE 14.
                  88 RMP--FIELD-DISABLED VALUE 15.
                  88 RMP--WINDOW-ERROR VALUE 16.
                  88 RMP--MENU-COMMAND-INVALID VALUE 20.
                  88 RMP--MODELESS-DATA-OVERLOAD VALUE 21.
                  88 RMP--NO-PULLDOWN VALUE 22.
                  88 RMP--WRONG-FIELD-TYPE VALUE 23.
                  88 RMP--TOO-MANY-PANELS VALUE 40.
                  88 RMP--CANNOT-CREATE-TEMP VALUE 41.
                  88 RMP--CANNOT-OPEN-TEMP VALUE 42.
                  88 RMP--API-PARAM-MISSING VALUE 1001.
                  88 RMP--API-MSG-NOT-DEFINED VALUE 1002.
                  88 RMP--API-PD-OPTION-INVALID VALUE 1003.
                  88 RMP--API-UNCHECKABLE VALUE 1004.
     03 RMP--FUNCTION-CODES.
           05 RMP--CAF PIC X VALUE X"01".
           05 RMP--CPP PIC X VALUE X"02".
           05 RMP--DAF PIC X VALUE X"03".
     05 RMP--DF PIC X VALUE X"04".
     05 RMP--DFI PIC X VALUE X"05".
     05 RMP--DP PIC X VALUE X"06".
     05 RMP--EE PIC X VALUE X"07".
     05 RMP--EFI PIC X VALUE X"08".
     05 RMP--IAF PIC X VALUE X"09".
     05 RMP--IF PIC X VALUE X"0A".
     05 RMP--RP PIC X VALUE X"0B".
     05 RMP--SFA PIC X VALUE X"0C".
     05 RMP--SFE PIC X VALUE X"0D".
     05 RMP--SFH PIC X VALUE X"0E".
     05 RMP--SPE PIC X VALUE X"0F".
     05 RMP--SPH PIC X VALUE X"10".
     05 RMP--VAF PIC X VALUE X"11".
     05 RMP--VF PIC X VALUE X"12".
     05 RMP--SSR PIC X VALUE X"13".
     05 RMP--EMO PIC X VALUE X"14".
     05 RMP--DMO PIC X VALUE X"15".
     05 RMP--CMO PIC X VALUE X"16".
     05 RMP--UMO PIC X VALUE X"17".
     05 RMP--EA PIC X VALUE X"18".
     05 RMP--DA PIC X VALUE X"19".
     05 RMP--AF PIC X VALUE X"1A".
     05 RMP--PUM PIC X VALUE X"1B".
     05 FILLER PIC X(2).
     05 RMP--U-SMC PIC X VALUE X"F1".
     05 RMP--U-HMC PIC X VALUE X"F2".
     05 RMP--U-SMD PIC X VALUE X"F3".
     05 RMP--U-EMD PIC X VALUE X"F4".
     05 RMP--U-DTF PIC X VALUE X"F5".
     05 RMP--U-SMO PIC X VALUE X"F6".
     05 RMP--U-SCO PIC X VALUE X"F7".
     05 RMP--U-SP PIC X VALUE X"F8".
     05 RMP--U-EP PIC X VALUE X"F9".
     05 RMP--E-CL PIC X VALUE X"80".
     05 RMP--E-AL PIC X VALUE X"81".
     05 RMP--E-CP PIC X VALUE X"82".
     05 RMP--E-AP PIC X VALUE X"83".
     05 RMP--E-SPL PIC X VALUE X"84".
     05 RMP--E-GPL PIC X VALUE X"85".
     05 RMP--E-GPC PIC X VALUE X"86".
     05 RMP--E-SPC PIC X VALUE X"87".
     05 RMP--E-GFD PIC X VALUE X"88".
     05 RMP--E-AFD PIC X VALUE X"89".
     05 RMP--E-CFD PIC X VALUE X"8A".
     05 RMP--E-GFV PIC X VALUE X"8B".
     05 RMP--E-SFV PIC X VALUE X"8C".
     05 RMP--E-GPT PIC X VALUE X"8D".
     05 RMP--E-SPT PIC X VALUE X"8E".
     05 RMP--E-GPD PIC X VALUE X"8F".
     05 RMP--E-SPD PIC X VALUE X"90".
     05 RMP--E-GMS PIC X VALUE X"91".
     05 RMP--E-SMS PIC X VALUE X"92".
     05 RMP--E-SHM PIC X VALUE X"93".
     05 RMP--E-SPLT PIC X VALUE X"94".
     05 RMP--E-GPLT PIC X VALUE X"95".
     05 RMP--E-SLC PIC X VALUE X"96".
     05 RMP--E-GLC PIC X VALUE X"97".
     05 FILLER PIC X(6).
     05 RMP--E-GFN PIC X VALUE X"A0".
     05 FILLER PIC X(3).
     05 RMP--E-SP PIC X VALUE X"B0".
     05 RMP--E-DC PIC X VALUE X"B1".
     05 RMP--E-DFD PIC X VALUE X"B3".
     05 RMP--E-HDP PIC X VALUE X"B4".
     05 RMP--E-RMO PIC X VALUE X"B7".
     05 FILLER PIC X(2).
     05 RMP--E-UDP PIC X VALUE X"BA".
   03 RMP--SCROLL-BAR-WS.
     05 RMP--SB-MIN PIC 9(4).
     05 RMP--SB-MAX PIC 9(4).
     05 RMP--SB-STEP PIC 9(4).
     05 RMP--SB-PAGE PIC 9(4).
     05 RMP--SB-OPERATED PIC X(30).
   03 FILLER PIC X(50).
Parent topic: Appendix A: Master Copy File RMPANELS.WS
Related information
RMPANELS WS Field Definitions


RMPANELS WS Field Definitions

01 RMP--PARAMETERS.

This is the group-level name used to reference the entire parameter block.

03 RMP--INTERNAL-VALUES.

This area contains values that are used solely by RM/Panels.

05 RMP--VERSIONPIC 9(4) VALUE 210.

This field allows future versions of the RM/Panels runtime system to provide backward compatibility with the current version.

03 RMP--CONFIGURATION-PARAMETERS.

This area contains values that configure the behavior of the RM/Panels runtime system.

05 RMP--RUNTIMEPIC X(80) VALUE "runpan2".

This area contains the name of the RM/Panels runtime system program. The value clause contains the default value. This default can be changed by individual programs at runtime execution, or can be modified in RMPANELS.WS before programs are compiled.

05 RMP--TEMP-FILE-NAMEPIC X(12) VALUE SPACE.

If dynamic changes are made to a panel, a temporary file may be created by the RM/Panels runtime system to store these changes. RM/Panels generates a filename if this field is blank, but if you supply a filename here it is used instead. Supplying a filename does not require you to supply a directory in RMP--TEMP-FILE-DIRECTORY.

05 RMP--TEMP-FILE-DIRECTORYPIC X(80) VALUE SPACE.

If dynamic changes are made to a panel, a temporary file may be created by the RM/Panels runtime system to store these changes. RM/Panels places this file in the current working directory if this field is blank, but if you supply a directory name here it is used instead. Supplying a directory name does not require you to supply a filename in RMP--TEMP-FILE-NAME.

05 RMP--DEBUG-SWPIC X VALUE "N."
   88 RMP--DEBUG VALUE "Y" WHEN FALSE "N".

This parameter can be used to enable the RM/Panels debugging mode. In this mode, extensive information is presented on the screen whenever an invalid standard runtime function request is made. The debugging mode should be used during program development. The parameter is set by the following statement:

SET RMP--DEBUG TO TRUE.
05 RMP--PROT-CHAR-SWPIC X VALUE "N".
   88 RMP--PROT-ALLOW-CHAR VALUE "Y".
   88 RMP--PROT-PREVENT-CHAR VALUE "N".

This parameter is used to control the type of keyboard action that returns control to the application program when a protected field/control is being entered. If RMP--PROT-ALLOW-CHAR is TRUE, a normal character key returns control to the application program in addition to exception keys. If RMP--PROT-PREVENT-CHAR is TRUE, only exception keys return control to the application program when a protected field/control is being entered. The parameter is set by the following statement:

SET RMP--PROT-ALLOW-CHAR TO TRUE.
05 RMP--FORCE-MONO-KEYPIC 9(3).

This parameter is used to indicate a field termination code that toggles between color and monochrome on the monitor, regardless of the type of video adapter or terminal being used. The parameter is set by the following statement:

MOVE 94 TO RMP--FORCE-MONO-KEY.

or by adding a value clause:

05 RMP--BACKSPACE-KEYPIC 9(3) VALUE 75.
05 RMP--USER-EDIT-KEYPIC 9(3).

This parameter is used to indicate a field termination code that starts the End-User Panel Editor. The parameter is set by the following statement:

MOVE 95 TO RMP--USER-EDIT-KEY.

or by adding a value clause:

05 RMP--BACKSPACE-KEYPIC 9(3) VALUE 75.
05 RMP--BACKSPACE-KEYPIC 9(3).

This parameter is used to indicate the field termination code that is generated by the Backspace key. The parameter is set by the following statement:

MOVE 75 TO RMP--BACKSPACE-KEY.

or by adding a value clause:

05 RMP--BACKSPACE-KEYPIC 9(3) VALUE 75.
05 RMP--GEN-HELP-SUP-SWPIC X VALUE "N".
   88 RMP--GEN-HELP-SUP VALUE "Y" WHEN FALSE "N".

This parameter is used to suppress the ability to display the panel help message when a field/control-specific help message is displayed. This parameter is set by the following statement:

SET RMP--GEN-HELP-SUP TO TRUE.
05 RMP--KEY-CONFIGURATION.

This area contains values that identify specific keys to the RM/Panels runtime system. These keys control RM/Panels behavior, such as displaying help messages, or moving to the previous field/control. Default values are included, but these can be changed by individual programs at runtime execution, or modified in RMPANELS.WS before programs are compiled.

Each entry relates to a specific type of behavior and contains room for up to five keys that RM/Panels recognizes. The values assigned to the entry are three-digit RM/COBOL field termination codes.

The order of the values is not important. When modifying values, be careful to use three-digit values and do not add spaces. For example:

The help function in the default configuration is assigned to the F1 key.

The F1 key is field termination code 1, so the default configuration is:

07 RMP--HELP-KEY-VALUES PIC X(15) VALUE "001000000000000".

If you want the F3 key (field termination code 3) and the F9 key (field termination code 9) to also function as help keys, you would change the help key configuration to the following:

07 RMP--HELP-KEY-VALUES PIC X(15) VALUE "001003009000000".
07 RMP--HELP-KEY-VALUESPIC X(15) VALUE "001000000000000".

This area specifies the field termination codes that initiate the automatic help messages provided by RM/Panels.

07 RMP--RETURN-KEY-VALUESPIC X(15) VALUE "013000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as the Enter key.

07 RMP--NEXT-FIELD-KEY-VALUES PIC X(15) VALUE "053000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as a request to move to the next field/control on the panel.

07 RMP--PREV-FIELD-KEY-VALUES PIC X(15) VALUE "052000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as a request to move to the previous field/control on the panel.

07 RMP--NEXT-GROUP-KEY-VALUES PIC X(15) VALUE "058000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as a request to move to the next group on the panel.

07 RMP--PREV-GROUP-KEY-VALUES PIC X(15) VALUE "056000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as a request to move to the previous group on the panel.

07 RMP--PULLDOWN-KEY-VALUESPIC X(15) VALUE "027000000000000".

This area specifies the field termination codes that should be interpreted by RM/Panels as a request to activate a pulldown menu.

03 RMP--GENERAL-FUNCTION-PARAMS.

This area contains parameters that are used with a number of different standard runtime functions.

05 RMP--LIBRARYPIC X(80).

This parameter identifies the panel library that contains the panels to be used. It must be set before the first panel is used, and set again whenever a new panel library is needed.

05 RMP--FIELD-NAMEPIC X(30).

This parameter is used with many standard runtime functions to identify a specific panel field/control.

05 RMP--FIELD-OCCURPIC 9(4).

This parameter is used with many standard runtime functions to identify a specific occurrence of a panel field/control.

05 RMP--FIELD-SEQPIC 9(3).

This parameter is used with many standard runtime functions to identify a panel field/control by the order in which it is entered on the panel.

05 RMP--ATTRIBUTEPIC X.

This parameter is used to specify an attribute value for the SET FIELD ATTRIBUTE standard runtime function.

05 RMP--PALETTEPIC 99.

This parameter is used to select a palette for the DISPLAY PANEL and CHANGE PANEL PALETTE standard runtime functions.

05 RMP--SUPPRESS-EVENT-RESET-SW PIC X VALUE "N".
   88 RMP--SUPPRESS-EVENT-RESET VALUE "Y" WHEN FALSE "N".

This parameter is used with the ENABLE/DISABLE FIELD standard runtime function, but it is included here because it controls the EXECUTE EVENT standard runtime function. It prevents RM/Panels from resetting the values of RMP--NEXT-FIELD and RMP--NEXT-OCCUR when a field/control is enabled or disabled.

05 RMP--FORCE-MONO-SWPIC X VALUE "N".
   88 RMP--FORCE-MONO VALUE "Y" WHEN FALSE "N".

This parameter is used to tell the RM/Panels runtime system to operate in monochrome mode, suppressing all colors. Because this parameter is checked by the runtime system when a library is opened, it must be set before a library is open. Setting RMP--FORCE-MONO to TRUE after opening a library has no effect until a new library is opened. This parameter is set by the following statement:

SET RMP--FORCE-MONO TO TRUE.
05 RMP--POLLING-INTERVALPIC 9(6).

This parameter is used by the utility function, START POLLING, to specify a polling interval in seconds.

03 RMP--PANEL-DISPLAY-PARAMS.

This area contains parameters for the DISPLAY PANEL standard runtime function. RMP--CLEAR-SW is also a parameter for the REMOVE PANEL standard runtime function.

05 RMP--SHOW-FIELDS-SWPIC X VALUE "N".
   88 RMP--SHOW-FIELDS VALUE "Y" WHEN FALSE "N".

This parameter is used to display the values of panel fields/controls at the same time the panel is displayed. The parameter is set by the following statement:

SET RMP--SHOW-FIELDS TO TRUE.
05 RMP--CLEAR-SWPIC X VALUE "N".
   88 RMP--CLEAR VALUE "Y" WHEN FALSE "N".

This parameter is used to erase the entire screen before a panel is displayed, or when a panel is erased. The parameter is set by the following statement:

SET RMP--CLEAR TO TRUE.
05 RMP--WINDOW-SWPIC X VALUE SPACE.
   88 RMP--WINDOW VALUE "Y" WHEN FALSE "N".

This parameter is used to override the default windowing characteristic of a panel. To force a panel to display as a window, set the parameter by the following statement:

SET RMP--WINDOW TO TRUE.

To force a panel to display without behaving as a window, set the parameter by the following statement:

SET RMP--WINDOW TO FALSE.
05 RMP--PANEL-LINEPIC 9(3).

This parameter is used to control the screen line at which a panel is displayed. Leaving this value at 0 accepts the default. Setting this parameter to 999 centers the panel vertically. Setting any other value displays the panel at the specified line.

05 RMP--PANEL-POSPIC 9(3).

This parameter is used to control the screen column at which a panel is displayed. Leaving this value at 0 accepts the default. Setting this parameter to 999 centers the panel horizontally. Setting any other value displays the panel at the specified column.

05 RMP--BEEP-SWPIC X VALUE "N".
   88 RMP--BEEP VALUE "Y" WHEN FALSE "N".

This parameter is used to generate a beep when a panel is displayed. The parameter is set by the following statement:

SET RMP--BEEP TO TRUE.
03 RMP--EXECUTE-EVENT-PARAMS.

These fields are parameters or returned values related to the EXECUTE EVENT standard runtime function.

05 RMP--EE-CONTROL-PARAMS.

These parameters are used to control the behavior of a single execution of the EXECUTE EVENT standard runtime function.

07 RMP--REPEAT-EVENT-SWPIC X VALUE "N".
   88 RMP--REPEAT-EVENT VALUE "Y" WHEN FALSE "N".

This parameter is used to force the RM/Panels runtime system to repeat the last event executed on this panel. It is set by the following statement:

SET RMP--REPEAT-EVENT TO TRUE.
07 RMP--FIRST-FIELD-SWPIC X VALUE "N".
   88 RMP--FIRST-FIELD VALUE "Y" WHEN FALSE "N".

This parameter is used to force the RM/Panels runtime system to begin user input with the first field/control on the panel. The parameter is set by the following statement:

SET RMP--FIRST-FIELD TO TRUE.
07 RMP--NEXT-FIELDPIC X(30).

This parameter is set by the RM/Panels runtime system to indicate the name of the field/control that will be entered next by the user. It may be modified by the application program to force input of a different field/control.

07 RMP--NEXT-OCCURPIC 9(3).

This parameter is set by the RM/Panels runtime system to indicate the occurrence of the field/control that will be entered next by the user. It may be modified by the application program to force input of a different occurrence.

07 RMP--NEXT-CURSOR-POSPIC 9(4).

This parameter is automatically set to zero by the RM/Panels runtime system and causes the cursor to move to the start of a field/control. By setting this parameter to a value other than zero, you can control the character position that the cursor initially moves to in a field/control.

Note: This value may be ignored under some graphical user interfaces.
07 RMP--NEXT-FIELD-SEQPIC 9(3).

This parameter is automatically set to zero by the RM/Panels runtime system and causes the cursor to move to the first enabled field/control. By setting this parameter to a value other than zero, you can control the field/control that is input next by entry order number.

07 RMP--SUPPRESS-SELECTION-SWPIC X VALUE "N".
   88 RMP--SUPPRESS-SELECTIONVALUE "Y" WHEN FALSE "N".

Setting this parameter to TRUE prevents the field/control being input during the next EXECUTE EVENT standard runtime function from being displayed with the selected attribute, even though it has the keyboard focus.

05 RMP--EE-RETURNED-PARAMS.

The parameters in this area contain values returned by the RM/Panels EXECUTE EVENT standard runtime function.

07 RMP--LAST-FIELDPIC X(30).

This parameter is used by the RM/Panels runtime system to indicate the name of the field/control that was just entered by the user.

07 RMP--LAST-OCCURPIC 9(3).

This parameter is used by the RM/Panels runtime system to indicate the occurrence of the field/control that was just entered by the user.

07 RMP--LAST-CURSOR-POSPIC 9(4).

This parameter is set to the location of the keyboard cursor, relative to the start of the field/control, when input was terminated. It is set only for input type fields/controls.

Note: This value may not be reported under some graphical user interfaces.
07 RMP--LAST-FIELD-SEQPIC 9(3).

This parameter is set to the entry order number of the field/control that was just entered by the user.

07 RMP--EVENT-TYPEPIC X VALUE SPACE.

This parameter is set by the RM/Panels runtime system to describe the type of event that just occurred. If none of the following conditions occur, input is terminated “normally”, that is, by auto exit or by pressing a field termination key.

88 RMP--BUTTON-PRESS VALUE "B".

This condition indicates that a push button was pressed. The name of the push button is contained in RMP--NEXT-FIELD. The condition-name representing the button in panelname-WS is also set to TRUE.

88 RMP--BOX-CHANGED VALUE "C".

This condition indicates that a check box was toggled. The name of the check box is contained in RMP--NEXT-FIELD.

88 RMP--MENU-COMMAND VALUE "M".

This condition indicates that a pulldown menu command was selected. The name and text of the command are contained in RMP--COMMAND-NAME and RMP--COMMAND-TEXT, respectively.

88 RMP--RADIO-BTN-PRESSED VALUE "R".

This condition indicates that a radio button was pressed. The name of the radio button is contained in RMP--NEXT-FIELD.

88 RMP--LB-CHOICE-SELECTED VALUE "L".

This condition indicates that a list box choice was selected. The name of the list box is contained in RMP--NEXT-FIELD.

88 RMP--SB-MOVED VALUES ARE "S" "D" "d" "U" "u".

This condition indicates that a scroll bar's thumb position was changed. The name of the scroll bar is reported in RMP--SB- OPERATED because scroll bars, unlike other fields/controls, do not receive keyboard focus. The following conditions give more detail on how the scroll bar thumb was moved.

88 RMP--SB-PAGE-UP VALUE "U".

This condition indicates that a scroll bar's thumb was moved up by clicking above the thumb.

88 RMP--SB-PAGE-DOWN VALUE "D".

This condition indicates that a scroll bar's thumb was moved down by clicking below the thumb.

88 RMP--SB-STEP-UP VALUE "u".

This condition indicates that a scroll bar's thumb was moved up by clicking on the up arrow.

88 RMP--SB-STEP-DOWN VALUE "d".

This condition indicates that a scroll bar's thumb was moved down by clicking on the down arrow.

88 RMP--SB-DRAG VALUE "S".

This condition indicates that a scroll bar's thumb was moved by dragging it.

88 RMP--TIME-OUT-OCCURRED VALUE "T".

This condition indicates that a “time out” occurred.

88 RMP--POLLING-OCCURRED VALUE "P".

This condition indicates that the polling interval established with the START POLLING utility function has elapsed.

88 RMP--PANEL-MOVED VALUE "F".

This condition indicates that the user moved the panel and that RM/Panels has repainted the panel and its fields. If you used a DISPLAY statement to place information on the panel, you need to display it again.

07 RMP--DATA-CHANGED-SWPIC X VALUE "N".
   88 RMP--DATA-CHANGED VALUE "Y" WHEN FALSE "N".

This condition indicates that the value of a field/control was changed by the last event. There is no indication of the field/control that was changed, because it is possible to change two fields/controls with one event. When a user types input to an input field/control and then clicks on a check box, both fields/controls change. This parameter allows you to bypass validation routines when no data has been changed on the panel.

07 RMP--PULLDOWN-PARAMETERS.

These parameters report the name and text of a pulldown menu command when it is selected.

09 RMP--COMMAND-NAMEPIC X(30).

This parameter reports the name of a pulldown menu command when it is selected. This name is an internal value that is not displayed to the user. Programs should check this value, rather than the text of the command, to maintain the logical, rather than physical, connection to the user interface.

09 RMP--COMMAND-TEXTPIC X(30).

This parameter reports the text of a pulldown menu command when it is selected. Programs are discouraged from checking this value and should instead use RMP--COMMAND-NAME.

07 RMP--MOUSE-CLICK-TYPEPIC X VALUE SPACE.

This parameter reports the type of mouse click performed on a field/control.

88 RMP--DOUBLE-CLICK VALUE "D".

This condition indicates that the mouse was double clicked on the field/control. Fields/controls must be configured to allow a double click.

88 RMP--SINGLE-CLICK VALUE "S".

This condition indicates that the mouse was single clicked on the field/control. All enabled fields/controls allow a single click.

07 RMP--LAST-PANELPIC X(20).

This parameter reports the name of the panel that was most recently accessed and is useful when implementing modeless behavior.

07 RMP--REQUESTED-PANELPIC X(20).

This parameter reports the name of an underlying panel that was selected during modeless behavior. This tells the application program the panel that should be used for the next EXECUTE EVENT standard runtime function to allow the panel to be elevated to the top level on the monitor.

07 RMP--PROT-CHARPIC X.

If a character key is pressed during protected field/control entry and RMP--PROT-ALLOW-CHAR is TRUE, this parameter contains the character that was pressed and RMP--EXCEPTION-NUMBER is 0. If an exception key is pressed, RMP--EXCEPTION-NUMBER contains the field termination code and is set to SPACE.

07 FILLERPIC X(96).

This area is reserved for future use.

03 RMP--RETURNED VALUES.

This area contains values that are returned by the RM/Panels runtime system.

05 RMP--EXCEPTION-NUMBERPIC 9(3).
   88 F10-KEY VALUE 10.
   88 ESCAPE-KEY VALUE 27.

This parameter is used by the RM/Panels runtime system to indicate to the application the key that was used to terminate user input. The value returned is the same value that the ON EXCEPTION clause returns for the key.

Level 88 condition-names are added after this parameter to allow the application program to easily interpret the key pressed. RETURN-KEY and ESCAPE-KEY are just samples that can be renamed, deleted, or added to. The names and values in this area are not important to the standard runtime function of RM/Panels. They are solely for the use of the application program.

05 RMP--MOUSE-PRESENT-SWPIC X VALUE SPACE.
   88 RMP--MOUSE-PRESENT VALUE "Y" WHEN FALSE "N".

This parameter is set by the RM/Panels runtime system whenever a library is opened. It lets the application program know whether a mouse is present and accessible to RM/Panels.

05 RMP--VALID-INPUT-SW PIC X SPACE.
   88 RMP--VALID-INPUT VALUE "Y".
   88 RMP--INVALID-INPUT VALUE "N".

This parameter is used by the RM/Panels runtime system to indicate to the application program whether user input to a field/control satisfied validation rules specified for that field/control in the panel. If the input satisfied the rules, the value is set to Y. If the input failed to satisfy the rules, the value is set to N.

05 RMP--STATUS PIC 9(4) VALUE 0.
   88 RMP--VALID-FUNCTION VALUE 0.
   88 RMP--FIELD-INVALID VALUE 1.
   .
   .
   .
   88 RMP--NO-ERROR-DEFINED VALUE 13.
   88 RMP--IO-ERROR VALUE 14.
   88 RMP--CONTROL-DISABLED VALUE 15.
   88 RMP--WINDOW-ERROR VALUE 16.
   88 RMP--NO-PULLDOWN VALUE 22.
   88 RMP--MENU-COMMAND-INVALID VALUE 20.
   88 RMP--MODELESS-DATA-OVERLOAD VALUE 21.
   88 RMP--NO-PULLDOWN VALUE 22.
   88 RMP--WRONG-FIELD-TYPE VALUE 23.
   88 RMP--TOO-MANY-PANELS VALUE 40.
   88 RMP--CANNOT-CREATE-TEMP VALUE 41.
   88 RMP--CANNOT-OPEN-TEMP VALUE 42.
   88 RMP--API-PARAM-MISSING VALUE 1001.
   88 RMP--API-MSG-NOT-DEFINED VALUE 1002.
   88 RMP--API-PD-OPTION-INVALID VALUE 1003.
   88 RMP--API-UNCHECKABLE VALUE 1004.

This parameter is used by the RM/Panels runtime system to report the outcome of the function request. If the function was performed successfully, a value of 0 is returned. If the function was unsuccessful, a non-zero value is returned indicating the reason. The condition-names are provided to make it easier for the application program to detect and interpret unsuccessful function requests.

03 RMP--FUNCTION-CODES.

These parameters contain the function codes used to identify standard, utility, and extended runtime functions to the RM/Panels runtime system. They should not be modified and the application program should never depend on the value or even the type of the data items. The calls to the RM/Panels runtime system use the data names. If direct calls are used in your application programs, they must always use the data-name and not the actual value.

03 RMP--SCROLL-BAR-WS.

These parameters contain values specific to scroll bars and their standard runtime functions.

05 RMP--SB-MINPIC 9(4).

This parameter is used to set a new minimum value for a scroll bar.

05 RMP--SB-MAXPIC 9(4).

This parameter is used to set a new maximum value for a scroll bar.

05 RMP--SB-STEPPIC 9(4).

This parameter is used to set a new step value for a scroll bar.

05 RMP--SB-PAGEPIC 9(4).

This parameter is used to set a new page value for a scroll bar.

05 RMP--SB-OPERATEDPIC X(30).

This parameter is used to report the name of a scroll bar when its thumb position is altered.

03 FILLERPIC X(50).

This area reserved for future use.

Parent topic: Appendix A: Master Copy File RMPANELS.WS
Related information
Contents of RMPANELS WS


Appendix B Standard Utility, and Extended Runtime Functions and Parameters

The following types of parameters are used with RM/Panels standard, utility, and extended runtime functions:

  • Required parameters
  • Optional parameters

Required parameters are those that must be set to valid values in order for a standard, utility, or extended runtime function to execute correctly.

Optional parameters are those that can be set to override the default behavior specified for the panel. Optional parameters are always reset to their default values by the RM/Panels runtime system after the function is executed. This prevents later executions of the standard runtime function from inheriting the overridden behavior.

Extended runtime functions also use additional arguments on the CALL statement.

The following table lists the required and optional parameters for RM/Panels standard runtime functions.

Standard Runtime Function Name | Abbr. | Required Parameters | Optional Parameters
ACCEPT FIELD | AF | RMP--FIELD-NAME RMP--FIELD-OCCUR | NONE
CHANGE PANEL PALETTE | CPP | RMP--PALETTE | NONE
CHECK MENU OPTION | CMO | RMP--COMMAND-NAME | NONE
CLEAR ALL FIELDS | CAF | NONE | NONE
DISABLE ALL FIELDS | DA | NONE | NONE
DISABLE FIELD FOR INPUT | DFI | RMP--FIELD-NAME | RMP--SUPPRESS- EVENT-RESET
DISABLE MENU OPTION | DMO | RMP--COMMAND-NAME | NONE
DISPLAY ALL FIELDS | DAF | NONE | NONE
DISPLAY FIELD | DF | RMP--FIELD-NAME RMP--FIELD-OCCUR | NONE
DISPLAY PANEL | DP | RMP--LIBRARY | RMP--BEEP RMP--CLEAR RMP--PALETTE RMP--PANEL-LINE RMP--PANEL-POS RMP--SHOW-FIELDS RMP--WINDOW
ENABLE ALL FIELDS | EA | NONE | NONE
ENABLE FIELD FOR INPUT | EFI | RMP--FIELD-NAME | RMP--SUPPRESS- EVENT-RESET
ENABLE MENU OPTION | EMO | RMP--COMMAND-NAME | NONE
EXECUTE EVENT | EE | RMP--FIRST-FIELD1 RMP--NEXT-FIELD1 RMP--NEXT-OCCUR1 RMP--REPEAT-EVENT1 You may select one of these parameters to execute the standard runtime function. | NONE
INITIALIZE ALL FIELDS | IAF | NONE | NONE
INITIALIZE FIELD | IF | RMP--FIELD-NAME RMP--FIELD-OCCUR | NONE
POPUP MENU | PUM | RMP--COMMAND-NAME | RMP--PANEL-LINE RMP--PANEL-POS
REMOVE PANEL | RP | NONE | RMP--CLEAR
SET FIELD ATTRIBUTE | SFA | RMP--ATTRIBUTE RMP--FIELD-NAME RMP--FIELD-OCCUR | NONE
SET SCROLL BAR RANGE | SSR | RMP--FIELD-NAME RMP--SB-MAX RMP--SB-MIN | RMP--SB-PAGE RMP--SB-STEP
SHOW FIELD ERROR | SFE | RMP--FIELD-NAME | NONE
SHOW FIELD HELP | SFH | RMP--FIELD-NAME | NONE
SHOW PANEL ERROR | SPE | NONE | NONE
SHOW PANEL HELP | SPH | NONE | NONE
UNCHECK MENU OPTION | UMO | RMP--COMMAND-NAME | NONE
VALIDATE ALL FIELDS | VAF | NONE | NONE
VALIDATE FIELD | VF | RMP--FIELD-NAME RMP--FIELD-OCCUR | NONE

The following table lists the required and optional parameters for RM/Panels utility functions.

Utility Function Name | Abbr. | Required Parameters | Optional Parameters
DELETE TEMPORARY FILE | DTF | NONE | NONE
END MODELESS OPERATION | EMD | NONE | NONE
END POLLING | EP | NONE | NONE
HIDE MOUSE CURSOR | HMC | NONE | NONE
SET COLOR | SCO | NONE | NONE
SET MONOCHROME | SMO | NONE | NONE
SHOW MOUSE CURSOR | SMC | NONE | NONE
START MODELESS OPERATION | SMD | NONE | NONE
START POLLING | SP | RMP--POLLING-INTERNAL | NONE

The following table lists the required parameters and additional arguments for RM/Panels extended runtime functions.

Extended Runtime Function Name | Abbr. | Required Parameters | Additional Arguments
ACTIVATE A LIBRARY | E-AL | NONE | libraryname
ACTIVATE A PANEL | E-AP | NONE | panelname
ADD FIELD DESCRIPTION | E-AFD | NONE | FIELD-DESCRIPTION
CHANGE FIELD DESCRIPTION | E-CFD | RMP--FIELD-NAME | FIELD-DESCRIPTION
CREATE A LIBRARY | E-CL | NONE | libraryname
CREATE A PANEL | E-CP | NONE | panelname
DELETE FIELD DESCRIPTION | E-DFD | RMP--FIELD-NAME | NONE
DISCARD CHANGES | E-DC | NONE | NONE
GET FIELD DESCRIPTION | E-GFD | RMP--FIELD-NAME | FIELD-DESCRIPTION
BY NAME |  |  |
GET FIELD DESCRIPTION BY NUMBER | E-GFN | RMP--FIELD-SEQ | FIELD-DESCRIPTION
GET FIELD VALUE | E-GFV | RMP--FIELD-NAME | FIELD-VALUE-DESC
GET LIBRARY CONFIGURATION | E-GLC | NONE | LIBRARY-CONFIG-DESC
GET MESSAGE | E-GMS | NONE | MSG-DESC
GET PALETTE DESCRIPTION | E-GPLT | RMP--PALETTE | PALETTE-DESC
GET PANEL CONFIGURATION | E-GPC | NONE | PANEL-CONFIG-DESC
GET PANEL LINE | E-GPL | NONE | PANEL-LINE-DESC
GET PULLDOWN MENU PULLDOWN OPTIONS | E-GPD | NONE | PULLDOWN-PD-DESC
GET PULLDOWN MENU TOP LEVEL OPTIONS | E-GPT | NONE | PULLDOWN-TITLE-AREA
HIDE PANEL | E-HDP | NONE | NONE
REMOVE MENU OPTION | E-RMO | RMP--COMMAND-NAME | NONE
SAVE A PANEL | E-SP | NONE | NONE
SET FIELD VALUE | E-SFV | RMP--FIELD-NAME | FIELD-VALUE-DESC
SET LIBRARY CONFIGURATION | E-SLC | NONE | LIBRARY-CONFIG-DESC
SET MESSAGE | E-SMS | NONE | MSG-DESC
SET PALETTE DESCRIPTION | E-SPLT | RMP--PALETTE | PALETTE-DESC
SET PANEL CONFIGURATION | E-SPC | NONE | PANEL-CONFIG-DESC
SET PANEL LINE | E-SPL | NONE | PANEL-LINE-DESC
SET PULLDOWN MENU PULLDOWN OPTIONS | E-SPD | NONE | PULLDOWN-PD-DESC
SET PULLDOWN MENU TOP LEVEL OPTIONS | E-SPT | NONE | PULLDOWN-TITLE-AREA
SHOW MESSAGE | E-SHM | NONE | MSG-DESC
UPDATE PANEL | E-UDP |  |
Parent topic: RM/Panels


Compatibility with XML Extensions

XML Extensions has many capabilities. The major features support the ability to import and export XML documents to and from COBOL working storage. Specifically, XML Extensions allows data to be imported from an XML document by converting data elements (as necessary) and storing the results into a matching COBOL data structure. Similarly, data is exported from a COBOL data structure by converting the COBOL data elements (as necessary) and storing the results in an XML document.

For more information about XML Extensions, refer to the XML Extensions User's Guide, available from the SupportLine section of the Micro Focus Web site.

For RM/COBOL users that utilize XML Extensions, here is a summary of compatibility issues that you need to be aware of when working in this COBOL system. Refer to this list and the RM/COBOL Conversion Issues list in the Compatibility with RM/COBOL section

Click a summary title for a fuller explanation and workaround, where possible.

  • Additional Parameter Required with XML Extensions Processing Statements
    In statements that use a Document Pointer parameter, you are also required to pass an additional Document Length parameter.
  • COBOL programs using BIS
    Programs in this COBOL system that are used with the Xcentrisity Business Information Server (BIS) must end with the GOBACK statement, not the STOP RUN statement. Also, messages for the BIS trace log must be generated by calling the B$Trace library program, not the DISPLAY statement.
  • Conflicts Between Model File-names and XML Data Files
    In this COBOL system, model file-names, as created by the compiler, are of the form program-name.xml. You should ensure your XML data files do not share the same name as this, to avoid any conflicts.
  • Creating an XML Model File
    To create an XML model file for use with XML Extensions, compile your application with the XMLGEN Compiler directive.
  • Displaying the Status of XML Extensions Statements
    In this COBOL system, use the XML-Status-Edited data item to display the status result of an XML Extensions statement execution.
  • Importing and Exporting Ambiguous Data-names
    When attempting to import or export an ambiguous model data-name, this COBOL system now displays a warning.
  • Invalid Characters in Condition Names
    In this COBOL system, if you use mark-up characters as values for condition names, this can produce invalid XML when exporting code using XML Extensions.
  • Restricted data items with XML Extensions
    In this COBOL system, you cannot use data items described in any section other than the File or Working Storage Sections, as model data names.
  • Unable to Use Data Items Declared in Nested Programs
    In this COBOL system, you cannot use data items declared in nested programs, as model data-names.
  • User-names Longer than 127 Bytes are Truncated
    In RM/COBOL, you can specify user-names (data-names, procedure-names, program-names, etc) up to 240 characters long. In this COBOL system, user-names longer than 127 bytes in length are truncated and a warning message is produced.
  • Using the Correct Calling Convention
    XML Extensions uses a different calling convention to the one used by the standard library routines implemented for RM/COBOL compatibility.
Parent topic: Compatibility with RM/COBOL


Additional Parameter Required with XML Extensions Processing Statements

In statements that use a Document Pointer parameter, you are also required to pass an additional Document Length parameter.

When using XML Extensions processing statements, each Document Pointer parameter must be immediately followed by a Document Length parameter. This applies to the following statements:

  • XML EXPORT TEXT
  • XML IMPORT TEXT
  • XML TEST WELLFORMED-TEXT
  • XML VALIDATE TEXT
  • XML GET TEXT
  • XML PUT TEXT
  • XML TRANSFORM TEXT
Note: XML FREE TEXT does not require that you use the Document Length parameter.

Solution:

Ensure that the Document Length parameter (MY-DOCUMENT-LENGTH) is specified immediately following the Document Pointer parameter (MY-DOCUMENT-POINTER) when calling an XML Extensions processing statement:

When the statement is outputting data, the statement will set MY-DOCUMENT-LENGTH:

XML EXPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.

When the statement is inputting data, you must set MY-DOCUMENT-LENGTH before the statement is processed:

XML IMPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH *> Item size MY-DOCUMENT-POINTER points to.
    "MY-MODEL-FILE".
IF NOT XML-OK GO TO Z.
Parent topic: Compatibility with XML Extensions


COBOL programs using BIS

Programs in this COBOL system that are used with the Xcentrisity Business Information Server (BIS) must end with the GOBACK statement, not the STOP RUN statement. Also, messages for the BIS trace log must be generated by calling the B$Trace library program, not the DISPLAY statement.

Programs that are used with the BIS must not use the STOP RUN statement, as this will terminate the MF run-time prematurely and the BIS will be unable to process any further web service requests.

In RM/COBOL, programs that are used with BIS capture the output of a DISPLAY statement and place it in the BIS trace log. In this COBOL system, to place messages in the BIS trace log, use the B$Trace library routine.

Solutions:

To ensure that programs used with the BIS do not prematurely terminate the MF run-time, use the GOBACK statement in those programs.

To place messages in the BIS trace log, call the B$Trace library program, using the same identifiers or literals, but not figurative constants, that you would use in a DISPLAY statement.
Note: Numeric data items can be of any data type and are converted to a numeric string by B$Trace.
call "B$Trace" using "Log message: " MyMessage " " MyStatus.
Parent topic: Compatibility with XML Extensions


Conflicts Between Model File-names and XML Data Files

In this COBOL system, model file-names, as created by the compiler, are of the form program-name.xml. You should ensure your XML data files do not share the same name as this, to avoid any conflicts.

In this COBOL system, if the ModelFileName#DataName parameter does not include a hash, it is always treated as a model data-name, and the model file-name is assumed to be program-name.xml for the program (or one of its callers) that executed an XML Extensions export or import statement. With this in mind, if you do not explicitly set a model file-name, you should ensure that your XML data files do not share the same name as your COBOL programs when performing import and export XML Extensions statements.

Solution:

To avoid conflicts between model file-names and XML data file-names, do one of the following:

  • Ensure you set the DocumentName parameter in your import and export statements to a name other than your COBOL program name.

  • If you want to keep your XML data file-names the same as the program-name, rename the model file-name after compilation and specify the new name in the value of the ModelFileDataName parameter before the hash, separating it from the ModelDataName.

When using the second technique, it is recommended that the compilation be done with a script that includes the renaming command, to avoid forgetting this step.

Notes:

In RM/COBOL, you can use the environment variable RM_MISSING_HASH to determine the meaning of the ModelFileDataName parameter when the hash is omitted. In this COBOL system, the environment variable is not supported.

Also, RM/COBOL v12 and later generally did not use model files because the model was embedded in the object program file; this COBOL system is more like RM/COBOL v11 and earlier, which always used model files. Thus, care must be taken to distribute model files with applications that use XML Extensions.

Parent topic: Compatibility with XML Extensions


Creating an XML Model File

To create an XML model file for use with XML Extensions, compile your application with the XMLGEN Compiler directive.

For complete information on using the XMLGEN compiler directive, see XMLGEN.

See Restricted data items with XML Extensions for a workaround to include data descriptions from other Data Division sections of your source code.

Parent topic: Compatibility with XML Extensions


Displaying the Status of XML Extensions Statements

In this COBOL system, use the XML-Status-Edited data item to display the status result of an XML Extensions statement execution.
In RM/COBOL, XML-Status, the data item used to display the status result of an XML Extensions statement execution, is defined as Display Usage. In this COBOL system, XML-Status is defined as:
03 XML-Status		PIC S9(4) COMP-5.
Therefore, an additional declaration is made in lixmldef.cpy, so that you can easily use the status result in your code:
03 XML-Status-Edited		PIC +9(4).
When an XML Extensions statement is executed, the value of XML-Status-Edited is not set, so you need move XML-Status to XML-Status-Edited before you can use the result.
Parent topic: Compatibility with XML Extensions


Importing and Exporting Ambiguous Data-names

In RM/COBOL, if you attempt to export an ambiguous data-item to a model file, an error is produced. If you attempt to import to an ambiguous data-item, the data is placed in the first occurrence of the named data-item.

In this COBOL system, if you attempt to export an ambiguous data-item to a model file, a warning message is produced and the first occurrence of the named data-item is exported. Similarly, If you attempt to import to an ambiguous data-item, a warning message is displayed and the data is placed in the first occurrence of the named data-item.

Example:

01 Group01.
    02 GroupA.
      03 NumItem	 PIC s9(5).
      03 StrItem	 PIC X(5).
        02 GroupB.
          03 NumItem  PIC s9(5).
          03 StrItem  PIC X(5).

--------------------------------
<StrItem> ABCDE </StrItem>   *> this produces a warning and updates StrItem in GroupA

<GroupB><StrItem> ABCDE </StrItem></GroupB>  *> this updates StrItem in GroupB
Parent topic: Compatibility with XML Extensions


Invalid Characters in Condition Names

In this COBOL system, if you use mark-up characters as values for condition names, this can produce invalid XML when exporting code using XML Extensions.

Mark-up characters, such as "<", ">" or "&" used in the values for condition names will produce invalid model files when using XML Extensions. The model files will cause parse errors when loaded by XML Extensions using the XML parser; XML Extensions will report the parse error and be unable to perform the requested export or import.

88 cond-name VALUE "<br/>".

Solution:

In this COBOL system, you must modify the COBOL source code, to eliminate mark-up characters in condition-name values.

Parent topic: Compatibility with XML Extensions


Restricted data items with XML Extensions

In this COBOL system, you cannot use data items described in any section other than the File or Working Storage Sections, as model data names.

To export data items from or import XML data into this COBOL system, use the XMLGEN Compiler directive to create a model file, for use with XML Extensions.

The model data names specified in the model file are determined by XMLGEN:
  • XMLGEN with no parameter specified produces model data names for data items/structures in the File Section only.
  • XMLGEN(ws) produces model data names for data items/structures in the Working Storage Section only.
Important: Data items/structures described in the Linkage Section, Communication Section, Local-Storage Section and Thread-Local-Storage Section cannot be used as model data names in a model file.

Solution:

Using a copybook containing your data items, compile a dummy program that copies the descriptions into the Working Storage section, and then use the XMLGEN(ws) Compiler directive to create a model file containing the required data items.

Notes:

The data items used at runtime when the model file is used can be in any section of the data division.

Parent topic: Compatibility with XML Extensions


Unable to Use Data Items Declared in Nested Programs

In this COBOL system, you cannot use data items declared in nested programs, as model data-names.

Solution:

Using a copybook containing your data items, compile a dummy program that copies the descriptions into the Working Storage section of your top-level program, and then use the XMLGEN(ws) Compiler directive to create a model file containing the required data items.

Parent topic: Compatibility with XML Extensions


Using the Correct Calling Convention

In this COBOL system, XML Extensions uses the standard COBOL calling convention. If your programs are also using the standard library routines implemented for RM/COBOL compatibility, you need to be aware that these are called using the 1024 calling convention.

Solution:

Generally, you should explicitly use the 1024 calling convention when calling your RM/COBOL standard library routines, but if you are using the DEFAULTCALLS Compiler directive to set this calling convention, you will need to override it when calling to XML Extensions.

Parent topic: Compatibility with XML Extensions


OO COBOL Class Library Reference

Help for the OO COBOL class libraries are available from the Micro Focus SupportLine Web site, as follows:

  1. Go to the Server Express documentation, at http://supportline.microfocus.com/documentation/books/sx51ws02/sx51indx.htm.
  2. Click Reference > OO COBOL.
  3. Expand OO COBOL Class Library Reference.
Parent topic: Compatibility


Data Access

  • Database Access
  • Data Files
  • Database Connectors for Visual COBOL
  • File Handling
Parent topic: Programming


Database Access

  • Accessing Databases from COBOL
    Describes the approaches we provide for accessing databases from COBOL.
  • Database Access Features
    This topic provides a brief overview of the main database access features.
  • Database Access Preprocessors
    Provides introductory information about each of the supported Database Access preprocessors.
  • Developing SQL Applications
    Information to assist you in developing SQL applications from scratch or maintaining SQL applications developed elsewhere.
  • Compiling SQL Applications
    Explains the process of compiling (building) and debugging SQL applications.
  • OpenESQL
    Explains the functionality available with the OpenESQL preprocessor and provides information for developing and deploying OpenESQL SQL applications.
  • DB2
    Explains the functionality associated with the DB2 External Compiler Module (ECM) preprocessor, and provides information for developing and deploying DB2 ECM SQL applications.
  • COBSQL
    Explains the functionality associated with the COBSQL preprocessor, and provides information for developing and deploying SQL applications for Oracle, Sybase, and Informix.
  • How to
    How to use the database access utilities and editors available to help you develop and deploy your SQL applications.
  • Reference
    Reference information for embedded statements, compiler directives, and other coding standards associated with database access.
Parent topic: Data Access
Related concepts
Additional Software Requirements for Visual COBOL Development Hub


Accessing Databases from COBOL

Describes the approaches we provide for accessing databases from COBOL.
We provide several approaches to accessing a database from a COBOL program that contains embedded SQL statements:
DBMS vendor pre-compiler technology
These pre-compilers take the COBOL source file as input, and then generates an output file that is compiled by the Micro Focus COBOL compiler. The pros and cons of this approach include:
  • A DBMS pre-compiler can offer better performance over Micro Focus ECM technology such as OpenESQL, but this is typically insignificant.
  • A DBMS pre-compiler enables the use of DBMS vendor extensions outside of the ANSI specification.
  • Compilation is a two-stage process: Pre-compilation followed by COBOL compilation.
  • Debugging is not integrated, meaning that you must debug pre-compiler output and not the original SQL embedded in the COBOL.
  • Pre-compilers do not currently support JVM managed code.
  • Pre-compilers do not support CHARSET(EBCDIC).
Micro Focus COBSQL technology
Micro Focus provides COBSQL technology that you can use with a DBMS pre-compiler to significantly improve integration between the pre-compiler and the COBOL compiler. For example, COBSQL enables you to debug the original SQL statements rather than source code generated by the pre-compiler. In addition, COBSQL supports CHARSET(EBCDIC).
Micro Focus External Compiler Module (ECM) technology for OpenESQL
OpenESQL provides ubiquitous database access. No DBMS vendor pre-compiler is required. The pros and cons of this approach include:
  • OpenESQL is database-agnostic, providing ODBC or JDBC connectivity within the confines of their corresponding APIs. This means that COBOL programs using OpenESQL can usually be switched to access a new database with minimal code change.
  • OpenESQL is currently the only technology that enables JDBC access by COBOL programs using embedded SQL.
  • OpenESQL performance could be slightly degraded over DMBS vendor pre-compilers, but this is typically insignificant.
  • By design, OpenESQL supports embedded SQL based on ANSI SQL standards.
  • OpenESQL might not support all of the extensions to the ANSI standard that some DBMS vendors provide.
Micro Focus External Compiler Module (ECM) technology for DB2 ECM
DB2 ECM provides database access to DB2 LUW and mainframe DB2, just like the IBM pre-compiler environment for COBOL. The DB2 ECM supports the following, providing advantages over DBMS vendor pre-compilers:
  • CHARSET (EBCDIC)
  • DSNTIAR and remapping SQLCODEs
  • COMP host variables
Parent topic: Database Access


Database Access Features

Runtimes
We supply several runtimes to communicate with your running SQL applications, including:
  • OpenESQL ODBC Runtime - communicates with native COBOL SQL applications that use any type of database.
  • OpenESQL JVM Managed Runtime - communicates with managed COBOL SQL applications that use any type of database
Preprocessors
Our database access preprocessors enable you to access relational databases by embedding SQL statements within your COBOL programs. The programming details differ with each preprocessor, resulting in many programming options. They also offer a wide range of features to assist you in the programming process.
  • OpenESQL for use with ODBC 3.0-compliant drivers and JDBC version 4 drivers
  • DB2 ECM for use with DB2 databases
  • COBSQL for use with COBOL preprocessors supplied by relational database vendors
    Note: You can also use a preprocessor supplied by your database vendor without COBSQL.
Stored Procedures
We support COBOL stored procedures for DB2 LUW and SQL Server 2008 or later.
Note: We do not provide details about SQL syntax, error messages returned or any use of SQL outside of the COBOL environment. For details of these, refer to the documentation supplied by your database vendor.
Parent topic: Database Access


Database Access Preprocessors

An ESQL preprocessor is essentially a conversion tool called by the COBOL compiler that processes embedded SQL, and can convert embedded SQL into code that is understood by your target database. Visual COBOL provides these database access preprocessors from which to choose, all designed to work closely with the Micro Focus COBOL Compiler.

OpenESQL Preprocessor

The OpenESQL preprocessor is the most flexible of the three available in Visual COBOL. Use it for basic SQL applications, applications designed to use multiple relational database systems, and for applications you might want to update to use a different relational database system in the future. In addition to processing embedded SQL statements, the OpenESQL preprocessor converts COBOL data types to their equivalent SQL data types.

OpenESQL provides these levels of database access:
  • ODBC for native applications
  • JDBC for managed JVM applications

DB2 External Compiler Module (ECM) Preprocessor

The DB2 ECM preprocessor converts embedded SQL statements into the appropriate calls to DB2 database services. Use this preprocessor for applications that access a DB2 relational database.

COBSQL Preprocessor

COBSQL is an integrated preprocessor designed to work with COBOL precompilers supplied by the Oracle, Sybase, and Informix relational database vendors. Use COBSQL if you are already using one of these precompilers with an earlier version of a Micro Focus COBOL product and want to migrate your application(s) to Visual COBOL. For any other type of embedded SQL application development, we recommend that you use OpenESQL.

This preprocessor replaces embedded SQL statements with the appropriate calls to database services, and adds code to bind COBOL host variables to the SQL variable names known to the database system.

When using the COBSQL precompiler with Visual COBOL, you can debug programs from the original source code rather than from the code produced by the precompiler.

Note: The COBSQL preprocessor is supported only for standard procedural COBOL programs. You cannot use COBSQL with Object Oriented COBOL syntax (OO programs) or with nested programs.
Parent topic: Database Access
Related concepts
OpenESQL
COBSQL
DB2


Developing SQL Applications

The following topics describe the programming features available for SQL applications in general. Specific information on programming for a particular preprocessor is contained in the topics covering the use of that preprocessor.

  • Embedded SQL
    Instructions on how to embed SQL statements into your programs.
  • Host Variables
    The purpose of host variables, how to declare them, and how to use them in your SQL applications.
  • Cursors
    The purpose of cursors, how to declare them, and how to use them in SQL applications.
  • Data Structures
    The purpose and use of the SQLCA and SQLDA data structures available for SQL applications.
  • Dynamic SQL
    An explanation of how dynamic SQL works, and a description of its purpose, advantages, and use.
Parent topic: Database Access


Embedded SQL

Each of the database access preprocessors works by taking the SQL statements that you have embedded in your COBOL program and converting them to the appropriate function calls to the database.

Keywords

In your COBOL program, each embedded SQL statement must be preceded by the introductory keywords:

EXEC SQL

and followed by the keyword:

END-EXEC

For example:

     EXEC SQL
         SELECT au_lname INTO :lastname FROM authors
          WHERE au_id = '124-59-3864'
     END-EXEC

The embedded SQL statement can be broken over as many lines as necessary following the normal COBOL rules for continuation, but between the EXEC SQL and END-EXEC keywords you can only code an embedded SQL statement; you cannot include any ordinary COBOL code.

The case of embedded SQL keywords in your programs is ignored. You can use all upper-case, all lower-case, or a combination of the two. For example, the following are all equivalent:

EXEC SQL CONNECT
exec sql connect
Exec Sql Connect

Cursor names, statement names, and connection names

The case of cursor names, statement names and connection names must match that used when the variable is declared. For example, if you declare a cursor as C1, you must always refer to it as C1 (and not as c1).

The settings for the particular database determine whether such things as connection names, table and column names, are case-sensitive.

SQL identifiers

Hyphens are not permitted in SQL identifiers such as table and column names.

SQL identifiers are typically restricted regarding which characters they support. Typically, unquoted identifiers can only contain A-Z, 0-9 and underscore. Some databases might also allow lower-case characters, and/or @ and # symbols. If your SQL identifiers contain any other characters, such as a grave accent, spaces, or DBCS characters, they must be delimited. Refer to your database vendor documentation for more information, including the character to use as the delimiter.

SQL statements

Most vendors provide SQL Reference documentation with their database software that includes full information about embedded SQL statements. Regardless of the database software, you should, for example, be able to perform the following typical operations using the statements shown:

Operation | SQL Statement(s)
Add data to a table | INSERT
Change data in a table | UPDATE
Retrieve a row of data from a table | SELECT
Create a named cursor | DECLARE CURSOR
Retrieve multiple rows of data using a cursor | OPEN, FETCH, CLOSE

A full syntax description is given for each of the supported embedded SQL statements, together with an example of its use, in the topics under Embedded SQL Statements.

Parent topic: Developing SQL Applications
Related reference
Embedded SQL Statements


Host Variables

Host variables are data items defined within a COBOL program. They are used to pass values to and receive values from a database. Host variables can be defined in the File Section, Working-Storage Section, Local-Storage Section or Linkage Section of your COBOL program and can be coded using any level number between 1 and 48.

A host variable can be input or output:
  • Input host variables - to specify data to be transferred from the COBOL program to the database
  • Output host variables - to hold data to be returned to the COBOL program from the database

To use host variables, you must declare them in your program and then reference them in your SQL statements.

A host variable can be defined as any of the following types:
  • Simple Host Variable - to store and retrieve a single string of data
  • Host Array - to store and retrieve multiple rows of data
  • Indicator Variable - a companion variable that store null value and data truncation information
  • Indicator Array - a companion array used to store null value and data truncation information for multiple rows

See the topics listed under Related concepts below for more information on features related to host variables.

  • Simple Host Variables
    Instructions for declaring and referencing simple host variables in your COBOL programs.
  • Host Arrays
    Instructions for declaring and referencing an array of host variables.
  • Indicator Variables
    A description of the types and uses of indicator variables in SQL applications.
  • Indicator Arrays
    A description of the types and uses of indicator arrays in SQL applications.
  • COBOL to SQL Data Type Mapping
    Describes how preprocessors map COBOL data types to SQL data types.
  • SQL TYPEs
    A description of SQL TYPE declarations and an example of using them with date, time, and timestamp fields.
Parent topic: Developing SQL Applications
Related concepts
JVM Host Variables in Managed Code


Simple Host Variables

Before you can use a host variable in an embedded SQL statement, you must declare it.

Declaring simple host variables

Generally, host variable declarations are coded as data items bracketed by the embedded SQL statements BEGIN DECLARE SECTION and END DECLARE SECTION. The following rules also apply:
  • You can use groups of data items as a single host variable. However, a group item cannot be used in a WHERE clause.
  • OpenESQL trims trailing spaces from character host variables. If the variable consists entirely of spaces, OpenESQL does not trim the first space character because some servers treat a zero length string as NULL.
  • For OpenESQL and DB2 ECM only, you can use COBOL data items as host variables even if they have not been declared using BEGIN DECLARE SECTION and END DECLARE SECTION.
  • Host variable names must conform to the COBOL rules for data items.
  • Host variables can be declared anywhere that it is legal to declare COBOL data items.
  • Underscores (_) are permitted in host variable names only when you compile using DIALECT"MF" (default setting) or DIALECT"ENTCOBOL".

Referencing simple host variables

You reference host variables from embedded SQL statements. When you code a host variable name into an embedded SQL statement, it must be preceded by a colon (:) to enable the compiler to distinguish between the host variable and tables or columns with the same name.

Example

 EXEC SQL
     BEGIN DECLARE SECTION
 END-EXEC
 01 id             pic x(4).
 01 name           pic x(30).
 01 book-title     pic x(40).
 01 book-id        pic x(5).
 EXEC SQL
    END DECLARE SECTION
 END-EXEC
    . . .
     display "Type your identification number: "
     accept id.

* The following statement retrieves the name of the
* employee whose ID is the same as the contents of
* the host variable "id". The name is returned in
* the host variable "name".

     EXEC SQL
         SELECT emp_name INTO :name FROM employees
          WHERE emp_id=:id
     END-EXEC
     display "Hello " name.

* In the following statement, :book-id is an input
* host variable that contains the ID of the book to
* search for, while :book-title is an output host
* variable that returns the result of the search.

     EXEC SQL
        SELECT title INTO :book-title FROM titles
           WHERE title_id=:book-id
     END-EXEC
Parent topic: Host Variables


Host Arrays

An array is a collection of data items associated with a single variable name. You can define an array of host variables (called host arrays) and operate on them with a single SQL statement.

You can use host arrays as input variables in INSERT, UPDATE and DELETE statements and as output variables in the INTO clause of SELECT and FETCH statements. This means that you can use arrays with SELECT, FETCH, DELETE, INSERT and UPDATE statements to manipulate large volumes of data.

Some of the benefits to using host arrays include:
  • You can perform multiple CALL, EXECUTE, INSERT or UPDATE operations by executing only one SQL statement, which can significantly improve performance, especially when the application and the database are on different systems.
  • You can fetch data in batches, which can be useful when creating a scrolling list of information.

As with simple host variables, you must declare host arrays in your program and then reference them in your SQL statements.

Declaring host arrays

Host arrays are declared in much the same way as simple host variables using BEGIN DECLARE SECTION and END DECLARE SECTION. With host arrays, however, you must use the OCCURS clause to dimension the array.

Referencing host arrays

The following rules apply to coding host arrays into embedded SQL statements:
  • Just as with simple host variables, you must precede a host array name with a colon (;).
  • If the number of rows available is more than the number of rows defined in an array, a SELECT statement returns the number of rows defined in the array, and an SQLCODE message is issued to indicate that the additional rows could not be returned.
  • Use a SELECT statement only when you know the maximum number of rows to be selected. When the number of rows to be returned is unknown, use the FETCH statement.
  • If you use multiple host arrays in a single SQL statement, their dimensions must be the same.
  • OpenESQL does not support the mixing of host arrays and simple host variables within a single SQL statement. They must be all simple or all arrays.
  • For OpenESQL, you must define all host variables within a host array with the same number of occurrences. If one variable has 25 occurrences, all variables in that host array must have 25 occurrences.
  • If you are using COBSQL with Oracle, you can code a simple host variable in the WHERE clause of a SELECT statement that references a host array. This is the only scenario that allows the mixing of simple host variables and host arrays.
  • Optionally, use the FOR clause to limit the number of array elements processed to just those that you want. This is especially useful in UPDATE, INSERT and DELETE statements where you may not want to use the entire array. The following rules apply:
    • If the value of the FOR clause variable is less than or equal to zero, no rows are processed.
    • The number of array elements processed is determined by comparing the dimension of the host array with the FOR clause variable. The lesser value is used.

Examples

The following example shows typical host array declarations and references.

 EXEC SQL
     BEGIN DECLARE SECTION
 END-EXEC
 01 AUTH-REC-TABLES
    05 Auth-id       OCCURS 25 TIMES PIC X(12).
    05 Auth-Lname    OCCURS 25 TIMES PIC X(40).
 EXEC SQL
    END DECLARE SECTION
 END-EXEC.
  . . .

     EXEC SQL
         CONNECT USERID 'user' IDENTIFIED BY 'pwd'
                 USING 'db_alias'
     END-EXEC
     EXEC SQL
         SELECT au-id, au-lname
          INTO :Auth-id, :Auth-Lname FROM authors
     END-EXEC
     display sqlerrd(3)

The following example demonstrates the use of the FOR clause, showing 10 rows (the value of :maxitems) modified by the UPDATE statement:

 EXEC SQL
     BEGIN DECLARE SECTION
 END-EXEC
 01 AUTH-REC-TABLES
    05 Auth-id       OCCURS 25 TIMES PIC X(12).
    05 Auth-Lname    OCCURS 25 TIMES PIC X(40).
 01 maxitems         PIC S9(4) COMP-5 VALUE 10.
 EXEC SQL
     END DECLARE SECTION
 END-EXEC.
   . . .
     EXEC SQL
         CONNECT USERID 'user' IDENTIFIED BY 'pwd'
                 USING 'db_alias'
     END-EXEC
     EXEC SQL
         FOR :maxitems
          UPDATE   authors
           SET   au_lname = :Auth_Lname
           WHERE au_id  = :Auth_id
     END-EXEC
     display sqlerrd(3)
Parent topic: Host Variables


Indicator Variables

Use indicator variables to:
  • Assign null values
  • Detect null values
  • Detect data truncation

Unlike COBOL, SQL supports variables that can contain null values. A null value means that no entry has been made and usually implies that the value is either unknown or undefined. A null value enables you to distinguish between a deliberate entry of zero (for numerical columns) or a blank (for character columns) and an unknown or inapplicable entry. For example, a null value in a price column does not mean that the item is being given away free, it means that the price is not known or has not been set.

Important: When a host variable is null, its indicator variable has the value -1; when a host variable is not null, the indicator variable has a value other than -1.

Indicator variables serve an additional purpose if truncation occurs when data is retrieved from a database into a host variable. If the host variable is not large enough to hold the data returned from the database, the warning flag sqlwarn1 in the SQLCA data structure is set and the indicator variable is set to the size of the data contained in the database.

Declaring indicator variables

Indicator variables are always defined as:

pic S9(4) comp-5.

Referencing indicator variables

Together, a host variable and its companion indicator variable specify a single SQL value. The following applies to coding a host variable with a companion indicator variable:
  • Both variables must be preceded by a colon (:).
  • Place an indicator variable immediately after its corresponding host variable.
  • Reference the host variable and indicator variable in a FETCH INTO or SELECT ...INTO statement with or without an INDICATOR clause as follows:
    :hostvar:indicvar

    or

    :hostvar INDICATOR :indicvar
  • You cannot use indicator variables in a search condition. To search for null values, use the is null construct instead.

Examples

This example demonstrates the declaration of an indiator variable that is used in a FETCH ...INTO statement.

 EXEC SQL
     BEGIN DECLARE SECTION
 END-EXEC
 01 host-var       pic x(4).
 01 indicator-var  pic S9(4) comp-5.
 EXEC SQL
    END DECLARE SECTION
 END-EXEC
    . . .

     EXEC SQL
         FETCH myCursor INTO :host-var:indicator-var
     END-EXEC

The following shows an embedded UPDATE statement that uses a saleprice host variable with a companion indicator variable, saleprice-null:

     EXEC SQL
        UPDATE closeoutsale
           SET temp_price = :saleprice:saleprice-null,
                listprice = :oldprice
     END-EXEC

In this example, if saleprice-null has a value of -1, when the UPDATE statement executes, the statement is read as:

     EXEC SQL
        UPDATE closeoutsale
           SET temp_price = null, listprice = :oldprice
     END-EXEC

This example demonstrates the use of the is null construct to do a search:

     if saleprice-null equal -1
         EXEC SQL
             DELETE FROM closeoutsale
                    WHERE temp_price is null
         END-EXEC
     else
         EXEC SQL
             DELETE FROM closeoutsale
                    WHERE temp_price = :saleprice
         END-EXEC
     end-if
Parent topic: Host Variables


Indicator Arrays

Just as an indicator variable is used as a companion to a host variable, use an indicator array as a companion to a host array to indicate the null status of each returned row or to store data truncation warning flags.

Note: COBSQL supports indicator arrays with Oracle databases only.

Example

In this example, an indicator array is set to -1 so that it can be used to insert null values into a column:
 01 ix                       PIC 99 COMP-5.
   . . .
 EXEC SQL
     BEGIN DECLARE SECTION
 END-EXEC
 01 sales-id       OCCURS 25 TIMES PIC X(12).
 01 sales-name     OCCURS 25 TIMES PIC X(40).
 01 sales-comm     OCCURS 25 TIMES PIC S9(9) COMP-5.
 01 ind-comm       OCCURS 25 TIMES PIC S9(4) COMP-5.
 EXEC SQL
     END DECLARE SECTION
 END-EXEC.
  . . .
     PERFORM VARYING iX FROM 1 BY 1 UNTIL ix > 25
         MOVE -1 TO ind-comm (ix)
     END-PERFORM.
      . . .
     EXEC SQL
         INSERT INTO SALES (ID, NAME, COMM)
           VALUES (:sales_id, :sales_name, :sales_comm:ind-comm)
     END-EXEC
Parent topic: Host Variables


COBOL to SQL Data Type Mapping

SQL has a standard set of data types, but the exact implementation of these varies between databases, and many databases do not implement the full set.

Within a program, COBOL host variable declarations can serve both as COBOL host variables and as SQL database variables. To make this possible, the preprocessor converts COBOL data types to their equivalent SQL data types. We sometimes refer to this conversion process as mapping COBOL data types to SQL data types. The preprocessor looks for specific COBOL picture clause formats that identify those that require mapping to SQL data types. For mapping to be successful, you must declare your COBOL host variables using these specific COBOL picture clauses.

We provide SQL data types for the OpenESQL and DB2 ECM preprocessors. For complete information on each SQL data type and its required COBOL host variable formats, see the SQL Data Types and SQL/COBOL Data Type Mappings Reference topics.

Note: For information on the appropriate host variable formats to use with the COBSQL preprocessor, see your DBMS documentation.
Parent topic: Host Variables
Related reference
SQL TYPEs
SQL Data Types
SQL/COBOL Data Type Mappings


SQL TYPEs

Manipulating SQL data that involves date, time, or binary data can be complicated using traditional COBOL host variables, and traditional techniques for handling variable-length character data can also be problematic. To make working with this data easier, we provide the SQL TYPE declaration to make it easier to specify host variables that more closely reflect the natural data types of relational data stores. This allows more applications to be built using static rather than dynamic SQL syntax, and also can help to optimize code execution.

Note: For a complete listing of available SQL TYPEs, see the SQL TYPEs reference topic.

Example: Defining date, time, and timestamp fields as SQL TYPEs

This example program shows date, time and timestamp escape sequences being used, and how to redefine them as SQL TYPEs. It applies to both OpenESQL and DB2 ECM:

 working-storage section.
 EXEC SQL INCLUDE SQLCA END-EXEC

 01  date-field1      pic x(29).
 01  date-field2      pic x(29).
 01  date-field3      pic x(29).

 procedure division.
     EXEC SQL
        CONNECT TO 'Net Express 4.0 Sample 1' USER 'admin'
     END-EXEC
* If the Table is there drop it.
     EXEC SQL
        DROP TABLE DT
     END-EXEC

* Create a table with columns for DATE, TIME, and DATE/TIME
* NOTE:  Access uses DATETIME column for all three.
*        Some databases will have dedicated column types.
* If you are creating DATE/TIME columns on another data
* source, refer to your database documentation to see how to
* define the columns.

     EXEC SQL
        CREATE TABLE DT ( id  INT,
                        myDate DATE NULL,
                        myTime TIME NULL,
                        myTimestamp TIMESTAMP NULL)
     END-EXEC

* INSERT into the table using the ODBC Escape sequences

     EXEC SQL
        INSERT into DT values (1 ,
            {d '1961-10-08'},  *> Set just the date part
            {t '12:21:54'  },  *> Set just the time part
            {ts '1966-01-24 08:21:56' } *> Set both parts
                              )
     END-EXEC

* Retrieve the values we just inserted

     EXEC SQL
        SELECT myDate
              ,myTime
              ,myTimestamp
         INTO  :date-field1
              ,:date-field2
              ,:date-field3
         FROM DT
         where id = 1
     END-EXEC

* Display the results.

     display 'where the date part has been set :'
             date-field1
     display 'where the time part has been set :'
             date-field2
     display 'NOTE, most data sources will set a default '
             'for the date part '
     display 'where both parts has been set :'
             date-field3

* Remove the table.

     EXEC SQL
        DROP TABLE DT
     END-EXEC

* Disconnect from the data source

     EXEC SQL
        DISCONNECT CURRENT
     END-EXEC

     stop run.

Alternatively you can use host variables defined with SQL TYPEs for date/time variables. Define the following host variables:

01  my-id          pic s9(08) COMP-5.
01  my-date        sql type is date.
01  my-time        sql type is time.
01  my-timestamp   sql type is timestamp.

and replace the INSERT statement with the following code:

*> INSERT into the table using SQL TYPE HOST VARS
    move 1                           to  MY-ID
    move "1961-10-08"                to  MY-DATE
    move "12:21:54"                  to  MY-TIME
    move "1966-01-24 08:21:56"       to  MY-TIMESTAMP

     EXEC SQL
        INSERT into DT value (
          :MY-ID
         ,:MY-DATE
         ,:MY-TIME
         ,:MY-TIMESTAMP  )
     END-EXEC
Parent topic: Host Variables
Related reference
SQL TYPEs


Cursors

When you write code in which the results set returned by a SELECT statement includes more than one row of data, you must declare and use a cursor. A cursor indicates the current position in a results set, in the same way that the cursor on a screen indicates the current position.

A cursor enables you to:

  • Fetch rows of data one at a time
  • Perform updates and deletions at a specified position within a results set.

The example below demonstrates the following sequence of events:

  1. The DECLARE CURSOR statement associates the SELECT statement with the cursor Cursor1.
  2. The OPEN statement opens the cursor, thereby executing the SELECT statement.
  3. The FETCH statement retrieves the data for the current row from the columns au_fname and au_lname and places the data in the host variables first_name and last_name.
  4. The program loops on the FETCH statement until no more data is available.
  5. The CLOSE statement closes the cursor.
 EXEC SQL DECLARE Cursor1 CURSOR FOR
     SELECT au_fname, au_lname FROM authors
 END-EXEC
  . . .
     EXEC SQL
         OPEN Cursor1
     END-EXEC
       . . .
     perform until sqlcode not = zero
         EXEC SQL
             FETCH Cursor1 INTO :first_name,:last_name
         END-EXEC
         display first_name, last_name
     end-perform
      . . .
     EXEC SQL
         CLOSE Cursor1
     END-EXEC
  • Declaring a Cursor
  • Opening a Cursor
  • Using a Cursor to Retrieve Data
  • Closing a Cursor
  • Positioned UPDATE and DELETE Statements
  • Using Cursors
Parent topic: Developing SQL Applications
Related concepts
Dynamic SQL Statements and Cursors
Related reference
FETCH
OPEN
QUERY ODBC
SELECT INTO
UPDATE (Positioned)


Declaring a Cursor

Before a cursor can be used, it must be declared. This is done using the DECLARE CURSOR statement in which you specify a name for the cursor and either a SELECT statement or the name of a prepared SQL statement.

Cursor names must conform to the rules for identifiers on the database that you are connecting to, for example, some databases do not allow hyphens in cursor names.

 EXEC SQL
     DECLARE Cur1 CURSOR FOR
      SELECT first_name FROM employee
       WHERE last_name = :last-name
 END-EXEC

This example specifies a SELECT statement using an input host variable (:last-name). When the cursor OPEN statement is executed, the values of the input host variable are read and the SELECT statement is executed.

 EXEC SQL
     DECLARE Cur2 CURSOR FOR stmt1
 END-EXEC
      . . .
     move "SELECT first_name FROM emp " &
          "WHERE last_name=?" to prep.
     EXEC SQL
        PREPARE stmt1 FROM :prep
     END-EXEC
      . . .
     EXEC SQL
        OPEN Cur2 USING :last-name
     END-EXEC

In this example, the DECLARE CURSOR statement references a prepared statement (stmt1). A prepared SELECT statement can contain question marks (?) which act as parameter markers to indicate that data is to be supplied when the cursor is opened. The cursor must be declared before the statement is prepared.

Within an Object Oriented (OO) program, you can declare a cursor anywhere that it is valid to declare a data item. Cursors are local to the object that they are opened in, that is, two instances of an object opening the "same" cursor each get their own cursor instance. You can open a cursor in one method, fetch it in a second and close it in a third but it must be declared in the Object-Storage Section if you want to do this.

COBSQL

A cursor can be declared in either the Data Division or the Procedure Division of your program. The DECLARE CURSOR statement does not generate any code but if a cursor is declared within the Procedure Division, COBSQL generates a debug breakpoint for the DECLARE CURSOR statement.

Note:
  • Object oriented COBOL syntax is not supported by COBSQL.
  • Some versions of the Informix precompiler can generate incorrect code if a cursor is declared within the Working-Storage Section. We therefore recommend that you only declare cursors in the Procedure Division when using INFORMIX.
Parent topic: Cursors


Opening a Cursor

Once a cursor has been declared, it must be opened before it can be used. This is done using the OPEN statement, for example:

     EXEC SQL
         OPEN Cur1
     END-EXEC

If the DECLARE CURSOR statement references a prepared statement that contains parameter markers, the corresponding OPEN statement must specify the host variables or the name of an SQLDA structure that will supply the values for the parameter markers, for example:

     EXEC SQL
         OPEN Cur2 USING :last-name
     END-EXEC

If an SQLDA data structure is used, the data type, length, and address fields must already contain valid data when the OPEN statement is executed.

COBSQL

  • When a cursor is opened, no locks are applied to the tables the data is being selected from.
  • An Oracle database allows a cursor to be re-opened before it is closed such that the SELECT statement is re-evaluated. If the program has been compiled in ANSI mode, however, re-opening the cursor before it has been closed generates an error. For more information on the MODE precompiler directive, refer to the Programmer's Guide to the ORACLE Precompilers.
Parent topic: Cursors


Using a Cursor to Retrieve Data

Once a cursor has been opened, it can be used to retrieve data from the database. This is done using the FETCH statement. The FETCH statement retrieves the next row from the results set produced by the OPEN statement and writes the data returned to the specified host variables (or to addresses specified in an SQLDA structure). For example:

     perform until sqlcode not = 0
         EXEC SQL
            FETCH Cur1 INTO :first_name
         END-EXEC
         display 'First name: ' fname
         display 'Last name : ' lname
         display spaces
     end-perform

When the cursor reaches the end of the results set, a value of 100 is returned in SQLCODE in the SQLCA data structure and SQLSTATE is set to "02000".

As data is fetched from a cursor, locks can be placed on the tables from which the data is being selected.

COBSQL

The ORACLE precompiler directive, MODE, affects the value put into SQLCODE when no data is found. For more information on the use of the MODE precompiler directive, refer to the Programmer's Guide to the ORACLE Precompilers.

Parent topic: Cursors


Closing a Cursor

When your application has finished using the cursor, it should be closed using the CLOSE statement. For example:

     EXEC SQL
         CLOSE Cur1
     END-EXEC

Normally, when a cursor is closed, all locks on data and tables are released. If the cursor is closed within a transaction, however, the locks may not be released.

COBSQL

  • The ORACLE precompiler directive, MODE, affects what happens to a cursor when either the commit or rollback command is used. For more information on the use of the precompiler directive MODE, refer to the Programmer's Guide to the ORACLE Precompilers.
  • When a cursor is closed, the ORACLE client may deallocate the memory and resources associated with the cursor. The following precompiler options control the deallocation of cursors: HOLD_CURSOR, MAXOPENCURSORS and RELEASE_CURSOR. For more information on the use of the precompiler directives, refer to the Programmer's Guide to the ORACLE Precompilers.
Parent topic: Cursors


Positioned UPDATE and DELETE Statements

Positioned UPDATE and DELETE statements are used in conjunction with cursors and include WHERE CURRENT OF clauses instead of search condition clauses. The WHERE CURRENT OF clause specifies the corresponding cursor.

     EXEC SQL
         UPDATE emp SET last_name = :last-name
          WHERE CURRENT OF Cur1
     END-EXEC

This will update last_name in the row that was last fetched from the database using cursor Cur1.

     EXEC SQL
         DELETE emp WHERE CURRENT OF Cur1
     END-EXEC

This example will delete the row that was last fetched from the database using cursor Cur1.

OpenESQL

With some ODBC drivers, cursors that will be used for positioned updates and deletes must include a FOR UPDATE clause. Note that positioned UPDATE and DELETE are part of the Extended ODBC Syntax and are not supported by all drivers.

COBSQL

With COBSQL, cursors that will be used for positioned updates and deletes must include a FOR UPDATE clause.

Parent topic: Cursors


Using Cursors

Cursors are very useful for handling large amounts of data but there are a number of issues which you should bear in mind when using cursors, namely: data concurrency, integrity and consistency.

To ensure the integrity of your data, a database server can implement different locking methods. Some types of data access do not acquire any locks, some acquire a shared lock and some an exclusive lock. A shared lock allows other processes to access the data but not update it. An exclusive lock does not allow any other process to access the data.

When using cursors there are three levels of isolation and these control the data that a cursor can read and lock:

  • Level zero

    Level zero can only be used by read-only cursors. At level zero, the cursor will not lock any rows but may be able to read data that has not yet been committed. Reading uncommitted data is dangerous (as a rollback operation will reset the data to its previous state) and is normally called a "dirty read". Not all databases will allow dirty reads.

  • Level one

    Level one can be used by read-only cursors or updateable cursors. With level one, shared locks are placed on the data unless the FOR UPDATE clause is used. If the FOR UPDATE clause is used, exclusive locks are placed on the data. When the cursor is closed, the locks are released. A standard cursor, that is a cursor without the FOR UPDATE clause, will normally be at isolation level one and use shared locks.

  • Level three

    Level three cursors are used with transactions. Instead of the locks being released when the cursor is closed, the locks are released when the transaction ends. With level three it is usual to place exclusive locks on the data.

It is worth pointing out that there can be problems with deadlocks or "deadly embraces" where two processes are competing for the same data. The classic example is where one process locks data A and then requests a lock on data B while a second process locks data B and then requests a lock on data A. Both processes have data that the other process requires. The database server should spot this case and send errors to one, or both, processes.

COBSQL

Oracle, Sybase and Informix allow an application to set the isolation level of the cursor and their documentation discusses the types of locks that are applied and how they work. Their documentation also discusses the physical level that the data is locked at. This can be a single row, a set of rows (that is, the page level), or the whole table. Care should be taken when using cursors that scan multiple tables, or tables that are used by most processes, as this will reduce the accessibility of the locked data.

Note:

COBSQL

Oracle, Sybase and Informix allow cursors to be defined with a number of different clauses, for example FOR READ ONLY, FOR UPDATE etc. These clauses effect the isolation level of the cursor and how it will act when involved in transaction processing. For more information on the effect of these difference clauses, refer to the SQL reference book supplied with your database.

Parent topic: Cursors


Data Structures

The SQL preprocessors supplied with this system use two data structures:

Data Structure | Description | Function
SQLCA | SQL Communications Area | Returns status and error information.
SQLDA | SQL Descriptor Area | Describes the variables used in dynamic SQL statements.
  • SQL Communications Area (SQLCA)
  • The SQL Descriptor Area (SQLDA)
Parent topic: Developing SQL Applications
Related reference
DESCRIBE
EXECUTE IMMEDIATE
FETCH
INCLUDE
OPEN
PREPARE
SELECT INTO


SQL Communications Area (SQLCA)

After each embedded SQL statement is executed, error and status information is returned in the SQL Communications Area (SQLCA).

For details of the layout of the SQLCA data structure, see the topic The SQLCA Data Structure.

Note: The Oracle, Sybase, and Informix versions of the SQLCA all use SQLCODE, SQLERRML, SQLERRMC, and SQLWARN. The sizes and the positions of these fields can differ among the precompilers.
OpenESQL
The SQLCA provided with Visual COBOL for use with OpenESQL contains two variables (SQLCODE and SQLSTATE) plus a number of warning flags which are used to indicate whether an error has occurred in the most recently executed SQL statement.
COBSQL
See your database vendor documentation for details on testing the success or failure of a given SQL statement.
  • Using the SQLCA
  • The SQLCODE Variable
  • The SQLSTATE Variable
  • SQLWARN Flags
  • The WHENEVER Statement
  • SQLERRM
  • SQLERRD
Parent topic: Data Structures
Related concepts
Error Codes
Related reference
The SQLCA Data Structure


Using the SQLCA

The SQLCA structure is supplied in the file sqlca.cpy, which by default is located in $COBDIR/cpylib. To include it in your program, use the following statement in the data division:

     EXEC SQL INCLUDE SQLCA END-EXEC

If you do not include this statement, the COBOL Compiler automatically allocates an area, but it is not addressable from within your program. However, if you declare either of the data items SQLCODE or SQLSTATE separately, the COBOL Compiler generates code to copy the corresponding fields in the SQLCA to the user-defined fields after each EXEC SQL statement.

If you declare the data item MFSQLMESSAGETEXT, it is updated with a description of the exception condition whenever SQLCODE is non-zero. MFSQLMESSAGETEXT must be declared as a character data item, PIC X(n), where n can be any legal value. This is particularly useful as ODBC error messages often exceed the 70-byte SQLCA message field.

Note: You do not need to declare SQLCA, SQLCODE, SQLSTATE or MFSQLMESSAGETEXT as host variables.
Parent topic: SQL Communications Area (SQLCA)


The SQLCODE Variable

Testing the value of SQLCODE is the most common way of determining the success or failure of an embedded SQL statement.

For details of SQLCODE values, see the topic SQLCODE Values.

DB2 LUW

For DB2, it is possible to get other positive values. This means that the SQL statement has executed but produced a warning.

COBSQL

For COBSQL, it is possible to get other positive values. This means that the SQL statement has executed but produced a warning.

  • For details about the range of positive values that SQLCODE can be set to, consult your Oracle, Sybase or Informix Error Messages manual. The above SQLCODES are produced by OpenESQL. The values for SQLCODE and the errors reported by Oracle, Sybase and Informix are all different. Please refer to Oracle, Sybase or Informix Error Messages manuals for more information on the errors returned.
  • The value +100 is the ANSI standard for 'data not found'. Oracle can return another value for 'data not found'. To get Oracle to return the value +100 for 'data not found', either of the Oracle precompiler directives MODE=ANSI or END_OF_FETCH=100 must be set. This will affect other aspects of the way the Oracle precompiler handles SQL statements. For more details on the Oracle precompiler MODE or END_OF_FETCH=+100 directives, refer to the Programmer's Guide to the ORACLE Precompilers.
  • Even when SQLCODE contains zero, a warning may have been generated. The values of the sqlwarn flags should be checked to determine the type of warning. For Oracle, Sybase and Informix, sqlwarn0 will always be set when the database server has sent a warning back to the application.
Parent topic: SQL Communications Area (SQLCA)
Related reference
GEN-SQLCA
SQLCODE Values


The SQLSTATE Variable

The SQLSTATE variable was introduced in the SQL-92 standard and is the recommended mechanism for future applications. It is divided into two components:

  • The first two characters are called the class code. Any class code that begins with the letters A through H or the digits 0 through 4 indicates a SQLSTATE value that is defined by the SQL standard or another standard.
  • The last three characters are called the subclass code.

A value of "00000" indicates that the previous embedded SQL statement executed successfully.

For specific details of the values returned in SQLSTATE when using Oracle, Sybase, or Informix, see the relevant database vendor documentation.

DB2 LUW
DB2 returns SQL-92 compliant SQLSTATE values.
Parent topic: SQL Communications Area (SQLCA)
Related reference
GEN-SQLCA
SQLCODE Values
SQLSTATE Values


SQLWARN Flags

Some statements may cause warnings to be generated. To determine the type of warning, your application should examine the contents of the SQLWARN flags.

  • W - The flag has generated a warning.
  • blank (space) - The flag has not generated a warning.

The value of a flag is set to W if that particular warning occurred, otherwise the value is a blank (space).

Each SQLWARN flag has a specific meaning. For more information on the meaning of the SQLWARN flags, see the topic The SQLCA Data Structure.

Parent topic: SQL Communications Area (SQLCA)
Related reference
SQLCODE Values
The SQLCA Data Structure


The WHENEVER Statement

Explicitly checking the value of SQLCODE or SQLSTATE after each embedded SQL statement can involve writing a lot of code. As an alternative, check the status of the SQL statement by using a WHENEVER statement in your application.

The WHENEVER statement is not an executable statement. It is a directive to the Compiler to automatically generate code that handles errors after each executable embedded SQL statement.

The WHENEVER statement allows one of three default actions (CONTINUE, GOTO or PERFORM) to be registered for each of the following conditions:

Condition | Value of SQLCODE
NOT FOUND | 100
SQLWARNING | +1
SQLERROR | < 0 (negative)

A WHENEVER statement for a particular condition replaces all previous WHENEVER statements for that condition.

The scope of a WHENEVER statement is related to its physical position in the source program, not its logical position in the run sequence. For example, in the following code if the first SELECT statement does not return anything, paragraph A is performed, not paragraph C:

     EXEC SQL
         WHENEVER NOT FOUND PERFORM A
     END-EXEC.
     perform B.
     EXEC SQL
        SELECT col1 into :host-var1 FROM table1
         WHERE col2 = :host-var2
     END-EXEC.
 A.
     display "First item not found".
 B.
     EXEC SQL
         WHENEVER NOT FOUND PERFORM C.
     END-EXEC.
 C.
     display "Second item not found".

COBSQL

For Oracle, Sybase and Informix, setting SQLWARN0 to "W" triggers the SQLWARNING clause.

Oracle

When no data is returned from a SELECT or FETCH statement, the condition NOT FOUND is triggered, regardless of the setting of the Oracle precompiler directive MODE.

Informix

Informix allows you to perform a STOP or a CALL from within a WHENEVER statement. These are additions to the ANSI standard and are documented in the Informix ESQL/COBOL programmers manual.

Parent topic: SQL Communications Area (SQLCA)


SQLERRM

The SQLERRM data area is used to pass error messages to the application from the database server. The SQLERRM data area is split into two parts:

  • SQLERRML - holds the length of the error message
  • SQLERRMC - holds the error text.

Within an error routine, the following code can be used to display the SQL error message:

     if (SQLERRML > ZERO) and (SQLERRML < 80)
         display 'Error Message: ', SQLERRMC(1:SQLERRML)
     else
         display 'Error Message: ', SQLERRMC
     end-if.
Parent topic: SQL Communications Area (SQLCA)


SQLERRD

The SQLERRD data area is an array of six integer status values.

  • COBSQL
  • DB2 LUW
Parent topic: SQL Communications Area (SQLCA)


COBSQL

Oracle, Sybase and Informix may set one (or more) of the six values within the SQLERRD array. These indicate how many rows were affected by the SQL statement just executed. For example, SQLERRD(3) holds the total number of rows returned by a SELECT or a series of FETCH statements.

Parent topic: SQLERRD


DB2 LUW

The third element of SQLERRD in the SQLCA, SQLERRD(3), records the number of rows processed for INSERT, UPDATE, DELETE and SELECT INTO statements. For FETCH statements, it records the cumulative sum of rows processed.

SQLERRD(3)

For DB2, SQLERRD(3) contains the following:

  • If PREPARE is invoked and successful, an estimate of the number of rows that will be returned.
  • After INSERT, UPDATE and DELETE, the actual number of rows affected.
  • If compound SQL is invoked, a count of the number of successful substatements.
  • If CONNECT is invoked, either 1 if the database can be updated or 2 if the database is read-only.
  • If an error occurs when processing a host array, the last row that was processed successfully.

SQLERRD(4)

For DB2, SQLERRD(4) contains the following:

  • If PREPARE is invoked and successful, a relative cost estimate of the resources required to process the statement.
  • If compound SQL is invoked, a count of the number of successful substatements.
  • If CONNECT is invoked, 0 for a one-phase commit from a down-level client; 1 for a one-phase commit; 2 for a one-phase, read-only commit; 3 for a two-phase commit.

SQLERRD(5)

For DB2, SQLERRD(5) contains the following:

  • The total number of rows deleted, inserted, or updated as a result of both:
    • The enforcement of constraints after a successful delete operation.
    • The processing of triggered SQL statements from activated triggers.
  • If compound SQL is invoked, an accumulation of the number of such rows for all substatements. In some cases, when an error is encountered, this field contains a negative value that is an internal error pointer.
  • If CONNECT is invoked, an authentication type value of 0 for a server authentication; 1 for client authentication; 2 for authentication using DB2 Connect; 3 for DCE security services authentication; 255 for unspecified authentication.
Parent topic: SQLERRD


The SQL Descriptor Area (SQLDA)

The SQLDA is unique to each precompiler. For example, the Oracle SQLDA is not compatible with that used by DB2 or OpenESQL.

When either the number of parameters to be passed, or their data types, are unknown at compilation time, you can use an SQL Descriptor Area (SQLDA) instead of host variables.

An SQLDA contains descriptive information about each input parameter or output column. It contains the column name, data type, length, and a pointer to the actual data buffer for each input or output parameter. An SQLDA is ordinarily used with parameter markers to specify input values for prepared SQL statements but you can also use an SQLDA with the DESCRIBE statement (or the INTO option of a PREPARE statement) to receive data from a prepared SELECT statement.

Although you cannot use an SQLDA with static SQL statements, you can use a SQLDA with a cursor FETCH statement.

  • COBSQL
  • OpenESQL
  • Using the SQLDA
Parent topic: Data Structures
Related reference
The SQLDA Data Structure


COBSQL

The SQLDA is only required if your program uses dynamic SQL. Oracle provides an extra copybook, ORACA, for use with dynamic SQL. To use this copybook:

  1. Include the following EXEC SQL statement in your program:
    EXEC SQL
   INCLUDE ORACA
END-EXEC
  2. When compiling, set the Oracle precompiler option, ORACA=YES.

    For more information on setting Oracle precompiler options, refer to the Programmer's Guide to the Oracle Precompilers.

  • Oracle does not supply an SQLDA. For a clearer explanation of this and the ORACA copybook, refer to the Programmer's Guide to the Oracle Precompilers.
  • COBSQL does not support inclusion of the SQLDA using the following syntax statement:
    EXEC SQL
   INCLUDE SQLDA
END-EXEC
  • Oracle
  • Sybase
  • Informix
Parent topic: The SQL Descriptor Area (SQLDA)


Oracle

Oracle provides an extra copybook, ORACA, for use with dynamic SQL. This can be included in your program using the following syntax:

EXEC SQL
   INCLUDE ORACA
END-EXEC

You must set the Oracle precompiler option, ORACA=YES before you can use the ORACA copybook. For more information on setting Oracle precompiler options, refer to the Programmer's Guide to the Oracle Precompilers.

Oracle does not supply an SQLDA. For a clearer explanation of this and the ORACA copybook, refer to the Programmer's Guide to the Oracle Precompilers.

Parent topic: COBSQL


Sybase

Sybase does not supply an SQLDA copybook. The Sybase precompiler documentation describes the layout of the SQLDA and how to assign values to the various items within it. The documentation also describes how to get Sybase to convert between COBOL and Sybase data types.

Parent topic: COBSQL


Informix

Informix does not supply an SQLDA copybook. The Informix precompiler documentation describes the layout of the data items that need to be defined to be able to use Dynamic SQL with Informix.

Parent topic: COBSQL


OpenESQL

The SQLDA structure is supplied in both the sqlda.cpy (SQLDA only) and sqlda78.cpy (SQLDA plus SQLTYPE definitions) files, which by default are located in the $COBDIR/cpylib directory.

You can include the SQLDA in your COBOL program by adding one or both of the following statements to your data division:

EXEC SQL
   INCLUDE SQLDA
END-EXEC

EXEC SQL
   INCLUDE SQLDA78
END-EXEC
Parent topic: The SQL Descriptor Area (SQLDA)


Using the SQLDA

Before an SQLDA structure is used, your application must initialise the following fields:

SQLN This must be set to the maximum number of SQLVAR entries that the structure can hold.
SQLDABC

The maximum size of the SQLDA.

  • 32-bit - Calculated as sqln * 44 + 16.
  • 64-bit - Calculated as sqln * 56 + 16.
.
  • The PREPARE and DESCRIBE Statements
  • The FETCH Statement
  • The OPEN or EXECUTE Statements
  • The DESCRIBE Statement
Parent topic: The SQL Descriptor Area (SQLDA)


The PREPARE and DESCRIBE Statements

You can use the DESCRIBE statement (or the PREPARE statement with the INTO option) to enter the column name, data type, and other data into the appropriate fields of the SQLDA structure.

Before the statement is executed, the SQLN and SQLDABC fields should be initialised as described above.

After the statement has been executed, the SQLD field will contain the number of parameters in the prepared statement. A SQLVAR record is set up for each of the parameters with the SQLTYPE and SQLLEN fields completed.

If you do not know how big the value of SQLN should be, you can issue a DESCRIBE statement with SQLN set to 1 and SQLD set to 0. No column detail information is moved into the SQLDA structure, but the number of columns in the results set is inserted into SQLD.

Parent topic: Using the SQLDA


The FETCH Statement

Before performing a FETCH statement using an SQLDA structure, follow the procedure below:

  1. The application must initialize SQLN and SQLDABC as described above.
  2. The application must then insert, into the SQLDATA field, the address of each program variable that will receive the data from the corresponding column. (The SQLDATA field is part of SQLVAR).
  3. If indicator variables are used, SQLIND must also be set to the corresponding address of the indicator variable.

The data type field (SQLTYPE) and length (SQLLEN) are filled with information from a PREPARE INTO or a DESCRIBE statement. These values can be overwritten by the application prior to a FETCH statement.

Parent topic: Using the SQLDA


The OPEN or EXECUTE Statements

To use an SQLDA structure to specify input data to an OPEN or EXECUTE statement, your application must supply the data for the fields of the entire SQLDA structure, including the SQLN, SQLD, SQLDABC, and SQLTYPE, SQLLEN, and SQLDATA fields for each variable. The following scenarios require additional attention:

SQLTYPE field is an odd number
If the value of the SQLTYPE field is an odd number, you must also supply the address of the indicator variable using SQLIND.
Host variable input is COMP
When using OpenESQL with a host variable input defined as COMP, add 8192 (x2000) to the SQLTYPE field.
SQLTYPE field is an odd number and indicator variable is COMP
If the SQLTYPE field is an odd number, and the indicator variable is defined as a COMP, add 4096 (x1000) to the SQLTYPE field.
Host variable input is COMP-5
When using OpenESQL with a host variable input defined as COMP-5, no change to the SQLTYPE field is required.

For a list of all SQLTYPE values supported by OpenESQL, see The SQLDA Data Structure.

Parent topic: Using the SQLDA
Related reference
The SQLDA Data Structure


The DESCRIBE Statement

-

After a PREPARE statement, you can execute a DESCRIBE statement to retrieve information about the data type, length and column name of each column returned by the specified prepared statement. This information is returned in the SQL Descriptor Area (SQLDA):

EXEC SQL
   DESCRIBE stmt1 INTO :sqlda
END-EXEC

If you want to execute a DESCRIBE statement immediately after a PREPARE statement, you can use the INTO option on the PREPARE statement to perform both steps at once:

EXEC SQL
   PREPARE stmt1 INTO :sqlda FROM :stmtbuf
END-EXEC

The following cases could require that you make manual changes to the SQLTYPE or SQLLEN fields in the SQLDA to accommodate differences in host variable types and lengths after executing DESCRIBE:

SQLTYPE: Variable-length character types
For variable-length character types you can choose to define SQLTYPE as a fixed-size COBOL host variable such as PIC X, N, or G, or a variable-length host variable such as a record with level 49 sub-fields for both length and the actual value. The SQLLEN field could be either 16 or 32 bits depending on the SQLTYPE value.
SQLTYPE: Numeric types
For numeric types you can choose to define SQLTYPE as COMP-3, COMP, COMP-5, or to display numeric COBOL host variables with an included or separate, and leading or trailing sign. The value returned by DESCRIBE depends on the data source. Generally this is COMP-3 for NUMERIC or DECIMAL columns, and COMP-5 for columns of the tinyint, smallint, integer, or bigint integer types.
SQLLEN
DESCRIBE sets SQLLEN to the size of integer columns in COMP and COMP-5 representations, meaning a value of 1, 2, 4, or 18. You might need to adjust this depending on SQLTYPE. For NUMERIC and DECIMAL columns, it encodes the precision and scale of the result.
Parent topic: Using the SQLDA
Related reference
DESCRIBE


Dynamic SQL

If everything is known about an SQL statement when the application is compiled, the statement is known as a static SQL statement.

In some cases, however, the full text of an SQL statement may not be known when an application is written. For example, you may need to allow the end-user of the application to enter an SQL statement. In this case, the statement needs to be constructed at run-time. This is called a dynamic SQL statement.

  • Dynamic SQL Statement Types
  • Preparing Dynamic SQL Statements
  • Executing Dynamic SQL Statements
  • Dynamic SQL Statements and Cursors
Parent topic: Developing SQL Applications
Related reference
DESCRIBE
EXECUTE
EXECUTE IMMEDIATE
OPEN
PREPARE
QUERY ODBC


Dynamic SQL Statement Types

There are four types of dynamic SQL statement:

Dynamic SQL Statement Type | Perform Queries? | Return Data?
Execute a statement once | No | No, can only return success or failure
Execute a statement more than once | No | No, can only return success or failure
Select a given list of data with a given set of selection criteria | Yes | Yes
Select any amount of data with any selection criteria | Yes | Yes

These types of dynamic SQL statement are described more fully below.

  • Execute a Statement Once
  • Execute a Statement More Than Once
  • Select a Given List of Data
  • Select any Amount of Data
Parent topic: Dynamic SQL


Execute a Statement Once

With this type of dynamic SQL statement, the statement is executed immediately. Each time the statement is executed, it is re-parsed.

Parent topic: Dynamic SQL Statement Types


Execute a Statement More Than Once

This type of dynamic SQL statement is either a statement that can be executed more than once or a statement that requires host variables. For the second type, the statement has to be prepared before it can be executed.

Parent topic: Dynamic SQL Statement Types


Select a Given List of Data

This type of dynamic SQL statement is a SELECT statement where the number and type of host variables is known. The normal sequence of SQL statements is:

  1. Prepare the statement
  2. Declare a cursor to hold the results
  3. Open the cursor
  4. Fetch the variables
  5. Close the cursor.
Parent topic: Dynamic SQL Statement Types


Select any Amount of Data

This type of dynamic SQL statement is the most difficult type to code. The type and/or number of variables is only resolved at run time. The normal sequence of SQL statements is:

  1. Prepare the statement
  2. Declare a cursor for the statement
  3. Describe the variables to be used
  4. Open the cursor using the variables just described
  5. Describe the variables to be fetched
  6. Fetch the variables using their descriptions
  7. Close the cursor.

If either the input host variables, or the output host variables are known (at compile time), then the OPEN or FETCH can name the host variables and they do not need to be described.

Parent topic: Dynamic SQL Statement Types


Preparing Dynamic SQL Statements

The PREPARE statement takes a character string containing a dynamic SQL statement and associates a name with the statement, for example:

     move "INSERT INTO publishers " &
               "VALUES (?,?,?,?)" to stmtbuf
     EXEC SQL
         PREPARE stmt1 FROM :stmtbuf
     END-EXEC

Dynamic SQL statements can contain parameter markers - question marks (?) that act as a place holder for a value. In the example above, the values to be substituted for the question marks must be supplied when the statement is executed.

Once you have prepared a statement, you can use it in one of two ways:

  • You can execute a prepared statement.
  • You can open a cursor that references a prepared statement.
  • Place Holders
  • Physical Location of PREPARE Statement
Parent topic: Dynamic SQL


Place Holders

Oracle does not use question marks as place holders. It uses the host variable notation. By convention, the place holders are named Vn, where n is a number to make the place holder unique within a statement. For readability the same place holder can be used more than once, but when the statement is executed (or opened if you are using a cursor), there must still be one host variable for each place holder. For example:

     string "update ordtab " delimited by size
            "set order_no = :v1, "
            "line_no = :v2, "
            "cust_code = :v3, "
            "part_no = :v4, "
            "part_name = :v5, "
            "order_val = :v6, "
            "pay_value = :v7 "
            "where order_no = :v1 and "
            "line_no = :v2 and "
            "cust_code = :v3 " delimited by size
      into Updt-Ord-Stmt-Arr
     end-string
     move 190 to Updt-Ord-Stmt-Len

     EXEC SQL PREPARE updt_ord FROM :Updt-Ord-Stmt END-EXEC

     EXEC SQL EXECUTE updt_ord USING
         :dcl-order-no, :dcl-line-no, :dcl-cust-code,
         :dcl-part-no,  :dcl-part-name:ind-part-name,
         :dcl-order-val,:dcl-pay-value,
         :dcl-order-no, :dcl-line-no, :dcl-cust-code
     END-EXEC

where Updt-Ord-Stmt has been defined as a host variable type of VARYING.

Parent topic: Preparing Dynamic SQL Statements


Physical Location of PREPARE Statement

When using the Oracle precompiler, the physical location of a PREPARE statement is important. A PREPARE statement must appear before an EXECUTE or a DECLARE statement.

Parent topic: Preparing Dynamic SQL Statements


Executing Dynamic SQL Statements

The EXECUTE statement runs a specified prepared SQL statement.

Note:

Only statements that do not return results can be executed in this way.

If the prepared statement contains parameter markers, the EXECUTE statement must include either the "using :hvar" option to supply parameter values using host variables or the "using descriptor :sqlda_struct" option identifying an SQLDA data structure already populated by the application. The number of parameter markers in the prepared statement must match the number of SQLDATA entries ("using descriptor :sqlda") or host variables ("using :hvar").

     move "INSERT INTO publishers " &
               "VALUES (?,?,?,?)" to stmtbuf
     EXEC SQL
         PREPARE stmt1 FROM :stmtbuf
     END-EXEC
      ...
     EXEC SQL
         EXECUTE stmt1 USING :pubid,:pubname,:city,:state
     END-EXEC.

In this example, the four parameter markers are replaced by the contents of the host variables supplied via the USING clause in the EXECUTE statement.

  • EXECUTE IMMEDIATE Statement
  • FREE Statement (COBSQL Informix)
Parent topic: Dynamic SQL


EXECUTE IMMEDIATE Statement

If the dynamic SQL statement does not contain any parameter markers, you can use EXECUTE IMMEDIATE instead of PREPARE followed by EXECUTE, for example:

     move "DELETE FROM emp " &
               "WHERE last_name = 'Smith'" to stmtbuf
     EXEC SQL
         EXECUTE IMMEDIATE :stmtbuf
     END-EXEC

When using EXECUTE IMMEDIATE, the statement is re-parsed each time it is executed. If a statement is likely to be used many times it is better to PREPARE the statement and then EXECUTE it when required.

Parent topic: Executing Dynamic SQL Statements


FREE Statement (COBSQL Informix)

The Informix precompiler provides a FREE statement that will release resources that are allocated to a prepared statement or to a cursor.

Once you have finished with a prepared statement, you would then use the FREE statement, for example:

     move "INSERT INTO publishers " " &
               "VALUES (?,?,?,?)" to stmtbuf
     EXEC SQL
         PREPARE stmt1 FROM :stmtbuf
     END-EXEC
      ...
     EXEC SQL
         EXECUTE stmt1 USING :pubid,:pubname,:city,:state
     END-EXEC.
      ...
     EXEC SQL
         FREE stmt1
     END-EXEC
Parent topic: Executing Dynamic SQL Statements


Dynamic SQL Statements and Cursors

If a dynamic SQL statement returns a result, you cannot use the EXECUTE statement. Instead, you must declare and use a cursor.

First, declare the cursor using the DECLARE CURSOR statement:

EXEC SQL
   DECLARE C1 CURSOR FOR dynamic_sql
END-EXEC

In the example above, dynamic_sql is the name of a dynamic SQL statement. You must use the PREPARE statement to prepare the dynamic SQL statement before the cursor can be opened, for example:

     move "SELECT char_col FROM mfesqltest " &
          "WHERE int_col = ?" to sql-text
     EXEC SQL
        PREPARE dynamic_sql FROM :sql-text
     END-EXEC

Now, when the OPEN statement is used to open the cursor, the prepared statement is executed:

EXEC SQL
   OPEN C1 USING :int-col
END-EXEC

If the prepared statement uses parameter markers, then the OPEN statement must supply values for those parameters by specifying either host variables or an SQLDA structure.

Once the cursor has been opened, the FETCH statement can be used to retrieve data, for example:

EXEC SQL
   FETCH C1 INTO :char-col
END-EXEC

For a full discussion of the FETCH statement, see the topic Cursors.

Finally, the cursor is closed using the CLOSE statement:

EXEC SQL
   CLOSE C1
END-EXEC

For a full discussion of the CLOSE statement, see the topic Cursors.

  • CALL Statements
Parent topic: Dynamic SQL
Related concepts
Cursors


CALL Statements

A CALL statement can be prepared and executed as dynamic SQL. This is supported only with the Open ESQL precompiler.

  • You can use parameter markers (?) in dynamic SQL wherever you use host variables in static SQL
  • Use of the IN, INPUT, OUT, OUTPUT, INOUT and CURSOR keyword following parameter markers is the same as their use after host variable parameters in static SQL.
  • The whole call statement must be enclosed in braces to conform to ODBC cannonical stored procedure syntax (the Open ESQL precompiler does this for you in static SQL). For example:
         move '{call myproc(?, ? out)}' to sql-text
     exec sql
         prepare mycall from :sql-text
     end-exec
     exec sql
         execute mycall using :parm1, :param2
     end-exec
  • If you use parameter arrays, you can limit the number of elements used with a FOR clause on the EXECUTE, for example:
         move 5 to param-count
     exec sql
         for :param-count
          execute mycall using :parm1, :param2
     end-exec
  • Example
Parent topic: Dynamic SQL Statements and Cursors


Example

The following is an example of a program that creates a stored procedure "mfexecsptest" using data source "SQLServer 2000" and then retrieves data from "publishers" table using a cursor "c1" with dynamic SQL.

$SET SQL
 WORKING-STORAGE SECTION.

 EXEC SQL INCLUDE SQLCA  END-EXEC

*> after an sql error this has the full message text
 01 MFSQLMESSAGETEXT  PIC X(250).
 01 IDX               PIC X(04)  COMP-5.

 EXEC SQL BEGIN DECLARE SECTION  END-EXEC
*> Put your host variables here if you need to port
*> to other COBOL compilers

 01  stateParam          pic xx.
 01  pubid               pic x(4).
 01  pubname             pic x(40).
 01  pubcity             pic x(20).

 01  sql-stat            pic x(256).

 EXEC SQL END DECLARE SECTION END-EXEC

 PROCEDURE DIVISION.

     EXEC SQL
         WHENEVER SQLERROR perform OpenESQL-Error
     END-EXEC

     EXEC SQL
         CONNECT TO 'SQLServer 2000' USER 'SA'
     END-EXEC

*> Put your program logic/SQL statements here

     EXEC SQL
         create procedure mfexecsptest
                 (@stateParam char(2) = 'NY' ) as

         select pub_id, pub_name, city from publishers
          where state = @stateParam
     END-EXEC

     exec sql
         declare c1 scroll cursor for dsql2 for read only
     end-exec

     move "{call mfexecsptest(?)}" to sql-stat
     exec sql prepare dsql2 from :sql-stat end-exec

     move "CA" to stateParam
     exec sql
         open c1 using :stateParam
     end-exec

     display "Testing cursor with stored procedure"
     perform until exit
         exec sql
             fetch c1 into :pubid, :pubname, :pubcity
         end-exec

         if sqlcode = 100
             exec sql close c1 end-exec
             exit perform
         else
             display pubid " " pubname " " pubcity
         end-if
     end-perform

      EXEC SQL close c1  END-EXEC

      EXEC SQL DISCONNECT CURRENT END-EXEC
      EXIT PROGRAM.
      STOP RUN.
*> Default sql error routine / modify to stop program if
*> needed
 OpenESQL-Error Section.

     display "SQL Error = " sqlstate " " sqlcode
     display MFSQLMESSAGETEXT
      *> stop run
     exit.
Parent topic: CALL Statements


Compiling SQL Applications

These topics apply to compiling SQL applications in general. Specific information on compiling for a particular preprocessor is contained in the topics covering the use of that preprocessor.

  • Specifying an SQL Preprocessor and Compiler Directive Options
    Explains the various methods of specifying an SQL preprocessor and its applicable compiler directive options to use when compiling an SQL application.
  • Compiling Multiple Program Modules
    Provides information on how to best compile SQL applications that specify multiple program modules.
  • Creating Debug Files
    Explains the process of creating debug files to assist Micro Focus SupportLine representatives in resolving issues related to the compiling of an SQL application.
Parent topic: Database Access
Related concepts
OpenESQL
COBSQL
DB2


Specifying an SQL Preprocessor and Compiler Directive Options

Generally, you also set applicable preprocessor compiler directive options when you specify the preprocessor; however, you can use a combination of methods at your preference. The order in which the COBOL compiler calls the preprocessor depends on where you specify it. We provide several alternatives:

On the Command Line
When compiling from the command line, you can specify your ESQL preprocessor and its directives in the sequence of compiler directives specified as arguments to the cobol command.
In a Directives File
You can specify your SQL preprocessor and its directives in the cobol.dir system-wide directives file and/or in a user directives file.
Embedded in the Program
You can also specify a preprocessor on the program level by embedding a $SET statement into the program itself. Use this method only when the program requires a preprocessor different from other programs in an application.

For details on setting specific SQL preprocessors, see Related concepts below.

Parent topic: Compiling SQL Applications
Related concepts
Setting the OpenESQL Preprocessor and Compiler Directive Options
Setting the COBSQL Preprocessor and Compiler Directive Options
Setting the DB2 ECM Preprocessor and Compiler Directive Options
Related reference
User Directives File


Compiling Multiple Program Modules

Multiple embedded SQL source files, compiled separately and linked to a single executable file, can share the same database connection at run time. This is also true for programs that are compiled into separate callable shared objects. If subsequent program modules (in the same process) do not process a CONNECT statement, they share the same database connection with the module that included the CONNECT statement.

OpenESQL
In a program that includes multiple, separately compiled modules, you should compile only one module with the INIT option of the SQL Compiler directive. All other modules in the program should share that first automatic connection or make explicit connections using the CONNECT statement.
OpenESQL - DB2
  • Statement names are local to a particular program module (compilation unit). This means that a statement cannot be prepared in one module and executed in another.
  • Within an application, cursor names should be unique.
COBSQL
With COBSQL, if the INIT directive is specified more than once, second and subsequent uses are ignored.
Parent topic: Compiling SQL Applications
Related reference
CONNECT
INIT


Creating Debug Files

If an error occurs when compiling a program that requires technical support, your support representative might ask you to provide additional debug files to help in determining the cause of the problem. You obtain these debug files by specifying extra Compiler directives. You might want to specifiy some of these directives to help in your own debugging efforts. The directives are:

OpenESQL
Directive | File created | Information within file
CHKECM(CTRACE) | ecmtrace.txt | Pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. This file is equivalent to output from the OpenESQL ODBC precompiler.
CHKECM(TRACE) | ecmtrace.txt | Detailed information as to what information is passed between the ODBC ECM and the Compiler. If an error occurs that generates invalid syntax, this file will be needed to help isolate where the problem occurred.
SQL(CTRACE) | sqltrace.txt | Detailed list of information passed to OpenESQL Precompiler Services, and the results. This file is very useful if an error might involve a bug in the OpenESQL run time as well as the OpenESQL ECM.
ECMLIST | program-name.lst | The standard COBOL list file, with pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. You must also compile the program with the CHKECM(CTRACE) and LIST directives.
DB2 ECM
Directive | File created | Information in the file
CHKECM(CTRACE) | ecmtrace.txt | This file contains pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. This code is equivalent to output from the IBM DB2 COBOL precompiler.
CHKECM(TRACE) | ecmtrace.txt | This file contains detailed information as to what information is passed between the DB2 ECM and the Compiler. If an error occurs that generates invalid syntax, this file will be needed to help isolate where the problem occurred.
DB2(CTRACE) | sqltrace.txt | This file contains a detailed list of information passed to IBM Precompiler Services, and the results. This file is very useful if an error might involve a bug in the DB2 system software as well as the DB2 ECM.
ECMLIST | program-name.lst | This file is the standard COBOL list file, with pseudo COBOL code that shows the code generated to replace the EXEC SQL statements. You must also compile the program with the CHKECM(CTRACE) and LIST directives.
COBSQL
For more information, see the topic COBSQL.
Parent topic: Compiling SQL Applications
Related concepts
COBSQL


OpenESQL

The OpenESQL preprocessor provides comprehensive compatibility with most database providers. When developing applications for the OpenESQL preprocessor, you can take advantage of several features that enable you to simplify your code and optimize your application at run time.

  • OpenESQL Preprocessor Options
    A discussion of the two OpenESQL preprocessor options - ODBC for native code and JDBC for JVM managed code.
  • Setting the OpenESQL Preprocessor and Compiler Directive Options
    Instructions on the methods provided to set the OpenESQL preprocessor and its options.
  • SQL Code Generation Options
    An overview of the SQL code generation options available with OpenESQL.
  • Scope - OpenESQL SQL Compiler Directive Options
    Describes the scope of each SQL compiler directive option with regard to its use at compile and run time.
  • OpenESQL DBMAN Use Case Scenarios
    A set of use case scenarios that show the appropriate SQL compiler directive options to set for each.
  • OpenESQL Datetime Data Type Handling
    Describes how OpenESQL handles date and time data types.
  • OpenESQL Fixed-length Character Strings Handling
    Describes how OpenESQL handles fixed-length character strings.
  • SQL Syntax Checking with OpenESQL
    Describes the methods you can use to boost OpenESQL SQL syntax checking.
  • OpenESQL Embedded SQL Cursor Behavior and Performance
    Describes the past and present default embedded SQL cursor behavior, including optimization, and introduces the OpenESQL Configuration utility.
  • Database Connections
    A discussion of the implicit and explicit database connection types, and how and under what circumstances to use each of them.
  • Managing Transactions
  • Programming for OpenESQL
    Programming techniques specific to SQL applications developed for the OpenESQL preprocessor.
  • ODBC
    Information specific to developing and maintaining native SQL applications that access ODBC data sources.
  • JDBC
    Information specific to developing, compiling, and maintaining managed SQL applications that access JDBC databases.
Parent topic: Database Access
Related concepts
Database Access Preprocessors
Compiling SQL Applications
Related reference
DISCONNECT


OpenESQL Preprocessor Options

The OpenESQL preprocessor provides two preprocessor options - ODBC for native code and JDBC for JVM managed code.

ODBC
Use OpenESQL with the ODBC option to compile your native applications. This option:
  • Is invoked using the SQL(DBMAN=ODBC) compiler directive
  • Uses any ODBC drivers and data providers
  • Connects to one or more ODBC data sources
  • Compiles applications to communicate with the OpenESQL ODBC Runtime
  • Enables maximum interoperability between different database systems
  • Provides comprehensive support for pessimistic (locking) concurrency control
  • Does not support disconnected or offline DataSets
JDBC
Use OpenESQL with the JDBC option to compile your JVM managed applications. This option:
  • Is invoked using the SQL(DBMAN=JDBC) compiler directive
  • Uses any of several JDBC drivers
  • Can connect to one JDBC Data Source using either a JDBC Connection String or a JDBC DataSource Object.
  • When connecting with a JDBC DataSource Object, enables you to connect to your Java data source for compilations with the SQL CHECK directive (this simulates OpenESQL DSNs with ODBC or ADO.NET)
  • Compiles applications to communicate with the OpenESQL JVM Managed Runtime
  • Enables maximum interoperability between different database systems
  • Provides support for pessimistic and optimistic (locking) concurrency control
  • Supports dynamic SQL using PREPARE, EXECUTE and EXECUTE IMMEDIATE statements and cursors that use prepared statements, but only with host variable lists in the EXECUTE and OPEN statements
  • Does not support disconnected or offline DataSets
Parent topic: OpenESQL


Setting the OpenESQL Preprocessor and Compiler Directive Options

You can specify the OpenESQL preprocessor and its directive options using any of the following methods:
In your Visual COBOL Project
Before compiling from within Visual COBOL:
  1. Open your project properties and .
  2. From the drop-down list, select OpenESQL.
On the Command Line
Use the SQL compiler directive, followed by the DBMAN option to specify the type of database access:

SQL(DBMAN==dbaType)

Where dbaType is ODBC or JDBC.

In a Directives File
You can include OpenESQL 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 OpenESQL 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 SQL(DBMAN=dbaType [SQLdirOpts])

Where dbaType is ODBC or JDBC, and SQLdirOpts is one or more additional directive options.

Important: Use this method only when the program requires a preprocessor different from other programs in an application.
Parent topic: OpenESQL
Related concepts
JDBC Process
Specifying an SQL Preprocessor and Compiler Directive Options
Related reference
System-wide Directives File, cobol.dir
SQL Compiler Directive Options
User Directives File


SQL Code Generation Options

Before you begin compiling, testing, and executing your OpenESQL code, consider what you want OpenESQL to do for you:
Only to embed SQL into the generated code
To have OpenESQL simply embed SQL into the generated code, no compiler directive options are required. This is the default behavior.
To manage the application using SQL Server stored procedures
For OpenESQL to manage your application using SQL Server stored procedures for your applicable SQL statements, specify either the ACCESS or BIND SQL compiler directive option.

The following table provides a quick reference to the SQL compiler directive options that affect code generation. For complete information on each, see the appropriate Reference topic.

SQL Compiler Directive Option | Generation Specifics | Advantages
None (default) | SQL remains embedded in object code | Simplicity
ACCESS | Creates a stored procedure at compile time for most static SQL statements | Convenient for testing when the BIND SQL compiler directive option is to be used for deployment.
BIND Enables deployment of application code by generating an SQL batch script that can be used with sqlcmd or SQL Server Management Studio to update the SQL Server database.
  • Security can be applied separately to procedures and data so that application users can only access and update data via the application.
  • DBAs can review SQL that is to be deployed without having to access source code.
Parent topic: OpenESQL
Related reference
ACCESS
BIND
SQL Compiler Directive Options


Scope - OpenESQL SQL Compiler Directive Options

Important: When the Enterprise Server feature is enabled: If you want to run your application under Enterprise Server using the generic one-phase commit switch module for ODBC or the RM switch module for SQL Server, you must recompile the appropriate RM switch module specifying all OpenESQL directives that are defined as process-based. See the process-based directives listed below. For more information on RA switch modules, see Using XA-compliant Resources (XARs).
Each SQL compiler directive option is used either at compile time, run time, or both. The behavior at run time is described as one of the following:
Source file
When a source file specifies the directive, the value set in the source file is used. If a source file does not specify the directive, then the process behavior is used.
Process
These directives affect connections. When the first-encountered EXEC SQL statement is executed, usually an EXEC SQL CONNECT statement, the runtime uses the directive settings for the source file containing the statement. These settings apply for the remainder of the process lifetime. The run-time behavior varies depending on the type of connection as follows:
ODBC with THREAD=ISOLATE
Each thread in the process uses its own set of global directive settings
ODBC with THREAD=SHARE
One set of global directive settings applies for the entire process
JDBC
COBOL runtime session, each session having its own set of global directive settings

For additional information on the scope of each SQL compiler directive option, see its corresponding Reference topic.

Process-based OpenESQL Directives

  • ALLOWNULLCHAR
  • ANSI92ENTRY
  • AUTOCOMMIT
  • CHECKDUPCURSOR
  • CHECKSINGLETON
  • CLOSE_ON_COMMIT
  • CONNECTIONPOOL
  • CURSORCASE
  • DBMAN
  • DECDEL
  • ESQLVERSION
  • ISOLATION
  • JNDI
  • JNDIENC
  • MARS
  • NIST
  • ODBCTRACE
  • ODBCV3
  • PARAMARRAY
  • PREFETCH
  • RESULTARRAY
  • STMTCACHE
  • TARGETDB
  • THREAD
  • USECURLIB
  • USER-SQLDA
  • XAID
Parent topic: OpenESQL
Related concepts
SQL Server RM Switch Module
Using XA-compliant Resources (XARs)
Related reference
SQL Compiler Directive Options


OpenESQL DBMAN Use Case Scenarios

The following OpenESQL use case scenarios show the appropriate SQL compiler directive options to set for each to ensure its ultimate success:

Type of Program | Scenario | SQL Compiler Directive Options
COBOL | ANSI compliant, and talk to an SQL Server data store via an ODBC driver | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, BEHAVIOR=ANSI)
COBOL | Maximize performance, not worry about mainframe compatibility, and talk to an Oracle data store via an ODBC driver | SQL(DBMAN=ODBC, TARGETDB=ORACLE, BEHAVIOR=OPTIMIZED)
COBOL | Maximize performance and talk to an SQL Server data store via a JDBC driver | SQL(DBMAN=JDBC, TARGETDB=MSSQLSERVER, BEHAVIOR=OPTIMIZED)
Parent topic: OpenESQL


OpenESQL Datetime Data Type Handling

By default, OpenESQL supports ODBC/ISO 8601 formats for all input and output character host variables associated with datetime columns in your DBMS.

For example, when using a SQL Server DBMS, the default data type formats for character host variables are:

SQL Server Data Type | ODBC/ISO 8601 Format
date | yyyy-mm-dd
time | hh:mm:ss
datetime2 | yyyy-mm-dd hh:mm:ss.ffffffff

In addition to SQL Server, these formats generally apply to other DBMS vendors that accept ISO 8601 formats. OpenESQL also supports alternative formats for both input and output character host variables. We provide several SQL compiler directive options that enable you to specify alternative formats that override the default.

Input Host Variables - DETECTDATE

The DETECTDATE SQL compiler option directive instructs OpenESQL to examine the contents of PIC X character input host variables, looking for data that matches the default ISO 8601 formats. You can override the default formats by specifying one or more additional directives:

Note: For complete information on each directive, see its corresponding topic under SQL Compiler Directive Options.
DATE
Specify an alternative DATE format.
DATEDELIM
Specify an alternative delimiter for date columns.
  • When used with DATE, the alternative delimiter is applied to the alternative date format specified.
  • When used without DATE, the alternative delimiter is applied to the ISO 8601 date format.
TIME
Specify an alternative TIME format.
TIMEDELIM
Specify an alternative delimiter for time columns.
  • When used with TIME, the alternative delimiter is applied to the alternative time format specified.
  • When used without TIME, the alternative delimiter is applied to the ISO 8601 time format.
TSTAMPSEP
Specify a one-character delimiter used between the date and time portions of your input host variables.

The dash character instructs OpenESQL to look for a specific set of delimiters, including a dash, a space, and a T. For example if you do not specify any alternative date or time formats, and you set TSTAMPSEP to a dash character (-), OpenESQL recognizes the following formats in your input host variables:

  • yyyy-mm-dd-hh.mm.ss.ffffff
  • yyyy-mm-dd hh.mm.ss.ffffff
  • yyyy-mm-dd hh:mm:ss.ffffff
  • yyyy-mm-ddThh.mm.ss.ffffff
  • yyyy-mm-ddThh:mm:ss.ffffff

All other characters instruct OpenESQL to search for that specific character between each date and time format, where the date portion is delimited by a dash character (-) and the time portion is delimited by a colon (:).

If you do not specify TSTAMPSEP, OpenESQL defaults to searching for a space character as the delimiter between the date and time formats, where the date portion is delimited by a dash character (-) and the time portion is delimited by a colon (:).

Guidelines for using DETECTDATE
Use of the DETECTDATE directive can create significant processing overhead. To minimize this, we recommend that you follow the guidelines presented in the following usage scenarios:
Scenario | DETECTDATE option
My application uses date, time and datetimes values in PIC X input host variables, but I am happy with the supported ODBC/ISO 8601 formats, and have no use for alternative formats. | Not required.1
My application uses date, time and datetime values in PIC X input host variables, but I only use those values in date, time, or datetime columns in my database. | CLIENT
My application uses ODBC escape sequences for date, time, and datetimes values in PIC X input host variables, but I only use those values in date, time, or datetime columns in my database. | CLIENT
My application uses date, time, and datetime values in PIC X input host variables, but I only use those values in character columns in my database. Also, my SQL does not use either implicit or explicit characters for date, time, or datetime2 data types. | Not required. Do not use DETECTDATE, DATE, or TIME SQL compiler directive options.
I only use SQLTYPE host variables with date, time and datetime columns, and never use PIC X host variables with date, time or datetime columns. | Not required.2
My application uses date, time and datetime values in PIC X input host variables, and I use those values both in character columns and in date, time and datetime columns in my database , and my character columns might use data in formats that could be confused with the formats for date, time or datetime values. | SERVER
1We recommend that you use DETECTDATE when also using TIME values with Oracle.

2Optionally, you can use alternative datetime SQL compiler directive options.

Note:
  • We recommend that for SQL Server applications developed using Visual COBOL version 2.2 Update 2 or earlier, you specify the DETECTDATE directive if the application uses PIC X host variables with datetime columns in your SQL Server database.
  • For complete information on all DETECTDATE options, see the DETECTDATE SQL compiler directive option topic.

Output Host Variables

By default OpenESQL returns date, time and datetime data types in the ISO 8601 default format. You can override the default format by specifying additional OpenESQL directives as follows:

DBMS Data Type | ODBC/ISO 8601 Format | OpenESQL Directives
date | yyyy-mm-dd | DATE, DATEDELIM
time | hh:mm:ss | TIME, TIMEDELIM
datetime | yyyy-mm-dd hh:mm:ss.ffffff | TSTAMPSEP
Parent topic: OpenESQL
Related reference
TIME
DATE
DATEDELIM
TIMEDELIM
TSTAMPSEP
SQL Compiler Directive Options
DETECTDATE


OpenESQL Fixed-length Character Strings Handling

You can use COBOL fixed-length character strings, declared as PIC X(n), as input, output, or a combination of input and output host variables in EXEC SQL statements. The following examples illustrate different uses of fixed-length character strings:

Example 1: Input using the HVIN host variable, two statements
 EXEC SQL INSERT INTO TAB1 (COL1)VALUES (:HVIN) END-EXEC
EXEC SQL DELETE * FROM TAB1 WHERE COL1 LIKE :HVIN END-EXEC
Example 2: Output using the HVOUT host variable, one statement
 EXEC SQL SELECT COL1 INTO :HVOUT FROM DUAL END-EXEC
Example 3: Input using the HVIN host variable, and output using the HVOUT host variable, two statements
 EXEC SQL SELECT COUNT(*) INTO :HVOUT FROM TAB1 WHERE COL1 = :HVIN END-EXEC
 EXEC SQL SELECT 'START' || :HVIN ||'END' INTO :HVOUT FROM SYSIBM.SYSDUMMY1 END-EXEC

Problem - preserve or trim trailing spaces

Typically, COBOL PIC X(n) host variables are not terminated with the NULL character ('\0'), but rather with trailing spaces (see Fixed-length Character Strings for details). Given the different ways PIC X(n) host variables can be constructed and used with varying DBMS SQL column definitions such as CHAR or VARCHAR, OpenESQL has difficulty determining whether to:

  • Preserve trailing spaces, meaning to present the trailing spaces to the database
  • Trim trailing spaces, meaning to omit the trailing spaces from the database

Consider the INSERT statement in Example 1 above. If COL1 is a VARCHAR column in TAB1, should trailing spaces contained in HVIN be preserved or trimmed?

Consider also the DELETE statement in Example 1 in the same context. When used with the LIKE predicate, should trailing spaces contained in HVIN be preserved or trimmed?

Solutions

Use the OpenESQL default behavior
The current OpenESQL PIC X(n) handling of trailing spaces has evolved over the years to address VARCHAR and WHERE expression issues. Currently by default, OpenESQL strips all trailing spaces before presenting input host variable values to the database with one exception, that is, when a PIC X(n) host variable contains only spaces. In that case, OpenESQL presents a single space to the database. The advantage of this approach is that the database itself pads host variables with trailing spaces before placing them into CHAR columns, and does not pad VARCHAR columns with trailing spaces.
Replace fixed-length host variables with variable-length host variables
Outside of the OpenESQL default behavior, best practice (insofar as it is possible) for ensuring the proper handling of trailing spaces in VARCHAR DBMS columns is to replace PIC X(n) host variables with variable-length character strings (see Variable-length Character Strings for details). In this case, the program itself explicitly controls the VARCHAR length and value.
Use the RTRIM and CAST functions
Another approach to resolving this problem is to re-write specific SQL statements in a portable manner using the RTRIM(:hvin) function to trim trailing spaces, and the CAST(:hvin as CHAR(n)) function to preserve trailing spaces, where hvin represents an input host variable.
Use the PICXBINDING directive
If you need your database to preserve space padding in VARCHAR columns, but you cannot change fixed-length host variables to variable-length, nor can you use the RTRIM or CAST functions, try using the OpenESQL PICXBINDING SQL compiler directive option to preserve or trim trailing spaces. This can be helpful, for instance, when using LIKE expressions with SQL Server. See PICXBINDING for details.
Note: PICXBINDING applies to all SQL statements and associated host variables in a given COBOL source file. If you need more granularity, however, you must use variable-length host variables, or the RTRIM or CAST functions on specific SQL statements.
Parent topic: OpenESQL
Related reference
PICXBINDING
Fixed-length Character Strings
Variable-length Character Strings


SQL Syntax Checking with OpenESQL

OpenESQL is an open implementation for the ANSI Embedded SQL standard, and as such can be used with a wide variety of databases, each of which can accept different and sometimes unique SQL syntax. To accommodate these differences, by default, OpenESQL does minimal SQL syntax checking at compile time. You can increase the level of OpenESQL SQL syntax checking at compile time by using the SQL(CHECK) directive with other associated directives.

SQL(CHECK) connects to the database during compilation, and asks the database to validate SQL syntax with the existing database SQL objects such as tables, columns, etc.

In addition to SQL(CHECK), you must also specify the SQL(DB) directive, and optionally the SQL(PASS) directive. This combination ensures a successful connection to your database at compile time, and returns applicable SQL syntax errors.

Note: When using SQL(CHECK), we suggest that you connect to a local rather than a remote database, as network access could compromise compilation speed.

In addition to the topics listed below, see the CHECK reference topic for more information on the SQL(CHECK) compiler directive option.

  • SQL(CHECK) and Schema Objects
  • SQL(CHECK) Command-line Options
    Describes command-line methods to use for boosting SQL syntax checking.
  • SQL Statement Prefixes for SQL(CHECK)
    Describes the statement prefixes you can use to initiate compile-time execution of SQL statements when compiling with SQL(CHECK).
Parent topic: OpenESQL
Related reference
CHECK


SQL(CHECK) and Schema Objects

All databases contain schemas that include SQL objects like tables, columns, views, and temporary tables. If all of the SQL objects in a database are available at compile time, using the SQL(CHECK) directive ensures that all SQL syntax is fully checked by the database during compilation.

However, some schema objects might not be available in the database at compile time. In this case, OpenESQL offers two solutions:

SQL(IGNORESCHEMAERRORS) directive
Use this directive with SQL(CHECK) when tables or other SQL objects do not exist in the database. The addition of SQL(IGNORESCHEMAERRORS) enables OpenESQL to ignore invalid object reference errors returned by the database, and continue compilation.
[ALSO CHECK] and [ONLY CHECK] statement prefixes
Use these statement prefixes on individual SQL statements in your code if you want OpenESQL to actually create SQL objects in the database at compile time. With the objects in the database, all invalid object reference errors are returned during compilation, and optionally at run time as well.

For more information on [ALSO CHECK] and [ONLY CHECK], see SQL Statement Prefixes for SQL(CHECK).

Parent topic: SQL Syntax Checking with OpenESQL
Related concepts
SQL(CHECK) Command-line Options
SQL Statement Prefixes for SQL(CHECK)
Related reference
CHECK


SQL(CHECK) Command-line Options

You can improve SQL syntax checking in some scenarios by combining SQL(CHECK) with additional compiler directive options and/or using a local database.

SQL(CHECK) with SQL(DB) and, optionally, SQL(PASS)
When you use the SQL(CHECK) and SQL(DB) directives, together with SQL(PASS) if necessary, OpenESQL opens a connection to a data source at compile time and uses the data source to perform additional checking. This is the recommended way to use OpenESQL and is much more reliable at detecting errors. In addition to detecting syntax errors that are specific to a particular data source, it can also detect misspelled names and invalid use of reserved words.
SQL(CHECK), local database, deployment schema
OpenESQL is at its most effective when you use SQL(CHECK) with a local database that uses the same schema that is used when the application is deployed. This combination compiles programs faster than accessing a networked server for compile-time checking.
SQL(CHECK), local database, no deployment schema
When you do not have access to a data source with the deployment schema installed you can still use SQL(CHECK) to perform additional syntax checking, but you must also use SQL(IGNORSCHEMAERRORS) to avoid errors for invalid name use. SQL(IGNORESCHEMAERRORS) is also helpful when your program uses temporary tables that exist only at runtime.
Parent topic: SQL Syntax Checking with OpenESQL
Related concepts
SQL(CHECK) and Schema Objects
Related reference
CHECK


SQL Statement Prefixes for SQL(CHECK)

To enable complete SQL syntax checking at compile time when tables or temporary tables are not in your database, OpenESQL provides SQL statement prefixes that enable you to actually execute specific SQL statements at compile time, and optionally at run time as well.

A statement prefix is coded directly into an EXEC SQL statement, and executed only when compiled with SQL(CHECK).

Syntax:

EXEC SQL [statementPrefix] [errorFlag[...]] SQLStatement END-EXEC

Parameters:

statementPrefix
[ALSO CHECK]
Statement prefix that instructs SQL(CHECK) to execute the following SQLStatement both at compile time and a run time.
[ONLY CHECK]
Statement prefix that instructs SQL(CHECK) to execute the following SQLStatement at compile time only.
[NOCHECK]
Statement prefix that turns off the effects of the SQL(CHECK) directive for the associated SQLStatement only.
errorFlag
[IGNORE ERROR]
Overrides the default behavior of providing a success or error return code upon SQLStatement execution, and instead ignores all errors at compile time and proceeds with compilation.
[WITH WARNING]
Overrides the default behavior of providing a success or error return code upon SQLStatement execution, and instead returns all errors as warnings at compile time, and proceeds with compilation.
SQLStatement
An SQL statement that conforms to the following:
  • A DDL statement such as CREATE TABLE or the specific DML statements INSERT, DELETE or UPDATE
  • No host variables used
  • Written in a syntax understood by the DBMS vendor

Examples:

Example 1
Create a SQL Server temporary table at compile time only so that subsequent SQL that references this table is fully syntax checked by the OpenESQL SQL(CHECK) directive during compilation.
EXEC SQL [ONLY CHECK]
create table #temp(col1 int,col2 char(32))
END-EXEC
Example 2
Create a SQL Server temporary table at both compile time and execution time so that, in addition to full compile-time syntax checking, the table is actually created at execution time.
EXEC SQL [ALSO CHECK]
create table #temp(col1 int,col2 char(32))
END-EXEC
Example 3
Create test data at compile time with Oracle whether or not the table exists at compile time.
EXEC SQL [ONLY CHECK IGNORE ERROR]
Drop table TT
END-EXEC

EXEC SQL [ONLY CHECK]
create table TT (col1 int)
END-EXEC

EXEC SQL [ONLY CHECK]
Insert into table TT values (1)
END-EXEC
Parent topic: SQL Syntax Checking with OpenESQL
Related concepts
SQL(CHECK) and Schema Objects
Related reference
CHECK


OpenESQL Embedded SQL Cursor Behavior and Performance

In releases of Visual COBOL earlier than version 2.1, by default, OpenESQL handled ambiguously declared embedded SQL cursors, that is, those declared without a FOR READONLY or FOR UPDATE clause, by making them updateable, scrollable, and capable of retrieving database locks — the maximum functionality. Unfortunately, this degraded performance for most applications. Also in these earlier releases, it was difficult and tedious to make robust changes to cursor characteristics because it often required modifying source code by either adding EXEC SQL SET statements or modifying existing EXEC SQL DECLARE CURSOR statements.

Starting with Visual COBOL 2.1, by default, OpenESQL began handling ambiguously declared embedded SQL cursors by making them forward and readonly, and incapable of retrieving locks. This change improved performance and efficiency, optimizing OpenESQL just as most DBMS SQL cursor access plans do.

You can further optimize OpenESQL by using the BEHAVIOR directive, which enables you to change your embedded SQL cursor characteristics without changing any code in your SQL application sources.

Visual COBOL provides the OpenESQL Configuration Utility to assist you in setting the BEHAVIOR directive and primitive directive defaults for your applications. See OpenESQL Configuration Utility for Default SQL Cursor Behavior for details.

  • Embedded SQL Cursors in Older Applications
    Provides solutions for updating and optimizing older OpenESQL applications.
Parent topic: OpenESQL
Related concepts
OpenESQL


Embedded SQL Cursors in Older Applications

When using a current version of Visual COBOL with an SQL application that has been:
  • Developed in an earlier Micro Focus COBOL development product or a version of Visual COBOL earlier than 2.1
  • Migrated to a version of Visual COBOL later than 2.1
Consider setting BEHAVIOR=UNOPTIMIZED as a temporary solution that enables you to compile and run these applications on the newer versions of Visual COBOL.

BEHAVIOR=UNOPTIMIZED sets OpenESQL to the default behavior that existed in older versions of our software, and therefore handles ambiguously declared embedded SQL cursors using the behavior that was the default when the application was developed. Apply this temporary solution to applications that contain the following:

  • EXEC SQL SET CONCURRENCY
  • EXEC SQL SET SCROLLOPTION
  • EXEC SQL SET CURSORTYPE
  • A FETCH that occurs on a cursor after an EXEC SQL COMMIT statement is executed

However, because this temporary solution does not provide optimized performance, we recommend that you eventually update your older SQL applications to take advantage of the current Visual COBOL optimization features. To do this:

  • Remove EXEC SQL SET CONCURRENCY, SET SCROLLOPTION, and SET CURSORTYPE statements. These are replaced by setting appropriate BEHAVIOR primitive directives.
  • We offer two approaches to updating applications that contain a FETCH that occurs on a cursor after an EXEC SQL COMMIT statement is executed. Do one of the following:
    • Modify the code by adding a WITH HOLD clause to the DECLARE CURSOR statement
    • Leave the code intact, and specify appropriate BEHAVIOR primitive directives
Parent topic: OpenESQL Embedded SQL Cursor Behavior and Performance


Database Connections

Each OpenESQL preprocessor option - ODBC and JDBC - requires that you create a connection to the database using either an explicit or an implicit connection.
Important: You must have the appropriate drivers and/or data providers installed and data source names created before you can establish a connection.

Explicit Connections (recommended)

An explicit connection is one established within your program code using the CONNECT embedded SQL statement, and disconnected using the DISCONNECT embedded SQL statement. This enables you to make connections to multiple databases at runtime on an as needed basis.

Use explicit connections when your program accesses multiple data sources or databases.

See the CONNECT and DISCONNECT embedded SQL topics for details.

Note: For ODBC connections only, you can specify an explicit disconnect and rollback to execute automatically if the program terminates abnormally. See the INIT compiler directive option topic for more information.

Implicit Connections

An implicit connection is one defined by way of SQL compiler directive options at compile time. This method establishes a single connection to one database. Use this method only when your program accesses only one database.

Use a combination of the INIT, DB, and possibly PASS compiler directive options to create the connection.
  • INIT - to identify the data source name
  • DB - to identify the database
  • PASS - to provide a user ID and password if required

OpenESQL automatically disconnects from the data source when the program terminates.

Parent topic: OpenESQL
Related reference
CONNECT
DB
DISCONNECT
INIT
PASS


Managing Transactions

Historically, SQL connections enabled by database providers operate in autocommit mode, meaning no transactional support is provided. However, SQL applications typically need transactional support, whether managed internally by an SQL standalone application or externally by transaction managers that provide 2PC.

In earlier releases of Visual COBOL the OpenESQL SQL AUTOCOMMIT compiler directive option was originally designed to accommodate internal transaction management in standalone SQL applications, and subsequently modified to also accommodate the various methods of external transaction management provided by external transaction managers.

Starting with Visual COBOL version 4.0, OpenESQL provides better transaction management using the TRANSACTION SQL compiler directive option, replacing the AUTOCOMMIT directive. The TRANSACTION directive enables more precise control over transaction behavior as compared to AUTOCOMMIT. See the TRANSACTION and AUTOCOMMIT reference topics for details.

Parent topic: OpenESQL
Parent topic: Using OpenESQL with ODBC
Related reference
AUTOCOMMIT
BEHAVIOR
TRANSACTION
ROLLBACK
COMMIT
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT


Programming for OpenESQL

These topics explain programming techniques that are specific to OpenESQL in general. For additional programming techniques specific to native applications, see the ODBC topic, and for managed applications, see the JDBC topic.

  • Working With OpenESQL Cursors and Result Sets
  • Working with Stored Procedures and Result Sets
  • Unicode Support in OpenESQL
  • OpenESQL Globalization Best Practices
  • Keywords
Parent topic: OpenESQL
Related concepts
ODBC
JDBC


Working With OpenESQL Cursors and Result Sets

OpenESQL applications support multiple results sets when you define your DECLARE CURSOR statements to include multiple SELECT statements.

Note: You can also reference multiple result sets by executing a stored procedure. For more information on how this works, see Working With OpenESQL Stored Procedures and Result Sets.
To return multiple result sets for a particular cursor, its DECLARE CURSOR statement in your application must open the cursor and also contain a SELECT statement for each result set you want to return. For example:
      EXEC SQL
          DECLARE C1 CURSOR
          FOR
              SELECT CUSTID FROM COMPANY;
              SELECT CUSTNAME FROM COMPANY;
      END-EXEC
      EXEC SQL OPEN C1 END-EXEC

In this example, we return two result sets. After opening the C1 cursor, execute a FETCH statement to consume the first result set - that defined by the SELECT CUSTID FROM COMPANY statement.

When FETCH returns an SQLCODE of 100 (signifying the end of the current result set), issue the GET NEXT RESULT SET statement to fetch the result set for the next SELECT statement. For example:
      EXEC SQL
          GET NEXT RESULT SET FOR C1
      END-EXEC
Once the result set for SELECT CUSTNAME FROM COMPANY is consumed, GET NEXT RESULT SET returns an SQLCODE of 100, indicating that no additional result sets are available.
Note: If another result set is available, meaning your DECLARE CURSOR statement contains at least one additional SELECT statement that has not been processed, GET NEXT RESULT SET returns an SQLCODE of 0. To retrieve all available result sets, continue issuing the GET NEXT RESULT SET statement until it returns an SQLCODE of 100.
Parent topic: Programming for OpenESQL
Related reference
DECLARE CURSOR
FETCH
GET NEXT RESULT SET


Working with Stored Procedures and Result Sets

A DBMS vendor-specific stored procedure can:

  • Accept input parameters
  • Return output parameters
  • Accept and return input/output parameters
  • Use positional or keyword parameters
  • Return one or more forward only read only result sets
  • Be called with parameter arrays
Note: The features provided by different database vendors vary considerably, and any given vendor might offer only a subset of the features listed above. For this reason, stored procedure calls are much less portable between data sources than other OpenESQL statements.

Calling a Stored Procedure that Returns No Result Sets

To call a stored procedure that returns no result sets, use the CALL embedded SQL statement. For complete details on using this statement, see the CALL topic.

Calling a Stored Procedure that Returns One or More Result Sets

If a stored procedure returns one or more result sets, you must first declare it using the DECLARE CURSOR statement. For example:

         EXEC SQL
                DECLARE cursorName CURSOR FOR storedProcedureCallStatement
         END-EXEC

You then call the stored procedure just as you would any other type of cursor using the OPEN statement to open the cursor, followed by the FETCH statement to fetch result set rows.

If your stored procedure is coded to return more than one result set, and your FETCH statement returns an SQLCODE of 100 (signifying the end of the current result set), you can issue the GET NEXT RESULT SET statement to fetch the next result set as follows:
          EXEC SQL
                 GET NEXT RESULT SET FOR cursorName
          END-EXEC

If your GET NEXT RESULT SET statement returns an SQLCODE of 0, another result set is available, and you can issue another GET NEXT RESULT SET to retrieve it. However, if GET NEXT RESULT SET returns an SQLCODE of 100, no additional result sets are available.

Using Array Parameters

ODBC parameters differ from Oracle array parameters. The effect of using a parameter array is the same as repeating the statement for each element of the array. On a stored procedure call, if one parameter is passed as an array, then all parameters must be arrays with the same number of elements. The stored procedure "sees" one call for each "row" of parameters. The number of rows passed can be limited to less than the full array size by preceding the call with the following phrase:
FOR :hvar

Where :hvar is an integer host variable containing a count of the number of rows to be passed.

OpenESQL for JDBC

When working with OpenESQL for JDBC, the following applies:

Restriction: The following scenario can cause the COBOL compiler to fail to update output host variables when the cursor for a stored procedure call is closed. This can happen when stored procedures meet all three of the following criteria:
  • Are called using the OPEN statement
  • Return a return value, output parameters, or both
  • Return a result set

The failure occurs because the COBOL compiler, when possible, compiles 01-level fields and their subordinate 01-level FILLER fields as JVM types.

To ensure successful compilation, use traditional COBOL data types, such as PIC X(n), COMP-3, etc., for host variables rather than object types, such as string, binary-long, BigDecimal, etc., and do one of the following:

  • Compile using the NOILNATIVE COBOL compiler directive
  • Declare host variables that receive return values or output parameters at level 02 or higher, with a record name other than FILLER

This scenario does not apply to stored procedures called using the CALL statement.

Parent topic: Programming for OpenESQL
Related reference
CALL
EXECSP
DECLARE CURSOR
FETCH
GET NEXT RESULT SET
OPEN


Unicode Support in OpenESQL

Some applications want to retrieve or store unicode data in Microsoft SQL Server data sources without it being converted to ANSI. Previous versions of OpenESQL did not have a way of accessing data without it being automatically converted. Now, however, OpenESQL and your COBOL development system can work directly with unicode data without having it converted to ANSI, by using a new type of host variable. Microsoft SQL Server supports three unicode column types:

  • NCHAR
  • NVARCHAR
  • NTEXT

To access these columns without the data being automatically converted, define a host variable with a definition of:

PIC N(xx) USAGE NATIONAL

where xx is the size of the column. This format is currently supported for both fixed and variable length data. Variable length data can be terminated with nulls to signify end of data for column when inserting or updating data. When data is retrieved from the data source, it will be space filled to the end of the host variable.

For example, the following program will retrieve employee information from the Northwind sample database that comes with Microsoft SQL Server 2000 product:

$SET UNICODE(NATIVE)
$SET SQL
 WORKING-STORAGE SECTION.

 EXEC SQL INCLUDE SQLCA  END-EXEC

* after an sql error this has the full message text
 01 MFSQLMESSAGETEXT  PIC X(250).
 01 IDX         PIC X(04)  COMP-5.

 EXEC SQL BEGIN DECLARE SECTION  END-EXEC
* Put your host variables here if you need to port
* to other COBOL compilers
 EXEC SQL INCLUDE Employees END-EXEC

 EXEC SQL END DECLARE SECTION END-EXEC

 PROCEDURE DIVISION.

     EXEC SQL
         WHENEVER SQLERROR perform OpenESQL-Error
     END-EXEC

     EXEC SQL
         CONNECT TO 'LocalServer'
     END-EXEC

* Put your program logic/SQL statements here
     EXEC SQL
         DECLARE CSR135 CURSOR FOR SELECT
               A.FirstName
              ,A.LastName
              ,A.EmployeeID
              ,A.HireDate
             FROM Employees A
     END-EXEC
     EXEC SQL OPEN CSR135 END-EXEC
     PERFORM UNTIL SQLSTATE >= "02000"
         EXEC SQL
             FETCH CSR135 INTO
                :Employees-FirstName
               ,:Employees-LastName
               ,:Employees-EmployeeID
               ,:Employees-HireDate:Employees-HireDate-NULL
         END-EXEC

        *> Process data from FETCH
         IF SQLSTATE < "02000"

*      for array fetches, field sqlerrd(3) contains the
*      number of rows returned
*            PERFORM VARYING IDX FROM 1 BY 1
*                    UNTIL IDX > SQLERRD(3)

*     you will need to add code here to process the array

*            END-PERFORM
         END-IF
     END-PERFORM
     EXEC SQL CLOSE CSR135 END-EXEC

     EXEC SQL DISCONNECT CURRENT END-EXEC
     EXIT PROGRAM.
     STOP RUN.

* Default sql error routine - modify to stop program
* if needed
 OpenESQL-Error Section.
     display "SQL Error = " sqlstate " " sqlcode
     display MFSQLMESSAGETEXT
*    stop run
     exit.

This is the same code that would retrieve the data in ANSI except for the definitions in the INCLUDE copybook Employees which now looks like:

* -----------------------------------------------------------
* COBOL DECLARATION FOR TABLE Employees
* -----------------------------------------------------------
 01  DCLEmployees.
     03 Employees-EmployeeID       PIC S9(09)  COMP-5.
     03 Employees-LastName         PIC N(20) USAGE NATIONAL.
     03 Employees-FirstName        PIC N(10) USAGE NATIONAL.
     03 Employees-Title            PIC N(30) USAGE NATIONAL.
     03 Employees-TitleOfCourtesy  PIC N(25) USAGE NATIONAL.
     03 Employees-BirthDate        PIC X(23).
     03 Employees-HireDate         PIC X(23).
     03 Employees-Address          PIC N(60) USAGE NATIONAL.
     03 Employees-City             PIC N(15) USAGE NATIONAL.
     03 Employees-Region           PIC N(15) USAGE NATIONAL.
     03 Employees-PostalCode       PIC N(10) USAGE NATIONAL.
     03 Employees-Country          PIC N(15) USAGE NATIONAL.
     03 Employees-HomePhone        PIC N(24) USAGE NATIONAL.
     03 Employees-Extension        PIC N(4) USAGE NATIONAL.
     03 Employees-Photo            PIC X(64000).
     03 Employees-Notes          PIC N(32000) USAGE NATIONAL.
     03 Employees-ReportsTo        PIC S9(09)  COMP-5.
     03 Employees-PhotoPath        PIC N(255) USAGE NATIONAL.
Parent topic: Programming for OpenESQL


OpenESQL Globalization Best Practices

OpenESQL supports the use of international data with COBOL host variables in a variety of different ways. International data is stored in the columns of a DBMS as UTF-16, UTF-8 or MBCS (Mixed- or Multi-byte Character Set). The locale for a DBMS client application can also be international, typically MBCS or UTF-8.

When an OpenESQL COBOL application issues a request to a DBMS to send or return international data to or from a host variable, OpenESQL determines the appropriate COBOL host variable content based on the host variable declaration itself and locale of your DBMS client application.

We strongly recommend that to avoid data loss, you match the locale of your DBMS client application with the international encoding specification for the DBMS, and that you select the most appropriate COBOL host variable declaration, as shown here:

COBOL Host Variable Declaration DBMS International Encoding Specification Summary
PIC X UTF-16 Conversion of DBMS data to and from host variables using the locale1 of the client application.

Possible data loss if your UTF-16 data is not supported with the locale of your application.

PIC X UTF-8 No conversion or translation of data if the locale1 of the client application is also UTF-8.
Note: Application locale UTF-8 is not supported on Windows platforms.

Highly recommended.

Conversion of DBMS data to and from host variables using the locale1 of the client application does take place if UTF-8 is not the locale of the client application. This can lead to possible data loss.

PIC X MBCS2 No conversion or translation of data if the locale1 of the client application uses the same MBCS2.

Highly recommended.

Conversion of DBMS data to and from host variables using the locale of the client application does take place if the MBCS of the client application does not match that of the DBMS. This can lead to possible data loss.

PIC N USAGE DISPLAY-1 PIC G4 UTF-16, UTF-8 Conversion of data to and from host variables using the locale1 of the client application.

Data is converted the DBCS3 of the client application's locale. This can lead to possible data loss.

PIC N USAGE DISPLAY-1 PIC G4 MBCS2 Minor conversion or translation of data if the locale1 of the client application uses the same MBCS2. In this case, single-byte characters in the DBMS are converted to and from the DBCS3 of the client application's locale.

If the MBCS of the client application does not match that of the DBMS, this can lead to possible data loss.

PIC N USAGE NATIONAL UTF-16 No conversion or translation of data.

Highly recommended.

PIC N USAGE NATIONAL UTF-8, MBCS2 Conversion of DBMS data to and from host variables where the format is UTF-16.

Because data is converted between UTF-8 and MBCS to and from UTF-16 format in host variables, no loss of data can occur.

Recommended.

1Code page.

2Mixed- or Multi-byte Character Set. Used to support mixed character sets containing characters that can be represented with single bytes (SBCS) as well as double bytes (DBCS). MBCSs exist in Japan, China, and Korea. For example, MBCS 932 is for the Japanese language.

3Double-byte Character Set. DBCS is the double-byte character component of an MBCS.

4PIC N USAGE DISPLAY-1 and PIC G host variables in your COBOL program always uses the DBCS that corresponds to the locale of your client application.

Example 1

If you store MBCS or UTF-8 in your DBMS, it is best to set the locale of your client application to the same value, and use PIC X host variables in your COBOL program.

Example 2

If you store UTF-16 in your database, it is best to use PIC N USAGE NATIONAL host variables in your COBOL programs.

Parent topic: Programming for OpenESQL
Related reference
DBCS Character Strings
DBCS Variable-length Character Strings
DBCS Large Character Strings
SQL/COBOL Data Type Mappings
Unicode Character Strings
Unicode Large Character Strings (DBCLOB)
Unicode Variable-length Character Strings


Keywords

A number of keywords are recognized by OpenESQL and should not therefore be used within your program for other purposes. A full list of reserved keywords is given in the Keywords reference topic.

Parent topic: Programming for OpenESQL
Related reference
Keywords


ODBC

Use OpenESQL with the ODBC option to compile your native applications. This option:
  • Is invoked using the SQL(DBMAN=ODBC) compiler directive
  • Uses any ODBC drivers and data providers
  • Connects to one or more ODBC data sources
  • Compiles applications to communicate with the OpenESQL ODBC Runtime
  • Enables maximum interoperability between different database systems
  • Provides comprehensive support for pessimistic (locking) concurrency control
  • Does not support disconnected or offline DataSets
  • Demonstration Applications
    A list of available demonstration applications are provided to illustrate programming techniques and runtime behavior for applications using ODBC, along with a description of each of these applications.
  • ODBC Drivers and Data Source Names
    Install ODBC drivers and create DSNs.
  • Using OpenESQL with ODBC
    Programming and compiling OpenESQL native SQL applications with ODBC.
Parent topic: OpenESQL
Related concepts
Programming for OpenESQL
Related reference
DBMAN


Demonstration Applications

Visual COBOL provides a number of demonstration applications or programs for OpenESQL ODBC.

Before you can use any of the demonstration applications, you need to have installed at least one ODBC driver, and created DSNs to use with the demonstrations.

Some of the demonstration applications expect that a table called EMP exists on the database to which you are connecting.

The OpenESQL ODBC demonstration applications all produce a console log displaying their progress and, possibly, query results. They all terminate on receipt of an error, after displaying an error message.

The source files for these samples are located in $COBDIR/demo/openesql.

Each sample program comes with a progName.txt file to explain how to use the program.

catalog.cbl
The file catalog.cbl is an OpenESQL demonstration program that shows how to use the ODBC catalog functions from COBOL.
dynquery.cbl
The file dynquery.cbl is an OpenESQL demonstration program that shows how to use dynamic SQL functions from COBOL. It provides the capability for the user to enter any SQL statement and the program will execute them. It shows how to prepare a SQL statement and how to use the SQLDA structure to retrieve data from columns when the type of the column is not known when the program is compiled.

If you are accessing the EMP table described above, a sample query would be:

select FIRST_NAME, LAST_NAME, HIRE_DATE, SALARY from EMP
static.cbl
The file static.cbl is an OpenESQL demonstration program that shows how to use basic SQL functions from COBOL. It demonstrates the use of INSERT, UPDATE, DELETE, SELECT INTO and SELECT using a cursor. It also shows the use of COMMIT and ROLLBACK.
testconn.cbl
The file testconn.cbl is an OpenESQL demonstration program that shows how to use different formats of the CONNECT and DISCONNECT statements.
Parent topic: ODBC


ODBC Drivers and Data Source Names

To use ODBC with OpenESQL, you must have the following in place:
  • Install at least one ODBC driver of your choice.
  • Install and configure ODBC Driver Manager and the ODBC driver software. See your Driver Manager or Driver vendor documentation for details.
  • Create at least one data source name (DSN) that identifies a database to which you can connect.
Parent topic: ODBC


Using OpenESQL with ODBC

When using the ODBC option, follow the programming and compiling guidelines provided for OpenESQL in general. In addition, the following topics provide information specific to working with ODBC:

  • Managing Transactions
  • Positioned Update
  • XML Support
Parent topic: ODBC


Positioned Update

ODBC supports positioned update, which updates the row most recently fetched by using a cursor. However, not all drivers provide support for positioned update.

Note: You cannot use host arrays with positioned update.

With some ODBC drivers, the select statement used by the cursor must contain a FOR UPDATE clause to enable positioned update. Most data sources require specific combinations of SCROLLOPTION and CONCURRENCY to be specified either by SET statements or in the DECLARE CURSOR statement. If this fails to work, the ODBC Cursor Library provides a restricted implementation of positioned update which can be enabled by compiling with the directive SQL(USECURLIB=YES) and using SCROLLOPTION STATIC and CONCURRENCY OPTCCVAL (or OPTIMISTIC). To avoid multiple rows being updated when using the ODBC Cursor Library, the cursor query should include the primary key column(s) for the table to be updated.

Example

$SET SQL(usecurlib=yes)
 WORKING-STORAGE SECTION.

 EXEC SQL INCLUDE SQLCA  END-EXEC

*> after an sql error this has the full message text
 01 MFSQLMESSAGETEXT  PIC X(250).
 01 IDX               PIC X(04)  COMP-5.

 EXEC SQL BEGIN DECLARE SECTION  END-EXEC
*> Put your host variables here if you need to port
*> to other COBOL compilers
 EXEC SQL INCLUDE Products END-EXEC

 EXEC SQL END DECLARE SECTION END-EXEC

 PROCEDURE DIVISION.

     EXEC SQL
         WHENEVER SQLERROR perform OpenESQL-Error
     END-EXEC

*> Demo for positioned updates using ACCESS datasource
     EXEC SQL
       CONNECT TO 'Inventory' USER 'admin'
     END-EXEC

*> Put your program logic/SQL statements here

     EXEC SQL
       DECLARE CSR679 CURSOR
         FOR SELECT
              A.ProductID
             ,A.ProductName
             ,A.UnitPrice
         FROM Products A
        WHERE ( A.ProductID <  3 )
     END-EXEC

     EXEC SQL SET SCROLLOPTION static  END-EXEC
     EXEC SQL SET CONCURRENCY optccval END-EXEC

     EXEC SQL OPEN CSR679 END-EXEC
     PERFORM UNTIL SQLSTATE >= "02000"
        EXEC SQL
        FETCH CSR679 INTO
            :ProductID
           ,:ProductName:ProductName-NULL
           ,:UnitPrice:UnitPrice-NULL
        END-EXEC
        *> Process data from FETCH
        IF SQLSTATE = "00000"
           *> increase price by 10%
            compute unitprice = unitprice * 1.10
            EXEC SQL
               UPDATE Products
                 SET UnitPrice = :UnitPrice:UnitPrice-NULL
               WHERE CURRENT OF CSR679
           END-EXEC
        END-IF
     END-PERFORM
     EXEC SQL CLOSE CSR679 END-EXEC

     EXEC SQL COMMIT END-EXEC

     EXEC SQL DISCONNECT CURRENT END-EXEC
     EXIT PROGRAM.
     STOP RUN.

*> Default sql error routine - modify to stop program if
*> needed
  OpenESQL-Error Section.

      display "SQL Error = " sqlstate " " sqlcode
      display MFSQLMESSAGETEXT
*> stop run
      exit.
Parent topic: Using OpenESQL with ODBC


XML Support

If you have an XML ODBC driver, you can set it up to access XML files just like any ODBC data source. Use the PERSIST embedded SQL statement to convert information to XML.

Parent topic: Using OpenESQL with ODBC
Related reference
PERSIST


JDBC

Use OpenESQL with the JDBC option to compile your JVM managed applications. This option:
  • Is invoked using the SQL(DBMAN=JDBC) compiler directive
  • Uses any of several JDBC drivers
  • Can connect to one JDBC Data Source using either a JDBC Connection String or a JDBC DataSource Object.
  • When connecting with a JDBC DataSource Object, enables you to connect to your Java data source for compilations with the SQL CHECK directive (this simulates OpenESQL DSNs with ODBC or ADO.NET)
  • Compiles applications to communicate with the OpenESQL JVM Managed Runtime
  • Enables maximum interoperability between different database systems
  • Provides support for pessimistic and optimistic (locking) concurrency control
  • Supports dynamic SQL using PREPARE, EXECUTE and EXECUTE IMMEDIATE statements and cursors that use prepared statements, but only with host variable lists in the EXECUTE and OPEN statements
  • Does not support disconnected or offline DataSets
  • JDBC Process
    Describes the recommended process to use for developing, building, and executing a JVM COBOL application for JDBC.
  • JDBC Resources
    Describes the resources needed by Visual COBOL to build and execute a JVM COBOL application for JDBC.
  • JNDI DataSource Objects
    Describes a JNDI DataSource object, and how to use them to connect to a database.
  • Database Connections
    Explains JDBC connection details with regard to connecting and sharing connections.
  • Using OpenESQL with JDBC
    Programming and compiling OpenESQL managed applications with JDBC.
Parent topic: OpenESQL
Related concepts
Programming for OpenESQL
Related reference
DBMAN


JDBC Process

We recommend the following process for developing, building, and executing a JVM COBOL application for JDBC:

  1. Assemble your JDBC resources
  2. Assemble application components
  3. Develop application code
  4. Add appropriate database connection code to your JDBC programs
  5. Build the project
  6. Configure the JVM runtime environment
  7. Run the application
Parent topic: JDBC
Related concepts
Configuring the JDBC Run-time Environment
Database Connections
Setting the OpenESQL Preprocessor and Compiler Directive Options


JDBC Resources

To build and execute JDBC applications, Visual COBOL must have access to a certain set of resources. The specific resources required vary depending on the type of database and type of application server used by the application.

Important: If you build your project using the SQL(CHECK) compiler directive, OpenESQL requires access to the same resources used when executing the application. In this case, before building the application, you must configure your JDBC environment for application execution.

Using SQL(CHECK) also requires that you use JNDI DataSource objects, either with Simple-JNDI, or JNDI services provided by a Java Application Server.

Recommendations

In the interest of keeping your JDBC resources organized and easily accessed, we offer the following recommendations:

Directory Structure
We recommend that you create a directory structure on a local or shared drive in which to store your JDBC project resources:
  1. Create a root directory for your JDBC resources. This directory is for storing JAR files and properties files. For example, /home/jdbcrsc.
  2. Create a subdirectory to the root directory in which to store data source files. For example, /home/jdbcrsc/DataSources.

Required Resources

The resources required to build and execute JDBC applications are:

JDBC Drivers
We recommend that you copy the appropriate driver file or files to the root directory you created for your JDBC resources. To see a list of currently supported drivers, see Additional Software Requirements on UNIX
JNDI Library
JNDI provides a way to define a database connection and make it accessible to multiple applications. The JNDI library file, usually a JAR file, contains the information required to connect to your JDBC database, including pointers to additional resources. JNDI requires its own configuration, which must be done before you can use the JNDI library.

You have several options with regard to JNDI. For example, each application server offers a JNDI implementation that you can use. However, for development and evaluation purposes, we recommend that you use a third-party JNDI server, Simple-JNDI. The Simple-JNDI package enables you to create and register JNDI DataSource objects, independent of your application server, for use with Visual COBOL. To use Simple-JNDI, follow the procedure presented in To install and configure Simple-JNDI.

JNDI DataSource Objects
A DataSource object is a properties file that contains the specifications required to connect to your database. To use a DataSource object, it must be registered on a JNDI server. For instructions on using Simple-JNDI to create and register a DataSource object, see To create a JNDI DataSource object. To see the contents of a variety of example DataSource objects, see Sample DataSource Object Files.
Parent topic: JDBC
Related concepts
Database Connections
JNDI DataSource Objects
Connect Using a JNDI DataSource Object
Related tasks
To install and configure Simple-JNDI
To create a JNDI DataSource object
Related reference
Sample DataSource Object Files
CHECK


JNDI DataSource Objects

A JNDI DataSource object is a file that contains the configuration details necessary to connect to a database. The DataSource object must be registered on a JNDI server, where it is identified using a JNDI name.

You can register your DataSource object directly on your application server via its JNDI service. The method used to do this varies from one application server to another.

As an alternative to directly registering DataSource objects on an application server, you can use the open-source Simple-JNDI package to create and register JNDI DataSource objects as Simple-JNDI data files. For development and evaluation purposes, we provide instructions for installing and using Simple-JNDI for this purpose. See To install and configure Simple-JNDI for details.

The components of a JNDI DataSource object are:

Type
The type of DataSource object. This is always set to javax.sql.DataSource.
Driver
The driver class.
URL
The URL to the driver location.
User
The user name required to connect to the database.
Password
The password required to connect to the database.

We recommend that you use a JNDI DataSource object to connect to your database; however, It is not required. Alternatively, you can specify a connection string directly in your application code or on the command line.

Parent topic: JDBC
Related concepts
JDBC Resources
Connect Using a JNDI DataSource Object
Related tasks
To install and configure Simple-JNDI
To create a JNDI DataSource object
Related reference
Sample DataSource Object Files
JDBC Driver Classes
JDBC URLs
DB


Database Connections

You can connect to your database by referencing a JDBC DataSource object in your connection string, or by including the connection information directly in the connection string. You can also share a database connection between Java and COBOL.

  • Connect Using a JNDI DataSource Object
  • Connect Using a JDBC Connection String
  • Sharing Database Connections Between Java and COBOL
Parent topic: JDBC
Related concepts
JDBC Resources
JDBC Process
Related reference
CONNECT


Connect Using a JNDI DataSource Object

You can connect to a JNDI DataSource object using the CONNECT embedded SQL statement, much the same as for ODBC connections:
EXEC SQL
  CONNECT TO DataSourceObject [USER userID.password]
END EXEC

If you have not specified a user ID and password within the DataSource object for a database connection that requires them, you can specify them as part of the CONNECT statement as indicated.

Parent topic: Database Connections
Related concepts
JNDI DataSource Objects
JDBC Resources
Related tasks
To create a JNDI DataSource object


Connect Using a JDBC Connection String

To connect without using a DataSource object, use the following embedded SQL syntax:
EXEC SQL
  CONNECT USING DRIVER=driverClass;URL=JDBC-URL;
END-EXEC

Where driverClass identifies the main class of the driver to be used for the connection, and JDBC-URL identifies the server and database, and may also include connection property values.

Parent topic: Database Connections
Related reference
JDBC Driver Classes
JDBC URLs


Sharing Database Connections Between Java and COBOL

COBOL and JDBC can use a common database connection. To achieve this, use a combination of EXEC SQL statements, depending on how the connection is opened.
When Java opens the connection
Connection guidelines
  1. Pass the connection object to COBOL.
  2. Use EXEC SQL BIND CONNECTION to establish the connection.
  3. When done using the connection, use EXEC SQL UNBIND CONNECTION if Java still requires access to it, or use EXEC SQL DISCONNECT if Java no longer requires access.
Example
Java code establishes a JDBC connection, and passes the connection object to the DoCOBOLSQL method of the COBOLSQL class, which binds to the connection, executes SQL, and then unbinds the connection, enabling Java to continue using the JDBC connection for further processing:
  • COBOLSQL tb = new COBOLSQL();
  • Context ctx = new InitialContext();
  • DataSource ds = (DataSource)ctx.lookup("mfdb");
  • Connection con = ds.getConnection("sa","password");
  • tb.DoCOBOLSQL(con);
  • ... (other JDBC access)
COBOL COBOLSQL class and DoCOBOLSQL method:
       class-id COBOLSQL public.
         working-storage section.
         method-id DoCOBOLSQL.
             local-storage section.
                exec sql include sqlca end-exec.
             linkage section.
             01  con         type java.sql.Connection.
             procedure division using by value con.
                exec sql bind connection to :con end-exec
                if sqlcode < 0
                    display "FAIL: Bind Connection " sqlcode
                    display sqlerrmc
                end-if
                exec sql … (other SQL) end-exec
                exec sql unbind connection end-exec

                goback.
         end method.
Note: Methods in the COBOL class are not limited as shown in this example. For instance, you could alternatively have a BIND method, a DoSQL method, and an UNBIND method.
When COBOL opens the connection
Connection guidelines
  1. Use EXEC SQL GET CONNECTION to get a connection object to pass to Java.
  2. When done using the connection, use EXEC SQL UNBIND CONNECTION if Java still requires access to it, or use EXEC SQL DISCONNECT if Java no longer requires access.
Example
JAVA code calls the DoCOBOLSQL method of the COBOLSQL class, which connects to the database, executes SQL, gets the connection and returns it to Java, then unbinds the connection, enabling Java to continue using the JDBC connection for further processing:
  • COBOLSQL tb = new COBOLSQL();
  • Connection con = tb.DoCOBOLSQL();
  • Statement stat = con.createStatement();
  • ResultSet r = stat.executeQuery("select RegionDescription from Region where RegionID = 1");
  • r.next();

COBOL COBOLSQL class and DoCOBOLSQL method:

       class-id COBOLSQL public.
         working-storage section.
         method-id DoCOBOLSQL.
             local-storage section.
                exec sql include sqlca end-exec.
             linkage section.
             01  con         type java.sql.Connection.
             procedure division returning con.
                EXEC SQL CONNECT TO :dbname USER :usr END-EXEC
                exec sql … (other SQL) end-exec
                exec sql get connection into :con end-exec
                exec sql unbind connection end-exec

                goback.
         end method.
Note: Methods in the COBOL class are not limited as shown in this example.
When Run-Unit is terminated
Within a run-unit, EXEC SQL UNBIND CONNECTION closes cursors but does not close the connection. However, if a run-unit terminates and UNBIND CONNECTION has not been called, OpenESQL closes both cursors and the connection.
Parent topic: Database Connections
Related reference
BIND CONNECTION
GET CONNECTION
UNBIND CONNECTION


Using OpenESQL with JDBC

When using the JDBC option, follow the programming and compiling guidelines provided for OpenESQL in general. In addition, the following topics provide information specific to working with JDBC:

  • Compiling JDBC Applications from the Command Line
  • Configuring the JDBC Run-time Environment
    Explains the environment configuration required to run JDBC applications.
  • JVM Host Variables in Managed Code
Parent topic: JDBC


Compiling JDBC Applications from the Command Line

To compile an OpenESQL application that uses OpenESQL for JDBC, you specify JVM COBOL using the -j command flag, and JDBC by setting the DBMAN SQL compiler directive option. For example:

cob -j myprog.cbl -C "SQL(DBMAN==JDBC)"

Note: If you also specify the SQL(CHECK) compiler directive, you must have your runtime environment configured to enable the compiler to access the database. See Configuring the JDBC Run-time Environment for details.
Parent topic: Using OpenESQL with JDBC
Related concepts
Sample DataSource Object Files
Configuring the JDBC Run-time Environment
Related reference
JVMGEN
Compile to JVM Byte Code (-j)


Configuring the JDBC Run-time Environment

Before you can execute your compiled JDBC applications, you must set up your environment to point to the required JDBC resources.
  • Add the appropriate JDBC driver file to your system's CLASSPATH environment variable.
  • If you are using Simple-JNDI to register JDBC DataSource objects, add your simple-jndi-version.jar and the jndi.properties to the CLASSPATH environment variable.
    Note: On the CLASSPATH, you can either specify the jndi.properties file in its original format, or as an alternative, you can compress it into a .zip archive and specify the .zip archive instead.
Parent topic: Using OpenESQL with JDBC
Related concepts
Compiling JDBC Applications from the Command Line
JDBC Process
Related reference
CHECK


JVM Host Variables in Managed Code

For your managed applications, OpenESQL provides the option of using traditional host variable declarations, and an option to use JVM data types as your host variable declarations. Use of JVM data types is made possible by the OpenESQL Managed Runtime, specified by setting the DBMAN directive option to JDBC.

When your managed application contains traditional host variable declarations using PIC clauses, this requires the OpenESQL Managed Runtime to read each PIC clause and convert it to the equivalent JVM type. However, by declaring your host variables using the JVM data types in place of the PIC clause, you get these advantages:
  • Improved performance - it is not necessary for the OpenESQL Managed Runtime to translate PIC clauses to JVM types, thereby greatly enhancing performance.
  • No size restrictions - JVM variables in managed applications are not restricted in size, whereas native COBOL applications have size restrictions on host variables, especially for applications that involve LOB data.
  • Improved application portability - the managed runtime simplifies the process of porting existing native EXEC SQL applications to JVM.
When coding your applications to use JVM host variables, keep in mind:
  • All JVM host variables must be defined at the 01 level or compiler errors result.
  • Syntax for common JVM data types can be defined with the short name. For example, System.String can be defined simply as:
    01 myName string.
  • Syntax for other JVM variables typically include a TYPE clause. For example:
    01 myDate type java.sql.Timestamp.
  • If a specific JVM type doesn't exist for an SQL data type provided by a vendor, you can use OBJECT as the host variable type. For example:
    01 myData object.
Note:
  • Only the OpenESQL preprocessor supports the use of JVM host variables. Currently, no DBMS vendors provide direct support for EXEC SQL syntax in JVM applications.
  • For complete information on declaring JVM host variables for the OpenESQL Managed Runtime, see the reference topics under SQL Data Types.

Example: Defining JVM host variables

  *> -------------------------------------------
       *> COBOL HOST VARIABLES FOR TABLE EMP
       *> -------------------------------------------
       01  EMP-EMPNO                          STRING.
       01  EMP-FIRSTNME                       STRING.
       01  EMP-MIDINIT                        STRING.
       01  EMP-LASTNAME                       STRING.
       01  EMP-WORKDEPT                       STRING.
       01  EMP-PHONENO                        STRING.
       01  EMP-HIREDATE                       type java.sql.Timestamp.
       01  EMP-JOB                            STRING.
       01  EMP-EDLEVEL                        BINARY-SHORT.
       01  EMP-SEX                            STRING.
       01  EMP-BIRTHDATE                      type java.sql.Timestamp.
       01  EMP-SALARY                         DECIMAL.
       01  EMP-BONUS                          DECIMAL.
       01  EMP-COMM                           DECIMAL.

EXEC SQL
 SELECT
        A.FIRSTNME
       ,A.LASTNAME
       ,A.HIREDATE
       ,A.SALARY
       ,A.EMPNO
INTO
        :EMP-FIRSTNME
       ,:EMP-LASTNAME
       ,:EMP-HIREDATE:EMP-HIREDATE-NULL
       ,:EMP-SALARY:EMP-SALARY-NULL
       ,:EMP-EMPNO
   FROM HCOSQL.EMP A
  WHERE (A.EMPNO = :EMP-EMPNO)
END-EXEC
Parent topic: Using OpenESQL with JDBC
Related concepts
Host Variables
Related reference
SQL Data Types


DB2

  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for applications using the DB2 ECM, along with a description of each of these applications.
  • DB2 External Compiler Module
    Describes how you can access a DB2 database from a COBOL program that contains embedded SQL statements.
  • COBOL DB2 Stored Procedures
Parent topic: Database Access
Related concepts
Database Access Preprocessors
Compiling SQL Applications


Demonstration Applications

Visual COBOL provides a number of demonstration applications or programs for the DB2 ECM.

A number of DB2 ECM sample programs are supplied. The source files for these samples are located in $COBDIR/demo/db2.

Each sample program comes with a progName.txt file to explain how to use the program.

db2test1.cbl
Shows the syntax variants for connecting to and disconnecting from a DB2 database using Type 1 CONNECTs that IBM DB2 LUW supports.
db2test2.cbl
A simple example of using both singleton SELECT and cursor-based FETCH statements with IBM DB2 LUW.
dynamic.cbl
A simple example of using dynamic SQL with IBM DB2 LUW, performing a variety of SQL operations. If this program was written as a STATIC SQL program, it would have to be broken apart into two programs, since static SQL requires that the table exists beforehand or it would cause a Compiler error.
lobdemo.cbl
Shows how LOB LOCATOR and VALUES functions to retrieve LOB data from DB2 LUW.
whenever.cbl
Shows how to use EXEC SQL WHENEVER statements for error handling, and the DB2(MSGAREA) Compiler directive to specify a COBOL variable for retrieving error message text larger than the 70 bytes provided in SQLERRMC.
Parent topic: DB2


DB2 External Compiler Module

The DB2 External Compiler Module (ECM) is an integrated preprocessor that converts embedded SQL statements into the appropriate calls to DB2 database services. It is designed to work closely with the Micro Focus COBOL compiler.

  • Compound SQL
  • Extensions to Embedded SQL Support
  • Compiling
  • Error Codes
  • Building Applications
  • Binding
Parent topic: DB2


Compound SQL

Compound SQL is supported, including the extended form now available in DB2. Note that incomplete Compound SQL statements are detected by the DB2 ECM and cause an error to be produced. However, DB2 may not always recover from this condition and valid SQL statements later in the program source may generate additional errors.

Parent topic: DB2 External Compiler Module


Extensions to Embedded SQL Support

This section discusses Micro Focus extensions to the embedded SQL support.

  • The INCLUDE Statement
  • The DECLARE Statement
  • Qualified Host Variables
  • Host Variable Groups and Indicator Arrays
  • The NOT Operator (¬)
  • The Concat Operator (|)
  • SQL Communications Area
  • Support for Object Oriented COBOL Syntax
  • Support for Nested COBOL Programs
    Describes support for nested COBOL programs, including information on generating single and multiple packages.
Parent topic: DB2 External Compiler Module


The INCLUDE Statement

Statements of the form:

exec sql
   include filename
end-exec

are permitted and are processed in exactly the same way as the statement:

copy filename

The included file can contain any COBOL statements that a copybook can, including further EXEC SQL statements.

On UNIX, the filename is converted to lower case for the special case of sqlca or sqlda, no matter how it is specified.

Parent topic: Extensions to Embedded SQL Support


The DECLARE Statement

Statements of the form:

exec sql
   DECLARE table-name TABLE
   ...
end-exec

are permitted and are treated as comments.

Statements of the form:

exec sql
   DECLARE host-var FOR BIT DATA
   ...
end-exec

instruct the DB2 ECM to not do ASCII/EBCIDIC translation on the specified host variable.

Parent topic: Extensions to Embedded SQL Support


Qualified Host Variables

Host variables can be qualified using DB2 for MVS compatible syntax.

For example, suppose you have defined some host variables as follows:

01 block-1.
   03 hostvar pic s9(4) comp-5.
01 block-2.
   03 hostvar pic s9(4) comp-5.

You can qualify which instance of hostvar to use with syntax of the form:

exec sql
   fetch s2 into :block-1.hostvar
end-exec
Parent topic: Extensions to Embedded SQL Support


Host Variable Groups and Indicator Arrays

When host variables are declared in a group item, an SQL statement which needs to refer to each of these variables in turn can be abbreviated by referring instead to the group-name. If you need to associate indicator variables with these host variables, define a table of indicator variables with as many instances as there are host variables, and reference this table (the item with the OCCURS clause, not a group item containing it).

For example, suppose you have defined some host variables as follows:

01  host-structure.
   03 sumh           pic s9(9) comp-5.
   03 avgh           pic s9(9) comp-5.
   03 minh           pic s9(9) comp-5.
   03 maxh           pic s9(9) comp-5.
   03 varchar.
      49 varchar-l   pic s9(4) comp.
      49 varchar-d   pic x(1000).
 01  indicator-table.
     03 indic          pic s9(4) comp-5 occurs 4.
 01  redefines indicator-table.
     03 indic1         pic s9(4) comp-5.
     03 indic2         pic s9(4) comp-5.
     03 indic3         pic s9(4) comp-5.
     03 indic4         pic s9(4) comp-5.

In such an example, the procedural statement:

exec sql fetch s3 into
  :host-structure:indic
end-exec

is equivalent to:

exec sql fetch s3 into
  :sumh:indic1, :avgh:indic2, :minh:indic3,
  :maxh:indic4, :varchar
end-exec

The four declared indicator variables are allocated to the first four host variables. If five or more had been declared, all five host variables would have an associated indicator variable.

The table of indicator variables is redefined only to show the equivalent SQL statement (subscripting is not allowed in SQL statements). The redefinition can be omitted and the COBOL program can refer to the indicator variables using subscripting, if desired.

Parent topic: Extensions to Embedded SQL Support


The NOT Operator (¬)

DB2 allows the operators ¬=, ¬> and ¬<. These are mapped to <>, <= and >=. The character representation of the NOT operator varies from system to system, so you can define it using the NOT option of the DB2 Compiler directive.

Parent topic: Extensions to Embedded SQL Support


The Concat Operator (|)

In some countries the symbol used for the concat operator is not the ASCII character (|). The DB2 ECM enables you to specify a different ASCII character for the concat operator via the CONCAT option of the DB2 Compiler directive.

Parent topic: Extensions to Embedded SQL Support


SQL Communications Area

After any SQL statement has executed, important information is returned to the program in an area called the SQL Communications Area (SQLCA). The SQL Communications Area is usually included in your program using the statement:

exec sql include sqlca end-exec

If you do not include this statement, the DB2 ECM automatically allocates an area, but this area is not addressable in your program. However, if you declare either or both of SQLCODE and SQLSTATE, the DB2 ECM generates code to copy the corresponding fields in the SQLCA area to the user-defined fields after each EXEC SQL statement.

Tip: For ANSI compatibility, we recommend you define the entire SQLCA.

After any non-zero condition in SQLCODE, the DB2 ECM updates the contents of the MFSQLMESSAGETEXT data item with a description of the exception condition, provided it has been defined. If it is, it must be declared as a character data item (PIC X(n), where n can be any legal value; if the message does not fit into the data item it is truncated).

None of SQLCA, SQLCODE, SQLSTATE and MFSQLMESSAGETEXT is required to be declared as host variables.

Parent topic: Extensions to Embedded SQL Support


Support for Object Oriented COBOL Syntax

The DB2 ECM has been enhanced to work with Object Oriented COBOL syntax (OO programs). There are, however, a couple of restrictions that you should be aware of:

  • The INIT option of the DB2 Compiler directive is disabled if used within an OO program. Therefore, to obtain the functionality of the DB2(INIT=PROT) Compiler directive, include a non-OO module and compile it with this directive.
  • If you use an EXEC SQL WHENEVER statement within a METHOD, any additional METHODs coded in the same CLASS that have SQL statements in them need to have the section that is referenced in the preceding WHENEVER statement defined. Not doing this results in a compilation error indicating that the section has not been defined. You can get around this restriction by defining another EXEC SQL WHENEVER statement.
Parent topic: Extensions to Embedded SQL Support


Support for Nested COBOL Programs

The DB2 ECM supports nested COBOL programs, but in some cases requires specification of an additional DB2 compiler directive option.

For non-nested COBOL programs, the DB2 ECM generates DB2 interface code in the form of a BND file that is then bound into a DB2 LUW package. The base name of both the BND and the package file defaults to the base name of the source file. You can override the base name using the PACKAGE directive to specify an alternative name. See PACKAGE for details.

For nested programs, you can use one of the following DB2 ECM directives to define how DB2 interface code is generated for a single source file. These directives are mutually exclusive, meaning you can specify only one at a time for any given source file:

SINGLE_PACKAGE
This is the default behavior. For all programs defined in the source file, the DB2 ECM creates a single BND file; thus a single package is bound and stored in your DB2 LUW database. Because they are all bound into the same DB2 LUW package, all programs in the package share the same BIND timestamp token(s) as the main program. The naming conventions of the BND and package files follow the same rules as for non-nested programs. See SINGLE_PACKAGE for details on using this directive.
Important: Cursors that are shared among the programs in a given package must be uniquely named and defined within that package.
MULTI_PACKAGE
When specified, overrides the default SINGLE_PACKAGE behavior. For each program defined in the source file, the DB2 ECM creates a distinct BND file, each with its own BIND timestamp token(s), and a corresponding package.

The names generated for BND files and packages can differ depending on whether or not you also specify the PACKAGE directive with a parameter in addition to MULTI_PACKAGE.

Example 1: Compile DEMO.cbl with MULTI_PACKAGE

The names of generated BND and package files are based on the program ID of each nested program, and the BND file and package names for the main program are based on the base name of the source file as follows:

Program ID | Resulting BND file name | Resulting PACKAGE name
MAIN | DEMO | DEMO
SUB1 | SUB1 | SUB1
SUB2 | SUB2 | SUB2

Example 2: Compile DEMO.cbl with MULTI_PACKAGE and PACKAGE=TEST

The BND file and package names are modified to include the package name as follows:

Program ID | Resulting BND file name | Resulting PACKAGE name
MAIN | DEMO | TEST
SUB1 | TESTSUB1 | TESTSUB1
SUB2 | TESTSUB2 | TESTSUB2

See MULTI_PACKAGE for additional details on using this directive.

IGNORE-NESTED
If the main program in a source file contains EXEC SQL statements, or just one nested program contains EXEC SQL statements, you can use the IGNORE-NESTED directive to suppress the generation of DB2 interface code for the other programs in the source file.

If more than one nested program using EXEC SQL statements exists in the source file, you can specify IGNORE-NESTED with a program ID that, when encountered by the DB2 ECM, triggers the generation of DB2 interface code for that program only. The base name of the generated BND and package files is the same as the specified program ID.

If more than one nested program using EXEC SQL statements exists in the source file, and you specify IGNORE-NESTED without a program ID, the DB2 ECM locates the program with a program ID that matches the base name of the source file. In this case, The base name of the generated BND and package files is the same as base name of the source file.

See IGNORE-NESTED for details on using this directive.

Note: You can also specify the PACKAGE directive with a parameter to override the base names for the BND and package files.
Note: Each of these directives has a synonym that provides identical functionality and can be used as a substitute:
Directive | Synonym
PACKAGE | ACCESS
SINGLE_PACKAGE | MULTI-NESTED
MULTI_PACKAGE | ALLOW-NESTED
Parent topic: Extensions to Embedded SQL Support
Related reference
IGNORE-NESTED
MULTI_PACKAGE
SINGLE_PACKAGE
ACCESS
PACKAGE


Compiling

Compiling your SQL program with the COBOL Compiler is logically equivalent to two steps: precompiling to change SQL lines into host language statements, and then compiling the resulting source. These two steps actually occur in a single process, which is performed by the COBOL Compiler in conjunction with the DB2 ECM.

Before you attempt to compile any SQL program, please complete these tasks to ensure you can connect to the database:

  • Install DB2 LUW Data Server Client must be installed. Failure to install the data server client could result in an error.
  • Start DB2 using db2start.
  • If using DB2 LUW as a remote database server, start security services.
  • Specify a valid database name by setting the DB2(DB=databaseName) compiler directive

Also before compiling, ensure that you log into DB2 with the appropriate authorization. You must have one of the following:

  • sysadm or dbadm authority
  • BINDADD privilege if a package does not exist, plus one of the following:
    • IMPLICIT_SCHEMA authority on database if the schema name of the package does not exist
    • CREATIN privilege on the schema if the schema name of the package exists
    • ALTERIN privilege on the schema if the package exists
    • BIND privilege on the package if it exists

Individual database users who compile must have the table privileges required to compile any static SQL statement that appears in the code. Privileges granted to groups are not used for authorization checking of static SQL statements. If a program fails to compile because of lack of authority on an SQL object, please contact your DB2 Database Administrator.

If you are using the API calls introduced for DB2 LUW version 7.1, the DB2 ECM calls an IBM module to validate them. If the DB2 ECM finds an error in the directive syntax, it displays a -104 SQLCODE error message:

Programs containing embedded SQL are compiled using the DB2 Compiler directive. Additional action is required when creating an executable (binary) file that requires linking to additional modules (see Linking).

You can debug programs containing SQL code just as you would any other program, and can examine host variables inside SQL statements as regular COBOL data items.

Note: If you attempt to compile but receive a COBDB0006 error message, see the topic COBDB0006 Required DB software token could not be found.
  • Setting the DB2 ECM Preprocessor and Compiler Directive Options
    Describes the options available for setting the DB2 ECM preprocessor and its applicable compiler directive options.
  • DB2 Compiler Directive
Parent topic: DB2 External Compiler Module


Setting the DB2 ECM Preprocessor and Compiler Directive Options

We provide several options that enable you to specify the DB2 ECM preprocessor and its applicable compiler directive options:

In a Directives File
You can include DB2 ECM 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.
On the Command Line
Use the DB2 compiler directive, followed by the DB option to specify the database name, followed by additional options:

DB2[(DB==dbName [DB2dirOpts])]

Where dbName is the name of your DB2 database, and DB2dirOpts is one or more additional directive options.

Note: If you do not specify the DB option, the compiler uses the database specified as the value of the DB2DBDFT environment variable.
Embedded in the Program
You can also specify the DB2 ECM preprocessor and compiler directive options on the program level by embedding a $SET statement into the program itself on the first line of the program:
$SET DB2[(DB=dbName [DB2dirOpts])]

Where dbName is the name of your DB2 database, and DB2dirOpts is one or more additional directive options.

Important:
  • Use this method only when the program requires a preprocessor different from other programs in an application.
  • If you do not specify the DB option, the compiler uses the database specified as the value of the DB2DBDFT environment variable.
Parent topic: Compiling
Related concepts
Specifying an SQL Preprocessor and Compiler Directive Options
Related reference
System-wide Directives File, cobol.dir
DB2 Compiler Directive Options
User Directives File


DB2 Compiler Directive

Use the DB2 compiler directive to invoke the DB2 ECM preprocessor.

Compiler directives have a default value which is used if no other value is specified. This also applies to all existing DB2 directive options. Many of the options are passed straight to DB2 at compilation time and the Compiler default is used when no other value is specified. In these cases, however, the suitability of, and default values for these options depend on the DB2 configuration, notably whether DB2 is configured to connect to a DRDA server via DDCS. Because of this, the default Compiler setting of these options is "not set". This means that no value is passed to DB2 and the default value (if applicable) is determined by DB2 itself. Consult your IBM DB2 reference documentation for these values.

Note: This list assumes that you are using DB2 LUW V9.7 or later. Some directives are only valid when using DB2 Connect with DB2 LUW. If you are using a different version of DB2 LUW, consult your IBM DB2 reference documentation under PRECOMPILE or BIND to see if the DB2 directive option is supported locally (DB2) or only by DB2 Connect (DRDA). If you are in any doubt, you can specify the directive and attempt to compile the program. If it is not supported, an error message is issued.
Parent topic: Compiling
Related reference
DB2 Compiler Directive Options


Error Codes

Error conditions are returned at compilation time as a number and explanation. Further details of these messages are given in the documentation supplied with your database system. Messages referencing host variables might be slightly modified if you are using an older version of DB2 LUW. Hyphens are shown as underscores (_), and there are up to three additional characters which can be ignored at the end of the name. These changes are side effects of modifications made by the DB2 ECM to the SQL code. For more information see the entry for the QUALFIX option in the section DB2 Compiler Directive Options

Error conditions at run time are indicated by non-zero values in SQLCODE. Explanatory text is placed in the MFSQLMESSAGETEXT data item if defined; see the section SQL Communications Area for further details about this data item.

For example:

801-S
** External Compiler Module message
** SQ0100 SQL1032N  No start database manager command was
**                  issued.
** SQLSTATE=57019
Parent topic: DB2 External Compiler Module
Related concepts
SQL Communications Area (SQLCA)
Related reference
QUALFIX
DB2 Compiler Directive Options


Building Applications

This section describes how to build:

  • Stand-alone DB2 applications, that is, applications that access DB2 databases directly
  • Client DB2 applications and their DB2 stored procedures. Client applications use DB2 stored procedures to access DB2 databases
  • Stand-alone DB2 Applications
  • Client DB2 Applications and Stored Procedures
Parent topic: DB2 External Compiler Module


Stand-alone DB2 Applications

If your DB2 application is to run as intermediate code or generated code you do not need to link.

In order to create a DB2 application as either an executable or a callable shared object, you must build it thus for executable:

cob -xvt db2prog.cbl -N nolitlink

or for callable shared object:

cob -zvt db2prog.cbl -N nolitlink
Parent topic: Building Applications


Client DB2 Applications and Stored Procedures

For information on how to create COBOL stored procedures for DB2 Database for Linux, UNIX, and Windows (LUW), see IBM's documentation on Developing User-defined Routines (SQL and External) and also their SQL reference material.

Parent topic: Building Applications


Binding

By default, using the database specified by the DB compiler directive option, the DB2 ECM preprocessor automatically binds your program during the compilation process, creating and storing in your DB2 database a DB2 package required for successful execution.

However, depending on your environment, this straight-forward, default behavior might not match your requirements. For instance, you might want to create DBRMs (.bnd files) during compilation, and bind the DBRMs later using the DB2 LUW BIND command against your DB2 LUW databases. For this and other related scenarios, we provide several DBRM options.

DBRM Options

We provide one option that enables you to specify an alternative name for the created DBRM file, and three options that enable you to redirect DBRM files to an alternative directory. If you specify more than one output option, the DB2 ECM uses the option that is determined to take precedence.

BIND (or BINDFILE) and BINDDIR compiler directive options
BIND (or BINDFILE)
In addition to instructing the DB2 ECM to create a DBRM file, you can also use BIND to specify an alternative filename for the DBRM file. The default DBRM filename is programname.bnd.

BIND also enables you to redirect the created DBRM file to an alternative directory. The default is the current directory unless you have also used one or both of the BINDDIR and HCOBND options. When you specify a path using BIND, it takes precedence over that specified by all other output options, if set.

Note: When compiling a program with the ACCESS compiler directive option (default), the DBRM is bound into the connected database, where it creates the SQL package required for execution. When compiling with NOACCESS, no binding takes place.

You can set BIND on the command line. For details, see the BIND DB2 compiler directive option topic.

BINDDIR
Use BINDDIR to specify an alternative output directory for the created DBRM file. The path specified by BINDDIR takes priority over that specified by the HCOBND environment variable, but is overridden if a path is specified by BIND (or BINDFILE).

You can set BINDDIR on the command line. For details, see the BINDDIR DB2 compiler directive option topic.

HCOBND environment variable
Attention: This option is deprecated, and provided for backward compatibility only.

Set the HCOBND environment variable to specify an alternative output directory for created DBRM files. This option has the lowest priority, and is used only when no alternative path is specified by either the BIND or the BINDDIR compiler directive options.

See HCOBIND environment variable for details.

Parent topic: DB2 External Compiler Module
Related reference
BIND
BINDDIR
HCOBND environment variable (deprecated)
ACCESS


COBOL DB2 Stored Procedures

DB2 LUW allows embedded SQL calls to be executed as stored procedures. Stored procedures are routines executed directly by a DB2 LUW Server instance, rather than indirectly via a call to a routine from within a client application. The benefits of using DB2 stored procedures over SQL calls include enhanced modularity, security, and performance.

Stored procedures are stored on a local or remote DB2 LUW Server. Local DB2 LUW Server applications or remote DRDA applications can use the SQL statement CALL to invoke a stored procedure.

Note:
  • If you are running your stored procedure on DB2 for OS/390, through the DB2 Connect product, see your IBM DB2 documentation for other steps necessary to run the stored procedure.
  • For complete information on writing stored procedures and setting options for DB2 Database for Linux, UNIX, and Windows (LUW), see IBM's documentation on Developing User-defined Routines (SQL and External) and also their SQL reference material.
  • Working with Stored Procedures
  • Writing and Preparing Stored Procedures
  • Writing and Preparing Applications to Use Stored Procedures
  • Defining Stored Procedures under DB2 LUW
  • Compiling and Linking Stored Procedures under DB2 LUW
  • Testing Stored Procedures under DB2 LUW
Parent topic: DB2


Working with Stored Procedures

Important: Any machine on which a COBOL stored procedure is executed must have a Micro Focus Enterprise Server or COBOL Server product installed and licensed. Contact SupportLine for more information.

To get a stored procedure up and running:

  1. To set up the initial environment, see Configuring the Environment for Developing RDBMS Applications on UNIX
  2. Code and prepare a stored procedure. See the topic Writing and Preparing Stored Procedures for instructions.
  3. Code and prepare an application that calls the stored procedure. An SQL statement, CALL, in that application must use the same parameter list and linkage convention as the stored procedure that it invokes. For instructions, see Writing and Preparing Applications to Use Stored Procedures.
  4. Define your stored procedure to the DB2 LUW Server by issuing a CREATE PROCEDURE command, which places a row in the appropriate system table(s). See Defining Stored Procedures under DB2 LUW for details.
  5. Compile and link your stored procedure. See Compiling and Linking Stored Procedures under DB2 LUW for details.
  6. Test your stored procedure. See Testing Stored Procedures under DB2 LUW for details.
Parent topic: COBOL DB2 Stored Procedures
Related concepts
Writing and Preparing Applications to Use Stored Procedures
Defining Stored Procedures under DB2 LUW
Compiling and Linking Stored Procedures under DB2 LUW
Testing Stored Procedures under DB2 LUW


Writing and Preparing Stored Procedures

A stored procedure is an application program that runs in the DB2 LUW Server's address space. It can contain most statements that an application program normally contains. It can consist of more than one program. Your stored procedure can call other programs as well as nested stored procedures but there are restrictions.

The application program that invokes the stored procedure can be in any language that supports SQL statements. You can write a stored procedure using many languages such as C, Java, COBOL or now SQL Procedure Language which is consistent with the Persistent Stored Module definition of the ANSI SQL99 standard.

The store procedure can be written in one language, for example Java, with the client written in another language, for example COBOL. When the languages differ, DB2 transparently passes the values between the client and the stored procedure so each program gets the values in the expected format defined by the CREATE PROCEDURE statement.

  • Preparing Stored Procedures
  • How an Application Works With a Stored Procedure
Parent topic: COBOL DB2 Stored Procedures
Related concepts
Writing and Preparing Applications to Use Stored Procedures


Preparing Stored Procedures

The following are high level tasks that must be completed before a stored procedure can be run on a DB2 LUW Server:

  1. Prepare the application according to your embedded SQL documentation for creating stored procedure.
  2. Define the stored procedure to the DB2 LUW Server. See Defining Stored Procedures under DB2 LUW.
  3. Place the stored procedure module on the DB2 LUW Server machine in a location specified in the CREATE PROCEDURE statement. If not specified, the default location is the function subdirectory under sqllib in the home directory of your DB2 LUW instance.
Note: IBM provides specific documentation on preparing stored procedures. Look in your IBM documentation for information on creating external routines and developing user-defined routines.
Parent topic: Writing and Preparing Stored Procedures
Related concepts
Defining Stored Procedures under DB2 LUW


How an Application Works With a Stored Procedure

A typical stored procedure contains two or more SQL statements, and some manipulative or logical processing. In this example, your application, CALLSTPR, runs on a workstation client and calls a stored procedure, GETEMPSVR. The following process occurs:

  1. The workstation application establishes a connection to the DB2 LUW Server.
  2. The SQL statement CALL tells the DB2 LUW Server that the application is going to run the stored procedure, GETEMPSVR. The calling application provides the necessary parameters.
  3. The DB2 LUW Server searches the system tables for rows associated with stored procedure GETEMPSVR.
  4. The DB2 LUW Server passes information about the request to the stored procedure.
  5. The stored procedure executes SQL statements.
  6. The stored procedure assigns values to the output parameters and then exits.
  7. Control returns to the calling application, which receives the output parameters.

The application can call more stored procedures or it can execute more SQL statements. The application designer determines whether to COMMIT work in the stored procedure that runs on the server, or in the client as a single transaction.

Parent topic: Writing and Preparing Stored Procedures


Writing and Preparing Applications to Use Stored Procedures

To invoke a stored procedure and to pass a list of parameters to the procedure, use the SQL statement CALL. Your application program can call several stored procedures.

After connecting to its server, an application can mix calls to stored procedures with SQL statements sent to the server.

  • Executing the SQL Statement CALL
  • Parameter Conventions
  • Using Indicator Variables to Speed Processing
  • Declaring Data Types for Passed Parameters
  • Limitations
Parent topic: COBOL DB2 Stored Procedures
Related concepts
Working with Stored Procedures
Writing and Preparing Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application.

Example 1

To call the stored procedure described in How an Application Works with a Stored Procedure, your application might use this statement:

EXEC SQL
 CALL GETEMPSVR (:V1, :V2)
END-EXEC

If you use host variables in the CALL statement, you must declare them before using them.

Example 2

The example above is based on the assumption that none of the input parameters can have null values. To allow null values, code a statement like this:

EXEC SQL
 CALL GETEMPSVR (:V1 :IV1, :V2 :IV2)
END-EXEC

where :IV1 and :IV2 are indicator variables for the parameters.

Example 3

To pass integer or character string constants or the null value to the stored procedure, code a statement like this:

EXEC SQL
 CALL GETEMPSVR (2, NULL)
END-EXEC

Example 4

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

Example 5

Assume that the stored procedure name is GETEMPSVR. The host variable PROCNAME is a character variable of length 254 or less that contains the value GETEMPSVR. 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 GETEMPSVR USING DESCRIPTOR :ADDVALS
END-EXEC

where ADDVALS is the name of an SQLDA.

Example 6

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: Writing and Preparing Applications to Use Stored Procedures


Parameter Conventions

For detailed information on DB2 LUW parameter conventions, see the IBM DB2 LUW documentation for external routine parameter styles.

Parent topic: Writing and Preparing Applications to Use Stored Procedures


Using Indicator Variables to Speed Processing

If any of your output parameters require a lot of storage, do not pass the entire storage areas to your stored procedure, but declare an indicator variable for every large output parameter in your SQL statement CALL. Indicator variables are used in the calling program to pass only a two-byte area to the stored procedure and to receive the entire area from the stored procedure.

Note: If you are using the 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)  END-EXEC
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Declaring Data Types for Passed Parameters

A stored procedure must declare each parameter passed to it. In addition, the DATA TYPE declared in the declaration must be valid for the data source being used and must use a compatible host variable data type when calling the stored procedure. For more information on data types, see SQL Data Types.

For example:

CREATE PROCEDURE GETEMPSVR
 (IN  EMPNO CHAR(6),
  INOUT SQLCD    INT ,
  OUT FIRSTNME CHAR(12),
  OUT LASTNAME CHAR(12),
  OUT HIREDATE CHAR(10),
  OUT SALARY   DEC(9,2) )
  LANGUAGE COBOL
  EXTERNAL NAME 'GETEMPSVR!GETEMPSVR'
  PARAMETER STYLE DB2SQL;
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Limitations

IBM has not implemented the same support for all SQL syntax related to stored procedures in every supported language. For example, you cannot create COBOL stored procedures that use result sets or the EXEC SQL syntax that supports that functionality with the workstation version of DB2 LUW.

There is no support for structure, array, or vector parameters using the DB2 native precompiler. However, there is much more flexibility when using the OpenESQL preprocessor and an ODBC connection.

The following embedded SQL statements are not allowed in Micro Focus stored procedures on any platform:
  • CONNECT
  • DISCONNECT
  • SET CONNECTION
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Defining Stored Procedures under DB2 LUW

A stored procedure is unusable until it is defined. Use the CREATE PROCEDURE command to do this. You can either use the DB2 command prompt or place the command in a program and compile and run it. If you use the DB2 command prompt, you first connect to the DB2 LUW Server where the stored procedure will be executed.

For example:

C:> db2 connect to sample

You can type in the command at the DB2 command prompt making sure you include continuation characters and command delimiters, or you can place the CREATE PROCEDURE in an ANSI text file. For example, if we placed the previous command in text file creproc.sql, the command that you would enter would be:

C:> db2 -td\; -vf creproc.sql

where:

  • the -td option indicates the next character is the delimiter to end the command. In our example, it is a semicolon (;).
  • the -vf option indicates that the next token is the file to process that contains the SQL command script.
  • The backslash is required so that the shell does not interpret the semi-colon.

The create procedure statement must uniquely identify a stored procedure. If you want to change the stored procedure to either add or drop parameters or change functionality, you must use the DROP PROCEDURE command and then re-add it with the CREATE PROCEDURE command.

This example includes a CREATE PROCEDURE command identifying a unique stored procedure in a text file (which would be named creproc.sql).

DROP PROCEDURE GETPRML;
CREATE PROCEDURE GETPRML
  (IN PROCNM CHAR(18)
  ,IN SCHEMA CHAR(8)
  ,OUT OUTCODE INTEGER
  ,OUT PARMLST VARCHAR(30)
  )
    DYNAMIC RESULT SETS 0
    LANGUAGE COBOL
    PARAMETER STYLE GENERAL
    NO DBINFO
    FENCED
    NOT THREADSAFE
    READS SQL DATA
    PROGRAM TYPE SUB
    EXTERNAL NAME "GETPRML!GETPRML"  ;

When DB2 was originally developed, it did not support the CREATE PROCEDURE function, and it is possible to write COBOL stored procedures without doing a CREATE PROCEDURE. Examples of this method and the parmlist that is required are included in the DB2 LUW Application Development Client.

Parent topic: COBOL DB2 Stored Procedures
Related concepts
Working with Stored Procedures
Preparing Stored Procedures


Compiling and Linking Stored Procedures under DB2 LUW

To compile and link a COBOL stored procedure using DB2 LUW:

  1. Compile and link the stored procedure as specified for your platform in the Building COBOL routines topic of the IBM DB2 LUW documentation.
  2. Copy the stored procedure object to the sqllib/function directory of your DB2 Instance.
Attention: By default, after calling a stored procedure, DB2 LUW does not unload it until DB2 LUW is stopped. To avoid problems with copying the file, you can do one of the following if you are not in a production environment:
  • From a command prompt with DB2 administrator privileges:
    1. Execute db2stop.
    2. Copy the stored procedure binary file.
    3. Execute db2start.
  • From a command prompt configured for the DB2 LUW environment, execute:

    db2 update dbm cfg using KEEPFENCED NO

    Warning: Do not execute the db2 update command in a production environment. Doing so results in significant performance degradation. Refer to your IBM documentation for more information on this command.
Parent topic: COBOL DB2 Stored Procedures
Related concepts
Working with Stored Procedures


Testing Stored Procedures under DB2 LUW

In lieu of coding test clients to test DB2 LUW stored procedures in COBOL, we offer the following options that do not require code:

  • If you have the IBM Data Studio software installed, use it to execute the stored procedure, manually providing required parameter values.
  • At a DB2 command prompt, connect to the database, then call the stored procedure as follows:
    C:> db2 call stored-procedure-name (parm1[, parm2…])

    For example:

    C:> db2 connect to Sample
C:> db2 call GETPRML ('TEST', 'TEST', 0, 'TEST')
    Note: If the sole required parameter is OUTPUT, represent it as a question mark (?).
Parent topic: COBOL DB2 Stored Procedures
Related concepts
Working with Stored Procedures


COBSQL

You can use COBSQL to access the SQL functions offered by the Oracle Database Management Systems (DBMS) by embedding SQL statements within your COBOL program in the form:

EXEC SQL
   SQL statement
END-EXEC

and then using the Oracle precompiler to process the embedded SQL before passing the program to the COBOL Compiler. The database precompiler replaces embedded SQL statements with the appropriate calls to database services. Other additions are made to the source code to bind COBOL host variables to the SQL variable names known to the database system.

The advantage of embedding SQL in this way is that you do not need to know the format of individual database routine calls. The disadvantage is that the source code that you see when you debug your program is that output by the precompiler and not the original embedded SQL. You can overcome this disadvantage by using COBSQL.

COBSQL provides an integrated interface between Micro Focus COBOL and the third-party standalone precompiler, enabling you to debug a program containing EXEC SQL statements and display your original source code rather than the code produced by the precompiler.

Note:
  • You should only use COBSQL if you are already using it with an earlier version of a Micro Focus COBOL product and want to migrate your application to this system. For any other type of embedded SQL development, we recommend that you use OpenESQL.
  • You cannot use COBSQL with programs that have been compiled with the Compiler directive SOURCEFORMAT(VARIABLE) unless you are using Pro*COBOL. Pro*COBOL supports both SOURCEFORMAT(TERMINAL) and SOURCEFORMAT(VARIABLE). Otherwise, you must use OpenESQL if your programs are free format.
Important: This note applies to UNIX environments (remote development) only.

To access a DBMS from COBOL under UNIX, the COBOL run-time system needs to be aware of the API routines used by the DBMS. A database vendor might provide a script that creates either:

  • An executable run-time system, consisting of the COBOL run-time system and DBMS routines
  • A callable shared object of DBMS routines that can be located by the COBOL run-time system at run time

The script contains a cob command, and you can control the effect of the script by amending the options to the cob command. See cob (cob32 or cob64) Command for more information.

  • Setting the COBSQL Preprocessor and Compiler Directive Options
  • Using the CP Preprocessor to Expand Copybooks
  • Troubleshooting
Parent topic: Database Access
Related concepts
Database Access Preprocessors
Compiling SQL Applications
Creating Debug Files
Related reference
SOURCEFORMAT
cob (cob32 or cob64) Command


Setting the COBSQL Preprocessor and Compiler Directive Options

You can specify the COBSQL preprocessor and its directives using any of the following methods:
Note: Adding the Oracle Pro*COBOL (COBSQL) preprocessor to the file or project property page automatically adds a read-only entry to the top of the preprocessors list in the property page. If you have multiple preprocessors in the preprocessors list, you can change the sequence of execution by moving preprocessors up and down the list. See section Additional Preprocessors for more information.
In your Visual COBOL File Properties
As a default, files in your project inherit the settings specified at project level. To specify the COBSQL preprocessor for an individual file in your project that differs from the SQL preprocessor settings at project level:
On the Command Line
Use this method when compiling from a Visual COBOL command prompt. See PREPROCESS(cobsql) and COBSQL Compiler Directives for details.
In a Directives File
You can include COBSQL directives in the cobsql.dir file, the cobol.dir system-wide directives file, or a user directives file. For COBSQL applications, we recommend that you place your directives in only one of these files:
cobsql.dir file
To ensure that COBSQL retrieves its compiler directives from a cobsql.dir file, you must specify the COBSQL preprocessor (without additional directives) either in your project properties or on the command line. This instructs COBSQL to look for cobsql.dir as its first task. The cobsql.dir file must reside in either the current directory or in a directory specified by the COBDIR environment variable. COBSQL searches the current directory and then along the COBDIR path for cobsql.dir. COBSQL uses the first found instance of cobsql.dir. Using any text editor, follow these rules when creating the content of a cobsql.dir file:
  • Do not include COBOL compiler directives in cobsql.dir. COBOL does not read the cobsql.dir file.
  • Put one or more COBSQL directives on each line in the file.
  • Do not split a COBSQL directive across multiple lines.
  • When COBSQL encounters either END-C, END, or END-COBSQL, the rest of the line passes to the database precompiler.
  • The options to be passed to the database precompiler must all appear on a single line in the cobsql.dir file.
cobol.dir file and User Directives file
  • When the compiler encounters the PREPROCESS directive, it passes the rest of the line to COBSQL until it reaches ENDP.
  • The compiler treats the PREPROCESS directive and all the options that follow, up to the endp, as a single compiler directive. Therefore, the PREPROCESS directive and all its options must all appear on a single line.
See System-wide Directives File, cobol.dir, PREPROCESS(cobsql), COBSQL Compiler Directives, and User Directives File for details.
Embedded in a Program
You can also specify the COBSQL preprocessor and its directives on the program level by embedding a $SET statement into the program itself:
  • If you are using fixed source format (SOURCEFORMAT"FIXED", which is the default setting), place the $SET statement in column 7 on the first line of the program.
  • Follow the $SET statement with the appropriate PREPROCESS(cobsql) command-line syntax.
Important: Use this method only when the program requires a preprocessor different from other programs in an application.

See PREPROCESS(cobsql) and COBSQL Compiler Directives for details.

Parent topic: COBSQL
Related concepts
Specifying an SQL Preprocessor and Compiler Directive Options
Related reference
PREPROCESS(cobsql)
System-wide Directives File, cobol.dir
COBSQL Compiler Directive Options
COBOL Directives
User Directives File
SOURCEFORMAT


Using the CP Preprocessor to Expand Copybooks

The complete set of methods used within COBOL to manipulate copybooks is not available with database precompilers and COBSQL itself cannot handle included copybooks. These problems can be overcome by using the Micro Focus Copybook Preprocessor (CP).

CP is a preprocessor that provides other preprocessors, such as COBSQL, with a mechanism for handling copybooks. CP follows the same rules as the COBOL Compiler for handling copybooks, so any copybook-related Compiler directives are automatically picked up and copybooks are searched for using the COBCPY environment variable. CP also expands the following statements:

EXEC SQL
   INCLUDE ...
END-EXEC

Oracle uses .pco and .cob extensions, Sybase uses .pco and .cbl extensions and Informix uses .eco, .cob and .mf2 extensions.

Oracle and Sybase:

For CP to resolve copybooks and include statements correctly, use the following COBOL Compiler directives for Sybase and Oracle:

copyext (pco,cbl,cpy,cob) osext(pco)

Informix:

For Informix, use:

copyext (eco,mf2,cbl,cpy,cob) osext(eco)

COBSQL can call CP to expand copybooks before the database precompiler is invoked. This means that all the copy-related commands are already resolved so that it appears to the database precompiler that a single source file is being used.

The other advantage of using CP is that it makes copybooks visible when debugging.

When CP sees an INCLUDE SQLCA statement, it does the following:

  • Searches for a file called sqlca.ext in the current directory, where ext is any copybook extension as set up by the OSEXT and COPYEXT Compiler directives. By default these are .cbl and .cpy.
  • Searches for sqlca.ext along the COBCPY path.
  • An example sqlca.cpy file is provided in the %ProgramFiles(x86)%\Micro Focus\Visual COBOL\cpylib directory. If the SQLCA file supplied by the database vendor is not located on the COBCPY path, this example of the SQLCA will be used.
Note: Using the file sqlca.cpy can result in errors when the program is run.

You can specify the CP preprocessor's SY directive to prevent CP expanding the SQLCA include file, for example:

preprocess(cobsql) preprocess(cp) sy endp

You should always use CP's SY directive when processing Sybase code because Sybase expects to expand the SQLCA itself.

If the MODE=ANSI option is specified to the Oracle precompiler, Pro*COBOL, then you should additionally use CP's SY directive to ensure that the SQLCA gets populated correctly.

As Oracle can produce code with either COMP or COMP-5 variables, it has two sets of copybooks. The standard sqlca.cob, oraca.cob and sqlda.cob all have COMP data items. The sqlca5.cob, oraca5.cob and sqlda5.cob files have COMP-5 data items. If you are using the comp5=yes Oracle directive, you must set the COBSQL directive MAKESYN to convert the COMP items in the SQLCA to COMP-5.

If CP produces errors when attempting to locate copybooks, check to make sure that the OSEXT and COPYEXT Compiler directives are set correctly. COPYEXT should be set first and should include as its first entry the extension used for source files (.pco or .eco, for example).

If these are set correctly, ensure that the copybook is either in the current directory or in a directory on the COBCPY path.

When using CP in conjunction with COBSQL, SQL errors inside included copybooks will be reported correctly. Without CP, the line counts will be wrong, and the error will either go unreported or will appear on the wrong line.

Parent topic: COBSQL
Related reference
CP Preprocessor


Troubleshooting

Initially, you should check each of the items outlined below.

  • Basic network connectivity

    Forget SQL, and determine whether the client and server are communicating. For TCP/IP, check whether you can ping the server from the workstation and vice versa. If host names don't work, try raw IP addresses.

  • SQL networking software

    Check that the SQL networking software is "talking" correctly to the network software. Many SQL vendors supply a ping utility which will show whether the SQL network is set up correctly.

  • Interactive SQL

    If the SQL network is okay, try some interactive SQL. Most vendors supply a simple utility that allows you to enter SQL from the keyboard and view the results. Most vendors also supply a sample database that is useful for this purpose.

  • Standalone Precompiler

    Verify that the standalone precompiler works. There may be an icon or a command line for the precompiler. Verify that it can produce COBOL code correctly. It is normal for some sample applications to be supplied with the precompiler.

  • Preprocessed application

    Check that a preprocessed application runs okay. Pass the expanded program through the COBOL Compiler and then try to run it.

  • COBSQL with minimal directives

    Try COBSQL with minimal directives. Place the SQLCA copybook into the directory with the sample program (prior to running the precompiler), and see if this works.

If you continue to have problems, please contact Micro Focus Support. To help Technical Support locate the cause of the problem:

  • Use the COBSQL directive SQLDEBUG
  • Send a zip file containing the following to Technical Support:
    • The original source
    • The expanded source (as produced by the database precompiler)
    • The trace file (which will have the extension .trc)
    • The database list file (which will normally have the extension .lis)
    • The command line debug file (which will have the extension .sdb)
    • The project file (projectname.cblproj)
    • The COBSQL directive settings used
  • Common Problem Areas
  • Oracle Considerations
  • Sybase Considerations
  • Informix Considerations
Parent topic: COBSQL


Common Problem Areas

If you cannot locate the source of the problem, check each of the following:

  • Latest versions

    Ensure that you are using the latest version of all the products involved.

  • COMP/COMP-5 Conflicts

    Check the vendor's documentation and example applications.

  • Configuration

    Check that environment variables, PATH and configuration file settings are set up correctly.

  • Directives

    By default, COBSQL does not display the command line it passes to the database precompiler. Setting the SQLDEBUG directive enables the command line to be displayed (you will need to do this if the precompiler gives command line errors). Possible causes of command line errors are that the directives to be passed to the precompiler are incorrect or that the length of the precompiler command line has been exceeded.

  • Memory

    COBSQL may display the following error because the database precompiler has terminated unexpectedly:

    * CSQL-F-021: Precompiler did not complete -- Terminating

    This may be because the Operating System has run out of memory attempting to execute the database precompiler.

  • Missing output files

    COBSQL may display the following errors because it cannot find the precompiler's output file. This may be because the precompiler did not produce an output file. The normal reason for this is that the precompiler hit a fatal error which meant it could not create the output file.

    * CSQL-E-024: Encountered an I/O on file filename
* CSQL-E-023: File Status  3 / 5

    where filename is the name of the file produced by the database precompiler.

  • Premature end of expanded source

    If COBSQL reports the error "Premature end of expanded source" and the precompiler runs correctly, this indicates that COBSQL has not been able to match the original source lines with the lines produced by the database precompiler.

    Another possible reason for COBSQL reporting this error is that the program does not contain any SQL. Generally, if the database precompiler does not come across any SQL it will abort the creation of its output file part way through, causing this error to be displayed.

Parent topic: Troubleshooting


Oracle Considerations

If you are troubleshooting Oracle problems, consider the following:

  • The following Oracle precompiler options can have a marked effect on the behavior and the memory requirements of an Oracle application. We recommend that you take time to review your Oracle documentation before changing the setting of these directives.
    DBMS
HOLD_CURSOR
MAXOPENCURSORS
MODE
RELEASE_CURSOR
  • Within an Oracle program it is possible to use the ALTER SESSION command to change the OPTIMIZER_GOAL. This can have a profound effect on the performance of the application. Before using this syntax, we recommend that you consider what is the best optimisation for an application in the general case rather than for a particular SQL statement. If you need to change the performance of one particular statement, it is probably better to use HINTS. Consult your Oracle documentation for further information on ALTER SESSION, OPTIMIZER_GOAL and HINTS.
  • Oracle provides a method of reducing network access by using arrays within Embedded SQL statements. This enables the application to perform 'batch' SQL commands, in that more than one row can be acted upon in a single SQL statement. See the section Host Arrays in the chapter Host Variables for more details.

    The use of arrays enables an application, for example, to fetch ten rows at a time instead of one at a time. Oracle supply an example program (normally called sample3.pco) that uses an array to fetch multiple rows. Arrays are documented in the Pro*Cobol Supplement to the ORACLE Precompilers Guide.

  • Pro*Cobol treats BINARY host variables as though they had been defined with a picture clause of COMP. This means that BINARY items will also be converted to COMP-5 when the Pro*Cobol comp5=yes option is used.
  • Pro*Cobol always needs to be supplied with an include directive, unless the SQLCA copybook is in the current directory, because it needs to know the location of the SQLCA copybook. If this is not supplied, Pro*Cobol gives an error on filename.pco, where filename can be any string of eight characters.
  • When Pro*Cobol runs, it can generate useful information. When the COBSQL VERBOSE directive is used, COBSQL displays as much of this information as it can.

    To get the maximum information from Pro*Cobol, set the Pro*Cobol directive xref=yes. You can add this directive to the Pro*Cobol configuration file $ORACLE_HOME/precomp/admin/pcbcfg.cfg where:

    $ORACLE_HOME is the root directory for the Oracle installation on your machine
  • By using the COBSQL DISPLAY directive, the current Pro*Cobol directives can be seen on the screen. This will be followed by the statistical information created by Pro*COBOL.
  • If the COBOL LIST directive is used, COBSQL passes any information it has collected from the precompiler to the COBOL checker for inclusion at the bottom of the COBOL listing.
  • Migration and Development
  • Oracle 8 and Micro Focus COBOL
Parent topic: Troubleshooting


Migration and Development

If you are migrating programs from Pro*COBOL 1.x to 8.x or later, you should be aware of the following:

  • Within the Data Division:
    • You should terminate all SQL statements with a period
    • Only ANSI comments are supported. Comments starting with *> in any column are not supported
  • Support for nested programs

    Define all inserted variables as GLOBAL including the data items inserted by COBSQL that support the EBCDIC to ASCII conversions.

  • Oracle 8 no longer requires a declare section as this can cause problems with the Oracle COMP to COMP-5 conversion.

    If the Oracle directive DECLARE_SECTION=NO is set (the default), Oracle converts all COMP, BINARY or COMP-4 data items to COMP-5.

    To limit the conversion of items to the declare section, set one of the following:

    • DECLARE_SECTION=YES or MODE=ANSI
    • The Pro*COBOL directive COMP5=NO and the COBSQL directive MAKESYN
  • Extra data types supported by Pro*COBOL 8.x or later are:
    • PACKED-DECIMAL

      These data items are treated in the same way as COMP-3 data items.

    • COMP-4
    • PIC 9(4) COMP / COMP-4 / BINARY / COMP-5
    • PIC 9(4) USAGE DISPLAY
    • PIC s9(4) USAGE DISPLAY SIGN TRAILING
    • PIC s9(4) USAGE DISPLAY SIGN TRAILING SEPARATE
    • PIC s9(4) USAGE DISPLAY SIGN LEADING
    • PIC s9(4) USAGE DISPLAY SIGN LEADING SEPARATE

      This type was previously supported as the Oracle DISPLAY datatype.

  • When working on x86 or x86-64 platforms, do not use the COBSQL directive NOMAKESYN, since this directive results in COMP host variables and on x86 and x86-64 platforms these items are incompatible with the native byte order expected by Oracle.
Parent topic: Oracle Considerations


Oracle 8 and Micro Focus COBOL

Pro*COBOL 8.x (or later) rejects some Micro Focus COBOL language extensions, data definitions and section headings:

  • All pointer data types
  • 88 level variables
  • Constants in a Value clause
  • Items defined as external-form
  • Local-Storage Section
  • Thread-Local-Storage Section

To overcome this you need to put these items into copybooks which are not opened by Pro*COBOL. However, this does not work if you use CP which expands copybooks before Pro*COBOL is invoked. This could cause a problem if you are using htmlpp which calls CP to expand copybooks. You must therefore invoke htmlpp before COBSQL.

For example, the following compile line works:

cob -k PROG.pco -C "p(htmlpp) preprocess(cobsql)
             csqlt==oracle8 endp"

whereas this line does not:

cob -k PROG.pco -c "preprocess(cobsql) csqlt==oracle8
             p(htmlpp) endp"

You must define at least one variable within the Working-Storage Section for Pro*COBOL to add its variables to the generated .cbl file.

Parent topic: Oracle Considerations


Sybase Considerations

Before using Sybase, you must make the following changes to your system:

  • In the Sybase-supplied copybooks cobpub.cbl and sybhesql.cbl, change all COMP data items to COMP-5.
  • Change the COBOPT environment variable to $COBDIR/src/sybase/cobopt_sybase

If you are troubleshooting Sybase problems, consider the following:

  • If CP is not used with COBSQL to locate copybooks, the copybook to be brought in by the Sybase precompiler needs to be fully qualified. The Sybase precompiler does not search for any extensions.
  • If the Sybase precompiler has problems locating the correct language to use to report messages on the client, check that the Sybase file, locales.dat is configured correctly.

    If the default setting for the client Operating System has been configured, but Sybase still reports national locale support errors, use the LANG environment variable to override the setting in the locales.dat file.

    For example if the aix client was causing problems and the locales.dat file contained the following setting for AIX:

    [aix]
locale = C, us_english, iso_1
locale = En_US, us_english, iso_1
locale = en_US, us_english, iso_1
locale = default, us_english, iso_1

    then a possible LANG setting for US English would be:

    LANG=en_US
  • It can be difficult to identify Sybase error messages. To help COBSQL identify them, you can modify the esql.loc file. Use a text editor to edit the esql.loc file to change the layout of the messages to the following:
    SYB-severity-number-text

    where the parameters are:

    SYB | A string which indicates to COBSQL that this is a modified Sybase error message.
    severity | Indicates the severity of the error; some of the Sybase messages are only warnings rather than normal or fatal errors.
    number | A unique, four digit error number assigned to the Sybase error.
    text | The original Sybase error message.

    For example, a typical entry in the esql.loc file might be:

    9 = M_PRECLINE, "Warning(s) during check of query on line %1!."

    and this would be changed to read:

    9 = M_PRECLINE, "SYB-W-2009 Warning(s) during check of query on line %1!."

    It is recommended that you make a copy of esql.loc before altering it. Using the modified version, COBSQL can detect the full range of Sybase error messages.

    The location of esql.loc is dependent on the language and code page used. This is defined in the locales.dat file. If the definition of the default language for the AIX platform was as follows:

    [aix]
locale = C, us_english, iso_1
locale = En_US, us_english, iso_1
locale = en_US, us_english, iso_1
locale = default, us_english, iso_1

    The default langauge would be us_english, using the iso_1 code page, so the copy of esql.loc that is to be used is:

    /sybase-home/locales/messages/us_english/iso_1/esql.loc

    where sybase-home is the directory that the Sybase client is installed into.

    For more information on how Sybase uses and locates the different error message files, refer to your Sybase Client Reference Manual.

  • To use Sybping with different Sybase servers, each server should have a service defined. The Sybase product sqledit shows you how to enter the required information.
  • If the name of the server is not specified when connecting to Sybase, Sybase searches for an environment variable called DSQUERY.
  • When the Sybase precompiler runs, it can generate useful information. If the COBSQL directive VERBOSE is set, COBSQL displays as much of this information as it can.
  • By using the COBSQL DISPLAY directive, the statistical information created by the Sybase precompiler can be seen on the screen.
  • If the COBOL LIST directive is set, COBSQL passes any information it has collected from the precompiler to the COBOL checker for inclusion at the end of the COBOL listing.
  • The Sybase precompiler accepts programs that do not contain any SQL statements, and produces an output file. This means that all of the programs in a project can be compiled successfully. However, it also means that the Sybase precompiler inserts all the Working-Storage items and COBOL support code that it would insert for a program that contains Sybase SQL statements into a non-Sybase program. This makes the program larger, and may effect its performance.
  • The Sybase COBOL precompiler can be supplied separately to the Sybase System 11 Server. If this is the case, care must be taken when installing the Sybase COBOL precompiler as it is supplied with its own version of the Open Client support files and problems can arise if the two products have different versions of these files. In this situation, we strongly recommend that you contact Sybase support before proceeding with the installation of the Sybase System 11 COBOL precompiler.
  • You should take particular care if you are installing the Sybase client onto a machine that has the Server installed onto it (or vice versa). Installing the Sybase client only does not cause any problems.
Parent topic: Troubleshooting


Informix Considerations

  • Informix uses the .eco, .cob and .mf2 file extensions. For CP to resolve copybooks and include statements correctly, use the following COBOL Compiler directives:
    copyext(eco,mf2,cob,cpy,cbl) osext(eco)
  • Under UNIX, because COBSQL invokes the Informix precompiler, the INFORMIXCOB, INFORMIXCOBTYPE and INFORMIXCOBDIR environment variables all need to be setup before using COBSQL. For more information about these environment variables, refer to the Informix COBOL/ESQL Programmers Guide.
  • Informix only produces error messages in its list files. Normally the error message will contain the line the error occured on. If COBSQL cannot locate the line number from the error message, it will not report the error.
  • To run COBSQL correctly with Informix, the INFORMIXDIR environment variable should be set before using COBSQL.
Parent topic: Troubleshooting


How to

  • JDBC
Parent topic: Database Access


JDBC

  • To install and configure Simple-JNDI
  • To create a JNDI DataSource object
Parent topic: How to


To install and configure Simple-JNDI

  1. Download Simple-JNDI version 11.4.1 or later from the osjava Open Source Java components Web site.
  2. Extract all files to the root directory you created for your JDBC resources. See JDBC Resources for details.
  3. Using any text editor, create a jndi.properties file, also in your JDBC resources root directory, containing the following:
    java.naming.factory.initial=org.osjava.sj.SimpleContextFactory
org.osjava.sj.root=jdbcRootDirectory
blankLine
    Where:
    • jdbcRootDirectory is the full path to the root directory, using double single slash characters in place of single characters. For example:

      For /home/jdbcrsc, specify /home/jdbcrsc/.

    • blankLine is a blank line immediately following the jdbcRootDirectory specification.
  4. If you would prefer that your project access the jndi.properties file from a zip archive, compress the file into an archive with a .zip file extension, and save it to the jdbcRootDirectory.
Parent topic: JDBC
Related concepts
JNDI DataSource Objects
JDBC Resources


To create a JNDI DataSource object

  1. Create the directory structure recommended in the topic JDBC Resources.
  2. Using any text editor, create a file in your JDBC resources DataSources subdirectory using the following naming convention:

    dataSourceName.properties

    where dataSourceName is a name you choose to describe the data source.

    For example, /home/jdbcrsc/DataSources/MSSQL.properties.

  3. Include the following content in the file:
    type=javax.sql.DataSource
driver=driverClass
url=JDBC-URL
user=userID
password=password
    Where:
    driverClass | The name of the JDBC driver's main class.
    JDBC-URL | A URL that identifies the server and database.
    userID | The user ID required to log onto the server and database. If not required by the database or if the user ID is supplied by your application at runtime, leave the value blank.
    password | The password that accompanies the specified user ID. If not required by the database or if the password is supplied by your application at runtime, leave the value blank.

For more information on driver classes, see JDBC Driver Classes. For more information on JDBC URLs, see JDBC URLs. To see several example DataSource object files, see Sample DataSource Object Files.

Parent topic: JDBC
Related concepts
JNDI DataSource Objects
JDBC Resources
Connect Using a JNDI DataSource Object
Related reference
JDBC URLs
JDBC Driver Classes
Sample DataSource Object Files


Reference

  • OpenESQL
  • DB2
  • COBSQL
  • SQL Data Types
  • SQL TYPEs
  • Data Structures
  • Keywords
Parent topic: Database Access


OpenESQL

  • Embedded SQL Statements
  • SQL Compiler Directive Options
  • DBMAN Directive Settings
  • JDBC Driver Classes
    Lists tested JDBC driver classes for DB2, Microsoft SQL Server, and Oracle databases.
  • JDBC URLs
    Describes JDBC URLs and shows examples for DB2, Microsoft SQL Server, and Oracle databases.
  • Sample DataSource Object Files
    Shows sample DataSource object files containing connection information for various databases.
  • SQL/COBOL Data Type Mappings
  • OpenESQL Messages
  • DSNTIAR and DSNTIAC
    Converts SQL return codes to character-string messages.
  • esqlconfig command
    Runs the command-line implementation of the OpenESQL Configuration utility, enabling you to set a default behavior for the SQL(BEHAVIOR) compiler directive option.
Parent topic: Reference


Embedded SQL Statements

With the exception of INSERT, DELETE(SEARCHED) and UPDATE(SEARCHED) which are included for your convenience, the embedded SQL statements described here work somewhat differently, or are in addition to, standard SQL statements.

  • BEGIN DECLARE SECTION
    Signals the beginning of the DECLARE section.
  • BEGIN TRAN
    Provides compatibility with Embedded SQL implementations that do not conform to the ANSI SQL standard with respect to transaction management and, in particular, the Micro Focus Embedded SQL Toolkit for Microsoft SQL Server.
  • BIND CONNECTION
    Enables a JDBC connection object to be shared with OpenESQL.
  • CALL
    Executes a stored procedure.
  • CLOSE
    Discards unprocessed rows and frees any locks held by the cursor.
  • COMMIT
    Makes any changes made by the current transaction on the current connection permanent in the database.
  • CONNECT
    Attaches to a specific database using the supplied user name and password.
  • DECLARE CURSOR
    Associates the cursor name with the specified SELECT statement and enables you to retrieve rows of data using the FETCH statement.
  • DECLARE DATABASE
    Declares the name of a database.
  • DECLARE STATEMENT
    Provided for compatibility with other ESQL SQL dialects, and is accepted but not processed by the OpenESQL preprocessor.
  • DELETE (Positioned)
    Deletes the row most recently fetched by using a cursor.
  • DELETE (Searched)
    Removes table rows that meet the search criteria.
  • DESCRIBE
    Provides information on prepared dynamic SQL statements and describes the result set for an open cursor.
  • DISCONNECT
    Closes the connection(s) to a database. In addition, all cursors opened for that connection are automatically closed.
  • END DECLARE SECTION
    Terminates a host variable declaration section begun by a BEGIN DECLARE SECTION statement.
  • EXECSP
    Executes a stored procedure.
  • EXECUTE
    Processes dynamic SQL statements.
  • EXECUTE IMMEDIATE
    Immediately executes the SQL statement.
  • FETCH
    Retrieves a row from the cursor's results set and writes the values of the columns in that row to the corresponding host variables (or to addresses specified in the SQLDA data structure).
  • GET CONNECTION
    Places an OpenESQL connection object into the supplied host variable such that the objects can then be shared with other JDBC programs.
  • GET HDBC
    Enables you to use ODBC calls that require you to supply the ODBC connection handle.
  • GET HENV
    Enables you to use ODBC calls that require you to supply the ODBC environment handle.
  • GET NEXT RESULT SET
    Makes the next result set available to an open cursor.
  • INCLUDE
    Includes the definition of the specified SQL data structure or source file in the COBOL program.
  • INSERT
    Adds new rows to a table.
  • INTO
    Retrieves one row of results and assigns the values of the items returned by an OUTPUT clause in a SQL Server INSERT, UPDATE, or DELETE statement to the host variables specified in the INTO list.
  • OPEN
    Runs the SELECT statement specified in the corresponding DECLARE CURSOR statement to produce the results set that is accessed one row at a time by the FETCH statement.
  • PERSIST
    Saves information defined in a cursor SELECT statement as XML files.
  • PREPARE
    Processes dynamic SQL statements.
  • QUERY ODBC
    Delivers a results set in the same way as a SELECT statement, and must therefore be associated with a cursor via DECLARE and OPEN, or DECLARE, PREPARE and OPEN.
  • RESET CONNECTION
    Closes all open cursors, even if the application has not appropriately closed them.
  • ROLLBACK
    Backs out any changes made to the database by the current transaction on the current connection, or partially rolls back changes to a previously set save point.
  • SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT
    Sets a transaction save point to which a current transaction can be rolled back, resulting in a partial roll back.
  • SELECT DISTINCT (using DECLARE CURSOR)
    Associates the cursor name with the SELECT DISTINCT statement and enables you to retrieve rows of data using the FETCH statement.
  • SELECT INTO
    Retrieves one row of results and assigns the values of the items in a specified SELECT list to the host variables specified in the INTO list.
  • SET AUTOCOMMIT
    Enables you to control ODBC AUTOCOMMIT mode at runtime.
  • SET CONCURRENCY
    Sets the concurrency option for cursors.
  • SET CONNECTION
    Sets the named connection as the current connection.
  • SET host_variable
    Provides information about OpenESQL connections and databases.
  • SET OPTION
    Enables you to set OpenESQL options.
  • SET SCROLLOPTION
    Enables you to set cursor scrolling options.
  • SET TRACELEVEL
    Enables you to dynamically set or change the reporting level of OpenESQL traces for native applications.
  • SET TRANSACTION ISOLATION
    Sets the transaction isolation level for the current connection to one of the isolation level modes specified by ODBC.
  • SYNCPOINT
    Closes all open cursors that were not opened using the WITH HOLD clause, even if the application has not appropriately closed them.
  • UNBIND CONNECTION
    Disassociates OpenESQL from the original JDBC connection object.
  • UPDATE (Positioned)
  • UPDATE (Searched)
    Updates a table or view based on specified search conditions.
  • WHENEVER
    Specifies the default action after running an Embedded SQL statement when a specific condition is met.
Parent topic: OpenESQL
Related concepts
Embedded SQL
Related reference
SQL


BEGIN DECLARE SECTION

Signals the beginning of the DECLARE section.

Syntax:

>>---EXEC SQL---BEGIN DECLARE SECTION---END-EXEC---><

Comments:

The BEGIN DECLARE SECTION statement can be included anywhere where COBOL permits variable declaration. Use END DECLARE SECTION to identify the end of a COBOL declaration section.

  • Declare sections cannot be nested.
  • Variables must be declared in COBOL, not in SQL.
  • To avoid conflict, variables inside a declaration section cannot be the same as any outside the declaration section or in any other declaration section, even in other compilation units.

If data structures are defined within a declaration section, only the bottom-level items (with PIC clauses) can be used as host variables. Two exceptions are arrays specified in FETCH statements and record structures specified in SELECT INTO statements.

Example:

 WORKING-STORAGE SECTION.
 EXEC SQL BEGIN DECLARE SECTION END-EXEC
 01 staff-id        pic x(4).
 01 last-name       pic x(30).
 EXEC SQL END DECLARE SECTION END-EXEC
Parent topic: Embedded SQL Statements
Related reference
END DECLARE SECTION
FETCH
SELECT INTO


BEGIN TRAN

Provides compatibility with Embedded SQL implementations that do not conform to the ANSI SQL standard with respect to transaction management and, in particular, the Micro Focus Embedded SQL Toolkit for Microsoft SQL Server.

Syntax, Format 1:

>>--EXEC SQL--BEGIN TRAN-.------------------.-END-EXEC---><
                         +-transaction_name-+

Syntax, Format 2:

>>-EXEC SQL-BEGIN TRANSACTION.----------------.-END-EXEC-><
                             +transaction_name+

Parameters:

transaction_name An optional identifier that is ignored.

Comments:

Use the BEGIN TRAN statement in AUTOCOMMIT mode to open a transaction. After you have opened the transaction in AUTOCOMMIT mode, you should execute a COMMIT or ROLLBACK statement to close the transaction and cause a return to AUTOCOMMIT mode.

If you are not opening a transaction in AUTOCOMMIT mode, then this statement has no effect.

Example:

 EXEC SQL BEGIN TRANSACTION END-EXEC
Parent topic: Embedded SQL Statements
Related reference
SET AUTOCOMMIT


BIND CONNECTION

Enables a JDBC connection object to be shared with OpenESQL.

Syntax:

>>--EXEC SQL--BIND CONNECTION--.-----------------.-TO :conn_obj_hv---->
                               +-connection_name-+
                               +- :conn_name_hv -+
 >--END-EXEC----><

Parameters:

connection_name | The connection name OpenESQL uses to refer to the JDBC connection object.
conn_name_hv | Host variable which contains the connection name OpenESQL uses to refer to the JDBC connection object.
conn_obj_hv | Host variable where the JDBC connection object is specified.

Comments:

The named OpenESQL connection can use the existing JDBC connection and transaction objects in further EXEC SQL processing.

Example:

     EXEC SQL
        BIND CONNECTION fred TO :con
     END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Sharing Database Connections Between Java and COBOL


CALL

Executes a stored procedure.

Syntax:

>>--EXEC SQL--.--------------------.--.----------------.->
              +-FOR :host_integer--+  +- :result_hvar -+

 >---CALL stored_procedure_name-.------------.-END-EXEC-><
                                | +-- , --+  |
                                | V       |  |
                                +(parameter)-+

Parameters:

host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
result_hvar | A host variable to receive the procedure result.
stored_procedure_name | The name of the stored procedure.
parameter A literal, a DECLARE CURSOR statement1, or a host variable parameter of the form:
[keyword=]:param_hvar [IN | INPUT |
INOUT | OUT | OUTPUT]

where:

keyword | The formal parameter name for a keyword parameter. Keyword parameters can be useful as an aid to readability and where the server supports default parameter values and optional parameters.
param_hvar | A host variable.
IN | An input parameter.
INPUT | An input parameter (default).
INOUT | An input/output parameter.
OUT | An output parameter.
OUTPUT | An output parameter.

1 Specify DECLARE CURSOR only with Oracle 8 or later and for stored procedures that return a result set. The use of DECLARE CURSOR unbinds the corresponding parameter.

Comments:

Do not use the FOR clause if the CALL is part of a DECLARE CURSOR statement.

For maximum portability, observe the following as general rules:
  • Avoid literal parameters
  • Use host variable parameters
  • Avoid mixing positional parameters and keyword parameters
  • If your server supports a mixture of positional and keyword parameters, list keyword parameters after positional parameters

Examples:

Call a stored procedure using two positional host variables as input parameters:
   EXEC SQL
      CALL myProc(param1,param2)
   END-EXEC
Call a stored procedure using a keyword host variable as an input parameter:
   EXEC SQL
      CALL myProc (namedParam=:paramValue)
   END-EXEC
Call a stored procedure using a result host variable and a keyword host variable as an input parameter:
   EXEC SQL
      :myResult = CALL myFunction(namedParam=:paramValue)
   END-EXEC
Call a stored procedure using two positional host variables, one as an input parameter and one as an output parameter:
   EXEC SQL
      CALL getDept(:empName IN, :deptName OUT)
   END-EXEC
Call a stored procedure using a DECLARE CURSOR statement and a positional host variable as an input parameter (Oracle only):
   EXEC SQL
      DECLARE cities CURSOR FOR CALL locateStores(:userState)
   END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Working with Stored Procedures and Result Sets
Related reference
DECLARE CURSOR
EXECSP
Related information
OpenESQL


CLOSE

Discards unprocessed rows and frees any locks held by the cursor.

Syntax:

>>---EXEC SQL---.------------.--->
                +-AT db_name-+

 >--CLOSE---cursor_name---.------------.---END-EXEC---><

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement. Provided for backward compatibility.
cursor_name | A previously declared and opened cursor.

Comments:

The cursor must be declared and opened before it can be closed. All open cursors are closed automatically at the end of the program.

Example:

*Declare the cursor...
     EXEC SQL
         DECLARE C1 CURSOR FOR
            SELECT staff_id, last_name
            FROM staff
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not declare cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL
        OPEN C1
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not open cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

     PERFORM UNTIL sqlcode NOT = ZERO
*SQLCODE will be zero as long as it has successfully fetched data
        EXEC SQL
           FETCH C1 INTO :staff-staff-id, :staff-last-name
        END-EXEC
        IF SQLCODE = ZERO
           DISPLAY "Staff ID: " staff-staff-id
           DISPLAY "Staff member's last name: " staff-last-name
        END-IF
     END-PERFORM

     EXEC SQL
        CLOSE C1
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not close cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
     END-IF
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
FETCH
OPEN
GET NEXT RESULT SET


COMMIT

Makes any changes made by the current transaction on the current connection permanent in the database.

Syntax:

>>---EXEC SQL--.------------.--->
               +-AT db_name-+

 >---COMMIT----.--------------.--->
               +-WORK---------+
               +-TRAN---------+
               +-TRANSACTION--+

 >---.-----------.---END-EXEC--><
     +--RELEASE--+

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is optional. If omitted, the current connection is committed. If provided, and the connection specified is different than the current connection, the commit is performed on the connection associated with the DECLARE CURSOR statement.
WORK | WORK, TRAN, and TRANSACTION are optional and synonymous.
RELEASE | If RELEASE is specified and the transaction was successfully committed, the current connection is closed.

Example:

* Ensure that multiple records are not inserted for a
* member of staff whose staff_id is 99
     EXEC SQL
        DELETE FROM staff WHERE staff_id = 99
     END-EXEC

* Insert dummy values into table
     EXEC SQL
        INSERT INTO staff
        (staff_id
        ,last_name
        ,first_name
        ,age
        ,employment_date)
        VALUES
        (99
        ,'Lee'
        ,'Phil'
        ,19
        ,'1992-01-02')
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not insert dummy values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL
        COMMIT
     END-EXEC

* Check it was committed OK
     IF SQLCODE = ZERO
        DISPLAY 'Error: Could not commit values.'
       DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

     DISPLAY 'Values committed.'

* Delete previously inserted data
     EXEC SQL
        DELETE FROM staff WHERE staff_id = 99
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not delete dummy values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Check data deleted OK, commit and release the connection
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not delete values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL
        COMMIT WORK RELEASE
     END-EXEC

* Check data committed OK and release the connection.
    IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not commit and release.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
     END-IF

     DISPLAY 'Values committed and connection released.'
Parent topic: Embedded SQL Statements
Related concepts
Managing Transactions
Related reference
CONNECT
DISCONNECT
ROLLBACK
SET CONNECTION
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT


CONNECT

Attaches to a specific database using the supplied user name and password.

Syntax, Format 1:

>>---EXEC SQL---CONNECT TO---.-------------.------------->
                             +-data_source-+

 >--.------------.------USER-.-------------------.-------->
    +-AS db_name-+           +-user-.-----------++
                                    +-.password-+

 >-.--------------------.-.-----------------------------.->
   +-WITH-.----.-PROMPT-+ +-RETURNING output_connection-+
          +-NO-+

 >------END-EXEC--------><

Syntax, Format 2:

>>---EXEC SQL---CONNECT user--.------------------------.->
                              +-IDENTIFIED BY password-+
                              +-------'/'password------+

 >---.--------------.--------.--------------------.------->
     +--AT db_name--+        +--USING data_source-+

 >---.----------------------.----------------------------->
     +--WITH-.----.-PROMPT--+
             +-NO-+

 >---.-----------------------------.---END-EXEC---><
     +-RETURNING output_connection-+

Syntax, Format 3:

>>----EXEC SQL---CONNECT WITH PROMPT-------------------->

 >---.------------------------------.---END-EXEC----><
     +-RETURNING output_connection -+

Syntax, Format 4:

>>----EXEC SQL---CONNECT RESET-.--------.--END-EXEC-----><
                               +--name--+

Syntax, Format 5:

>>----EXEC SQL--------CONNECT DSN input_connection------->

 >---.------------------------------.-------END-EXEC-----><
     +-RETURNING output_connection -+

Syntax, Format 6:

>>----EXEC SQL---CONNECT USING input_connection---------->

 >-----.-------------.---.---------------------.---------->
       +--AS db_name-+   +--WITH-.----.-PROMPT-+
                                 +-NO-+

 >-----.------------------------------.------END-EXEC----><
       +--RETURNING output_connection-+

Parameters:

data_ source

The name of the ODBC data store. For ODBC data stores, this is the DSN created via the Microsoft ODBC Data Source Administrator. .

If you omit data_source, the default ODBC data source is assumed. The data source can be specified as a literal or as a host variable.

db_name A name for the connection. Connection names can have as many as 30 characters, and can include alphanumeric characters and any symbols legal in filenames. The first character must be a letter. Do not use Embedded SQL keywords or CURRENT or DEFAULT or ALL for the connection name; they are invalid. If db_name is omitted, DEFAULT is assumed. db_name can be specified as a literal or a host variable.

When connecting to SQL Server, db_name is the database to which you are connecting.

user | A valid user-id at the specified data source.
password | A valid password for the specified user-id.
output_connection | A PIC X(n) text string defined by ODBC as the connection string used to connect to a particular data source. Subsequently, you can specify this string as the input_connection in a CONNECT USING statement.
input_connection | A PIC X(n) text string containing connection information used by ODBC to connect to the data source. The test string can be either a literal or a host variable.
RESET | Resets (disconnects) the specified connection.
name | You can specify name as CURRENT, DEFAULT or ALL.

OS Authentication:

When using Oracle, DB2 or SQL Server with ODBC or JDBC runtimes, you can achieve OS authentication using either of these two methods:

  • In the CONNECT statement, specify a user ID consisting of a single forward slash and either omit the password or specify all spaces
  • Completely omit the user ID and password from the CONNECT statement

For complete information on OS authentication requirements for your DBMS product, consult your DBMS documentation. While various DBMS products have differing requirements, the following is a brief summary:

SQL Server
The Windows user must have a corresponding SQL Server login.
DB2
The WIndows user must be a member of either the DB2USERS group or the DB2 ADMNS group.
Oracle
Create an Oracle user with the OS authentication prefix and include the domain name with the user name. For JDBC you can set REMOTE_OS_AUTHENT in init.ora or use the OCI driver rather than the thin driver (e.g. url=jdbc:oracle:oci:@localhost:1521:ORCL).

Comments:

If you use only one connection, you do not need to supply a name for the connection. When you use more than one connection, you must specify a name for each connection. Connection names are global within a process. Named connections are shared by separately compiled programs that are linked into a single executable module.

After a successful CONNECT statement, all database transactions other than CONNECT RESET work through this most recently declared current connection. To use a different connection, use the SET CONNECTION statement.

To cause the ODBC run-time module to prompt at run-time for entry or confirmation of connection details, use CONNECT WITH PROMPT.

Use CONNECT DSN and CONNECT USING to simplify administration.

With CONNECT TO, CONNECT, CONNECT WITH PROMPT, CONNECT DSN and CONNECT USING, you can return connection information to the application.

Note:
  • If the INIT option of the SQL Compiler directive is used, an implicit connection to the database will be made at run-time. In this case, it is not necessary to execute an explicit CONNECT statement.
  • A File DSN cannot contain a password.

Example, Format 1:

     MOVE 'servername' TO svr
     MOVE 'username.password' TO usr

     EXEC SQL
        CONNECT TO :svr USER :usr
     END-EXEC

Example, Format 2:

     EXEC SQL
        CONNECT 'username.password' USING 'servername'
     END-EXEC

Example, Format 3:

     EXEC SQL
        CONNECT WITH PROMPT
     END-EXEC

Example, Format 4:

     EXEC SQL
        CONNECT RESET
     END-EXEC

Example, Format 5:

    EXEC SQL
        CONNECT USING 'FileDSN=Oracle8;PWD=tiger'
     END-EXEC

The example above uses a File DSN.

Example, Format 6:

 01  connectString               PIC X(72) value
                   'DRIVER={Microsoft Excel Driver (*.xls)};'
                   &'DBQ=c:\demo\demo.xls;'
                   &'DRIVERID=22'
                   .

 procedure division.

     EXEC SQL
         CONNECT USING :connectString
     END-EXEC

The example above connects to an Excel spreadsheet without setting up a data source.

Parent topic: Embedded SQL Statements
Related concepts
Database Connections
Database Connections
Compiling Multiple Program Modules
Related reference
COMMIT
DISCONNECT
ROLLBACK
SET CONNECTION
DECLARE DATABASE
SET OPTION


DECLARE CURSOR

Associates the cursor name with the specified SELECT statement and enables you to retrieve rows of data using the FETCH statement.

Syntax, Format 1:

>>--EXEC SQL---.------------.------DECLARE cursor_name------>
               +-AT db_name-+

 >--.-------------.-----.---------.------.--------------.--->
    +-SENSITIVE---+     +-FORWARD-+      +-LOCK---------+
    +-INSENSITIVE-+     +-KEYSET--+      +-LOCKCC-------+
                        +-DYNAMIC-+      +-OPTIMISTIC---+
                        +-STATIC--+      +-OPTCC--------+
                        +-SCROLL--+      +-OPTCCVAL-----+
                              +-READ ONLY----+
                                         +-READONLY-----+
                                         +-FASTFORWARD--+
                                         +-FAST FORWARD-+

 >--CURSOR-------.----------------.---------FOR------------->
                 +----WITH HOLD---+

 >----.----select_stmt-----------------------.-------------->
      +----stored_procedure_call_statement---+
      +----prepared_stmt_name----------------+
      +----OPTIMIZE FOR n ROWS---------------+
 >--.-------------------------------.----------------------->
    +-FOR READ ONLY-----------------+
    +-FOR UPDATE-.----------------.-+
                 +-OF column_list-+
 >------END-EXEC--------><

Syntax, Format 2:

Note: Format 2 is supported for SQL Server only.
>>--EXEC SQL---.------------.------DECLARE cursor_name------>
               +-AT db_name-+
 >--CURSOR FOR---result-set-generating-dml-statement-------->

 >------END-EXEC--------><

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. Note: If you must use AT db_name in a DECLARE CURSOR, the connection for any following statements that reference the cursor automatically switch to the connection associated with the cursor if different than the current connection, but only for the duration of the statement.
cursor_name | Cursor name used to identify the cursor in subsequent statements. Cursor names can contain any legal filename character and be up to 30 characters in length. The first character must be a letter.
select_stmt | Any valid SQL SELECT statement, or a QUERY ODBC statement or a CALL statement for a stored procedure that returns a result set.
prepared_stmt_name | The name of a prepared SQL SELECT statement or QUERY ODBC statement.
stored_procedure_call_stmt | A valid stored procedure call which returns a result set.
n | The number of rows per block fetched when the cursor is opened. The value of n must be less than 1000.
column_list | A list of column-names, separated by commas.
result-set-generating-dml-statement | A SQL Server INSERT, non-positioned UPDATE, or DELETE statement with an OUTPUT clause.

Comments:

Two separately compiled programs cannot share the same cursor. All statements that reference a particular cursor must be compiled together.

The DECLARE CURSOR statement must appear before the first reference to the cursor. The SELECT statement runs when the cursor is opened. The following rules apply to the SELECT statement:

  • It cannot contain an INTO clause or parameter markers.
  • It can contain input host variables previously identified in a declaration section.
  • With some ODBC drivers, the SELECT statement must include a FOR UPDATE clause if positioned updates or deletions are to be performed.

If OPTIMIZE FOR is specified, OpenESQL uses n to override the setting of the PREFETCH directive for the cursor. This allows prefetch optimization for individual cursors.

You can specify multiple SELECT statements in a DECLARE CURSOR statement, signifying the return of multiple result sets from either of the following. In either case, the client application must use the GET NEXT RESULT SET statement to retrieve additional result sets.
  • A COBOL stored procedure for SQL Server
  • A standard OpenESQL application program
The following applies to the behavior of certain DECLARE CURSOR options:
  • SCROLL selects a scroll option, other than FORWARD, that is supported by the driver.
  • LOCKCC and LOCK are equivalent.
  • READ ONLY and READONLY are equivalent.
  • OPTIMISTIC selects an optimistic concurrency mode (OPTCC or OPTCCVAL) that is supported by the driver.
  • If a HOLD cursor is requested and the current connection closes cursors at the end of transactions, the OPEN statement will return an error (SQLCODE = -19520).
  • If the database is Microsoft SQL Server and the NOANSI92 ENTRY directive setting has been used (this is the default setting), then a Microsoft SQL Server specific ODBC call will be made at connect time to request that cursors are not closed at the end of transactions. This is compatible with the Micro Focus Embedded SQL Toolkit for Microsoft SQL Server. The setting for USECURLIB must not be YES.
  • FAST FORWARD and FASTFORWARD are equivalent. This is a performance optimization parameter that applies only to FORWARD, READ-ONLY cursors. You can obtain even greater performance gains by also compiling the program with the AUTOFETCH directive; this is the most efficient method of getting a results set into an application. The AUTOFETCH directive enables two optimizations that can significantly reduce network traffic. The most dramatic improvement is seen when processing cursors with relatively small result sets that can be cached in the memory of an application. FASTFORWARD cursors work only with Microsoft SQL Server 2000 or later servers.

Example:

EXEC SQL DECLARE C1 CURSOR FOR
   SELECT last_name, first_name FROM staff
END-EXEC

EXEC SQL DECLARE C2 CURSOR FOR
   QUERY ODBC COLUMNS TABLENAME 'staff'
END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Working with Stored Procedures and Result Sets
Working With OpenESQL Cursors and Result Sets
Related reference
CALL
CLOSE
SELECT DISTINCT (using DECLARE CURSOR)
FETCH
OPEN
PREPARE
QUERY ODBC
SET CONCURRENCY
SELECT INTO
SET SCROLLOPTION
INTO
DELETE (Positioned)
DELETE (Searched)
EXECSP
UPDATE (Positioned)


DECLARE DATABASE

Declares the name of a database.

Syntax:

>>---EXEC SQL---DECLARE db_name---DATABASE---END-EXEC---->

Parameters:

db_name A name associated with a database. It must be an identifier and not a host variable. It cannot contain quotation marks.

Comments:

You must DECLARE db_name before using a CONNECT ... AT db_name statement.

You cannot use DECLARE DATABASE with EXECUTE IMMEDIATE or with PREPARE and EXECUTE.

Parent topic: Embedded SQL Statements
Related reference
CONNECT
EXECUTE
EXECUTE IMMEDIATE
PREPARE
UPDATE (Positioned)


DECLARE STATEMENT

Provided for compatibility with other ESQL SQL dialects, and is accepted but not processed by the OpenESQL preprocessor.

Syntax:

>>---EXEC SQL---DECLARE statement_name---STATEMENT---END-EXEC---->

Parameters:

statement_name A dynamic SQL statement name.

Comments:

In effect, the OpenESQL preprocessor ignores DECLARE STATEMENT.

Parent topic: Embedded SQL Statements


DELETE (Positioned)

Deletes the row most recently fetched by using a cursor.

Syntax:

>>---EXEC SQL---.------------.--->
                +-AT db_name-+

 >--DELETE---FROM---table_name--->

 >--WHERE CURRENT OF--cursor_name---END-EXEC---><

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.
table_name | The same table used in the SELECT FROM option (see DECLARE CURSOR).
cursor_name | A previously declared, opened, and fetched cursor.

Comments:

ODBC supports positioned delete, which deletes the row most recently fetched by using a cursor in the Extended Syntax (it was in the Core Syntax for ODBC 1.0 but was moved to the Extended Syntax for ODBC 2.0). Not all drivers provide support for positioned delete, although OpenESQL sets ODBC cursor names to be the same as COBOL cursor names to facilitate positioned update and delete.

With some ODBC drivers, the select statement used by the cursor must contain a 'FOR UPDATE' clause to enable positioned delete.

You cannot use host arrays with positioned delete.

The other form of DELETE used in standard SQL statements is known as a searched delete.

Most data sources require specific combinations of SCROLLOPTION and CONCURRENCY to be specified either by SET statements or in the DECLARE CURSOR statement.

The ODBC cursor libray provides a restricted implementation of positioned delete which can be enabled by compiling with SQL(USECURLIB=YES) and using SCROLLOPTION STATIC and CONCURRENCY OPTCCVAL (or OPTIMISTIC).

Example:

* Declare a cursor for update
     EXEC SQL DECLARE C1 CURSOR FOR
        SELECT staff_id, last_name FROM staff FOR UPDATE
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not declare cursor for update.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Open the cursor
     EXEC SQL
        OPEN C1
     END-EXEC
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not open cursor for update.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Display staff member's details and give user the opportunity
* to delete particular members.
     PERFORM UNTIL SQLCODE NOT = ZERO
        EXEC SQL FETCH C1 INTO :staff-id,:last-name END-EXEC
        IF SQLCODE = ZERO
           DISPLAY 'Staff ID:     ' staff-id
           DISPLAY 'Last name:    ' last-name
           DISPLAY 'Delete <y/n>? ' WITH NO ADVANCING
           ACCEPT usr-input
           IF usr-input = 'y'
              EXEC SQL
                 DELETE FROM staff WHERE CURRENT OF C1
              END-EXEC
              IF SQLCODE NOT = ZERO
                 DISPLAY 'Error: Could not delete record.'
                 DISPLAY SQLERRMC
                 DISPLAY SQLERRML
              END-IF
           END-IF
        END-IF
     END-PERFORM
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
FETCH
INSERT


DELETE (Searched)

Removes table rows that meet the search criteria.

Syntax:

>>--EXEC SQL--.-------------------.--->
              +-FOR :host_integer-+

 >--.-------------.--DELETE--.------.--->
    +-AT db_name--+          +-FROM-+

 >--.-table_name-.--.-------------------------.-END-EXEC-><
    +--view_name-+  +-WHERE search_conditions-+

Parameters:

host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is optional. If omitted, the current connection is deleted. If provided, and the connection specified is different than the current connection, the delete is performed on the connection associated with the DECLARE CURSOR statement.
FROM | An optional keyword. It is required for ANSI SQL 92 conformance.
table_name | The target table for the delete operation.
view_name | The target view for the delete operation.
WHERE | A standard SQL WHERE clause identifying the row to be deleted.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.

Comments:

DELETE is a standard SQL statement. See the documentation supplied with your ODBC driver for the exact syntax.

You cannot mix simple host variables with host arrays in the WHERE clause. If one of the host variables is an array, they must all be arrays.

If you do not specify a WHERE clause, all of the rows in the named table are removed.

Example:

EXEC SQL
   DELETE FROM staff WHERE staff_id = 99
END-EXEC
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
INSERT


DESCRIBE

Provides information on prepared dynamic SQL statements and describes the result set for an open cursor.

Syntax, Format 1:

>>---EXEC SQL-----DESCRIBE---.----------------------.----->
                             +---SELECT LIST FOR----+
                             +---BIND VARIABLES FOR-+

 >--.--prepared_stmt_name--.---INTO---:sqlda_struct---END-EXEC--><

Syntax, Format 2:

>>---EXEC SQL-----DESCRIBE---CURSOR---cursor_name----->

 >---INTO---:sqlda_struct---END-EXEC--><

Parameters:

prepared_stmt_name | The name of a prepared SQL SELECT statement or QUERY ODBC statement.
cursor-name | The name of an open cursor.
: sqlda_struct | A host variable that specifies the output SQLDA data structure to be populated. The colon is optional to provide compatibility with other embedded SQL implementations.

Comments:

This statement populates the specified SQLDA data structure with the data type, length, and column name of each column returned by the specified prepared statement.

If neither SELECT LIST FOR or BIND VARIABLES FOR is specified, SELECT LIST FOR is used by default. If BIND VARIABLES FOR is specified, information about input parameters is returned in the SQLDA rather than information about results columns.

The DESCRIBE statement inserts the number of columns into the sqld field of the SQLDA structure. If a non-select statement was prepared, sqld is set to 0. Before DESCRIBE is called, the following fields in the SQLDA data structure must be initialised by the application:

sqln The maximum number of sqlvar (column descriptor) entries that the structure can accommodate.
sqldabc The maximum size of the SQLDA:
  • 32-bit - Calculated as sqln * 44 + 16
  • 64-bit - Calculated as sqln * 56 + 16

If sqln is set to 0, no column descriptor entries are constructed, but sqld is set to the number of entries required. The DESCRIBE statement works in a similar way to a PREPARE statement with an INTO clause.

By default, the SQL types for date, time and timestamp are respectively DATE-RECORD, TIME-RECORD and TIMESTAMP-RECORD. When you use the BEHAVIOR=OPTIMIZED option for the SQL Compiler directive, OpenESQL mimics the DB2 on the mainframe for these data types, providing character strings (i.e., PIC X(n)) instead of the standard, default record constructs.

Note: Few drivers fully implement the ODBC calls necessary for DESCRIBE BIND VARIABLES.

Example:

      $set sql(behavior=optimized)
       working-storage section.
       EXEC SQL INCLUDE SQLCA END-EXEC.
       EXEC SQL INCLUDE SQLDA78 END-EXEC.
       EXEC SQL BEGIN DECLARE SECTION END-EXEC
       01 statement   pic x(80).
       01 host-var-block.
          03 host-var-1   pic 99.
          03 host-var-2   pic x(10).
          03 host-var-3   pic x(15).
       EXEC SQL END DECLARE SECTION END-EXEC

       PROCEDURE DIVISION.

       EXEC SQL CONNECT TO ORCL USER scott.tiger END-EXEC

       EXEC SQL
           DECLARE C1 CURSOR FOR stmt1
       END-EXEC

       move "select * from dept" to statement

       move 20 to sqln
      $IF P64 SET
       compute sqldabc = 16 + 56 * sqln
      $ELSE
       compute sqldabc = 16 + 44 * sqln
      $END

       EXEC SQL
           PREPARE stmt1 FROM :statement
       END-EXEC
       EXEC SQL
           DESCRIBE stmt1 INTO :sqlda
       END-EXEC

      * The data structure "sqlda" now contains a description
      * of the dynamic SQL statement.
       EXEC SQL
           OPEN C1
       END-EXEC

      * Complete the SQLDA, by adding buffer addresses and lengths
      * and changeing types, as necessary and appropriate, to
      * to match host variables actually used.
      *
      * The following SQL directives can reduce the amount of effort
      * required by specifying how OpenESQL should DESCRIBE varchar
      * and date/time SQL data types:
      *    DESCRIBEVARCHARPICX
      *    DESCRIBEVARCHAR49
      *    DESCRIBEDTCHAR
      *    DESCRIBEDTREC

       move ESQL-UDISP-UNSIGN to sqltype(1)
       set sqldata(1) to address of host-var-1
       set sqldata(2) to address of host-var-2
       set sqldata(3) to address of host-var-3

       perform until exit
           EXEC SQL
               FETCH C1 USING DESCRIPTOR :sqlda
           END-EXEC
           if sqlerrd(3) not = 1
               exit perform
           end-if
           display host-var-1 ' ' host-var-2 ' ' host-var-3

       end-perform
       goback.
Parent topic: Embedded SQL Statements
Related concepts
Dynamic SQL
Data Structures
Related reference
PREPARE
FETCH
INCLUDE
The DESCRIBE Statement


DISCONNECT

Closes the connection(s) to a database. In addition, all cursors opened for that connection are automatically closed.

Syntax:

>>---EXEC SQL---DISCONNECT---.-name----.----END-EXEC----><
                             +-ALL-----+
                             +-CURRENT-+
                             +-DEFAULT-+

Parameters:

name | The connection name.
ALL | Disconnects all connections (including automatic connections made when the INIT option of the SQL Compiler directive is used).
CURRENT | Disconnects the current connection. The current connection is either the most recent connection established by a CONNECT statement or a subsequent connection set by a SET CONNECTION statement.
DEFAULT | Disconnects the default connection. This is the connection made by a CONNECT statement which did not specify a connection name.

Example:

EXEC SQL CONNECT TO "srv1" AS server1 USER "sa." END-EXEC
EXEC SQL CONNECT TO "srv2" AS server2 USER "sa." END-EXEC
...
EXEC SQL DISCONNECT server1 END-EXEC
EXEC SQL DISCONNECT server2 END-EXEC.
Parent topic: Embedded SQL Statements
Related concepts
Database Connections
OpenESQL
Related reference
COMMIT
CONNECT
ROLLBACK
SET CONNECTION


END DECLARE SECTION

Terminates a host variable declaration section begun by a BEGIN DECLARE SECTION statement.

Syntax:

>>---EXEC SQL---END DECLARE SECTION---------END-EXEC----><

Example:

 WORKING-STORAGE SECTION.

 EXEC SQL BEGIN DECLARE SECTION END-EXEC
 01 staff-id        pic x(4).
 01 last-name       pic x(30).
 EXEC SQL END DECLARE SECTION END-EXEC
Parent topic: Embedded SQL Statements
Related reference
BEGIN DECLARE SECTION


EXECSP

Executes a stored procedure.

Syntax:

>>--EXEC SQL-.----------------.-EXECSP-.---------------.->
             +-FOR :host_integer-+        +-:result_hvar -+

 >-- stored_procedure_name -----.------------.------------->
                                | +-- , --+  |
                                | V       |  |
                                +(parameter)-+

 >-.----------------.------------------------END-EXEC-----<>
   +-WITH RECOMPILE-+

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
:result_hvar | A host variable to receive the procedure result.
stored_procedure_name | The name of the stored procedure.
parameter A literal or a host variable parameter of the form:
[keyword=]:param_hvar [OUT | OUTPUT]

where:

keyword | is the formal parameter name for a keyword parameter.
:param_hvar | is a host variable.
OUT | specifies an output parameter.
OUTPUT | specifies an output parameter.
WITH RECOMPILE | Is ignored and has no effect. It is allowed for syntax compatibility only.

Comments:

The EXECSP statement is an alternative to the CALL statement and provides backward compatibility with the Micro Focus Embedded SQL Toolkit for Microsoft SQL Server. Wherever possible, the CALL statement should be used in preference to EXECSP.

Do not use the FOR clause if the EXECSP is part of a DECLARE CURSOR statement.

Example:

EXEC SQL
   EXECSP myProc param1,param2
END-EXEC

EXEC SQL
   EXECSP :myResult = myFunction namedParam = :paramValue
END-EXEC

EXEC SQL
   EXECSP getDept :empName, :deptName OUT
END-EXEC

EXEC SQL
   DECLARE cities CURSOR FOR EXECSP locateStores :userState
END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Working with Stored Procedures and Result Sets
Related reference
CALL
DECLARE CURSOR


EXECUTE

Processes dynamic SQL statements.

Syntax:

>>-EXEC SQL-----.-------------------.------EXECUTE------>
                +--FOR :host_integer---+

 >-prepared_stmt_name-.--------------------------------.->
                      +-USING DESCRIPTOR :sqlda_struct-+
                      |       +- , -+                  |
                      |       V     |                  |
                      +-USING :hvar--------------------+

 >-----END-EXEC-----<>

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
prepared_stmt_name | A previously prepared SQL statement.
:sqlda_struct | A previously declared SQLDA data structure containing a description of the input values. The colon is optional to provide compatibility with other embedded SQL implementations.
:hvar | One or more input host variables.

Comments:

Do not use the FOR clause if the EXECUTE is part of a DECLARE CURSOR statement.

The EXECUTE statement runs the specified prepared SQL statement after substituting values for any parameter markers. (Prepared statements are created using the PREPARE statement.) Only statements that do not return results are permitted.

If the prepared statement contains parameter markers, the EXECUTE statement must include either the USING :hvar option with the same number of host variables or the USING DESCRIPTOR :sqlda_struct option identifying a SQLDA data structure already populated by the application.

The number of parameter markers in the prepared statement must match the number of sqldata entries (USING DESCRIPTOR :sqlda) or host variables (USING :hvar).

Example:

* Store statement to be dynamically executed...
     MOVE "INSERT INTO staff VALUES(?,?,?,?,?)" TO stmtbuf.

* Ensure attempt is not made to insert an existing record
     EXEC SQL
        DELETE FROM staff WHERE staff_id = 99
     END-EXEC

* Prepare the statement
     EXEC SQL
        PREPARE st FROM :stmtbuf
     END-EXEC.

     MOVE 99 TO staff-id
     MOVE 'Lee' TO last-name
     MOVE 'Phil' TO first-name
     MOVE 19 TO age
     MOVE '1997-01-01' TO employment-date

* Execute the statement with current values.
     EXEC SQL
        EXECUTE st USING :staff-id, :last-name
                        ,:first-name, :age, :employment-date
     END-EXEC
     IF SQLCODE = ZERO
        DISPLAY 'Statement executed.'
     ELSE
        DISPLAY 'Error: Could not execute statement.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Finally, remove the entry
     EXEC SQL
        DELETE FROM staff where staff_id = 99
     END-EXEC
     IF SQLCODE = ZERO
        DISPLAY 'Values deleted.'
     ELSE
        DISPLAY 'Error: Could not delete inserted values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF
Parent topic: Embedded SQL Statements
Related concepts
Dynamic SQL
Related reference
DECLARE DATABASE
EXECUTE IMMEDIATE
PREPARE
INCLUDE
QUERY ODBC


EXECUTE IMMEDIATE

Immediately executes the SQL statement.

Syntax:

>>--EXEC SQL--.-------------------.--EXECUTE IMMEDIATE-->
              +--FOR :host_integer---+

 >----:stmt_hvar----END-EXEC-<>

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
:stmt_hvar | A character string host variable.

Comments:

Do not use the FOR clause if the EXECUTE IMMEDIATE is part of a DECLARE CURSOR statement.

The EXECUTE IMMEDIATE statement cannot contain input parameter markers or host variables. It cannot return results; any results returned from this statement are discarded. Additionally, the statement cannot contain SQL keywords that pertain exclusively to Embedded SQL.

If any rows are returned, SQLCODE is set to +1.

EXECUTE IMMEDIATE must be used for SET statements specific to the Microsoft SQL Server, that is, those that are intended to execute at that server.

Example:

     EXEC SQL
        DELETE FROM staff WHERE staff_id = 99
     END-EXEC

* Put the required SQL statement in prep.
     MOVE   "insert into staff (staff_id, last_name, first_name ,age,
-           "employment_date) VALUES (99, 'Lee', 'Phillip', 19, '1992-
-           "01-02')" TO prep

* Note EXECUTE IMMEDIATE does not require the statement to be
* prepared
     EXEC SQL
        EXECUTE IMMEDIATE :prep
     END-EXEC

* Check it worked...
     IF SQLCODE = ZERO
        DISPLAY 'Statement executed OK.'
     ELSE
        DISPLAY 'Error: Statement not executed.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Run through the same procedure again, this time deleting the
* values just inserted
     MOVE "delete from staff where staff_id = 99" TO prep
     EXEC SQL
        EXECUTE IMMEDIATE :prep
     END-EXEC

     IF SQLCODE = ZERO
        DISPLAY 'Statement executed OK.'
     ELSE
        DISPLAY 'Error: Statement not executed.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF
Parent topic: Embedded SQL Statements
Related concepts
Keywords
Dynamic SQL
Data Structures
Related reference
DECLARE DATABASE
EXECUTE
INCLUDE
PREPARE
QUERY ODBC


FETCH

Retrieves a row from the cursor's results set and writes the values of the columns in that row to the corresponding host variables (or to addresses specified in the SQLDA data structure).

Syntax:

>>--EXEC SQL--.-------------------.------->
              +-FOR :host_integer-+

 >-----.-------------.--FETCH---.-------------.-->
       +-AT db_name--+          +---PREVIOUS--+
                                +---LAST------+
                                +---PRIOR-----+
                                +---FIRST-----+
                                +---NEXT------+

 >-----cursor_name---.-------------------------------------.------->
                     +-USING DESCRIPTOR :sqlda_struct------+
                     |       +--------------------------,-+|
                     |       V                            ||
                     +-INTO--.-:hvar----------------------.+
                             +-:hvar:ivar-----------------+
                             +-:hvar-.-----------.-:ivar--+
                                     +-INDICATOR-+

 >--END EXEC--><

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement. Provided for backward compatibility.
cursor_name | A previously declared and opened cursor.
:sqlda_struct | An SQLDA data structure previously populated by the DESCRIBE statement and containing output value addresses. This option is used only with a cursor declared by a prepared SELECT statement. (SELECT statements are prepared using the PREPARE statement.) The colon is optional to provide compatibility with other embedded SQL implementations.
:hvar | Identifies one or more host variables to receive the data.
:ivar Specifies either of the following:
  • One or more host variables, each separated by a comma
  • One or more host variable+indicator variable combinations, each combination separated by a comma

Comments:

By default, the FETCH statement retrieves the next row, but you can also specify the previous row or last row or prior row or first row. If there are no more rows to fetch SQLCODE is set to 100 and SQLSTATE is set to "02000".

An OPEN cursor_name statement must precede a FETCH statement, and the cursor must be open while FETCH runs. If you use PREVIOUS, LAST, PRIOR, FIRST or NEXT, you must also set the appropriate cursor options via the DECLARE CURSOR statement or the SET SCROLLOPTION and SET CONCURRENCY statements. Also, the data type of the host variable must be compatible with the data type of the corresponding database column.

If the number of columns is less than the number of host variables, the value of SQLWARN3 is set to W. If an error occurs, no further columns are processed. (Processed columns are not undone.)

Alternatively, the :hvar variable can specify a COBOL record that contains several fields, each corresponding to a column in the select list of the cursor declaration statement. To use this form, you must specify the DB2 option of the SQL Compiler directive. (Note that this will cause PREPARE INTO and DESCRIBE statements to be rejected by the COBOL compiler).

If ANSI92ENTRY is set, then attempting to fetch a null value will set SQLCODE to -19425 if there is no null indicator. If ANSI92ENTRY is not set, SQLCODE will be 0. In both cases, SQLSTATE will be 22002 and SQLWARN2 will be W.

If one of the host variables in the INTO clause is an array, they must all be arrays.

Comments:

After execution, SQLERRD(3) contains the number of elements processed. For FETCH it is the number of rows actually fetched.

Example:

* Declare a cursor for a given SQL statement.
     EXEC SQL DECLARE C1 CURSOR FOR
        SELECT last_name, first_name FROM staff
     END-EXEC

     EXEC SQL OPEN C1 END-EXEC

* Fetch the current values from the cursor into the host variables
* and if everything goes ok, display the values of the host
* variables
     PERFORM UNTIL SQLCODE NOT = ZERO
        EXEC SQL
           FETCH C1 INTO :lname,:fname
        END-EXEC
        IF SQLCODE NOT = ZERO AND SQLCODE NOT = 100
           DISPLAY 'Error: Could not perform fetch'
           DISPLAY SQLERRML
           DISPLAY SQLERRMC
           EXEC SQL DISCONNECT ALL END-EXEC
           STOP RUN
        END-IF
        DISPLAY 'First name: 'fname
        DISPLAY 'Last name : 'lname
        DISPLAY SPACES
     END-PERFORM
Parent topic: Embedded SQL Statements
Related concepts
Working with Stored Procedures and Result Sets
Working With OpenESQL Cursors and Result Sets
Cursors
Data Structures
Related reference
BEGIN DECLARE SECTION
CLOSE
DECLARE CURSOR
DELETE (Positioned)
DESCRIBE
OPEN
PREPARE
SELECT DISTINCT (using DECLARE CURSOR)
UPDATE (Positioned)


GET CONNECTION

Places an OpenESQL connection object into the supplied host variable such that the objects can then be shared with other JDBC programs.

Syntax:

>>--EXEC SQL---GET CONNECTION--.-----------------.--INTO :conn_obj_hv---------->
                               +-connection_name-+
                               +- :conn_name_hv -+
 >--END-EXEC----><

Parameters:

connection_name | The connection name OpenESQL uses to refer to the JDBC connection object.
conn_name_hv | Host variable which contains the connection name OpenESQL uses to refer to the JDBC connection object.
conn_obj_hv | Host variable where the current OpenESQL JDBC connection object is placed.

Example:

     EXEC SQL
        GET CONNECTION INTO :con
     END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Sharing Database Connections Between Java and COBOL


GET HDBC

Enables you to use ODBC calls that require you to supply the ODBC connection handle.

Syntax:

>>---EXEC SQL---GET HDBC---INTO---:hvar---END-EXEC---->

Parameters:

hvar A host variable to store the ODBC connection handle. Must be declared as PIC X(4) COMP-5.

Example:

EXEC SQL
    GET HDBC INTO :hvar
END-EXEC
Parent topic: Embedded SQL Statements
Related reference
GET HENV


GET HENV

Enables you to use ODBC calls that require you to supply the ODBC environment handle.

Syntax:

>>---EXEC SQL---GET HENV---INTO---:hvar---END-EXEC---->

Parameters:

hvar A host variable to store the ODBC environment handle. Must be declared as PIC X(4) COMP-5.

Example:

EXEC SQL
    GET HENV INTO :HENV
END-EXEC
Parent topic: Embedded SQL Statements
Related reference
GET HDBC
GET HENV


GET NEXT RESULT SET

Makes the next result set available to an open cursor.

Syntax:

>>---EXEC SQL---.------------.--->
                +-AT db_name-+

 >--GET NEXT RESULT SET FOR---cursor_name---END-EXEC---><

Parameter:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.
cursor_name | A previously declared and opened cursor.

Comments:

For client applications compiled without DIALECT=MAINFRAME, GET NEXT RESULT SET makes the next result set available when retrieving multiple result sets from a stored procedure or from a DECLARE CURSOR statement defined with multiple SELECT statements.

If additional result sets are not available, GET NEXT RESULT SET returns an SQLCODE of 100 and sets SQLSTATE to 02000.

Example:

           exec sql declare c cursor for
               call TestProc2(:hv-country)
           end-exec

           exec sql open c end-exec

           display " "
           display "First result set from proc"
           display " "

           perform until exit
               exec sql fetch c into
                   :CustomerID, :Company, :City
               end-exec
               if sqlcode = 100 or sqlcode < 0
                   exit perform
               end-if
               display CustomerID " " City
           end-perform

            *> Always get SQLCODE 100 at the end of a result set
            *> until you close the cursor or ask for another result set
            exec sql fetch c into
                :CustomerID, :Company, :City
            end-exec
            if sqlcode not  = 100
                display "FAIL: Fetch after SQLCODE 100 OK"
            end-if

            *> Ask for another result set, SQLCODE 100 if there isn't one
            exec sql get next result set for c end-exec

            display " "
            display "Second result set from proc"
            display " "

            perform until exit
               exec sql fetch c into
                   :CustomerID, :Company, :City
               end-exec
               if sqlcode = 100 or sqlcode < 0
                   exit perform
               end-if
               display CustomerID " " City
            end-perform
Parent topic: Embedded SQL Statements
Related concepts
Working with Stored Procedures and Result Sets
Working With OpenESQL Cursors and Result Sets
Related reference
CLOSE


INCLUDE

Includes the definition of the specified SQL data structure or source file in the COBOL program.

Syntax:

>>---EXEC SQL---INCLUDE-----.-SQLCA----.----END-EXEC----><
                            +-SQLDA----+
                            +-filename-+

Parameters:

SQLCA | Indicates that a SQLCA data structure is accessed.
SQLDA | Indicates that a SQLDA data structure is accessed.
filename | Indicates that a file should be included in the source at this point (this is equivalent to the COBOL COPY facility).

Comment:

This statement uses the corresponding .cpy file. Ensure that sqlca.cpy and sqlda.cpy are in the current directory or that the COBCPY environment variable specifies the directory that contains them.

Example:

EXEC SQL INCLUDE SQLCA END-EXEC
EXEC SQL INCLUDE SQLDA END-EXEC
EXEC SQL INCLUDE MYFILE END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Data Structures
Related reference
DESCRIBE
EXECUTE
EXECUTE IMMEDIATE
OPEN
PREPARE


INSERT

Adds new rows to a table.

Syntax:

>>--EXEC SQL--.-------------------.---------->
              +-FOR :host_integer-+

 >---.------------.--INSERT--.------.---.-table_name-.--->
     +-AT db_name-+          +-INTO-+   +-view_name--+

                                +-------- , ------+
                                V                 |
 >---.---------------.--VALUES (constant_expression)----->
     +-(column_list)-+

 >------END-EXEC---><

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is optional. If omitted, the current connection executes the insert. If provided, and the connection specified is different than the current connection, the insert is performed on the connection associated with the DECLARE CURSOR statement.
table_name | The table into which rows are to be inserted.
view_name | The view into which rows are to be inserted.
INTO | An optional keyword. Required for ANSI SQL 92 conformance.
column_list | A list of one or more columns to which data is to be added. The columns can be in any order, but the incoming data must be in the same order as the columns. The column list is necessary only when some, but not all, columns in the table are to receive data. Enclose the items in the column list in parentheses. If no column list is given, all the columns in the receiving table (in CREATE TABLE order) are assumed. The column list determines the order in which values are entered.
VALUES | Introduces a list of constant expressions.
constant_expression | Constant or null values for the indicated columns. The values list must be enclosed in parentheses and must match the explicit or implicit columns list. Enclose non-numeric constants in single or quotation marks.

Comments:

The INSERT statement is passed directly to the ODBC driver. See the documentation supplied with your ODBC driver for the exact syntax.

If the host variables in the WHERE clause are arrays, the INSERT statement is executed once for each set of array elements.

Uuse UPDATE to modify column values in an existing row.

You can omit items in the column list and VALUES list providing that the omitted columns are defined to allow null values.

You can select rows from a table and insert them into the same table in a single statement.

After execution, SQLERRD(3) contains the number of elements processed. For INSERT it is the total number of rows inserted.

Example:

     DISPLAY "Enter new staff member's id:"
     ACCEPT staff-id

     DISPLAY "Enter new staff member's last name:"
     ACCEPT last-name

     DISPLAY "Enter new staff member's first name:"
     ACCEPT first-name

     DISPLAY "Enter new staff member's age:"
     ACCEPT age

     DISPLAY "Enter new staff member's employment date(yyyy/mm/dd):"
     ACCEPT employment-date

     EXEC SQL
        INSERT INTO staff
        (staff_id
       ,last_name
       ,first_name
      ,age
       ,employment_date)
        VALUES
        (:staff-id
       ,:last-name
       ,:first-name
       ,:age
       ,:employment-date)
     END-EXEC
Parent topic: Embedded SQL Statements
Related reference
DELETE (Positioned)
DELETE (Searched)
UPDATE (Positioned)
UPDATE (Searched)


INTO

Retrieves one row of results and assigns the values of the items returned by an OUTPUT clause in a SQL Server INSERT, UPDATE, or DELETE statement to the host variables specified in the INTO list.

Syntax:

>>---EXEC SQL--.-------------------.---.------------.---->
               +-FOR :host_integer-+   +-AT db_name-+
           +- ,-+
           V    |
 >---INTO--:hvar--result-set-generating-dml-statement---->

 >---END-EXEC---><

Parameters:

host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
db_name | The name of a database that has been declared using DECLARE DATABASE.
hvar | A host variable to store the ODBC connection handle. Must be declared as PIC X(4) COMP-5.
result-set-generating-dml-statement | A SQL Server INSERT, non-positioned UPDATE, or DELETE statement with an OUTPUT clause.

Comments:

INTO is supported for SQL Server only.

Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
SELECT INTO


OPEN

Runs the SELECT statement specified in the corresponding DECLARE CURSOR statement to produce the results set that is accessed one row at a time by the FETCH statement.

Syntax:

>>--EXEC SQL---OPEN---cursor_name------------------------>

 >----.--------------------------------.----END-EXEC-----><
      +-USING DESCRIPTOR :sqlda_struct-+
      |       +- , -+                  |
      |       V     |                  |
      +-USING :hvar--------------------+

Parameters:

cursor_name | A previously declared cursor.
:sqlda_struct | An SQLDA data structure previously constructed by the application. The SQLDA data structure contains the address, data type, and length of each input parameter. This option is used only with a cursor that references a prepared SQL statement in the DECLARE statement. The colon is optional to provide compatibility with other embedded SQL implementations.
:hvar | One or more input host variables corresponding to parameter markers in the SELECT statement. This option is used only with a cursor that references a prepared SQL statement in the DECLARE statement.

Comments:

If the cursor is declared with a static SELECT statement (that is, one that was not prepared), the SELECT statement can contain host variables but not parameter markers . The current values of the host variables are substituted when the OPEN statement runs. For a statically declared cursor, the OPEN statement cannot contain the USING :hvar or USING DESCRIPTOR :sqlda_struct option.

If the cursor is declared with a dynamic SELECT statement (that is, one that was prepared), the SELECT statement can contain parameter markers but not host variables. Parameter markers can appear wherever column values are allowed in the SELECT statement. If the SELECT statement has parameter markers, the OPEN statement must include either the USING :hvar option with the same number of host variables or the USING DESCRIPTOR :sqlda_struct option identifying an SQLDA data structure already populated by the application.

With the USING DESCRIPTOR :sqlda_struct option, values of the program variables are substituted for parameter markers in the SELECT statement. These program variables are addressed by corresponding SQLDATA entries in the SQLDA data structure.

The number of parameter markers in the SELECT statement must match the number of sqldata entries (USING DESCRIPTOR :sqlda_struct) or host variables (USING :hvar) in the OPEN statement.

Example:

*Declare the cursor...
     EXEC SQL
     DECLARE C1 CURSOR FOR
        SELECT staff_id, last_name
        FROM staff
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not declare cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL
        OPEN C1
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not open cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

     PERFORM UNTIL sqlcode NOT = ZERO
*SQLCODE will be zero as long as it has successfully fetched data
        EXEC SQL
           FETCH C1 INTO :staff-staff-id, :staff-last-name
        END-EXEC
        IF SQLCODE = ZERO
          DISPLAY "Staff ID: " staff-staff-id
           DISPLAY "Staff member's last name: " staff-last-name
        END-IF
     END-PERFORM

     EXEC SQL
        CLOSE C1
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not close cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
     END-IF
Restriction: The following scenario can cause the COBOL compiler to fail to update output host variables when the cursor for a stored procedure call is closed. This can happen when stored procedures meet all three of the following criteria:
  • Are called using the OPEN statement
  • Return a return value, output parameters, or both
  • Return a result set

The failure occurs because the COBOL compiler, when possible, compiles 01-level fields and their subordinate 01-level FILLER fields as JVM types.

To ensure successful compilation, use traditional COBOL data types, such as PIC X(n), COMP-3, etc., for host variables rather than object types, such as string, binary-long, BigDecimal, etc., and do one of the following:

  • Compile using the NOILNATIVE COBOL compiler directive
  • Declare host variables that receive return values or output parameters at level 02 or higher, with a record name other than FILLER

This scenario does not apply to stored procedures called using the CALL statement.

Parent topic: Embedded SQL Statements
Related concepts
Cursors
Data Structures
Dynamic SQL
Working with Stored Procedures and Result Sets
Related reference
CLOSE
DECLARE CURSOR
FETCH
INCLUDE
QUERY ODBC


PERSIST

Saves information defined in a cursor SELECT statement as XML files.

Syntax:

>>-EXEC SQL--.------------.--->
                     +-AT db_name-+

 >--PERSIST cursor_name TO xml_destination--->

 >-----END-EXEC-----<>

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.
cursor_name | A previously declared and opened cursor.
xml_destination | An identifier, a host variable, or a literal enclosed in single or double quotes

Comments:

To use PERSIST, you must:
  • Have an XML ODBC driver installed
  • Embed the SET SCROLLOPTION statement and set it to STATIC

If you are using Data Direct Connect ODBC drivers, you must use version 3.70 or later.

Example:

 01  hv  pic x(50).
 procedure-division.

    *> set whenever clause to handle sql errors
    exec sql whenever sqlerror goto sql-error end-exec
    exec sql whenever sqlwarning perform sql-warning end-exec

    *> connect to data source
    exec sql connect to "data source"  end-exec

    *> declare static cursor with column info you want to save to xml file
    exec sql
      declare c static cursor for
        select * from emp
    end-exec

    *> open cursor
    exec sql open c end-exec

    *> save data to xml file using double quoted literal
    exec sql
      persist c to "c:\XML Files\xmltest1.xml"
    end-exec

    *> save data to xml file using single quoted literal
    exec sql
      persist c to 'c:\XML Files\xmltest2.xml'
    end-exec

    *> save data to xml file using a host variable
    move "c:\XML Files\xmltest3.xml" to hv
    exec sql
      persist c to :hv
    end-exec

    *> close the cursor
    exec sql close c end-exec

    *> disconnect from datasource
    exec sql disconnect current end-exec

    goback.
Parent topic: Embedded SQL Statements
Related concepts
XML Support
Related reference
SET SCROLLOPTION


PREPARE

Processes dynamic SQL statements.

Syntax:

>>--EXEC SQL---PREPARE---stmt_name---.-------------.----->
                                     +-INTO :sqlda-+

 >---FROM---:hvar---END-EXEC-----><

Parameters:

stmt_name | The prepared statement name. This can be used by a subsequent EXECUTE or OPEN statement, and/or a previous DECLARE CURSOR statement.
:sqlda | The output SQL descriptor area (SQLDA) data structure to be populated. The colon is optional to provide compatibility with other embedded SQL implementations.
:hvar | The host variable that contains the SQL statement.

Comments:

You can use a prepared statement in one of two ways:

  • You can open a cursor that references a prepared statement.
  • You can execute a prepared statement.

If the prepared statement is used by an EXECUTE statement, :hvar cannot contain a SQL statement that returns results.

Because singleton SELECT statements (SELECT INTO) are not allowed in dynamic SQL statements, they cannot be prepared.

When using PREPARE, the SQL statement in :hvar cannot contain host variables or comments, but it can contain parameter markers. Also, the SQL statement cannot contain SQL keywords that pertain exclusively to Embedded SQL.

The INTO :sqlda option merges the functionality of DESCRIBE and PREPARE so that this example code:

 EXEC SQL
     PREPARE stmt1 INTO :sqlda FROM :stmt-buf
 END-EXEC

is identical to:

 EXEC SQL
     PREPARE stmt1 FROM :stmt-buf
 END-EXEC
 EXEC SQL
     DESCRIBE stmt1 INTO :sqlda
 END-EXEC

For more details about using the PREPARE statement, see your Database Access Guide.

Example:

 PROGRAM-ID. progname.

 WORKING-STORAGE SECTION.
 EXEC SQL INCLUDE SQLCA END-EXEC
 EXEC SQL BEGIN DECLARE SECTION END-EXEC
 01 prep           PIC X(80).
 01 nme            PIC X(20).
 01 car            PIC X(20).
 01 n60            PIC x(5).
 EXEC SQL END DECLARE SECTION END-EXEC.

 PROCEDURE DIVISION.
     EXEC SQL CONNECT TO 'srv1' USER 'sa' END-EXEC
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not connect to database.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRMC
        STOP RUN
     END-IF

* Ensure attempt is not made to recreate an existing table...
     EXEC SQL DROP TABLE mf_table END-EXEC

* Create a table...
     EXEC SQL CREATE TABLE mf_table
                 (owner          char(20)
                 ,car_col        char(20)
                 ,nought_to_60   char(5))
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not create table'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

* Insert an SQL statement into host variable prep...
     MOVE "insert into mf_table values(?,?,?)" TO prep

* Prepare the statement...
     EXEC SQL
        PREPARE prep_stat FROM :prep
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not prepare statement'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

     MOVE "Owner" TO nme
     MOVE "Lamborghini" TO car
     MOVE "4.9" TO n60

* Execute the prepared statement using the above host variables...
     EXEC SQL
        EXECUTE prep_stat USING :nme, :car, :n60
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not execute prepared statement.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

* Finally, drop the now unwanted table...
     EXEC SQL
        DROP TABLE mf_table
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not drop table.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT CURRENT END-EXEC
        STOP RUN
     END-IF

     DISPLAY 'All statements executed.'
     EXEC SQL DISCONNECT CURRENT END-EXEC
     STOP RUN.
Parent topic: Embedded SQL Statements
Related concepts
Data Structures
Dynamic SQL
Related reference
DECLARE CURSOR
DECLARE DATABASE
DESCRIBE
EXECUTE
FETCH
INCLUDE
EXECUTE IMMEDIATE
QUERY ODBC


QUERY ODBC

Delivers a results set in the same way as a SELECT statement, and must therefore be associated with a cursor via DECLARE and OPEN, or DECLARE, PREPARE and OPEN.

Syntax, Format 1:

>>--EXEC SQL---QUERY ODBC---.-COLUMN--.------------------>
                            +-COLUMNS-+

 >---.--------------------------.--.------------------.--->
     +-QUALIFIER qualifier_name-+  +-OWNER owner_name-+

 >--.----------------------.--.------------------------.-->
    +-TABLENAME table_name-+  +-COLUMNNAME column_name-+

 >---END-EXEC---<>

Syntax, Format 2:

>>--EXEC SQL---QUERY ODBC---.-DATATYPE--.---------------->
                            +-DATATYPES-+

 >---.-------------------------.---END-EXEC---><
     +-TYPE--.-datatype_name--.+
             +-BIGINT---------+
             +-BINARY---------+
             +-BIT------------+
             +-CHAR-----------+
             +-DATE-----------+
             +-DECIMAL--------+
             +-DOUBLE---------+
             +-FLOAT----------+
             +-INTEGER--------+
             +-LONG VARBINARY-+
             +-LONG VARCHAR---+
             +-NUMERIC--------+
             +-REAL-----------+
             +-SMALLINT-------+
             +-TIME-----------+
             +-TIMESTAMP------+
             +-TINYINT--------+
             +-VARBINARY------+
             +-VARCHAR--------+

Syntax, Format 3:

>>--EXEC SQL---QUERY ODBC---.-TABLE--.------------------>
                            +-TABLES-+
>---.--------------------------.--.------------------.--->
    +-QUALIFIER qualifier_name-+  +-OWNER owner_name-+

 >--.----------------------.--.------------------------.-->
    +-TABLENAME table_name-+  +-TYPE tabletype_name----+

 >--END-EXEC--<>

Parameters:

qualifier_name | A host variable, identifier or literal which specifies a qualifier to be used to select tables. Not all ODBC drivers support qualifiers, and those that do may use them in different ways. For example, if a data source supports multiple databases, a qualifier can be used to specify which database to use. Alternatively, for drivers providing access to file based data sources, a qualifier can be used to specify a particular directory to be searched.
owner_name | A host variable, identifier or literal which specifies a table owner to be used to select tables. Not all ODBC drivers support table ownership.
table_name | A host variable, identifier or literal which specifies tables to be included in the query.
datatype_name | A host variable, identifier or literal which specifies a data type to be queried.
tabletype_name | A host variable, identifier or literal which specifies a list of table types to be included in the query.

Comments:

Search patterns consist of the legal characters for SQL identifiers plus underscore (_) which matches any single character, percent (%) which matches any sequence of zero or more characters, or a driver defined escape character which can be used to allow underscore or percent in a pattern to represent themselves rather than a wildcard.

If a search pattern parameter is not supplied, a pattern of % is used, which will match all relevant dictionary entries.

For table queries the following special rules apply:

  • If qualifier-name is % and owner-name and table-name are empty strings, the results set consists of a list of valid qualifiers at the data source. All columns apart from TABLE_QUALIFIER in the results set (see below) will be null.
  • If owner-name is % and qualifier-name and table-name are empty strings, the results set consists of a list of valid owners at the data source. All columns apart from TABLE_OWNER in the results set (see below) will be null.
  • If tabletype-name is % and qualifier-name, owner-name and table-name are empty strings the results set consists of a list of valid table types at the data source. All columns apart from TABLE_TYPE in the results set (see below) will be null.
  • If tabletype-name is not specified, tables of all types will be returned in the results set. If it is specified it must consist of a comma separated list of table types, for example'TABLE,VIEW'.

Example:

     EXEC SQL
        DECLARE tcurs CURSOR FOR QUERY ODBC TABLES
     END-EXEC

     EXEC SQL DECLARE C1 CURSOR FOR
        QUERY ODBC TABLES OWNER :tab-owner TABLETYPE 'TABLE,VIEW'
     END-EXEC

     MOVE 'staff' to tab-name
     EXEC SQL DECLARE C2 CURSOR FOR
        QUERY ODBC COLUMNS TABLENAME :tab-name
     END-EXEC

     EXEC SQL DECLARE C3 CURSOR FOR
        QUERY ODBC DATATYPES
     END-EXEC
  • QUERY ODBC - Column Query
  • QUERY ODBC - Data Type Query
  • QUERY ODBC - Table Query
Parent topic: Embedded SQL Statements
Related concepts
Cursors
Dynamic SQL
Related reference
DECLARE CURSOR
EXECUTE
EXECUTE IMMEDIATE
PREPARE
OPEN


QUERY ODBC - Column Query

The results set for a column query is:

TABLE_QUALIFIER | VARCHAR(128) |
TABLE_OWNER | VARCHAR(128) |
TABLE_NAME | VARCHAR(128) NOT NULL |
COLUMN_NAME | VARCHAR(128) NOT NULL |
DATA_TYPE | SMALLINT NOT NULL | See odbcext.cpy and odbc.cpy for constants representing the ODBC data type codes.
TYPE_NAME | VARCHAR(128) NOT NULL | Driver dependent name for the column's data type.
PRECISION | INTEGER |
LENGTH | INTEGER | Amount of memory required for a column value in its native representation.
SCALE | SMALLINT |
RADIX | SMALLINT | For numeric columns either 10 or 2 depending on the data type; otherwise null
NULLABLE | SMALLINT NOT NULL |
REMARKS | VARCHAR(254) |
Parent topic: QUERY ODBC


QUERY ODBC - Data Type Query

The results set for a data type query is:

TYPE_NAME | VARCHAR(128) NOT NULL | Driver dependent name for the column's data type
DATA_TYPE | SMALLINT NOT NULL | See odbcext.cpy and odbc.cpy for constants representing the ODBC data type codes.
PRECISION | INTEGER | Maximum precision for columns of this type.
LITERAL_PREFIX | VARCHAR(128) | Character or characters required to prefix literal values for this type.
LITERAL_SUFFIX | VARCHAR(128) | Character or characters required to suffix literal values for this type.
CREATE_PARAMS | VARCHAR(128) | Parameters required when creating a column of this type, for example, 'precision,scale' for decimal types.
NULLABLE | SMALLINT NOT NULL |
CASE_SENSITIVE | SMALLINT NOT NULL | Specifies case sensitivity in comparisons for character data types.
SEARCHABLE | SMALLINT NOT NULL | SQL_UNSEARCHABLE, SQL_LIKE_ONLY or SQL_ALL_EXCEPT_LIKE (these are defined in odbc_cpy).
UNSIGNED_ATTRIBUTE | SMALLINT | Specifies if a numeric type is signed or unsigned.
MONEY | SMALLINT NOT NULL | Specifies if a numeric type is a money data type.
AUTO_INCREMENT | SMALLINT | Specifies if the data type is auto incrementing .
LOCAL_TYPE_NAME | VARCHAR(128) | Localized version of the data type name.
MINIMUM_SCALE | SMALLINT |
MAXIMUM_SCALE | SMALLINT |
Parent topic: QUERY ODBC


QUERY ODBC - Table Query

The results set for a table query is:

TABLE_QUALIFIER | VARCHAR(128) |
TABLE_OWNER | VARCHAR(128) |
TABLE_NAME | VARCHAR(128) |
TABLE_TYPE | VARCHAR(128) | One of TABLE, VIEW, SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS, SYNONYM or a data source specific type identifier
REMARKS | VARCHAR(254) |
Parent topic: QUERY ODBC


RESET CONNECTION

Closes all open cursors, even if the application has not appropriately closed them.

Syntax:

>>---EXEC SQL---RESET CONNECTION---END-EXEC---><

Comments:

Use RESET CONNECTION in the XA switch modules provided for Enterprise Server environments to ensure that all cursors have been closed before a new unit of work is started.

In Enterprise Server environments, RESET CONNECTION ensures that all database locks acquired are released if the application fails to close cursors explicitly.

Parent topic: Embedded SQL Statements


ROLLBACK

Backs out any changes made to the database by the current transaction on the current connection, or partially rolls back changes to a previously set save point.

Syntax:

>>---EXEC SQL---.------------.--->
                +-AT db_name-+

 >--ROLLBACK----.--------------.--------->
                +-WORK---------+
                +-TRAN---------+
                +-TRANSACTION--+

 >---.-----------.---END-EXEC---><
     +--RELEASE--+
     +--TO-.-----------.-name--+
           +-SAVEPOINT-+

Parameter:

AT db_name The name of a database that has been declared using DECLARE DATABASE. This clause is optional. If omitted, the current connection is rolled back. If provided, and the connection specified is different than the current connection, the rollback is performed on the connection associated with the DECLARE CURSOR statement.

Comments:

When RELEASE is specified and the transaction is successfully rolled back, the current connection is closed.

TO [SAVEPOINT] rolls the transaction back just to the save point specified by name, which must be set by a preceding SAVEPOINT statement.

Example:

EXEC SQL
   ROLLBACK
END-EXEC

EXEC SQL
    ROLLBACK WORK RELEASE
END-EXEC

END-EXEC

EXEC SQL
    ROLLBACK TO SP1
END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Managing Transactions
Related reference
COMMIT
CONNECT
DISCONNECT
SET CONNECTION
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT


SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT

Sets a transaction save point to which a current transaction can be rolled back, resulting in a partial roll back.

Syntax:

>>---EXEC SQL--.------------.--SAVEPOINT-name--.------.-->
               +-AT db_name-+                  +UNIQUE+

 >--.-----------------------------------------------------------.---END-EXEC---><
    +--ON ROLLBACK RETAIN CURSORS--.----------------------------+
                                   +--ON ROLLBACK RETAIN LOCKS--+

>>---EXEC SQL--.------------.--SAVE-.-TRANSACTION--.--name-- END-EXEC---><
               +-AT db_name-+       +-TRAN---------+

>>---EXEC SQL--.------------.--RELEASE-.----.-SAVEPOINT-name---END-EXEC---><
               +-AT db_name-+          +-TO-+

Parameter:

AT db_name The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.

Restrictions:

Because SQL Server does not allow save points with fire hose cursors,

Comments:

You can define multiple save points for a single transaction.

When you set a save point using a unique name, and subsequently set another save point using the same unique name, the named save point is reset to the current transaction state.

The behavior of cursors and locks after a rollback to a save point is database-specific. For details, see the documentation provided by your database vendor.

Example:

EXEC SQL
   SAVEPOINT SP1
END-EXEC

EXEC SQL
    SAVEPOINT PHASE2 ON ROLLBACK RETAIN CURSORS
END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Managing Transactions
Related reference
COMMIT
ROLLBACK
PF_RO_CURSOR
BEHAVIOR


SELECT DISTINCT (using DECLARE CURSOR)

Associates the cursor name with the SELECT DISTINCT statement and enables you to retrieve rows of data using the FETCH statement.

Syntax:

>>---EXEC SQL--.------------.------DECLARE cursor_name---->
               +-AT db_name-+

 >---CURSOR FOR------SELECT DISTINCT------select_list------>

 >---FROM----table_list--.-----------------2--END-EXEC----><
                         +-select_options--+

Parameters:

db_name | The name of a database that has been declared using DECLARE DATABASE.
cursor_name | Cursor name used to identify the cursor in subsequent statements. Cursor names can contain any legal filename character and be up to 30 characters in length. The first character must be a letter.
select_list | The name of the columns to retrieve.
table_list | The name of the tables that contain the columns to be retrieved, as specified in select_list.
select_options | The options specified to limit the number of rows retrieved and/or order the rows retrieved.

Comments:

Two separately compiled programs cannot share the same cursor. All statements that reference a particular cursor must be compiled together.

The SELECT DISTINCT statement runs when the cursor is opened. The following rules apply to the SELECT DISTINCT statement:

  • The statement cannot contain an INTO clause or parameter markers.
  • The statement can contain input host variables previously identified in a declaration section.
  • With some ODBC drivers, the SELECT DISTINCT statement must include a FOR UPDATE clause if positioned updates or deletions are to be performed.
Note:

Use SELECT DISTINCT instead of SELECT INTO to remove duplicate rows in the row set.

Example:

 01 age-array        pic s9(09) comp-5 occurs 10 times.
 01 lname-array      pic x(32)   occurs 10 times.

    MOVE 5 TO staff-id
    EXEC SQL
       SELECT DISTINCT last_name
          INTO :lname-array
          FROM staff
          WHERE staff_id > :staff-id
    END-EXEC

    EXEC SQL
       SELECT DISTINCT age
          INTO :age-array
          FROM staff
          WHERE first_name > 'George'
    END-EXEC
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
FETCH
SELECT INTO


SELECT INTO

Retrieves one row of results and assigns the values of the items in a specified SELECT list to the host variables specified in the INTO list.

Syntax:

>>---EXEC SQL--.-------------------.---.------------.---->
               +-FOR :host_integer-+   +-AT db_name-+

                                        +- ,-+
                                        V    |
 >----SELECT----.-------------.---INTO--:hvar------------->
                +-select_list-+

 >----select_options----END-EXEC---><

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
db_name | The name of a database that has been declared using DECLARE DATABASE.
select_list | The portion of the table to retrieve data from.
:hvar | One or more host variables to receive the select_list items.
select_options | One or more statements or other options that can be used with the SQL SELECT statement (for example, a FROM or WHERE clause).

Comments:

A singleton SELECT must contain a FROM clause.

If more columns are selected than the number of receiving host variables, the value of sqlwarn3 is set to 'W'. The data type and length of the host variable must be compatible with the value assigned to it. If data is truncated, the value of sqlwarn1 is set to 'W'.

If a SELECT INTO statement returns more than one row from the database, all rows except the first one will be discarded and sqlwarn4 will be set to "W". If you want to return more than the first row, you should use a cursor. Alternatively, you can specify array items in the INTO clause. The array will be populated up to either the maximum size of the array, the value of host_integer or the number of rows returned, whichever is the smallest.

If SELECT INTO returns more rows from the database than the statement in the application is able to accept, OpenESQL returns the following for each of the specified directives:
CHECKSINGLETON     SQLCODE = -811 SQLSTATE = 21000 SQLWARN4 = W
NOCHECKSINGLETON   SQLCODE = 0    SQLSTATE = 00000 SQLWARN4 = space

ANSI92ENTRY        SQLCODE = -1   SQLSTATE = 21000 SQLWARN4 = W
If SELECT INTO returns more rows from the database than the statement in the application is able to accept, and none of these directives are set, then OpenESQL returns:
SQLCODE = +1 SQLSTATE = 21000 SQLWARN4 = W
Note: If any one of the host variables in the INTO clause is an array, then they all must be arrays.

Example:

  ...
     MOVE 99 TO staff-id
     EXEC SQL
        SELECT last_name
           INTO :lname
           FROM staff
           WHERE staff_id=:staff-id
     END-EXEC
     EXEC SQL
        SELECT staff_id
           INTO :staff-id
           FROM staff
           WHERE first_name = 'Phil'
     END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Cursors
Data Structures
Related reference
BEGIN DECLARE SECTION
DECLARE CURSOR
SELECT DISTINCT (using DECLARE CURSOR)
INTO


SET AUTOCOMMIT

Enables you to control ODBC AUTOCOMMIT mode at runtime.

Syntax:

>>--EXEC SQL--SET AUTOCOMMIT---.-ON--.---END-EXEC--><
                               +-OFF-+

Parameters:

ON | Changes to AUTOCOMMIT mode, whereby each SQL statement is treated as a separate transaction and is committed immediately upon execution.
OFF | Switches off AUTOCOMMIT mode. If the ODBC driver you are using supports transactions, statements must be explicitly committed (or rolled back) as part of a transaction.

Comments:

The SET AUTOCOMMIT statement is useful for data sources which can only execute DDL statements, such as CREATE and DROP, in AUTOCOMMIT mode.

When set to ON, AUTOCOMMIT releases locks when an outermost stored procedure executes a COMMIT or a ROLLBACK statement.

This statement overrides the AUTOCOMMIT SQL compiler directive option.

Example:

EXEC SQL SET AUTOCOMMIT ON END-EXEC
Parent topic: Embedded SQL Statements
Related reference
BEGIN TRAN
AUTOCOMMIT


SET CONCURRENCY

Sets the concurrency option for cursors.

Syntax:

>>--EXEC SQL--SET CONCURRENCY--.-READONLY-.---END-EXEC--><
                               +-LOCKCC---+
                               +-OPTCC----+
                               +-OPTCCVAL-+

Parameters:

READONLY | Specifies read-only cursors. Data cannot be modified.
LOCKCC | Places an update intent lock on the data page that contains each row as it is fetched. If not inside an open transaction, the locks are released when the next fetch is performed. If inside an open transaction, the locks are released when the transaction is closed.
OPTCC | Optimistic concurrency control using timestamp or values. Changes to a row through the cursor succeed only if the row remains unchanged since the last fetch. Changes are detected by comparing timestamps or by comparing all non-text, non-image values if timestamps are not available.
OPTCCVAL | Optimistic concurrency control using values. Changes to a row through the cursor succeed only if the row remains unchanged since the last fetch. Changes are detected by comparing all non-text, non-image values.

Dependencies:

The BEHAVIOR compiler directive option must be set to UNOPTIMIZED.

Comments:

The SET CONCURRENCY statement is not supported by all ODBC drivers.

You should establish a connection before you use SET CONCURRENCY.

The default is LOCKCC unless:

  • The ESQLVERSION option of the SQL Compiler directive is set to 2.0, in which case the default is OPTCC.
  • LOCKCC is not supported by the ODBC driver, in which case SET CONCURRENCY is set to READONLY (all ODBC drivers should support this setting).

If you try to set an option which is not supported by the ODBC driver, you will get an error (-19512).

Note:
  • If you are using the Microsoft Access driver, the default for CONCURRENCY is set to READONLY. If you want to use an updateable cursor with Access, you must compile with SQL(USECURLIB=YES) and use SCROLLOPTION STATIC and CONCURRENCY OPTCCVAL (or OPTIMISTIC).
  • If the OPTCC or OPTCCVAL option is used, an UPDATE WHERE CURRENT OF statement can fail, with a value in SQLCODE of -532 (SQLSTATE = "01001"), if the row has been changed since the last FETCH statement. Your application needs to contain code to handle this situation.

Example:

EXEC SQL SET CONCURRENCY READONLY END-EXEC
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
BEHAVIOR
UPDATE (Positioned)
SET OPTION


SET CONNECTION

Sets the named connection as the current connection.

Syntax:

>>--EXEC SQL--SET CONNECTION---.-name-----.---END-EXEC--><
                               +-DEFAULT--+

Parameters:

name | Specifies the name of a database connection. Must match the connection name specified in a previous CONNECT statement. The name can be either the connection's literal name or the name of a host variable containing character values.
DEFAULT | If you have established a connection using the CONNECT statement but omitting the connection name, you can refer to the connection established as DEFAULT.

Comment:

If you are using connections across compilation modules you must use named connections.

Example:

     EXEC SQL CONNECT TO "srv1" AS server1 USER "sa." END-EXEC
     EXEC SQL CONNECT TO "srv2" AS server2 USER "sa." END-EXEC

* server2 is the current connection
     EXEC SQL CREATE TABLE phil1
        (charbit    CHAR(5))
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not create table.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL INSERT INTO phil1 VALUES('hello') END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not insert data.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
      END-IF

* set the current connection to server1
     EXEC SQL SET CONNECTION server1 END-EXEC
     EXEC SQL
        SELECT first_name
           INTO :fname
           FROM staff
           WHERE staff_id = 10
     END-EXEC

     DISPLAY fname ' says ' WITH NO ADVANCING

* set the current connection back to server2
     EXEC SQL SET CONNECTION server2 END-EXEC
     EXEC SQL
        SELECT charbit
           INTO :fname
           WHERE charbit = 'hello'
           FROM phil1
     END-EXEC

     DISPLAY fname
     EXEC SQL DISCONNECT server1 END-EXEC
     EXEC SQL DISCONNECT server2 END-EXEC
     STOP RUN
Parent topic: Embedded SQL Statements
Related reference
COMMIT
CONNECT
DISCONNECT
ROLLBACK


SET host_variable

Provides information about OpenESQL connections and databases.

Syntax:

>>--EXEC SQL--.------------.--->
                      +-AT db_name-+

 >--SET :host_variable = >
 >------.-CURRENT CONNECTION-.------------.----------.-->
        +-CURRENT DATABASE---.------------.----------+
        +-OPTION-------------+-DATE-------+-USA------+
                                          +-EUR------+
                                          +-JIS------+
                                          +-ODBC-----+
                                          +-EXTERNAL-+
                                          +-ISO------+
                                          +-DEFAULT--+
                             +-TIME-------+-USA------+
                                          +-EUR------+
                                          +-JIS------+
                                          +-ODBC-----+
                                          +-EXTERNAL-+
                                          +-ISO------+
                                          +-DEFAULT--+
                             +-DATEDELIM--+-char-----+
                             +-TIMEDELIM--+-char-----+
                             +-TSTAMPSEP--+-char-----+
                             +-DETECTDATE-+-CLIENT---+
                                          +-SERVER---+
                                          +-OFF------+
 >---END EXEC---><

Parameters:

AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.
host_variable | A PIC X(n) host variable
char | Any single printable character or space
Note: For a full description of each option and its corresponding parameters, see the equivalent SQL Compiler Directive Options topic as listed in the Related reference section below.

Comments:

This statement returns the name of the current connection or the type of database for the current connection as specified in the EXEC SQL CONNECT statement in the specified host variable.

If there is no current open connection, host_variable is set to NONE for both CURRENT CONNECTION and CURRENT DATABASE.

With CURRENT CONNECTION, you can use host_variable in a subsequent EXEC SQL SET CONNECTION statement.

With CURRENT DATABASE, if there is a current open connection, host_variable is set to one of the following values, depending on the connection:

  • DB2
  • SQLSERVER
  • ORACLE
  • POSTGRESQL
  • OTHER
In addition to the OPTION syntax specified above, you can optionally place an equals (=) sign between the option and its parameter. For example, the following are equivalent:
exec sql set :myhostvar option date EUR end-exec
and
exec sql set :myhostvar option date=EUR end-exec
Parent topic: Embedded SQL Statements
Related reference
TIME
DATE
DATEDELIM
TIMEDELIM
TSTAMPSEP
SQL Compiler Directive Options
DETECTDATE


SET OPTION

Enables you to set OpenESQL options.

Syntax:

>>---EXEC SQL---SET OPTION----.-QUERYTIME---.----------.-->
                              +-LOGINTIME---+
                              +-APPLICATION-+
                              +-HOST--------+
                              +-DATE--------+-USA------+
                                            +-EUR------+
                                            +-JIS------+
                                            +-ODBC-----+
                                            +-EXTERNAL-+
                                            +-ISO------+
                                            +-DEFAULT--+
                              +-TIME--------+-USA------+
                                            +-EUR------+
                                            +-JIS------+
                                            +-ODBC-----+
                                            +-EXTERNAL-+
                                            +-ISO------+
                                            +-DEFAULT--+
                               +-DATEDELIM--+-char-----+
                               +-TIMEDELIM--+-char-----+
                               +-TSTAMPSEP--+-char-----+
                               +-DETECTDATE-+-CLIENT---+
                                            +-SERVER---+
                                            +-OFF------+

 >---value---END-EXEC---><

Parameters:

value | A literal or the name of a host variable. The host variable must contain character values for APPLICATION or HOST and numeric values for LOGINTIME or QUERYTIME.
QUERYTIME | Sets the number of seconds that the program waits for a response to an OpenESQL statement. The default is 0, meaning forever. This option does not override existing network timeout settings.
LOGINTIME | Sets the number of seconds that the program waits for a response to a CONNECT TO statement. The default is 10 seconds. A value of 0 indicates an infinite timeout period.
APPLICATION | Sets the application name which is passed by OpenESQL to the data source when a CONNECT TO statement is executed.
HOST | Sets the host workstation name which is passed by OpenESQL when a CONNECT TO statement is executed.
Note: For a full description of the DATE, TIME, DATEDELIM, TIMEDELIM, TSTAMPSEP, and DETECTDATE options and their corresponding parameters, see the equivalent SQL Compiler Directive Options topic as listed in the Related reference section below.

Comment:

The SET OPTION statement is not supported by all ODBC drivers.

As an option, you can place an equals (=) sign between an option and its parameter. For example, the following are equivalent:
exec sql set option date EUR end-exec
and
exec sql set option date=EUR end-exec

Example:

     EXEC SQL SET OPTION logintime 5 END-EXEC

     EXEC SQL CONNECT TO "srv2" USER "sa." END-EXEC

* If the CONNECT statement cannot log in to the server "srv2"
* within five seconds, it will time out and return to the program.

     EXEC SQL SET OPTION querytime 2 END-EXEC

     EXEC SQL SELECT name FROM sysobjects INTO :name END-EXEC

* If the SELECT statement does not respond within 2 seconds,
* the query will time out and return to the program.
Parent topic: Embedded SQL Statements
Related reference
CONNECT
SET CONCURRENCY
SET SCROLLOPTION
TIME
DATE
DATEDELIM
TIMEDELIM
TSTAMPSEP
SQL Compiler Directive Options
DETECTDATE


SET SCROLLOPTION

Enables you to set cursor scrolling options.

Syntax:

>>--EXEC SQL--SET SCROLLOPTION--.-KEYSET----.--END-EXEC-><
                                +-DYNAMIC------+
                                +-FORWARD------+
                                +-STATIC-------+
                                +-FASTFORWARD--+
                                +-FAST FORWARD-+

Parameters:

KEYSET | In a keyset cursor, the membership and order of rows in the cursor result set is determined when the cursor is opened. A row will not be fetched if it is deleted or if it is updated such that it no longer meets the WHERE clause criteria. A row appears in the cursor result set only if it is inserted through a cursor based on a single table. Any updates made by the cursor owner and committed changes made by other users to any of the rows in the results set are visible.
DYNAMIC | With a dynamic cursor, membership of rows in the cursor result set is determined at fetch time and it can change between each fetch. A row will disappear from the cursor result set if it is deleted or if it is updated such that it no longer meets the WHERE clause criteria. A row appears in the result set if it is inserted or updated such that it meets the WHERE clause criteria. Any updates made by the cursor owner and committed changes made by other users to any of the rows in the result set are visible.
FORWARD | Equivalent to DYNAMIC, but the application can only move forward through the result set.
STATIC | In a static cursor, the result set appears to be static. Changes to the membership, order or values of the result set after the cursor is opened are not usually detected.
FASTFORWARD and FAST FORWARD | FAST FORWARD and FASTFORWARD are equivalent. This is a performance optimization parameter that applies only to FORWARD, READ-ONLY cursors. You can obtain even greater performance gains by also compiling the program with the AUTOFETCH directive; this is the most efficient method of getting a results set into an application. The AUTOFETCH directive enables two optimizations that can significantly reduce network traffic. The most dramatic improvement is seen when processing cursors with relatively small result sets that can be cached in the memory of an application. FASTFORWARD cursors work only with Microsoft SQL Server 2000 or later servers.

Dependencies:

The BEHAVIOR compiler directive option must be set to UNOPTIMIZED.

Comments:

The SET SCROLLOPTION statement is not supported by all ODBC drivers.

You should establish a connection before you use SET SCROLLOPTION.

The default is DYNAMIC unless:

  • The ESQLVERSION option of the SQL Compiler directive is set to 2.0, in which case the default is KEYSET.
  • The ODBC driver does not support DYNAMIC, in which case SET SCROLLOPTION is set to FORWARD (all ODBC drivers should support this setting).
  • FAST FORWARD works only with Microsoft SQL Server data sources.

If you try to set an option which is not supported by the ODBC driver, you will get an error (-19512).

Example:

 PROGRAM-ID. progname.
 WORKING-STORAGE SECTION.
 EXEC SQL INCLUDE SQLCA END-EXEC
 01      buffer      PIC x(32).
 01      cnt         PIC 9 COMP-5.

 PROCEDURE DIVISION.
     EXEC SQL CONNECT TO 'srv1' USER 'sa' END-EXEC
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not connect to database.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
     END-IF
* Any cursors declared hereafter can be updated dynamically
     EXEC SQL SET SCROLLOPTION DYNAMIC END-EXEC
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not set scroll option.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Ensure multiple tables are not created ...
     EXEC SQL DROP TABLE phil1 END-EXEC

* Create a table...
     EXEC SQL
        CREATE TABLE phil1
             (ident      char(3)
             ,textbit    char(3))
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not create table.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Insert some values into it...
     EXEC SQL
        INSERT INTO phil1
            (ident
            ,textbit)
        VALUES
            ('AAA'
            ,'BBB')
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not insert values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

     EXEC SQL
        INSERT INTO phil1
            (ident
           ,textbit)
         VALUES
           ('CCC'
            ,'DDD')
    END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not insert values.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Declare a cursor...
     EXEC SQL
        DECLARE C1 CURSOR FOR
           SELECT ident
           FROM phil1
           WHERE textbit = 'BBB'
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not declare cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Open it...
     EXEC SQL
        OPEN C1
     END-EXEC
     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not open cursor.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Update one of the rows in the table such that it now meets the
* cursor requirements...
     EXEC SQL
        UPDATE phil1
        SET textbit = 'BBB'
        WHERE ident = 'CCC'
     END-EXEC

     IF SQLCODE NOT = ZERO
        DISPLAY 'Error: Could not update row.'
        DISPLAY SQLERRMC
        DISPLAY SQLERRML
        EXEC SQL DISCONNECT ALL END-EXEC
        STOP RUN
     END-IF

* Despite the row being updated to meet cursor requirement after
* the cursor was opened, SET SCROLLOPTION DYNAMIC should ensure
* that it is pointed to by the cursor. Check the displayed output
* to be sure...
    MOVE 0 TO cnt
    PERFORM UNTIL SQLCODE NOT = ZERO
       EXEC SQL
          FETCH C1 INTO :buffer
       END-EXEC
       IF SQLCODE = ZERO
          DISPLAY buffer
       END-IF
    END-PERFORM

    EXEC SQL
       CLOSE C1
    END-EXEC

    IF SQLCODE NOT = ZERO
       DISPLAY 'Error: Could not close cursor.'
       DISPLAY SQLERRMC
       DISPLAY SQLERRML
       EXEC SQL DISCONNECT ALL END-EXEC
       STOP RUN
    END-IF

    EXEC SQL DROP TABLE phil1 END-EXEC

    IF SQLCODE NOT = ZERO
       DISPLAY 'Error: Could not drop table.'
       DISPLAY SQLERRMC
       DISPLAY SQLERRML
       EXEC SQL DISCONNECT ALL END-EXEC
       STOP RUN
    END-IF

    EXEC SQL DISCONNECT CURRENT END-EXEC
    STOP RUN.
Parent topic: Embedded SQL Statements
Related reference
DECLARE CURSOR
BEHAVIOR
PERSIST
SET OPTION
AUTOFETCH
UPDATE (Positioned)


SET TRACELEVEL

Enables you to dynamically set or change the reporting level of OpenESQL traces for native applications.

Syntax:

>>--EXEC SQL--SET TRACELEVEL--.-0-------.---END-EXEC--><
                              +-1-------+
                              +-2-------+
                              +-3-------+
                              +-4-------+
                              +-OFF-----+
                              +-DEFAULT-+

Parameters:

0

Turns off the OpenESQL trace.

1

The following information is written to the trace file:

BEGIN | traces main SQL directives
END | indicates end of run
DIRECTIVES | traces per compilation unit directives the first time a compilation unit is enountered at run time
PREPARE | identifies the original source code when a statement is prepared
DISPOSE | provides summary information for overall statement usage when a statement is removed from the prepared statement cache at disconnect time
FLUSH | provides summary information for overall statement usage when a statement is flushed from the cache usually due to a cache overflow

2

The following information is written to the trace file in addition to the information written when you set the trace level to 1:

OPEN
EXECUTE | provides the number of rows selected, inserted, or updated
EXEC_IMMED EXECUTE | provides the number of rows selected, inserted, or updated
ODBCCLOSE | provides summary information for the current cursor use
STMT_CHANGED | reports new concurrency and scroll option settings when the ODBC driver uses different settings than those requested by OpenESQL

3

The following information is written to the trace file in addition to the information written when you set the trace level to 2:

ODBCFETCH | provides the number of rows fetched
COBOLFETCH | provides the number of rows returned to the COBOL application

4

The following information is written to the trace file in addition to the information written when you set the trace level to 3:

  • EXEC_SQL_BEGIN
  • EXEC_SQL_END

OFF

Turns off the OpenESQL trace.

DEFAULT

Resets the trace setting to the value set by the SQL TRACELEVEL directive. If the TRACELEVEL directive was not used to compile a program, this is equivalent to setting this option to OFF.

Example:

EXEC SQL SET TRACELEVEL DEFAULT END-EXEC
Parent topic: Embedded SQL Statements


SET TRANSACTION ISOLATION

Sets the transaction isolation level for the current connection to one of the isolation level modes specified by ODBC.

Syntax:

>>--EXEC SQL--SET TRANSACTION ISOLATION------------------->

 >-------.-READ UNCOMMITTED-.---------END-EXEC------------><
         +-READ COMMITTED---+
         +-REPEATABLE READ--+
         +-SERIALIZABLE-----+

Comments:

Transactions can affect each other in the following ways, depending on the setting of the transaction isolation level:

  • Dirty read - Transaction 1 updates a row. Transaction 2 reads the row before transaction 1 commits. Transaction 1 issues a rollback. Transaction 2's results are based on invalid data.
  • Nonrepeatable read - Transaction 1 reads a row. Transaction 2 updates or deletes the row and commits the change. If transaction 1 re-reads the row, it will retrieve different values, or may not be able to re-read the row.
  • Phantom - Transaction 1 reads a set of rows using a select with a where clause. Transaction 2 inserts a row that satisfies the where clause. If transaction 1 repeats the select, it will read a different set of rows.

These situations can be controlled by locking, which means that a transaction might have to wait until another transaction completes, which limits concurrency (sometimes called pessimistic concurrency), or by forcing a transaction to rollback if the situation occurs, which has less of an impact on concurrency but may force work to be repeated (this is sometimes called optimistic concurrency).

In READ UNCOMMITED mode, dirty reads, nonrepeatable reads and phantoms are all possible.

In READ COMMITED mode, dirty reads are not possible but nonrepeatable reads and phantoms are.

In REPEATABLE READ mode, dirty reads and nonrepeatable reads are not possible, but phantoms are.

In SERIALIZABLE mode dirty reads, nonrepeatable reads and phantoms are all impossible.

Note:

A driver might not support all the isolation levels defined by ODBC. If you set a mode that the driver does not support, SQLCODE and SQLSTATE are set accordingly.

Example:

EXEC SQL SET TRANSACTION ISOLATION READ UNCOMMITTED END-EXEC
Parent topic: Embedded SQL Statements


SYNCPOINT

Closes all open cursors that were not opened using the WITH HOLD clause, even if the application has not appropriately closed them.

Syntax:

>>---EXEC SQL---SYNCPOINT---END-EXEC---><

Comments:

Use SYNCPOINT in the XA switch modules provided for Enterprise Server environments to ensure that all cursors that were not opened using the WITH HOLD clause have been closed before a new unit of work is started.

In Enterprise Server environments, SYNCPOINT ensures that all database locks acquired are released if the application fails to close cursors explicitly.

Parent topic: Embedded SQL Statements


UNBIND CONNECTION

Disassociates OpenESQL from the original JDBC connection object.

Syntax:

>>--EXEC SQL--UNBIND CONNECTION--.-----------------.---->
                                 +-connection_name-+
                                 +-:conn_name_hv---+

 >----END-EXEC----><

Parameters:

connection_name | The connection name OpenESQL uses to refer to the JDBC connection object.
conn_name_hv | Host variable which contains the connection name OpenESQL uses to refer to the JDBC connection object.

Example:

     EXEC SQL
        UNBIND CONNECTION fred
     END-EXEC
Parent topic: Embedded SQL Statements
Related concepts
Sharing Database Connections Between Java and COBOL


UPDATE (Positioned)

Syntax:

>>---EXEC SQL---.-----------------.--.------------.----->
                +--FOR :host_integer-+  +-AT db_name-+

                                  +------ ,-------+
                                  V               |
 >---UPDATE---table_name-----SET--column_expression----->

 >--WHERE CURRENT OF--cursor_name---END-EXEC---><

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is not required, and if omitted, the connection automatically switches to the connection associated with the DECLARE CURSOR statement if different than the current connection, but only for the duration of the statement.
table_name | The table to be updated.
column_expression | A value for a particular column name. This value can be an expression or a null value.
cursor_name | A previously declared, opened, and fetched cursor.

Comments:

Do not use the FOR clause if the UPDATE is part of a DECLARE CURSOR statement.

After execution, SQLERRD(3) contains the number of elements processed. For UPDATE it is the total number of rows updated.

ODBC supports positioned update, which updates the row most recently fetched by using a cursor, in the Extended Syntax (it was in the core Syntax for ODBC 1.0 but was moved to the Extended Syntax for ODBC 2.0). Not all drivers provide support for positioned update, although OpenESQL sets ODBC cursor names to be the same as COBOL cursor names to facilitate positioned update and delete.

With some ODBC drivers, the select statement used by the cursor must contain a FOR UPDATE clause to enable positioned update.

The other form of UPDATE used in standard SQL statements is known as a searched update.

You cannot use host arrays with positioned update.

Most data sources require specific combinations of SCROLLOPTION and CONCURRENCY to be specified either by SET statements or in the DECLARE CURSOR statement.

The ODBC cursor library provides a restricted implementation of positioned update which can be enabled by compiling with SQL(USECURLIB=YES) and using SCROLLOPTION STATIC and CONCURRENCY OPTCCVAL (or OPTIMISTIC).

Example:

     EXEC SQL CONNECT TO 'srv1' USER 'sa' END-EXEC

     EXEC SQL DECLARE C1 CURSOR FOR
        SELECT last_name, first_name
        FROM staff
        FOR UPDATE
     END-EXEC

     EXEC SQL
        OPEN C1
     END-EXEC

     PERFORM UNTIL SQLCODE NOT = ZERO

        EXEC SQL
            FETCH C1 INTO :fname,:lname
        END-EXEC

        IF SQLCODE = ZERO
           DISPLAY fname " " lname
           DISPLAY "Update?"
           ACCEPT reply
           IF reply = "y"
              DISPLAY "New last name?"
              ACCEPT lname
              EXEC SQL
                 UPDATE staff
                 SET last_name=:lname WHERE CURRENT OF c1
              END-EXEC
              DISPLAY "update sqlcode=" SQLCODE
            END-IF
        END-IF
     END-PERFORM

     EXEC SQL DISCONNECT ALL END-EXEC
     STOP RUN.
Parent topic: Embedded SQL Statements
Related concepts
Cursors
Related reference
INSERT
SET CONCURRENCY
DECLARE CURSOR
DECLARE DATABASE
FETCH
SET SCROLLOPTION
UPDATE (Searched)


UPDATE (Searched)

Updates a table or view based on specified search conditions.

Syntax:

>>--EXEC SQL--.-------------------.---------------------->
              +-FOR :host_integer-+

 >-----.-------------.------UPDATE------.-table_name-.---->
       +-AT db_name--+                  +-view_name--+

          +------ ,-------+
          V               |
 >---SET--column_expression--.-------------------------.-->
                             +-WHERE search_conditions-+

 >----END-EXEC---><

Parameters:

:host_integer | A host variable that specifies the maximum number of host array elements processed. Must be declared as PIC S9(4) COMP-5 or PIC S9(9) COMP-5.
AT db_name | The name of a database that has been declared using DECLARE DATABASE. This clause is optional. If omitted, the current connection executes the update. If provided, and the connection specified is different than the current connection, the update is performed on the connection associated with the DECLARE CURSOR statement.
table_name | The table to be updated.
view_name | The view to be updated.
column_expression | A value for a particular column name. This value can be an expression or a null value.
search_conditions | Any valid expression that can follow the standard SQL WHERE clause.

Comments:

UPDATE is a standard SQL statement which is passed directly to the ODBC driver. See the documentation supplied with your ODBC driver for the exact syntax.

If you do not specify a WHERE clause, all the rows in the named table are updated.

If one of the host variables used in the WHERE clause or SET clause is an array, they must all be arrays.

After execution, SQLERRD(3) contains the number of elements processed. For UPDATE it is the total number of rows updated.

Example:

     EXEC SQL
        UPDATE staff
        SET first_name = 'Jonathan'
        WHERE staff_id = 1
     END-EXEC

     MOVE 'Phil' TO NewName
     MOVE 1 TO targetID

     EXEC SQL
        UPDATE staff
        SET first_name = :NewName
        WHERE staff_id  = :targetID
     END-EXEC
Parent topic: Embedded SQL Statements
Related reference
INSERT
UPDATE (Positioned)


WHENEVER

Specifies the default action after running an Embedded SQL statement when a specific condition is met.

Syntax:

>>--EXEC SQL---WHENEVER---.-NOT FOUND--.----------------->
                          +-SQLERROR---+
                          +-SQLWARNING-+

 >--.-CONTINUE--------.----END-EXEC---><
    +-PERFORM label---+
    +-GOTO stmt_label-+

Parameters:

CONTINUE | Causes the next sequential statement in the source program to run.
PERFORM label | Identifies a paragraph or section of code to be performed when a certain error level is detected.
GOTO stmt_label | Identifies the place in the program that takes control when a certain error level is detected.

Comments:

The WHENEVER statement specifies the default action after running an Embedded SQL statement on each of the following conditions: NOT FOUND, SQLERROR, SQLWARNING.

Condition | sqlcode
No error | 0
NOT FOUND | 100
SQLWARNING | +1
SQLERROR | < 0 (negative)

The scope of a WHENEVER statement is related to the position of statements in the source program, not in the run sequence. The default is CONTINUE for all three conditions.

Example:

The following example shows the WHENEVER statement in use:

     EXEC SQL WHENEVER sqlerror PERFORM errormessage1 END-EXEC

     EXEC SQL
        DELETE FROM staff
        WHERE staff_id = 'hello'
     END-EXEC

     EXEC SQL
        DELETE FROM students
        WHERE student_id = 'hello'
     END-EXEC

     EXEC SQL WHENEVER sqlerror CONTINUE END-EXEC

     EXEC SQL
        INSERT INTO staff VALUES ('hello')
     END-EXEC

     DISPLAY 'Sql Code is: ' SQLCODE
     EXEC SQL WHENEVER sqlerror PERFORM errormessage2 END-EXEC

     EXEC SQL
        INSERT INTO staff VALUES ('hello again')
     END-EXEC

     STOP RUN.

 errormessage1 SECTION.
     display "SQL DELETE error: " sqlcode
     EXIT.

 errormessage2 SECTION.
     display "SQL INSERT error: " sqlcode
     EXIT.
Parent topic: Embedded SQL Statements
Related reference
The SQLCA Data Structure


SQL Compiler Directive Options

  • ALLOWNULLCHAR
    Allows programs to use PIC X(n) host variables, and to select/insert/update the null character (x00) into CHAR columns without changing source to use SQL TYPE BINARY host variables.
  • ALLOWSERVERSELECT
    Passes unrecognized EXEC SQL SELECT statements through to the server, thus enabling server-specific behavior.
  • ANSI92ENTRY
    If this is set, OpenESQL conforms to the SQL ANSI'92 entry level standard.
  • ARRAYCHECK
    Checks to ensure that indicator variable arrays match up correctly with host array variables.
  • AUTOCOMMIT
    Regulates an SQL connection's autcommit attribute.
  • AUTOFETCH
    Sets the AUTOFETCH attribute on SELECT statements that are run on Microsoft SQL Server data sources. Compiling with this directive can help the performance of your application. This directive works only if the program is also compiled with directive SQL(TARGETDB=MSSQLSERVER). It also serves as a primitive directive for the BEHAVIOR directive option.
  • BEHAVIOR
    Instructs OpenESQL to properly match your COBOL cursors with the database you are using, thus maximizing database cursor performance. BEHAVIOR makes use of multiple primitive directives and associates a default value for each primitive directive depending on the target DBMS. You can also override the default setting of any primitive directive.
  • CHECK
    Sends each SQL statement to the database at compilation time.
  • CHECKDUPCURSOR
    Instructs OpenESQL to determine if the cursor has been opened twice, and if so takes action accordingly.
  • CHECKSINGLETON
    Instructs OpenESQL to check if singleton SELECTs return more than one row when executed.
  • CLOSE_ON_COMMIT
    Specifies whether to close cursors not defined WITH HOLD or leave them open for further fetches after a COMMIT.
  • CONCAT
    Specifies the ASCII character code to use for the CONCAT symbol (|). Use this directive only if you need to change the default.
  • CONNECTIONPOOL
    Enables use of ODBC 3.0 connection pooling. When a connection is closed, the Driver Manager actually keeps it alive for a timeout period, and saves the overhead of re-establishing a connection from scratch if the application re-opens an identical connection. ODBC allows you to choose between having a pooling for an ODBC environment or for each driver. See your ODBC documentation for details.
  • CTRACE
    Causes debug information to be put into the file sqltrace.txt.
  • CURSORCASE
    If ESQLVERSION is 2.0, CURSORCASE is implied. NOCURSORCASE means that cursor names are not case sensitive. CURSORCASE means that they are case sensitive. Note that in previous versions of OpenESQL, cursor names have been case sensitive.
  • DATE
    Specifies the explicit date format to use when date values are returned from database date columns into character output host variables.
  • DATEDELIM
    Specifies a single character as the delimiter between the year, month, and day components to override the default delimiter determined by the DATE directive specification, or implicitly based on default ISO 8601 format (yyyy-mm-dd).
  • DB
    Identifies a data source that defines database connection information.
  • DBMAN
    Specifies the preprocessor to use. This directive is not required when compiling programs with OpenESQL.
  • DECDEL
    Specifies the decimal delimiter to use for decimal variables.
  • DESCRIBEDTCHAR
    When using dynamic SQL, described or prepared SQL statements with DATE, TIME, and DATETIME columns are suitable for PIC X(n) character host variables or DATE, TIME, and TIMESTAMP SQL TYPEs.
  • DESCRIBEDTREC
    When using dynamic SQL, described or prepared SQL statements with DATE, TIME, and DATETIME, columns are suitable for the DATE, TIME, and TIMESTAMP-RECORD SQL TYPEs in ODBC format record structures.
  • DESCRIBEVARCHAR49
    When using dynamic SQL, described or prepared SQL statements with VARCHAR, columns are suitable for VARCHAR host variables with level 49 sub-fields for length and data.
  • DESCRIBEVARCHARPICX
    When using dynamic SQL, described or prepared SQL statements with VARCHAR, columns are suitable for PIC X host variables.
  • DETECTDATE
    Allows datetime values for PIC X character input host variables in an OpenESQL application to be in different formats than the standard ISO 8601 formats.
  • ESQLVERSION
    Sets OpenESQL syntax level.
  • FIPSFLAG
    Enables FIPS flagging (NIST certification requirement only).
  • GEN-CC2
    Generates ESQL API calls using call convention 2 instead of call convention 74.
  • GEN-CLASS-VAR
    Enables backward compatibility with OO SQL COBOL programs migrated from Net Express, and instructs the OpenESQL preprocessor to generate SQL interface variables at the end of object storage in addition to the end of local storage.
  • 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.
  • GEN-INIT-FLAG
    Generates the SQL-INIT-FLAG variable for DB2 for OS/390 compatibility. The flag is updated when the SQL environment is initialized. If you define this variable in your application, compile your application with this directive set to NOGEN-INIT-FLAG and the variable will not be generated by the precompiler.
  • GEN-SQLCA
    Generates an SQLCA equivalent to coding an EXEC SQL INCLUDE SQLCA statement in an application program.
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • IGNORE-NESTED
    In nested programs, this is the program-id at which to start generating the database interface code. If the program file name matches the program-id, you can just specify IGNORE-NESTED.
  • IGNORESCHEMAERRORS
    Suppresses compile-time errors resulting from missing schema objects.
  • INIT
    When set without parameters, the preprocessor automatically generates code to make the connection to the database. When set with the PROT parameter, protects the database when an application terminates abnormally.
  • ISOLATION
    This directive specifies the isolation level that OpenESQL uses as a connection attribute. It also serves as a primitive directive for the BEHAVIOR directive option.
  • JIT
    Generate OpenESQL interface code only if an EXEC SQL statement is found in the procedure division.
  • JNDI
    Enables you to specify a JNDI class to use to look up the connection string for the data source name specified in the EXEC SQL CONNECT statements, or at compile time as specified by the SQL(DB) compiler directive if the SQL(CHECK) compiler directive is also specified.
  • JNDIENC
    Enables applications to use the JNDI Environment Naming Context (ENC) when looking up JDBC data source names using JNDI.
  • MARS
    Enable multiple active results sets when connecting to an Microsoft SQL Server 2005 or later.
  • NIST
    Sets OpenESQL to conform to the NIST interpretation of the SQL ANSI 92 entry level standard.
  • NOT
    Specifies the character code to use for NOT symbol (¬). Use this only if you need to change the default setting.
  • ODBCTRACE
    ODBCTRACE=USER enables you to control ODBC tracing via odbc.ini from which you can specify the file that the trace goes into.
  • ODBCV3
    This directive causes an application to register itself as an ODBC Version 3 application.
  • OPTIMIZECURSORS
    Optimizes memory consumption when using Oracle, PostgreSQL, DB2, or SQL Server JDBC providers. Also applies the same data integrity rules on all databases for embedded SQL cursors that use WITH HOLD and FOR UPDATE clauses for both DBMAN=ODBC and DBMAN=JDBC.
  • OPTION (deprecated)
    Enables non-default optional behavior.
  • OPTPER
    Causes the OpenESQL preprocessor to optimize the performance of CHARSET"EBCDIC" processing.
  • PARAMARRAY
    If PARAMARRAY is set, ODBC array binding is used, if it is supported by the ODBC driver, for all input parameters.
  • PASS
    The login to use to connect to the data source. This option works in conjunction with the INIT and/or CHECK options.
  • PICXBINDING
    Specifies the handling of fixed-length PIC X(n) host variables.
  • PRE
    Instructs the preprocessor to generate code that dynamically loads the OpenESQL module at run time.
  • PREFETCH
    An application can use this directive to request that OpenESQL use block fetches for cursors. This can provide performance benefits, similar to array fetching, without having to change program logic. The performance benefit depends on the value of n and on whether the ODBC driver in use is already configured to use prefetching.
  • QUALFIX
    Causes the OpenESQL preprocessor to append three characters to the name of the host variables when declaring them to SQL. This ensures problems caused by qualification (where two or more host variables have identical names when not qualified) are avoided but has the side-effect that SQL error messages sometimes display the names of host variables with the three additional characters appended to them.
  • RESULTARRAY
    If RESULTARRAY is set, ODBC array binding is used, if it is supported by the ODBC driver, for all output parameters.
  • SAVE-RETURN-CODE
    Specifies whether or not to save and then restore RETURN-CODE.
  • STMTCACHE
    The number of prepared SQL statements OpenESQL can cache such that the statements never again require preparation during a program run, thus improving performance.
  • TARGETDB
    Set this directive if you want to optimize performance for a specific data source.
  • TESTSQLSTATE
    Instructs OpenESQL to generate code that tests SQLSTATE rather than SQLCODE after an SQL statement is executed.
  • THREAD
    Specifies the handling of threads with regard to connections.
  • TIME
    Specifies an explicit time format to use when time values are returned from database time columns into character output host variables.
  • TIMEDELIM
    Specifies a single character as the delimiter between the hour, minute, and second components to override the default delimiter determined by the TIME directive specification, or implicitly based on default ISO 8601 format (hh:mm:ss).
  • TRACELEVEL
    Produces a statistical analysis of application behavior by tracing certain operations in native applications. The report produced by this directive provides better readability and is inherently more useful than a traditional ODBC trace.
  • TRANSACTION
    This directive provides OpenESQL with specifications for managing run-time transactions and, in some cases, enabling compile-time checking.
  • TSTAMPSEP
    Specifies a single character to use as the separator between the date and time parts when datetime values are returned from database datetime columns into character output host variables.
  • USECURLIB
    Controls use of the ODBC's Cursor Library.
  • USER-SQLDA
    Eliminates invalid host variable compiler errors for applications that contain an SQLDA rather than including it using the COPY SQLDA statement.
  • WHERECURRENT
    Allows PostgreSQL and MySQL to accept updateable SELECT and CURSOR statements when no positioned UPDATEs or DELETEs are required.
  • XAID
    Simplifies working with multiple XARs of the SQL Server or generic one-phase commit for ODBC RM types defined in a single enterprise server region.
Parent topic: OpenESQL
Related concepts
Setting the OpenESQL Preprocessor and Compiler Directive Options
SQL Code Generation Options


ALLOWNULLCHAR

Allows programs to use PIC X(n) host variables, and to select/insert/update the null character (x00) into CHAR columns without changing source to use SQL TYPE BINARY host variables.

Syntax:

Important: Use ALLOWNULLCHAR with legacy code only, for example, code that uses FOR BIT DATA columns in DB2 (now discouraged by IBM) where the cost of converting to BINARY columns in the database and SQL TYPE IS BINARY host variables is prohibitive. Storing binary data in character columns is not a best practice and should be avoided wherever possible.
[NO]ALLOWNULLCHAR

Properties:

Default: NOALLOWNULLCHAR

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

With ALLOWNULLCHAR, OpenESQL does not truncate the contents of the input host variable when the first embedded NULL character is encountered.

With NOALLOWNULLCHAR, however, the database is presented a truncated value, including all characters up to the first embedded NULL.

PostgreSQL does not support the embedding of the NULL character into CHAR columns; therefore ALLOWNULLCHAR is not supported in PostgreSQL OpenESQL applications.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
PICXBINDING
Fixed-length Character Strings


ALLOWSERVERSELECT

Passes unrecognized EXEC SQL SELECT statements through to the server, thus enabling server-specific behavior.

Syntax:

[NO]ALLOWSERVERSELECT

Properties:

Default: NOALLOWSERVERSELECT

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

NOALLOWSERVERSELECT gives an error when OpenESQL does not recognize an EXEC SQL SELECT statement.

NOALLOWSERVERSELECT behavior is compatible with versions of Visual COBOL earlier than 5.0.

When ALLOWSERVERSELECT is set, OpenESQL simply passes unrecognized EXEC SQL SELECT statements through to the server, thus enabling server-specific behavior.

Important: ALLOWSERVERSELECT behavior was the default for Net Express, and might be required by some applications when migrated to Visual COBOL.
Parent topic: SQL Compiler Directive Options


ANSI92ENTRY

If this is set, OpenESQL conforms to the SQL ANSI'92 entry level standard.

Syntax:

[NO]ANSI92ENTRY

Properties:

Default: NOANSI92ENTRY

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

When ANSI92ENTRY is not specified or NOANSI92ENTRY is specified, OpenESQL does not set any error or warning conditions.

When ANSI92ENTRY is specified and neither CHECKSINGLETON nor NOCHECKSINGLETON is specified (default), OpenESQL returns:

SQLCODE = -1 SQLSTATE = 21000 SQLWARN4 = W

In conformance with the ANSI-92 standard, OpenESQL does the following when ANSI92ENTRY is specified:

  • Sets the isolation level to serializable.
  • Closes non-HOLD cursors at the end of a transaction.
  • When an EXEC SQL FETCH statement is executed on an unopened cursor, returns SQLSTATE 24000. If ODBCV3 is also set, returns SQLSTATE 07005.
  • When an EXEC SQL FETCH statement returns a null value but no indicator host variable has been supplied, returns SQLCODE -19425.
  • When an EXEC SQL OPEN statement is executed on an opened cursor, returns SQLCODE -19516 and SQLSTATE 07005.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings
CHECKSINGLETON
SQLCODE Values


ARRAYCHECK

Checks to ensure that indicator variable arrays match up correctly with host array variables.

Syntax:

[NO]ARRAYCHECK

Properties:

Default: ARRAYCHECK

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

If your code contains indicator variable arrays used with non-host array variables, specify NOARRAYCHECK to prevent OpenESQL from throwing an error message when it encounters an array of this type.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


AUTOCOMMIT

Regulates an SQL connection's autcommit attribute.

Syntax:

[NO]AUTOCOMMIT

Properties:

Default: NOAUTOCOMMIT

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Because NOAUTOCOMMIT is used by default, OpenESQL default behavior explicitly turns off the SQL connection's autocommit attribute regardless of how the connection was created.

For OpenESQL connections, NOAUTOCOMMIT allows your application to control local transactions, with normal COMMIT and ROLLBACK statements; however, for connections not created by OpenESQL such as an external connection created by a Java application server, turning off the connection's autocommit attribute by using NOAUTOCOMMIT could result in error.

When AUTOCOMMIT is specified explicitly, the SQL connection's autocommit attribute is not altered, whether the connection was created by OpenESQL or by some other means. The result for OpenESQL connections is that AUTOCOMMIT commits every SQL statement in your application, operating in "autocommit mode." With external connections, the autocommit attribute is not modified, so your application continues to participate in the transaction managed externally.

The SET AUTOCOMMIT embedded SQL statement overrides the AUTOCOMMIT compiler directive option.

An application can programmatically control the autocommit setting for a connection by executing the EXEC SQL SET AUTOCOMMIT statement.

An application in autocommit mode can start a local database transaction with the EXEC SQL BEGIN TRANSACTION statement. The transaction ends when the next COMMIT or ROLLBACK statement is executed.

When a transaction ends, if the connection's autocommit attribute is on, the connection reverts to autocommit mode; otherwise a new local database transaction is started automatically.

Parent topic: SQL Compiler Directive Options
Related concepts
Managing Transactions
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings
SET AUTOCOMMIT
TRANSACTION


AUTOFETCH

Sets the AUTOFETCH attribute on SELECT statements that are run on Microsoft SQL Server data sources. Compiling with this directive can help the performance of your application. This directive works only if the program is also compiled with directive SQL(TARGETDB=MSSQLSERVER). It also serves as a primitive directive for the BEHAVIOR directive option.
Note:
  • Errors on a cursor OPEN are deferred until the subsequent FETCH when AUTOFETCH is enabled.
  • BEHAVIOR=OPTIMIZED for MS SQL Server enables AUTOFETCH
  • Errors on a cursor OPEN are deferred until the subsequent FETCH when AUTOFETCH is enabled

Syntax:

[NO]AUTOFETCH

Properties:

Default: NOAUTOFETCH

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
SET SCROLLOPTION


BEHAVIOR

Instructs OpenESQL to properly match your COBOL cursors with the database you are using, thus maximizing database cursor performance. BEHAVIOR makes use of multiple primitive directives and associates a default value for each primitive directive depending on the target DBMS. You can also override the default setting of any primitive directive.
Note:
  • If you don't specify any BEHAVIOR primitive directives, and you also accept the default primitive directive values listed in the relevant table in the Default Primitive Directives section later in this topic, the TARGETDB directive is not required; however, you must specify TARGETDB if you want to use different default values for any primitive directive.
  • Setting the BEHAVIOR directive can also affect the SQL types returned when using Dynamic SQL. See the DESCRIBE Statement topic for more information.
  • Because the JDBC API does not support prefetching, very limited support is provided for BEHAVIOR primitive directives with DBMAN=JDBC. See DBMAN Directive Settings for more information.

Syntax:

BEHAVIOR={OPTIMIZED | UNOPTIMIZED | ANSI | MAINFRAME } [primitivedirective [value]]...

Parameters:

OPTIMIZED | Enables OpenESQL to optimize ambiguous cursor declarations; enhances the access speed
UNOPTIMIZED | Provides backward compatibility with earlier Micro Focus products, where ambiguous cursors are both updateable and scrollable
ANSI | Enables OpenESQL to work like the ANSI standard; enhances the access speed
MAINFRAME | Synonym for OPTIMIZED
primitivedirective | Optional directives that enable the fine-tuning of BEHAVIOR

Properties:

Default: BEHAVIOR=OPTIMIZED

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Default Primitive Directives:

Table 1. Default Behavior Primitive Table for SQL Server:
BEHAVIOR = Primitive Default Values | OPTIMIZED, MAINFRAME | ANSI
AUTOFETCH | ON | OFF
DEF_CURSOR | RO | UPD
RO_CURSOR | FORWARD or IC_FH | FORWARD or IC_FH
PF_RO_CURSOR | 1 | 1
IC_FH_ISOLATION | UR | UR
UPD_CURSOR | DYNAMIC | DYNAMIC
PF_UPD_CURSOR | 8 | 8
UPD_CONCURRENCY | LOCK | LOCK
ISOLATION | CR | CR
Table 2. Default Behavior Primitive Table for Other DBMSs:
BEHAVIOR = Primitive Default Values | OPTIMIZED, MAINFRAME | ANSI
AUTOFETCH | ON | OFF
DEF_CURSOR | RO | UPD
RO_CURSOR | FORWARD | FORWARD
PF_RO_CURSOR | 8 | 8
UPD_CURSOR | KEYSET | KEYSET
PF_UPD_CURSOR | 8 | 8
UPD_CONCURRENCY | LOCK | LOCK
ISOLATION | CR | CR

For more information on using BEHAVIOR to migrate your COBOL cursors, see the topic COBOL Program Migration Support.

You can fine tune the BEHAVIOR directive and override these default settings by providing alternate values for primitive directives. If you do this, you must set the TARGETDB directive.

Comments:

  • You can change the default setting to either ANSI or UNOPTIMIZED using the OpenESQL Configuration Utility. However, when the BEHAVIOR directive is specified in program code, project settings, or in a compiler directive file, the specified parameter overrides the default setting.
  • Setting this directive can also affect the SQL types returned when using Dynamic SQL. See the DESCRIBE Statement topic for more information.
  • OpenESQL sets default values for primitive directives depending on the value of BEHAVIOR and your target database. See the topic Primitive Directives for more information.
  • Primitive Directives
Parent topic: SQL Compiler Directive Options
Related concepts
Managing Transactions
Related reference
PREFETCH
esqlconfig command
DBMAN Directive Settings
SET CONCURRENCY
SET SCROLLOPTION
DESCRIBEDTCHAR
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT
CLOSE_ON_COMMIT


Primitive Directives

These directives work only with when you have your target database set and you have specified the BEHAVIOR directive as well. Specify them only when you want to override the default settings for BEHAVIOR. For example:

SQL(TARGETDB=INFORMIX BEHAVIOR=OPTIMIZED DEF_CURSOR=UPD)
  • DEF_CURSOR
    This cursor directive specifies the default cursor type for ambiguous COBOL cursors, either read only or updateable. Use this directive when the DECLARE CURSOR statement has neither the FOR READONLY nor the FOR UPDATE OF clause.
  • IC_FH_ISOLATION
    This directive sets the transaction isolation for independent firehose cursor connections, enabling simultaneous access to firehose cursors.
  • PF_RO_CURSOR
    This is a prefetch directive that enables you to retrieve more than one read only record at a time from the DBMS with one client request.
  • PF_UPD_CURSOR
    This is a prefetch directive that enables you to retrieve more than one updateable record at a time from the DBMS with one client request.
  • RO_CURSOR
    This directive determines what type of database cursor your COBOL read-only cursors use.
  • UPD_CONCURRENCY
    This directive enables you to choose the level of concurrency for updateable COBOL cursors.
  • UPD_CURSOR
    This directive determines what type of database cursor updateable COBOL cursors use.
Parent topic: BEHAVIOR
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DEF_CURSOR

This cursor directive specifies the default cursor type for ambiguous COBOL cursors, either read only or updateable. Use this directive when the DECLARE CURSOR statement has neither the FOR READONLY nor the FOR UPDATE OF clause.

Syntax:

DEF_CURSOR={RO | UPD}

Parameters:

RO | Read Only
UPD | Updateable

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

While the default when BEHAVIOR=ANSI is DEF_CURSOR=UPD, if the original developer assumed RO, then use of UPD could adversely affect performance.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


IC_FH_ISOLATION

This directive sets the transaction isolation for independent firehose cursor connections, enabling simultaneous access to firehose cursors.

Syntax:

 IC_FH_ISOLATION={UR | CR | RR | SZ}

Parameters:

UR | Uncommitted Read
CR | Committed Read
RR | Repeatable Read
SZ | Serializable isolation in ODBC

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


PF_RO_CURSOR

This is a prefetch directive that enables you to retrieve more than one read only record at a time from the DBMS with one client request.

Syntax:

PF_RO_CURSOR={numberofrows | buffersizeK | buffersizeB}

Properties:

Default for SQL Server connections: 8

Parameters:

numberofrows | The number of rows to retrieve
buffersizeK | The size of the buffer you want to fill in kilobytes
buffersizeB | The size of the buffer you want to fill in bytes

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • PF_RO_CURSOR must be set after TARGETDB and BEHAVIOR
  • Does not work with FORWARD or IC_FH selection in RO_CURSOR
  • SQL Server read-only server cursors now use PF_RO_CURSOR consistently across all runtimes
Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT


PF_UPD_CURSOR

This is a prefetch directive that enables you to retrieve more than one updateable record at a time from the DBMS with one client request.

Syntax:

PF_UPD_CURSOR={numberofrows | buffersizeK | buffersizeB}

Parameters:

numberofrows | The number of rows to retrieve
buffersizeK | The size of the buffer you want to fill in kilobytes
buffersizeB | The size of the buffer you want to fill in bytes

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • PF_UPD_CURSOR must be set after TARGETDB and BEHAVIOR
  • Does not work with FORWARD selection in RO_CURSOR
Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


RO_CURSOR

This directive determines what type of database cursor your COBOL read-only cursors use.

Syntax:

RO_CURSOR={SCROLL | FORWARD | DYNAMIC | KEYSET | STATIC | FF | IC_FH}

Parameters:

FF | Fast Forward
IC_FH | Independent Connection Fire Hose

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • SCROLL, FORWARD, DYNAMIC, and KEYSET are standard ODBC types.
  • FF and IC_FH are cursors specific to MS SQL Server.
  • Under MS SQL Server, prefetching does not work with FORWARD and IC_FH.
  • As its name indicates, an IC_FH cursor has its own independent connection to MS SQL Server. Because of this, these cursors are sensitive to the isolation level and locking protocol of previous data access in the application program.
  • When using a SQL Server connection that supports MARS, MARS is automatically enabled and IC_FH is converted to FORWARD.
Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


UPD_CONCURRENCY

This directive enables you to choose the level of concurrency for updateable COBOL cursors.

Syntax:

UPD_CONCURRENCY={LOCK | OPTIMISTIC | OPTCC | OPTCCVAL}

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

LOCK, OPTIMISTIC, OPTCC, and OPTCCVAL are standard ODBC types.

Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


UPD_CURSOR

This directive determines what type of database cursor updateable COBOL cursors use.

Syntax:

UPD_CURSOR={SCROLL | FORWARD | DYNAMIC | KEYSET | STATIC}

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • SCROLL, FORWARD, DYNAMIC, KEYSET, and STATIC are standard ODBC types.
  • Prefetching does not work with FORWARD.
Parent topic: Primitive Directives
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


CHECK

Sends each SQL statement to the database at compilation time.

Syntax:

[NO]CHECK

Properties:

Default: NOCHECK

Dependencies:

CHECK requires that you also:
  • Set the DB compiler directive option, or identify the database using the DB2DBDFT environment variable.
  • If the connection to the database specified requires authentication, then the PASS compiler directive option is also required.
  • When using SQL(CHECK) with an ODBC connection to Oracle, you must have at least the same user privileges as are required to execute the SQL statements in the program.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Depending on your driver and/or DBMS and in certain circumstances, CHECK does not flag invalid SQL statements.

You can specify the [NOCHECK], [ALSO CHECK], or [WITH CHECK] statement prefix to affect specific SQL statements. See SQL Statement Prefixes for CHECK Directive for complete information.

Important: For applications that use JDBC with the JVM Managed Runtime, be sure that your environment is configured appropriately. Otherwise, compilation could fail. See To create a JVM COBOL project for JDBC and Configuring the JDBC Run-time Environment for details.
Parent topic: SQL Compiler Directive Options
Related concepts
SQL Syntax Checking with OpenESQL
SQL(CHECK) Command-line Options
SQL Statement Prefixes for SQL(CHECK)
SQL(CHECK) and Schema Objects
Configuring the JDBC Run-time Environment
JDBC Resources
Scope - OpenESQL SQL Compiler Directive Options
Building applications
Related reference
DB
JNDI
IGNORESCHEMAERRORS


CHECKDUPCURSOR

Instructs OpenESQL to determine if the cursor has been opened twice, and if so takes action accordingly.

Syntax:

[NO]CHECKDUPCURSOR

Properties:

Default: NOCHECKDUPCURSOR

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

If the cursor has been opened twice and the NOANSI92ENTRY directive has also been specified, CHECKDUPCURSOR returns SQLCODE -516 and sets SQLSTATE=24000.

If the cursor has been opened twice and ANSI92ENTRY has not been specified, NOCHECKDUPCURSOR automatically closes the cursor and then re-opens it.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings
SQLCODE Values


CHECKSINGLETON

Instructs OpenESQL to check if singleton SELECTs return more than one row when executed.

Syntax:

[NO]CHECKSINGLETON

Properties:

Default: None

Returns:

Directive | SQLCODE returns | SQLSTATE returns
None (default)* | +1 | 21000
CHECKSINGLETON | -811 | 21000
NOCHECKSINGLETON | 0 | 21000
*When ANSI92ENTRY is specified without CHECKSINGLETON or NOCHECKSINGLETON (default), SQLCODE returns -1 and SQLSTATE returns 21000. See ANSI92ENTRY for additional details.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • CHECKSINGLETON is provided for DB2 compatibility.
  • NOCHECKSINGLETON is provided for applications that require SQLCODE 0.
  • For applications that require SQLCODE -1, specify ANSI92ENTRY without CHECKSINGLETON or NOCHECKSINGLETON.
  • OpenESQL returns the following SQLDA diagnostics when a singleton SELECT returns more than one row:
    SQLCODE | SQLSTATE | SQLWARN4 Flag
    -811 | 21000 | W
    0 | 00000 | space
    +1 | 21000 | W
    -1 | 21000 | W

    For more information, see SQLCODE Values, SQLSTATE Values, and The SQLCA Data Structure.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings
The SQLCA Data Structure
SQLSTATE Values
ANSI92ENTRY
SQLCODE Values


CLOSE_ON_COMMIT

Specifies whether to close cursors not defined WITH HOLD or leave them open for further fetches after a COMMIT.

Syntax:

CLOSE_ON_COMMIT={YES | NO}

Parameters:

YES
Close cursors on COMMIT.
NO
Leave cursors open on COMMIT.

Properties:

Default: YES

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

By default, meaning CLOSE_ON_COMMIT is not specified or CLOSE_ON_COMMIT=YES is specified, all cursors not declared WITH HOLD are closed after a COMMIT.

CLOSE_ON_COMMIT works with the BEHAVIOR directive as follows:

BEHAVIOR=UNOPTIMIZED
CLOSE_ON_COMMIT is ignored. Cursor selection is least optimal. Cursor remains open after COMMIT.

Provides backward compatibility with Net Express.

BEHAVIOR=OPTIMIZED or ANSI, CLOSE_ON_COMMIT=YES (default)
Cursor selection is optimal. Cursor is closed after COMMIT.
BEHAVIOR=OPTIMIZED or ANSI, CLOSE_ON_COMMIT=NO
Cursor selection is optimal. Cursor remains open after COMMIT.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
BEHAVIOR


CONCAT

Specifies the ASCII character code to use for the CONCAT symbol (|). Use this directive only if you need to change the default.

Syntax:

CONCAT=ascii-character-code

Properties:

Default: CONCAT=33.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

When setting this directive, be sure to appropriately set the LANG environment variable when compiling your program .

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
NOT
Environment Variables


CONNECTIONPOOL

Enables use of ODBC 3.0 connection pooling. When a connection is closed, the Driver Manager actually keeps it alive for a timeout period, and saves the overhead of re-establishing a connection from scratch if the application re-opens an identical connection. ODBC allows you to choose between having a pooling for an ODBC environment or for each driver. See your ODBC documentation for details.

This option is only useful for applications that frequently open and close connections. Note that some environments, such as Microsoft Transaction Server (MTS), control connection pooling themselves. This option will probably improve the performance of ISAPI applications that are not running under MTS.

Syntax:

CONNECTIONPOOL={DRIVER | ENVIRONMENT | NONE}

Properties:

Default: CONNECTIONPOOL=NONE.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


CTRACE

Causes debug information to be put into the file sqltrace.txt.

Syntax:

[NO]CTRACE

Properties:

Default: NOCTRACE.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


CURSORCASE

If ESQLVERSION is 2.0, CURSORCASE is implied. NOCURSORCASE means that cursor names are not case sensitive. CURSORCASE means that they are case sensitive. Note that in previous versions of OpenESQL, cursor names have been case sensitive.

Syntax:

[NO]CURSORCASE

Properties:

Default: NOCURSORCASE

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DATE

Specifies the explicit date format to use when date values are returned from database date columns into character output host variables.

When used in addition to DETECTDATE, also specifies the explicit data format to recognize in character input host variables.

Syntax

DATE={ODBC | ISO | USA | EUR | JIS}

Parameters:

ODBC
yyyy-mm-dd (ISO 8601 default format)
ISO
yyyy-mm-dd (mainframe default format)
USA
mm/dd/yyyy
EUR
dd.mm.yyyy
JIS
yyyy-mm-dd

Properties:

Default: ODBC (ISO 8601 default format)

Dependencies:

For input host parameters, requires that the DETECTDATE SQL compiler directive option is also set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

DATE can be used with the DATEDELIM directive to specify an alternative delimiter that separates day, month, and year components.

DATE, with or without DATEDELIM, changes the display format of output host variables as specified.

When you specify both DATE and DETECTDATE, OpenESQL uses DATE (with or without DATEDELIM) to also recognize date values in your input host variables. See DETECTDATE for more information.

Important: If you do not specify an alternative format using DATE, OpenESQL returns your date columns using the ISO 8601 default format in your output character host variables, as specified in the Properties section of this topic. The same is also true of input character host variables when DETECTDATE is specified in addition to DATE.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Related reference
DETECTDATE
TIME
DATEDELIM
TSTAMPSEP
SET host_variable
SET OPTION
DATE


DATEDELIM

Specifies a single character as the delimiter between the year, month, and day components to override the default delimiter determined by the DATE directive specification, or implicitly based on default ISO 8601 format (yyyy-mm-dd).

The specified delimiter is used in character output host variables and, if DETECTDATE is also specified, in character input host variables.

Syntax

DATEDELIM=character

Properties:

Default: None

Dependencies:

None; however, DATEDELIM can be used with DATE to specify an alternative delimiter. See DATE for details.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

DATEDELIM set without DATE overrides the default ISO 8601 delimiter, a dash (-) character, for date values.

DATEDELIM set with DATE overrides the default delimiter for the specified DATE parameter. For example, the default delimiter for DATE=USA is a forward slash character (/).

See DATE, DETECTDATE, and OpenESQL Datetime Data Types Handling for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Related reference
DETECTDATE
DATE
SET host_variable
SET OPTION
DATE


DB

Identifies a data source that defines database connection information.

Syntax:

DB=connection
NODB

Parameter:

connection
The value for this parameter varies depending on the runtime:
ODBC Runtime | An ODBC DSN
JVM Managed Runtime | The name of a JNDI DataSource object

Properties:

Default: NODB

Dependencies:

At compile time, DB is required when you set SQL(CHECK).

At run time, DB is required when you set SQL(INIT).

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments

The .int file generated is the same except for the TARGETDB number embedded in the file.

Parent topic: SQL Compiler Directive Options
Related concepts
Database Connections
JNDI DataSource Objects
Scope - OpenESQL SQL Compiler Directive Options
Building applications
Related reference
CHECK
INIT
JNDI


DBMAN

Specifies the preprocessor to use. This directive is not required when compiling programs with OpenESQL.

Syntax:

DBMAN={ODBC | JDBC}

Parameters:

ODBC | For native code
JDBC | For JVM managed code

Properties:

Default:

DBMAN=ODBC for native applications

DBMAN=JDBC for JVM applications (see JVMGEN)

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
ODBC
JDBC
Scope - OpenESQL SQL Compiler Directive Options
Building applications
Related reference
DBMAN Directive Settings
DBRMLIB
MEMBER
VERSION
DIALECT


DECDEL

Specifies the decimal delimiter to use for decimal variables.

Syntax:

DECDEL={PERIOD | COMMA | LOCAL}
NODECDEL

Parameters:

PERIOD
Always use a period (.) as a decimal delimiter.
COMMA
Always use a comma (,) as a decimal delimiter.
LOCAL
Call GetLocaleInfo one time to get the decimal delimiter.
NODECDEL
Call GetLocaleInfo every time a decimal variable is referenced. Use this when your application dynamically changes it's effective locale at runtime.

Properties:

Default: LOCAL

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DESCRIBEDTCHAR

When using dynamic SQL, described or prepared SQL statements with DATE, TIME, and DATETIME columns are suitable for PIC X(n) character host variables or DATE, TIME, and TIMESTAMP SQL TYPEs.

Syntax:

DESCRIBEDTCHAR

Properties:

Default: None

Dependencies:

BEHAVIOR=OPTIMIZED automatically sets DESCRIBEDTCHAR.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For dynamic SQL, by default, OpenESQL expects DATE, TIME and TIMESTAMP columns to be placed into host variables of DATE, TIME, and TIMESTAMP-RECORD SQL TYPEs in ODBC format record structures.

When BEHAVIOR=OPTIMIZED or DESCRIBEDTCHAR is set, OpenESQL expects DATE, TIME, and DATETIME columns to be placed into PIC X(n) character host variables or DATE, TIME, and TIMESTAMP SQL TYPEs.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
BEHAVIOR
DATE SQL Type
TIME SQL Type
TIMESTAMP SQL Type


DESCRIBEDTREC

When using dynamic SQL, described or prepared SQL statements with DATE, TIME, and DATETIME, columns are suitable for the DATE, TIME, and TIMESTAMP-RECORD SQL TYPEs in ODBC format record structures.

Syntax:

DESCRIBEDTREC

Properties:

Default: DESCRIBEDTREC

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For dynamic SQL, by default, OpenESQL expects DATE, TIME and TIMESTAMP columns to be placed into host variables of DATE, TIME, and TIMESTAMP-RECORD SQL TYPEs in ODBC format record structures.

Use DESCRIBEDTREC to override BEHAVIOR=OPTIMIZED set by DESCRIBEDTCHAR.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DATE SQL Type
TIME SQL Type
TIMESTAMP-RECORD SQL Type


DESCRIBEVARCHAR49

When using dynamic SQL, described or prepared SQL statements with VARCHAR, columns are suitable for VARCHAR host variables with level 49 sub-fields for length and data.

Syntax:

DESCRIBEVARCHAR49

Properties:

Default: None

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For dynamic SQL, by default, OpenESQL expects VARCHAR columns to be placed into PIC X host variables.

Use DESCRIBEVARCHAR49 to enable the use of VARCHAR host variables with level 49 sub-fields for length and data.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DESCRIBEVARCHARPICX

When using dynamic SQL, described or prepared SQL statements with VARCHAR, columns are suitable for PIC X host variables.

Syntax:

DESCRIBEVARCHARPICX

Properties:

Default: DESCRIBEVARCHARPICX

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For dynamic SQL, by default, OpenESQL expects VARCHAR columns to be placed into PIC X host variables.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DETECTDATE

Allows datetime values for PIC X character input host variables in an OpenESQL application to be in different formats than the standard ISO 8601 formats.
DETECTDATE enables you to specify alternative formats for input host variables. OpenESQL manages the translation between the format specified by DETECTDATE and the format recognized by your DBMS. This is done for each SQL call on both input and output.

For example, instead of the standard ISO formats, you might prefer to use EUR formats for date and time data.

Important: Use DETECTDATE with extreme caution and only when absolutely necessary. Before using DETECTDATE, carefully review all options specified here, all of the information presented in OpenESQL Datetime Data Types Handling, and the information in the DATE, DATEDELIM, TIME, and TIMEDELIM topics to help you determine the best fit for your application.

Syntax:

[NO]DETECTDATE
DETECTDATE={CLIENT | SQLTYPE | SERVER | PICX}

Parameters:

CLIENT
Applies to DBMAN=ODBC only.
Input Host Variables
For PIC X character input host variables, OpenESQL recognizes specified datetime formats and translates the data into the ISO 8601 format acceptable to your DBMS. Specified datetime formats for input host variables are:
Date
ISO 8601 default, can be overridden by specifying the DATE directive and/or the DATEDELIM directive.
Time
ISO 8601 default, can be overridden by specifying the TIME directive and/or the TIMEDELIM directive.
Datetime
ISO 8601 default, can be overridden by specifying the TSTAMPSEP directive.

The dash character instructs OpenESQL to look for a specific set of delimiters, including a dash, a space, and a T. For example if you do not specify any alternative date or time formats, and you set TSTAMPSEP to a dash character (-), OpenESQL recognizes the following formats in your input host variables:

  • yyyy-mm-dd-hh.mm.ss.ffffff
  • yyyy-mm-dd hh.mm.ss.ffffff
  • yyyy-mm-dd hh:mm:ss.ffffff
  • yyyy-mm-ddThh.mm.ss.ffffff
  • yyyy-mm-ddThh:mm:ss.ffffff

All other characters instruct OpenESQL to search for that specific character between each date and time format, where the date portion is delimited by a dash character (-) and the time portion is delimited by a colon (:).

Output Host Variables
For PIC X output character host variables, OpenESQL returns the data for output host variables in the following datetime formats:
Date
ISO 8601 default, can be overridden by specifying the DATE directive and/or the DATEDELIM directive.
Time
ISO 8601 default, can be overridden by specifying the TIME directive and/or the TIMEDELIM directive.
Timestamp
ISO 8601 default, can be overridden by specifying the TSTAMPSEP directive. When TSTAMPSEP is set to a dash (-) character (TSTAMPSEP="-"), OpenESQL returns datetime columns in the following format:

yyyy-mm-dd-hh.mm.ss.ffffff

SQLTYPE
Note: Deprecated feature starting with Visual COBOL version 2.3, and provided for backward compatibility only. Datetime processing of SQLTYPE host variables is now independent of DETECTDATE.
Applies to DBMAN=ODBC only. Processing is identical to the CLIENT option, but applies only to SQLTYPE host variables and not PIC X.
SERVER
Applies to DBMAN=ODBC only.

Issues SQLDescribeParam calls to the DBMS to identify which input and output host variables are associated with specific character or datetime columns in the database. Host variables associated with datetime columns are translated with the datetime formats listed in CLIENT. Character columns are not translated.

PICX
Identical to the CLIENT option. Provided for backward compatibility.

Properties:

Defaults: When DETECTDATE is not specified, the default is: NODETECTDATE

When DETECTDATE with no argument is specified, the default is: DETECTDATE=CLIENT

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL Compiler Directive Options for more information.

Comments:

  • Use DETECTDATE=CLIENT only when your OpenESQL application does not use character columns in the database to store data that is a match to any of the alternative formats for the date, time or datetime fields in your DBMS.
  • Use DETECTDATE=SERVER when your OpenESQL application uses datetime values in both datetime and character columns of tables in your database.
    Note: DETECTDATE=SERVER does cause OpenESQL to perform extra overhead processing on each applicable SQL statement.
  • Datetime formats are defined implicitly unless you set them explicitly by specifying the DATE, DATEDELIM, TIME, and/or TIMEDELIM directives. See DATE, TIME, DATEDELIM, and TIMEDELIM for more information.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Building applications
Related reference
TIME
DATE
DATEDELIM
TIMEDELIM
TSTAMPSEP
SET host_variable
SET OPTION


ESQLVERSION

Sets OpenESQL syntax level.

Syntax:

Note: Micro Focus plans to deprecate ESQLVERSION in a future release.
ESQLVERSION={1.0 | 2.0 | 3.0}

Properties:

Default: ESQLVERSION=3.0

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


FIPSFLAG

Enables FIPS flagging (NIST certification requirement only).

Syntax:

[NO]FIPSFLAG

Properties:

Default: NOFIPSFLAG.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


GEN-CC2

Generates ESQL API calls using call convention 2 instead of call convention 74.
Note:
  • Use GEN-CC2 to emulate application generation as done using Net Express 3.0.
  • Micro Focus plans to deprecate GEN-CC2 in a future release.

Syntax:

[NO]GEN-CC2

Properties:

Default: NOGEN-CC2

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


GEN-CLASS-VAR

Enables backward compatibility with OO SQL COBOL programs migrated from Net Express, and instructs the OpenESQL preprocessor to generate SQL interface variables at the end of object storage in addition to the end of local storage.

Syntax:

[NO]GEN-CLASS-VAR

Properties:

Default: NOGEN-CLASS-VAR

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


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.

Syntax:

[NO]GEN-HV-FROM-GROUP

Properties:

Default: NOGEN-HV-FROM-GROUP

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Recompile using GEN-HV-FROM-GROUP if your code contains a multiple-level group name in a FETCH or singleton SELECT and the compiler throws the following error:

COBES0103 token does not have a suitable definition to be used as a host variable.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


GEN-INIT-FLAG

Generates the SQL-INIT-FLAG variable for DB2 for OS/390 compatibility. The flag is updated when the SQL environment is initialized. If you define this variable in your application, compile your application with this directive set to NOGEN-INIT-FLAG and the variable will not be generated by the precompiler.

Syntax:

[NO]GEN-INIT-FLAG

Properties:

Default: NOGEN-INIT-FLAG

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


GEN-SQLCA

Generates an SQLCA equivalent to coding an EXEC SQL INCLUDE SQLCA statement in an application program.

Syntax:

[NO]GEN-SQLCA

Properties:

Default: NOGEN-SQLCA

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

If SQLCODE is defined in the application, the generated copybook defines SQLCODE and ensures that SQLCODE is updated appropriately on every SQL statement with that value.

If SQLSTATE is defined in the application, the copybook defines SQLSTATE and ensures that SQLSTATE is updated appropriately on every SQL statement with that value.

If SQLCODE or SQLSTATE is not defined in the application, the generated copybook defines them.

This behavior is equivalent to STDSQL(YES) on mainframe DB2 z/OS.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
The SQLCODE Variable
The SQLSTATE Variable


HSFTRACE

Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.

Syntax:

[NO]HSFTRACE

Properties:

Default: HSFTRACE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

SMFTRACE is an alias for HSFTRACE.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Configuring and Starting Transaction Data Collection


IGNORE-NESTED

In nested programs, this is the program-id at which to start generating the database interface code. If the program file name matches the program-id, you can just specify IGNORE-NESTED.

Syntax:

IGNORE-NESTED=program-id
NOIGNORENESTED

Properties:

Default: NOIGNORE-NESTED.

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


IGNORESCHEMAERRORS

Suppresses compile-time errors resulting from missing schema objects.

Syntax:

[NO]IGNORESCHEMAERRORS

Properties:

Default: NOIGNORESCHEMAERRORS

Dependencies

To use IGNORESCHEMAERRORS, you must also set CHECK.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

By setting both IGNORESCHEMAERRORS and CHECK, OpenESQL checks for SQL syntax errors without reference to the database schema. This can be helpful when planning an application migration, as you can use the COBOL compiler and OpenESQL to identify the statements that require remediation without having to first migrate the database schema. It also provides enhanced OpenESQL syntax checking during the development phase.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
CHECK


INIT

When set without parameters, the preprocessor automatically generates code to make the connection to the database. When set with the PROT parameter, protects the database when an application terminates abnormally.
Note: The INIT directive (without PROT) is deprecated, and provided for backward compatibility only. We strongly recommend that you use EXEC SQL CONNECT statements in your application instead.

Syntax:

INIT[={[PROT|P]}]
NOINIT

Parameters:

INIT | Generates a CONNECT statement in shared mode, and also generates exit handling code
INIT=PROT | Generates exit handling code only.
INIT=P
NOINIT | No code generation whatsoever.

Properties:

Default: NOINIT

Dependencies:

If your INIT call generates a connection, you can use it with the DB and PASS SQL compiler directive options.

Comments:

  • For the following reasons, we strongly recommend that you consider placing an EXEC SQL CONNECT statement into your code instead of using INIT, INIT=S or INIT=X :
    • INIT actually stores user credentials in your code, so its use can raise security concerns.
    • If the DBMS vendor were to change the underlying APIs used to implement a database connection, this could cause compatibility problems when using INIT.
  • Set the INIT directive, with or without PROT, only once for each application. Do not set INIT for SQL programs called by other SQL programs. Instead, specify the INIT option for the first SQL program executed in a run unit. Compiling more than one module in an application with the INIT option could cause your program to terminate abnormally.
  • INIT is ignored when used within an OO program.
Parent topic: SQL Compiler Directive Options
Related concepts
Database Connections
Scope - OpenESQL SQL Compiler Directive Options
Building applications
Compiling Multiple Program Modules
Related reference
DB
JNDI


ISOLATION

This directive specifies the isolation level that OpenESQL uses as a connection attribute. It also serves as a primitive directive for the BEHAVIOR directive option.

Syntax:

ISOLATION={UR | CR | RR | SZ}

Parameters:

UR | Uncommitted Read
CR | Committed Read
RR | Repeatable Read
SZ | Serializable isolation in ODBC

Properties:

Default: CR

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


JIT

Generate OpenESQL interface code only if an EXEC SQL statement is found in the procedure division.

Syntax:

[NO]JIT

Properties:

Default: NOJIT

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


JNDI

Enables you to specify a JNDI class to use to look up the connection string for the data source name specified in the EXEC SQL CONNECT statements, or at compile time as specified by the SQL(DB) compiler directive if the SQL(CHECK) compiler directive is also specified.
Important: We highly recommend that you code EXEC SQL CONNECT statements into your application for use at runtime rather than using the INIT directive to generate the code for the connection to the database.

Syntax:

JNDI=JNDIContextFactoryClassName

Parameters:

JNDIContextFactoryClassName The Java context factory class name.

Properties:

Default: An empty string.

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

JNDI is effective at both compile time and runtime.

JNDI is equivalent to setting the Context.INITIAL_CONTEXT_FACTORY class in a Java application.

We do not recommend using Simple-JNDI for production deployment; however, when doing initial testing with a Java application server, you can use Simple-JNDI rather than the application server's JNDI implementation. To do this, specify:

SQL(JNDI=org.osjava.sj.SimpleContextFactory)

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
PASS
DB
CHECK
INIT


JNDIENC

Enables applications to use the JNDI Environment Naming Context (ENC) when looking up JDBC data source names using JNDI.

Syntax:

JNDIENC=jndiEnc

Parameters:

jndiEnc The JNDI ENC specification.

Properties:

Default: An empty string.

Scope:

Used at compile time: | Yes
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • You can test the JNDIENC directive option using Simple-JNDI by adding ENC-specific code to the jndi.properties file. For example:
    # Use an Environment Naming Context (ENC)
org.osjava.sj.space=java:/comp/env
# LDAP/XPath like delimiters
org.osjava.sj.delimiter=/
    JNDIENC is not required when using Simple-JNDI in standalone applications; however, it can be useful if you intend to deploy your standalone application to a Java application server because it eliminates the need to change the JNDIENC setting when switching between test and deployment environments.
  • When deploying applications to a Java application server, JNDIENC is required to specify the ENC that the server uses for data sources. For example, the Tomcat server requires:
    SQL(JNDIENC=java:/comp/env)
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


MARS

Enable multiple active results sets when connecting to an Microsoft SQL Server 2005 or later.

Syntax:

MARS

Dependencies:

To use this directive, you must also specify TARGETDB=MSSQLSERVER.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

For SQL Server connections, a forward-only read-only non-hold cursor always uses a firehose cursor with no prefetching. There is no beneft in prefetching firehose cursors because the server streams the result set to the client for firehose cursors.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Building applications


NIST

Sets OpenESQL to conform to the NIST interpretation of the SQL ANSI 92 entry level standard.

Syntax:

[NO]NIST

Properties:

Default: NONIST

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


NOT

Specifies the character code to use for NOT symbol (¬). Use this only if you need to change the default setting.

Syntax:

NOT=ascii-character-code

Properties:

Default: NOT=172

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

When setting this directive, be sure to appropriately set the LANG environment variable when compiling your program .

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
CONCAT
Environment Variables


ODBCTRACE

ODBCTRACE=USER enables you to control ODBC tracing via odbc.ini from which you can specify the file that the trace goes into.

ALWAYS lets you control ODBC tracing via a directive, which is more convenient from within the IDE. ALWAYS generates the trace into MFSQLTRACE.LOG in the current directory, regardless of the settings in odbc.ini.

Under normal development conditions, and depending on the project's build setting, this is the Debug or Release directory of the current project. NEVER means that the application will never be traced and overrides odbc.ini . As ODBC trace files can contain sensitive information, use NEVER in production applications in secure environments. For more information see the database driver documentation.

Syntax:

ODBCTRACE={ALWAYS | NEVER | USER}

Properties:

Default: ODBCTRACE=USER.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


ODBCV3

This directive causes an application to register itself as an ODBC Version 3 application.

Syntax:

[NO]ODBCV3

Properties:

Default: NOODBCV3

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

If ODBCV3 is not specified, the application registers itself as an ODBC Version 2 application. There can be a small performance benefit in registering as an ODBC 3 application. However, registering as an ODBC Version 3 application can result in error and warning conditions returning different values for SQLCODE and SQLSTATE.

We recommend that you use this directive with care.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


OPTIMIZECURSORS

Optimizes memory consumption when using Oracle, PostgreSQL, DB2, or SQL Server JDBC providers. Also applies the same data integrity rules on all databases for embedded SQL cursors that use WITH HOLD and FOR UPDATE clauses for both DBMAN=ODBC and DBMAN=JDBC.

Syntax:

OPTIMIZECURSORS={YES|NO}

Parameters:

YES
Optimize cursors. This can result in considerable memory savings and performance gains for large result sets, and also ensures that SQL cursors that use WITH HOLD and FOR UPDATE clauses have appropriate database locks when positioned updates/deletes occur.
NO
Provided for backward compatibility. Sets the behavior to that of Visual COBOL versions before 3.0.

Properties:

Default: YES

Dependencies:

To use OPTIMIZECURSORS, you must set DBMAN to either ODBC or JDBC explicitly, or by setting an SQL compiler directive option that sets DBMAN to ODBC or JDBC implicitly.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options


OPTION (deprecated)

Enables non-default optional behavior.
Note: OPTION is deprecated, and supported for backward compatibility only. We recommend that you use equivalent SQL compiler directive options instead.

Syntax:

OPTION={[NO]IGNORESCHEMAERRORS |
 [NO]SPDISPLAY | [DESCRIBEVARCHARPICX |
DESCRIBEVARCHAR49] | [DESCRIBEDTREC | DESCRIBEDTCHAR] | OPTIMIZESPCURSORS}...

Parameters:

IGNORESCHEMAERRORS
When SQL(CHECK) is also specified, suppresses compile time errors resulting from missing schema objects. In this mode, you can use OpenESQL to check for SQL syntax errors without reference to the database schema. This can be helpful when planning an application migration, as you can use the COBOL compiler and OpenESQL to identify the statements that require remediation without having to first migrate the database schema. It also provides enhanced OpenESQL syntax checking during the development phase. Default is NOIGNORESCHEMAERRORS.
SPDISPLAY
Determines where COBOL DISPLAY information can be accessed. When set for a SQL CLR stored procedure, COBOL DISPLAYs are sent back to the caller as SQL Server information messages. When set for a COBOL application, SQL Server information messages are written to the console. When a COBOL stored procedure is called using an interactive SQL tool, such as SQL Server Management Studio, information messages are shown via the message output provided by the tool.

SPDISPLAY can be useful for tracing during debugging and for logging in deployed applications. If not set, then COBOL DISPLAY statements have no effect. Default is NOSPDISPLAY.

DESCRIBEVARCHARPICX
VARCHAR columns are suitable for PIC X host variables. Default.
DESCRIBEVARCHAR49
VARCHAR columns are suitable for VARCHAR host variables with level 49 sub-fields for length and data.
DESCRIBEDTREC
DATE, TIME, and DATETIME columns are suitable for the DATE, TIME, and TIMESTAMP-RECORD SQL TYPEs in ODBC format record structures. Default.
DESCRIBEDTCHAR
DATE, TIME, and DATETIME columns are suitable for PIC X(n) character host variables or DATE, TIME, and TIMESTAMP SQL TYPEs.

Properties:

Default: None

Dependencies:

BEHAVIOR=OPTIMIZED automatically sets DESCRIBEDTCHAR.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

Separate each instance of OPTION with a space.

Examples:

SQL(OPTION=DESCRIBEVARCHARPIX)
SQL(OPTION=DESCRIBEVARCHARPIX OPTION=IGNORESCHEMAERRORS)
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Working with Stored Procedures and Result Sets
Related reference
IGNORESCHEMAERRORS
DESCRIBEDTCHAR
DESCRIBEDTREC
DESCRIBEVARCHAR49
DESCRIBEVARCHARPICX


OPTPER

Causes the OpenESQL preprocessor to optimize the performance of CHARSET"EBCDIC" processing.

Syntax:

[NO]OPTPER

Properties:

Default: OPTPER

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

OPTPER is on by default across all platforms

Optionally, you can turn OPTPER off by using NOOPTPER.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


PARAMARRAY

If PARAMARRAY is set, ODBC array binding is used, if it is supported by the ODBC driver, for all input parameters.

Syntax:

[NO]PARAMARRAY

Properties:

Default: PARAMARRAY.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


PASS

The login to use to connect to the data source. This option works in conjunction with the INIT and/or CHECK options.

Syntax:

PASS={password | userid.password}
NOPASS

Properties:

Default: NOPASS

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Database Connections
Scope - OpenESQL SQL Compiler Directive Options
Related reference
JNDI
INIT
CHECK


PICXBINDING

Specifies the handling of fixed-length PIC X(n) host variables.

Syntax:

PICXBINDING={DEFAULT | PAD | TRIM | TRIMALL | FIXED | VARIABLE}

Parameters:

DEFAULT
SQL Server - SBCS locales
Always passes PIC X(n) host variables to SQL Server as fixed-length data, and trims trailing spaces. The ODBC driver pads the data with spaces before presenting it to SQL Server.
SQL Server - DBCS locales
Always passes PIC X(n) host variables to SQL Server as variable-length data, and trims trailing spaces. If the PIC X(n) host variable is all spaces, present one space to SQL Server.
All other DBMSs in all locales
Always passes PIC X(n) host variables to the DBMS as fixed-length data, and trims trailing spaces. If the PIC X(n) host variable is all spaces, present one space to the DBMS.
PAD or FIXED
Always preserves trailing spaces for all DBMSs in all locales, and passes the data to the DBMS as fixed-length data.
TRIM or VARIABLE
Always trims trailing spaces for all DBMSs in all locales. If the PIC X(n) host variable is all spaces, presents one space to the DBMS and passes the data to the DBMS as variable-length data.
TRIMALL
Always trims trailing spaces for all DBMSs in all locales. If the PIC X(n) host variable is all spaces, presents an empty string to the DBMS and passes the data to the DBMS as variable-length data.

Properties:

Default: DEFAULT

Dependencies:

ALLOWNULLCHAR is compatible with PICXBINDING only when PICXBINDING is omitted (meaning it is set to DEFAULT by default) or explicitly set to DEFAULT. Because PICXBINDING is designed to be used with PIC X(n) host variables that contain character data, not embedded binary data such as the NULL character ('\0'), an attempt to use ALLOWNULLCHAR when PICXBINDING is set to VARIABLE or FIXED could return unpredictable results.

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For PIC X(n) host variables that contain all spaces, consider the following effects of PICXBINDING parameters when inserting into VARCHAR columns:

  • DEFAULT with SQL Server inserts a space-padded column
  • DEFAULT with all non-SQL Server DBMSs inserts one space into the column
  • PAD with all DBMSs inserts a space-padded column
  • TRIM with all DBMSs inserts one space into the column
  • TRIMALL with Oracle inserts a NULL value into the column
  • TRIMALL with all non-Oracle DBMSs inserts an empty string into the column
Parent topic: SQL Compiler Directive Options
Related concepts
OpenESQL Fixed-length Character Strings Handling
Scope - OpenESQL SQL Compiler Directive Options
Related reference
ALLOWNULLCHAR


PRE

Instructs the preprocessor to generate code that dynamically loads the OpenESQL module at run time.

Syntax:

[NO]PRE

Properties:

Default: PRE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

The OpenESQL module on UNIX is either odbcrunx.so or odbcrunx64.so for unthreaded, or either odbcrunx_t.so or odbcrunx64_t.so for threaded.

PRE must be used when creating INT or GNT files.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


PREFETCH

An application can use this directive to request that OpenESQL use block fetches for cursors. This can provide performance benefits, similar to array fetching, without having to change program logic. The performance benefit depends on the value of n and on whether the ODBC driver in use is already configured to use prefetching.

If n is less than 1000, it controls the number of rows to be fetched per batch and the same number of rows is fetched for all cursors. If n is greater than or equal to 1000, it sets the size of the prefetch buffer for each cursor. All cursors will have the same buffer size but the number of rows prefetched will depend on the overall size of the row returned by the query for each cursor.

When PREFETCH=n is used with Microsoft SQL Server, AUTOFETCH is also used for read only cursors. Cursors which are not read only are forced to be keyset cursors and can be used for positioned updates. PREFETCH=n is only supported with DB2, Oracle and Microsoft SQL Server.

Syntax:

PREFETCH=n

Properties:

Default: PREFETCH=8

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comment:

Much of the functionality provided by PREFETCH is now incorporated into the functionality of the BEHAVIOR SQL compiler directive option. As a result, PREFETCH is likely to be deprecated in a future release.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
BEHAVIOR


QUALFIX

Causes the OpenESQL preprocessor to append three characters to the name of the host variables when declaring them to SQL. This ensures problems caused by qualification (where two or more host variables have identical names when not qualified) are avoided but has the side-effect that SQL error messages sometimes display the names of host variables with the three additional characters appended to them.

Syntax:

[NO]QUALFIX

Properties:

Default: NOQUALFIX

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


RESULTARRAY

If RESULTARRAY is set, ODBC array binding is used, if it is supported by the ODBC driver, for all output parameters.

Syntax:

[NO]RESULTARRAY

Properties:

Default: RESULTARRAY.

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


SAVE-RETURN-CODE

Specifies whether or not to save and then restore RETURN-CODE.

Syntax:

[NO]SAVE-RETURN-CODE

Properties:

Default: SAVE-RETURN-CODE

Comments:

Use NOSAVE-RETURN-CODE if your COBOL dialect does not recognize the COBOL special register RETURN-CODE.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


STMTCACHE

The number of prepared SQL statements OpenESQL can cache such that the statements never again require preparation during a program run, thus improving performance.

Syntax:

STMTCACHE=n

Parameter:

n Any number; however we recommend that you set this to a number between 20 and 300

Properties:

Default: STMTCACHE=20

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

Exercise caution with this directive as STMTCACHE is a trade off between performance and memory use.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


TARGETDB

Set this directive if you want to optimize performance for a specific data source.

Syntax:

TARGETDB={MSSQLSERVER | ORACLE | INFORMIX |
          SYBASE | DB2 | ORACLE7 | POSTGRESQL}
NOTARGETDB

Properties:

Default: NOTARGETDB

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

When TARGETDB=DB2, OpenESQL retains the generated FOR READ ONLY clause to assist DB2 in generating a more efficient access plan.

With the vast majority of non-DB2 databases, the FOR READ ONLY clause has no effect on the access plan that the database server generates for a query. This, in combination with the fact that FOR READ ONLY syntax is not supported by most servers, OpenESQL removes the generated FOR READ ONLY clause at compile time unless TARGETDB is set to DB2. Removing this clause can facilitate code migration between different database servers, and can also facilitate the incorporation of code that works with multiple types of database servers.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
DBMAN Directive Settings


TESTSQLSTATE

Instructs OpenESQL to generate code that tests SQLSTATE rather than SQLCODE after an SQL statement is executed.

Syntax:

TESTSQLSTATE
NOTESTSQLSTATE

Properties:

Default: NOTESTSQLSTATE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Example:

           invoke wCLRRTS "adoastop" using
               by reference SQLCA
           move SQLCA(13:4) to MFSQLECM-SQLCODE-2(1:4)
           move SQLCA(101:1) to MFSQLECM-SQLWARN
           move SQLCA(132:2) to MFSQLECM-SQLSTATE-2
           perform MFSQLECM-UPD-SQLCA-2
           if MFSQLECM-SQLSTATE-2 not = "00" and MFSQLECM-SQLSTATE-2 not
      -        = "01" and MFSQLECM-SQLSTATE-2 not = "02"
               go to SQL-ERROR
           end-if
           if MFSQLECM-SQLCODE-2 > 0 and MFSQLECM-SQLCODE-2 not = 100
               move "W" to MFSQLECM-SQLWARN
           else
               if MFSQLECM-SQLCODE-2 not = 0
                   move " " to MFSQLECM-SQLWARN
               end-if
           end-if
           if MFSQLECM-SQLSTATE-2 = "01"
               go to SQL-ERROR
           end-if
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


THREAD

Specifies the handling of threads with regard to connections.

Syntax:

THREAD={SHARE | ISOLATE}

Parameters:

SHARE
All SQL connections, cursors, etc. in an application are shared by all threads. For example, if you have a hard-coded CONNECT statement and thread 1 executes it and then thread 2 executes it, thread 2 gets an error because the connection is already open.
ISOLATE
ODBC only. All connections, cursors, etc. are local to the thread that creates them. This is required for multi-threaded application server environments such as IIS/ISAPI. .NET applications should use COBOL run units to isolate processing of service requests.

Properties:

Default: SHARE

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


TIME

Specifies an explicit time format to use when time values are returned from database time columns into character output host variables.

When used in addition to DETECTDATE, specifies the explicit time format to recognize in character input host variables.

Syntax:

TIME={ODBC | ISO | USA | EUR | JIS}

Parameters:

ODBC
hh:mm:ss (ISO 8601 default format)
ISO
hh.mm.ss (mainframe default format)
USA
hh:mm{AM | PM}
EUR
hh.mm.ss
JIS
hh:mm:ss

Properties:

Default: ODBC (ISO 8601 default format)

Dependencies:

For input host parameters, requires that the DETECTDATE SQL compiler directive is also set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

TIME can be used with the TIMEDELIM directive to specify an alternative delimiter that separates hour, minute, and second components.

TIME, with or without TIMEDELIM, changes the display format of output host variables as specified.

When you specify both TIME and DETECTDATE, OpenESQL uses TIME (with or without TIMEDELIM) to also recognize time values in your input host variables. See DETECTDATE for more information

The following apply to USA format:
  • Minutes can be omitted. For example, 1 PM is equivalent to 1:00 PM.
  • AM and PM are not case sensitive.
  • There must be a single blank before AM or PM.
  • The hour must not be greater than 12 and cannot be 0 except for the special case of 00:00 AM.
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Related reference
DETECTDATE
DATE
TIMEDELIM
TSTAMPSEP
SET host_variable
SET OPTION
TIME


TIMEDELIM

Specifies a single character as the delimiter between the hour, minute, and second components to override the default delimiter determined by the TIME directive specification, or implicitly based on default ISO 8601 format (hh:mm:ss).

Syntax

TIMEDELIM=character

Properties:

Default: None

Dependencies:

None; however, TIMEDELIM can be used with TIME to specify an alternative delimiter. See TIME for details.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

TIMEDELIM set without TIME overrides the default ISO 8601 delimiter, a colon (:), for time values.

TIMEDELIM set with TIME overrides the default delimiter for the specified TIME parameter. For example, the default delimiter for TIME=EUR is a dot character (.).

See TIME, DETECTDATE, and OpenESQL Datetime Data Types Handling for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Related reference
DETECTDATE
TIME
SET host_variable
SET OPTION
TIME


TRACELEVEL

Produces a statistical analysis of application behavior by tracing certain operations in native applications. The report produced by this directive provides better readability and is inherently more useful than a traditional ODBC trace.

The statistical analysis information is written to a logfile named OpenESQLTrace.processID.log, which is created the first time you use TRACELEVEL. With each subsequent use of TRACELEVEL, tracing information is appended to the end of the file. A separator record is written at the end of each trace to help identify different traces.

OpenESQL creates the logfiles under the directory where the application is located. If file/directory permissions prevent file creation in that location, OpenESQL creates the logfiles under the directory referenced in the %TEMP% environment variable.

All trace records contain the elapsed runtime, accurate to one microsecond.

Syntax:

TRACELEVEL={T | 1 | 2 | 3 | 4 | D}

Scope:

Used at compile time: | No
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

  • When TRACELEVEL=T, the following information is written to the trace file:
    • BEGIN - traces main SQL directives
    • END - indicates end of run
    • DIRECTIVES - traces per compilation unit directives the firs ttime acompilation unit is enountered at run time.
  • When TRACELEVEL=1, the following information is written to the trace file in addition to the information written when you speficy TRACELEVEL=T:
    • PREPARE - identifies the original source code when a statement is prepared.
    • DISPOSE - provides summary information for overall statement usage when a statement is removed from the prepared statement cache at disconnect time
    • FLUSH - provides summary information for overall statement usage when a statement is flushed from the cache usually due to a cache overflow
  • When TRACELEVEL=2, the following information is written to the trace file in addition to the information written when you specify TRACELEVEL=1:
    • OPEN
    • EXECUTE - provides the number of rows selected, inserted, or updated
    • EXEC_IMMED EXECUTE - provides the number of rows selected, inserted, or updated
    • ODBCCLOSE - provides summary information for the current cursor use
    • STMT_CHANGED - reports new concurrency and scroll option settings when the ODBC driver uses different settings than those requested by OpenESQL
  • When TRACELEVEL=3, the following information is written to the trace file in addition to the information written when you specify TRACELEVEL=2:
    • ODBCFETCH - provides the number of rows fetched
    • COBOLFETCH - provides the number of rows returned to the COBOL application
  • When TRACELEVEL= 4, the following information is written to the trace file in addition to the information written when you specify TRACELEVEL=3:
    • EXEC_SQL_BEGIN
    • EXEC_SQL_END
  • When TRACELEVEL=D, a reduced version of TRACELEVEL=4 is produced for debugging purposes. It contains only the following information:
    • BEGIN
    • END
    • EXEC_SQL_BEGIN
    • EXEC_SQL_END
    • DIRECTIVES
Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Multiple user COBOL applications in Java


TRANSACTION

This directive provides OpenESQL with specifications for managing run-time transactions and, in some cases, enabling compile-time checking.

Syntax:

TRANSACTION={GLOBAL | LOCAL | MIXED | AUTO}

Parameters:

GLOBAL Manages transactions via a distributed transaction manager, such as a Java application server, and its external SQL connection.

Checks for the following statements that are not compatible with Java application server applications:

  • BEGIN TRANSACTION
  • COMMIT
  • CONNECT
  • DISCONNECT
  • ROLLBACK
  • SET AUTOCOMMIT
  • SET CONNECT
  • SET TRANSACTION [ISOLATION]

Reports an error for each incompatible statement found.

LOCAL | Manages transactions via a data source and its OpenESQL connection.
MIXED | Manages transactions via a distributed transaction manager (similar to GLOBAL), but does not perform compile-time checking. This allows EXEC SQL CONNECT statements to create local transactions with an OpenESQL connection in addition to the connection provided by the distributed transaction manager.
AUTO

Use this option when you want to AUTOCOMMIT each statement executed on an OpenESQL connection:

  • An application can programmatically control the autocommit setting for a connection by executing the EXEC SQL SET AUTOCOMMIT statement
  • An application in autocommit mode can start a local database transaction with the EXEC SQL BEGIN TRANSACTION statement. The transaction ends when the next COMMIT or ROLLBACK statement is executed
  • When a transaction ends, if the connection's autocommit attribute is on, the connection reverts to autocommit mode; otherwise a new local database transaction is started automatically.

Properties:

Default: TRANSACTION=LOCAL

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Managing Transactions
Scope - OpenESQL SQL Compiler Directive Options
Related reference
AUTOCOMMIT


TSTAMPSEP

Specifies a single character to use as the separator between the date and time parts when datetime values are returned from database datetime columns into character output host variables.

When used in addition to DETECTDATE, specifies the explicit datetime format to recognize in character input host variables.

Syntax

TSTAMPSEP="character"

Parameters:

character
Any single character, including:
- (dash character)

When TSTAMPSEP="-" and DETECTDATE is not specified

Character output host variables are returned in the following format:

yyyy-mm-dd-hh.mm.ss.ffffff

When TSTAMPSEP="-" and DETECTDATE is specified

The dash character instructs OpenESQL to look for a specific set of delimiters, including a dash, a space, and a T. For example if you do not specify any alternative date or time formats, and you set TSTAMPSEP to a dash character (-), OpenESQL recognizes the following formats in your input host variables:

  • yyyy-mm-dd-hh.mm.ss.ffffff
  • yyyy-mm-dd hh.mm.ss.ffffff
  • yyyy-mm-dd hh:mm:ss.ffffff
  • yyyy-mm-ddThh.mm.ss.ffffff
  • yyyy-mm-ddThh:mm:ss.ffffff
Any other character

When DETECTDATE is not also specified:

Character output host variables are returned in the following format:

yyyy-mm-ddChh:mm:ss.ffffff

Where C is any character except a dash (-) character, and the number of fractional seconds is platform dependent.

When DETECTDATE is also specified

Character input host variables are returned and scanned using the following format:

yyyy-mm-ddChh:mm:ss.ffffff

Where C is any character except a dash (-) character, and the number of fractional seconds is platform dependent.

Properties:

Default: Space character (ISO 8601 default)

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

TSTAMPSEP changes the display format of output host variables as specified.

You can use TSTAMPSEP directive to override the delimiter used in the output format to separate date and time components.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
OpenESQL Datetime Data Type Handling
Related reference
Date and Time Data Types
DETECTDATE
TIME
DATE
SET host_variable
SET OPTION
TIMESTAMP


USECURLIB

Controls use of the ODBC's Cursor Library.

The Cursor Library can provide support for scrolling cursors when the underlying driver doesn't, and can also allow "simulated" positioned updates. With USECURLIB=YES, the Cursor Library will always be used. With USERCURLIB=NO, it will never be used. With the default USERCURLIB=IFNEEDED, it will be used if the application tries to do something the driver manager thinks the driver doesn't support. To use a scrolling cursor with the Cursor Library, you must use a STATIC cursor. To do positioned updates using the Cursor Library, you must use OPTCCVAL concurrency.

Note: A "simulated" positioned update might hit more than one row. We recommend including the primary key in the select for this reason.

Syntax:

USECURLIB={NO | YES | IFNEEDED}
NOUSECURLIB

Properties:

Default: USECURLIB=IFNEEDED

Scope:

Used at compile time: | No
Behavior at run time: | Process

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


USER-SQLDA

Eliminates invalid host variable compiler errors for applications that contain an SQLDA rather than including it using the COPY SQLDA statement.

Syntax:

USER-SQLDA={NONE | ANSI | MAINFRAME}

Parameters:

NONE
The application does not contain an SQLDA.
ANSI
The application defines an SQLDA using COMP-5 fields.
MAINFRAME
The application defines an SQLDA using COMP fields. We recommend this option when migrating from the mainframe.

Properties:

Default: USER-SQLDA=NONE

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


WHERECURRENT

Allows PostgreSQL and MySQL to accept updateable SELECT and CURSOR statements when no positioned UPDATEs or DELETEs are required.

Syntax:

[NO]WHERECURRENT

Properties:

Default: WHERECURRENT

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

For PostgreSQL, depending on the table definition, the required pseudo column (oid) on a positioned UPDATE or DELETE might be missing.

For MySQL, depending on the table definition, the required pseudo column (_rowid) on a positioned UPDATE or DELETE might be missing.

If positioned UPDATEs and DELETEs are required, you might need to change your PostgreSQL or MySQL table definition to expose the appropriate pseudo column and make it available.

When positioned UPDATEs and DELETEs are not required, use NOWHERECURRENT.

Parent topic: SQL Compiler Directive Options


XAID

Simplifies working with multiple XARs of the SQL Server or generic one-phase commit for ODBC RM types defined in a single enterprise server region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

XAID=xarid

Parameters:

xarid
The XAR ID set in the enterprise server region XAR definition.

Properties:

Default: None

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

XAID has the same effect as inserting an EXEC SQL SET CONNECTION statement before every EXEC SQL statement in a program.

XAID is mandatory when using more than one XAR defined with the same RM switch module type for use in Web Services applications.

See RM Switch Module Registration for more information.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options


DBMAN Directive Settings

This table shows all of the SQL compiler directive options and the DBMAN preprocessor options with which they are valid.

Directive |  | DBMAN=ODBC | DBMAN=JDBC
ACCESS |  | X |
ALLOWNULLCHAR |  | X | X
ANSI92ENTRY |  | X | X
AUTOCOMMIT |  | X | X
AUTOFETCH |  | X |
BEHAVIOR |  | X | X
 | DEF_CURSOR | X |
 | IC_FH_ISOLATION | X |
 | PF_RO_CURSOR | X |
 | PF_UPD_CURSOR | X | X1
 | RO_CURSOR | X |
 | TRANSACTION | X |
 | UPD_CONCURRENCY | X |
 | UPD_CURSOR | X |
BIND |  | X |
CHECK |  | X | X
CHECKDUPCURSOR |  | X | X
CHECKSINGLETON |  | X | X
CLOSE_ON_COMMIT |  | X | X
CONCAT |  | X | X
CONNECTIONPOOL |  | X |
CTRACE |  | X | X
CURSORCASE |  | X |
DATE |  | X | X
DATEDELIM |  | X | X
DB |  | X | X
DECDEL |  | X |
DESCRIBEDTCHAR |  | X | X
DESCRIBEDTREC |  | X | X
DESCRIBEVARCHAR49 |  | X | X
DESCRIBEVARCHARPICX |  | X | X
DETECTDATE |  | X | X
ESQLVERSION |  | X |
FIPSFLAG |  | X |
GEN-CC2 |  | X |
GEN-CLASS-VAR |  | X |
GEN-HV-FROM-GROUP |  | X | X
GEN-INIT-FLAG |  | X | X
GEN-SQLCA |  | X | X
HSFTRACE |  | X |
IGNORE-NESTED |  | X | X
IGNORESCHEMAERRORS |  | X | X
INIT |  | X | X
ISOLATION |  | X |
JIT |  | X | X
JNDI |  |  | X
JNDIENC |  |  | X
MARS |  | X | X
NIST |  | X | X
NOT |  | X | X
ODBCTRACE |  | X |
ODBCV3 |  | X | X
OPTIMIZECURSORS |  | X | X
OPTION |  | X | X
OPTPER |  | X |
PARAMARRAY |  | X |
PASS |  | X | X
PICXBINDING |  | X | X
PRE |  | X |
PREFETCH |  | X |
QUALFIX |  | X | X
RESULTARRAY |  | X |
SAVE-RETURN-CODE |  | X | X
SPDISPLAY |  | X |
STMTCACHE |  | X | X
TARGETDB |  | X | X
TESTSQLSTATE |  | X |
THREAD |  | X |
TIME |  | X | X
TIMEDELIM |  | X | X
TRACELEVEL |  | X |
TSTAMPSEP |  | X | X
USECURLIB |  | X |
USER-SQLDA |  | X |
XAID |  | X |
1 SQL Server only
Parent topic: OpenESQL
Related reference
ANSI92ENTRY
AUTOCOMMIT
BEHAVIOR
CHECKDUPCURSOR
CHECKSINGLETON
DBMAN
ESQLVERSION
NIST
PF_UPD_CURSOR
TARGETDB
UPD_CONCURRENCY


JDBC Driver Classes

The JVM Managed Runtime requires that you identify a JDBC driver class either as a component of a DataSource object or as a parameter in a connection string.

A driver class is the main class for a JDBC driver. They are driver-specific. See the documentation for your JDBC driver for complete details.

We have tested the following driver classes with the OpenESQL JVM Managed Runtime:
Driver | Driver Class
DB2 | com.ibm.db2.jcc.DB2Driver
Microsoft SQL Server | com.microsoft.sqlserver.jdbc.SQLServerDriver
Oracle | oracle.jdbc.driver.OracleDriver
Parent topic: OpenESQL
Related concepts
JNDI DataSource Objects
Connect Using a JDBC Connection String
Related tasks
To create a JNDI DataSource object


JDBC URLs

The JVM Managed Runtime requires that you identify a JDBC URL either as a component of a DataSource object or as a parameter in a connection string.

A JDBC URL identifies the server and the database. These URLs are driver-specific. See the documentation for your JDBC driver for complete details.

The following are example JDBC URLs:
Database | URL
DB2 | jdbc:db2://localhost:50000/sample
Microsoft SQL Server | jdbc:sqlserver://localhost;database=Northwind;integratedSecurity=true;
Oracle | jdbc:oracle:thin:@localhost:1521/ORCL
Parent topic: OpenESQL
Related concepts
JNDI DataSource Objects
Connect Using a JDBC Connection String
Related tasks
To create a JNDI DataSource object


Sample DataSource Object Files

These sample DataSource object files represent connection properties for three typical data source connections:

DB2 with DB2-Express
File name: DB2.properties
    type=javax.sql.DataSource
    driver=com.ibm.db2.jcc.DB2Driver
    url=jdbc:db2://localhost:50000/sample:retrieveMessagesFromServerOnGetMessage=true;
    user=userName
    password=password
MSSQL with SQL Server Express
File name: MSSQL.properties

For all platforms using SQL Server authentication:

    type=javax.sql.DataSource
    driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
    url=jdbc:sqlserver://remotehost\SQLEXPRESS;database=Northwind;integratedSecurity=true;
    user=userName
    password=password
Oracle
File name: ORA.properties
    type=javax.sql.DataSource
    driver=oracle.jdbc.driver.OracleDriver
    url=jdbc:oracle:thin:@localhost:1521/ORCL
    user=userName
    password=password
Parent topic: OpenESQL
Related concepts
JDBC Resources
Compiling JDBC Applications from the Command Line
JNDI DataSource Objects
Related tasks
To create a JNDI DataSource object


SQL/COBOL Data Type Mappings

The following table shows the mappings used by OpenESQL when converting between ODBC SQL and COBOL data types.

ODBC SQL Type | COBOL Picture | Notes
SQL_CHAR(n)1 | PIC X(n) |
SQL_NCHAR(n)1 | PIC X(n) or PIC N(n) |
SQL_VARCHAR(n)1 | PIC X(n) |
SQL_NVARCHAR(n)1 | PIC X(n) or PIC N(n) |
SQL_LONGVARCHAR1 | PIC X(max) or SQL TYPE LONG-VARCHAR(max) |
SQL_NTEXT1 | PIC X(max) or PIC N(max) |
SQL_DECIMAL(p,s) or SQL_NUMERIC(p,s) | PIC S9(p-s)V9(S) COMP-3 | p = precision (total number of digits). s = scale (number of digits after the decimal point). OpenESQL doesn’t support using unsigned packed decimal host variables.
SQL_SMALLINT | PIC S9(4) COMP-5 |
SQL_INTEGER | PIC S9(9) COMP-5 |
SQL_REAL | COMP-1 |
SQL_FLOAT | COMP-2 |
SQL_DOUBLE | COMP-2 |
SQL_BIT | PIC S9(4) COMP-5 |
SQL_TINYINT | PIC S9(4) COMP-5 |
SQL_BIGINT | PIC S9(18) COMP-3 |
SQL_BINARY(n) | PIC X(n) or SQL TYPE BINARY(n) |
SQL_VARBINARY(n) | PIC X(n) ) or SQL TYPE VARBINARY(n) |
SQL_LONVARBINARY | PIC X(max) or SQL TYPE LONG-VARBINARY(max) |
SQL_DATE or SQL_TYPE_DATE | PIC X(10) ) or SQL TYPE DATE | yyyy-mm-dd
SQL_TIME or SQL_TYPE_TIME or SQL_SS_TIME2 | PIC X(8) or SQL TYPE TIME or SQL TYPE TIME-RECORD | hh:mm:ss
SQL_TIMESTAMP or SQL_TYPE_TIMESTAMP | PIC X(29) or SQL TYPE TIMESTAMP or SQL TYPE TIMESTAMP-RECORD | yyyy-mm-ddhh:mm:ss.ffffff
SQL_SS_TIMESTAMPOFFSET | PIC X(34) | yyyy-mm-ddhh:mm:ss.ffffff +/-hh:mm
1For more information on using host variables with international data, particularly PIC N and PIC G host variables, see OpenESQL Globalization Best Practices.
Parent topic: OpenESQL
Related concepts
OpenESQL Globalization Best Practices
COBOL to SQL Data Type Mapping


OpenESQL Messages

  • SQLSTATE Values
  • SQLCODE Values
  • OpenESQL Preprocessor Error Messages
Parent topic: OpenESQL


SQLSTATE Values

OpenESQL statements return SQLSTATE values as defined by the X/Open and SQL Access Group SQL CAE specification (1992). SQLSTATE is a five character field that can be declared independently by an application, but which is also present in SQLCA, if declared. The table below lists SQLSTATE values that can be returned by OpenESQL statements.

The value returned in SQLSTATE consists of a two character class value followed by a three character subclass value. A class value of "01" indicates a warning and is accompanied by a SQLCODE of 1. Class values other than "01", except for the class "IM", indicate an error and are accompanied by a SQLCODE of -10000. The class "IM" is specific to warnings and errors that derive from the implementation of ODBC itself. The subclass value "000" in any class is for implementation defined conditions within the given class. The assignment of class and subclass values is defined by ANSI SQL-92.

Note:

Although successful execution of a function is normally indicated by a SQLCODE of 0, the SQLSTATE 00000 also indicates success.

SQLSTATE | Error
01000 | General warning
01002 | Disconnect error
01004 | Data truncated
01006 | Privilege not revoked
01S00 | Invalid connection string attribute
01S01 | Error in row
01S02 | Option value changed
01S03 | No rows updated or deleted
01S04 | More than one row updated or deleted
01S05 | Cancel treated as SQLFreeStmt with the SQL_CLOSE option
01S06 | Attempt to fetch before the result set returned the first rowset
07001 | Wrong number of parameters
07006 | Restricted data type attribute violation
07S01 | Invalid use of default parameter
08001 | Unable to connect to data source
08002 | Connection in use
08003 | Connection not open
08004 | Data source rejected establishment of connection
08007 | Connection failure during transaction
08S01 | Communication link failure
21S01 | Insert value list does not match column list
21S02 | Degree of derived table does not match column list
22001 | String data right truncation
22002 | Indicator variable required but not supplied
22003 | Numeric value out of range
22005 | Error in assignment
22008 | Datetime field overflow
22012 | Division by zero
22026 | String data, length mismatch
23000 | Integrity constraint violation
24000 | Invalid cursor state
25000 | Invalid transaction state
28000 | Invalid authorization specification
34000 | Invalid cursor name
37000 | Syntax error or access violation
3C000 | Duplicate cursor name
42000 | Syntax error or access violation
70100 | Operation aborted
IM001 | Driver does not support this function
IM002 | Data source name not found and no default driver specified
IM003 | Specified driver could not be loaded
IM004 | Driver's SQLAllocEnv failed
IM005 | Driver's SQLAllocConnect failed
IM006 | Driver's SQLSetConnect-Option failed
IM007 | No data source or driver specified; dialog prohibited
IM008 | Dialog failed
IM009 | Unable to load translation .dll file
IM010 | Data source name too long
IM011 | Driver name too long
IM012 | DRIVER keyword syntax error
IM013 | Trace file error
S0001 | Base table or view already exists
S0002 | Base table not found
S0011 | Index already exists
S0012 | Index not found
S0021 | Column already exists
S0022 | Column not found
S0023 | No default for column
S1000 | General error
S1001 | Memory allocation failure
S1002 | Invalid column number
S1003 | Program type out of range
S1004 | SQL data type out of range
S1008 | Operation canceled
S1009 | Invalid argument value
S1010 | Function sequence error
S1011 | Operation invalid at this time
S1012 | Invalid transaction operation code specified
S1015 | No cursor name available
S1090 | Invalid string or buffer length
S1091 | Descriptor type out of range
S1092 | Option type out of range
S1093 | Invalid parameter number
S1095 | Function type out of range
S1096 | Information type out of range
S1097 | Column type out of range
S1098 | Scope type out of range
S1099 | Nullable type out of range
S1100 | Uniqueness option type out of range
S1101 | Accuracy option type out of range
S1103 | Direction option out of range
S1105 | Invalid parameter type
S1106 | Fetch type out of range
S1107 | Row value out of range
S1108 | Concurrency option out of range
S1109 | Invalid cursor position
S1110 | Invalid driver completion
S1111 | Invalid bookmark value
S1C00 | Driver not capable
S1T00 | Timeout expired
Parent topic: OpenESQL Messages
Related concepts
The SQLSTATE Variable
Related reference
CHECKSINGLETON


SQLCODE Values

The possible values for SQLCODE are:

Value |  | Meaning
0 |  | The statement ran without error.
1 |  | The statement ran, but a warning was generated. The values of the SQLWARN flags should be checked to determine the type of error. See The SQLCA Data Structure for more information on SQLWARN flags.
< 0 (negative) | Varies | The statement did not run due to an application, database, system, or network error.
-1 | Autoconnect failure | SQL(INIT) was used, and automatic CONNECT failed. Programs which use SQL(INIT) need to check SQLCODE immediately on startup.
100 |  | Data matching the query was not found or the end of the results set has been reached. No rows were processed.
-10000 | <The first error message returned by the ODBC call SQLError after the OpenESQL run-time module detected an error> or | See your ODBC driver documentation, or other ODBC reference documents for details of ODBC error messages. SQLSTATE will contain a unique code for each ODBC error condition.
 | Unable to retrieve ODBC error | An ODBC error occurred, but no more details are available. This usually indicates a serious run-time condition, such as severe memory shortage.
-19085 | Invalid ODBC catalog query | This is caused by invalid parameters to a QUERY ODBC statement.
-19101 | Statement too long |
-19199 | ESQL Keyword(s) detected in PREPARE/EXECUTE IMMEDIATE statement |
-19313 | Too few host variables |
-19413 | Data overflow occurred during decimal data conversion |
-19501 | No cursor declared |
-19514 | Cursor is not prepared |
-19701 | NULL connection name or Connection name not found | These two errors (-19701 and -19702) occur when a program refers to a connection which does not exist. The most likely cause is attempting to execute an Embedded SQL statement before a CONNECT has executed successfully, or after all connections have been disconnected.
-19702 | Connection name not found or Attempt to close non-existent connection
-19703 | Could not make connection |
-19707 | Duplicate connection name |
-19708 | OpenESQL failed to get details of the connection | This can happen when OpenESQL makes a request to Enterprise Server .NET to get a database XA Resource (XAR), but Enterprise Server .NET fails to return one. The most likely cause is that the XAR has not been defined. See To Define an XA Resource (XAR) for an Enterprise Server Region for more information.
-19822 | Improperly initialized User SQLDA |
-19957 | Statement text not found or empty |
-20000 | Unimplemented embedded SQL feature | The COBOL compiler may accept some Embedded SQL syntax which is not yet supported by the OpenESQL run-time module. If an attempt is made to execute such a statement, this condition is the result.
OpenESQL directives ANSI92ENTRY, CHECKDUPCURSOR, and CHECKSINGLETON can affect how the SQLCODE and SQLSTATE variables and the SQLWARN flag are set. Please review each directive for additional detail.
Parent topic: OpenESQL Messages
Related concepts
The SQLSTATE Variable
SQLWARN Flags
The SQLCODE Variable
Related tasks
To Define an XA Resource (XAR) for an Enterprise Server Region
Related reference
CHECKSINGLETON
ANSI92ENTRY
CHECKDUPCURSOR


OpenESQL Preprocessor Error Messages

  • COBES0002 token is badly defined.
    An error exists in the definition of the SQLCA area, SQLCODE field, or SQLSTATE field.
  • COBES0003 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.
  • COBES0004 Nested or multi-source programs not allowed.
    You are trying to compile a program that is nested or multi-source. This is not supported.
  • COBES0005 An error occurred when 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.
  • COBES0006 No DB engine could be found.
    The required OpenESQL system software was not installed.
  • COBES0007 Source file name is invalid.
    A system error has occurred. The source file name passed to the preprocessor is not valid.
  • COBES0010 OESQL rejected an unspecified option.
    OESQL precompiler services returned a -4905 sql error on initialization.
  • COBES0022 The directive SQL(DBMAN=ODBC) is not supported under Personal Edition.
    You are using Visual COBOL Personal Edition. This Edition does not support ODBC.
  • COBES0023 The SQL(DBMAN) directive option is not supported with native applications.
    You have specified the SQL(DBMAN) compiler directive option to compile a native application. This is not supported.
  • COBES0024 The SQL(DBMAN) directive option is not supported with JDBC applications.
    You have specified the SQL(DBMAN) compiler directive option to compile a JDBC application. This is not supported.
  • COBES0100 SQL incompatible with MAINFRAME
    The preprocessor has encountered an embedded SQL statement that is not supported when the BEHAVIOR SQL compiler directive option is set to MAINFRAME.
  • COBES0101 Statement is too long.
    The SQL statement passed to the preprocessor is more than 65536 characters long. The preprocessor gets passed a compressed version of the SQL statement rather than the original source, which might have comments included as well as leading and trailing blanks.
  • COBES0102 Statement contains too many host variables.
    The SQL statement contains more than 8000 host and indicator variables.
  • COBES0103 token does not have a suitable definition to be used as a host variable.
    The host variable displayed in error message is not recognized with a data definition suitable for SQL data types.
  • COBES0104 Bad SQL data declaration.
    An unexpected SQL declaration was passed to the preprocessor.
  • COBES0105 Syntax error.
    The SQL statement includes invalid syntax or does not include required information.
  • COBES0106 Filename too long.
    A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.
  • COBES0107 File token not found.
    The copybook specified in token was not found.
  • COBES0108 token is not unique and should be qualified.
    The host variable displayed in token is not unique.
  • COBES0109 token is not a data item.
    The host variable displayed in token was not defined or was defined incorrectly.
  • COBES0110 Statement contains more than one SQLDA.
    More than one SQLDA has been used in the SQL statement.
  • COBES0111 token is not a table of null indicator variables.
    The preprocessor expects that the token displayed is either a null indicator or a null indicator table.
  • COBES0112 variable should not be defined with an OCCURS clause.
    A host variable is defined as an array using an OCCURS clause.
  • COBES0113 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.
  • COBES0114 Statement only allowed in the Procedure Division.
    An SQL statement such as EXEC SQL SELECT was coded in the Working-Storage Section.
  • COBES0115 Statement not allowed in the Procedure Division.
    A SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Division
  • COBES0116 An error occurred when processing the trace file.
    A file error occurred while trying to write information to the preprocessor trace file.
  • COBES0118 Mismatched DECLARE.
    More than one DECLARE statement was found within an EXEC SQL statement.
  • COBES0119 Host variable name is too long.
    The host variable name is too long. The maximum length of the host variable is 30 characters.
  • COBES0120 Internal error - dictionary handle is too big.
    The preprocessor creates an internal dictionary of all host variables used in a program. When building the dictionary, a system error occurred.
  • COB ES0121 Compiler directive SQL (token1=token2) is invalid or badly sequenced - all SQL statements ignored.
    The command line used to compile the application or program either contains an invalid value for a valid SQL compiler directive option (represented by token2), or the SQL compiler directive option appears in the wrong place.
  • COBES0123 Invalid ILTARGET - cannot use ILTARGET(ANYCPU) - must specify ILTARGET(X86) or ILTARGET(X64).
    You have specified the ILTARGET(ANYCPU) compiler directive to compile an ODBC application as .NET managed code.
  • COBES0124 Host or Indicator Variable varname should not be defined in EXEC SQL statement using a subscript.
    In an EXEC SQL statement, you have defined the specified host or an indicator variable using a subscript.
  • COBES0125 variable should be defined with an OCCURS clause.
    If an array is used in an SQL statement, the OpenESQL preprocessor checks to ensure that all variables in the statement use arrays of the same size. This message is generated when a variable used in this scenario has not been defined as an array, i.e., using an OCCURS clause.
  • COBES0130 Host variable host-var.group-var is part of a group variable expansion that is not supported in this type of SQL statement.
    The EXEC SQL statement in which the host variable is included does not support group variable expansion.
  • COBES0201 BEHAVIOR directive not valid unless TARGETDB directive of DB2, ORACLE, or MSSQLSERVER set first.
    You have set the SQL(BEHAVIOR) compiler directive option, but neglected to also set the SQL(TARGETDB) directive to a value of DB2, ORACLE, or MSSQLSERVER. SQL(BEHAVIOR) is dependent on SQL(TARGETDB).
  • COBES0202 BEHAVIOR directive not set.
    You have neglected to set the SQL(BEHAVIOR) compiler directive option, which is required to compile OpenESQL applications.
  • COBES0203 PREFETCH and BEHAVIOR directives are mutually exclusive - cannot set both.
    You have set both the SQL(PREFETCH) and SQL(BEHAVIOR) compiler directive options to compile an application. These are mutually exclusive.
  • COBES0205 Cannot set directive PF_RO_CURSOR > 1 if RO_CURSOR directive is set to IC_FH.
    When compiling an application, you have set the PF_RO_CURSOR primitive directive to a value greater than 1 and also set the RO_CURSOR primitive directive to IC_FH. This combination is not supported.
  • COBES0206 Cannot set directive PF_RO_CURSOR > 1 if RO_CURSOR directive is set to FORWARD and TARGETDB is MSSQLSERVER.
    When compiling an application, you have set the PF_RO_CURSOR primitive directive to a value greater than 1, set the RO_CURSOR primitive directive to FORWARD, and set the TARGETDB SQL compiler directive option to MSSQLSERVER. This combination is not supported.
  • COBES0207 Cannot set directive PF_UPD_CURSOR > 1 if UPD_CURSOR directive is set to FORWARD.
    When compiling an application, you have set the PF_UPD_CURSOR primitive directive to a value greater than 1 and also set the UPD_CURSOR primitive directive to FORWARD. This combination is not supported.
  • COBES0208 Cannot set UPD_CURSOR directive to DYNAMIC if TARGETDB directive is set to ORACLE.
    When compiling an application, you have set the UPD_CURSOR primitive directive to DYNAMIC, and also set the TARGETDB SQL compiler directive option to ORACLE. This combination is not supported.
  • COBES0209 Cannot set UPD_CURSOR directive to STATIC if TARGETDB directive is set to MSSQLSERVER.
    When compiling an application, you have set the UPD_CURSOR primitive directive to STATIC, and also set the TARGETDB SQL compiler directive option to MSSQLSERVER. This combination is not supported.
  • COBES0222 Invalid Framework target - SQL applications must be built to target the 4.0 .NET Framework.
    When compiling an SQL application, you have specified the ILCLR compiler directive value as 2. SQL applications require that the SQL(ILCLR) compiler directive option be set to 4 to target .NET Framework version 4.0.
  • COBES0223 TARGETDB directive not set.
    When compiling an SQL application, you have either neglected to set the SQL(TARGETDB) compiler directive option, or you have set it after the BEHAVIOR, ACCESS, BIND, or MARS compiler directive options.
  • COBES0900 An internal error occurred.
    An unexpected error occurred in the preprocessor.
  • COBES0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.
    A severe SQL error has occurred. Additional EXEC SQL statements will not be processed by the preprocessor.
  • COBES1000W Use of EXEC SQL INCLUDE SQLCA END-EXEC
    FIPS certification (reference X/OPEN CAE SQL 8.1.1) requires that this warning be generated.
  • COBES1002 Statement is not in area B.
    An EXEC SQL statement starts before column 12.
  • COBES1004 token directive is not supported and has been ignored.
    The compiler directive token is not supported when compiling SQL applications.
Parent topic: OpenESQL Messages
Related information
Data Related


COBES0002 token is badly defined.

An error exists in the definition of the SQLCA area, SQLCODE field, or SQLSTATE field.

One of the following occurred:

  • The SQLCA area is defined with total length less than 136 characters.
  • The SQLCODE field is not defined as a S9(8) COMP-5 field.
  • The SQLSTATE field is not defined as a character field of length 5.
  • One of the previous fields is defined incorrectly.

Resolution:

Correct the definition or use the SQLCA copybook provided. If the problem persists, report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


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

Resolution:

Remove the duplicate definitions and recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0004 Nested or multi-source programs not allowed.

You are trying to compile a program that is nested or multi-source. This is not supported.

Resolution:

Move the subroutines to a separate program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0005 An error occurred when 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.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0006 No DB engine could be found.

The required OpenESQL system software was not installed.

Resolution:

Install the required OpenESQL software.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0007 Source file name is invalid.

A system error has occurred. The source file name passed to the preprocessor is not valid.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0010 OESQL rejected an unspecified option.

OESQL precompiler services returned a -4905 sql error on initialization.

Resolution:

Check to make sure your ODBC drivers are installed properly and that all required system files are available via the PATH environment variable. If the problem persists, report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0022 The directive SQL(DBMAN=ODBC) is not supported under Personal Edition.

You are using Visual COBOL Personal Edition. This Edition does not support ODBC.

Resolution:

Either upgrade to Visual COBOL, or remove the SQL(DBMAN=ODBC) directive; then recompile the application.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0023 The SQL(DBMAN) directive option is not supported with native applications.

You have specified the SQL(DBMAN) compiler directive option to compile a native application. This is not supported.

Resolution:

Recompile the application without the SQL(DBMAN) directive.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0024 The SQL(DBMAN) directive option is not supported with JDBC applications.

You have specified the SQL(DBMAN) compiler directive option to compile a JDBC application. This is not supported.

Resolution:

Recompile the application without the SQL(DBMAN) directive.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0100 SQL incompatible with MAINFRAME

The preprocessor has encountered an embedded SQL statement that is not supported when the BEHAVIOR SQL compiler directive option is set to MAINFRAME.

Resolution:

Correct the EXEC SQL statement; then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages
Related reference
BEHAVIOR


COBES0101 Statement is too long.

The SQL statement passed to the preprocessor is more than 65536 characters long. The preprocessor gets passed a compressed version of the SQL statement rather than the original source, which might have comments included as well as leading and trailing blanks.

Resolution:

Look at breaking the SQL statement into multiple SQL statements and then try recompiling the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0102 Statement contains too many host variables.

The SQL statement contains more than 8000 host and indicator variables.

Resolution:

Look at breaking the SQL statement into multiple SQL statements and then try recompiling the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0103 token does not have a suitable definition to be used as a host variable.

The host variable displayed in error message is not recognized with a data definition suitable for SQL data types.

Resolution:

Review the SQL Data Types documentation to determine valid data definitions for host variables.

If your code contains a multiple-level group name in a FETCH or singleton SELECT, recompile using the GEN-HV-FROM-GROUP SQL compiler directive option.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
SQL Data Types
Related reference
GEN-HV-FROM-GROUP
SQL Data Types


COBES0104 Bad SQL data declaration.

An unexpected SQL declaration was passed to the preprocessor.

Generally this error occurs only when the host variable is defined as:

 host-variable-name SQL TYPE IS ....

and the preprocessor has not been set up to handle that definition.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


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

Resolution:

Correct the SQL statement and recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0106 Filename too long.

A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.

Resolution:

Correct the filename and recompile the program

Parent topic: OpenESQL Preprocessor Error Messages


COBES0107 File token not found.

The copybook specified in token was not found.

Resolution:

The preprocessor looks first in the current directory, and then down the paths specified by environment variable COBCPY. Either correct the filename or set the environment variable COBCPY to include the full path to your copybook. You should also check your COPYEXT setting in case your copybook files have a file extension other than .cbl or .cpy.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0108 token is not unique and should be qualified.

The host variable displayed in token is not unique.

Resolution:

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 the following if you wanted the host variable from the ORDERS copybook to be used in the query:

:ORDERS.ORD-NO
Parent topic: OpenESQL Preprocessor Error Messages


COBES0109 token is not a data item.

The host variable displayed in token was not defined or was defined incorrectly.

Resolution:

Verify that the host variable exists. If it does not, make the required changes to correct the error. Variables defined in COBOL copybooks are also valid for host variables, unlike mainframe DB2.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0110 Statement contains more than one SQLDA.

More than one SQLDA has been used in the SQL statement.

Resolution:

The preprocessor has a limit of only one SQLDA definition per program. If the problem persists, report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0111 token is not a table of null indicator variables.

The preprocessor expects that the token displayed is either a null indicator or a null indicator table.

Resolution:

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 would specify staff-null-ind rather than staff-null-tbl in your query.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0112 variable should not be defined with an OCCURS clause.

A host variable is defined as an array using an OCCURS clause.

Resolution:

The preprocessor does not allow host variables to be defined this way. Edit your program to remove the OCCURS clause and then recompile.

Important: This error can sometimes be generated incorrectly when an indicator variable array is specified with a non-array host variable. If this happens, instead of removing the OCCURS clause, recompile using the SQL(NOARRAYCHECK) directive to prevent the error from being generated.
Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Host Variables
Related reference
ARRAYCHECK


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

Resolution:

The preprocessor does not allow host variables to be defined this way.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Host Variables


COBES0114 Statement only allowed in the Procedure Division.

An SQL statement such as EXEC SQL SELECT was coded in the Working-Storage Section.

Resolution:

This statement is not supported when coded in the Working-Storage Section. Move the statement to the Procedure Division and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0115 Statement not allowed in the Procedure Division.

A SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Division

Resolution:

This statement is not supported when coded in the Procedure Division. Move it into Working-Storage Section and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0116 An error occurred when processing the trace file.

A file error occurred while trying to write information to the preprocessor trace file.

Resolution:

Be sure you have WRITE permission on the drive and directory where the trace file is written, and be sure you have enough space left on the drive to save the file.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0118 Mismatched DECLARE.

More than one DECLARE statement was found within an EXEC SQL statement.

Resolution:

Correct the statement and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages
Related reference
DECLARE CURSOR
DECLARE DATABASE


COBES0119 Host variable name is too long.

The host variable name is too long. The maximum length of the host variable is 30 characters.

Resolution:

Make sure the host variable is a valid COBOL name. It should be 30 characters or less in length.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Host Variables


COBES0120 Internal error - dictionary handle is too big.

The preprocessor creates an internal dictionary of all host variables used in a program. When building the dictionary, a system error occurred.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

We also suggest that you be prepared to provide your SupportLine representative with enough information (e.g., program source, etc.) to recreate the error.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COB ES0121 Compiler directive SQL (token1=token2) is invalid or badly sequenced - all SQL statements ignored.

The command line used to compile the application or program either contains an invalid value for a valid SQL compiler directive option (represented by token2), or the SQL compiler directive option appears in the wrong place.

For example, you must specify TARGETDB on the command line before specifying BEHAVIOR.

Resolution:

Correct the command line and recompile.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0123 Invalid ILTARGET - cannot use ILTARGET(ANYCPU) - must specify ILTARGET(X86) or ILTARGET(X64).

You have specified the ILTARGET(ANYCPU) compiler directive to compile an ODBC application as .NET managed code.

Resolution:

Recompile the application specifying either ILTARGET(X86) or ILTARGET(X64).

Parent topic: OpenESQL Preprocessor Error Messages
Related reference
ILTARGET


COBES0124 Host or Indicator Variable varname should not be defined in EXEC SQL statement using a subscript.

In an EXEC SQL statement, you have defined the specified host or an indicator variable using a subscript.

Resolution:

Redefine the host or indicator variable without using a subscript and recompile.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0125 variable should be defined with an OCCURS clause.

If an array is used in an SQL statement, the OpenESQL preprocessor checks to ensure that all variables in the statement use arrays of the same size. This message is generated when a variable used in this scenario has not been defined as an array, i.e., using an OCCURS clause.

Resolution:

Redefine the variable using an OCCURS clause.

Important: This error can sometimes be generated incorrectly when an indicator variable array is specified with a non-array host variable. If this happens, instead of redefining the variable, recompile using the SQL(NOARRAYCHECK) directive to prevent the error from being generated
Parent topic: OpenESQL Preprocessor Error Messages
Related reference
ARRAYCHECK


COBES0130 Host variable host-var.group-var is part of a group variable expansion that is not supported in this type of SQL statement.

The EXEC SQL statement in which the host variable is included does not support group variable expansion.

Resolution:

Scenario 1: Group variable is valid
In the case where the group variable is valid, compile with SQL(GEN-HV-FROM-GROUP). For example, the following statement includes a valid group variable:
EXEC SQL Select a into :HV1 where col_a IN (:group-var)
Scenario 2: Group variable is invalid
Redefine the group variable as an elementary host variable. For example:
01 GROUP-VAR.
     05 ELEM-VAR1 PIC X.
     05 ELEM-VAR2 PIC X.
01 ELGROUP-VAR PIC X(2) redefines GROUP-VAR.

Then code the EXEC SQL statement to use the elementary definition. For the above example, use this:

EXEC SQL Select a into :HV1 where col_a = :elgroup-var

Instead of this:

EXEC SQL Select a into :HV1 where col_a = :group-var
Parent topic: OpenESQL Preprocessor Error Messages


COBES0201 BEHAVIOR directive not valid unless TARGETDB directive of DB2, ORACLE, or MSSQLSERVER set first.

You have set the SQL(BEHAVIOR) compiler directive option, but neglected to also set the SQL(TARGETDB) directive to a value of DB2, ORACLE, or MSSQLSERVER. SQL(BEHAVIOR) is dependent on SQL(TARGETDB).

Resolution:

Set the SQL(TARGETDB) compiler directive option to DB2, ORACLE, or MSSQLSERVER in addition to specifying the SQL(BEHAVIOR) directive option; then recompile the application.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0202 BEHAVIOR directive not set.

You have neglected to set the SQL(BEHAVIOR) compiler directive option, which is required to compile OpenESQL applications.

Resolution:

Recompile the application using the SQL(BEHAVIOR) and SQL(TARGETDB) compiler directive options.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0203 PREFETCH and BEHAVIOR directives are mutually exclusive - cannot set both.

You have set both the SQL(PREFETCH) and SQL(BEHAVIOR) compiler directive options to compile an application. These are mutually exclusive.

Resolution:

Recompile your application specifying either the SQL(BEHAVIOR) or SQL(PREFETCH) compiler directive option, but not both.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0205 Cannot set directive PF_RO_CURSOR > 1 if RO_CURSOR directive is set to IC_FH.

When compiling an application, you have set the PF_RO_CURSOR primitive directive to a value greater than 1 and also set the RO_CURSOR primitive directive to IC_FH. This combination is not supported.

Resolution:

Recompile your application using a supported combination of primitive directives and values. See the topic Primitive Directives for more information.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0206 Cannot set directive PF_RO_CURSOR > 1 if RO_CURSOR directive is set to FORWARD and TARGETDB is MSSQLSERVER.

When compiling an application, you have set the PF_RO_CURSOR primitive directive to a value greater than 1, set the RO_CURSOR primitive directive to FORWARD, and set the TARGETDB SQL compiler directive option to MSSQLSERVER. This combination is not supported.

Resolution:

Recompile your application using a supported combination of primitive directives and values, and SQL(TARGETDB) compiler directive option value. See the topics Primitive Directives and TARGETDB for more information.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0207 Cannot set directive PF_UPD_CURSOR > 1 if UPD_CURSOR directive is set to FORWARD.

When compiling an application, you have set the PF_UPD_CURSOR primitive directive to a value greater than 1 and also set the UPD_CURSOR primitive directive to FORWARD. This combination is not supported.

Resolution:

Recompile your application using a supported combination of primitive directives and values. See the topic Primitive Directives for more information.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0208 Cannot set UPD_CURSOR directive to DYNAMIC if TARGETDB directive is set to ORACLE.

When compiling an application, you have set the UPD_CURSOR primitive directive to DYNAMIC, and also set the TARGETDB SQL compiler directive option to ORACLE. This combination is not supported.

Resolution:

Recompile your application, specifying a supported combination of primitive directives and SQL compiler directive options. See the topics Primitive Directives and TARGETDB for more information.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0209 Cannot set UPD_CURSOR directive to STATIC if TARGETDB directive is set to MSSQLSERVER.

When compiling an application, you have set the UPD_CURSOR primitive directive to STATIC, and also set the TARGETDB SQL compiler directive option to MSSQLSERVER. This combination is not supported.

Resolution:

Recompile your application, specifying a supported combination of primitive directives and SQL compiler directive options. See the topics Primitive Directives and TARGETDB for more information.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0222 Invalid Framework target - SQL applications must be built to target the 4.0 .NET Framework.

When compiling an SQL application, you have specified the ILCLR compiler directive value as 2. SQL applications require that the SQL(ILCLR) compiler directive option be set to 4 to target .NET Framework version 4.0.

Resolution:

Recompile the application, setting the ILCLR directive to 4.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0223 TARGETDB directive not set.

When compiling an SQL application, you have either neglected to set the SQL(TARGETDB) compiler directive option, or you have set it after the BEHAVIOR, ACCESS, BIND, or MARS compiler directive options.

Resolution:

Recompile the application, specifying the TARGETDB SQL compiler directive option before the BEHAVIOR, ACCESS, BIND, or MARS compiler directive options.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0900 An internal error occurred.

An unexpected error occurred in the preprocessor.

Resolution:

Create a trace file using the CHKECM(TRACE) compiler directive, and contact SupportLine. See Creating Debug Files for additional details on how to create a trace file.

Parent topic: OpenESQL Preprocessor Error Messages
Related concepts
Creating Debug Files


COBES0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.

A severe SQL error has occurred. Additional EXEC SQL statements will not be processed by the preprocessor.

Resolution:

Correct the severe error and then recompile the program.

Parent topic: OpenESQL Preprocessor Error Messages


COBES1000W Use of EXEC SQL INCLUDE SQLCA END-EXEC

FIPS certification (reference X/OPEN CAE SQL 8.1.1) requires that this warning be generated.

FIPS certification (reference X/OPEN CAE SQL 8.1.1) requires that a warning is generated if this syntax is supported:

   EXEC SQL
      INCLUDE SQLCA
   END-EXEC

Resolution:

No action is required.

Parent topic: OpenESQL Preprocessor Error Messages


COBES1002 Statement is not in area B.

An EXEC SQL statement starts before column 12.

Resolution:

Move the EXEC SQL statement so that it starts after column 12.

Parent topic: OpenESQL Preprocessor Error Messages


COBES1004 token directive is not supported and has been ignored.

The compiler directive token is not supported when compiling SQL applications.

Resolution:

Recompile the application, omitting the offending compiler directive.

Parent topic: OpenESQL Preprocessor Error Messages


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


esqlconfig command

Runs the command-line implementation of the OpenESQL Configuration utility, enabling you to set a default behavior for the SQL(BEHAVIOR) compiler directive option.

Syntax:

esqlconfig {-P[erformance] | -A[NSI] | -C[ompatibility] | -W[arning]
| -E[rror] | -D[isplay] | -H[elp]}

Parameters:

P[erformance] | Sets the default to Optimize for performance and mainframe compatibility, and displays the old and new settings
A[NSI] | Sets the default to ANSI compliance, and displays the old and new settings
C[ompatibility] | Sets the default to No change in default behavior and no optimization, and displays the old and new settings
W[arning] | Sets the default to Issue a warning at compile time, and displays the old and new settings
E[rror] | Sets the default to Issue an error at compile time, and displays the old and new settings
D[isplay] | Displays the current default setting
H[elp] | Displays the current default setting, and displays the syntax for the esqlconfig command

Comments:

If you enter no parameters or an invalid parameter, esqlconfig displays the current default setting and appropriate syntax as if you had specified the -H parameter.

Parent topic: OpenESQL
Related reference
BEHAVIOR


DB2

  • DB2 Compiler Directive Options
  • DB2 Environment Variables
  • DB2 ECM Error Messages
Parent topic: Reference


DB2 Compiler Directive Options

  • ACCESS
    Specifies the name of the package to be created and stored in the database.
  • ACTION
    Indicates whether the package can be added or replaced.
  • ALEBRA
    When CHARSET(EBCDIC) is also specified, suppresses generation of ASCII/EBCDIC data translation in host variables used in SQL statements.
  • APREUSE
    Specifies whether or not to reuse static SQL access plans.
  • BIND
    Instructs the DB2 ECM to create a DBRM file to use for manual binding. Also optionally used to specify an alternative filename for and/or path to the created DBRM file.
  • BINDDIR
    Specifies an alternative directory in which to write the DBRM file created during compilation.
  • BGP
    Specifies the type of background syntax checking to be done by the DB2 ECM preprocessor when a program is being edited in Visual COBOL.
  • BLOCK
    Specifies the record blocking mode to be used on package creation. For information about row blocking, see the IBM DB2 Administration Guide or the Application Programming Guide.
  • CALL_RESOLUTION
    Specifies how a CALL statement will be resolved.
  • CASE
    Specifies the case of the package name.
  • CCSIDG
    An integer specifying the coded character set identifier (CCSID) to be used for double byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • CCSIDM
    An integer specifying the coded character set identifier (CCSID) to be used for mixed byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • CCSIDS
    An integer specifying the coded character set identifier (CCSID) to be used for single byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • CHARSUB
    Designates the default character sub-type that is to be used for column definitions in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2.
  • COLLECTION
    Specifies a 30-character collection identifier for the package. If this is not specified, the authorization identifier for the user processing the package is used.
  • COMMIT
    Specifies where implicit COMMIT statements should be generated.
  • CONCAT
    Specifies the ASCII character code to use for the CONCAT symbol (|).
  • CONCURRENTACCESSRESOLUTION
    Specifies the concurrent access resolution to use for statements in the package.
  • CONNECT
    Specifies that a CONNECT statement is to be processed as either a type 1 CONNECT or a type 2 CONNECT.
  • COPY
    Enables the use SQL host variables in COBOL copybooks.
  • CTRACE
    Creates a trace file for submission to Technical Support if requested. The filename of the file that is created is sqltrace.txt.
  • DB
    Specifies the name of the database that the program accesses. If DB is specified without a parameter, the database specified in the environment variable DB2DBDFT is used.
  • DBPROTOCOL
    Specifies what protocol to use when connecting to a remote site that is identified by a three-part name statement.
  • DEC
    Specifies the maximum precision to be used in decimal arithmetic operations. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • DECDEL
    Designates whether a period (.) or a comma (,) will be used as the decimal point indicator in decimal and floating point literals. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • DEFERRED_PREPARE
    Provides a performance enhancement when accessing DB2 common server databases or DRDA databases. This option combines the SQL PREPARE statement flow with the associated OPEN, DESCRIBE, or EXECUTE statement flow to minimize inter-process or network flow.
  • DEGREE
    Specifies whether or not the query is to be executed using I/O parallel processing.
  • DISCONNECT
  • DYNAMICRULES
    Specifies which authorization identifier to use when dynamic SQL in a package is executed.
  • ENCODING
    Specifies the encoding for all host variables in static statements in the plan or package.
  • EXPLAIN
    Stores information in the Explain tables about the access plans chosen for each SQL statement in the package. DRDA does not support the ALL value for this option.
  • EXPLSNAP
    Stores Explain Snapshot information in the Explain tables. This DB2 precompile/bind option is not supported by DRDA.
  • EXTENDEDINDICATOR
    Enables the recognition of extended indicator variable values during the execution of the associated plan or package.
  • FEDERATED
    Specifies whether a static SQL statement references a nickname or a federated view. SQL errors are returned if the package does not refer to a federated view or nickname and this option is specified, or if the package does refer to a federated view or nickname and the option is not specified.
  • FEDERATED_ASYNCHRONY
    Specifies the maximum number of asynchrony table queues (ATQs) that the federated server supports in the access plan for programs that use embedded SQL.
  • FOR
    Specifies whether or not the precompiler modifies the updatable cursor to add a FOR UPDATE clause.
  • FORMAT
    Specifies the date and time format when date/time fields are assigned to string representations in host variables. DEF is a date and time format associated with the country code of the database.
  • FUNCPATH
    Specifies the function path to be used in resolving user-defined distinct types and functions in static SQL. If this option is not specified, the default function path is:
  • GENERIC
    Provides a means of passing new bind options to a target DRDA database. Each option must be separated by one or more spaces and enclosed in double quotes. For example:
  • 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 DB2 statement.
  • GEN-INIT-FLAG
    Generates the SQL-INIT-FLAG variable for DB2 for OS/390 compatibility. The flag is updated when the SQL environment is initialized. If you define this variable in your application, compile your application with this directive set to NOGEN-INIT-FLAG and the variable will not be generated by the precompiler.
  • GEN-SQLCA
    Generates an SQLCA set of program variables equivalent to coding an EXEC SQL INCLUDE SQLCA statement in an application program.
  • HCO
    Causes the DB2 ECM to execute in MFHCO mode, enabling the use of CHARSET EBCDIC, as well as supporting some mainframe DB2 SQL syntax.
  • HOSTVAR
    Enables the precompiler to compile a program when host variables are defined on multiple lines. If host variables are defined on multiple lines, the precompiler generates a COBDB0100S error. If this error occurs, compile the program using DB2(HOSTVAR).
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • IGNORE-NESTED
    In nested programs, indicates the program or programs for which to generate DB2 interface code.
  • IMMEDIATE
    A synonym for directive CALL_RESOLUTION=IMMEDIATE.
  • IMMEDWRITE
    Specifies whether or not to immediately write updates made to group buffer pool dependent pagesets or database partitions.
  • INIT
    Generates a CONNECT statement and/or exit handling code to ensure rollback to the last commit point in the case of an abnormal termination.
  • INSERT
    Allows a program being precompiled or bound against a DB2 Enterprise Server Edition server to request that data inserts be buffered to increase performance.
  • ISOLATION
    Determines how far a program bound to this package can be isolated from the effect of other executing programs. For more information about isolation levels, see the IBM DB2 SQL Reference.
  • KEEPDYNAMIC
    Specifies whether or not to keep dynamic SQL statements after commit points.
  • LANGLEVEL
    For more information about this option, see the IBM DB2 Application Programming Guide.
  • LEVEL
    Defines the level of a module using the consistency token. The consistency token is any alphanumeric value up to 8 characters in length. The RDB package consistency token verifies that the requester's application and the relational database package are synchronized.
  • MSGAREA
    Specifies the name of an alphanumeric data item. If this item is present in the program source it will automatically contain a description of a DB2 error condition (when SQLCODE is non zero).
  • MULTI_PACKAGE
    Enables the preprocessor to generate a BND file and package for the main program and each of the nested programs contained in a given source file.
  • NOT
    Specifies the character code to use for NOT character (¬).
  • OPTPROFILE
    Specifies the name of an existing optimization profile to be used for all static statements in the package.
  • OPTHINT
    Specifies whether or not to use query optimization hints for static SQL.
  • OPTPER
    Causes the DB2 ECM to optimize the performance of CHARSET"EBCDIC" processing.
  • OS400NAMING
    Specifies which naming option is to be used when accessing DB2 for System i® data.
  • OWNER
    Designates a 30-character authorization identifier for the package owner. The owner must have the privileges required to execute the SQL statements in the package. The default is the primary authorization ID of the precompile/bind process if this option has not been explicitly specified.
  • PACKAGE
    Specifies the name of the package to be created and stored in the database.
  • PASS
    Supplies login credentials required to connect to a DB2 database.
  • PRE
    Instructs the preprocessor to generate code that dynamically loads associated DB2 modules at run time.
  • QUALFIX
    Causes the DB2 ECM to append three characters to the name of the host variables when declaring them to DB2. This ensures problems caused by qualification (where two or more host variables have identical names when not qualified) are avoided but has the side-effect that DB2 error messages sometimes display the names of host variables with the three additional characters appended to them.
  • QUALIFIER
    Provides a 128-character implicit qualifier for unqualified table names, views, indexes, and aliases contained in the package. The default is the owner's authorization ID.
  • QUALIFY-CALL
    Works with the DB2 QUALIFIER directive to modify EXEC SQL CALL statements by attaching the schema name to the stored procedure name.
  • QUERYOPT
    Indicates the desired level of optimization for all static SQL statements contained in the package.
  • RELEASE
    Indicates whether resources are released at each COMMIT point, or when the application terminates. This DRDA precompile/bind option is not supported by DB2.
  • REOPT
    Specifies whether or not to have DB2 optimize an access path using values for host variables, parameter markers, global variables, and special registers.
  • REPLVER
    Replaces a specific version of a package. The version identifier specifies which version of the package is to be replaced. Maximum length is 254 characters. REPLVER must follow immediately after ACTION=REPLACE or RETAIN if specified.
  • RETAIN
    Indicates whether EXECUTE authorities are to be preserved when a package is replaced. If ownership of the package changes, the new owner grants the BIND and EXECUTE authority to the previous package owner.
  • SAVE-RETURN-CODE
    When calling DB2 LUW functions, specifies whether or not to save and then restore RETURN-CODE.
  • SINGLE_PACKAGE
    Enables the preprocessor to generate one BND file and package for the main program all of the nested programs contained in a given source file.
  • SORTSEQ
    Specifies which sort sequence table to use on the System i system.
  • SQLERROR
    Indicates whether to create a package or a bind file if an error is encountered.
  • SQLFLAG
    Identifies and reports on deviations from the SQL language syntax specified.
  • SQLRULES
    Specifies whether type 2 CONNECTs are to be processed according to the DB2 rules or the Standard (STD) rules based on ISO/ANS SQL92.
  • SQLWARN
    Indicates whether warnings will be returned from the compilation of dynamic SQL statements (via PREPARE or EXECUTE IMMEDIATE), or from describe processing (via PREPARE...INTO or DESCRIBE). This DB2 precompile/bind option is not supported by DRDA.
  • STATICREADONLY
    Determines whether or not static cursors are treated as READ ONLY.
  • STOPROC
    On entering a stored procedure, converts character data on DB2 LUW stored procedure parameters to CHARSET(EBCDIC), and converts it back to CHARSET(ASCII) on exiting the stored procedure.
  • STRDEL
    Designates whether an apostrophe (') or double quotation marks (") will be used as the string delimiter within SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.
  • SYNCPOINT
    Specifies how commits or rollbacks are to be coordinated among multiple database connections.
  • SYNTAX
    A synonym for directive SQLERROR=CHECK.
  • TEMPORAL-HISTORY
    Specifies whether or not changes to data in system-period temporal tables made by static or dynamic SQL statements make changes to the corresponding history table.
  • TEXT
    The description of a package. Maximum length is 255 characters. The default value is blanks. This DRDA precompile/bind option is not supported by DB2.
  • TRANSFORM-GROUP
    Specifies the transform group name to be used for static SQL. This is a SQL identifier up to 18 characters in length.
  • UDB-VERSION
    Specifies the version of DB2 Database for Linux, UNIX, and Windows (LUW) you want to use.
  • VALIDATE
    Determines when the database manager checks for authorization errors and object not found errors. The package owner authorization ID is used for validity checking.
  • VERSION
    Defines the version identifier for a package. The version identifier is any alphanumeric value, $, #, @, _, -, or ., up to 254 characters in length.
  • XAID
    Simplifies working with multiple XARs of the DB2 RM type defined in a single enterprise server region.
Parent topic: DB2
Related concepts
DB2 Compiler Directive
Error Codes
Setting the DB2 ECM Preprocessor and Compiler Directive Options


ACCESS (DB2 compiler directive option)

ACCESS

Specifies the name of the package to be created and stored in the database.

Syntax:

[NO]ACCESS
ACCESS=package-name

Parameters:

ACCESS
When specified without the package-name parameter, the package name defaults to the base name of the program source file (i.e., without the .cbl extension).
package-name
An alternative name for the package, other than the base name of the program source file.

Properties:

Default: | ACCESS
Synonym: | PACKAGE
Parent topic: DB2 Compiler Directive Options
Related concepts
Binding
Support for Nested COBOL Programs
Related reference
MULTI_PACKAGE
PACKAGE


ACTION

Indicates whether the package can be added or replaced.

Syntax:

ACTION={ADD | REPLACE }
NOACTION

Parameters:

ADD | Indicates that the named package does not exist, and that a new package is to be created. If the package already exists, execution stops, and a diagnostic error message is returned.
REPLACE | Indicates that the old package is to be replaced by a new one with the same location, collection, and package name. If you specify REPLACE, and want to specify REPLVER or RETAIN or both, you must specify them (in either order) immediately after ACTION=REPLACE.

Properties:

Default: NOACTION
Parent topic: DB2 Compiler Directive Options


ALEBRA

When CHARSET(EBCDIC) is also specified, suppresses generation of ASCII/EBCDIC data translation in host variables used in SQL statements.

Syntax:

[NO]ALEBRA

Properties:

Default: NOALEBRA

Dependencies:

Must be used with CHARSET(EBCDIC).

Comments:

Applies only to systems using the Alebra Remote DB2 Access software to connect to DB2 for z/OS in lieu of IBM DB2 Connect software.

Parent topic: DB2 Compiler Directive Options
Related reference
CHARSET


APREUSE

Specifies whether or not to reuse static SQL access plans.

When enabled, the compiler attempts to reuse the access plans for the statement in any existing packages during the bind and during future implicit and explicit rebinds.

Syntax:

APREUSE={NO | YES}

Parameters:

NO | The query compiler does not attempt to reuse access plans for the statements in the package.
YES | The compiler attempts to reuse the access plans for the statements in the package. If there is an existing package, the query compiler attempts to reuse the access plan for every statement that can be matched with a statement in the new bind file. For a statement to match, the statement text must be identical and the section number for the statement in the existing package must match the section number for the statement in the new package.

Properties:

Default: APREUSE=NO

Comment:

Applies to DB2 LUW only.

Parent topic: DB2 Compiler Directive Options


BIND

Instructs the DB2 ECM to create a DBRM file to use for manual binding. Also optionally used to specify an alternative filename for and/or path to the created DBRM file.

Syntax:

BIND
BIND=[path]DBRMfilename
NOBIND

Parameters:

path
The full path to the output directory for the created DBRM file. If not specified, the DBRM file is written to the current directory, the directory specified by the BINDDIR directive, or the directory specified by the HCOBND environment variable. See Binding for details.
DBRMfilename
The prefix for the DBRM filename. The default prefix is the program name, and the default extension is .bnd, which is mandatory and automatically appended if not specified.

Properties:

Default: | NOBIND
Synonym: | BINDFILE

Comments:

When you specify a path using BIND, it takes precedence over that specified by all other output options, if set. For complete information on DBRM file output options, including how to determine the current output file location, see Binding.

Example:

db2(bind=/mybinds/test)
Parent topic: DB2 Compiler Directive Options
Related concepts
Binding
Related reference
BINDDIR
HCOBND environment variable (deprecated)


BINDDIR

Specifies an alternative directory in which to write the DBRM file created during compilation.

Syntax:

BINDDIR=path

Parameters:

path
The full path to the directory where you want to store the created DBRM (.bnd) file.

Properties:

Default: None

Comments:

For complete information on DBRM file output options, including how to determine the current output file location, see Binding.

Parent topic: DB2 Compiler Directive Options
Related concepts
Binding
Related reference
BIND
HCOBND environment variable (deprecated)


BGP

Specifies the type of background syntax checking to be done by the DB2 ECM preprocessor when a program is being edited in Visual COBOL.

Syntax:

BGP={NONE | FULL}

Parameters:

NONE
Validates only the host variables names in EXEC SQL statements, and does not validate SQL syntax.
FULL
Validates all SQL syntax. This parameter requires an active connection to a DB2 database.

Properties:

Default: NONE
Parent topic: DB2 Compiler Directive Options


BLOCK

Specifies the record blocking mode to be used on package creation. For information about row blocking, see the IBM DB2 Administration Guide or the Application Programming Guide.

Syntax:

BLOCK={UNAMBIG | ALL | NO}

Parameters:

ALL | Specifies blocking for read-only cursors or cursors not specified as FOR UPDATE OF. Ambiguous cursors are treated as read-only.
NO | Specifies no blocking of any cursors. Ambiguous cursors are treated as updateable.
UNAMBIG | Specifies blocking for read-only cursors or cursors not specified as FOR UPDATE OF. Ambiguous cursors are treated as updateable.

Properties:

Default: | BLOCK=UNAMBIG
Synonym: | BLOCKING.
Parent topic: DB2 Compiler Directive Options


CALL_RESOLUTION

Specifies how a CALL statement will be resolved.

Syntax:

CALL_RESOLUTION={IMMEDIATE | DEFERRED}
IMMEDIATE

Parameters:

IMMEDIATE | Specifies that the CALL statement will be excecuted as a normal SQL statement. If the name being called cannot be resolved, the precompiler reports error SQL0204.
DEFERRED | Specifies that the CALL statement will be executed as an invocation of the deprecated sqleproc() API.

Properties:

Default: IMMEDIATE

Comments:

You must be using DB2 LUW V8.1 or later for this directive to work.

You need to set CALL_RESOLUTION=DEFERRED if you place the name of the stored procedure in a host variable or if the precompiler fails to resolve the procedure on a CALL statement (in which case, the precompiler reports error SQL0204).

Parent topic: DB2 Compiler Directive Options


CASE

Specifies the case of the package name.
Note:

This option applies only to Linux and Unix DB2 Servers.

Syntax:

CASE={UPPER | LOWER | ASIS}

Parameters:

UPPER | Change the package name to use all upper-case characters
LOWER | Change the package name to use all lower-case characters
ASIS | Use the package name as it was entered
Parent topic: DB2 Compiler Directive Options


CCSIDG

An integer specifying the coded character set identifier (CCSID) to be used for double byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Syntax:

CCSIDG=double-ccsid
NOCCSIDG

Properties:

Default: NOCCSIDG
Parent topic: DB2 Compiler Directive Options


CCSIDM

An integer specifying the coded character set identifier (CCSID) to be used for mixed byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Syntax:

CCSIDM=mixed-ccsid
NOCCSIDM

Properties:

Default: NOCCSIDM
Parent topic: DB2 Compiler Directive Options


CCSIDS

An integer specifying the coded character set identifier (CCSID) to be used for single byte characters in character column definitions (without a specific CCSID clause) in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Syntax:

CCSIDS=sbcs-ccsid
NOCCSIDS

Properties:

Default: NOCCSIDS
Parent topic: DB2 Compiler Directive Options


CHARSUB

Designates the default character sub-type that is to be used for column definitions in CREATE and ALTER TABLE SQL statements. This DRDA precompile/bind option is not supported by DB2.

Syntax:

CHARSUB={DEFAULT | BIT | SBCS | MIXED}
NOCHARSUB

Parameters:

BIT | Use the FOR BIT DATA SQL character sub-type in all new character columns for which an explicit sub-type is not specified.
DEFAULT | Use the target system defined default in all new character columns for which an explicit sub-type is not specified.
MIXED | Use the FOR MIXED DATA SQL character sub-type in all new character columns for which an explicit sub-type is not specified.
SBCS | Use the FOR SBCS DATA SQL character sub-type in all new character columns for which an explicit sub-type is not specified.

Properties:

Default: NOCHARSUB
Parent topic: DB2 Compiler Directive Options


COLLECTION

Specifies a 30-character collection identifier for the package. If this is not specified, the authorization identifier for the user processing the package is used.

Syntax:

COLLECTION=schema name
NOCOLLECTION

Properties:

Default: NOCOLLECTION
Parent topic: DB2 Compiler Directive Options


COMMIT

Specifies where implicit COMMIT statements should be generated.

Syntax:

COMMIT={1 | 2 | 3 | 4}

Parameters:

1 | No COMMIT statements implicitly generated
2 | COMMIT statements are implicitly generated on STOP RUN statements and at the end of the program
3 | COMMIT statements are implicitly generated on STOP RUN and EXIT PROGRAM statements and at the end of the program
4 | COMMIT statements are implicitly generated after every SQL statement

Properties:

Default: COMMIT=2
Parent topic: DB2 Compiler Directive Options


CONCAT

Specifies the ASCII character code to use for the CONCAT symbol (|).

Syntax:

CONCAT={ascii-character-code | 33}

Properties:

Default: CONCAT=33
Parent topic: DB2 Compiler Directive Options


CONCURRENTACCESSRESOLUTION

Specifies the concurrent access resolution to use for statements in the package.

Syntax:

CONCURRENTACCESSRESOLUTION={WAIT | USE-CURRENT}
NOCONCURRENTACCESSRESOLUTION

Parameters:

WAIT | Specifies Cursor Stability and higher scans to wait for the commit or rollback when encountering data in the process of being updated or deleted. Rows in the process of being inserted are not skipped. The settings for the registry variables DB2_EVALUNCOMMITTED, DB2_SKIPDELETED , and DB2_SKIPINSERTED do not apply.
USE CURRENT | Specifies that the database manager can use the currently committed version of the data for applicable scans when it is in the process of being updated or deleted. Rows in the process of being inserted can be skipped. This clause applies when the isolation level in effect is Cursor Stability or Read Stability (for Read Stability it skips uncommited inserts only) and is ignored otherwise. Applicable scans include read-only scans that can be part of a read-only statement as well as a non read-only statement. The settings for the registry variables DB2_EVALUNCOMMITTED, DB2_SKIPDELETED, and DB2_SKIPINSERTED do not apply to scans using currently committed. However, the settings for these registry variables still apply to scans that do not use currently committed.

Properties:

Default: NOCONCURRENTACCESSRESOLUTION
Parent topic: DB2 Compiler Directive Options


CONNECT

Specifies that a CONNECT statement is to be processed as either a type 1 CONNECT or a type 2 CONNECT.

Syntax:

CONNECT={1 | 2}
NOCONNECT

Properties:

Default: NOCONNECT
Parent topic: DB2 Compiler Directive Options


COPY

Enables the use SQL host variables in COBOL copybooks.

Syntax:

COPY
NOCOPY

Parameters:

Default: NOCOPY
Parent topic: DB2 Compiler Directive Options


CTRACE

Creates a trace file for submission to Technical Support if requested. The filename of the file that is created is sqltrace.txt.

Syntax:

CTRACE
NOCTRACE

Properties:

Default: NOCTRACE
Parent topic: DB2 Compiler Directive Options


DB

Specifies the name of the database that the program accesses. If DB is specified without a parameter, the database specified in the environment variable DB2DBDFT is used.

Syntax:

DB=database name
DB

Properties:

Default: DB
Parent topic: DB2 Compiler Directive Options
Related reference
PASS


DBPROTOCOL

Specifies what protocol to use when connecting to a remote site that is identified by a three-part name statement.
Note:

Supported by DB2 for OS/390® only. For a list of supported option values, see your DB2 for OS/390 documentation.

Syntax:

DBPROTOCOL={DRDA | PRIVATE}

Parameters:

DRDA
PRIVATE
Parent topic: DB2 Compiler Directive Options


DEC

Specifies the maximum precision to be used in decimal arithmetic operations. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Use 15 to specify 15-digit precision is used in decimal arithmetic operations.

Use 31 to specify 31-digit precision is used in decimal arithmetic operations.

Syntax:

DEC={31 | 15}
NODEC

Properties:

Default: NODEC
Parent topic: DB2 Compiler Directive Options


DECDEL

Designates whether a period (.) or a comma (,) will be used as the decimal point indicator in decimal and floating point literals. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Syntax:

DECDEL={PERIOD | COMMA}
NODECDEL

Parameters:

COMMA | Use a comma (,) as the decimal point indicator.
PERIOD | Use a period (.) as the decimal point indicator.

Properties:

Default: NODECDEL
Parent topic: DB2 Compiler Directive Options


DEFERRED_PREPARE

Provides a performance enhancement when accessing DB2 common server databases or DRDA databases. This option combines the SQL PREPARE statement flow with the associated OPEN, DESCRIBE, or EXECUTE statement flow to minimize inter-process or network flow.

Syntax:

DEFERRED_PREPARE={NO | YES | ALL}
NODEFERRED_PREPARE

Parameters:

NO | The PREPARE statement will be executed at the time it is issued.
YES | Execution of the PREPARE statement will be deferred until the corresponding OPEN, DESCRIBE, or EXECUTE statement is issued. The PREPARE statement will not be deferred if it uses the INTO clause, which requires an SQLDA to be returned immediately. However, if the PREPARE INTO statement is issued for a cursor that does not use any parameter markers, the processing will be optimized by pre-OPENing the cursor when the PREPARE is executed.
ALL | Same as YES, except that a PREPARE INTO statement which contains parameter markers is deferred. If a PREPARE INTO statement does not contain parameter markers, pre-OPENing of the cursor will still be performed. If the PREPARE statement uses the INTO clause to return an SQLDA, the application must not reference the content of this SQLDA until the OPEN, DESCRIBE, or EXECUTE statement is issued and returned.

Properties:

Default: NODEFERRED_PREPARE
Parent topic: DB2 Compiler Directive Options


DEGREE

Specifies whether or not the query is to be executed using I/O parallel processing.

Syntax:

DEGREE={1 | degree-of-parallelism | ANY}
NODEGREE

Parameters:

1 | Prohibits parallel I/O operations
degree-of-I/O-parallelism | Specifies the degree of parallel I/O operations, a value between 2 and 32767 (inclusive)
ANY | Allows parallel I/O operations.

Properties:

Default: NODEGREE
Parent topic: DB2 Compiler Directive Options


DISCONNECT

Syntax:

DISCONNECT={EXPLICIT | CONDITIONAL | AUTOMATIC}
NODISCONNECT

Parameters:

AUTOMATIC | Specifies that all database connections are to be disconnected at commit.
CONDITIONAL | Specifies that the database connections that have been marked RELEASE or have no open WITH HOLD cursors are to be disconnected at commit.
EXPLICIT | Specifies that only database connections that have been explicitly marked for release by the RELEASE statement are to be disconnected at commit.

Properties:

Default: NODISCONNECT
Parent topic: DB2 Compiler Directive Options


DYNAMICRULES

Specifies which authorization identifier to use when dynamic SQL in a package is executed.

Syntax:

DYNAMICRULES={BIND | RUN | DEFINE | DEFINEBIND | DEFINERUN |
               INVOKE | INVOKEBIND | INVOKERUN}
NODYNAMICRULES

Parameters:

BIND | Indicates that the authorization identifier used for the execution of dynamic SQL is the package owner.
RUN | Indicates that the authorization identifier used for the execution of dynamic SQL is the authid of the person executing the package.
DEFINE | Indicates that the authorization identifier used for execution of dynamic SQL is the definer of the UDF or stored procedure. This option is not supported by DB2.
DEFINEBIND | If the package is used within a routine context, the authorization identifier of the routine definer is to be used for authorization checking and for implicit qualification of unqualified object references within dynamic SQL statements within the routine. If the package is used as a standalone application, dynamic SQL statements are processed as though the package were bound with DYNAMICRULES BIND.
DEFINERUN | If the package is used within a routine context, the authorization identifier of the routine definer is to be used for authorization checking and for implicit qualification of unqualified object references within dynamic SQL statements within the routine. If the package is used as a standalone application, dynamic SQL statements are processed as though the package were bound with DYNAMICRULES RUN.
INVOKE | Indicates that the authorization identifier used for the execution of dynamic SQL is the invoker of the UDF or stored procedure. This option is not supported by DB2.
INVOKEBIND | If the package is used within a routine context, the current statement authorization identifier in effect when the routine is invoked is to be used for authorization checking of dynamic SQL statements and for implicit qualification of unqualified object references within dynamic SQL statements within that routine. If the package is used as a standalone application, dynamic SQL statements are processed as though the package were bound with DYNAMICRULES BIND.
INVOKERUN | If the package is used within a routine context, the current statement authorization identifier in effect when the routine is invoked is to be used for authorization checking of dynamic SQL statements and for implicit qualification of unqualified object references within dynamic SQL statements within that routine. If the package is used as a standalone application, dynamic SQL statements are processed as though the package were bound with DYNAMICRULES RUN.

Properties:

Default: NODYNAMICRULES
Parent topic: DB2 Compiler Directive Options


ENCODING

Specifies the encoding for all host variables in static statements in the plan or package.
Note:

Supported by DB2 for OS/390® only. For a list of supported option values, see your DB2 for OS/390 documentation.

Syntax:

ENCODING={ASCII | EBCDIC | UNICODE | CCSID}
Parent topic: DB2 Compiler Directive Options


EXPLAIN

Stores information in the Explain tables about the access plans chosen for each SQL statement in the package. DRDA does not support the ALL value for this option.

Syntax:

EXPLAIN={NO | YES | ALL}
NOEXPLAIN

Parameters:

NO | Explain information will not be captured.
YES | Explain tables will be populated with information about the chosen access plan.
ALL | Explain information for each eligible static SQL statement will be placed in the Explain tables. In addition, Explain information will be gathered for eligible dynamic SQL statements at run time, even if the CURRENT EXPLAIN SNAPSHOT register is set to NO. For more information about special registers, see the IBM DB2 SQL Reference.

Properties:

Default: NOEXPLAIN
Parent topic: DB2 Compiler Directive Options


EXPLSNAP

Stores Explain Snapshot information in the Explain tables. This DB2 precompile/bind option is not supported by DRDA.

Syntax:

EXPLSNAP={NO | YES | ALL}
NOEXPLSNAP

Parameters:

NO | An Explain Snapshot will not be captured.
YES | An Explain Snapshot for each eligible static SQL statement will be placed in the Explain tables.
ALL | An Explain Snapshot for each eligible static SQL statement will be placed in the Explain tables. In addition, Explain Snapshot information will be gathered for eligible dynamic SQL statements at run time, even if the CURRENT EXPLAIN SNAPSHOT register is set to NO. For more information about special registers, see the IBM DB2 SQL Reference.

Properties:

Default: NOEXPLSNAP
Parent topic: DB2 Compiler Directive Options


EXTENDEDINDICATOR

Enables the recognition of extended indicator variable values during the execution of the associated plan or package.

Syntax:

EXTENDEDINDICATOR={NO | YES }

Parameters:

NO | Extended indicator variable values are recognized. Using any non-recognized indicator variable values, or using the default or unassigned indicator variable-based values in a non-supported location will cause DB2 database manager to generate an error message during execution of the bound statement.
YES | Extended indicator variable values are not recognized. Indicator variables are normal indicator variables; negative indicator variable values imply null, and positive or zero values imply non-null.

Properties:

Default: EXTENDEDINDICATOR=NO
Parent topic: DB2 Compiler Directive Options


FEDERATED

Specifies whether a static SQL statement references a nickname or a federated view. SQL errors are returned if the package does not refer to a federated view or nickname and this option is specified, or if the package does refer to a federated view or nickname and the option is not specified.

Syntax:

FEDERATED={NO | YES}

Parameters:

NO | The program will connect to a DB2 LUW. This is the default value.
YES | The program will access a DB2 federated system.

Properties:

Default: FEDERATED=NO
Parent topic: DB2 Compiler Directive Options


FEDERATED_ASYNCHRONY

Specifies the maximum number of asynchrony table queues (ATQs) that the federated server supports in the access plan for programs that use embedded SQL.

Syntax:

FEDERATED_ASYNCHRONY={ANY | atqsNo}
NOFEDERATED_ASYNCHONY

Parameters:

ANY | The optimizer determines the number of ATQs for the access plan. The optimizer assigns an ATQ to all eligible SHIP or remote pushdown operators in the plan. The value that is specified for DB2_MAX_ASYNC_REQUESTS_PER_QUERY server option limits the number of asynchronous requests.
atqsNo | The number of ATQs in the plan. You specify a number in the range 0 to 32767.

Properties:

Default: NOFEDERATED_ASYNCHONY

Comment:

Applies to DB2 LUW only.

Parent topic: DB2 Compiler Directive Options


FOR

Specifies whether or not the precompiler modifies the updatable cursor to add a FOR UPDATE clause.

Syntax:

[NO]FOR

Properties:

Default: FOR
Parent topic: DB2 Compiler Directive Options


FORMAT

Specifies the date and time format when date/time fields are assigned to string representations in host variables. DEF is a date and time format associated with the country code of the database.

Syntax:

FORMAT={DEF | USA | EUR | ISO | JIS | LOC}

Parameters:

EUR | is the IBM standard for European date and time format.
ISO | is the date and time format of the International Standards Organization.
JIS | is the date and time format of the Japanese Industrial Standard.
LOC | is the date and time format in local form associated with the country code of the database.
USA | is the IBM standard for U.S. date and time format.

Properties:

Default: | FORMAT=LOC
Synonym: | DATETIME.
Parent topic: DB2 Compiler Directive Options


FUNCPATH

Specifies the function path to be used in resolving user-defined distinct types and functions in static SQL. If this option is not specified, the default function path is:
"SYSIBM","SYS FUN",USER

where USER is the value of the USER special register. This DB2 precompile/bind option is not supported by DRDA.

Syntax:

FUNCPATH=schema-name
NOFUNCPATH

Parameters:

schema-name is a short SQL identifier, either ordinary or delimited, which identifies a schema that exists at the application server. No validation that the schema exists is made at precompile or at bind time. The same schema cannot appear more than once in the function path. The number of schemas that can be specified is limited by the length of the resulting function path, which cannot exceed 254 bytes. The schema SYSIBM does not need to be explicitly specified; it is implicitly assumed to be the first schema if it is not included in the function path. For more information, see the IBM DB2 SQL Reference.

Properties:

Default: NOFUNCPATH
Parent topic: DB2 Compiler Directive Options


GENERIC

Provides a means of passing new bind options to a target DRDA database. Each option must be separated by one or more spaces and enclosed in double quotes. For example:
DB2(GENERIC="keepdynamic
  yes")

Syntax:

GENERIC=string
Parent topic: DB2 Compiler Directive Options


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 DB2 statement.

Syntax:

[NO]GEN-HV-FROM-GROUP

Properties:

Default: NOGEN-HV-FROM-GROUP

Comments:

Recompile using GEN-HV-FROM-GROUP if your code contains a multiple-level group name in a FETCH or singleton SELECT and the compiler throws the following error:

COBDB0103 host-var definition does not match the column type associated with it.

Parent topic: DB2 Compiler Directive Options


GEN-INIT-FLAG

Generates the SQL-INIT-FLAG variable for DB2 for OS/390 compatibility. The flag is updated when the SQL environment is initialized. If you define this variable in your application, compile your application with this directive set to NOGEN-INIT-FLAG and the variable will not be generated by the precompiler.

Syntax:

GEN-INIT-FLAG
NOGEN-INIT-FLAG

Properties:

Default: GEN-INIT-FLAG
Parent topic: DB2 Compiler Directive Options


GEN-SQLCA

Generates an SQLCA set of program variables equivalent to coding an EXEC SQL INCLUDE SQLCA statement in an application program.

Syntax:

GEN-SQLCA
NOGEN-SQLCA

Properties:

Default: NOGEN-SQLCA
Parent topic: DB2 Compiler Directive Options


HCO

Causes the DB2 ECM to execute in MFHCO mode, enabling the use of CHARSET EBCDIC, as well as supporting some mainframe DB2 SQL syntax.

Syntax:

[NO]HCO

Properties:

Default: HCO

Comments:

HCO is on by default across all platforms

Optionally, you can turn HCO off by using NOHCO.

Parent topic: DB2 Compiler Directive Options
Related reference
OPTPER


HOSTVAR

Enables the precompiler to compile a program when host variables are defined on multiple lines. If host variables are defined on multiple lines, the precompiler generates a COBDB0100S error. If this error occurs, compile the program using DB2(HOSTVAR).

Syntax:

HOSTVAR
NOHOSTVAR

Properties:

Default: NOHOSTVAR
Parent topic: DB2 Compiler Directive Options


HSFTRACE

Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.

Syntax:

[NO]HSFTRACE

Properties:

Default: HSFTRACE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

Comments:

SMFTRACE is an alias for HSFTRACE.

Parent topic: DB2 Compiler Directive Options


IGNORE-NESTED

In nested programs, indicates the program or programs for which to generate DB2 interface code.
Tip: For detailed information on how the DB2 ECM handles nested programs, see Support for Nested COBOL Programs.

Syntax:

[NO]IGNORE-NESTED
IGNORE-NESTED=program-id

Parameters:

IGNORE-NESTED
When used without the program-id parameter, the DB2 ECM generates DB2 interface code for the main program by default.
program-id
A program ID that, when encountered by the DB2 ECM, triggers the generation of DB2 interface code for that program only. Any nested program ID encountered before the specified program ID is ignored and no DB2 interface code is generated for that program.
Note: You must specify the program ID in the source code to avoid compiler errors.

Properties:

Default: NOIGNORE-NESTED

Dependencies:

IGNORE-NESTED is mutually exclusive to both the SINGLE_PACKAGE and MULTI_PACKAGE directives.

Parent topic: DB2 Compiler Directive Options
Related concepts
Support for Nested COBOL Programs


IMMEDIATE

A synonym for directive CALL_RESOLUTION=IMMEDIATE.

Syntax:

SYNTAX

Properties:

Synonym: CALL_RESOLUTION=IMMEDIATE
Parent topic: DB2 Compiler Directive Options


IMMEDWRITE

Specifies whether or not to immediately write updates made to group buffer pool dependent pagesets or database partitions.
Note:

Supported by DB2 for OS/390® only. For a list of supported option values, see your DB2 for OS/390 documentation.

Syntax:

IMMEDWRITE={NO | YES | PH1}
Parent topic: DB2 Compiler Directive Options


INIT

Generates a CONNECT statement and/or exit handling code to ensure rollback to the last commit point in the case of an abnormal termination.
Note: INIT, INIT=S and INIT=X are deprecated, and provided for backward compatibility only.
Important: We strongly recommend that you use EXEC SQL CONNECT statements in your application instead of INIT, INIT=S or INIT=X.

Syntax:

INIT[={[PROT|P] | S | X}]
NOINIT

Parameters:

INIT | Generates a CONNECT statement in shared mode, and also generates exit handling code
INIT=S
INIT=X | Generates a CONNECT statement in exclusive mode, and also generates exit handling code
INIT=PROT | Generates exit handling code only.
INIT=P
NOINIT | No code generation whatsoever.

Properties:

Default: NOINIT

Dependency:

  • If your INIT call generates a connection, you can use it with the DB2 PASS compiler directive option.

Comments:

  • For the following reasons, we strongly recommend that you consider placing an EXEC SQL CONNECT statement into your code instead of using INIT, INIT=S or INIT=X :
    • Because INIT actually stores user credentials in your code, its use can raise security concerns.
    • If IBM were to change the underlying APIs used to implement a database connection, this could cause compatibility problems when using INIT.
  • Set the INIT directive, regardless of the parameter options, only once for each application. Do not set INIT for SQL programs called by other SQL programs. Instead, specify the INIT option for the first SQL program executed in a run unit. Compiling more than one module in an application with the INIT option could cause your program to terminate abnormally.
  • INIT is ignored when used within an OO program.
Parent topic: DB2 Compiler Directive Options


INSERT

Allows a program being precompiled or bound against a DB2 Enterprise Server Edition server to request that data inserts be buffered to increase performance.

Syntax:

INSERT={DEF | BUF}
NOINSERT

Parameters:

BUF | Specifies that inserts from an application should be buffered.
DEF | Specifies that inserts from an application should not be buffered.

Properties:

Default: NOINSERT
Parent topic: DB2 Compiler Directive Options


ISOLATION

Determines how far a program bound to this package can be isolated from the effect of other executing programs. For more information about isolation levels, see the IBM DB2 SQL Reference.

Syntax:

ISOLATION={CS | RR | UR | RS | NC}

Parameters:

CS | specifies Cursor Stability as the isolation level.
NC | (No Commit) specifies that commitment control is not to be used. This isolation level is not supported by DB2.
RR | specifies Repeatable Read as the isolation level.
RS | specifies Read Stability as the isolation level. Read Stability ensures that the execution of SQL statements in the package is isolated from other application processes for rows read and changed by the application.
UR | specifies Uncommitted Read as the isolation level.

Properties:

Default: ISOLATION=CS
Parent topic: DB2 Compiler Directive Options


KEEPDYNAMIC

Specifies whether or not to keep dynamic SQL statements after commit points.
Note:

Supported by DB2 for OS/390® only. For a list of supported option values, see your DB2 for OS/390 documentation.

Syntax:

KEEPDYNAMIC={NO | YES}
Parent topic: DB2 Compiler Directive Options


LANGLEVEL

For more information about this option, see the IBM DB2 Application Programming Guide.

Syntax:

LANGLEVEL={SAA1 | NONE | MIA | SQL92E}

Parameters:

MIA | The FOR UPDATE clause is optional for positioned updates. C null-terminated strings are padded with blank characters, and always include the null-terminating character. This option is not supported by DB2 CONNECT or DDCS.
SAA1 | Requires the FOR UPDATE clause for all columns that are updated in a positioned update. C null-terminated strings are not padded with blank characters, and do not include a null-terminating character if truncation occurs.
NONE | Synonym for SAA1.
SQL92E | Similar to MIA. See the manual for the differences.

Properties:

Default: | LANGLEVEL=SAA1
Synonym: | STDLVL.
Parent topic: DB2 Compiler Directive Options


LEVEL

Defines the level of a module using the consistency token. The consistency token is any alphanumeric value up to 8 characters in length. The RDB package consistency token verifies that the requester's application and the relational database package are synchronized.
Note:

This option is not recommended for general use.

Syntax:

LEVEL=consistency-token
NOLEVEL

Properties:

Default: NOLEVEL
Parent topic: DB2 Compiler Directive Options


MSGAREA

Specifies the name of an alphanumeric data item. If this item is present in the program source it will automatically contain a description of a DB2 error condition (when SQLCODE is non zero).

Syntax:

MSGAREA={data-item-name | MFSQLMESSAGETEXT }
NOMSGAREA)

Properties:

Default: MSGAREA=MFSQLMESSAGETEXT
Parent topic: DB2 Compiler Directive Options


MULTI_PACKAGE

Enables the preprocessor to generate a BND file and package for the main program and each of the nested programs contained in a given source file.

When specified, overrides the default SINGLE_PACKAGE behavior. For each program defined in the source file, the DB2 ECM creates a distinct BND file, each with its own BIND timestamp token(s), and a corresponding package.

The names of generated BND and package files are based on the program ID of each nested program, and the BND file and package names for the main program are based on the base name of the source file. However, when the PACKAGE (or ACCESS) directive is used with a parameter, the BND file and PACKAGE name for each nested program is a combination of the PACKAGE parameter value and the program ID; the main program's BND file is the base name of the source file, and its PACKAGE name is the PACKAGE parameter value.

Tip: For detailed information on how the DB2 ECM handles nested programs, see Support for Nested COBOL Programs.

Syntax:

[NO]MULTI_PACKAGE

Properties:

Default: | NOMULTI_PACKAGE
Synonym: | ALLOW-NESTED

Dependencies:

MULTI_PACKAGE is mutually exclusive to both the SINGLE_PACKAGE and IGNORE-NESTED directives.

When specified, overrides the default SINGLE_PACKAGE setting.

Parent topic: DB2 Compiler Directive Options
Related concepts
Support for Nested COBOL Programs
Related reference
ACCESS
PACKAGE
SINGLE_PACKAGE


NOT

Specifies the character code to use for NOT character (¬).

Syntax:

  NOT={ansi-character-code | 172}

Properties:

Default: NOT=172
Parent topic: DB2 Compiler Directive Options


OPTPROFILE

Specifies the name of an existing optimization profile to be used for all static statements in the package.
Note: This option is not supported by DRDA.

Syntax:

OPTPROFILE=profileName
NOOPTPROFILE

Parameters:

profileName The default value is an empty string. When specified, the name applies as the default for dynamic preparation of DML statements for which the CURRENT OPTIMIZATION PROFILE special register is null. If the specified name is unqualified, it is an SQL identifier, which is implicitly qualified by the QUALIFIER bind option.

Properties:

Default: NOOPTPROFILE

Comment:

Applies to DB2 LUW only.

Parent topic: DB2 Compiler Directive Options


OPTHINT

Specifies whether or not to use query optimization hints for static SQL.
Note:

Supported by DB2 for OS/390® only. For a list of supported option values, see your DB2 for OS/390 documentation.

Syntax:

OPTHINT=hintId
Parent topic: DB2 Compiler Directive Options


OPTPER

Causes the DB2 ECM to optimize the performance of CHARSET"EBCDIC" processing.

Syntax:

[NO]OPTPER

Properties:

Default: OPTPER

Comments:

OPTPER is on by default across all platforms

Optionally, you can turn OPTPER off by using NOOPTPER.

Parent topic: DB2 Compiler Directive Options
Related reference
HCO


OS400NAMING

Specifies which naming option is to be used when accessing DB2 for System i® data.
Note:

Supported by DB2 for System i only. For a list of supported option values, see your DB2 for System i documentation.

Syntax:

OS44NAMING={SYSTEM | SQL}
Parent topic: DB2 Compiler Directive Options


OWNER

Designates a 30-character authorization identifier for the package owner. The owner must have the privileges required to execute the SQL statements in the package. The default is the primary authorization ID of the precompile/bind process if this option has not been explicitly specified.

Syntax:

OWNER=authorization-id
NOOWNER

Properties:

Default: | NOOWNER
Synonym: | SCHEMA.
Parent topic: DB2 Compiler Directive Options


PACKAGE

Specifies the name of the package to be created and stored in the database.

Syntax:

[NO]PACKAGE
PACKAGE=package-name

Parameters:

PACKAGE
When specified without the package-name parameter, the package name defaults to the base name of the program source file (i.e., without the .cbl extension).
package-name
An alternative name for the package, other than the base name of the program source file.

Properties:

Default: | PACKAGE
Synonym: | ACCESS
Parent topic: DB2 Compiler Directive Options
Related concepts
Support for Nested COBOL Programs
Related reference
MULTI_PACKAGE
ACCESS


PASS

Supplies login credentials required to connect to a DB2 database.

Syntax:

PASS={password | userid.password}
NOPASS

Parameters:

password
Visual COBOL accepts a maximum of 18 characters for the password; however, the length cannot exceed the maximum set by DB2 or the operating system.
userid
Visual COBOL accepts a maximum of 30 characters for the user ID; however, the length cannot exceed the maximum set by DB2 or the operating system.

Properties:

Default: NOPASS

Comments:

By default, the compiler uses the operating system user credentials to connect to the DB2 database.

When connecting to a database, use PASS only when it is necessary to supply credentials other than the operating system credentials as in the following cases:

  • You are logged into the operating system as a user that does not have the documented DB2 privileges.
  • You are logged into the operating system as a user who is not the owner of unqualified database metadata referenced by the program being compiled.
  • When connecting to a database that resides on a remote server and is catalogued locally.
Parent topic: DB2 Compiler Directive Options
Related reference
DB


PRE

Instructs the preprocessor to generate code that dynamically loads associated DB2 modules at run time.

Syntax:

[NO]PRE

Properties:

Default: PRE

Comments:

PRE must be used when creating INT or GNT files.

Parent topic: DB2 Compiler Directive Options


QUALFIX

Causes the DB2 ECM to append three characters to the name of the host variables when declaring them to DB2. This ensures problems caused by qualification (where two or more host variables have identical names when not qualified) are avoided but has the side-effect that DB2 error messages sometimes display the names of host variables with the three additional characters appended to them.

Syntax:

[NO]QUALFIX

Properties:

Default: NOQUALFIX
Parent topic: DB2 Compiler Directive Options
Related concepts
Error Codes


QUALIFIER

Provides a 128-character implicit qualifier for unqualified table names, views, indexes, and aliases contained in the package. The default is the owner's authorization ID.

Syntax:

QUALIFIER=qualifier-name
NOQUALIFIER

Properties:

Default: NOQUALIFIER
Parent topic: DB2 Compiler Directive Options
Related reference
QUALIFY-CALL


QUALIFY-CALL

Works with the DB2 QUALIFIER directive to modify EXEC SQL CALL statements by attaching the schema name to the stored procedure name.

Syntax:

QUALIFY-CALL
NOQUALIFY-CALL

Properties:

Default: NOQUALIFY-CALL

Dependencies:

Must be used with QUALIFIER DB2 compiler directive option.

Example:

When QUALIFY-CALL is used with QUALIFIER:

DB2(QUALIFIER=TESTER QUALIFY-CALL)

This statement:

exec sql call mystoredproc(:parm1) end-exec

Becomes:

exec sql call TESTER.mystoredproc (:parm1) end-exec
Parent topic: DB2 Compiler Directive Options
Related reference
QUALIFIER


QUERYOPT

Indicates the desired level of optimization for all static SQL statements contained in the package.

Syntax:

QUERYOPT=optimization-level
NOQUERYOPT

Parameters:

optimization-level
A number that represents the optimization level. The default is 5. For the complete range of valid optimization level numbers and a description of each, see the SET CURRENT QUERY OPTIMIZATION statement topic in the SQL Reference of your IBM DB2 documentation.

Properties:

Default: NOQUERYOPT

Comments:

QUERYOPT is not supported by DRDA.

Parent topic: DB2 Compiler Directive Options


RELEASE

Indicates whether resources are released at each COMMIT point, or when the application terminates. This DRDA precompile/bind option is not supported by DB2.

Syntax:

RELEASE={COMMIT | DEALLOCATE}
NORELEASE

Parameters:

COMMIT | Release resources at each COMMIT point. Used for dynamic SQL statements.
DEALLOCATE | Release resources only when the application terminates.

Properties:

Default: NORELEASE
Parent topic: DB2 Compiler Directive Options


REOPT

Specifies whether or not to have DB2 optimize an access path using values for host variables, parameter markers, global variables, and special registers.

Syntax:

REOPT={NONE | ONCE | ALWAYS}

Parameters:

NONE | DB2 does not optimize the access path for SQL statements containing host variables, parameter markers, global variables, or special registers, and uses real values for these variables. Instead, DB2 uses the default estimates for the these variables, caching and using these defaults subsequently.
ONCE | When a query is first executed, DB2 optimizes the access path for SQL statements using the real values of the host variables, parameter markers, global variables, or special registers caching and using these real values subsequently.
ALWAYS | DB2 compiles and reoptimizes the access path for SQL statements using the values of the host variables, parameter markers, global variables, or special registers known at each execution time.

Properties:

Default: NONE
Parent topic: DB2 Compiler Directive Options


REPLVER

Replaces a specific version of a package. The version identifier specifies which version of the package is to be replaced. Maximum length is 254 characters. REPLVER must follow immediately after ACTION=REPLACE or RETAIN if specified.

Syntax:

REPLVER=version-id
NOREPLVER

Properties:

Default: NOREPLVER
Parent topic: DB2 Compiler Directive Options


RETAIN

Indicates whether EXECUTE authorities are to be preserved when a package is replaced. If ownership of the package changes, the new owner grants the BIND and EXECUTE authority to the previous package owner.

Syntax:

RETAIN={YES | NO}
NORETAIN

Parameters:

NO | does not preserve EXECUTE authorities when a package is replaced.
YES | preserves EXECUTE authorities when a package is replaced.

Properties:

Default: NORETAIN

Comments:

RETAIN must follow immediately after ACTION=REPLACE or REPLVER if specified.

Parent topic: DB2 Compiler Directive Options


SAVE-RETURN-CODE

When calling DB2 LUW functions, specifies whether or not to save and then restore RETURN-CODE.

Syntax:

[NO]SAVE-RETURN-CODE

Properties:

Default: SAVE-RETURN-CODE

Comments:

Use NOSAVE-RETURN-CODE if your COBOL dialect does not recognize the COBOL special register RETURN-CODE.

Parent topic: DB2 Compiler Directive Options


SINGLE_PACKAGE

Enables the preprocessor to generate one BND file and package for the main program all of the nested programs contained in a given source file.

For all programs defined in the source file, the DB2 ECM creates a single BND file; thus a single package is bound and stored in your DB2 LUW database. Because they are all bound into the same DB2 LUW package, all programs in the package share the same BIND timestamp token(s) as the main program. The naming conventions of the BND and package files follow the same rules as for non-nested programs.

Important: Cursors that are shared among the programs in a given package must be uniquely named and defined within that package.
Tip: For detailed information on how the DB2 ECM handles nested programs, see Support for Nested COBOL Programs.

Syntax:

[NO]SINGLE_PACKAGE

Properties:

Default: | NOSINGLE_PACKAGE
Synonym: | MULTI-NESTED

Dependencies:

SINGLE_PACKAGE is mutually exclusive to both the MULTI_PACKAGE and IGNORE-NESTED directives.

Parent topic: DB2 Compiler Directive Options
Related concepts
Support for Nested COBOL Programs
Related reference
MULTI_PACKAGE


SORTSEQ

Specifies which sort sequence table to use on the System i system.
Note:

Supported by DB2 for System i only. For a list of supported option values, see your DB2 for System i documentation.

Syntax:

SORTSEQ={JOBRUN | HEX}
Parent topic: DB2 Compiler Directive Options


SQLERROR

Indicates whether to create a package or a bind file if an error is encountered.

Syntax:

SQLERROR={NOPACKAGE | CHECK | CONTINUE}
NOSQLERROR

Parameters:

CHECK | Specifies that the target system performs all syntax and semantic checks on the SQL statements being bound. A package will not be created as part of this process. If, while creating a package, an existing package with the same name and version is encountered, the existing package is neither dropped nor replaced if action replace was specified.
CONTINUE | A package or a bind file is created even when SQL errors are encountered. This option is not supported by DB2.
NOPACKAGE | A package or a bind file is not created if an error is encountered.

Properties:

Default: | NOSQLERROR
Synonym: | ERROR.

Comments:

If syntax is used together with the package option, package is ignored.

Parent topic: DB2 Compiler Directive Options


SQLFLAG

Identifies and reports on deviations from the SQL language syntax specified.

A bind file or a package is created only if the BINDFILE or the PACKAGE option is specified in addition to the SQLFLAG option.

Local syntax checking is performed only if one of the following options is specified: BINDFILE, PACKAGE, SQLERROR CHECK, SYNTAX.

If SQLFLAG is not specified, the flagger function is not invoked, and the bind file or the package is not affected.

Syntax:

SQLFLAG={MVSDB2V23 | MVSDB2V31 | MVSDB2V41|SQL92E}-SYNTAX
NOSQLFLAG

Parameters:

MVSDB2V23-SYNTAX | The SQL statements will be checked against MVS DB2 Version 2.3 SQL language syntax. Any deviation from the syntax is reported in the precompiler listing.
MVSDB2V31-SYNTAX | The SQL statements will be checked against MVS DB2 Version 3.1 SQL language syntax. Any deviation from the syntax is reported in the precompiler listing.
MVSDB2V41-SYNTAX | The SQL statements will be checked against MVS DB2 Version 4.1 SQL language syntax. Any deviation from the syntax is reported in the precompiler listing.
SQL92E-SYNTAX | The SQL statements will be checked against ANSI or ISO SQL92 SQL language syntax. Any deviation from the syntax is reported in the compiler listing.

Properties:

Default: | NOSQLFLAG
Synonym: | FLAG.
Parent topic: DB2 Compiler Directive Options


SQLRULES

Specifies whether type 2 CONNECTs are to be processed according to the DB2 rules or the Standard (STD) rules based on ISO/ANS SQL92.

Syntax:

SQLRULES={DB2 | STD}
NOSQLRULES

Parameters:

DB2 | Allow the use of the SQL CONNECT statement to switch the current connection to another established (dormant) connection.
STD | Allow the use of the SQL CONNECT statement to establish a new connection only. The SQL SET CONNECTION statement must be used to switch to a dormant connection.

Properties:

Default: | NOSQLRULES
Synonym: | RULES.
Parent topic: DB2 Compiler Directive Options


SQLWARN

Indicates whether warnings will be returned from the compilation of dynamic SQL statements (via PREPARE or EXECUTE IMMEDIATE), or from describe processing (via PREPARE...INTO or DESCRIBE). This DB2 precompile/bind option is not supported by DRDA.

Syntax:

SQLWARN={YES | NO}
NOSQLWARN

Parameters:

NO | Warnings will not be returned from the SQL compiler.
YES | Warnings will be returned from the SQL compiler.

Properties:

Default: | NOSQLWARN
Synonym: | WARN.

Comments:

SQLCODE +238 is an exception. It is returned regardless of the sqlwarn option value.

Parent topic: DB2 Compiler Directive Options


STATICREADONLY

Determines whether or not static cursors are treated as READ ONLY.
Note:

This option is not supported by DRDA.

Syntax:

STATICREADONLY={NO | YES}

Parameters:

NO | All static cursors take on the attributes generated based on the statement text and the setting of the LANGLEVEL option.
YES | Static cursors containing neither the FOR UPDATE nor the FOR READ ONLY clause are considered READ ONLY.

Properties:

Default: NO
Parent topic: DB2 Compiler Directive Options


STOPROC

On entering a stored procedure, converts character data on DB2 LUW stored procedure parameters to CHARSET(EBCDIC), and converts it back to CHARSET(ASCII) on exiting the stored procedure.

Syntax:

[NO]STOPROC

Properties:

Default: NOSTOPROC

Limitations:

STOPROC is limited to single-byte character parameters and is intended for use only when the routine cannot be called directly from a COBOL application. We do not recommend using STOPROC in cases where the routine can be called directly from a COBOL application.

Comments:

STOPROC enables DB2 LUW stored procedures to be compiled with CHARSET(EBCDIC) and remain accessible to non-EBCDIC enabled languages such as C# or JAVA. In addition, this directive replaces all parameters defined as COMP variables with COMP format on entry, and with COMP-5 format on exit.

Parent topic: DB2 Compiler Directive Options


STRDEL

Designates whether an apostrophe (') or double quotation marks (") will be used as the string delimiter within SQL statements. This DRDA precompile/bind option is not supported by DB2. The DRDA server will use a system defined default value if this option is not specified.

Syntax:

STRDEL={APOSTROPHE | QUOTE}
NOSTRDEL

Parameters:

APOSTROPHE | Use an apostrophe (') as the string delimiter.
QUOTE | Use double quotation marks (") as the string delimiter.

Properties:

Default: NOSTRDEL
Parent topic: DB2 Compiler Directive Options


SYNCPOINT

Specifies how commits or rollbacks are to be coordinated among multiple database connections.

Syntax:

SYNCPOINT={ONEPHASE | TWOPHASE | NONE}
NOSYNCPOINT

Parameters:

NONE | Specifies that no Transaction Manager (TM) is to be used to perform a two-phase commit, and does not enforce single updater, multiple reader. A COMMIT is sent to each participating database. The application is responsible for recovery if any of the commits fail.
ONEPHASE | Specifies that no TM is to be used to perform a two-phase commit. A one-phase commit is to be used to commit the work done by each database in multiple database transactions.
TWOPHASE | Specifies that the TM is required to coordinate two-phase commits among those databases that support this protocol.

Properties:

Default: NOSYNCPOINT
Parent topic: DB2 Compiler Directive Options


SYNTAX

A synonym for directive SQLERROR=CHECK.

Syntax:

SYNTAX

Properties:

Synonym: SQLERROR=CHECK
Parent topic: DB2 Compiler Directive Options


TEMPORAL-HISTORY

Specifies whether or not changes to data in system-period temporal tables made by static or dynamic SQL statements make changes to the corresponding history table.
Restriction: TEMPORAL-HISTORY is supported by DB2 LUW version 10.5 or later.

Syntax:

TEMPORAL-HISTORY={YES | NO}

Parameters:

YES
A change to data in a system-period temporal table triggers a change to the corresponding history table. This is equivalent to the IBM PRECOMPILE WITH TEMPORAL HISTORY option.
NO
A change to data in a system-period temporal table does not trigger a change to the corresponding history table. This is equivalent to the IBM PRECOMPILE WITHOUT TEMPORAL HISTORY option.
Note: Your DBA can provide values to override the ROW-BEGIN, ROW-END, and TRANSACTION-START-ID columns even when they are defined as GENERATED ALWAYS.

Properties:

Default: TEMPORAL-HISTORY=YES

Comments:

DBADM authority is required to use TEMPORAL-HISTORY. For more information, see the IBM DB2 documentation.

Parent topic: DB2 Compiler Directive Options


TEXT

The description of a package. Maximum length is 255 characters. The default value is blanks. This DRDA precompile/bind option is not supported by DB2.

Syntax:

TEXT=label
NOTEXT

Properties:

Default: NOTEXT
Parent topic: DB2 Compiler Directive Options


TRANSFORM-GROUP

Specifies the transform group name to be used for static SQL. This is a SQL identifier up to 18 characters in length.

Syntax:

TRANSFORM-GROUP=identifier
NOTRANSFORM-GROUP

Properties:

Default: NOTRANSFORM-GROUP
Parent topic: DB2 Compiler Directive Options


UDB-VERSION

Specifies the version of DB2 Database for Linux, UNIX, and Windows (LUW) you want to use.

Syntax:

UDB-VERSION={V6 | V7 | V8 | V9 | V95 | V97 | V10 | V11}

Properties:

Default: DB2 LUW Server Version from connection
Parent topic: DB2 Compiler Directive Options


VALIDATE

Determines when the database manager checks for authorization errors and object not found errors. The package owner authorization ID is used for validity checking.

Syntax:

VALIDATE={RUN | BIND}
NOVALIDATE

Parameters:

BIND | Validation is performed at precompile/bind time. If all objects do not exist, or all authority is not held, error messages are produced. If sqlerror continue is specified, a package/bind file is produced despite the error message, but the statements in error are not executable.
RUN | Validation is attempted at bind time. If all objects exist, and all authority is held, no further checking is performed at execution time. If all objects do not exist, or all authority is not held at precompile/bind time, warning messages are produced, and the package is successfully bound, regardless of the sqlerror continue option setting. However, authority checking and existence checking for SQL statements that failed these checks during the precompile/bind process may be redone at execution time.

Properties:

Default: NOVALIDATE
Parent topic: DB2 Compiler Directive Options


VERSION

Defines the version identifier for a package. The version identifier is any alphanumeric value, $, #, @, _, -, or ., up to 254 characters in length.

Syntax:

VERSION=version-id
NOVERSION

Properties:

Default: NOVERSION
Parent topic: DB2 Compiler Directive Options


XAID

Simplifies working with multiple XARs of the DB2 RM type defined in a single enterprise server region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

XAID=xarid[_s|_S]

Parameters:

xarid
The XAR ID set in the enterprise server region XAR definition.
[_s|_S]
The XA resource will use static registration. If not specified, the XA resource will use the DB2 default of dynamic registration in distributed transactions. In most cases, dynamic registration is more efficient then static registration.

Properties:

Default: None
Parent topic: DB2 Compiler Directive Options


DB2 Environment Variables

  • HCOBND environment variable (deprecated)
    Specifies an alternative directory in which to write DBRM files created during compilation.
Parent topic: DB2


HCOBND environment variable (deprecated)

Specifies an alternative directory in which to write DBRM files created during compilation.

Syntax:

Note: HCOBND is deprecated, and provided for backward compatibility only. We recommend that you use either the BIND or the BINDDIR compiler directive option.
SET HCOBND=path
export HCOBND

Parameter:

path
The full path to the directory where you want to store created DBRM (.bnd) files.

Properties:

Default: None

Comments:

The directory specified by the HCOBND environment variable applies to all DBRM files created by the DB2 ECM unless you override it using the BIND or the BINDDIR compiler directive option. For complete information on DBRM file output options, including how to determine the current output file location, see Binding.

Example:

SET HCOBND=/mydir/binds
export HCOBND
Parent topic: DB2 Environment Variables
Related concepts
Binding
Related reference
BIND
BINDDIR


DB2 ECM Error Messages

  • COBDB0002 - COBDB0013
    Lists the DB2 ECM error messages from COBDB0002 through COBDB0013.
  • COBDB0100 - COBDB0115
    Lists the DB2 ECM error messages from COBDB0100 through COBDB0115.
  • COBDB0116 - COBDB0137
    Lists the DB2 ECM error messages from COBDB0116 through COBDB0137.
  • COBDB0501 - COBDB0503
  • COBDB0900 - COBDB1004
    Lists the DB2 ECM error messages from COBDB0900 through COBDB1004.
Parent topic: DB2
Related information
Data Related


COBDB0002 - COBDB0013

Lists the DB2 ECM error messages from COBDB0002 through COBDB0013.
  • COBDB0002 token is badly defined.
    The preprocessor has encountered a problem with one of the following: SQLCA copybook, SQLCODE field, SQLSTATE field, or MFSQLMESSAGETEXT field.
  • COBDB0003 Program contains more than one definition of field-name
    More than one definition exists for one or more of the following fields: SQLCA, SQLCODE, SQLSTATE or MFSQLMESSAGETEXT.
  • COBDB0004 Nested or multi-source programs not allowed.
    You are trying to compile a program that is nested or multi-source. This is not supported.
  • COBDB0005 An error occurred when processing the internal dictionary.
    A system error has occurred when the preprocessor attempted to create an internal dictionary of all host variables used in the program.
  • COBDB0006 Required DB software token could not be found.
    The required IBM DB2 system software was not installed.
  • COBDB0007 Source file name is invalid.
    A system error has occurred. The source file name passed to the preprocessor is not valid.
  • COBDB0008 MF DB2 Connect program missing or invalid.
    To compile your program, the preprocessor must connect to a DB2 database. The preprocessor uses the Micro Focus DB2 Connect program to do this. The program was not found, was damaged, or is an old version.
  • COBDB0009 MF DB2 Connect program reported error condition token.
    To compile your program, the preprocessor must connect to a DB2 database. The preprocessor uses the Micro Focus DB2 Connect program to do this. An unexpected SQL error was reported when attempting to connect.
  • COBDB0010 DB2 rejected an unspecified option.
    An SQLCODE of -4905 was reported when processing the DB2 compiler directive options specified.
  • COBDB0011 No database name was specified.
    Either you did not specify a database name in your project, or you have not set the DB2DBDFT environment variable to specify a database name.
  • COBDB0012 Functionality only supported in 32-bit mode
    The functionality built into your program or application is supported when running in 32-bit mode only.
  • COBDB0013 Invalid directive token. IBM supports only precompiled code running as native code.
    You have specified the compiler directive to compile a native application, or you have specified DB2 compiler directive options to compile a managed code application. DB2 is supported for native applications only.
Parent topic: DB2 ECM Error Messages


COBDB0002 token is badly defined.

The preprocessor has encountered a problem with one of the following: SQLCA copybook, SQLCODE field, SQLSTATE field, or MFSQLMESSAGETEXT field.

The problem could be one of the following:

  • The SQLCA area was defined with total length less than 136 characters
  • The SQLCODE field was not defined as a S9(8) COMP field
  • The SQLSTATE field was not defined as a character field of length 5
  • The MFSQLMESSAGETEXT field was defined with a length greater than 65535 characters
  • One of the previous fields was defined incorrectly

Resolution:

Correct the definition or use the SQLCA copybook provided with Visual COBOL. If the problem persists, report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0002 - COBDB0013
Related concepts
Creating Debug Files
SQL Communications Area (SQLCA)
The SQLCODE Variable
The SQLSTATE Variable


COBDB0003 Program contains more than one definition of field-name

More than one definition exists for one or more of the following fields: SQLCA, SQLCODE, SQLSTATE or MFSQLMESSAGETEXT.

Resolution:

Remove the duplicate definitions and recompile the program.

Parent topic: COBDB0002 - COBDB0013
Related concepts
SQL Communications Area (SQLCA)
The SQLCODE Variable
The SQLSTATE Variable


COBDB0004 Nested or multi-source programs not allowed.

You are trying to compile a program that is nested or multi-source. This is not supported.

Resolution:

Use Micro Focus Net Express if you want to develop applications using nested or multi-source programs.

Parent topic: COBDB0002 - COBDB0013


COBDB0005 An error occurred when processing the internal dictionary.

A system error has occurred when the preprocessor attempted to create an internal dictionary of all host variables used in the program.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0002 - COBDB0013
Related concepts
Host Variables
Creating Debug Files


COBDB0006 Required DB software token could not be found.

The required IBM DB2 system software was not installed.

Resolution:

Install one of the required DB2 system software products and then either create or catalog the DB2 database and tables against which to compile the program. If the token is:

db2agapi
Either the DB2 software was not installed or the PATH statement might require modification to include the DB2 installation directory.
db2aprep
Check to be sure that the DB2 Application Development Client software is installed.
DB2INSTANCE
Check to be sure that your DB2 environment is configured correctly. For details, see your IBM DB2 documentation on setting up the application development environment.
libdb2
Check to be sure that your DB2 environment is configured correctly. For details, see your IBM DB2 documentation on setting up the application development environment.
Parent topic: COBDB0002 - COBDB0013


COBDB0007 Source file name is invalid.

A system error has occurred. The source file name passed to the preprocessor is not valid.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0002 - COBDB0013
Related concepts
Creating Debug Files


COBDB0008 MF DB2 Connect program missing or invalid.

To compile your program, the preprocessor must connect to a DB2 database. The preprocessor uses the Micro Focus DB2 Connect program to do this. The program was not found, was damaged, or is an old version.

Resolution:

If you have an old Micro Focus COBOL development system installed, uninstall it. In any case, reinstall Visual COBOL to ensure that the appropriate version of DB2 Connect is installed.

Parent topic: COBDB0002 - COBDB0013


COBDB0009 MF DB2 Connect program reported error condition token.

To compile your program, the preprocessor must connect to a DB2 database. The preprocessor uses the Micro Focus DB2 Connect program to do this. An unexpected SQL error was reported when attempting to connect.

Resolution:

token is either an internal error or an SQLCODE return code. See the IBM DB2 Error Reference manual for additional information.

Parent topic: COBDB0002 - COBDB0013
Related concepts
The SQLCODE Variable


COBDB0010 DB2 rejected an unspecified option.

An SQLCODE of -4905 was reported when processing the DB2 compiler directive options specified.

Resolution:

Verify that the compiler directive options specified are valid for the DB2 server that you are compiling the program against. Make any corrections necessary and then recompile the program.

Parent topic: COBDB0002 - COBDB0013
Related concepts
The SQLCODE Variable


COBDB0011 No database name was specified.

Either you did not specify a database name in your project, or you have not set the DB2DBDFT environment variable to specify a database name.

Resolution:

Do one of the following:
  • On the SQL in your :
    • Set the ESQL Preprocessor to DB2
    • Set the DB directive, specifying the name of your DB2 database as its value
  • Set the DB2DBDFT environment variable value to the name of your DB2 database

Then, recompile the program.

Parent topic: COBDB0002 - COBDB0013
Related reference
Environment variables in alphabetical order


COBDB0012 Functionality only supported in 32-bit mode

The functionality built into your program or application is supported when running in 32-bit mode only.

Resolution:

Run the program or application in 32-bit mode.

Parent topic: COBDB0002 - COBDB0013


COBDB0013 Invalid directive token. IBM supports only precompiled code running as native code.

You have specified the compiler directive to compile a native application, or you have specified DB2 compiler directive options to compile a managed code application. DB2 is supported for native applications only.

Resolution:

Recompile using compiler directives appropriate to your application type.

Parent topic: COBDB0002 - COBDB0013


COBDB0100 - COBDB0115

Lists the DB2 ECM error messages from COBDB0100 through COBDB0115.
  • COBDB0100 SQL error description
    The preprocessor encountered an SQL error while compiling your program. The SQL error is displayed following this error message.
  • COBDB0101 Statement is too long.
    The SQL statement passed to the preprocessor is longer than 65,536 characters. In this case, the preprocessor receives a compressed version of the SQL statement rather than the original source.
  • COBDB0102 Statement contains too many host variables.
    The SQL statement contains more than 8000 host and indicator variables.
  • COBDB0103 host-var definition does not match the column type associated with it.
    The host variable data definition does not match the column type associated with it in the SQL statement. For example, you would get this error if you use a host variable defined as PIC X(n) with a column defined as SMALLINT.
  • COBDB0104 Bad SQL data declaration.
    An unexpected SQL declaration was passed to the preprocessor.
  • COBDB0105 Syntax error.
    The SQL statement includes invalid syntax or does not include required information.
  • COBDB0106 Filename too long.
    A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.
  • COBDB0107 File filename not found.
    The copybook specified in filename was not found.
  • COBDB0108 host-var is non-unique and should be qualified.
    The host variable host-var is not unique and requires that you qualify it.
  • COBDB0109 host-var is not a data item.
    The host variable host-var was not defined or was defined incorrectly.
  • COBDB0110 Statement contains more than one SQLDA.
    More than one SQLDA has been used in the SQL statement.
  • COBDB0111 token is not a table of null indicator variables.
    The preprocessor was expecting token to be either a null indicator or a null indicator table.
  • COBDB0112 host-var should not be defined with an OCCURS clause.
    A host variable is defined as part of an OCCURS clause. The preprocessor does support host variables defined this way.
  • COBDB0113 host-var 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 preprocessor does not support host variables defined this way.
  • COBDB0114 Statement only allowed in the Procedure Division.
    The SQL statement in question was not defined in the Procedure Division.
  • COBDB0115 Statement not allowed in the PROCEDURE DIVISION.
    An SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Division. The preprocessor does not support the SQL statement coded into the Procedure Division.
Parent topic: DB2 ECM Error Messages


COBDB0100 SQL error description

The preprocessor encountered an SQL error while compiling your program. The SQL error is displayed following this error message.

Resolution:

See your IBM SQL Error Message manual for information on the SQL error and how to resolve it.

Parent topic: COBDB0100 - COBDB0115


COBDB0101 Statement is too long.

The SQL statement passed to the preprocessor is longer than 65,536 characters. In this case, the preprocessor receives a compressed version of the SQL statement rather than the original source.

Resolution:

Reduce the statement length to less than 65,536 characters. If the SQL statement contains comments or leading and trailing blanks, consider removing these to shorten the statement length. You can also break the SQL statement into multiple statements. Recompile the program after reducing the statement length to less than 65,536 characters.

Parent topic: COBDB0100 - COBDB0115


COBDB0102 Statement contains too many host variables.

The SQL statement contains more than 8000 host and indicator variables.

Resolution:

Look at breaking the SQL statement into multiple SQL statements and then try recompiling the program.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables


COBDB0103 host-var definition does not match the column type associated with it.

The host variable data definition does not match the column type associated with it in the SQL statement. For example, you would get this error if you use a host variable defined as PIC X(n) with a column defined as SMALLINT.

Resolution:

Verify that the host variable definition corresponds appropriately to the column definition and make any changes to correct the error. Alternatively use the Host Compatibility Option DCLGEN tool to generate a copybook of the host variable for the SQL table in question.

If your code contains a multiple-level group name in a FETCH or singleton SELECT, recompile using the GEN-HV-FROM-GROUP DB2 compiler directive option.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables
Related reference
GEN-HV-FROM-GROUP


COBDB0104 Bad SQL data declaration.

An unexpected SQL declaration was passed to the preprocessor.
Generally this error occurs only for host variables defined as:
host-variable-name SQL TYPE IS ....

and the preprocessor has not been set up to handle that definition.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables
Creating Debug Files


COBDB0105 Syntax error.

The SQL statement includes invalid syntax or does not include required information.
For example, this error would be generated if you coded:
EXEC SQL INCLUDE END-EXEC

and did not specify the name of the copybook file to INCLUDE.

Resolution:

Correct the SQL statement and recompile the program.

Parent topic: COBDB0100 - COBDB0115


COBDB0106 Filename too long.

A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.

Resolution:

Correct the filename and recompile the program

Parent topic: COBDB0100 - COBDB0115


COBDB0107 File filename not found.

The copybook specified in filename was not found.

Either the filename is incorrect, or the path containing the file has not been specified on either the SQLCPY or the COBCPY environment variables.

Resolution:

Do one of the following:
  • Correct the filename.
  • Add the path to the copybook to the COBCPY environment variable. You can do this from your project Properties on the COBOL tab, Advanced Options dialog box. Type the appropriate path into the Additional copybook paths field.
Note: The preprocessor looks first in the current directory, and then down the paths specified by the SQLCPY environment variable, and then the COBCPY environment variable.
Parent topic: COBDB0100 - COBDB0115


COBDB0108 host-var is non-unique and should be qualified.

The host variable host-var is not unique and requires that you qualify it.

Resolution:

Fully qualify a host variable in an SQL query. For example if the ORD-NO host variable exists in both the ORDERS and ITEMS copybooks, and you want the host variable from the ORDERS copybook to be used in the query, specify:
:ORDERS.ORD-NO
Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables


COBDB0109 host-var is not a data item.

The host variable host-var was not defined or was defined incorrectly.

Resolution:

Verify that host-var exists. If not, make any changes to correct the error, or use the Host Compatibility Option DCLGEN tool to generate a copybook of the host variable for the SQL table in question.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables


COBDB0110 Statement contains more than one SQLDA.

More than one SQLDA has been used in the SQL statement.

Resolution:

The preprocessor currently limits you to one SQLDA reference in an SQL statement. For example:
EXEC SQL PREPARE DYNSTMT INTO :SQLDA FROM :SQL-STMT END-EXEC

If this becomes an issue, contact SupportLine.

Parent topic: COBDB0100 - COBDB0115


COBDB0111 token is not a table of null indicator variables.

The preprocessor was expecting token to be either a null indicator or a null indicator table.

Resolution:

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 rather than staff-null-tbl in your query.

Parent topic: COBDB0100 - COBDB0115


COBDB0112 host-var should not be defined with an OCCURS clause.

A host variable is defined as part of an OCCURS clause. The preprocessor does support host variables defined this way.

Resolution:

Modify the code such that the host variable is not defined as part of an OCCURS clause; then recompile the program.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables


COBDB0113 host-var 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 preprocessor does not support host variables defined this way.

Resolution:

Modify the code such that the host variable is not defined as part of an OCCURS clause or as part of a structure that includes an OCCURS clause; then recompile the program.

Parent topic: COBDB0100 - COBDB0115
Related concepts
Host Variables


COBDB0114 Statement only allowed in the Procedure Division.

The SQL statement in question was not defined in the Procedure Division.

Resolution:

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: COBDB0100 - COBDB0115


COBDB0115 Statement not allowed in the PROCEDURE DIVISION.

An SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Division. The preprocessor does not support the SQL statement coded into the Procedure Division.

Resolution:

Move the SQL statement into the Working-Storage Section and then recompile the program.

Parent topic: COBDB0100 - COBDB0115


COBDB0116 - COBDB0137

Lists the DB2 ECM error messages from COBDB0116 through COBDB0137.
  • COBDB0116 An error occurred when processing the trace file.
    A file error occurred when attempting to write information to the preprocessor trace file.
  • COBDB0117 Invalid format of compound SQL statement.
    The preprocessor could not process a compound SQL statement.
  • COBDB0118 Mismatched DECLARE.
    More than one DECLARE statement was found within an EXEC SQL statement.
  • COBDB0119 Host variable name is too long.
    The host variable name is too long.
  • COBDB0120 Internal error - dictionary handle is too big.
    The preprocessor creates an internal dictionary of all host variables used in a program. When building the dictionary, a system error occurred.
  • COBDB0121 Package name is too long.
    The package name specified is longer than 128 characters. If you did not specify an explicit package name via the ACCESS DB2 compiler directive option, the preprocessor defaults to using the filename of the program being compiled. If the program name is more than 128 characters, this error message is generated.
  • COBDB0122 Nested INCLUDEs not supported
    The DB2 ECM does not support EXEC SQL INCLUDE statements that expand an EXEC SQL INCLUDE statement.
  • COBDB0127 Parentheses are illegal in the INTO clause.
    A left parenthesis, (, was found in the INTO clause of an SQL statement. The preprocessor does not support parentheses in INTO clauses.
  • COBDB0131 SQLCA or SQLCODE not found.
    An SQLCA or SQLCODE was not found in the Working-Storage Section or Linkage Section.
  • COBDB0137 Indicator variable ind-var is not SMALLINT type.
    The indicator variable data definition does not match the data type associated with it in the SQL statement.
Parent topic: DB2 ECM Error Messages


COBDB0116 An error occurred when processing the trace file.

A file error occurred when attempting to write information to the preprocessor trace file.

Resolution:

Make sure you have write authority directory where the file is being written, and that you have sufficient disk space.

Parent topic: COBDB0116 - COBDB0137


COBDB0117 Invalid format of compound SQL statement.

The preprocessor could not process a compound SQL statement.

Resolution:

Modify the code to correct the invalid compound SQL statement. See the IBM SQL Reference for details.

Note: This condition is non-recoverable; subsequent valid SQL statements could generate spurious errors. Compound SQL statements contain multiple SQL statements that could each generate an error message after this error.
Parent topic: COBDB0116 - COBDB0137


COBDB0118 Mismatched DECLARE.

More than one DECLARE statement was found within an EXEC SQL statement.

Resolution:

Correct the statement and recompile the program.

Parent topic: COBDB0116 - COBDB0137


COBDB0119 Host variable name is too long.

The host variable name is too long.

If you are using a version of DB2 before DB2 LUW V5, the maximum length of the host variable is 30 characters. The preprocessor automatically adds 3 characters to a host variable name to make it unique unless you specify directive DB2(NOQUALFIX) to turn this feature off.

Resolution:

Specify the DB2(NOQUALFIX) compiler directive, and recompile the program. If you still get the error, make sure the host variable is a valid COBOL name of 30 characters or less in length.

Parent topic: COBDB0116 - COBDB0137
Related concepts
Host Variables
Related reference
QUALFIX


COBDB0120 Internal error - dictionary handle is too big.

The preprocessor creates an internal dictionary of all host variables used in a program. When building the dictionary, a system error occurred.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

We also suggest that you be prepared to provide your SupportLine representative with enough information (e.g., program source, etc.) to recreate the error.

Parent topic: COBDB0116 - COBDB0137
Related concepts
Host Variables
Creating Debug Files


COBDB0121 Package name is too long.

The package name specified is longer than 128 characters. If you did not specify an explicit package name via the ACCESS DB2 compiler directive option, the preprocessor defaults to using the filename of the program being compiled. If the program name is more than 128 characters, this error message is generated.

Resolution:

Specify a package name using the DB2(ACCESS=packageName) compiler directive, where packageName is 128 characters or fewer.

Parent topic: COBDB0116 - COBDB0137
Related reference
ACCESS


COBDB0122 Nested INCLUDEs not supported

The DB2 ECM does not support EXEC SQL INCLUDE statements that expand an EXEC SQL INCLUDE statement.

Resolution:

Remove EXEC SQL INCLUDE statements that expand an EXEC SQL INCLUDE statement; then recompile the program.

Parent topic: COBDB0116 - COBDB0137


COBDB0127 Parentheses are illegal in the INTO clause.

A left parenthesis, (, was found in the INTO clause of an SQL statement. The preprocessor does not support parentheses in INTO clauses.

Resolution:

Correct the syntax and recompile your program. See the IBM SQL Reference for the correct syntax.

Parent topic: COBDB0116 - COBDB0137


COBDB0131 SQLCA or SQLCODE not found.

An SQLCA or SQLCODE was not found in the Working-Storage Section or Linkage Section.

Resolution:

Check to see if an SQLCA is included and declared correctly.

Parent topic: COBDB0116 - COBDB0137
Related concepts
SQL Communications Area (SQLCA)
The SQLCODE Variable


COBDB0137 Indicator variable ind-var is not SMALLINT type.

The indicator variable data definition does not match the data type associated with it in the SQL statement.

Resolution:

Correct the picture clause for the indicator variable identified in the error message and recompile the program. For example, define your indicator variable as PIC X(n) rather than PIC S9(04) COMP.

Parent topic: COBDB0116 - COBDB0137
Related concepts
Indicator Variables


COBDB0501 - COBDB0503

  • COBDB0501 Found variable expected END-EXEC in nested include.
    The preprocessor found the variable cited, but expected to find an END-EXEC token within the nested EXEC SQL INCLUDE copybook; the END-EXEC token was not found.
  • COBDB0502 Found variable expected INCLUDE in nested EXEC SQL statement.
    The preprocessor found the variable cited, but expected to find an INCLUDE token within the nested EXEC SQL INCLUDE copybook; the INCLUDE token was not found.
  • COBDB0503 Found variable expected SQL in nested EXEC statement.
    Following an EXEC token, the preprocessor found the variable cited.
Parent topic: DB2 ECM Error Messages


COBDB0501 Found variable expected END-EXEC in nested include.

The preprocessor found the variable cited, but expected to find an END-EXEC token within the nested EXEC SQL INCLUDE copybook; the END-EXEC token was not found.

Resolution:

All EXEC SQL statements in an EXEC SQL INCLUDE copybook must be terminated by an END-EXEC. Correct the copybook code and compile again.

Parent topic: COBDB0501 - COBDB0503


COBDB0502 Found variable expected INCLUDE in nested EXEC SQL statement.

The preprocessor found the variable cited, but expected to find an INCLUDE token within the nested EXEC SQL INCLUDE copybook; the INCLUDE token was not found.

Resolution:

Correct the EXEC SQL statement contained in the copybook and compile again.

Parent topic: COBDB0501 - COBDB0503


COBDB0503 Found variable expected SQL in nested EXEC statement.

Following an EXEC token, the preprocessor found the variable cited.

Resolution:

Only EXEC SQL statements can be coded within a NESTED EXEC SQL copybook. Correct the copybook code and compile again.

Parent topic: COBDB0501 - COBDB0503


COBDB0900 - COBDB1004

Lists the DB2 ECM error messages from COBDB0900 through COBDB1004.
  • COBDB0900 An internal error occurred.
    An unexpected error occurred in the preprocessor.
  • COBDB0901 SQL processing cannot continue.
    A severe SQL error has occurred. Any subsequent EXEC SQL statements are not processed by the preprocessor.
  • COBDB1000 Use of EXEC SQL INCLUDE SQLCA END-EXEC.
    A warning that certifies the preprocessor as ANSI compliant.
  • COBDB1001 MF DB2 Connect program produced the warning token.
    While precompiling the program, the Micro Focus DB2 Connect software returned a warning token when attempting to connect to the DB2 server specified in the DB2(DB) directive.
  • COBDB1002 Statement is not in area B.
    An EXEC SQL statement starts before column 12.
  • COBDB1004 INVALID SQL STATEMENT - statement ignored.
    The program was compiled with the DB2(GEN-SQLCA) directive, but includes an EXEC SQL INCLUDE SQLCA statement.
Parent topic: DB2 ECM Error Messages


COBDB0900 An internal error occurred.

An unexpected error occurred in the preprocessor.

Resolution:

Create a trace file using the CHKECM(TRACE) compiler directive, and contact SupportLine. See Creating Debug Files for additional details on how to create a trace file.

Parent topic: COBDB0900 - COBDB1004
Related concepts
Creating Debug Files


COBDB0901 SQL processing cannot continue.

A severe SQL error has occurred. Any subsequent EXEC SQL statements are not processed by the preprocessor.

Resolution:

Report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0900 - COBDB1004
Related concepts
Creating Debug Files


COBDB1000 Use of EXEC SQL INCLUDE SQLCA END-EXEC.

A warning that certifies the preprocessor as ANSI compliant.

Resolution:

On the COBOL tab in your Project Properties, set the Warning level to Severe errors only (Level S).

Parent topic: COBDB0900 - COBDB1004
Related concepts
SQL Communications Area (SQLCA)


COBDB1001 MF DB2 Connect program produced the warning token.

While precompiling the program, the Micro Focus DB2 Connect software returned a warning token when attempting to connect to the DB2 server specified in the DB2(DB) directive.

Resolution:

Verify that your DB2 software is installed correctly and that you can connect to the DB2 server specified. If the problem persists, report this error to SupportLine. We suggest that you have trace files available to help SupportLine to resolve this problem. See Creating Debug Files for details on how to create these trace files.

Parent topic: COBDB0900 - COBDB1004
Related concepts
Creating Debug Files


COBDB1002 Statement is not in area B.

An EXEC SQL statement starts before column 12.

Resolution:

Move the EXEC SQL statement so that it starts after column 12.

Parent topic: COBDB0900 - COBDB1004


COBDB1004 INVALID SQL STATEMENT - statement ignored.

The program was compiled with the DB2(GEN-SQLCA) directive, but includes an EXEC SQL INCLUDE SQLCA statement.

Resolution:

Compile the program without the DB2(GEN-SQLCA) directive or remove the EXEC SQL INCLUDE SQLCA statement.

Parent topic: COBDB0900 - COBDB1004
Related concepts
SQL Communications Area (SQLCA)
Related reference
GEN-SQLCA


COBSQL

  • PREPROCESS(cobsql)
    Describes the use of the PREPROCESS compiler directive with the (cobsql) option, used to compile COBSQL programs and applications.
  • COBOL Directives
  • COBSQL Compiler Directive Options
  • COBSQL Messages
Parent topic: Reference


PREPROCESS(cobsql)

Describes the use of the PREPROCESS compiler directive with the (cobsql) option, used to compile COBSQL programs and applications.

Syntax

cob -C "{preprocess | p}(cobsql) [[[{cobsqltype|csqlt}==preCompiler] [COBSQLopts] {end-cobsql|end-c|end}] [PreCompilerOpts endp]]"

Parameters

preCompiler
The name of a third-party database precompiler. Default is oracle8. See COBSQLTYPE, CSQL for a full list of valid values.
COBSQLopts
COBSQL compiler directive options. See COBSQL Compiler Directive Options for complete information on each option.
end-cobsql|end-c|end
Signals the end of COBSQL options.
PreCompilerOpts
Third-party precompiler directive options.
endp
Signals the end of options specified for the PREPROCESS directive.

Comments

cobsql must be in lower case.

end-c and endp have the following effect:

  • Directives placed before end-c pass to COBSQL.
  • Directives placed between end-c and endp pass via COBSQL to the third-party precompiler.
  • Directives placed after endp pass to the COBOL compiler.
    Warning: Be careful not to omit the endp before adding COBOL compiler directives. COBSQL continues to process directives until it reaches endp; therefore, if you omit it, your COBOL directives are processed by COBSQL instead of the COBOL compiler.

Examples

Oracle
cob –k testprog.pco –C "p(cobsql) csqlt==ora makesyn end-c xref==yes mode==ansi endp ans85"

The COBSQL directives, terminated by end-c, are csqlt==ora and makesyn. The precompiler directives (in this case, Pro*COBOL), terminated by endp, are xref==yes and mode==ansi. The COBOL compiler directive is ans85.

cob -k sample.pco anim "preprocess(cobsql) csqlt==ora end-c comp5==yes endp"

The COBOL compiler directive specified is anim. The COBSQL directive, initiated by preprocess(cobsql) and terminated by end-c, is csqlt==ora. The precompiler directive (in this case, Pro*COBOL), terminated by endp, is comp5==yes.

Parent topic: COBSQL
Related concepts
Setting the COBSQL Preprocessor and Compiler Directive Options
Related reference
COBSQL Compiler Directive Options
COBSQLTYPE, CSQLT
END-COBSQL, END-C, END


COBOL Directives

The following are COBOL directives that the Compiler also passes to COBSQL regardless of their position in a command line relative to PREPROCESS(cobsql):
Directive | Description
[NO]BELL | Controls whether COBSQL sounds the bell when an error occurs.
[NO]BRIEF | Controls whether COBSQL shows SQL error text as well as the error number.
[NO]CONFIRM | Displays accepted/rejected COBSQL directives.
[NO]LIST | Saves the precompiler listing file (.lis).
[NO]WARNING | Determines the lowest severity of SQL errors to report.

For complete information on each of these directives, see Compiler Directives.

Parent topic: COBSQL
Related concepts
Setting the COBSQL Preprocessor and Compiler Directive Options
Related reference
BELL
BRIEF
CONFIRM
LIST
WARNING, WARNINGS
Compiler Directives
COBSQL Compiler Directive Options


COBSQL Compiler Directive Options

  • COBSQLTYPE, CSQLT
    Specifies which precompiler to use.
  • CSTART, CST
    Forces COBSQL to load the database support modules at execution time.
  • CSTOP, CSP
    Forces COBSQL to load the stop run module that performs a rollback if the application terminates abnormally
  • DEBUGFILE, DEB
    Creates a debug (.deb) file.
  • DISPLAY, DIS
    Displays precompiler statistics. Should only be used when initially verifying that COBSQL is correctly calling the standalone precompiler.
  • END-COBSQL, END-C, END
    Signals the end of COBSQL directives; remaining directives, if any, are passed to the precompiler
  • HSFTRACE
    Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.
  • KEEPCBL
    Saves the precompiled source (.cbl) file.
  • KEEPCOMP
    Maintains all COMP variables as COMP when the Oracle Pro*COBOL COMP5=yes directive is specified.
  • MAKESYN
    When specified, all COMP and COMP-4 variables inside a DECLARE SECTION are converted to COMP-5. When NOMAKESYN is specified, no conversions are made. If neither MAKESYN nor NOMAKESYN is set (the default), all variables in Working-Storage defined as COMP or COMP-4 are converted to COMP-5.
  • SQLDEBUG
    Creates a number of files that we can use to debug COBSQL. These files include the output file from the precompiler (normally this has the extension .cbl), the listing file produced by the precompiler (this has the extension .lis), plus a COBSQL debug file which has the extension .sdb.
  • STOPCHK
    Stops compilation when the preprocessor encounters an EXEC SQL statement error, and sends the Pro*Cobol error text to the console display.
  • TRACE
    Creates a trace file.
  • VERBOSE
    Displays all precompiler messages and gives status updates as the program is processed. You should only use this when initially verifying that COBSQL is calling the standalone precompiler correctly.
  • XAID
    Simplifies working with multiple XARs of the Oracle RM type defined in a single enterprise server region.
Parent topic: COBSQL
Related concepts
Setting the COBSQL Preprocessor and Compiler Directive Options
Related reference
COBOL Directives
PREPROCESS(cobsql)


COBSQLTYPE, CSQLT

Specifies which precompiler to use.

Syntax:

{COBSQLTYPE|CSQLT}={ORACLE|ORACLE8|SYBASE|INFORMIX-NEW}

Properties:

Default: COBSQLTYPE=ORACLE8

Comments:

Both the ORACLE and ORACLE8 parameters set the COBSQL precompiler to Oracle 8, given that Oracle no longer supports versions earlier than 8.

Parent topic: COBSQL Compiler Directive Options
Related reference
PREPROCESS(cobsql)


CSTART, CST

Forces COBSQL to load the database support modules at execution time.

Syntax:

[NO]{CSTART|CST}

Properties:

Default: NOCSTART

Comments:

This directive is not available on UNIX.

Parent topic: COBSQL Compiler Directive Options


CSTOP, CSP

Forces COBSQL to load the stop run module that performs a rollback if the application terminates abnormally

Syntax:

[NO]{CSTOP|CSP}

Properties:

Default: NOCSTOP

Comments:

This directive is not available on UNIX. However, you can emulate the CSTOP functionality by installing a closedown procedure that performs an EXEC SQL ROLLBACK. Here is an example of the call to the library routine CBL_EXIT_PROC:

 working-storage section.

 EXEC SQL INCLUDE SQLCA END-EXEC.

 EXEC SQL BEGIN DECLARE SECTION END-EXEC.
 01 DUMMY                    PIC x.
 EXEC SQL END DECLARE SECTION END-EXEC.

 78  func-install        value 0.
 78  func-deinstall      value 1.
 78  Initial-Call        value 9.
 01.
     03  install-flag        pic x comp-x value Initial-Call.
     03  install-params.
         05  install-addrs   procedure-pointer.
         05  install-prrty   pic x comp-x value 64.

 procedure division.
     if install-flag = Initial-Call
        set  install-addrs to entry "myexitpc"
        move func-install  to install-flag
        call "CBL_EXIT_PROC" using install-flag install-params
        end-call
     end-if
Parent topic: COBSQL Compiler Directive Options


DEBUGFILE, DEB

Creates a debug (.deb) file.

Syntax:

[NO]{DEBUGFILE|DEB}

Properties:

Default: NODEBUGFILE

Comments:

Saves the (.deb) file to the current directory.

Parent topic: COBSQL Compiler Directive Options


DISPLAY, DIS

Displays precompiler statistics. Should only be used when initially verifying that COBSQL is correctly calling the standalone precompiler.

Syntax:

[NO]{DISPLAY|DIS}

Properties:

Default: NODISPLAY
Parent topic: COBSQL Compiler Directive Options


END-COBSQL, END-C, END

Signals the end of COBSQL directives; remaining directives, if any, are passed to the precompiler

Syntax:

{END-COBSQL|END-C|END}

Properties:

Default: None
Parent topic: COBSQL Compiler Directive Options
Related reference
PREPROCESS(cobsql)


HSFTRACE

Generates calls around each SQL statement to the HSF trace routine. In some cases, the application must be linked with mfsqlSMF.lib.

Syntax:

[NO]HSFTRACE

Properties:

Default: HSFTRACE

Scope:

Used at compile time: | Yes
Behavior at run time: | N/A

Comments:

SMFTRACE is an alias for HSFTRACE.

Parent topic: COBSQL Compiler Directive Options


KEEPCBL

Saves the precompiled source (.cbl) file.

Syntax:

KEEPCBL

Properties:

Default: None

Dependencies:

Automatically set by SQLDEBUG.

Comments:

Saves the (.cbl) file to the current directory.

Parent topic: COBSQL Compiler Directive Options
Related reference
SQLDEBUG


KEEPCOMP

Maintains all COMP variables as COMP when the Oracle Pro*COBOL COMP5=yes directive is specified.

Syntax:

[NO]KEEPCOMP

Properties:

Default: NOKEEPCOMP

Dependencies:

When both KEEPCOMP and MAKESYN are specified, MAKESYN is ignored.

Comments:

A Pro*COBOL program or application compiled using KEEPCOMP does not require that COMP and COMP-5 data items be separate in the code. KEEPCOMP enables Oracle applications to run unchanged on little-endian platforms that use both COMP and COMP-5 data items.

Parent topic: COBSQL Compiler Directive Options
Related reference
MAKESYN


MAKESYN

When specified, all COMP and COMP-4 variables inside a DECLARE SECTION are converted to COMP-5. When NOMAKESYN is specified, no conversions are made. If neither MAKESYN nor NOMAKESYN is set (the default), all variables in Working-Storage defined as COMP or COMP-4 are converted to COMP-5.

Syntax:

[NO]MAKESYN

Properties:

Default: None. When not specified, all variables in Working-Storage defined as COMP or COMP-4 are converted to COMP-5.

Dependencies:

When the KEEPCOMP directive is specified, it overrides MAKESYN, NOMAKESYN, and the default behavior when neither MAKESYN nor NOMAKESYN are specified.

Parent topic: COBSQL Compiler Directive Options
Related reference
KEEPCOMP


SQLDEBUG

Creates a number of files that we can use to debug COBSQL. These files include the output file from the precompiler (normally this has the extension .cbl), the listing file produced by the precompiler (this has the extension .lis), plus a COBSQL debug file which has the extension .sdb.

Syntax:

SQLDEBUG

Properties:

Default: | None
Synonym: | SQLDEBUG

Dependencies:

SQLDEBUG automatically sets KEEPCBL and TRACE.

Comments:

Writes all output files to the current directory.

Parent topic: COBSQL Compiler Directive Options
Related reference
KEEPCBL
TRACE


STOPCHK

Stops compilation when the preprocessor encounters an EXEC SQL statement error, and sends the Pro*Cobol error text to the console display.
Restriction: This topic applies to Oracle only.

Syntax:

[NO]STOPCHK

Properties:

Default: NOSTOPCHK

Comment:

NOSTOPCHK continues compilation when the preprocessor encounters an EXEC SQL statement error, and sends the Pro*Cobol error and all subsequently detected errors to the checker for proper error handling.

Parent topic: COBSQL Compiler Directive Options


TRACE

Creates a trace file.

Syntax:

[NO]TRACE

Properties:

Default: NOTRACE

Dependencies:

Automatically set by SQLDEBUG.

Comments:

Creates a trace (.trc) file in the current directory.

Parent topic: COBSQL Compiler Directive Options
Related reference
SQLDEBUG


VERBOSE

Displays all precompiler messages and gives status updates as the program is processed. You should only use this when initially verifying that COBSQL is calling the standalone precompiler correctly.

Syntax:

VERBOSE

Properties:

Default: None
Parent topic: COBSQL Compiler Directive Options


XAID

Simplifies working with multiple XARs of the Oracle RM type defined in a single enterprise server region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

XAID={*|xarid}

Parameters:

*
Set XAID=* when the xa_open string in your XAR definition does not specify the DB parameter
xarid
The XAR ID set in the enterprise server region. Set XAID=xarid when the xa_open string in your XAR definition specifies the DB parameter.

Properties:

Default: None
Parent topic: COBSQL Compiler Directive Options


COBSQL Messages

COBSQL displays four different types of message. These are as follows:

  • Banner Information

    As COBSQL starts, it displays three banner lines which include the COBSQL version number.

  • Precompiler Information

    The database precompilers produce information about the program that they are compiling. If the COBSQL "Verbose" or "Display" directives are used, then COBSQL will display this information.

  • Precompiler Errors

    All the database precompilers produce error messages. These messages range from those that are displayed for information only to those describing fatal errors. COBSQL attempts to identify the severity of the errors passed to it by the precompiler. It also extracts the precompiler error number and text and attempts to locate the source line on which the error occurred. The format of precompiler error messages is as follows:

    precompiler-error-no. severity precompiler-error-text

    The precompiler error message is passed to the COBOL Compiler after the source line that the error occurred on, allowing the COBOL Compiler to identify the source line that the error occurred on.

    If COBSQL cannot determine the severity of the error passed by the precompiler, it will assume that it is a normal error, rather than a fatal error.

  • COBSQL Errors

    COBSQL itself produces four types of message: information only, warning, error or fatal. Most are fatal. The format of COBSQL errors is as follows:

    * CSQL-severity-errorno.: error- text

  • CSQL-I-001 to CSQL-E-023
    Lists the COBSQL messages from CSQL-I-001 through CSQL-E-023.
  • CSQL-E-024 to CSQL-F-050
    Lists the COBSQL messages from CSQL-E-024 through CSQL-F-050.
Parent topic: COBSQL


CSQL-I-001 to CSQL-E-023

Lists the COBSQL messages from CSQL-I-001 through CSQL-E-023.
  • CSQL-I-001: COBSQL has finished returning to the Checker
    This message is for information only. COBSQL has successfully processed the source file and has passed all the necessary information back to the COBOL Compiler. The program can now be animated or executed.
  • CSQL-I-003: COBSQLTYPE is incorrect defaulting to Oracle
    This message is for information only. COBSQL defaults to using the Oracle precompiler if the COBSQLTYPE directive is not set, is set incorrectly, or is set to an obsolete value.
  • CSQL-I-004: Accepted COBSQL-directive
    COBSQL displays this message to confirm that a directive is valid.
  • CSQL-I-005: Passing precompiler-directive
    COBSQL has encountered directives after the END-COBSQL directive. These directives are for the database precompiler and COBSQL will pass them on. This message is only displayed if the CONFIRM directive is set.
  • CSQL-I-006: Rejected COBSQL-directive
    COBSQL has encountered an invalid directive. Either the directive is incorrect or the value supplied for the directive is incorrect.
  • CSQL-F-007: COBSQL/Checker incompatible -- Terminating
    When COBSQL has to interact with other COBOL Integrated Preprocessors (for example, CP or HTMLPP), it needs to make sure that the subordinate preprocessor(s) are using the same line buffer size as COBSQL. If they are not, this error message is generated.
  • CSQL-I-008: Invoking integrated-preprocessor Preprocessor
    This message is displayed when other Integrated Preprocessors are to be invoked. It is for information only.
  • CSQL-F-009: Irrecoverable error in integrated-preprocessor -- Terminating
    The Integrated Preprocessor that COBSQL invoked has returned a fatal error message. COBSQL passes this message to the COBOL Compiler and aborts.
  • CSQL-F-010: Irrecoverable error writing STK record
    In a stacked environment (for example when COBSQL invokes another Integrated Preprocessor such as CP), COBSQL stores information returned from the other Integrated Preprocessor in a side file that has an extension of STK. The file has the same basename as the input file.
  • CSQL-F-011: Environment unsupported by COBSQL/Informix
    COBSQL is being run with a version of COBOL for which, to the best of our knowledge, no Informix COBOL precompiler is available. This message is also displayed if the wrong Informix COBSQLTYPE is specified for the COBOL release that COBSQL is running with.
  • CSQL-F-012: INFORMIXDIR must be set for Informix Support
    To be able to use the Informix Precompiler, the environment variable INFORMIXDIR must be set. COBSQL uses the value of the INFORMIXDIR environment variable to locate the ESQL/COBOL precompiler.
  • CSQL-F-013: Unable to access: filename
    This error can occur when COBSQL tries to open the source code file, or tries to process a copy statement in the expanded code.
  • CSQL-F-015: DOS Exec error Return Code is return-code
    COBSQL has attempted to invoke the database precompiler and has been unsuccessful. There are a number of possible reasons for this.
  • CSQL-F-016: UNIX Exec error Return Code is Return-Code
    This message is displayed when running under UNIX. On UNIX this is not a fatal error. If a database precompiler came across errors in the source file, it is likely it would produce a non-zero return code. Because this might happen, COBSQL will continue after displaying this message.
  • CSQL-I-017: Creating filename
    COBSQL displays this message, for information only, when the expanded source file is to be kept.
  • CSQL-I-018: Invoking precompiler Precompiler/Translator
    COBSQL displays this message, for information only, to let the user know which database precompiler is about to be called.
  • CSQL-F-019: Irrecoverable error Opening STK file
    COBSQL has attempted to open the STK side file. This file is only used when COBSQL is stacked with other Integrated Precompilers.
  • CSQL-I-020: Processing output of precompiler Precompiler
    COBSQL displays this message once it has successfully called the database precompiler and is about to start processing the expanded code.
  • CSQL-F-021: Precompiler did not complete -- Terminating
    After calling the database precompiler COBSQL checks to make sure that it completed. It does this by trying to open the files that the precompiler should have produced. If it cannot open the files, it reports this error.
  • CSQL-F-022: Irrecoverable error Reopening ORG file
    As part of the processing performed after the database precompiler has completed, COBSQL reopens the original source code file. If COBSQL cannot open the file, it displays this error message.
  • CSQL-E-023: File Status file-status
    COBSQL displays this error message after a file operation has failed. This message is normally preceded by another COBSQL error message identifying the file in error.
Parent topic: COBSQL Messages


CSQL-I-001: COBSQL has finished returning to the Checker

This message is for information only. COBSQL has successfully processed the source file and has passed all the necessary information back to the COBOL Compiler. The program can now be animated or executed.

If any errors have been found, these will be highlighted in the source and the error text will be made available.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-003: COBSQLTYPE is incorrect defaulting to Oracle

This message is for information only. COBSQL defaults to using the Oracle precompiler if the COBSQLTYPE directive is not set, is set incorrectly, or is set to an obsolete value.

This message is displayed if the last COBSQLTYPE directive has an incorrect value.

COBSQL attempts to invoke the Oracle precompiler. This will cause further errors if the Oracle precompiler is not present.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-004: Accepted COBSQL-directive

COBSQL displays this message to confirm that a directive is valid.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-005: Passing precompiler-directive

COBSQL has encountered directives after the END-COBSQL directive. These directives are for the database precompiler and COBSQL will pass them on. This message is only displayed if the CONFIRM directive is set.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-006: Rejected COBSQL-directive

COBSQL has encountered an invalid directive. Either the directive is incorrect or the value supplied for the directive is incorrect.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-007: COBSQL/Checker incompatible -- Terminating

When COBSQL has to interact with other COBOL Integrated Preprocessors (for example, CP or HTMLPP), it needs to make sure that the subordinate preprocessor(s) are using the same line buffer size as COBSQL. If they are not, this error message is generated.

Under normal execution, this message should not appear. If it does, it indicates that an old version of COBSQL is being used with a new Integrated Preprocessor, or vice versa.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-008: Invoking integrated-preprocessor Preprocessor

This message is displayed when other Integrated Preprocessors are to be invoked. It is for information only.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-009: Irrecoverable error in integrated-preprocessor -- Terminating

The Integrated Preprocessor that COBSQL invoked has returned a fatal error message. COBSQL passes this message to the COBOL Compiler and aborts.

For more information about what might have caused the other Integrated Preprocessor to abort, refer to its documentation.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-010: Irrecoverable error writing STK record

In a stacked environment (for example when COBSQL invokes another Integrated Preprocessor such as CP), COBSQL stores information returned from the other Integrated Preprocessor in a side file that has an extension of STK. The file has the same basename as the input file.

This message is displayed if COBSQL receives a COBOL error while trying to write out a record to the STK side file. COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-011: Environment unsupported by COBSQL/Informix

COBSQL is being run with a version of COBOL for which, to the best of our knowledge, no Informix COBOL precompiler is available. This message is also displayed if the wrong Informix COBSQLTYPE is specified for the COBOL release that COBSQL is running with.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-012: INFORMIXDIR must be set for Informix Support

To be able to use the Informix Precompiler, the environment variable INFORMIXDIR must be set. COBSQL uses the value of the INFORMIXDIR environment variable to locate the ESQL/COBOL precompiler.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-013: Unable to access: filename

This error can occur when COBSQL tries to open the source code file, or tries to process a copy statement in the expanded code.

COBSQL attempts to open the source file before it invokes the database precompiler. If it cannot open the file, it will report this error.

This error may also be displayed if COBSQL cannot open a copybook that appears in the expanded source code. COBSQL needs to process copy statements that are inserted by the database precompiler. If COBSQL did not do this, the COBOL Compiler would treat the copy statement as though it appeared in the original source, and expand it.

Once COBSQL has displayed this error, it will also display error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-015: DOS Exec error Return Code is return-code

COBSQL has attempted to invoke the database precompiler and has been unsuccessful. There are a number of possible reasons for this.

You should check the following:

  • Has the database precompiler been installed?
  • Can the database precompiler be run on this machine/OS?
  • Is the database precompiler on the PATH?
  • Is there enough memory to execute the database precompiler?
  • Has COBSQLTYPE been set correctly?
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-016: UNIX Exec error Return Code is Return-Code

This message is displayed when running under UNIX. On UNIX this is not a fatal error. If a database precompiler came across errors in the source file, it is likely it would produce a non-zero return code. Because this might happen, COBSQL will continue after displaying this message.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-017: Creating filename

COBSQL displays this message, for information only, when the expanded source file is to be kept.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-018: Invoking precompiler Precompiler/Translator

COBSQL displays this message, for information only, to let the user know which database precompiler is about to be called.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-019: Irrecoverable error Opening STK file

COBSQL has attempted to open the STK side file. This file is only used when COBSQL is stacked with other Integrated Precompilers.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-I-020: Processing output of precompiler Precompiler

COBSQL displays this message once it has successfully called the database precompiler and is about to start processing the expanded code.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-021: Precompiler did not complete -- Terminating

After calling the database precompiler COBSQL checks to make sure that it completed. It does this by trying to open the files that the precompiler should have produced. If it cannot open the files, it reports this error.

If this message is displayed and the precompiler has created both a listing file and the expanded source code, then either COBSQL does not have read permissions on the files, or they have been created in the wrong directory. Ensure that the current directory is set correctly before running COBSQL.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-F-022: Irrecoverable error Reopening ORG file

As part of the processing performed after the database precompiler has completed, COBSQL reopens the original source code file. If COBSQL cannot open the file, it displays this error message.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-E-023: File Status file-status

COBSQL displays this error message after a file operation has failed. This message is normally preceded by another COBSQL error message identifying the file in error.
Parent topic: CSQL-I-001 to CSQL-E-023


CSQL-E-024 to CSQL-F-050

Lists the COBSQL messages from CSQL-E-024 through CSQL-F-050.
  • CSQL-E-024: Encountered an I/O on file filename
    This message is displayed when a write error occurs on either the trace or the debug file.
  • CSQL-F-025: Unable to Create virtual-heap
    To process the source file and the expanded code, COBSQL needs to create a number of virtual heaps. If there is a problem when COBSQL tries to create a heap, this message is displayed indicating which heap COBSQL had problems creating.
  • CSQL-F-026: Premature end of expanded source. Check for precompiler abort when run standalone. This error is unrecoverable. Hit any key to abort Source Lines could not be matched by COBSQL. COBSQL was processing: area-of-code Source lines around line in error are lines-of source-code
  • CSQL-I-027: Detected Working Section, now processing it
    This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Working Storage Section and is about to process it.
  • CSQL-I-028: Now processing through Procedure Division
    This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Procedure Division and is about to process it.
  • CSQL-I-029: Found an EXEC SQL Statement, processing it
    This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered an EXEC SQL statement within the procedure division of a program and is about to process it.
  • CSQL-E-036: Unable to open the precompiler file: filename
    As part of the processing performed after the database precompiler has completed, COBSQL opens the expanded source code file. If COBSQL cannot open the file, it displays this message.
  • CSQL-F-037: Wrong Version of COBOL used, please upgrade
    COBSQL is being run with an old version of COBOL and will not work correctly. Because of this, COBSQL terminates rather than trying to continue.
  • CSQL-I-038: The following directive is now Obsolete: COBSQL-directive
    COBSQL has encountered a directive that is now marked as obsolete.
  • CSQL-I-039: The ORG & the CBL files were out of synch
    COBSQL sometimes tries to re-position itself when working through the original source file (ORG) and the source produced by the database precompiler (CBL). It does this by scanning ahead in the CBL file to try to find a matching line. If it does, it displays this message.
  • CSQL-W-040: Pro*COBOL commented out the following line: source-line
    Pro*COBOL has commented out a line of code that was not a part of an EXEC SQL statement. This may alter the way that the program executes and care should be taken if the application is run.
  • CSQL-F-041: Cannot read the COBOL runtime switches
    COBSQL tries to determine how the current run-time is configured by examining the settings of the run-time switches. This error is displayed if COBSQL cannot read the current settings.
  • CSQL-F-042: Cannot set the COBOL runtime switches
    Some external code generators produce COBOL code which contains null characters. COBSQL reads the settings of the run-time switches and attempts to change the settings of the relevant switches in order to enable it to read code containing null characters.
  • CSQL-F-046: Command line is too large. Maximum length is 1140 characters
    Your command line length has exceeded the 1140-character limit.
  • CSQL-F-047: Cobsql cannot be used with the SOURCEFORMAT directive.
    You have specified the SOURCEFORMAT(FIXED) directive along with one or more other SOURCEFORMAT directives. With the exception of Pro*COBOL, COBSQL supports the SOURCEFORMAT(FIXED) directive only when no other SOURCEFORMAT directives are specified. If you are using Pro*COBOL, you can also use SOURCEFORMAT(TERMINAL) and SOURCEFORMAT(VARIABLE).
  • CSQL-F-048: Cobsql is not supported for use with managed code.
    You have attempted to compile a managed code application using COBSQL.
Parent topic: COBSQL Messages


CSQL-E-024: Encountered an I/O on file filename

This message is displayed when a write error occurs on either the trace or the debug file.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-025: Unable to Create virtual-heap

To process the source file and the expanded code, COBSQL needs to create a number of virtual heaps. If there is a problem when COBSQL tries to create a heap, this message is displayed indicating which heap COBSQL had problems creating.

The most likely cause of this problem is that not enough memory is available or that too many virtual heaps have already been created. The solution is to close down some COBOL applications to free up memory or virtual file slots.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-026: Premature end of expanded source. Check for precompiler abort when run standalone. This error is unrecoverable. Hit any key to abort Source Lines could not be matched by COBSQL. COBSQL was processing: area-of-code Source lines around line in error are lines-of source-code

  1. The precompiler could not complete the creation of the expanded source code.
  2. COBSQL found a mismatch between a line in the original source code and the expanded source code.

Of these two options, number two is the more likely.

The item area-of-code corresponds to the position within the original source code that COBSQL was processing. These areas include Working-Storage, Procedure Division and SQL statements.

The item lines-of source-code identifies the original source code lines that COBSQL was processing. These are displayed as they can indicate where the problem lies in the original source code.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-I-027: Detected Working Section, now processing it

This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Working Storage Section and is about to process it.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-I-028: Now processing through Procedure Division

This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Procedure Division and is about to process it.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-I-029: Found an EXEC SQL Statement, processing it

This message is displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered an EXEC SQL statement within the procedure division of a program and is about to process it.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-E-036: Unable to open the precompiler file: filename

As part of the processing performed after the database precompiler has completed, COBSQL opens the expanded source code file. If COBSQL cannot open the file, it displays this message.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-037: Wrong Version of COBOL used, please upgrade

COBSQL is being run with an old version of COBOL and will not work correctly. Because of this, COBSQL terminates rather than trying to continue.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-I-038: The following directive is now Obsolete: COBSQL-directive

COBSQL has encountered a directive that is now marked as obsolete.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-I-039: The ORG & the CBL files were out of synch

COBSQL sometimes tries to re-position itself when working through the original source file (ORG) and the source produced by the database precompiler (CBL). It does this by scanning ahead in the CBL file to try to find a matching line. If it does, it displays this message.

The usual reason for a mismatch between the two source files is that the precompiler has produced code that COBSQL is not able to cope with. Until COBSQL is altered to cope with this, using the SQLDEBUG directive provides a temporary work-around.

The code produced when this message has been displayed may not function correctly because some of the original source may have been removed so that COBSQL can re-position itself.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-W-040: Pro*COBOL commented out the following line: source-line

Pro*COBOL has commented out a line of code that was not a part of an EXEC SQL statement. This may alter the way that the program executes and care should be taken if the application is run.
Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-041: Cannot read the COBOL runtime switches

COBSQL tries to determine how the current run-time is configured by examining the settings of the run-time switches. This error is displayed if COBSQL cannot read the current settings.

This error causes COBSQL to abort.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-042: Cannot set the COBOL runtime switches

Some external code generators produce COBOL code which contains null characters. COBSQL reads the settings of the run-time switches and attempts to change the settings of the relevant switches in order to enable it to read code containing null characters.

This message is displayed if COBSQL has successfully read the run-time switches but has failed in its attempt to set them.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-046: Command line is too large. Maximum length is 1140 characters

Your command line length has exceeded the 1140-character limit.

Resolution:

To reduce the number of characters on your command line, place parameters used by your DBMS precompiler into its appropriate configuration file rather than specifying the parameters on the command line. See the documentation for your DBMS for more information.

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-047: Cobsql cannot be used with the SOURCEFORMAT directive.

You have specified the SOURCEFORMAT(FIXED) directive along with one or more other SOURCEFORMAT directives. With the exception of Pro*COBOL, COBSQL supports the SOURCEFORMAT(FIXED) directive only when no other SOURCEFORMAT directives are specified. If you are using Pro*COBOL, you can also use SOURCEFORMAT(TERMINAL) and SOURCEFORMAT(VARIABLE).

Resolution:

Remove the additional SOURCEFORMAT directive(s).

Parent topic: CSQL-E-024 to CSQL-F-050


CSQL-F-048: Cobsql is not supported for use with managed code.

You have attempted to compile a managed code application using COBSQL.

Resolution:

Recompile your application as native code.

Parent topic: CSQL-E-024 to CSQL-F-050


SQL Data Types

  • Integer Data Types
  • Character Data Types
  • Numeric Data Types
  • Binary Data Types
  • Date and Time Data Types
  • Locator Data Types
  • File Data Types
  • Miscellaneous Data Types
Parent topic: Reference
Related concepts
JVM Host Variables in Managed Code
SQL Data Types
COBOL to SQL Data Type Mapping


Integer Data Types

  • Small Integer
  • Integer
  • Big Integer
Parent topic: SQL Data Types


Small Integer

A small integer (SMALLINT) is a 2-byte integer SQL data type.

Host Variable Formats

OpenESQL and DB2 ECM
01 shortint1      PIC S9(4)  COMP.
01 shortint2      PIC S9(4)  COMP-4.
01 shortint3      PIC X(2)   COMP-5.
01 shortint4      PIC S9(4)  COMP-5.
01 shortint5      PIC X(2)   COMP-X.
01 shortint6      PIC 9(4)   COMP-X.
01 shortint7      PIC S9(4)  BINARY.
Parent topic: Integer Data Types


Integer

An integer (INT) is a 4-byte integer SQL data type.

Host Variable Formats

OpenESQL and DB2 ECM
All of the following definitions are valid for host variables to map directly onto the INT data type.
01 longint1      PIC S9(9)  COMP.
01 longint2      PIC X(4)   COMP-5.
01 longint3      PIC S9(9)  COMP-5.
01 longint4      PIC X(4)   COMP-X.
01 longint5      PIC 9(9)   COMP-X.
01 longint6      PIC S9(9)  BINARY.

For the most efficient access, we recommend that you declare integers as COMP-5.

Parent topic: Integer Data Types


Big Integer

A big integer (BIGINT) is an 8-byte integer SQL data type.

Host Variable Formats

OpenESQL and DB2 ECM
01 bigint1      PIC S9(18)  COMP-3.
01 bigint2      PIC S9(18)  COMP-5.
OpenESQL
01 bigint3      PIC X(8)    COMP-5.
01 bigint4      PIC X(8)    COMP-X.
In non-COBOL applications, a BIGINT data type can hold a value larger than PIC S9(18). If you define your host variable for a COBOL data time with a value larger than S9(18), your data might be truncated.
Parent topic: Integer Data Types


Character Data Types

  • Fixed-length Character Strings
  • Variable-length Character Strings
  • Large Character Strings (CLOB)
  • Unicode Character Strings
  • Unicode Variable-length Character Strings
  • Unicode Large Character Strings (DBCLOB)
  • DBCS Character Strings
  • DBCS Variable-length Character Strings
  • DBCS Large Character Strings
  • XML Data Type
Parent topic: SQL Data Types


Fixed-length Character Strings

Fixed-length character strings (CHAR) are SQL data types with a driver-defined maximum length. They are declared in COBOL as:
PIC X(n)
where n is an integer between 1 and the maximum length.

Host Variable Formats

OpenESQL and DB2 ECM
01 char-field1      PIC X(5).
01 char-field2      PIC X(254).

The largest supported fixed length character string is 254 bytes for the DB2 ECM. If you need a character string greater than 254 bytes in length, use a VARCHAR field.

OpenESQL trims trailing spaces from input parameters before sending them to the database server. Trimming the trailing spaces can improve performance when comparing CHAR and VARCHAR values.

Important: For OpenESQL, the database server pads the value with spaces as necessary. When space padding is required for a host variable used in an expression, use an explicit SQL CAST function to ensure that the server converts the host variable to the required data type.
OpenESQL
01 char-field3      SQL TYPE IS CHAR(200).

The char-field3 format uses the CHAR SQL TYPE.

Parent topic: Character Data Types
Related concepts
OpenESQL Fixed-length Character Strings Handling
Related reference
CHAR SQL Type
ALLOWNULLCHAR


Variable-length Character Strings

Variable-length character strings (VARCHAR and LONGVARCHAR) are SQL data types with a variable maximum length.

Host Variable Formats

OpenESQL and DB2 ECM
01 varchar1.
   49 varchar1-len        PIC 9(4) COMP.
   49 varchar1-data       PIC X(200).
01 longvarchar1.
   49 longvarchar1-len    PIC 9(4) COMP.
   49 longvarchar1-data   PIC X(30000).
01 clob1                  SQL TYPE IS CLOB(32K).
  • The level number for group items containing only two elementary items must be 49. The first item is a 2-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PIC X(n) data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.
  • If the data being copied to a SQL CHAR, VARCHAR or LONG VARCHAR data type is longer than the defined length, then the data is truncated and the SQLWARN1 flag in the SQLCA data structure is set. If the data is smaller than the defined length, a receiving CHAR data type might be padded with blanks.
  • The clob1 format uses the CLOB SQL TYPE.
OpenESQL
In addition to the definitions valid for both OpenESQL and DB2 ECM, the following definitions are also valid for OpenESQL:
01 varchar2  PIC X(20) VARYING.
01 varchar3  SQL TYPE IS CHAR-VARYING(200).
01 longvarchar1 SQL TYPE IS LONG-VARCHAR(50000).
  • The varchar3 format uses the CHAR-VARYING SQL TYPE.
  • The longvarchar1 format uses the LONG-VARCHAR SQL TYPE.
Parent topic: Character Data Types
Related concepts
OpenESQL Fixed-length Character Strings Handling
Related reference
CHAR-VARYING SQL Type
LONG-VARCHAR SQL Type
CLOB SQL Type
PIC X VARYING Data Type


Large Character Strings (CLOB)

Large character strings (CLOB) enable you to store large amounts of data in columns.

Host Variable Formats

OpenESQL and DB2 ECM
01 clob1     SQL TYPE IS CLOB(2M).

The clob1 format uses the CLOB SQL TYPE.

OpenESQL
01 clob2.
   49 clob2-len    PIC 9(9) COMP.
   49 clob2-data   PIC X(70000).
  • The level number for group items containing only two elementary items must be 49. The first item is a 4-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PIC X(n) data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.
Parent topic: Character Data Types
Related reference
CLOB SQL Type


Unicode Character Strings

Unicode character strings (UNI) are SQL data types similar to fixed-length character strings, but are encoded using UTF-16 characters instead of single- or mixed-byte characters.

Host Variable Formats

OpenESQL and DB2 ECM
03 uni-field1      PIC N(X) USAGE NATIONAL.

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices


Unicode Variable-length Character Strings

Unicode variable-length character strings (unichar) are SQL data types similar to variable-length character strings, but are encoded using UTF-16 characters instead of single- or mixed-byte characters.

Host Variable Formats

OpenESQL and DB2 ECM
01 unichar1.
   49 unichar1-len        PIC S9(4)  COMP-5.
   49 unichar1-data       PIC N(200) USAGE NATIONAL.

01 unichar2.
   49 unichar1-len        PIC S9(4)  COMP.
   49 unichar1-data       PIC N(200) USAGE NATIONAL.
  • The level number for group items containing only two elementary items must be 49. The first item is a four-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PICn NATIONAL data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices


Unicode Large Character Strings (DBCLOB)

Unicode large character strings (DBCLOB) enable you to store large amounts of Unicode data in columns.

Host Variable Formats

OpenESQL and DB2 ECM
01 dbclob1     SQL TYPE IS DBCLOB(2M).

The dbclob1 format uses the DBCLOB SQL TYPE.

OpenESQL
The following definition is also valid:
01 dbclob2.
   49 dbclob2-len          PIC S9(9) COMP-5.
   49 dbclob2-data         PIC N(32000) USAGE NATIONAL.
  • The level number for group items containing only two elementary items must be 49. The first item is a four-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PICn NATIONAL data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices
Related reference
DBCLOB SQL Type


DBCS Character Strings

DBCS character strings are SQL data types similar to fixed-length character strings, but are encoded using DBCS characters instead of single- or mixed-byte characters.

Host Variable Formats

OpenESQL and DB2 ECM
01 dbcs-field1      PIC N(X) USAGE DISPLAY-1.
01 dbcs-field2      PIC G(X).

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices


DBCS Variable-length Character Strings

DBCS variable-length character strings are SQL data types similar to variable-length character strings, but are encoded using DBCS characters instead of single- or mixed-byte characters.

Host Variable Formats

OpenESQL and DB2 ECM
01 dbcschar1.
   49 dbcschar1-len        PIC S9(4)  COMP-5.
   49 dbcschar1-data       PIC N(200) USAGE DISPLAY-1.

01 dbcschar2.
   49 dbcschar1-len        PIC S9(4)  COMP.
   49 dbcschar1-data       PIC G(200).
  • The level number for group items containing only two elementary items must be 49. The first item is a two-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PIC n DISPLAY-1 or PIC G data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices


DBCS Large Character Strings

DBCS large character strings enable you to store large amounts of DBCS data in columns.

Host Variable Formats

OpenESQL
01 dbcs1.
   49 dbcs1-len          PIC S9(9) COMP-5.
   49 dbcs1-data         PIC N(32000) USAGE DISPLAY-1.

01 dbcs2.
   49 dbcs2-len          PIC S9(9) COMP-5.
   49 dbcs2-data         PIC G(32000).
  • The level number for group items containing only two elementary items must be 49. The first item is a four-byte field declared with usage COMP or COMP-5 that represents the effective length of the character string. The length field can be signed or unsigned. The second item is a PIC n DISPLAY-1 or PIC G data type, where n is an integer representing the length of the field that holds the data.
  • SQL statements must reference the group name.

For more information on using host variables with international data, see OpenESQL Globalization Best Practices.

Parent topic: Character Data Types
Related concepts
OpenESQL Globalization Best Practices


XML Data Type

Many DBMS providers support XML as a data type in both character and binary formats. See your DBMS documentation for further information as to what types of host variables the vendor suggests using.

Host Variable Format

OpenESQL and DB2 ECM
01 xmlclob1-hv-name        SQL TYPE IS XML AS CLOB(2M).

The xmlclob1-hv-name format uses the XML SQL TYPE.

DB2 ECM
01 xmlblob-file1-hv-name   SQL TYPE IS XML AS BLOB-FILE.
01 xmlclob-file1-hv-name   SQL TYPE IS XML AS CLOB-FILE.
01 xmldbclob-file1-hv-name SQL TYPE IS XML AS DBCLOB-FILE.

All formats use the XML SQL TYPE.

Parent topic: Character Data Types
Related reference
XML SQL Type


Numeric Data Types

  • Approximate Numeric Data Types
  • Exact Numeric Data Types
  • Unicode Numeric Data Types
Parent topic: SQL Data Types


Approximate Numeric Data Types

Approximate numeric data types (FLOAT, DOUBLE, and REAL) are SQL data types that enable floating points.

Host Variable Formats

OpenESQL and DB2 ECM
01 real1       USAGE COMP-1.
01 float1      USAGE COMP-2.
  • The real1 format is for the 32-bit (single-precision) SQL floating-point data type, REAL.
  • The float1 format is for 64-bit (double-precision) SQL floating-point data types, FLOAT and DOUBLE.
Parent topic: Numeric Data Types


Exact Numeric Data Types

Exact numeric data types (DECIMAL and NUMERIC) can hold values up to a driver-specified precision and scale.

Host Variable Formats

OpenESQL and DB2 ECM
01 packed1      PIC S9(8)V9(10) USAGE COMP-3.
01 packed2      PIC S9(8)V9(10) USAGE PACKED-DECIMAL.
01 packed3      PIC S9(8)v9(10) USAGE DISPLAY.
Both OpenESQL and DB2 ECM support:
  • Unsigned and signed DISPLAY numerics
  • Leading and trailing signs
Parent topic: Numeric Data Types


Unicode Numeric Data Types

Unicode numeric data types (signed and unsigned) can hold values up to a driver-specified precision and scale.

Host Variable Formats

OpenESQL
01 uninum-us      PIC 9(5)v9(5)  USAGE NATIONAL.
01 uninum-sls     PIC S9(5) SIGN LEADING SEPARATE USAGE NATIONAL.
01 uninum-sts     PIC S9(5)v9(5) SIGN TRAILING SEPARATE USAGE NATIONAL.
Native OpenESQL supports:
  • Unsigned and signed Unicode numerics
  • Leading and trailing signs
Parent topic: Numeric Data Types


Binary Data Types

  • Fixed-length Binary Strings
  • Variable-length Binary Strings
  • Large Binary Strings (BLOB)
Parent topic: SQL Data Types


Fixed-length Binary Strings

Fixed-length binary data types (RAW, BINARY, and CHAR(x) FOR BIT DATA) are SQL data types with a driver-defined maximum length.

Host Variable Formats

OpenESQL
03 bin-field1      PIC X(5).
03 bin-field2      SQL TYPE IS BINARY(200).
  • SQL BINARY, VARBINARY and IMAGE data are represented in COBOL as PIC X (n) fields.
  • OpenESQL does not perform data conversion.
  • When data is fetched from the database, if the host-variable field is smaller than the amount of data fetched, the data is truncated and the SQLWARN1 field in the SQLCA data structure is set to W. If the host-variable field is larger than the amount of data, the field is padded with null (x"00") bytes.
  • Any of the following enable you to insert data into BINARY, VARBINARY or LONG-VARBINARY columns:
    • Use dynamic SQL statements
    • Compile your application with the ALLOWNULLCHAR directive
    • Use SQL TYPE host variables
  • If you use PIC X host variables, compile your application with the ALLOWNULLCHAR directive to prevent the truncation of transferred data to or from the host variable if a null (x"00") is encountered.
  • The bin-field2 format uses the BINARY SQL TYPE.
DB2 ECM
03 bin-field1      PIC X(5).
  • Use CHAR FOR BIT DATA to represent BINARY.
  • Use VARCHAR(n) FOR BIT DATA to represent VARBINARY.
  • Use LONG VARCHAR FOR BIT DATA to represent LONG-VARBINARY.
  • The IBM ODBC driver returns the BINARY, VARBINARY and LONG VARBINARY data types instead of the IBM equivalent.
  • The IMAGE data type can be represented by BLOB.
  • DB2 uses LOBs (Character Large Object, Binary Large Object or Graphical Large Object) to define very large columns (2 Gigabytes maximum). You can use static SQL with these data types.
Parent topic: Binary Data Types
Related reference
BINARY SQL Type


Variable-length Binary Strings

Variable-length binary data types (VARBINARY, LONG-VARBINARY, and LONG VARCHAR FOR BIT DATA) are SQL data types with a driver-defined maximum variable length.

Host Variable Formats

OpenESQL
01 varbin-field1      SQL TYPE IS VARBINARY(2000).
01 varbin-field2      SQL TYPE IS LONG-VARBINARY(20000).
01 varbin-field3.
   49 varbin-field3-len    PIC S9(4) COMP-5.
   49 varbin-field3-data   PIC X(2000).
  • SQL BINARY, VARBINARY and IMAGE data are represented in COBOL as PIC X (n) fields.
  • OpenESQL does not perform data conversion.
  • When data is fetched from the database, if the host-variable field is smaller than the amount of data fetched, the data is truncated and the SQLWARN1 field in the SQLCA data structure is set to W. If the host-variable field is larger than the amount of data, the field is padded with null (x"00") bytes.
  • Any of the following enable you to insert data into BINARY, VARBINARY or LONG-VARBINARY columns:
    • Use dynamic SQL statements
    • Compile your application with the ALLOWNULLCHAR directive
    • Use SQL TYPE host variables
  • The varbin-field1 format uses the VARBINARY SQL TYPE.
  • The varbin-field2 format uses the LONG-VARBINARY SQL TYPE.
DB2 ECM
01 varbin-field3.
   49 varbin-field3-len    PIC S9(4) COMP-5.
   49 varbin-field3-data   PIC X(2000).
  • Use CHAR FOR BIT DATA to represent BINARY.
  • Use VARCHAR(n) FOR BIT DATA to represent VARBINARY.
  • Use LONG VARCHAR FOR BIT DATA to represent LONG-VARBINARY.
  • The IBM ODBC driver returns the BINARY, VARBINARY and LONG VARBINARY data types instead of the IBM equivalent.
  • The IMAGE data type can be represented by BLOB.
  • DB2 uses LOBs (Character Large Object, Binary Large Object or Graphical Large Object) to define very large columns (2 Gigabytes maximum). You can use static SQL with these data types.
Parent topic: Binary Data Types
Related reference
VARBINARY SQL Type
LONG-VARBINARY SQL Type


Large Binary Strings (BLOB)

Large binary string data types (BLOB) are SQL data types that enable you to store large amounts of data, from sources such as JPG files, in binary columns.

Host Variable Formats

OpenESQL and DB2 ECM
01 blob1     SQL TYPE IS BLOB(2M).
  • SQL BINARY, VARBINARY and IMAGE data are represented in COBOL as PIC X (n) fields.
  • OpenESQL does not perform data conversion.
  • When data is fetched from the database, if the host-variable field is smaller than the amount of data fetched, the data is truncated and the SQLWARN1 field in the SQLCA data structure is set to W. If the host-variable field is larger than the amount of data, the field is padded with null (x"00") bytes.
  • Any of the following enable you to insert data into BINARY, VARBINARY or LONG-VARBINARY columns:
    • Use dynamic SQL statements
    • Compile your application with the ALLOWNULLCHAR directive
    • Use SQL TYPE host variables
Parent topic: Binary Data Types
Related reference
BLOB SQL Type


Date and Time Data Types

COBOL does not support date and time data types directly. Therefore, date and time data columns are converted to COBOL character representations.

  • DATE
  • TIME
  • TIMESTAMP
  • TIMESTAMPOFFSET
Parent topic: SQL Data Types
Related reference
TSTAMPSEP


DATE

Data Format

Default and alternative date value formats vary. If using DB2 ECM, consult IBM documentation on differing formats. For OpenESQL, review the DATE and DATEDELIM SQL compiler directive option topics for more information.

For example, one supported date format is:
yyyy-mm-dd
An example value for this format is:
1994-05-24

Host Variable Formats

OpenESQL and DB2 ECM
01 date1         PIC X(10).
OpenESQL
01 date2         SQL TYPE IS DATE.
01 date3         SQL TYPE IS DATE-RECORD.
01 date4         PIC X(n).
date1 format
  • Move date data into the host variable using the form:
    MOVE "yyyy-mm-dd" TO host-var.
  • Review the DETECTDATE SQL compiler directive option topic to determine whether or not it applies to your application.
date2 format
  • Move date data into the host variable using the form:
    MOVE "yyyy-mm-dd" TO host-var.
  • Preferred format; use whenever possible.
  • Uses the DATE SQL TYPE.
  • Similar to the date1 format, but when using Visual COBOL version 2.3 or later, never requires DETECTDATE for input host variable processing .
date3 format
Use this format when your application moves date data to host variables using ODBC escape sequences.
Note: This format is deprecated starting with Visual COBOL version 2.3. Instead, we strongly suggest that you use the DATE and DATEDELIM SQL compiler directive options to avoid using ODBC escape sequences.
  • Move date data into the host variable using the form:
    MOVE "{d 'yyyy-mm-dd'}" TO host-var.
  • Compile applications with the DETECTDATE SQL compiler directive option to ensure that OpenESQL evaluates PIC X fields for possible time formats in input host variables.
  • Ensure n is large enough to accommodate the date value plus the characters used by the ODBC escape sequence.
  • Output host variable values are returned without the ODBC escape sequence.
date4 format
  • Move date data into host variables using these forms:
    MOVE yyyy TO host-var-year
MOVE mm TO host-var-month
MOVE dd to host-var-day
  • Uses the DATE-RECORD SQL TYPE.
Parent topic: Date and Time Data Types
Related reference
DATE SQL Type
DATE-RECORD SQL Type
DATE
DATEDELIM


TIME

Data Format

Default and alternative time value formats vary. If using DB2 ECM, consult IBM documentation on differing formats. For OpenESQL, review the TIME and TIMEDELIM SQL compiler directive option topics for more information.

For example, one supported time format is:
hh:mm:ss
An example value for this format is:
12:34:00

Host Variable Formats

OpenESQL and DB2 ECM
01 time1         PIC X(8).
OpenESQL
01 time2         SQL TYPE IS TIME.
01 time3         PIC X(n).
01 time4         SQL TYPE IS TIME-RECORD.
time1 format
  • Move time data into a host variable using any of these forms:
    MOVE "hh:mm:ss" TO host-var.
MOVE "hh.mm.ss" TO host-var.
MOVE "hh:mm PM" TO host-var.
  • Review the DETECTDATE SQL compiler directive option topic to determine whether or not it applies to your application.
time2 format
  • Move time data into a host variable using these forms:
    MOVE "hh:mm:ss" TO host-var.
MOVE "hh.mm.ss" TO host-var.
MOVE "hh:mm PM" TO host-var.
  • Preferred format - use whenever possible.
  • Uses the TIME SQL TYPE.
  • Similar to the time1 format, but when using Visual COBOL version 2.3 or later, never requires DETECTDATE for input host variable processing.
time3 format
Use this format when your application moves time data to host variables using ODBC escape sequences.
Note: This format is deprecated starting with Visual COBOL version 2.3. Instead, we strongly suggest that you use the TIME and TIMEDELIM SQL compiler directive options to avoid using ODBC escape sequences.
  • Move time data into host variables using the form:
    MOVE "{t 'hh:mm:ss'}" TO host-var.
  • Compile applications with the DETECTDATE SQL compiler directive option to ensure that OpenESQL evaluates PIC X fields for possible time formats in input host variables.
  • Ensure n is large enough to accommodate the time value plus the characters used by the ODBC escape sequence.
  • Output host variable values are returned without the ODBC escape sequence.
time4 format
  • Move time data into host variables using this form:
    MOVE hh TO host-var-hour
MOVE mm TO host-var-min
MOVE ss TO host-var-sec
  • Uses the TIME-RECORD SQL TYPE.
Parent topic: Date and Time Data Types
Related reference
TIME SQL Type
TIME-RECORD SQL Type
TIME
TIMEDELIM


TIMESTAMP

Data Format

Default and alternative timestamp value formats vary. If using DB2 ECM, consult IBM documentation on differing formats. For OpenESQL, review the TSTAMPSEP SQL compiler directive option topic for more information.

For example, one supported time format is:
yyyy-mm-dd hh:mm:ss[.f[f[...]]]
where the number of fractional digits is driver-defined. An example value for this format is:
1994-05-24 12:34:00.000

Host Variable Formats

OpenESQL and DB2 ECM
01 timestamp1         PIC X(29).
01 timestamp2         SQL TYPE IS TIMESTAMP.

The timestamp2 format uses the TIMESTAMP SQL TYPE.

OpenESQL
01 timestamp3         PIC X(n).
01 timestamp4         SQL TYPE IS TIMESTAMP-RECORD.
timestamp1 format
  • Move timestamp data into a host variable using the form:
    MOVE "yyyy-mm-dd hh:mm:ss" TO timestamp1
  • Review the DETECTDATE SQL compiler directive option topic to determine whether or not it applies to your application.
timestamp2
  • Move timestamp data into a host variable using the form:
    MOVE "yyyy-mm-dd hh:mm:ss" TO timestamp2
  • Preferred format - use whenever possible.
  • Uses the TIMESTAMP SQL TYPE.
  • Similar to the timestamp1 format, but when using Visual COBOL version 2.3 or later, never requires DETECTDATE for input host variable processing.
timestamp3 format
Use this format when your application moves timestamp data to host variables using ODBC escape sequences.
Note: This format is deprecated starting with Visual COBOL version 2.3. Instead, we strongly suggest that you use the TSTAMPDEP SQL compiler directive option to avoid using ODBC escape sequences.
  • Move timestamp data into a host variable using the form:
    MOVE "{ts 'yyyy-mm-dd hh:mm:ss[.f[f[...]]]'}"
     TO timestamp3
  • Compile applications with the DETECTDATE SQL compiler directive option to ensure that OpenESQL evaluates PIC X fields for possible timestamp formats in input host variables.
  • Ensure n is large enough to accommodate the timestamp value plus the characters used by the ODBC escape sequence.
  • Output host variable values are returned without the ODBC escape sequence.
timestamp4 format
  • Move timestamp data into host variables using these forms:
    MOVE yyyy TO host-var-year
MOVE mm TO host-var-month
MOVE dd TO host-var-day
MOVE hh TO host-var-hour
MOVE mm TO host-var-minute
MOVE ss TO host-var-sec
MOVE ff TO host-varc-fra
  • Uses the TIMESTAMP-RECORD SQL TYPE.
DB2 ECM

The TIMESTAMP data type has a maximum length of 26 characters.

Parent topic: Date and Time Data Types
Related reference
TIMESTAMP SQL Type
TIMESTAMP-RECORD SQL Type
TSTAMPSEP


TIMESTAMPOFFSET

Data Format

If a COBOL output host variable is defined for an SQL timestamp value with an offset, the date and time are specified in the following format:
yyyy-mm-dd hh:mm:ss[.f[f[...]]]  {+ | -}hh:mm
where the number of fractional digits is driver-defined. For example:
1994-05-24 12:34:00.000 +02:00

Host Variable Formats

OpenESQL and DB2 ECM
01 timestampoffset1   PIC X(36).
OpenESQL
01 timestampoffset2   SQL TYPE IS TIMESTAMP-OFFSET.
01 timestampoffset3   SQL TYPE IS TIMESTAMP-OFFSET-RECORD.
  • The timestampoffset2 format uses the TIMESTAMP-OFFSET SQL TYPE.
  • The timestampoffset3 format uses the TIMESTAMP-OFFSET-RECORD SQL TYPE.
Parent topic: Date and Time Data Types
Related reference
TIMESTAMP-OFFSET SQL Type
TIMESTAMP-OFFSET-RECORD SQL Type


Locator Data Types

  • BLOB-LOCATOR Data Type
  • CLOB-LOCATOR Data Type
  • DBCLOB-LOCATOR Data Type
Parent topic: SQL Data Types


BLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 blob-locator-file1 SQL TYPE IS BLOB-LOCATOR.

The blob-locator-file1 format uses the BLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
BLOB-LOCATOR SQL Type


CLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 clob-locator1 SQL TYPE IS CLOB-LOCATOR.

The clob-locator1 format uses the CLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
CLOB-LOCATOR SQL Type


DBCLOB-LOCATOR Data Type

Host Variable Format

DB2 ECM
01 dbclob-locator-file1 SQL TYPE IS CLOB-LOCATOR.

The dbclob-locator-file1 format uses the DBCLOB-LOCATOR SQL TYPE.

Parent topic: Locator Data Types
Related reference
DBCLOB-LOCATOR SQL Type


File Data Types

  • BLOB-FILE Data Type
  • CLOB-FILE Data Type
  • DBCLOB-FILE Data Type
Parent topic: SQL Data Types


BLOB-FILE Data Type

Host Variable Format

DB2 ECM
01 blob-file1      SQL TYPE IS BLOB-FILE.

The blob-file1 format uses the BLOB-FILE SQL TYPE.

Parent topic: File Data Types
Related reference
BLOB-FILE SQL Type


CLOB-FILE Data Type

Host Variable Format

DB2 ECM
01 clob-file1 SQL TYPE IS CLOB-FILE.

The clob-file1 format uses the CLOB-FILE SQL TYPE.

Parent topic: File Data Types
Related reference
CLOB-FILE SQL Type


DBCLOB-FILE Data Type

Host Variable Format

DB2 ECM
01 dbclob-file1 SQL TYPE IS DBCLOB-FILE.

The dbclob-file1 format uses the DBCLOB-FILE SQL TYPE.

Parent topic: File Data Types
Related reference
DBCLOB-FILE SQL Type


Miscellaneous Data Types

  • PIC X VARYING Data Type
  • ROWID Data Type
Parent topic: SQL Data Types


PIC X VARYING Data Type

Note: OpenESQL only

Syntax

PIC X(n) VARYING

Where n is an integer representing the length of the field that holds the data.

Example

01 ename  PIC X(15) VARYING.

generates

01  ename.
     05  ename-len  PIC S9(4) COMP.
     05  ename-ARR  PIC X(15).
Parent topic: Miscellaneous Data Types
Related reference
Variable-length Character Strings


ROWID Data Type

Host Variable Format

DB2 ECM
01 rowid1 SQL TYPE IS ROWID.
  • ROWID can be used with DB2 ECM but only for DB2 for z/OS servers.
  • The rowid1 format uses the ROWID SQL TYPE.
Parent topic: Miscellaneous Data Types
Related reference
ROWID SQL Type


SQL TYPEs

  • BINARY SQL Type
  • BLOB SQL Type
  • BLOB-FILE SQL Type
  • BLOB-LOCATOR SQL Type
  • CHAR SQL Type
  • CHAR-VARYING SQL Type
  • CLOB SQL Type
  • CLOB-FILE SQL Type
  • CLOB-LOCATOR SQL Type
  • DATE SQL Type
  • DATE-RECORD SQL Type
  • DBCLOB SQL Type
  • DBCLOB-FILE SQL Type
  • DBCLOB-LOCATOR SQL Type
  • LONG-VARBINARY SQL Type
  • LONG-VARCHAR SQL Type
  • ROWID SQL Type
  • TIME SQL Type
  • TIME-RECORD SQL Type
  • TIMESTAMP SQL Type
  • TIMESTAMP-RECORD SQL Type
  • TIMESTAMP-OFFSET SQL Type
  • TIMESTAMP-OFFSET-RECORD SQL Type
  • VARBINARY SQL Type
  • XML SQL Type
Parent topic: Reference
Related concepts
COBOL to SQL Data Type Mapping
SQL TYPEs


BINARY SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] BINARY(n)

Example

01 hv-name SQL TYPE IS BINARY(200).

generates

01 hv-name PIC X(200).
Parent topic: SQL TYPEs
Related reference
Fixed-length Binary Strings
Related information
OpenESQL


BLOB SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] BLOB(lob-length)

Where lob-length is a value between 1 and 1073741823 expressed either as a number or a number followed by K (kilobytes), M (megabytes), or G (gigabytes).

Note: Although this SQL TYPE has a theoretical size limitation of 2G, for all practical purposes, the actual limitation is approximately 450M, which is the data size actually allocated to the application program.

Example

01 hv-name SQL TYPE IS BLOB(2M).

generates

01 hv-name.
  03 hv-name-length  PIC S9(9) COMP-5.
  03 hv-name-data    PIC X(2097152).
Parent topic: SQL TYPEs
Related reference
Large Binary Strings (BLOB)


BLOB-FILE SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] BLOB-FILE

Example

01 hv-name SQL TYPE IS BLOB-FILE.

generates

01  hv-name.
  49 hv-name-name-length PIC S9(9) COMP-5.
  49 hv-name-data-length PIC S9(9) COMP-5.
  49 hv-name-file-option PIC S9(9) COMP-5.
  49 hv-name-name PIC X(255).
Parent topic: SQL TYPEs
Related reference
BLOB-FILE Data Type
XML SQL Type


BLOB-LOCATOR SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] BLOB-LOCATOR

Example

01 hv-name SQL TYPE IS BLOB-LOCATOR.

generates

01 hv-name PIC S9(9) COMP-5.
Parent topic: SQL TYPEs
Related reference
BLOB-LOCATOR Data Type


CHAR SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] CHAR(n)

Example

01 hv-name SQL TYPE IS CHAR(200).

generates

01 hv-name PIC X(200).
Parent topic: SQL TYPEs
Related reference
Fixed-length Character Strings


CHAR-VARYING SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] CHAR-VARYING(n)
  • CHAR-VARYING data is passed to OpenESQL as SQL_VARCHAR.
  • Data sent to the data source eliminates trailing spaces except for the first space if the value is all spaces.
  • Values fetched from the data source are padded with spaces.

Example

01 hv-name SQL TYPE IS CHAR-VARYING(200).

generates

01 hv-name PIC X(200).
Parent topic: SQL TYPEs
Related reference
Variable-length Character Strings


CLOB SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] CLOB(lob-length)

Where lob-length is a value between 1 and 1073741823 expressed either as a number or a number followed by K (kilobytes), M (megabytes), or G (gigabytes).

Note: Although this SQL TYPE has a theoretical size limitation of 2G, for all practical purposes, the actual limitation is approximately 450M, which is the data size actually allocated to the application program.

Example

01 hv-name SQL TYPE IS CLOB(2M).

generates

01 hv-name.
  03 hv-name-length  PIC S9(9) COMP-5.
  03 hv-name-data    PIC X(2097152).
Parent topic: SQL TYPEs
Related reference
Variable-length Character Strings
Large Character Strings (CLOB)
XML SQL Type


CLOB-FILE SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] CLOB-FILE

Example

01 hv-name SQL TYPE IS CLOB-FILE.

generates

01  hv-name.
  49 hv-name-name-length PIC S9(9) COMP-5.
  49 hv-name-data-length PIC S9(9) COMP-5.
  49 hv-name-file-option PIC S9(9) COMP-5.
  49 hv-name-name PIC X(255).
Parent topic: SQL TYPEs
Related reference
CLOB-FILE Data Type
XML SQL Type


CLOB-LOCATOR SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] CLOB-LOCATOR

Example

01 hv-name SQL TYPE IS CLOB-LOCATOR.

generates

01 hv-name PIC S9(9) COMP-5.
Parent topic: SQL TYPEs
Related reference
CLOB-LOCATOR Data Type


DATE SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] DATE

Use DATE to generate a single working-storage record to contain all date information.

Example

01 hv-name SQL TYPE IS DATE.

generates

01 hv-name PIC X(10).
Parent topic: SQL TYPEs
Related reference
DESCRIBEDTCHAR
DESCRIBEDTREC
DATE


DATE-RECORD SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] DATE-RECORD
Use DATE-RECORD to generate a group-level record for the date containing individual records for each element of the date as follows:
  • Year
  • Month
  • Day

Example

01 hv-name SQL TYPE IS DATE.

generates

01 hv-name PIC X(10).
Parent topic: SQL TYPEs
Related reference
DATE


DBCLOB SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] DBCLOB(lob-length)

Where lob-length is a value between 1 and 1073741823 expressed either as a number or a number followed by K (kilobytes), M (megabytes), or G (gigabytes).

Note: Although this SQL TYPE has a theoretical size limitation of 2G, for all practical purposes, the actual limitation is approximately 450M, which is the data size actually allocated to the application program.

Example

01 hv-name SQL TYPE IS DBCLOB(2M).

generates

01 hv-name.
  03 hv-name-length  PIC S9(9) COMP-5.
  03 hv-name-data    PIC N(2097152).
Parent topic: SQL TYPEs
Related reference
Unicode Large Character Strings (DBCLOB)


DBCLOB-FILE SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] DBCLOB-FILE

Example

01 hv-name SQL TYPE IS DBCLOB-FILE.

generates

01  hv-name.
  49 hv-name-name-length PIC S9(9) COMP-5.
  49 hv-name-data-length PIC S9(9) COMP-5.
  49 hv-name-file-option PIC S9(9) COMP-5.
  49 hv-name-name PIC X(255).
Parent topic: SQL TYPEs
Related reference
DBCLOB-FILE Data Type
XML SQL Type


DBCLOB-LOCATOR SQL Type

Note: DB2 ECM only

Syntax

SQL [TYPE] [IS] DBCLOB-LOCATOR

Example

01 hv-name SQL TYPE IS DBCLOB-LOCATOR.

generates

01 hv-name PIC S9(9) COMP-5.
Parent topic: SQL TYPEs
Related reference
DBCLOB-LOCATOR Data Type


LONG-VARBINARY SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] LONG-VARBINARY(n)

Example

01 hv-name SQL TYPE IS LONG-VARBINARY(2000).

generates

01 hv-name.
  03 hv-name-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(2000).
Parent topic: SQL TYPEs
Related reference
Variable-length Binary Strings


LONG-VARCHAR SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] LONG-VARCHAR(n)

Example

01 hv-name SQL TYPE IS LONG-VARCHAR(65000).

generates

01 hv-name.
  03 hv-name-len    PIC S9(9) COMP-5.
  03 hv-name-val    PIC X(65000).
Parent topic: SQL TYPEs
Related reference
Variable-length Character Strings


ROWID SQL Type

Note: Valid for DB2 ECM but only for DB2 for z/OS servers

Syntax

SQL [TYPE] [IS] ROWID

Example

01 hv-name SQL TYPE IS ROWID.

generates

01 hv-name.
  03 hv-name-len    PIC S9(4) COMP.
  03 hv-name-text   PIC X(40).
Parent topic: SQL TYPEs
Related reference
ROWID Data Type


TIME SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] TIME

Use TIME to generate a single working-storage record to contain all time information.

Example

01 hv-name SQL TYPE IS TIME.

generates

01 hv-name PIC X(8).
Parent topic: SQL TYPEs
Related reference
DESCRIBEDTCHAR
DESCRIBEDTREC
TIME


TIME-RECORD SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] TIME-RECORD

Use TIME-RECORD to generate a group-level record for the time containing individual records for each element as follows:

  • Hour
  • Minutes
  • Seconds

To insert data, you must pass valid data in the generated field names.

Example

01 hv-name SQL TYPE IS TIME-RECORD.

generates

01 hv-name.
  03 hv-name-hour  PIC 9(4) COMP-5.
  03 hv-name-min   PIC 9(4) COMP-5.
  03 hv-name-sec   PIC 9(4) COMP-5.
Parent topic: SQL TYPEs
Related reference
TIME


TIMESTAMP SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] TIMESTAMP
Use TIMESTAMP to generate a single working-storage record to contain all timestamp information.
  • Data must be organized in fixed date/time formats.
  • Fractional seconds are supported up to nine digits. However, this value can vary depending on your target DBMS and your ODBC driver. For example, DB2 ECM limits fractional seconds to six digits. See your DBMS or ODBC driver documentation for more information.
  • Fractional data is passed left justified, and must contain the number of digits defined in your record. For example, to pass a fractional value of 678 to a record that defines fractional data as nine digits, move the value 678000000.
  • Fractional data is right justified when returned from a SELECT or FETCH statement.
  • Because of the way SQL Server stores date/time values, it might round the last fractional digit of a fractional value up or down depending on the digit. For example:
    If you pass... | SQL Server returns...
    01/01/98 23:59.59.999 | 1998-01-02 00:00:00.000
    01/01/98 23:59.59.995 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.996 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.997 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.998 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.992 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.993 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.994 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.990 | 1998-01-01 23:59:59.990
    01/01/98 23:59.59.991 | 1998-01-01 23:59:59.990

Example

01 hv-name SQL TYPE IS TIMESTAMP.

generates

01 hv-name PIC X(29).
Parent topic: SQL TYPEs
Related reference
DESCRIBEDTCHAR
TIMESTAMP


TIMESTAMP-RECORD SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] TIMESTAMP-RECORD

Use TIMESTAMP-RECORD to generate a group-level record for the timestamp containing individual records for each element of the timestamp as follows:

  • Year
  • Month
  • Day
  • Hour
  • Minute
  • Second
  • Fractional second

To insert data, you must pass valid data in the generated field names.

  • Data must be organized in fixed date/time formats.
  • Fractional seconds are supported up to nine digits. However, this value can vary depending on your target DBMS and your ODBC driver. For example, DB2 ECM limits fractional seconds to six digits. See your DBMS or ODBC driver documentation for more information.
  • Fractional data is passed left justified, and must contain the number of digits defined in your record. For example, to pass a fractional value of 678 to a record that defines fractional data as nine digits, move the value 678000000.
  • Fractional data is right justified when returned from a SELECT or FETCH statement.
  • Because of the way SQL Server stores date/time values, it might round the last fractional digit of a fractional value up or down depending on the digit. For example:
    If you pass... | SQL Server returns...
    01/01/98 23:59.59.999 | 1998-01-02 00:00:00.000
    01/01/98 23:59.59.995 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.996 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.997 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.998 | 1998-01-01 23:59:59.997
    01/01/98 23:59.59.992 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.993 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.994 | 1998-01-01 23:59:59.993
    01/01/98 23:59.59.990 | 1998-01-01 23:59:59.990
    01/01/98 23:59.59.991 | 1998-01-01 23:59:59.990

Example

01 hv-name SQL TYPE IS TIMESTAMP-RECORD.

generates

01 hv-name.
  03 hv-name-year  PIC S9(4) COMP-5.
  03 hv-name-month PIC 9(4) COMP-5.
  03 hv-name-day   PIC 9(4) COMP-5.
  03 hv-name-hour  PIC 9(4) COMP-5.
  03 hv-name-min   PIC 9(4) COMP-5.
  03 hv-name-sec   PIC 9(4) COMP-5.
  03 hv-name-frac  PIC 9(9) COMP-5.
Parent topic: SQL TYPEs
Related reference
DESCRIBEDTREC
TIMESTAMP


TIMESTAMP-OFFSET SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] TIMESTAMP-OFFSET

Use TIMESTAMP-OFFSET to generate a single working-storage record to contain all timestamp information.

Example

01 hv-name SQL TYPE IS TIMESTAMP-OFFSET.

generates

01 hv-name PIC X(36).
Parent topic: SQL TYPEs
Related reference
TIMESTAMPOFFSET


TIMESTAMP-OFFSET-RECORD SQL Type

Note: OpenESQL only

Syntax

SQL [TYPE] [IS] TIMESTAMP-OFFSET-RECORD
Use TIMESTAMP-OFFSET-RECORD to generate a group-level record for the timestamp containing individual records for each element of the timestamp as follows:
  • Year
  • Month
  • Day
  • Hour
  • Minute
  • Second
  • Fractional second
  • Offset hours
  • Offset minutes

To insert data, you must pass valid data in the generated field names.

Example

01 hv-name SQL TYPE IS TIMESTAMP-OFFSET-RECORD.

generates

01 hv-name.
  03 hv-name-year  PIC S9(4) COMP-5.
  03 hv-name-month PIC 9(4) COMP-5.
  03 hv-name-day   PIC 9(4) COMP-5.
  03 hv-name-hour  PIC 9(4) COMP-5.
  03 hv-name-min   PIC 9(4) COMP-5.
  03 hv-name-sec   PIC 9(4) COMP-5.
  03 hv-name-frac  PIC 9(9) COMP-5.
  03 hv-name-tz-hour PIC S9(4) COMP-5.
  03 hv-name-tz-min  PIC S9(4) COMP-5.
Parent topic: SQL TYPEs
Related reference
TIMESTAMPOFFSET


VARBINARY SQL Type

Note: OpenESQL and DB2 ECM only

Syntax

SQL [TYPE] [IS] VARBINARY(n)

Example

01 hv-name SQL TYPE IS VARBINARY(2000).

generates

01 hv-name.
    49 hv-name-len  PIC S9(4) COMP-5.
    49 hv-name-val  PIC X(2000).
    49 hv-name-text REDEFINES hv-name-val  PIC X(2000).
Parent topic: SQL TYPEs
Related reference
Variable-length Binary Strings


XML SQL Type

Note: OpenESQL and DB2 ECM only

OpenESQL and DB2 ECM

Syntax
SQL [TYPE] [IS] XML AS CLOB(lob-length)

Where lob-length is a value between 1 and 2147483647 expressed either as a number or a number followed by K (kilobytes), M (megabytes), or G (gigabytes).

Note: Although this SQL TYPE has a theoretical size limitation of 2G, for all practical purposes, the actual limitation is approximately 450M, which is the data size actually allocated to the application program.
Example
01 xmlclob1-hv-name SQL TYPE IS XML AS CLOB(2M).

generates

01 xmlclob1-hv-name.
  03 xmlclob1-hv-name-length  PIC S9(9) COMP-5.
  03 xmlclob1-hv-name-data    PIC X(2097152).

DB2 ECM

Syntax
SQL [TYPE] [IS] XML AS BLOB-FILE
SQL [TYPE] [IS] XML AS CLOB-FILE
SQL [TYPE] [IS] XML AS DBCLOB-FILE
Examples
BLOB-FILE
01 xmlblob-file1-hv-name SQL TYPE IS XML AS BLOB-FILE.

generates

01  xmlblob-file1-hv-name.
  49 xmlblob-file1-hv-name-name-length PIC S9(9) COMP-5.
  49 xmlblob-file1-hv-name-data-length PIC S9(9) COMP-5.
  49 xmlblob-file1-hv-name-file-option PIC S9(9) COMP-5.
  49 xmlblob-file1-hv-name-name PIC X(255).
CLOB-FILE
01 xmlclob-file1-hv-name SQL TYPE IS XML AS CLOB-FILE.

generates

01  xmlclob-file1-hv-name.
  49 xmlclob-file1-hv-name-name-length PIC S9(9) COMP-5.
  49 xmlclob-file1-hv-name-data-length PIC S9(9) COMP-5.
  49 xmlclob-file1-hv-name-file-option PIC S9(9) COMP-5.
  49 xmlclob-file1-hv-name-name PIC X(255).
DBCLOB-FILE
01 xmldbclob-file1-hv-name SQL TYPE IS XML AS DBCLOB-FILE.

generates

01  xmldbclob-file1-hv-name.
  49 xmldbclob-file1-hv-name-name-length PIC S9(9) COMP-5.
  49 xmldbclob-file1-hv-name-data-length PIC S9(9) COMP-5.
  49 xmldbclob-file1-hv-name-file-option PIC S9(9) COMP-5.
  49 xmldbclob-file1-hv-name-name PIC X(255).
Parent topic: SQL TYPEs
Related reference
XML Data Type
CLOB SQL Type
BLOB-FILE SQL Type
CLOB-FILE SQL Type
DBCLOB-FILE SQL Type


Data Structures

  • The SQLCA Data Structure
  • The SQLDA Data Structure
Parent topic: Reference


The SQLCA Data Structure

The SQLCA data structure for OpenESQL and the DB2 ECM is shown below:

 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.
     05  SQLEXT.
         10  SQLWARN8    PIC X.
         10  SQLWARN9    PIC X.
         10  SQLWARN10   PIC X.
         10  SQLWARNA    PIC X REDEFINES SQLWARN10.
     05  SQLSTATE    PIC X(5).

The table below describes the contents of the SQLCA data structure:

Field | Contents
SQLCAID | The text string "SQLCA".
SQLCABC | The length of the SQLCA data structure.
SQLCODE | The status code for the last-run SQL statement:
SQLERRML | The length of the error message in SQLERRMC (0–70).
SQLERRMC | Error message text. Error messages longer than 70 bytes are truncated.
SQLERRP | Reserved (diagnostic information).
SQLERRD | An array of six integer status codes (those not listed below are reserved):
 | SQLERRD(1) | SQL server error number.
 | SQLERRD(2) | SQL server severity.
 | SQLERRD(3) | The number of rows affected.
SQLWARN | Eight warning flags, each containing a blank or "W" (those not listed below are reserved): A warning flag will be set if SQLCODE contains a value of +1:
 | SQLWARN0 | A summary of all warning fields. Blank means there are no warnings.
 | SQLWARN1 | "W" indicates that data was truncated on output to a character host variable.
 | SQLWARN2 | "W" indicates that a null value exists, but no indicator variable was provided.
 | SQLWARN3 | "W" indicates that the number of columns is less than the number of host variables or that the number of host variables provided does not match the number of parameter markers in the statement. The lower of the two numbers has been used.
 | SQLWARN4 | "W" indicates a singleton select that returns more than one row (only the first row is returned).
FILLER | Reserved.
SQLSTATE | Status indicator for the last-run SQL statement.
Note: The Oracle, Sybase, and Informix versions of the SQLCA all use SQLCODE, SQLERRML, SQLERRMC, and SQLWARN. The sizes and the positions of these fields can differ among the precompilers.
Parent topic: Data Structures
Related concepts
SQL Communications Area (SQLCA)
SQLWARN Flags
Related reference
WHENEVER
CHECKSINGLETON


The SQLDA Data Structure

The SQLDA data structure is shown below:

    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.
      $IF P64 SET
             *> For 64-bit environments, ensure that SQLDATA is
             *> aligned on an 8-byte boundary.
             10 FILLER             PIC S9(9) COMP-5.
      $END
             10 SQLDATA            USAGE POINTER.
             10 SQLIND             USAGE POINTER.
             10 SQLNAME.
                15 SQLNAMEL        PIC S9(4) COMP-5.
                15 SQLNAMEC        PIC X(30).

The following table describes the contents of the SQLDA data structure.

Field | Contains
SQLDAID | The text string "SQLDA".
SQLDABC
  • 32-bit - The length of the SQLDA data structure (SQLN * 44 + 16)
  • 64-bit - The length of the SQLDA data structure (SQLN * 56 + 16)
SQLN | Total number of SQLVAR entries allocated, equal to the number of input parameters or output columns.
SQLD | Number of SQLVAR entries used.
SQLVAR | SQLVAR is a group item, the number of occurrences of which depends on the value of SQLD.
SQLTYPE | A number representing the data type of the column or host variable and indicating whether null values are allowed (see the table below for valid values).
SQLLEN | Length of a value from a column. If the data is decimal (including money), SQLLEN is split into two parts: the first byte contains the precision; the second byte contains the scale.
FILLER | For 64-bit environments, this is necessary to ensure that SQLDATA and SQLIND reside on 8-byte boundaries in memory, which is required for execution within a 64-bit environment.
SQLDATA | For FETCH, OPEN, and EXECUTE, the address of the host variable (must be inserted by the application). For DESCRIBE and PREPARE, SQLDATA is not used.
SQLIND | For FETCH, OPEN, and EXECUTE, the address of an associated indicator variable, if one exists. If the column does not permit a null value, the field is undefined. If the column permits a null value, SQLIND is set to -1 if the data value is null or to 0 if the data value is not null. For DESCRIBE and PREPARE, SQLIND is not used.
SQLNAME | A group item containing the name and length of the column (not used for FETCH, OPEN or EXECUTE.
SQLNAMEL | Length of the name column
SQLNAMEC | Name of the column. For a derived column, this field contains the ASCII numeric literal value that represents the derived column's original position within the select list

SQL TYPE Values

       78  ESQL-DATE-CHAR                  VALUE 384.
       78  ESQL-DATE-CHAR-NULL             VALUE 385.
       78  ESQL-DATE-REC                   VALUE 386.
       78  ESQL-DATE-REC-NULL              VALUE 387.
       78  ESQL-TIME-CHAR                  VALUE 388.
       78  ESQL-TIME-CHAR-NULL             VALUE 389.
       78  ESQL-TIME-REC                   VALUE 390.
       78  ESQL-TIME-REC-NULL              VALUE 391.
       78  ESQL-TIMESTAMP-CHAR             VALUE 392.
       78  ESQL-TIMESTAMP-CHAR-NULL        VALUE 393.
       78  ESQL-TIMESTAMP-REC              VALUE 394.
       78  ESQL-TIMESTAMP-REC-NULL         VALUE 395.
       78  ESQL_TIMESTAMP_OFFSET_CHAR      VALUE 396.
       78  ESQL_TIMESTAMP_OFFSET_CHAR_NULL VALUE 397.
       78  ESQL_TIMESTAMP_OFFSET_REC       VALUE 398.
       78  ESQL_TIMESTAMP_OFFSET_REC_NULL  VALUE 399.

       78  ESQL-LONGVARBINARY              VALUE 404.
       78  ESQL-LONGVARBINARY-NULL         VALUE 405.
       78  ESQL-LONGVARCHAR                VALUE 408.
       78  ESQL-LONGVARCHAR-NULL           VALUE 409.
       78  ESQL-BINARY                     VALUE 444.
       78  ESQL-BINARY-NULL                VALUE 445.
       78  ESQL-VARBINARY                  VALUE 446.
       78  ESQL-VARBINARY-NULL             VALUE 447.
       78  ESQL-VARCHAR                    VALUE 448.
       78  ESQL-VARCHAR-NULL               VALUE 449.

       78  ESQL-CHARVARYING                VALUE 450.  *> added esq03n31
       78  ESQL-CHARVARYING-NULL           VALUE 451.  *> added esq03n31

       78  ESQL-CHAR                       VALUE 452.
       78  ESQL-CHAR-NULL                  VALUE 453.

       78  ESQL-CHAR-FIXED                 VALUE 454.  *> added esq03n31
       78  ESQL-CHAR-FIXED-NULL            VALUE 455.  *> added esq03n31

       78  ESQL-VARGRAPH                   VALUE 464.
       78  ESQL-VARGRAPH-NULL              VALUE 465.
       78  ESQL-GRAPHIC                    VALUE 468.
       78  ESQL-GRAPHIC-NULL               VALUE 469.
       78  ESQL-LONGRAPH                   VALUE 472.
       78  ESQL-LONGRAPH-NULL              VALUE 473.

       78  ESQL-DOUBLE                     VALUE 480.
       78  ESQL-DOUBLE-NULL                VALUE 481.
       78  ESQL-REAL                       VALUE 482.
       78  ESQL-REAL-NULL                  VALUE 483.
       78  ESQL-DECIMAL                    VALUE 484.
       78  ESQL-DECIMAL-NULL               VALUE 485.
       78  ESQL-BIGINT                     VALUE 492.
       78  ESQL-BIGINT-NULL                VALUE 493.
       78  ESQL-INTEGER                    VALUE 496.
       78  ESQL-INTEGER-NULL               VALUE 497.
       78  ESQL-SMALLINT                   VALUE 500.
       78  ESQL-SMALLINT-NULL              VALUE 501.
       78  ESQL-TINYINT                    VALUE 502.
       78  ESQL-TINYINT-NULL               VALUE 503.

       78  ESQL-UDISP-UNSIGN               VALUE 510.
       78  ESQL-UDISP-UNSIGN-NULL          VALUE 511.
       78  ESQL-UDISP-SIGN-LEAD-SEP        VALUE 512.
       78  ESQL-UDISP-SIGN-LEAD-SEP-NULL   VALUE 513.
       78  ESQL-UDISP-SIGN-TRAIL-SEP       VALUE 514.
       78  ESQL-UDISP-SIGN-TRAIL-SEP-NULL  VALUE 515.
       78  ESQL-UDISP-SIGN-LEAD-INC        VALUE 516.
       78  ESQL-UDISP-SIGN-LEAD-INC-NULL   VALUE 517.
       78  ESQL-UDISP-SIGN-TRAIL-INC       VALUE 518.
       78  ESQL-UDISP-SIGN-TRAIL-INC-NULL  VALUE 519.

       78  ESQL-WCHAR                      VALUE 1080.
       78  ESQL-WCHAR_NULL                 VALUE 1081.
       78  ESQL-WVARCHAR                   VALUE 1090.
       78  ESQL-WVARCHAR_NULL              VALUE 1091.
       78  ESQL-WLONGVARCHAR               VALUE 1100.
       78  ESQL-WLONGVARCHAR_NULL          VALUE 1101.

       78  ESQL_UTINYINT                   VALUE 1200.
       78  ESQL_UTINYINT_NULL              VALUE 1201.
       78  ESQL_USMALLINT                  VALUE 1202.
       78  ESQL_USMALLINT_NULL             VALUE 1203.
       78  ESQL_UINTEGER                   VALUE 1204.
       78  ESQL_UINTEGER_NULL              VALUE 1205.
       78  ESQL_UBIGINT                    VALUE 1206.
       78  ESQL_UBIGINT_NULL               VALUE 1207.

       78  ESQL-PICX-VARYING               VALUE 1208.
       78  ESQL-PICX-VARYING-NULL          VALUE 1209.
Parent topic: Data Structures
Related concepts
The SQL Descriptor Area (SQLDA)
The OPEN or EXECUTE Statements


Keywords

The following words are recognized by OpenESQL. Not all are currently used. Some are reserved for future enhancements, or for compatibility with other Embedded SQL implementations. Absence of a word from this list does not imply that ODBC drivers which use the word are not supported.

  • ALL
  • APPLICATION
  • ANSI
  • AS
  • AT
  • AUTOCOMMIT
  • BEGIN
  • BIND
  • BROWSE
  • BY
  • CALL
  • CLOSE
  • COMMIT
  • COMMITED
  • CONCURRENCY
  • CONNECT
  • CONNECTION
  • CONTINUE
  • CUR_BROWSE
  • CUR_STANDARD
  • CURRENT
  • CURSOR
  • CURSORTYPE
  • DATABASE
  • DATE
  • DBLIBVER
  • DECLARE
  • DEFAULT
  • DELETE
  • DESCRIBE
  • DESCRIPTOR
  • DISCONNECT
  • DO
  • DSN
  • DYNAMIC
  • END
  • EXEC
  • EXECSP
  • EXECUTE
  • ESQL_VERSION
  • FETCH
  • FETCHBUFFER
  • FIRST
  • FOR
  • FORWARD
  • FOUND
  • FROM
  • GET
  • GO
  • GOTO
  • HDBC
  • HENV
  • HOLD
  • HOST
  • IDENTIFIED
  • IMMEDIATE
  • IN
  • INCLUDE
  • INDICATOR
  • INOUT
  • INPUT
  • INSENSITIVE
  • INTO
  • ISARRAY
  • ISOLATION
  • KEYSET
  • LAST
  • LIST
  • LOCK
  • LOCKCC
  • LOGINTIME
  • MIXED
  • NEXT
  • NO
  • NOT
  • OF
  • OFF
  • ON
  • ONLY
  • OPEN
  • OPTCC
  • OPTCCVAL
  • OPTIMISTIC
  • OPTION
  • OUT
  • OUTPUT
  • PERFORM
  • PREPARE
  • PREVIOUS
  • PRIOR
  • PROMPT
  • QUERY
  • QUERYTIME
  • READ
  • READONLY
  • RECOMPILE
  • RELEASE
  • REPEATABLE
  • RESET
  • RETURNING
  • ROLLBACK
  • SAVE
  • SCROLL
  • SCROLLOPTION
  • SECTION
  • SELECT
  • SENSITIVE
  • SERIALIZABLE
  • SET
  • SQLCA
  • SQLERROR
  • SQLDA
  • SQLSERVER95
  • SQLWARNING
  • STANDARD
  • STATEMENT
  • STATIC
  • TIME
  • TIMESTAMP
  • TO
  • TRAN
  • TRANSACTION
  • UPDATE
  • USER
  • USING
  • UNCOMMITED
  • VARIABLES
  • WHENEVER
  • WITH
  • WORK

The following words are reserved for use in ODBC function calls by the ODBC specification.

  • ABSOLUTE
  • ACTION
  • ADA
  • ADD
  • ALL
  • ALLOCATE
  • ALTER
  • AND
  • ANY
  • ARE
  • AS
  • ASC
  • ASSERTION
  • AT
  • AUTHORIZATION
  • AVG
  • BEGIN
  • BETWEEN
  • BIT
  • BIT_LENGTH
  • BOTH
  • BY
  • CASCADE
  • CASCADED
  • CASE
  • CAST
  • CATALOG
  • CHAR
  • CHAR_LENGTH
  • CHARACTER
  • CHARACTER_LENGTH
  • CHECK
  • CLOSE
  • COALESCE
  • COBOL
  • COLLATE
  • COLLATION
  • COLUMN
  • COMMIT
  • CONNECT
  • CONNECTION
  • CONSTRAINT
  • CONSTRAINTS
  • CONTINUE
  • CONVERT
  • CORRESPONDING
  • COUNT
  • CREATE
  • CROSS
  • CURRENT
  • CURRENT_DATE
  • CURRENT_TIME
  • CURRENT_TIMESTAMP
  • CURRENT_USER
  • CURSOR
  • DATE
  • DAY
  • DEALLOCATE
  • DEC
  • DECIMAL
  • DECLARE
  • DEFAULT
  • DEFERRABLE
  • DEFERRED
  • DELETE
  • DESC
  • DESCRIBE
  • DESCRIPTOR
  • DIAGNOSTICS
  • DISCONNECT
  • DISTINCT
  • DOMAIN
  • DOUBLE
  • DROP
  • ELSE
  • END
  • END-EXEC
  • ESCAPE
  • EXCEPT
  • EXCEPTION
  • EXEC
  • EXECUTE
  • EXISTS
  • EXTERNAL
  • EXTRACT
  • FALSE
  • FETCH
  • FIRST
  • FLOAT
  • FOR
  • FOREIGN
  • FORTRAN
  • FOUND
  • FROM
  • FULL
  • GET
  • GLOBAL
  • GO
  • GOTO
  • GRANT
  • GROUP
  • HAVING
  • HOUR
  • IDENTITY
  • IMMEDIATE
  • IN
  • INCLUDE
  • INDEX
  • INDICATOR
  • INITIALLY
  • INNER
  • INPUT
  • INSENSITIVE
  • INSERT
  • INT
  • INTEGER
  • INTERSECT
  • INTERVAL
  • INTO
  • IS
  • ISOLATION
  • JOIN
  • KEY
  • LANGUAGE
  • LAST
  • LEADING
  • LEFT
  • LEVEL
  • LIKE
  • LOCAL
  • LOWER
  • MATCH
  • MAX
  • MIN
  • MINUTE
  • MODULE
  • MONTH
  • MUMPS
  • NAMES
  • NATIONAL
  • NATURAL
  • NCHAR
  • NEXT
  • NO
  • NONE
  • NOT
  • NULL
  • NULLIF
  • NUMERIC
  • OCTET_LENGTH
  • OF
  • ON
  • ONLY
  • OPEN
  • OPTION
  • OR
  • ORDER
  • OUTER
  • OUTPUT
  • OVERLAPS
  • PAD
  • PARTIAL
  • PASCAL
  • PLI
  • POSITION
  • PRECISION
  • PREPARE
  • PRESERVE
  • PRIMARY
  • PRIOR
  • PRIVILEGES
  • PROCEDURE
  • PUBLIC
  • READ
  • REAL
  • REFERENCES
  • RELATIVE
  • RESTRICT
  • REVOKE
  • RIGHT
  • ROLLBACK
  • ROWS
  • SCHEMA
  • SCROLL
  • SECOND
  • SECTION
  • SELECT
  • SEQUENCE
  • SESSION
  • SESSION_USER
  • SET
  • SIZE
  • SMALLINT
  • SOME
  • SPACE
  • SQL
  • SQLCA
  • SQLCODE
  • SQLERROR
  • SQLSTATE
  • SQLWARNING
  • SUBSTRING
  • SUM
  • SYSTEM_USER
  • TABLE
  • TEMPORARY
  • THEN
  • TIME
  • TIMESTAMP
  • TIMEZONE_HOUR
  • TIMEZONE_MINUTE
  • TO
  • TRAILING
  • TRANSACTION
  • TRANSLATE
  • TRANSLATION
  • TRIM
  • TRUE
  • UNION
  • UNIQUE
  • UNKNOWN
  • UPDATE
  • UPPER
  • USAGE
  • USER
  • USING
  • VALUE
  • VALUES
  • VARCHAR
  • VARYING
  • VIEW
  • WHEN
  • WHENEVER
  • WHERE
  • WITH
  • WORK
  • WRITE
  • YEAR
  • ZONE
Parent topic: Reference
Related concepts
Keywords
Related reference
EXECUTE IMMEDIATE


Data Files

  • Data File Tools
  • Rebuild
    Rebuild is a file management utility invoked from the command line. It enables you to perform a number of actions on indexed data files, such as repairing or reorganizing them.
Parent topic: Data Access


Data File Tools

  • Data File Editor
    Micro Focus Data File Editor is a standalone record editor in which to create and edit data files for use in your COBOL testing environment.
  • File Conversion Utilities
    This chapter describes utilities provided to help you move files between the mainframe and the PC.
Parent topic: Data Files


Data File Editor

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

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.
  • The only supported UNIX platforms are SUSE, Red Hat, Solaris SPARC, and AIX.
  • There is no support for Unicode files.
  • There is no file conversion functionality; use the DFCONV command line utility if you require this 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
  • National data items are not supported in record or segment layouts.
  • 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; you can only edit in Overwrite mode.
  • If you are using Data File Editor through a ViewNow X Window, you must have installed the additional ViewNow HotFix file that is included with your product installation; see Installing X Windows on Windows of your development product help for more details.
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 Shell Prompt
Parent topic: Data File Editor


Launching Data File Editor from a Shell Prompt

Use the following syntax to launch Data File Editor from your shell prompt:

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.
Parent topic: Accessing Data File Editor


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 [image] and [image] icons to navigate the pages of records.
Note: You must restart Data File Editor before any changes to this setting take effect.
Temporary Directory
Set the location of a temporary directory that is required in order to filter a data file. You can specify either an absolute or a relative (to the current working directory) path. An invalid path, or no path at all, will produce an error when you attempt to apply a filter.
Padding Character
Each new record is immediately padded with the characters you specify here for both ANSI and EBCDIC encoding. Enter the character in the top cell of the box next to the encoding name.

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.

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.

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; for more information, refer to the keytool utility documentation on the Oracle web site (http://docs.oracle.com/en/java/).

  • 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 [image] (Preferences).

    The Preferences dialog box appears.

  2. To set the amount of records per page, in the Miscellaneous section, enter the number of records in the Records per page field. The maximum number of records you can have per page is 10,000.
    Note: You must restart Data File Editor before any changes to this setting take effect.
  3. To set the temporary directory, which is required to apply a filter to a data file, either type a valid path, or click Browse and select one.
    Note: You can enter a relative path, which will be relative to the current working directory.
  4. To specify the padding character, in the top cell of the box next to the required encoding name, enter the character: its hexadecimal equivalent is displayed beneath.
  5. Click OK.

    The dialog box is closed.

Parent topic: Preferences


Using the Data File Editor

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.
  • Viewing and Filtering Data Files
    Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File 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
    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 to filename.pro check box on the Create New File dialog box.

For indexed files, you can also define the required indexed keys.

  • Create a Non-indexed Data File
  • Create an Indexed Data File
Parent topic: Using the Data File Editor


Create a Non-indexed Data File

Use this procedure to create a (record) sequential, line sequential, or relative data file. To create an indexed data file, see Create an Indexed Data File.

  1. From the Micro Focus Data File Tools window, select File > New, or click [image] (New File).

    The New dialog box appears.

  2. Select Data File, then click OK.

    The Create New File dialog box appears.

  3. In the Filename field, type the name of the data file.
    Tip: You can specify:
    • An absolute path: for example, /home/path/to/file/dat-name.dat.
      Note: Using an absolute path is only applicable when creating a file locally; if you are creating a file remotely (for example, from Windows), you must map a SAMBA drive and prepend the drive to the path.
    • 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 filename.pro 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. 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 [image] (New File).

    The New dialog box appears.

  2. Select Data File, then click OK.

    The Create New File dialog box appears.

  3. In the Filename field, type the name of the data file.
    Tip: You can specify:
    • An absolute path: for example, /home/path/to/file/dat-name.dat.
      Note: Using an absolute path is only applicable when creating a file locally; if you are creating a file remotely (for example, from Windows), you must map a SAMBA drive and prepend the drive to the path.
    • 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.

  8. Add a primary key:
    1. On the Key tab, click [image] (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 [image] (Insert After), select the new component and specify the key values.
      Tip: To delete a component, select it, then click [image] (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 [image] (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 [image] (Insert After), select the new component and specify the key values.
      Tip: To delete a component, select it, then click [image] (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.

  • 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
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. The procedure to open a data set in the Data File Editor is different from opening a data file, but once opened in the editor, edit it in the same way as you would a data file.

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.

Data sets will usually be opened through a Fileshare server running in the region that you connect to. Although, this does not have to be the case if you are opening data sets on a local region, as you can bypass Fileshare and open them directly, which can give faster access. In fact, in this scenario Fileshare does not even need to be configured.

If you are attempting to open data sets on a remote enterprise server region (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.

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.

  • Opening a Data Set in Enterprise Server
  • Error Messages When Using Data File Editor with Enterprise Server
Parent topic: Editing Data Files
Related reference
Getting Started with Auditing (deprecated)
Related information
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


Opening a Data Set in Enterprise Server

Before you start, you must ensure that the Enterprise Server region is running; additionally, if you are connecting to a remote Enterprise Server, you must set the CCITCP2 environment variable in your environment to the IP address of the Enterprise Server with which you are going to connect, and a Fileshare server must be running within the region.
  1. In the Micro Focus Data File Tools window, select File > Open Dataset, or click [image] (Open Dataset).

    The Open Dataset dialog box appears.

  2. In the ES Region section, enter the connection details for the region that contains the data set:, type the IP address or network name in the Host field, and the port number in the ESMAC Port field.
    1. If the connection is via SSL, check Use SSL.

      For more information about enabling SSL connections, see the Security section in Preferences.

    2. In the Host field, type the network name or IP address of the region containing the data set.
    3. 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. In the Authentication section, if the region has an external security manager enabled, type the ID and group for a user that has access to the data set you intend to edit. If the region does not have an external security manager enabled, do not enter any details in these fields.
    Tip: If you will be opening more than one data set from the region, select Save password for this session to save having to enter the password each time you open a data set.
  4. If you only want to display a subset of the data sets in the catalog, 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).
  5. Click Get Datasets.

    You connect to the Enterprise Server region specified, and the data sets that match the filter and that you have permission to update appear. If you are using authentication details, and they are either incorrect or do not grant access to any data sets, a message appears.

  6. In the Available Datasets section, highlight the required data set and click Open.

    The Use Fileshare dialog box appears.

  7. If you are opening a data set on a remote Enterprise Server, in the Fileshare Server section, check Use Fileshare, then type the name of a Fileshare server running on the remote Enterprise Server. (If the Enterprise Server is on this machine, you do not need to enter any details.)
  8. Click OK.

    The Open Data File dialog box appears.

  9. Complete the Open Data File dialog box as you would for any other data file, then use the Data File editor, again, as you would for any other data file.
    Note: Structure files must be stored locally; therefore, if you open a remote data set, you must select any required structure file for it each time the data set is opened.
Parent topic: Working with Data Sets in Enterprise Server
Related concepts
Preferences
Related information
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 SupportLine.
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 SupportLine.
  • 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 SupportLine.
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 SupportLine.

Parent topic: Working with Data Sets in Enterprise Server
Related information
Opening a Data Set in Enterprise Server


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 [image] (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.

  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.

    The editor switches to Insert mode, as indicated in the status bar.

  4. If the data file is unformatted (that is, not using a record layout), type the new record text in the free-text editing field in the bottom pane, then press Enter.

    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 [image] (Save Record) to save the record.
  7. Click Yes to confirm.

    The new record is inserted.

Parent topic: Editing Data Files
Related concepts
Create an Indexed Data File
Create a Non-indexed Data File
Related reference
Preferences
Related information
Working with Data Sets in Enterprise Server
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.
  1. In the Micro Focus Data File Tools window, ensure you have an unformatted data file open. If you are in Shared mode, click [image] (Switch to Exclusive Mode).
  2. Select the required record to edit, then click [image] (Edit Record).

    The record text in the bottom pane becomes editable.

  3. Edit the text in the bottom pane, then click [image] (Save Record).
    Tip: When editing records and fields, you can edit in Overwrite or Insert mode, which works much the same as it does on any conventional word processing package. 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, and the data file is saved automatically.

Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
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.
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 a formatted data file open. If you are in Shared mode, click [image] (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 [image] (Edit Record).

    The field becomes editable.

  4. Edit the text in the field, then click [image] (Save Record).
  5. Click Yes to confirm.

    The record is updated, and the data file is saved automatically.

Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
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

Restriction: You cannot use the Duplicate Record option for indexed file types.
  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 [image] (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.

    The record is duplicated.

    Note: You are not required to save the new record when duplicating records.
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
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a record


Layout and Field Validation

When using a record layout, the following validation occurs:

  • The data in each field is validated to ensure is it compatible with the field's PICTURE string, which is determined by the structure file. The validation uses the same logic as is used in your COBOL system; for example, a character in a COMP 9 USAGE DISPLAY field is invalid.
  • The size of the record layout is validated to ensure that it is within the bounds of any minimum or maximum record length specified for the data file.

If any field within a record is invalid or the size of the layout is outside the bounds of minimum or maximum record length, the whole record is marked as invalid, as indicated by [image] displayed beside the name of the layout in use. In the case of an invalid field, 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, [image] is displayed beside the name of the layout.

You can filter on invalid (and valid) records using the normal filtering process, by specifying the Is Invalid (and Is Valid) operator(s).

  • Fix Validation Warnings
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
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 [image] (Edit Record) to enter Edit mode.
    Tip: A record that has an invalid field displays [image] 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 [image] (Save Record).
    Tip: When editing records and fields, you can edit in Overwrite or Insert mode, which works much the same as it does on any conventional word processing package. 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, [image] 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 [image] (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.

  4. Type a new two-digit/character hex pair, then click [image] (Save Record).
    Note: You cannot enter a numerical or character value if it results in an invalid hex pair.
  5. Click Yes to confirm.

    The ANSI/EBCDIC character is updated, and the data file is saved automatically.

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
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 [image] (Switch to Exclusive Mode).
  2. In the left-hand pane, right-click the required record, then click Delete Record.

    The record is deleted, and the data file is saved automatically.

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


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.

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


Viewing and Filtering Data Files

Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File 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.

There are also navigational arrows (or you can use the cursor keys) to move from one record to the next. You can also jump directly to a record by entering the record number in the Record Number box.

For larger data files, an easier solution is to filter the file on specific information. The filter allows you to use multiple criteria in order to filter the records that are displayed. After the filter has been applied, you can switch between the entire file and the filtered results using the Records option.

  • View File Information
  • Filtering a Data File
  • Navigate a Data File
  • Show the Contents of a Data File in Hexadecimal
  • Select the Encoding for a Data File
  • Order a Data File using Indexed Keys
Parent topic: Using the Data File Editor
Related reference
Creating Structure Files and Layouts


View File Information

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] (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 and Filtering Data Files
Related information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Filtering a Data File

Applying a filter to the current data file enables you to limit the amount of records that are displayed at a time.

Your filter is defined by one or more conditions, and you can produce filtered results that include records matching all or any one of those conditions.

There are two types of condition that you can use:

Reference condition
A reference condition uses the same principles as reference modification in your COBOL syntax. You specify the starting position within a record in which to start filtering, and then specify the number of positions on from that in which to filter; for example, values of 7:3 will filter on positions 7 to 9 within each record, as indicated below

Field condition
This type of condition is only available if you have applied a layout to your data file. A field condition 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 a value that you wish to filter and an operator (for example, greater than, contains, or not equal to). There are also supplementary criteria to add to the condition, such as making it case sensitive, or trimming leading or trailing space from the area filtered.

Data File 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.

  • Filter the Data File
  • Filter Operators
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Filter the Data File

The results of a filter include each record that contains data that satisfied the conditions.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] (Filter).

    The Filter dialog box appears.

    Note: If a message appears warning you that a valid temporary directory does not exist, on the Tools menu, click Preferences, enter a valid directory in the Temporary Directory field, then repeat the last step.

    Filters are constructed by adding one or more conditions.

  6. To add a reference condition:
    1. Click New Ref.

      The basic filter elements appear.

    2. In the Field field, enter the start position and the number of positions on from that in which to filter on within each record; for example, values of 7:3 will filter on positions 7 to 9 within each record, as indicated below:

    3. In the Alphanumeric field, click [image] and select the type of text to filter: Text or Numeric.
    4. In the Operator field, click [image] and select the required operator.
    5. In the Value field, enter the filter value.
    6. (Optional) Select Trim to remove any leading or trailing spaces, or leading zeroes from each record before it is filtered.
    7. (Optional) Select Case to ensure the filtered content is case sensitive.
  7. To add a field condition:
    Note: This type of condition is only available if you are using a layout.
    1. Click New Field.

      The basic filter elements appear.

    2. In the Field field, click [image] and select the field on which to filter.
      Note: Group fields are not available to select.

      The Alphanumeric field is updated based on the type of field selected.

    3. In the Operator field, click [image] and select the required operator.
    4. In the Value field, enter the filter value.
    5. (Optional) Select Trim to remove any leading or trailing spaces, or leading zeroes from each record before it is filtered.
    6. (Optional) Select Case Sensitive to ensure the filtered content is case sensitive.

    By default, a record must match all specified conditions to be included in the results.

  8. To base the results on a record matching any of the conditions, click Match one.

  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 [image] (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 Operators


Filter Operators

Use the following operators in a filter condition:

Operator | Description
= | Equals the given text
!= | Not equal to the given text
> | Greater than the given text
>= | Greater than or equal to the given text
< | Less than the given text
<= | Less than or equal the given text
Contains | Contains the given text
Does not contain | Does not contain the given text
Is Valid | Contents of field is valid
Is Invalid | Contents of field is invalid
Parent topic: Filtering a Data File
Related information
Filter the Data File


Navigate a Data File

There are a number of techniques that enable you to navigate around the data file.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] and [image].
      Note: Each page contains a maximum of 100 records, configurable from the Preferences dialog box.
    • To jump directly to a record, click [image] (Go to) then enter the record number in the Record Number field and click OK; alternatively, click the record in the Data File pane.
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Show the Contents of a Data File in Hexadecimal

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] (Toggle Hex).

    An additional pane is displayed beneath the Displaying Records pane, and if a record layout is being used, beneath the layout, both showing the equivalent hexadecimal digits for the selected data. Each pair of hex digits is arranged vertically; for example, when you edit ANSI data, an M is shown in hex as 4 with a D beneath.

    Tip: You can edit the hex values directly; see Edit a Record Using the Hexadecimal Values.
  6. To hide the Hex pane, click [image] (Toggle Hex) again.
Parent topic: Viewing and Filtering Data Files
Related tasks
Edit a Record Using Hexadecimal Values
Related information
View File Information
Filtering a Data File
Navigate a Data File
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Select the Encoding for a Data File

By default, the file is displayed using ANSI encoding.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] beside ANSI, then select another encoding.

    The data file is displayed using the selected encoding.

Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Order a Data File using Indexed Keys


Order a Data File using Indexed Keys

You can only perform this action with indexed files, where you can order the records by any of the keys configured when the data file was created.
  1. From the Micro Focus Data File Tools window, click File > Open > File, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 [image] beside Primary Key, then select an alternate key to order your data file by.

    The data file is ordered (ascending order) using the key value.
    Note: The ordering starts at the currently selected record. For example, if you have the fifth record in a list selected when you sort on a different key, that record will remain fifth in the list, and the sixth record onwards will be sorted, in ascending order, using the key value. There will also be four records before the current record, which will be sorted in descending order using the key value. This may mean that not all records from the data file are displayed.
  6. To order based on a particular value (without having to select the record containing that value):
    1. Click [image] beside the key name.

      The Go to :<key-name> dialog box appears.

    2. Type the value on which to search, then click OK.
    Note: If you select a split key, type the required value(s) in the relevant component boxes.

    The data file is ordered (ascending order) using the key value(s).

  7. To re-display the original order of the data file, click [image], which is displayed just above the records, on the left-hand side.
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File


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. If you are using a structure file, you can even compare only individual fields within each record.

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.

  2. Select the two data files to compare:
    1. In the File 1 section, click [image] 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. If you plan to compare using a structure file, select the structure (.str) file to be used for both data files:
    1. Select Use structure?.
    2. Click [image] (Select file) and 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.
  4. In the Compare mode section, select one of the following modes:
    Option | Description
    Compare records sequentially | The records are compared in the exact order that they appear in the two files.
    Compare the differences between records | Not currently available
  5. 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.
  6. 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.
  7. Click OK.

    The records from the two files are display unformatted, side by side; records containing differences are highlighted.

  8. 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.
Parent topic: Comparing Data Files


Viewing Merged Spool Files

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.

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: Using the Data File Editor


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


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 [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. Click Backup.

    The Save dialog box appears.

  4. If required, edit the default name and location, then click Save.

    A copy of the data file is created.

Parent topic: Backing Up Data Files


Using the Structure File Editor

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

  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.

    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 [image] (Default) and [image] (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:

    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.

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 [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required structure file, then click Open.
    Tip: Click [image] beside Files of type, then select Structure Files (.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


File Conversion Utilities

File Conversion Utility | Use to...
DFCONV | Convert downloaded data files to the required format on the PC
  • DFCONV Batch File Conversion
Parent topic: Data File Tools


DFCONV Batch File Conversion

The DFCONV utility, also known as the Data File Converter, converts data files. The utility provides a batch and called program interface to enable conversion of file formats, organizations and data formats and reorganization of indexed files using data file conversion profiles.

Use the Data File Converter to:

  • Convert data files downloaded to a PC from a mainframe
  • Convert PC data files to VRECGEN2 format files for sending to the mainframe
  • Convert report files from mainframe to PC formats and vice versa
  • Convert files between EBCDIC and ANSI or ASCII data formats
  • Convert floating-point formats
  • Reorganize file structures
  • Convert multiple record types
  • Convert Micro Focus format files to Btrieve format files and vice versa
  • Act as a batch interface
Note:
  • To convert between character sets on records with non-text data items; that is, COMPUTATIONAL data and numeric data, you must have previously created a record layout file. For more information on how to create a record layout file, see the topic To create a record layout file.
  • Operation
  • Using the Data File Converter
  • Data File Converter Error Messages
Parent topic: File Conversion Utilities


Operation

The following operations are available in the Data File Converter:

  • Command Line Batch Interface
Parent topic: DFCONV Batch File Conversion


Command Line Batch Interface

The command line is:

dfconv [-d] profile-fname [input-fname] [output-fname]
where the parameters are:
-d
Stops the display of the data file convert console messages (optional).
profile-fname
The name of the profile file that contains the details of the task you need to perform.
Note: This file must have a .PRO extension. If you specify a file with any other extension, DFCONV attempts to locate a profile file using the specified base-name and the .PRO extension.
input-fname
The name of the input file (optional).
output-fname
The name of the output file (optional).

The input and output file-names are optional as they can be extracted from the profile file. If you specify file-names on the command line as well as in the profile file, those on the command line take precedence.

After conversion, the operating system error level is set to non-zero if an error occurred during conversion. If you are running the conversion from a batch file, you can interrogate this to determine what action to take after the conversion.

Parent topic: Operation
Related information
Defining File Conversion with a Profile File


Using the Data File Converter

The following sections describe how to use the Data File Converter to convert data files and rebuild file indexes.

  • File Format and Data Conversion
  • EBCDIC to ANSI Conversion
  • Mainframe to PC Print Conversion
  • Indexed File Reorganization
  • Defining File Conversion with a Profile File
Parent topic: DFCONV Batch File Conversion


File Format and Data Conversion

Converting files from one format to another enables data to be restructured from one format to another. For example, you can convert from sequential organization to indexed organization. You can also add extra secondary indices as the needs of an application change. When using the Data File Converter, you do not need to recreate data already produced or write special conversion programs.

Although many file transfer packages convert files from one format to another, they are restricted to converting the whole file to the other data format. Typical COBOL data files and database records have complex record structures with a mix of text and binary data that must be translated accordingly. The GUI version of the Data File Converter provides an easy method for data conversion using record layout descriptions. For more information on how to create a record layout file, see To create a record layout file.

The Data File Converter can also convert internal floating-point formats between IEEE format and S/370 format.

Parent topic: Using the Data File Converter
Related information
EBCDIC to ANSI Conversion
Mainframe to PC Print Conversion
Indexed File Reorganization
Defining File Conversion with a Profile File


EBCDIC to ANSI Conversion

A mainframe file should be transferred to the PC in binary format. If, initially, this file is a variable-length indexed file, use the mainframe program VRECGEN to perform an initial reformat of the file on the mainframe. The Data File Converter can then process the downloaded file.

Parent topic: Using the Data File Converter
Related information
File Format and Data Conversion
Mainframe to PC Print Conversion
Indexed File Reorganization
Defining File Conversion with a Profile File


Mainframe to PC Print Conversion

A mainframe report format file is either a file downloaded to the PC from the mainframe or a file created by an application, downloaded to the PC and run on the PC.

A mainframe report format contains carriage-control characters which are converted by the Data File Converter to PC printable formats. When defining the mainframe report files, the record length includes the carriage-control character and the records must be fixed length. In PC Print files, the record length is solely the data length.

You can print the PC print format files on any standard ANSI printer capable of printing 132 characters per line. As some ANSI printers print only 80 characters per line, you might have to print your files in compressed mode to achieve this.

If you specify the input file as a mainframe report format file, but it was created on the PC using a downloaded mainframe application, you may receive error message 139 ("Input file not "real" mainframe report format"). This can occur if the printer output has been created in PC format rather than the mainframe report format. Check directives used to control the compilation and execution of the program.

The Data File Converter provides specific support for conversion between Mainframe Report files and PC Print files. Conversion to or from these formats to other formats is not supported.

Parent topic: Using the Data File Converter
Related information
File Format and Data Conversion
EBCDIC to ANSI Conversion
Indexed File Reorganization
Defining File Conversion with a Profile File


Indexed File Reorganization

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. By ensuring that the input and output file settings are identical, the data and indices can be rebuilt in an ordered sequential manner, reclaiming any free space, and so providing optimum file performance and integrity.

Parent topic: Using the Data File Converter
Related information
File Format and Data Conversion
EBCDIC to ANSI Conversion
Mainframe to PC Print Conversion
Defining File Conversion with a Profile File


Defining File Conversion with a Profile File

This section describes the entries required in the profile file to convert a file, or to restructure a file from one organization to another. For example, you might need to do one of the following:

  • Add extra secondary indices to an indexed file
  • Convert a sequential or relative file to an indexed file
  • Convert an indexed file to a relative file
  • Convert a blocked variable length file to a sequential file

Example profile files

The first record in the file identifies the format of the profile file. The profiles used by DFCONV are the same format as used with earlier Workbench.

Example 1:
DFS Profile File Version  V09.B01.07

Batch-Process: Convert-file
                   ***************************************************
                   *           (Twin)                  (Single)      *
                   * Options:  Convert-File            Rebuild-index *
                   *           Rebuild-index-and-data  None          *
                   ***************************************************
Strt-file:              drive:\path\filename.STR
Edit-Mode:     Quick
                   * Options:  Quick/Full                            *
--------------------------------------------------------------------------------
Input-File     drive:\path\inputfile.dat
   Format:         Micro-Focus
                       * Options:  Micro-Focus         IDXFORMAT(4)  *
                       *           Btrieve             C-ISAM        *
                       *           LEVEL-II            ESDS          *
   Organization:   VRECGEN
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    Mainframe-Report-mach *
                       *           VRECGEN     PC-Print              *
   Record-Format:  Variable
                       * Options:  Fixed/Variable                    *
   Character-Set:  EBCDIC
                       * Options:  ASCII/EBCDIC                      *
   Floating-Point: 370
                       * Options:  IEEE/370                          *
   Compression:    Off
                       * Options:  On/Off                            *
   Min-Rec-Length: 352
   Max-Rec-Length: 633
--------------------------------------------------------------------------------

Output-File    drive:\path\outputfile.dat
   Format:         Micro-Focus
   Organization:   Indexed
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    PC-Print              *
                       *           VRECGEN2                          *
   Record-Format:  Variable
   Character-Set:  EBCDIC
   Floating-Point: 370
   Compression:    Off
   Min-Rec-Length: 352
   Max-Rec-Length: 633
                       * Key to settings                             *
                       *       d=      allow duplicates              *
                       *       s=      sparse character set          *
                       *       Compression                           *
                       *           cd= on duplicates                 *
                       *           cl= on leading spaces             *
                       *           ct= on trailing spaces            *
   Prime-key :   1:1, 2:6

   Alt-Key  1:   8:1
                 d,cl
   Alt-Key  2:   9:1
                 d,cd,ct
   Alt-Key  3:   10:5
Example 2:
DataTools Profile Version  V09.B02.05

Batch-Process: Convert-file
                   ***************************************************
                   *           <Twin>                  <Single>      *
                   * Options:  Convert-File            Rebuild-index *
                   *           Rebuild-index-and-data  None          *
                   ***************************************************
Strt-file:     No-structure
Edit-Mode:     Full
                   * Options:  Quick/Full                            *
--------------------------------------------------------------------------------
Input-File     LP2293.QA.DAT
   Format:         Micro-Focus
                       * Options:  Micro-Focus         IDXFORMAT(4)  *
                       *           Btrieve             C-ISAM        *
                       *           LEVEL-II            ESDS          *
   Organization:   Blocked-VRec
                       * Options:  Sequential  Line-Sequential       *
                       *           Indexed     Mainframe-Report-ANSI *
                       *           Relative    Mainframe-Report-mach *
                       *           VRECGEN     PC-Print              *
                       *           Blocked-VRec                      *
   Record-Format:  Variable
                       * Options:  Fixed/Variable                    *
   Character-Set:  EBCDIC
                       * Options:  ASCII/EBCDIC                      *
   Floating-Point: IEEE
                       * Options:  IEEE/370                          *
   Compression:    Off
                       * Options:  On/Off                            *
   Min-Rec-Length: 500
   Max-Rec-Length: 500
--------------------------------------------------------------------------------

Output-File    LP2293-seq.dat
   Format:         Micro-Focus
   Organization:   Sequential
   Record-Format:  Variable
   Character-Set:  EBCDIC
   Floating-Point: IEEE
   Compression:    Off
   Min-Rec-Length: 500
   Max-Rec-Length: 500
  • Specifying the Conversion Operation
  • Specifying the Input File Parameters
  • Output File Specifications
  • General Conversion Information
Parent topic: Using the Data File Converter
Related information
File Format and Data Conversion
EBCDIC to ANSI Conversion
Mainframe to PC Print Conversion
Indexed File Reorganization
Command Line Batch Interface


Specifying the Conversion Operation

The operation to be performed is chosen as a parameter to the Batch-Process option.

Batch-Process
The operation to be performed on the defined files. Value must be Convert-file.
An Input-File and Output-File is defined.
Strt-file location\filename.str
The file containing the Record Layout descriptions for the input file.

If the data file is being converted between EBCDIC and ANSI and the records contain non-text data items, a record layout description is required to define the data items requiring conversion and those to be left unconverted (for example, binary values). The record layouts are created with the Record Layout Editor and stored in files with an .str file extension. For more information on how to create a record layout file, see the topic To create a record layout file.

Edit-Mode
The edit mode if this profile is read by the Data File Editor. Value must be either Quick or Full.

This parameter is not used by DFCONV.

Parent topic: Defining File Conversion with a Profile File
Related information
Specifying the Input File Parameters
Output File Specifications
General Conversion Information


Specifying the Input File Parameters

First of all, choose an input file:
Input-File
The input file name for the defined operation.
Then, use parameters to describe the input file:
Format
The file format for the input file. Valid values are:
  • Micro Focus
  • ESDS
  • Btrieve
  • IDXFORMAT(4)
  • Extended-ESDS
  • Vision
  • RM
  • C-ISAM
  • LEVEL-II
  • IDXFORMAT(8)
  • IDXFORMAT(12)

The default format is Micro Focus and this would normally be used for files downloaded from the host and recreated on the PC. If the chosen file is an emulation of the mainframe VSAM entry-sequenced data set, choose ESDS or Extended-ESDS to provide the emulation of VSAM ESDS on the PC.

Organization
The file organization for the input file. Valid values are:
  • Line sequential
  • Sequential
  • Indexed sequential
  • Relative
  • VRECGEN
  • ANSI Mainframe Report (The mainframe report with ANSI carriage control characters)
  • Machine Mainframe Report (The mainframe report with machine code carriage control characters)
  • PC Print.
  • Blocked-VRec
Record-Format
The record format for the input file. Valid values are:
  • Fixed
  • Variable

Variable length Mainframe Report files are not supported.

Character-Set
The character encoding used in the input file. Valid values are:
  • ASCII
  • EBCDIC
Note: The Windows environment uses the EBCIDIC and ANSI character encodings, and the UNIX/LINUX environments use the EBCIDIC and ASCII character encodings. The character encodings used in the ANSI and ASCII code pages are different.
Floating-Point
The type of floating-point format that is used in the input file.
  • IEEE
  • 370
Compression
An indication that data compression is used for the input file. Valid values are:
  • On
  • Off

This should only be set to On if the file was created with data compression.

Min-Rec-Length
The minimum record length for the input file.

If the file is fixed length this should be set to the same value as the maximum record length.

Max-Rec-Length
The maximum record length for the input file.
If the file being created is indexed, the keys are defined using the following records.
Prime-key
The start position of the key is either the column number or offset depending on the version of the profile being used. A colon is used to separate the position and length fields.
  • DFS Profile Files use a start position (column) starting at 1 with the prime key being in the format position:length (for example, 1:12).
  • DataTools Profiles use an offset starting at 0 with the prime key being in the format offset:length (for example, 1:12).
A second record in the profile file sets the key flags required for the indexed file being created. The flags are separated by a comma (for example: d,cd).
Flag | Description
d | allow duplicate record keys
s | sparse character - not supported
cd | compress duplicate record keys
cl | compress leading spaces on record keys
ct | compress trailing spaces on record keys
Parent topic: Defining File Conversion with a Profile File
Related information
Specifying the Conversion Operation
Output File Specifications
General Conversion Information


Output File Specifications

The Data File Converter can create a new output file or overwrite an existing output file. For new output files, you must provide all specifications manually. For existing output files, the Data File Converter picks up the organization and record format from the file automatically; however, you can change these before converting.

File Formats
We support the following file formats:
File Format | Purpose
C-ISAM | Emulates files from old systems
ESDS | Emulates VSAM ES files
IDXFORMAT(4) | When converting an input file that has many duplicate keys
IDXFORMAT(8) | For very large files
IDXFORMAT(12) | As IDXFORMAT(8), except it uses a separate file to store the indexed keys
Extended-ESDS | Emulates VSAM ES for very large files
Level-II | Emulates files from old systems
Micro Focus | In all other cases

The default format is Micro Focus, which is normally used for files downloaded from the host and recreated on the PC. If the chosen file is an emulation of the mainframe VSAM entry-sequenced data set, choose ESDS or Extended-ESDS to provide the emulation of VSAM ESDS on the PC.

File Organizations
We support the following file organizations:
  • Indexed sequential
  • Line sequential
  • Relative
  • Sequential
  • VRECGEN2
Maximum and Minimum Record Lengths
You can increase or decrease the minimum and maximum record length for the output file. The Data File Converter makes adjustments depending on the length of the original record and the specified new length, as explained in the following scenarios:
Increase the minimum record length
Records shorter than the new minimum length are filled in using the number of padding bytes needed to complete the record length.
Increase the maximum record length
Records are filled in using the number of padding bytes needed to complete the record length.
Decrease the maximum record length
Records longer than the new maximum length are truncated.
Note: If you request a conversion of a sequential file to an indexed file with unique keys and some of the records contain duplicate key values, the Data File Converter ignores these records and does not convert them. At the end of the conversion, the Data File Converter informs you of the number of records rejected.
Parent topic: Defining File Conversion with a Profile File
Related information
Specifying the Conversion Operation
Specifying the Input File Parameters
General Conversion Information


General Conversion Information

You should be aware of the following points when defining the input and output files:

  • If the chosen file type is indexed, variable-length sequential or variable-length relative:

    The record length information is extracted from the file header and replaces the record length information defined for the input file in the profile file

  • If the file type is Mainframe Report format:

    You should set the input record lengths and the output record lengths so that the record length of the mainframe Print Format file is one character longer to hold the carriage control characters

  • If a program calling DFCONV is compiled with CHARSET"EBCDIC":

    The Data File Converter cannot interpret the profiles sent to it; the File Converter applies only to DOS and ANSI based programs. To ensure correct processing, use an ANSI-based program to call the Data File Converter.

  • If the output file contains non-text data:

    The output file type you specify should not be line sequential. Extra bytes (X'00') are inserted into the ANSI line sequential record whenever a byte contains a value of X'1B' or less, this may result in unnecessarily large files. The extra bytes are include to provide NULL protection to data held in the line sequential file, these bytes would otherwise be interpreted as control characters used in this type of file.

Parent topic: Defining File Conversion with a Profile File
Related information
Specifying the Conversion Operation
Specifying the Input File Parameters
Output File Specifications


Data File Converter Error Messages

To see details on the error messages, click General Reference > Error Messages > Data File Converter Messages.

Parent topic: DFCONV Batch File Conversion
Related information
Data File Converter Error Messages


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
Related concepts
Indexed 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 TMPDIR to point to the directory where you would like to keep temporary files.
Parent topic: Rebuild
Related information
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Command Line

The format of the Rebuild command line is:

rebuild in-file [,out-file] [options]

Both in-file and out-file must include the filename extension. The filename of out-file must not be the same as in-file. You can use environment variables in place of in-file or out-file to implement filename mapping.

The options specified on the command line define the operation to be carried out by Rebuild.

  • Option Files
  • Redirection of Information
Parent topic: Rebuild
Related 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.

On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

The following options are available:

/c | Specifies file compression
/d | Reconstructs an index from the data area of an indexed file
/e | Reports illegal duplicate keys and continues processing. If more than 1000 illegal duplicate keys are found, the rebuild aborts, because it considers the file attributes being used conflict with the data in the file to an extent that any results could be meaningless.
/f | Validates indexed files
/i | Displays information about the files being processed
/k | Defines the key structure for an indexed file
/m | Reserved for future use
/n | Displays information about a file (no other processing is performed)
/o | Specifies the organization of the input and output files
/p | Rebuilds IDXFORMAT"8" file in place
/q | Quickly rebuilds index files using the index side file (IDXFORMAT"12")
/r | Defines the record structure of the input and output files
/s | Specifies the format of the input file
/t | Specifies the format of the output file
/u | Attempts to recover a file for which the last update operation was not completed
/v | Displays a record count which is incremented as the file is processed
/y | Forces Rebuild to ignore file size discrepancies
/x | Specifies the order in which data is written when reorganizing an indexed file
/z | Instructs Rebuild to use a Fileshare server for file access
//q | Suppresses display of the Rebuild banner
//v | Displays the version number of Rebuild

Options can be placed in any order on the command line, except that options beginning with a double 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}

On UNIX systems, replace the server-name prefix $$ with \$\$.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Callable Rebuild
Rebuild Examples


Callable Rebuild

You can call Rebuild from your COBOL program as follows:

call "callrb" using commands status

where:

Parameter: | Meaning:
commands | A PIC X(600) item containing the Rebuild command line. This item must be 600 bytes in length because Rebuild scans the command line backwards from offset 599.
status | A PIC XX COMP-X item containing the returned file status. This item shows the result of the call to Rebuild.

When called from within a program, Rebuild does not display any of its usual messages.

If an error occurs or the rebuild is unsuccessful, RETURN-CODE contains a non-zero value and status contains the returned file status. You should always check RETURN-CODE and status after a call to Rebuild.

The possible values of RETURN-CODE are shown below.

Value | Description
0 | Rebuild executed successfully
1 | An error occurred on the input file such as file not found or invalid file format - check status parameter
2 | An error occurred on the output file - check status parameter
3 | Error in sort
4 | File is corrupt
5 | Attempt to do a /k:a:exists
6 | Attempt to do a /k:r:onprime
7 | Attempt to do a /k:r:dontexist
8 | Too many duplicates on out
9 | The parameter list contained an error such as an invalid option or an invalid combination of options
10 | Rebuild has run out of memory

If an error occurs, execute Rebuild from the command line on the same file with a set of identical options. The screen output should give a more precise indication as to the cause of the error.

Note: If you are using the -f option (validate an indexed file), then any non-zero RETURN-CODE indicates that the file is corrupt. Again, execute Rebuild from the command line on the same file with a set of identical options to obtain more precise information.

The following example shows Rebuild being called from within a COBOL program.

 01 parameters   pic x(600).
 01 status       pic xx comp-x.
   ...
     move "infile.dat,outfile.dat -s:lii -c:d1" to parameters
     call "callrb" using parameters,status
     end-call
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Rebuild Examples


Rebuild Examples

On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

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


Database Connectors for Visual COBOL

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This guide describes Micro Focus Database Connectors for Visual COBOL.

  • Database Connectors User's Guide
  • Database Connectors Tasks
  • Database Connectors Reference
Parent topic: Data Access


Database Connectors User's Guide

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This section describes the concept of Database Connectors interfaces, and how to configure access to relational database management systems from COBOL.

  • Database Connectors Overview
    This section provides an overview of Micro Focus Database Connectors for Visual COBOL, and how you can use its interfaces to bridge the worlds of COBOL and Structured Query Language (SQL).
  • Getting Started
    This section is designed to get your started using Database Connectors after your installation.
  • XFDs
    This section explains the importance of Extended File Descriptors (XFDs), and how you understand and create them.
  • Using XFD Directives
    This section explains what XFD directives are, and how you can use them in your COBOL File Descriptors (FDs) to control how your database tables are built.
  • Invalid Data
    This section lists the COBOL data items that are considered invalid, and explains what happens to them when they are stored in the database. This section also covers database items that are considered invalid, and explains how those are translated to COBOL.
  • Working with COBOL
    This section explains how to prepare your COBOL programs for use with Database Connectors.
  • New and Existing Databases
    This section explains how to handle your data in both existing and new databases.
  • File Handling Configuration
    This section explains how to configure COBOL file handling operations to interact with supported RDBMS.
  • Run Time System Configuration
    Database Connectors uses an ACUFH configuration file to determine how the run time system should behave when interacting with data. This chapter describes how to configure the File Handler, and how to use ACUFH configuration variable options to configure the run time system for your relational database environment.
  • Database Connectors for DB2
    This appendix provides information that is specific to Database Connectors for DB2.
  • Database Connectors for Microsoft SQL Server
    This appendix provides information that is specific to Database Connectors for Microsoft SQL Server.
  • Database Connectors for ODBC
    This appendix provides information that is specific to Database Connectors for ODBC.
  • Database Connectors for Oracle
    This appendix provides information that is specific to Database Connectors for Oracle.
  • Performance and Troubleshooting
    This section provides some guidelines into improving performance when using Database Connectors. It also provides some reference topics to help troubleshoot some common problems.
  • Questions and Answers
    This section contains some answers to commonly asked questions, which apply to any of the relational database management systems you are using.
Parent topic: Database Connectors for Visual COBOL


Database Connectors Overview

This section provides an overview of Micro Focus Database Connectors for Visual COBOL, and how you can use its interfaces to bridge the worlds of COBOL and Structured Query Language (SQL).

It explains how to describe data in your COBOL programs and how to handle differences in the field names and data types that are passed between COBOL and the database engine.

  • Relational Database Management Systems Support
  • Accessing Data
  • Database Concepts
  • How Database Connectors Works
Parent topic: Database Connectors User's Guide


Relational Database Management Systems Support

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Database Connectors supports the following Relational Database Management Systems (RDBMS):
  • Oracle
  • DB2
  • Microsoft SQL Server
  • ODBC
RDBMS Support includes the following:
RDBMS | Latest Versions Tested | Probable compatibility, based on vendor information (Client/Server may be used for connecting to other versions)
Microsoft SQL Server | 2016 | Versions greater than 6.5
Oracle | 12c | Versions greater than 9i
DB2 | 10.5 | Versions greater than 8.1
ODBC | 3.0 | Versions greater than 3.0

Database Connectors uses standard COBOL I/O statements to access databases. It handles the translation between standard COBOL and the SQL used by the RDBMS.

Specific instructions and status messages apply to each type of RDBMS, and these are included in their own RDBMS-specific sections.

Parent topic: Database Connectors Overview
Related information
Accessing Data
Database Concepts
How Database Connectors Works
Database Connectors for DB2
Database Connectors for Microsoft SQL Server
Database Connectors for Oracle


Accessing Data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

COBOL systems include a standard file system, which can be configured to handle data in a format required by the supported RDBMS. Configuration is made simple, with the setting of the IDXFORMAT Compiler directive or File Handler configuration variable; see Configuring the File Handler for more information.

Extended File Descriptors (XFDs) files are another key component to interfacing successfully with an RDBMS. They are the files that map your COBOL records to database fields. it is important that you understand these, to understand how your COBOL data will be represented in a database. See XFDs for more information.

To then take that information and interface with one of the RDBMS, you need the specific database connector. These connectors are installed as part of your COBOL development installation, but you must license each one individually in order to use it.

Parent topic: Database Connectors Overview
Related reference
Configuring the File Handler
XFDs
Related information
Relational Database Management Systems Support
Database Concepts
How Database Connectors Works


Database Concepts

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Relational databases differ from indexed file systems in several significant ways. These are the logical associations between database concepts and COBOL indexed file concepts:

Indexed File Concept | Database Concept
Directory | Database
File | Table
Record | Row
Field | Column

Or, put another way:

  • Database operations are performed on columns. Indexed file operations are performed on records
  • A COBOL indexed file is logically represented in database table format. Within a table, each column represents one COBOL field; each row represents one COBOL record
  • Database table columns are strictly associated with a particular data type, such as date, integer, or character. In COBOL, data can have multiple type definitions

For example, for Oracle, a COBOL record that looks like this:

01  terms-record.
    03  terms-code        pic 999.
    03  terms-rate        pic s9v999.
    03  terms-days        pic 9(2).
    03  terms-descript    pic x(15).

would be represented in the database as a table with a format similar to this:

Name | Null | Type
TERMS_CODE | NOT NULL | NUMBER (3)
TERMS_RATE | – | NUMBER (4, 3)
TERMS_DAYS | – | NUMBER (2)
TERMS_DESCRIPT | – | CHAR (15)
Parent topic: Database Connectors Overview
Related information
Relational Database Management Systems Support
Accessing Data
How Database Connectors Works


How Database Connectors Works

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors implements a direct, transparent interface between COBOL and RDBMSs.

Previously, accessing a relational database from a COBOL program involved writing SQL code and embedding that code in your program. You had to know SQL, and you had to write SQL statements appropriate for the specific database you wanted to access. Because your queries were tailored to suit one database management system, you had to re-code your COBOL application if you wanted to access a different RDBMS, or an indexed file system, or even to migrate a file from one system to another.

As an alternative, some interface products now translate COBOL I/O statements into direct reads and writes on the database files, without going through the driver, or engine, supplied by the database manufacturer. This means that the COBOL programmer must provide for enforcement of database rules that the engine already knows about and is designed to handle. Bypassing the database engine also means that new constraints or changes in the database structure require reprogramming of the COBOL application.

Database Connectors implements a more suitable approach by dynamically generating industry standard SQL from COBOL I/O statements. As the run time system is executing your COBOL application, Database Connectors is running behind the scenes to match up the requirements and rules of both COBOL and the RDBMS to accomplish the task set by your application. This means that Database Connectors uses the full power designed into the database engine. The engine enforces database rules and constraints; any violations are returned to the COBOL program as I/O error conditions.

  • What Is a Transparent Interface?
  • XFDs and Mapping
  • Summary
Parent topic: Database Connectors Overview
Related information
Relational Database Management Systems Support
Accessing Data
Database Concepts


What Is a Transparent Interface?

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors provide a transparent, efficient interface between your program and the relational database. The interface is categorized as transparent because the communication between your COBOL program and the database is smooth, with no special query coding on your part and no interruptions in the execution of your program. You need not change your COBOL code if you later want to access a different database or to access an alternate indexed file system.

The information exchange operations between the database and the COBOL program are invisible to the end user. For example, if your program specifies a READ, a database query is automatically generated by the interface. Then the data that is read from the database is translated into a COBOL record. This exchange occurs in fractions of a second, and the application proceeds without interruption.

Parent topic: How Database Connectors Works


XFDs and Mapping

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Because relational databases handle I/O at the column (field) level, and COBOL handles I/O at the record level, some mapping is necessary to associate records with their fields. One function of Database Connectors is to map COBOL records into database fields, and to map the database fields back into records. Database Connectors does this by consulting XFDs generated by the Compiler. The detailed structure of XFDs is discussed in How XFDs are Formed.

Database Connectors builds its own database queries dynamically whenever an input or output request is received. You just compile your program, and Database Connectors does the rest.

Parent topic: How Database Connectors Works
Related reference
How XFDs are Formed


Summary

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors ensures that all database changes are immediately available to your COBOL program. It also ensures that all data updates to your COBOL program are immediately reflected in the database.

After your XFDs are generated, you can switch to a different RDBMS simply by setting the IDXFORMAT Compiler directive or file handling configuration option. No recompiling is necessary.

Because Database Connectors accesses the database through its native engine, the full relational integrity of the database is maintained. The COBOL program need not be concerned about such things as enforcing relationships between keys and foreign keys on tables or constraints on field relationships and contents.

If you have specified that a file is to reside on a RDBMS (by setting IDXFORMAT), an OPEN OUTPUT filename statement in your COBOL program generates a CREATE TABLE filename function on the specified host database. Appropriate permissions are granted based on login and password and access parameters; see the RDBMS-specific sections of this Help for specific details. For large tables, your systems database administrator can create the table and indexes for you. Databases offer many methods for creating tables that may improve performance for large tables, such as spreading the table across multiple hard drives or storing the data and the indexes on different drives.

Changes to the way a database functions should be carefully considered and tested before being fully implemented. If a database violation occurs, the engine detects it, and Database Connectors returns an I/O error condition to the COBOL program. The program can, if desired, call a standard COBOL library routine for an extended error description.

It is possible that there are library routines that do not work with or do not make sense to use with some of the Database Connectors interfaces. To find out if that is the case with your Database Connectors interface, look in the Common Questions and Answers section of the appendix specific to your interface.

Parent topic: How Database Connectors Works
Related reference
Configuring the File Handler


Getting Started

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

For installation instructions specific to the RDBMS you plan to use, see the specific links below. Once you have installed and configured the Database Connectors interface, refer to the Licensing section, and then to test the setup, run the demonstration program.

The Working with COBOL section also contains demonstration programs, which can be compiled and run to produce database tables.

  • Licensing
  • The Demonstration Program
Parent topic: Database Connectors User's Guide
Related reference
Installation and Setup on DB2
Installation and Setup on Oracle
Installation and Setup on Microsoft SQL Server
Working with COBOL


Licensing

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors is licensed through Sentinel RMS. Refer to the Managing Licenses section of the Help that is supplied with the Micro Focus License Manager for details on how to license Database Connectors.

Parent topic: Getting Started


The Demonstration Program

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

After your installation and setup are complete, you may run the demonstration program (demo.cbl), which can be found in the Connectors sub-directory within your $COBDIR/demo directory. This program illustrates many of the Database Connectors product capabilities, including how to:

  • Map RDBMS data types to traditional COBOL data types
  • Compile a COBOL program in preparation for interfacing with an RDBMS
  • Modify records within the RDBMS database

The demo program simulates what might be used in a distributor’s shipping department. You'll create a table named orderfile, which contains information about the orders placed by the distributor's customers. The orderfile table has the following columns of information (the database data type and COBOL data type are shown for each).

Note: The data type may be slightly different depending on your RDBMS.
Column Name | Data Type | COBOL PIC
ORDER_NUM | CHAR(4) | pic x(4)
ORDER_DATE | DATE | pic 9(6)
CUSTOMER_NUM | CHAR(3) | pic x(3)
SHIP_INSTRUCT | CHAR(40) | pic x(40)
BACKLOG | CHAR(1) | pic x
PO_NUM | CHAR(10) | pic x(10)
SHIP_DATE | DATE | pic 9(6)
SHIP_WEIGHT | NUMBER(8,2) | pic 9(6)v99
SHIP_CHARGE | NUMBER(6,2) | pic 9(4)v99
PAID_DATE | DATE | pic 9(6)

Here is the COBOL file descriptor (FD) that matches the orderfile table. Note that the FD entries must match the names of the RDBMS fields and must match their data types:

fd  orders.
01  order-record.
    03  order-num              pic x(4).
    03  order-fields.
        05  order-date         pic 9(6).
        05  customer-num       pic x(3).
        05  ship-instruct      pic x(40).
        05  backlog            pic x.
        05  po-num             pic x(10).
        05  ship-date          pic 9(6).
        05  ship-weight        pic 9(6)v99.
        05  ship-charge        pic 9(4)v99.
        05  paid-date          pic 9(6).
Tip: Database Connectors creates new tables in a target database when your COBOL application issues an OPEN OUTPUT command. If you turn on file tracing for a COBOL program that performs this operation on a target file, you can see the series of SQL statements generated by the run time system to create the database table, indexes, and access permissions. This can be useful should you wish to have a set of stand-alone SQL scripts to generate test databases or base set of tables for an end user install for your COBOL files to work with.
Parent topic: Getting Started
Related reference
XFDs
To compile and run the demo program


XFDs

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Extended File Descriptors (XFDs) map COBOL records to database fields. These are called XFDs because they're based on standard COBOL File Descriptors (FDs). An XFD file is created as an XML file. The XFD contains a description of a COBOL indexed, sequential, or relative file based on its fields. XFDs are used to interface to database management systems.

  • XFD Files
Parent topic: Database Connectors User's Guide


XFD Files

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To create an XFD, use the CREATEXFD directive. When you specify the CREATEXFD directive with no parameters, an .xfd file is created for each indexed data file specified in the compiled program. XFDs are generated in XML format in the latest XFD version available (Version 6). XFDs are stored in your source code directory by default.

Specify all to generate XFDs for all indexed, relative, and sequential files, and specify an XFD path if you want to store your XFDs in a directory other than your source code directory.

Once you compile with the CREATEXFD directive, each COBOL file has a corresponding .xfd file. The directive creates .xfd files without changing anything in the object code.

Creating XFD files at compile time offers two significant advantages:

  • Any changes made to the file definitions are automatically included in the XFDs when the program is recompiled
  • The effects of all compile-time options, COPY REPLACING, and source-code control lines are reflected correctly in the XFDs
  • How XFDs are Formed
  • Defaults Used in XFD Files
  • Summary of XFD Fields
  • Identical Field Names
  • Long Field Names
  • Naming the XFD File
  • Forming the Final XFD Name
  • Mapping Other Files to an XFD
Parent topic: XFDs
Related information
CREATEXFD directive


How XFDs are Formed

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

XFDs enable the interface to create a table (or access an existing one) in the database for each indexed file. Each column in the table contains the values for one field. The column names are essentially the field names.

The table that is built is based on the largest record in the COBOL file and contains the fields from that record plus any key fields (key fields are those that are named in KEY IS phrases of SELECT verbs in the FILE CONTROL section). This ensures that data from all COBOL records fit within the table and simplifies the storage and retrieval process. If you were to examine the database columns, only the fields from the largest record, and the key fields, would appear. For additional information, see Defaults Used in XFD Files.

Note: If the field named in the KEY IS phrase is a group item, it does not become a column in the database table. Instead, each of the elementary items subordinate to the named group item become a column. You can force a group item to be a column by using the USE GROUP XFD directive.

With multiple record formats (level 01), not all COBOL fields are represented in the database by name, but all fields are storable and retrievable. The XFD maps fields from all records of a file to the corresponding locations in the master (largest) record of the file, and thus to the database table. Since Database Connectors has access to the XFD, it knows where the data from a given COBOL record fits in the database tables. This activity is invisible to the COBOL application.

For example, if your program has one file with the three records shown below, the underlined fields are included in the database table by default (this example assumes that ar-codes-key is named in a KEY IS phrase). Some fields do not appear in the table, but the XFD maps them to the master field names. Database Connectors thus eliminates redundancies for optimum performance.

01  ar-codes-record.
    03  ar-codes-key.
        05  ar-code-type      pic x.
        05  ar-code-num       pic 999.
01  ship-code-record.
    03  filler                pic x(4).
    03  ship-weight           pic s999v9.
    03  ship-instruct         pic x(15).
01  terms-code-record.
    03  filler                pic x(4).
    03  terms-rate-1          pic s9v999.
    03  terms-days-1          pic 9(3).
    03  terms-rate-2          pic s9v999.
    03  terms-descript        pic x(15).

The following diagram shows how Database Connectors creates database columns for some of the fields in the COBOL record, while the XFD maps other fields to those columns; this means that all of the fields are accessible to the COBOL program.

Making Field Accessible to COBOL Programs

See Defaults Used in XFD Files for a description of rules that Database Connectors follows as it builds the database table and an explanation of how you can override those rules when necessary.

Parent topic: XFD Files
Related information
USE GROUP XFD directive
Defaults Used in XFD Files
KEY IS Phrase


Defaults Used in XFD Files

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Several elements of COBOL require special handling when XFDs are built. These include multiple record definitions REDEFINES, FILLER, and OCCUR. This section describes how the compiler handles each of these situations.

Note that in many instances you can override the default behavior described below by placing special comment lines in the FDs of your COBOL code. These comments are called XFD directives, and are described in Using XFD Directives. For example, the WHEN XFD directive lets you use multiple definitions for a single set of data by specifying when each definition should be used.

Databases generally do not support the notion of multiple definitions for the same column. As the following paragraphs explain, whenever a COBOL program gives more than one definition for the same data, the compiler chooses which definition to use in the XFD and disregards the rest.

  • KEY IS Phrase
  • REDEFINES Clause
Parent topic: XFD Files
Related information
WHEN XFD directive
Using XFD Directives


KEY IS Phrase

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Fields named in KEY IS phrases of SELECT statements are included as column names. Other fields that occupy the same areas as the key fields (by either explicit or implicit redefinition) are not included by name, but are mapped to the key field column names by the XFD.

Remember, if the field named in the KEY IS phrase is a group item, it does not become a column in the database table unless a USE GROUP XFD directive is used See How XFDs are Formed for more information. Instead, the subordinate fields of the group item are used.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP XFD directive


REDEFINES Clause

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Fields contained in a redefining item occupy the same positions as the fields being redefined. The compiler needs to select only one of the field definitions to use. The default rule that it follows is to use the fields in the item being redefined as column names; the XFD maps fields that appear subordinate to a REDEFINES clause to column names.

Multiple Record Definitions

This same rule extends to multiple record definitions. In COBOL, multiple record definitions are essentially redefinitions of the entire record area. This leads to the same complication that is encountered with REDEFINES: multiple definitions for the same data. So the compiler needs to select one definition to use.

Multiple Record Definitions

Because the multiple record types can be different sizes, the compiler needs to use the largest one, so that it can cover all of the fields adequately. Thus, the compiler's rule is to use the fields in the largest record defined for the file. If more than one record is of the largest size, the compiler uses the first one.

Group Items

Note that group items are, by default, never included in an XFD for the same reason that REDEFINES are excluded: they result in multiple names for the same data items. You can, however, choose to combine grouped fields into one data item by specifying the USE GROUP XFD directive.

FILLER Data Items

In a COBOL FD, FILLER data items are essentially place holders. FILLER items are not uniquely named and thus cannot be uniquely referenced. For this reason, they are not placed into the XFD. The XFD maintains the correct mapping of the other fields, and no COBOL record positional information is lost.

Sometimes you need to include a FILLER data item, such as when it occurs as part of a key. In such a case, you could include it under a USE GROUP XFD directive or give it a name of its own with the NAME XFD directive.

OCCURS Definition

An OCCURS clause always requires special handling, because the run time system must assign a unique name to each database column. The run time system accomplishes this by appending sequential index numbers to the item named in the OCCURS clause.

For example, if the following were part of a file's description:

03  employee-table occurs 20 times.
    05  employee-number            pic 9(3)

these column names would be created in the database table:

employee_number_1
employee_number_2
.
.
.
employee_number_10
employee_number_11
.
.
.
employee_number_20

Note that the hyphens in the COBOL code are translated to underscores in database field names, and the index number is preceded by an underscore.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP XFD directive
NAME XFD directive


Summary of XFD Fields

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Fields defined with an OCCURS clause are assigned unique sequential names. Fields without names are disregarded. When multiple fields occupy the same area, the compiler chooses only one of them unless you have a WHEN XFD directive to distinguish them. To choose, the compiler:

  • Preserves fields mentioned in KEY IS phrases
  • Discards group items unless USE GROUP is specified
  • Discards REDEFINES
  • Uses the largest record if there are multiple record definitions
Parent topic: XFD Files
Related information
WHEN XFD directive


Identical Field Names

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

In COBOL, you distinguish fields with identical names by qualification. For example, there are two fields named RATE in the following code, but they can be qualified by their group items. Thus, you would reference RATE OF TERMS-CODE and RATE OF AR-CODE in your program:

01  record-area.
    03  terms-code.
        05  rate                   pic s9v999.
        05  days                   pic 9(3).
        05  descript               pic x(15).
    03  ar-code.
        05  rate                   pic s9v999.
        05  days                   pic 9(3).
        05  descript               pic x(15).

Database systems consider duplicate names an error. Thus, if more than one field in a particular file has the same name, the XFD is not generated for that file.

The solution to this situation is to add a NAME XFD directive that associates an alternate name with one or both of the conflicting fields.

Parent topic: XFD Files
Related information
NAME XFD directive


Long Field Names

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To meet the SQL requirements of some relational database management systems (RDBMSs), the Database Connectors run time truncates long field names to the maximum allowed by the RDBMS. (In the case of the OCCURS clause described above, the truncation is to the original name, not the appended index numbers. However, the final name, including the index number, is limited to the RDBMS maximum.) It's a good idea to make sure that your field names are unique (and meaningful) within the first 18 characters.

The database you are connecting to may allow longer names, and if so, more characters are used. Names longer than 30 characters generate a warning. Instead of allowing default truncation, use the NAME XFD directive to give a shorter alias to a field with a long name. Note that within the COBOL application you can continue to use the original name. The NAME XFD directive affects only the XFD connection to the RDBMS table.

Parent topic: XFD Files
Related information
NAME XFD directive


Naming the XFD File

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The compiler needs to give a name to each XFD file that is built. It attempts to build the name from your COBOL code, although there are some instances where the name in the code is nonspecific, and you must provide a name.

Each XFD name is built from a starting name that is derived (if possible) from the SELECT statement in your COBOL code. The following table explains how that occurs.

ASSIGN name is a variable | If the SELECT for the XFD file has a variable ASSIGN name (ASSIGN TO filename), you must specify a starting name for the .xfd file via a FILE XFD directive in your code. This process is described in Using XFD Directives
ASSIGN name is a constant | If the SELECT for the XFD file has a constant ASSIGN name (such as ASSIGN TO COMPFILE), that name is used as the starting name for the .xfd file name
ASSIGN name is generic | If the ASSIGN phrase refers to a generic device (such as ASSIGN TO DISK), the compiler uses the SELECT name as the starting name for the XFD
Parent topic: XFD Files
Related information
FILE XFD directive
Using XFD Directives


Forming the Final XFD Name

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

From the starting name, the final name is formed as follows:

  • The compiler removes any extensions from the starting name
  • It constructs a universal base name by stripping out directory information that fits any of the formats used by the operating systems that run the compiler
  • It reduces the base name to eight characters and converts it to lower case
  • It appends the letters .xfd to the base name

Examples of XFD names

COBOL code File name
ASSIGN TO "usr/ar/customer.dat"
 customer.xfd
SELECT TESTFILE, ASSIGN TO DISK
 testfile.xfd
ASSIGN TO FILENAME
 (you specify)
Parent topic: XFD Files


Mapping Other Files to an XFD

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

At run time, it is possible to use a single XFD for files that have different names. For example, suppose a site has customer files that have identical structures but different names (such as CUST0001, CUST0002, and CUST0003). It's not necessary to have a separate XFD for each file, as long as their record definitions are the same.

The individual files can all be mapped to the same XFD via an ACUFH configuration file variable called XFD_MAP. The following paragraphs describe how this works.

Suppose your COBOL application has a SELECT with a variable ASSIGN name, such as customer-file. This variable assumes different values (such as CUST0001 and CUST0002) during program execution.

Before compiling the application, you would use the FILE XFD directive to provide a base name for the XFD. Suppose you provide CUST as the base. The compiler would then generate an XFD named cust.xfd. (The compiler always converts XFD names to lower case.)

To ensure that all customer files, each having a unique name, use this same XFD, enter the following in your ACUFH configuration file:

XFD_MAP   CUST* = CUST

The asterisk ("*") in the example is a wildcard that matches any number of characters. Note that the extension .xfd should not be included in the map. This statement would cause the XFD cust.xfd to be used for all files whose names begin with CUST.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...

where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:

* | matches any number of characters
? | matches a single occurrence of any character

For example:

CUST???? | matches CUST0001 and CUSTOMER; does not match CUST001 or CUST00001
CUST* | matches all of the above
CUST*1 | matches CUST001 and CUST0001 and CUST00001; does not match CUSTOMER
*OMER | matches CUSTOMER; does not match CUST001 or CUST0001

The XFD_MAP variable is read during the open file stage of any Connector interfaces linked into the run time system.

XFD values can be replaced or added to the end of existing XFD map values by setting the XFD_MAP_RESETS ACUFH configuration file variable. This variable determines whether setting XFD_MAP adds to or replaces the existing value. When this variable is set to 0 (off, false, no), setting XFD_MAP adds new value patterns to the end of the existing value. When XFD_MAP_RESETS is set to 1 (on, true, yes), setting XFD_MAP replaces the existing value with a new value. The default value is 1 (on, true, yes).

This variable may be useful if you need to include multiple XFD_MAP lines in an ACUFH configuration file and want to avoid setting and resetting the variable. When multiple lines exist, all patterns are used in the order they are listed.

Parent topic: XFD Files
Related information
XFD_MAP configuration variable
FILE XFD directive
XFD_MAP_RESETS configuration variable


Using XFD Directives

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This section explains what XFD directives are, and how you can use them in your COBOL File Descriptors (FDs) to control how your database tables are built.
  • Introduction
  • XFD Directive Syntax
  • Supported XFD Directives
Parent topic: Database Connectors User's Guide


Introduction

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

EXtended File Descriptors (XFDs) are based on your COBOL File Descriptors (FDs). Each XFD describes all of the fields for one file.

XFD directives are optional comments that you can use in your FDs to control how things look on the database side. Many applications use only the CREATEXFD directive. XFD directives are most commonly used when a site intends to do a lot of work with the relational database management system (RDBMS) outside of the COBOL application, and wants to control how the database table is built.

XFD directives are special comments placed into an FD in your COBOL source code. They guide the building of the XFDs, which in turn guide the building of the database table.

Each XFD directive includes the letters XFD. These three letters indicate to the compiler that the comment is to be used in XFD generation.

XFD directives provide extended control over how the database table is built. Among other things, they let you:

  • Specify a column name to be used in the database table, in place of a COBOL field name.
  • Map elementary items of a group item together into a single column.
  • Cause numeric COBOL data to be treated as a text string in the database.
  • Cause the fields from a specific record in a file to appear in the database table (rather than just the fields from the largest record).
  • Assign a column the DATE type, providing the built-in functionality that dates have in the RDBMS.
  • Give a name to the XFD file itself.

XFD directives are always placed within a COBOL FD. They do not affect Procedure Division I/O statements, and they do not change your COBOL fields in any way. Rather, they guide the building of the XFDs, giving you control over the way COBOL data maps to database fields.

You can build XFDs directly from your source code with only the CREATEXFD directive if the default mapping rules described in XFDs and New and Existing Databases are sufficient for your situation. Unlike the XFD directives, the CREATEXFD directive can be specified on the command line or within your project properties if you do not want to place the directive in your program. If you would like to override the default mapping behavior or map a field to a different name, you must add additional XFD directives to your COBOL code.

Parent topic: Using XFD Directives
Related reference
XFD Directives
New and Existing Databases


XFD Directive Syntax

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Place each XFD directive syntax on a line by itself, immediately before the COBOL line to which it pertains.

Introduce each XFD directive with a $ in the Indicator Area (column 7 in standard ANSI source format), followed immediately by the letters XFD, and then the XFD directive itself. There should be no space between the $ and the XFD. Spaces are permitted elsewhere on the line as separators. For example, the NAME XFD directive looks like this:

$XFD  NAME = EMP-NUMBER

Note that XFD directives are case-insensitive and that hyphens and underscores are considered equivalent. Thus, for example,

$XFD VAR_LENGTH
$XFD VAR-LENGTH
$xfd var_length
$xfd var-length

are all recognized as equivalent.

Two or more XFD directives that pertain to the same line of COBOL code may be combined on one comment line. The XFD directives should be separated by a space or a comma. For example, to specify both USE GROUP and NUMERIC at the same time, you would add this line:

$XFD  USE GROUP, NUMERIC
  • Line Continuation for Complex XFDs
    Syntax for XFD directives that exceed one line.
Parent topic: Using XFD Directives


Line Continuation for Complex XFDs

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

$XFD directives may be continued onto multiple lines by specifying a single character backslash (\) as the last non-blank character on a line. For example:

$XFD WHEN (var1 = "abc" and var2 = "def"    \
$XFD       and (var3 = "ghi" or var4 = "jkl"))  \
$XFD       or var5 != "xyz"

Line Continuation Rules

  • $XFD directives are continued via a backslash as the last non-blank character on the line.
  • Continued lines begin with $XFD just like the first directive line (with the dollar sign in the indicator column).
  • The final continuation line omits the trailing backslash.
  • "The overall combined directive is a concatenation of all of the continuation lines.
  • The next character after the blank that follows $XFD is the next character of the directive. That character logically replaces the backslash on the previous line.
  • There is no limit on the number of continuation lines other than the limit on total program source lines, and the overall size of the continued directive is limited only by available memory. But it is highly unlikely that one XFD directive would ever need to exceed a few dozen lines or a few thousand characters.
  • In standard ANSI source format the contents of columns 73-80 are ignored, the continuation backslash must appear in Area B (columns 12-72).
  • Backslashes within data (literals) do not cause a problem because they are inside quoted strings (and cannot be the last non-blank character on the line).
  • In-line comments ("*>") are not allowed on continued XFD directive lines.
  • A new error message is generated for a syntax error within continued XFD directive lines and the erroneous continuation lines scanned up to that point are ignored. Possible syntax errors include placing a source line other than a comment line within an intended sequence of continued XFD directive lines, or omitting the final continuation line (the line that begins with $XFD and does not end with a trailing backslash). Other errors are possible when the directive itself is scanned and processed.
Parent topic: XFD Directive Syntax


Supported XFD Directives

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following XFD directives are supported. For complete definitions of these directives, see XFD Directives.

XFD Directive | Brief Description
ALPHA | Allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program
BINARY | Specifies that the data in the field could be alphanumeric data of any classification
COBOL-TRIGGER | Tells Database Connectors that a COBOL trigger is to be executed
IDENTITY-COLUMN | Allows you to insert an identity column into the database
COMMENT | Allows you to include comments in an XFD file
DATE | Stores a field in the database as a date or time
FILE | Supplies a starting name from which the XFD file name is formed
NAME | Assigns a database field name to the field defined on the next line
NUMERIC | Allows you to treat a data item as an unsigned integer when it is declared as alphanumeric
SECONDARY_TABLE | Indicates that the next data item may be placed into a subordinate table
USE GROUP | Allows you to enter a group item into the database as a single field
VAR_LENGTH | Requests that the data item that immediately follows the XFD directive be assigned a type that implies variable length
WHEN | Lets you include multiple record definitions or REDEFINES in a database table
XSL | Allows you to include a stylesheet reference in the XML header
Parent topic: Using XFD Directives
Related reference
XFD Directives


Invalid Data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This section lists the COBOL data items that are considered invalid, and explains what happens to them when they are stored in the database. This section also covers database items that are considered invalid, and explains how those are translated to COBOL.
  • Illegal COBOL Data
  • Invalid Database Data
Parent topic: Database Connectors User's Guide


Illegal COBOL Data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

COBOL data (except key data) that is illegal by database standards is stored in the database as null unless you specifically override this default. (Use the ACUFH configuration file variable 4GL_ILLEGAL_DATA to override.)

The following COBOL data usages are considered illegal by the database:

 | Illegal Values
USAGE DISPLAY numbers | LOW-VALUES , HIGH-VALUES, and SPACES
COMP-2 numbers | HIGH-VALUES and SPACES
COMP-3 numbers | HIGH-VALUES

All other numeric types fit one of the preceding cases (depending on their internal storage format)

DATE fields | The value "zero" and any other illegal conditions as defined by the date's USAGE type (see above)
text fields | LOW-VALUES

BINARY numbers are always legal, and all values are legal in BINARY text fields.

  • Invalid Key Data
  • Invalid Data Other Than Keys
Parent topic: Invalid Data
Related information
4GL_ILLEGAL_DATA configuration variable


Invalid Key Data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Any field that is part of a key is never stored as null. (A null key does not have a well-defined position in relation to other keys.) If a key field has an illegal value, the field is stored in the database as described here:

Illegal LOW-VALUES | minimum possible value (0 or -99999...) minimum possible date value (01/01/01)
Illegal HIGH-VALUES | maximum possible value (99999...) maximum possible date value (database dependent)
Illegal SPACES | zero (or 01/01/01 for a date field)
Parent topic: Illegal COBOL Data
Related information
Invalid Data Other Than Keys


Invalid Data Other Than Keys

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

You have the option to convert illegal data, other than keys, into legal values by setting the configuration variable 4GL_ILLEGAL_DATA to Converted. When this is set, the Database Connectors interface converts data the same way it does for keys.

4GL_ILLEGAL_DATA can also be set to Null to indicate that illegal COBOL data other than keys should be converted to null. This is the default behavior.

Parent topic: Illegal COBOL Data
Related information
Invalid Key Data
4GL_ILLEGAL_DATA configuration variable


Invalid Database Data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When Database Connectors receives a null field from the database, it translates it to COBOL as follows:

Numbers (including dates): | zero
Text (including binary): | spaces

For additional information about the handling of invalid dates, see the DATE XFD directive.

Parent topic: Invalid Data
Related information
4GL_ILLEGAL_DATA configuration variable
DATE XFD directive


Working with COBOL

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

After the environment has been set up for the Database Connectors interface, you are ready to use the system. This section describes how to prepare your COBOL program and compile it for use with Database Connectors.

  • Examples of Preparing and Compiling a Program
Parent topic: Database Connectors User's Guide


Examples of Preparing and Compiling a Program

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The Connectors sub-directory within your Samples directory contains three sample programs that are based on the code excerpt below. These programs show different ways of how to manipulate your COBOL records in readiness for being written to a database. Remember to compile them with the appropriate IDXFORMAT directive and accompanying ACUFH configuration file.

Note: If you are not familiar with XFD directives, you may want to read the topics in the Using XFD Directives section before continuing with this topic.

The examples are based upon a purchase orders file from a COBOL program and will be stored in a database. The file descriptor below contains the records that handle all of the information from a fictitious company's purchase orders. Within it are two record types:

  • The purchase order (header) record (there is one of these for each purchase order form)
  • The purchase order detail record (there is one detail record for each line item in a purchase order)

The file is keyed off the purchase order number. This following three examples demonstrate three different approaches to using the COBOL file descriptor and XFD directives:

  • Example 1 (order1.cbl) only includes the largest record in the database table; see Example 1 - Compiling with just the CREATEXFD directive.
  • Example 2 (order2.cbl) uses the WHEN XFD directive, which causes all record formats to be included in the database; see Example 2 - Compiling with the WHEN XFD Directive.
  • Example 3 (order3.cbl) groups together several fields and renames them, for convenience; see Example 3 - Using Additional XFD Directives.
IDENTIFICATION DIVISION.
program-id.  purchase.
ENVIRONMENT DIVISION.
input-output section.
file-control.

select p-o-file
assign to disk "purch1"
organization is indexed
access mode is dynamic
record key is p-o-number
file status is p-o-status.

DATA DIVISION.
file section.
fd p-o-file.
01 p-o-record.
   03 p-o-division-number                pic 9(3).
   03 p-o-record-type                    pic x.
      88 header-record                   value "h".
      88 detail-record                   value "d".
   03 p-o-number                         pic 9(10).
   03 p-o-number-detail redefines
         p-o-number.
      05 picking-ticket-number           pic 9(6).
      05 shipping-region                 pic 9(2).
      05 p-o-customer-type               pic 9(2).
      05 p-o-customer-breakdown redefines
            p-o-customer-type.
         07 customer-category            pic x.
         88 p-o-customer-retail          value "r".
         88 p-o-customer-whlsale         value "w".
         07 customer-pay-format          pic x.
            88 is-net-30                 value "3".
            88 is-net-10                 value "1".
   03 p-o-date.
      05 p-o-yy                          pic 9(2).
      05 p-o-mm                          pic 9(2).
      05 p-o-dd                          pic 9(2).

01 p-o-detail-record.
   03 p-o-dept-number                    pic 9(3).
   03 p-o-record-type                    pic x.
   03 detail-p-o-number                  pic 9(10).
   03 p-o-shipping-info.
      05 p-o-quantity-to-ship            pic s9(4) comp.
      05 p-o-total-quantity              pic s9(4) comp.
   03 p-o-notes.
      05 notes-line occurs 3 times       pic x(40).
working-storage section.
01 p-o-status                            pic x(2).
PROCEDURE DIVISION.
level-1 section.
main-logic.

open output p-o-file.
close p-o-file.
stop run.
  • Example 1 - Compiling with just the CREATEXFD directive
  • Example 2 - Compiling with the WHEN XFD Directive
  • Example 3 - Using Additional XFD Directives
Parent topic: Working with COBOL
Related reference
Using XFD Directives
Related information
Example 1 - Compiling with just the CREATEXFD directive
Example 2 - Compiling with the WHEN XFD Directive
Example 3 - Using Additional XFD Directives


Example 1 - Compiling with just the CREATEXFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This example (order1.cbl) just uses the CREATEXFD directive to generate the XFD. The compiled program builds the database table shown at the end of this section.

The database table builds as follows.
  • First, any fields listed in the KEY IS clause of the SELECT are included (p-o-number in this example).
  • The compiler then takes the largest record (p-o-detail-record) and lists the fields that make up that record.
The rest of this section shows the specific fields that are placed into the table.

All data from the COBOL program is stored in and retrieved from the database, even though not all fields are explicitly named in the database table. For a description of how this works, see XFDs.

The underlined fields are the only ones entered into the table:

fd p-o-file.
 01  p-o-record.
     03  p-o-division-number                   pic 9(3).
     03  p-o-record-type                       pic x.
         88  header-record                     value "h".
         88  detail-record                     value "d".
     03  p-o-number                            pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number             pic 9(6).
         05  shipping-region                   pic 9(2).
         05  p-o-customer-type                 pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category             pic x.
                 88  p-o-customer-retail       value "r".
                 88  p-o-customer-whlsale      value "w".
             07  customer-pay-format           pic x.
                 88 is-net-30                  value "3".
                 88 is-net-10                  value "1".
     03  p-o-date.
         05  p-o-yy                            pic 9(2).
         05  p-o-mm                            pic 9(2).
         05  p-o-dd                            pic 9(2).

 01  p-o-detail-record.
     03  p-o-dept-number                       pic 9(3).
     03  p-o-record-type                       pic x.
     03  detail-p-o-number                     pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship              pic s9(4) comp.
         05  p-o-total-quantity                pic s9(4) comp.
     03  p-o-notes.
         05  notes-line occurs 3 times         pic x(40).

As the table is built:

  • Any hyphens in the COBOL field names are converted to underscores
  • Field names longer than 18 characters generate a warning if the first 18 characters are not unique. Some databases limit you to 18 total characters. Use the least number of characters for optimal portability and end-user efficiency. You can use the NAME XFD directive for this to avoid changing your procedure division code.
  • Fields in OCCURS clauses get special handling, because the run time system must assign a unique name to each data item. Sequential index numbers are appended to the item named in the OCCURS. Limits vary between databases. See to the documentation for your RDBMS. In some instances, the name may be truncated by the Connector if necessary before the index is added.
Note: detail-p-o-number is not part of the table because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_number | number(10)*
p_o_dept_number | number(3)*
p_o_record_type | char(1)
p_o_quantity_to_ship | number(4)*
p_o_total_quantity | number(4)*
notes_line_1 | char(40)
notes_line_2 | char(40)
notes_line_3 | char(40)

* The actual database data type may vary.

See the Limits and Ranges topic for your specific RDBMS for a list of supported data types and their COBOL equivalents.

Parent topic: Examples of Preparing and Compiling a Program
Related reference
XFDs
NAME XFD directive
Related information
Example 2 - Compiling with the WHEN XFD Directive
Example 3 - Using Additional XFD Directives


Example 2 - Compiling with the WHEN XFD Directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This example (order2.cbl) enables you to override the default table build; it allows you to force certain columns to be built that would be built by default. Add the WHEN XFD directive in front of each record, which results in the underlined fields being entered into the table:

fd p-o-file.
$xfd when p-o-record-type = "h"
 01  p-o-record.
     03  p-o-division-number                       pic 9(3).
     03  p-o-record-type                           pic x.
         88  header-record                         value "h".
         88  detail-record                         value "d".
     03  p-o-number                                pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number                 pic 9(6).
         05  shipping-region                       pic 9(2).
         05  p-o-customer-type                     pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category                 pic x.
                 88  p-o-customer-retail           value "r".
                 88  p-o-customer-whlsale          value "w".
             07  customer-pay-format               pic x.
                 88  is-net-30                     value "3".
                 88  is-net-10                     value "1".
     03  p-o-date.
         05  p-o-yy                                pic 9(2).
         05  p-o-mm                                pic 9(2).
         05  p-o-dd                                pic 9(2).
$xfd when p-o-record-type = "d"
 01  p-o-detail-record.
     03  p-o-dept-number                           pic 9(3).
     03  p-o-record-type                           pic x.
     03  detail-p-o-number                         pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship                  pic s9(4) comp.
         05  p-o-total-quantity                    pic s9(4) comp.
     03  p-o-notes.
         05  notes-line occurs 3 times             pic x(40).
Note: p-o-record-type is entered into the table only once. The detail-p-o-number field is not part of the table, because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_division_number | number(3)*
p_o_record_type | char(1)
p_o_number | number(10)*
p_o_yy | number(2)*
p_o_mm | number(2)*
p_o_dd | number(2)*
p_o_dept_number | number(3)*
p_o_quantity_to_ship | number(4)*
p_o_total_quantity | number(4)
notes_line_1 | char(40)
notes_line_2 | char(40)
notes_line_3 | char(40)

* The actual database data type may vary.

Note: When p_o_record_type is h, p_o_dept_number, p_o_quantity_to_ship, p_o_total_quantity, and notes_lines_1, 2, and 3 become NULL. When p_o_record_type is d, p_o_division_number, p_o_yy, p_o_mm and p_o_dd become NULL.
Parent topic: Examples of Preparing and Compiling a Program
Related reference
WHEN XFD directive
Related information
Example 1 - Compiling with just the CREATEXFD directive
Example 3 - Using Additional XFD Directives


Example 3 - Using Additional XFD Directives

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This example (order3.cbl) demonstrates how to streamline the code to introduce the following changes:

  • Apply the USE GROUP XFD directive to the notes to group them, which improves execution speed and clarity. Accessing each note line individually from the database side is not required.
  • Rename the notes field for convenience.
  • Apply the USE GROUP and DATE XFD directives to the date, to give it all the properties of a date on the database side.
fd p-o-file.
$xfd when p-o-record-type = "h"
 01  p-o-record.
     03  p-o-division-number                      pic 9(3).
     03  p-o-record-type                          pic x.
         88  header-record                        value "h".
         88  detail-record                        value "d".
     03  p-o-number                               pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number                pic 9(6).
         05  shipping-region                      pic 9(2).
         05  p-o-customer-type                    pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category                pic x.
                 88  p-o-customer-retail          value "r".
                 88  p-o-customer-whlsale         value "w".
             07  customer-pay-format              pic x.
                 88  is-net-30                    value "3".
                 88  is-net-10                    value "1".
$xfd use group, date
     03  p-o-date.
         05  p-o-yy                               pic 9(2).
         05  p-o-mm                               pic 9(2).
         05  p-o-dd                               pic 9(2).
$xfd when p-o-record-type = "d"
 01  p-o-detail-record.
     03  p-o-dept-number                          pic 9(3).
     03  p-o-record-type                          pic x.
     03  detail-p-o-number                        pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship                 pic s9(4) comp.
         05  p-o-total-quantity                   pic s9(4) comp.
$xfd use group, name = notes
     03  p-o-notes.
         05  notes-line occurs 3 times            pic x(40).
Note: p-o-record-type is entered only once into the table. The detail-p-o-number field is not part of the table, because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_division_number | number(3)
p_o_record_type | char(1)
p_o_number | number(10)
p_o_date | date
p_o_dept_number | number(3)
p_o_quantity_to_ship | number(4)
p_o_total_quantity | number(4)
notes | char(120)
Parent topic: Examples of Preparing and Compiling a Program
Related reference
DATE XFD directive
USE GROUP XFD directive
Related information
Example 1 - Compiling with just the CREATEXFD directive
Example 2 - Compiling with the WHEN XFD Directive


New and Existing Databases

You may encounter one of two situations as you begin to use Database Connectors. In situation one, the database files don't exist yet. In situation two, the database files already exist, and you want to access that existing data from a COBOL application. There may or may not already be existing COBOL programs that access the database.

Each situation has potential questions.

  • How do I declare COBOL data so that it matches the database data?
  • Are there any special fields in the database that must be accessed in a special way?
  • How do I create COBOL record names, field names, index names, and data types that best conform to the compiler, Database Connectors, and the database engine?
These questions are addressed in the next few sections.
  • Default Behavior
  • Accessing Existing Database Files
Parent topic: Database Connectors User's Guide


Default Behavior

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following are automatically handled by Database Connectors:

  • Conversion of uppercase field names to lowercase (or vice versa) when necessary.
  • Data conversions needed to match the internal storage formats used by the database.
  • Creation of database files, if needed, when you execute an OPEN OUTPUT verb. If this is your situation, matching COBOL fields to database fields should not be an issue. Fields match perfectly, because the database fields are based on your COBOL code. As an alternative, you can use your database query tool to create a database.
  • Sequencing of data returned from a database: you may encounter unexpected sequencing. If your COBOL definition does not include alternate keys with duplicates, the data is returned in key order. If your COBOL definition does include alternate keys with duplicates, Database Connectors cannot control the sequence in which the data is returned. The database query optimizer decides how to order the returned records. For a set of records with the same key value, the records may not be in historical order
Parent topic: New and Existing Databases


Accessing Existing Database Files

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If accessing existing data in a relational database, you need to know how to declare your data to match the database fields.

If your COBOL code isn't written yet, you should follow the guidelines given in the Appendix for your specific RDBMS.

If your COBOL code already exists, you can make necessary adjustments by adding XFD directives to your code. XFD directives are comments that guide the creation of the eXtended File Descriptors (XFDs). The XFDs in turn help map the COBOL fields to their equivalent database fields. XFD directives are described in Using XFD Directives, and XFDs are described in XFDs.

  • How Do I Match Existing Text Fields?
  • How Do I Match Existing Numeric Fields?
  • Field Names
Parent topic: New and Existing Databases
Related information
Using XFD Directives
XFDs


How Do I Match Existing Text Fields?

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To access character data, you simply declare the field as PICTURE X, with as many X's as appropriate.

Parent topic: Accessing Existing Database Files
Related information
How Do I Match Existing Numeric Fields?
Field Names


How Do I Match Existing Numeric Fields?

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Numeric fields are more database-specific than text fields. Most relational database systems accommodate INTEGER, DECIMAL, and DATE types. For information on the handling of other numeric types, see the Appendix containing information specific to your RDBMS.

Parent topic: Accessing Existing Database Files
Related information
How Do I Match Existing Text Fields?
Field Names


Field Names

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If your COBOL application already exists, and if it must access a relational database that already exists, you may have to work around differences in the names of the fields, as well as naming conventions imposed by the RDBMS. For example, your program might use the name EMPLOYEE-NO, while the database uses the name EMP-NUMBER for the same item of information.

  • Resolving Name Conflicts
Parent topic: Accessing Existing Database Files
Related information
How Do I Match Existing Text Fields?
How Do I Match Existing Numeric Fields?


Resolving Name Conflicts

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If naming differences exist, you need not rename your COBOL fields and you need not change the database. This is because the CREATEXFD directive builds XFDs that map your COBOL fields to the correct database fields. The mapping is automatic if the names are the same. If the COBOL name differs from the database name, you enable the compiler to make the correct mapping by adding a NAME XFD directive to your COBOL code.

You can also use XFD directives to produce other effects when data is mapped from COBOL to the database. XFD directives are described in detail in Using XFD Directives.

Parent topic: Field Names
Related information
Using XFD Directives
Name XFD Directive


File Handling Configuration

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This section explains how to configure COBOL file handling operations to interact with supported RDBMS.
  • Configuring the File Handler
Parent topic: Database Connectors User's Guide


Configuring the File Handler

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As well as the database-specific information that you specify in an ACUFH configuration file, you also need to inform the File Handler of which database type it is working with when performing file handling operations. You do this by specifying the IDXFORMAT, which can be set using one of the following methods:

  • Set at compile-time, either within your source code or on the command line.
  • Set in a File Handler configuration file, which is queried at run time.

The supported values for the IDXFORMAT option are:

IDXFORMAT No: | RDBMS:
18 | Microsoft SQL Server
19 | Oracle
20 | DB2
22 | ODBC

Set the format at compile-time

Set the option within your source code using the following syntax (replacing nn with the appropriate value from the table above):

      $set IDXFORMAT"nn"
       Identification Division.
       Program-id. Dbc-demo.
       ...
       End program Dbc-demo.

Or specify the IDXFORMAT on the command line, during compilation:

cob Dbc-demo.cbl IDXFORMAT"nn";
Note: Another method is to use the USE directive, specifying a directives file that contains the required IDXFORMAT.

Set the format at run time

Tip: Configuring the File Handler at run time enables you to use the same source code with more than one of the supported RDBMSs without the need to recompile. It also gives you greater control when setting different formats at once.

Set the option within a File Handler configuration file:

[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:/home/data/db2]
IDXFORMAT=20
[FOLDER:/home/data/oracle]
IDXFORMAT=19
Note: You cannot specify the values 18, 19, or 20 in the [XFH-DEFAULT] section of a configuration file. In the example above, IDXFORMAT 8 is used as default, but files placed in /home/data/db2, and /home/data/oracle use IDXFORMATs 20 and 19 respectively.

To use the configuration file at run time, you must specify it in the EXTFH environment variable:

EXTFH=/home/dbc/extfh.cfg
export EXTFH

sets the file name to /home/dbc/extfh.cfg.

Parent topic: File Handling Configuration


Run Time System Configuration

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Database Connectors uses an ACUFH configuration file to determine how the run time system should behave when interacting with data. This chapter describes how to configure the File Handler, and how to use ACUFH configuration variable options to configure the run time system for your relational database environment.
  • ACUFH Configuration Variables
Parent topic: Database Connectors User's Guide


ACUFH Configuration Variables

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before running Database Connectors, you must set the A_CONFIG environment variable to the name of the ACUFH configuration file. You may want to make and use a personalized copy of the ACUFH configuration file to avoid impacting other users. Set the A_CONFIG environment variable to identify your own personal copy. For example:

Windows:

SET A_CONFIG=directory-name\my-file-name

UNIX:

A_CONFIG=directory-name/my-file-name
export A_CONFIG

defines a configuration file with the name of your choice, in the directory of your choice.

There are several variables that can be set in your ACUFH configuration file that affect the Database Connectors processing. Those listed below are applicable to any relational database management system (RDBMS) with which Database Connectors communicates. Some ACUFH configuration variables are database-specific; those variables are discussed in the database-specific sections later in this guide.

Variable | Description
4GL_2000_CUTOFF | Determines which two-digit years are considered to be in the twentieth century and which are considered to be in the twenty-first century
4GL_8_DIGIT_CUTOFF | Determines whether to use 4GL_2000_CUTOFF for dates that don't use a format string and that are eight digits
4GL_COLUMN_CASE | Tells Database Connectors to leave the case of the field names found in the eXtended File Descriptor (XFD) unchanged
4GL_COMMIT_COUNT | Indicates the conditions under which you want to issue an automatic COMMIT_WORK operation
4GL_CONVERT_DATE_ZERO | Allows Database Connectors to locate and return those records written using the date 01/01/01
4GL_DB_MAP | Enables you to set one map at a time by using FILE_PREFIX as a list of directories, each of which maps to a different database
4GL_FULL_DATA_TEST | Allows you to specify whether an entire field is tested for illegal data or if only the first field is tested
4GL_IGNORED_SUFFIX_LIST | Lists the case-independent suffixes to ignore when opening DB2 tables
4GL_ILLEGAL_DATA | Determines how COBOL data considered illegal by the database is converted before it is stored in the database
4GL_JULIAN_BASE_DATE | Sets the base date to be used for Julian date calculations
4GL_WHERE_CONSTRAINT | Allows you to override any value given in the external variable A4GL_WHERE_CONSTRAINT
FILE_TRACE | Allows you to start file tracing without opening the debugger
XFD_DIRECTORY | Tells the run time system the name of the directory that contains the XFD files built by the compiler
XFD_MAP | Tells the run time system to associate certain filenames with a particular XFD
XFD_MAP_RESETS | Determines whether setting XFD_MAP adds to or replaces the existing value
XFD_PREFIX | Defines a specific series of directories to search for XFD files
Parent topic: Run Time System Configuration


Database Connectors for DB2

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This appendix provides information that is specific to Database Connectors for DB2.
  • DB2 Concepts Overview
  • Client Configuration
  • Filename Translation
  • Decimal Points
  • ACUFH Configuration File Variables for DB2
  • Record and Table Locking
  • Limits and Ranges
  • Data Type Mapping
  • Run-Time System Errors
  • Common Questions and Answers
Parent topic: Database Connectors User's Guide


DB2 Concepts Overview

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This quick overview of some basic design concepts underlying the DB2 relational database management system (RDBMS) helps to interface your COBOL program to it.

  • Transactions
  • Record-locking Issues in Transactions
  • Database Connectors and Record Locking
Parent topic: Database Connectors for DB2


Transactions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The DB2 RDBMS is a transaction-based system. All of the work that you perform while using DB2 must occur within a transaction, whether that work is being done through the Database Connectors for DB2 or another application. When you use Database Connectors for DB2, a transaction is implicitly started for you by the database engine itself with the first file I/O operation performed on a file associated with DB2. Because all operations with Database Connectors for DB2 occur within a transaction, any record locked during processing remains locked until either a COMMIT WORK or ROLLBACK WORK is issued by Database Connectors. This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL.

The benefits of this transaction management system are best illustrated by an example. A COBOL application that handles order entry might perform these steps to accept an order:

  • Write an invoice record
  • Update a customer record
  • Write a payroll record for sales commissions
  • Update an inventory record

This series of four file operations is a logical unit. If the program were interrupted and had completed only some of the four file operations, the files would be in an inconsistent state. For example, if the program terminated unexpectedly after it updated the customer record, but before it updated the inventory record, a subsequent run might access non-existent inventory.

The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur. Then, if the program encounters an error or terminates, the files are left in a consistent state.

All file operations that are part of a transaction are logged. Once logged, they can be either committed or rolled back (undone) by the program.

If a program dies, or the system fails, the log file can be used to reconstruct complete transactions, returning all files to a consistent state. Transaction logging gives the ability to:

  • Define and commit transactions, or undo them (usually in response to an error condition); this undo facility is called a rollback
  • Reconstruct files into a consistent state after a program dies or system failure occurs; this operation is called recovery
Parent topic: DB2 Concepts Overview
Related information
Record-locking Issues in Transactions
Database Connectors and Record Locking


Record-locking Issues in Transactions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Applications that perform work in small operation-based logical units, benefit greatly from DB2's transaction management systems. Other applications may encounter difficulty with record locking when operating against a system (DB2) that enforces transaction management.

The difficulty can occur with an application that is performing more than one logical task at a time. Any operation that modifies or reads data in an I/O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system. As a result, the application may have many more record locks present than would be expected by the normal rule of COBOL file locking. The application would act in a manner similar to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used. This can best be illustrated by an example:

  1. The user is entering a customer's order.
  2. As each line item is entered into the order, the inventory file is modified to reflect that items have been removed from the stock on hand.
  3. The user must switch to a different part of the application to perform a different task, perhaps as a result of a phone call from a new customer.
  4. All of the records that were locked, or modified, by the application before the switch remain locked because the first order is not complete. As no COMMIT or ROLLBACK has been issued, all of the records remain locked until the application ends, thus ending the transaction.
  5. Because one order is open and not yet committed, other applications may be locked out of certain order items if they are still locked by the processing of the first order. The second order entry may be held up until the first order is completed.

Note that the first application is not locked out. A process can read its own locked records.

Parent topic: DB2 Concepts Overview
Related information
Transactions
Database Connectors and Record Locking


Database Connectors and Record Locking

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Your DB2 database may be set up for wait-level locks. The DB2 universal database products have the ability to time-out a lock and send an error return code to the waiting application. See your database administrator for details. (This SQL code would be placed in ERROR_MAP_FILE.)

Database Connectors provides semi-automated ways to handle transaction logging based on the setting of the 4GL_COMMIT_COUNT environment variable. You can also directly alter your source code to deal with this issue. Individual users determine how much work they wish to do to conform to Oracle's transaction management system by choosing the method that best fits their needs and resources. The following methods are listed in order of increasing amount of work:

4GL_COMMIT_COUNT = 0 (Default)

When you set this variable to zero, the run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement.

4GL_COMMIT_COUNT = n

When you set this variable to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of 4GL_COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released.

4GL_COMMIT_COUNT = -1

No commit is issued by Database Connectors. When 4GL_COMMIT_COUNT is set to -1, alternate ways to perform a commit or rollback include:

  • Call your database query tool with COMMIT WORK or ROLLBACK WORK.

A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

Parent topic: DB2 Concepts Overview
Related information
Transactions
Record-locking Issues in Transactions
A_DB2_ERROR_MAP_FILE configuration variable
4GL_COMMIT_COUNT configuration variable


Client Configuration

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following section covers the client setup required before you begin using Database Connectors for DB2 on a new system.

Before you begin, you need to have:

  • Access to an already installed and configured DB2 database.
  • Configured any client software (if the server is on a remote machine), and verify a successful connection to the intended database.

You should consult your DB2 documentation for help with these tasks.

Once you have successfully connected to your DB2 database, continue with the Database Connectors-specific configuration.

  • Setting Up the User Environment
  • Designating the Host Data Source
  • Configuring the File Handler for DB2
Parent topic: Database Connectors for DB2


Setting Up the User Environment

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To configure the client environment for Database Connectors, you usually use an ACUFH configuration file.

The minimum settings required would be the A_DB2_LOGIN, A_DB2_PASSWD, and A_DB2_DATASOURCE variables; refer to ACUFH Configuration File Variables for additional variables you can include.

You use the A_CONFIG environment variable to identify the ACUFH configuration file, which allows you to create your own personalized copy of the file, to avoid impacting other users.

If you are concerned about including passwords in a configuration file, you can set details such as A_DB2_PASSWD in your COBOL program or environment. The following syntax is an example of how you can set a variable within your code:

SET ENVIRONMENT A_DB2_PASSWD TO user-entry

See To Set Up The User Environment for more information.

Parent topic: Client Configuration
Related information
Designating the Host Data Source
Configuring the File Handler for DB2
To create an error map
ACUFH Configuration Variables
ACUFH Configuration File Variables for DB2
To Set Up The User Environment


Designating the Host Data Source

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

You must tell the run time system which data source to use for your DB2 file. You accomplish this by setting the ACUFH configuration file variable A_DB2_DATASOURCE. You can set this variable in your configuration file if using only one data source.

If you don't know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_DB2_DATASOURCE" TO "DB2 Database"
Parent topic: Client Configuration
Related information
Setting Up the User Environment
Configuring the File Handler for DB2
A DB2 DATASOURCE configuration variable
Preparing and Compiling Your COBOL Program Example
The Demonstration Program


Configuring the File Handler for DB2

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As well as the database-specific information that you specify in an ACUFH configuration file, you also need to inform the File Handler of which database type it is working with when performing file handling operations. You do this by specifying the IDXFORMAT, which can be set using one of the following methods:

  • Set at compile-time, either within your source code or on the command line.
  • Set in a File Handler configuration file, which is queried at run time.

The supported values for the IDXFORMAT option are:

IDXFORMAT No: | RDBMS:
18 | Microsoft SQL Server
19 | Oracle
20 | DB2
22 | ODBC

Set the format at compile-time

Set the option within your source code using the following syntax (replacing nn with the appropriate value from the table above):

      $set IDXFORMAT"nn"
       Identification Division.
       Program-id. Dbc-demo.
       ...
       End program Dbc-demo.

Or specify the IDXFORMAT on the command line, during compilation:

cob Dbc-demo.cbl IDXFORMAT"nn";
Note: Another method is to use the USE directive, specifying a directives file that contains the required IDXFORMAT.

Set the format at run time

Tip: Configuring the File Handler at run time enables you to use the same source code with more than one of the supported RDBMSs without the need to recompile. It also gives you greater control when setting different formats at once.

Set the option within a File Handler configuration file:

[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:/home/data/db2]
IDXFORMAT=20
[FOLDER:/home/data/oracle]
IDXFORMAT=19
Note: You cannot specify the values 18, 19, or 20 in the [XFH-DEFAULT] section of a configuration file. In the example above, IDXFORMAT 8 is used as default, but files placed in /home/data/db2, and /home/data/oracle use IDXFORMATs 20 and 19 respectively.

To use the configuration file at run time, you must specify it in the EXTFH environment variable:

EXTFH=/home/dbc/extfh.cfg
export EXTFH

sets the file name to /home/dbc/extfh.cfg.

Parent topic: Client Configuration
Related information
Setting Up the User Environment
Designating the Host Data Source


Filename Translation

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As you prepare to work with Database Connectors, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and eXtended File Descriptor (XFD) files are formed and work together. For detailed information on XFDs, see XFDs.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUFH configuration file variables, the run time system translates the name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

Database Connectors translate the name to uppercase letters and changes hyphens to underscores. File extensions are stripped, based on the setting of 4GL_IGNORED_SUFFIX_LIST. This new name is the one that Database Connectors uses for references to database tables.

Parent topic: Database Connectors for DB2
Related reference
XFDs
4GL IGNORED SUFFIX LIST configuration variable


Decimal Points

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors reads the decimal point character from the environment variable DECIMAL_POINT. If DECIMAL_POINT is set, Database Connectors uses that character. If the variable is not set, Database Connectors uses the decimal character that is encoded in the XFD file.

The two most common decimal indicators are the period “.” and the comma “,” characters. The comma is used often in European code and is often indicated in COBOL programs by the DECIMAL POINT IS COMMA clause.

Parent topic: Database Connectors for DB2


ACUFH Configuration File Variables for DB2

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before running Database Connectors, you must set the A_CONFIG environment variable to the name of the ACUFH configuration file. You may want to make and use a personalized copy of the ACUFH configuration file to avoid impacting other users. Set the A_CONFIG environment variable to identify your own personal copy. For example:

Windows:

SET A_CONFIG=directory-name\my-file-name

UNIX:

A_CONFIG=directory-name/my-file-name
export A_CONFIG

ensures the specified configuration file is used when interfacing with your database.

This section lists the ACUFH configuration file variables that are specific to DB2. For ACUFH configuration file variables that are generally applicable to any RDBMS with which Database Connectors communicates, see ACUFH Configuration Variables in the Run Time Configuration section.

Variable | Description
A_DB2_ALTERNATE_COMMIT_LOGIC | Determines how the interface responds to the setting of 4GL_COMMIT_COUNT
A_DB2_CATALOG | Indicates the catalog name to be used when the Connector searches for objects in the database
A_DB2_COMMIT_ON_BEGIN | To ensure that the previous transaction has been ended before a new one begins, set A_DB2_COMMIT_ON_BEGIN to a nonzero value
A_DB2_DATASOURCE | Set to the exact name of the host data source
A_DB2_ERROR_MAP_FILE | Allows you to map errors using a text file to supplement the default method of providing errors
A_DB2_ISOLATION_LEVEL | Sets the isolation level
A_DB2_LOCK_METHOD | Specifies the locking method that the Connector should use when accessing your data source
A_DB2_LOGIN | Indicates the user name under which you want to connect to the database system
A_DB2_PASSWD | Set to the password assigned to the database account associated with the user name specified by A_DB2_LOGIN
A_DB2_STRICT_EQUAL | Causes the interface to stop fetching data when it reaches the end of data specified by a SELECT statement
A_DB2_TABLE_TYPES | Specifies a table type that should be looked for when selecting a database table
A_DB2_USE_CATALOG | Enables you to use the catalog in the actual SQL queries
A_DB2_USE_CHAR_FOR_BINARY | Lets you store data that uses the BINARY XFD directive as hexadecimal encoded CHAR types
USER_PATH | Indicates the user name or names (schemas) to be used when the Connector searches for files
Parent topic: Database Connectors for DB2
Related reference
ACUFH Configuration Variables


Record and Table Locking

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

With Database Connectors, records are locked in a Wait mode. An application trying to read a locked record does not respond until the record becomes available.

DB2 Universal Database products have the ability to time-out a lock and send an error return code to waiting applications. See your database administrator for additional information.

Parent topic: Database Connectors for DB2


Limits and Ranges

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The following limits exist when working with DB2:
Maximum number of columns per key: | 16
Maximum number of columns: | 500
Maximum index size: | 255
Maximum record size: | 4005
Note that these limits may be further constrained by your database configuration. For example, the size of your page affects the maximum row size. Some limits are given here, but please refer to your database documentation for additional information.
Page Size | Maximum Row Size | Maximum Column Count | Maximum Index Size
4K | 4,005 | 500 | 255
8K | 8,101 | 1,012 | –
16K | 16,293 | 1,012 | –
32K | 32,677 | 1,012 | –

To achieve the same sort or retrieval sequence under DB2 as under the file system, place a BINARY XFD directive immediately before each key field that contains signed numeric data. High values and low values can cause problems in key fields. If you want data that uses the BINARY XFD directive to be stored as hexadecimal encoded CHAR types, you can specify A_DB2_USE_CHAR_FOR_BINARY in the ACUFH configuration file.

Parent topic: Database Connectors for DB2


Data Type Mapping

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The table below shows the mappings used by Database Connectors when interacting with DB2. Note how some mappings use a combination of the data type and XFD directive. For additional information on XFD directives, see Using XFD Directives .

If you are in a position where you need to create a COBOL file descriptor (FD) based on an existing data source table, use these mappings as a guide; although, getting them correct is not critical, as when Database Connectors opens an existing data source, mapping is carried out by matching the COBOL data names with the column names.

If you do need to accurately represent your data in the COBOL program, setting your data items as PIC X(nn) will work perfectly well (since most DB2 data types have a CHAR representation). For INTEGER types, use PIC9(9), or if you know the range of an INTEGER column (say, 0 to 999), you can match it more closely (by using PIC 9(3)).

COBOL Data Type | Database Connectors for DB2
Date (DATE XFD directive applied) | date
binary (BINARY XFD directive applied) | char (2 * x)
varchar (VAR_LENGTH XFD directive applied) | varchar
float | float
pic 9(4) | smallint
pic 9(9) | integer
pic 9(10) | decimal(10,0)
pic 9(x)v9(y) | decimal (x + y, y)
pic x(254) | char
pic x(255) | or greater must apply VAR_LENGTH XFD directive
Parent topic: Database Connectors for DB2
Related reference
Using XFD Directives
DATE XFD directive
BINARY XFD directive
VAR LENGTH XFD directive


Run-Time System Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic lists the Database Connectors for DB2 error messages that could occur during execution of your program. For information on compile-time errors and several methods for retrieving run time system errors, see the chapter Performance and Troubleshooting.

Run-time system errors have this format:

9/xxx

The 9 indicates a file system error and is reported as the first digit of the 2-byte FILE STATUS variable. The xxx is a binary value between 1 and 255 that provides more information. If xxx is 83, you can retrieve additional information with C$RERR. That additional information can come from either the database or the run time. Run-time codes returned with C$RERR include:

Code | Message
1 | Error reading the XFD file
2 | Corrupt XFD/dictionary file
3 | Error opening the XFD file
4 | Too many key fields (16 max)
12 | DB2 library function returned an unexpected error
13 | Illegal size or type of data for variable xxx
14 | More than one table with the same name

For a detailed description of a particular message, see the Error Messages section.

Parent topic: Database Connectors for DB2
Related reference
Troubleshooting
Error Messages


Common Questions and Answers

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic contains some questions and answers specific to Database Connectors for DB2.

On HP-UX platforms, which type of COBOL run time system - non-threaded or multi-threaded - should I use when connecting to the database?
You need to use the multi-threaded RTS, because DB2 is multi-threaded. If you use the non-threaded RTS, you will get a database connection error, because HP-UX does not allow the mixing of multi-threaded and non-threaded code.
On other UNIX/Linux platforms, you can use either run time system.
I'm noticing some performance degradation when accessing my DB2 data source. What is the cause of this?
You may notice some performance impact if you were previously accessing indexed files directly. This is because DB2 adds a software layer between your applications and your data sources. In return for minor performance impact, you can reap the benefits of database independence and enhanced portability. Overall performance depends on several factors, including your network configuration and your specific data source.
Parent topic: Database Connectors for DB2


Database Connectors for Microsoft SQL Server

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

These topics provide information specific to Database Connectors for Microsoft SQL Server.

  • Microsoft SQL Server Concepts Overview
  • Client Configuration
  • Filename Translation
  • ACUFH Configuration File Variables for MSSQL
  • Using the Database Table
  • Table Locking
  • Limits and Ranges
  • Supported Data Types for SQL Server
  • Run-Time System Errors
  • Common Questions and Answers
Parent topic: Database Connectors User's Guide


Microsoft SQL Server Concepts Overview

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This quick overview of some basic design concepts underlying the Microsoft SQL Server (MSSQL) Database Management System (RDBMS) helps to interface your COBOL program to it.

Servers

An MSSQL server is one copy of the database engine executing on a computer. A server has a name, and when a program wants to access a database controlled by that server, the program asks for a connection to the server by name. Multiple servers, controlling different databases, can be executing on a single machine. The default name that MSSQL gives to a server is localhost; refer to the A_MSSQL_DEFAULT_CONNECTION configuration variable for further details on how to connect your program to one or more servers.

Table Ownership

Table names in MSSQL have the form database.owner.table_name. Within MSSQL, if you are the owner of a given table, you can refer to it as just table_name. If you are not the owner, you must refer to it with the owner of the table as a prefix; thus, different owners can have tables of the same name. However, this is not true when you use the Database Connectors for MSSQL interface.

The Database Connectors interface works a little differently: it automatically determines the owner name used to reference a table. It is therefore essential that there are not multiple tables with the same name in a single database, even though the tables have different owners. If there are such multiple tables, the interface does not necessarily find the correct one, and no diagnostic is issued.

Table names include dots (.) as separators. Because of this, you must make sure there are no extensions on COBOL file names that could be converted to table names. For example, for a COBOL file named IDX1.DTA, the Connector attempts to open a table DTA with owner IDX1. You can avoid this problem either by renaming your COBOL file in your source program or by using a configuration file variable to map the file name to an allowable file name, such as:

IDX1.DTA  IDX1

In the above example, IDX1.DTA is the name in the ASSIGN clause of the file's SELECT statement.

If you map your file name to a new name, drop the extension to form the new name. The compiler uses the base file name — without the extension — to create the eXtended File Descriptor (XFD) file name IDX1.XFD. XFDs are explained in detail in XFDs. The run time system needs to locate this file. But if you've mapped the file name to something completely different (such as MYFILE), the run time looks for an XFD file named MYFILE.XFD. So you would have to remember to change the name of IDX1.XFD to MYFILE.XFD in the XFD directory. Dropping the extension when you map the name prevents having to perform this extra step.

Refer to 4GL_IGNORED_SUFFIX_LIST configuration variable for an alternate method of removing file extensions.

Security

Security is implemented in the MSSQL RDBMS. A user is required to log in to the RDBMS before any file processing can occur. Database Connectors provides both a default and a user-configurable method for implementing this; refer to Setting up the User Environment for further details on how to supply login details.

Generally, it is best for someone with database administrator (DBA) privileges to create and drop the tables, allowing others only the permissions to add, change, or delete information contained in them.

See the Microsoft SQL Server documentation for more details on DBA privileges.

Parent topic: Database Connectors for Microsoft SQL Server
Related information
A_MSSQL_DEFAULT_CONNECTION
4GL IGNORED SUFFIX LIST configuration variable
XFDs
Setting Up the User Environment


Client Configuration

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following section covers the client setup required before you begin using Database Connectors for Microsoft SQL Server (MSSQL) on a new system. The Microsoft SQL Server RDBMS must be installed and configured on the server prior to this, and must be at least version 6.5. Your client must also contain a correctly configured driver for the intended data source.

During the client installation, you will also be required to install some stored procedures; therefore, you require something such as Microsoft SQL Server's Query Analyzer or SQL Server command-line tools to run a query that installs these stored procedures.

Note: The default sort order for MSSQL is case-independent. Make sure that this is what you really want when you install the server. The Database Connectors connector uses the sort order as installed and cannot change its behavior to do case-dependent ordering if that is not what the server uses.

Follow the instructions below, which require you to install on both the server and the client. Where necessary, be sure to use the 64-bit libraries with a 64-bit run time system and 64-bit Database Connectors for MSSQL, and the 32-bit libraries with a 32-bit run time system and 32-bit Database Connectors for MSSQL.

  • Installing the Server and Client Machine
  • Setting Up a User Login
  • Setting Up the User Environment
  • Configuring the File Handler for Microsoft SQL Server
Parent topic: Database Connectors for Microsoft SQL Server


Installing the Server and Client Machine

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The Database Connectors interface for MSSQL is an add-on module. The installation includes a .DLL or .so file that is detected at run time. It is not necessary to relink the run time system.

Typically, the setup is one of a client machine using a Database Connectors connector to access an SQL database on a separate server; however, your SQL server and your client can be on the same machine. The Database Connectors interface can be executed on a machine that is running any supported Windows or Linux platform.

See To Install Database Connectors for Microsoft SQL Server for details on client and server configuration, regardless of how you are set up.

Parent topic: Client Configuration
Related information
Setting Up a User Login
Setting Up the User Environment
Configuring the File Handler for Microsoft SQL Server
To Install Database Connectors for Microsoft SQL Server


Setting Up a User Login

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

For Database Connectors for MSSQL to be able to communicate with the SQL Server, you must supply a valid user login that has access to the database that you are reading from and writing to. The user login must also have write access to the database in which you installed the stored procedures earlier.

You can set up either one general user login for all Database Connectors users or a login for each individual user. To set up a user login, you must have DBA privileges for the SQL Server; see the Microsoft SQL Server documentation for more information on setting up user logins.

Parent topic: Client Configuration
Related information
Installing the Server and Client Machine
Setting Up the User Environment
Configuring the File Handler for Microsoft SQL Server


Setting Up the User Environment

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To set up your user environment to use Database Connectors, the most convenient method is to populate an ACUFH configuration file with the configuration variables to suit your requirements; you can make a personalized copy of the ACUFH configuration file and set the A_CONFIG variable to point to this. Populate this file with the variables as detailed in ACUFH Configuration File Variables.

Alternatively, if you do not use a configuration file, you must set each required variable directly in the environment, either from the command line or programmatically.

Whichever method you use, you must at least set the valid user login details for your SQL Server. These are A_MSSQL_LOGIN and A_MSSQL_PASSWD. Alternately, you can set the configuration variable A_MSSQL_NT_AUTHENTICATION to TRUE.

Tip: For security reasons, we recommend setting A_MSSQL_PASSWD from your COBOL program, by prompting for a password and then executing:
 SET ENVIRONMENT "A_MSSQL_PASSWD" TO user-entry

On UNIX/Linux platforms, you should also ensure that the A_MSSQL_ODBC_DRIVER_NAME variable is set. This needs to be set to the exact name as specified in the odbcinst.ini configuration file used by the driver manager.

Parent topic: Client Configuration
Related reference
ACUFH Configuration File Variables for MSSQL
Related information
Installing the Server and Client Machine
Setting Up a User Login
Configuring the File Handler for Microsoft SQL Server


Configuring the File Handler for Microsoft SQL Server

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As well as the database-specific information that you specify in an ACUFH configuration file, you also need to inform the File Handler of which database type it is working with when performing file handling operations. You do this by specifying the IDXFORMAT, which can be set using one of the following methods:

  • Set at compile-time, either within your source code or on the command line.
  • Set in a File Handler configuration file, which is queried at run time.

The supported values for the IDXFORMAT option are:

IDXFORMAT No: | RDBMS:
18 | Microsoft SQL Server
19 | Oracle
20 | DB2
22 | ODBC

Set the format at compile-time

Set the option within your source code using the following syntax (replacing nn with the appropriate value from the table above):

      $set IDXFORMAT"nn"
       Identification Division.
       Program-id. Dbc-demo.
       ...
       End program Dbc-demo.

Or specify the IDXFORMAT on the command line, during compilation:

cob Dbc-demo.cbl IDXFORMAT"nn";
Note: Another method is to use the USE directive, specifying a directives file that contains the required IDXFORMAT.

Set the format at run time

Tip: Configuring the File Handler at run time enables you to use the same source code with more than one of the supported RDBMSs without the need to recompile. It also gives you greater control when setting different formats at once.

Set the option within a File Handler configuration file:

[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:/home/data/db2]
IDXFORMAT=20
[FOLDER:/home/data/oracle]
IDXFORMAT=19
Note: You cannot specify the values 18, 19, or 20 in the [XFH-DEFAULT] section of a configuration file. In the example above, IDXFORMAT 8 is used as default, but files placed in /home/data/db2, and /home/data/oracle use IDXFORMATs 20 and 19 respectively.

To use the configuration file at run time, you must specify it in the EXTFH environment variable:

EXTFH=/home/dbc/extfh.cfg
export EXTFH

sets the file name to /home/dbc/extfh.cfg.

Parent topic: Client Configuration
Related information
Installing the Server and Client Machine
Setting Up a User Login
Setting Up the User Environment
The Demonstration Program
Preparing and Compiling Your COBOL Program


Filename Translation

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As you prepare to work with Database Connectors for MSSQL, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUFH configuration file variables, the run time system translates the file name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

However, the Connector needs the name of the file to find the appropriate XFD file. To do this, Database Connectors changes the name of the file to lowercase letters and changes hyphens to underscores. Note, however, that this is performed only on a local copy of the file. Once the XFD file is found, the filename reverts to the name that was originally passed to the open() function. Characters that are illegal in identifiers, such as a hyphen ("-"), are trapped by Database Connectors neither find the file nor create a new one.

Parent topic: Database Connectors for Microsoft SQL Server


ACUFH Configuration File Variables for MSSQL

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before running Database Connectors, you must set the A_CONFIG environment variable to the name of the ACUFH configuration file. You may want to make and use a personalized copy of the ACUFH configuration file to avoid impacting other users. Set the A_CONFIG environment variable to identify your own personal copy. For example:

SET A_CONFIG=directory-name\my-file-name

ensures the specified configuration file is used when interfacing with your database.

This section lists the ACUFH configuration file variables that are specific to MSSQL. For ACUFH configuration file variables that are generally applicable to any RDBMS with which Database Connectors communicates, see ACUFH Configuration Variables in the Run Time Configuration section.

As a minimum, you should set the following configuration variables:

  • A_MSSQL_DEFAULT_CONNECTION
  • A_MSSQL_LOCK_DB
  • A_MSSQL_DATABASE
  • A_MSSQL_ODBC_DRIVER_NAME
    Note: For Windows platforms, the default value of this variable - SQL Server - should suffice, and so this variable doesn't need to be explicitly set; for Linux\UNIX platforms, the variable should be explicitly set to the value of the driver name as specified in the driver manager's odbcinst.ini file.

and either:

  • A_MSSQL_LOGIN
  • A_MSSQL_PASSWD

or:

  • A_MSSQL_NT_AUTHENTICATION
Variable | Description
A_MSSQL_ADD_IDENTITY | Adds an extra column to any table created by the Connector
A_MSSQL_ADD_TIMESTAMP | Ensures that modifications made to a row are not overwriting someone else's changes
A_MSSQL_APPROLE_NAME | Allows the Connector to use approles
A_MSSQL_APPROLE_PASSWD | Allows the Connector to use approles
A_MSSQL_CREATE_UNICODE_COLUMNS | Creates nchar or nvarchar columns for all new text data
A_MSSQL_CURSOR_OPTION_1, A_MSSQL_CURSOR_OPTION_2, A_MSSQL_CURSOR_OPTION_3 | Allow you to fine-tune the declaration of cursors in the Connector
A_MSSQL_DATABASE | Specifies the name of the particular database to be accessed
A_MSSQL_DEADLOCK_LOOPS | Can be used to instruct the Connector to re-execute an INSERT statement
A_MSSQL_DEFAULT_CONNECTION | Specifies the name of the server to which the run time system connects
A_MSSQL_DEFAULT_OWNER | Specifies the name of the user of a table
A_MSSQL_DO_NOT_TRANSLATE_CHAR | Enables all character fields (except date fields) to be treated as binary, instead of being translated
A_MSSQL_FAILOVER_PARTNER | Specifies the name of the failover partner used when multi-subnet failover support is enabled
A_MSSQL_FAILOVER_PARTNER_SPN | Specifies the name of the failover partner SPN used when multi-subnet failover support is enabled
A_MSSQL_FAST_ACCESS | Files opened while this variable is set to a nonzero value are optimized for forward sequential access
A MSSQL IGNORE GUID COLUMNS | Enables you to ignore columns of type GUID
A_MSSQL_LIMIT_DROPDOWN | This variable allows an application to direct the interface not to perform "drop down" query generation and instead return "end of file" when the records matching the current query have been exhausted.
A_MSSQL_LOCK_DB | Specifies the name of the database that holds the lock table
A_MSSQL_LOGIN | Indicates the user name under which you want to connect to the database system
A_MSSQL_MAX_BINARY_LENGTH | Specifies the maximum size of a COBOL variable that can be used as a BINARY data type
A_MSSQL_MAX_CHAR_LENGTH | Specifies the maximum size of a COBOL variable that can be used as a VARCHAR data type
A_MSSQL_MAX_CHARACTERS | Indicates the maximum number of bytes the Connector allows in a table row
A_MSSQL_MAX_COLUMNS | Indicates the maximum number of columns the Connector allows in a table
A_MSSQL_MULTI_SUBNET_FAILOVER | Set to TRUE to enable multi-subnet failover support for your Microsoft SQL Server connection
A_MSSQL_NATIVE LOCK_TIMEOUT | Enables the native locking method (as opposed to the AcuLocks1 table being used to hold locks).
A_MSSQL_NO_CACHED_READ | Determines if the 'cached-read' method, which can improve performance, is in effect
A_MSSQL_NO_COUNT_CHECK | Causes the interface not to check that a record was updated
A_MSSQL_NO_DBID | Causes the interface to use a Database ID of "0", instead of the actual ID of the database
A_MSSQL_NO_RECORD_LOCKS | Causes all READS to be treated as READ NO LOCK
A_MSSQL_NO_TABLE_LOCKS | Causes the interface to not use the AcuOpenTables1 table, which causes all table locking to be disabled
A_MSSQL_NO_23_ON_START | Causes START not to detect whether records actually exist
A_MSSQL_NT_AUTHENTICATION | Indicates whether MSSQL authenticates users based on their Windows login
A_MSSQL_ODBC_DRIVER_NAME | Specifies the ODBC SQL Server driver name for the SQL Server interface
A_MSSQL_PACKETSIZE | Sets the size of network packets
A_MSSQL_PASSWD | Set to the password assigned to the database account associated with the user name specified by A_MSSQL_LOGIN
A_MSSQL_ROWCOUNT | Determines how many rows are returned by a SELECT statement sent to the server
A_MSSQL_SELECT_KEY_ONLY | Directs the interface to select key columns only when searching for records
A_MSSQL_SEPARATE_LOCK_CONN | Determines whether a separate connect is made to handle the internal workings
A_MSSQL_SERVER_SPN | Specifies the name of the server SPN used when multi-subnet failover support is enabled
A_MSSQL_SKIP_ALTERNATE_KEYS | Determines whether alternate keys are used to form indexes during table creation
A_MSSQL_STRIP_PATH_INFO | Strips the Servername portion from the MSSQL naming syntax
A_MSSQL_TRANSACTION_LEVEL | Indicate the transaction nested level depth
A_MSSQL_TRANSLATE_TO_ANSI | Causes the Connector to call the same translation function used by the Windows run time system to translate characters going to the server into the OEM character set, and to translate characters coming from the server to ANSI
A_MSSQL_UNLOCK_ON_EXECUTE | Causes all invocations of I$IO using the EXECUTE opcode to unlock all records
A_MSSQL_UPDATE_PRIMARY_COLS | Updates all the fields in a table in files that have only primary key fields
A_MSSQL_USE_DROPDOWN_QUERIES | Causes selects sent to the database to be of the drop-down variety, instead of a single large query
Parent topic: Database Connectors for Microsoft SQL Server
Related information
ACUFH Configuration Variables


Using the Database Table

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The database table is built and accessed automatically when the COBOL application is executed. To the end user, the interaction between the COBOL and the MSSQL database is invisible; queries are generated and data is exchanged in fractions of a second, and the application proceeds without interruption.

You can also access the database information directly from MSSQL, at your option.

To create a sample COBOL application, see Preparing and Compiling a Program Example.

Parent topic: Database Connectors for Microsoft SQL Server


Table Locking

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

By default, MSSQL doesn't support the type of record and table locking that COBOL expects. For this reason, the Connector implements its own locking method. This is accomplished with the addition of two tables to a database. You choose the database to hold these tables during installation of Database Connectors.

Before using the locking tables, you must execute the included ms_inst.sql script. (See the installation instructions you used from this manual for the exact procedure. You can find them in the Contents.) If you don't perform this step, the first time you try to execute a COBOL program that opens an MSSQL table, error 11, Lock Table Incorrect, occurs.

AcuLocks1 Table

The first locking table is called AcuLocks1; it holds the record locks. The columns in this table are the

  • DBID
  • Table ID
  • Process ID of the process holding the lock
  • Primary key of the record that is locked

There is a unique index on the DBID, the Table ID, and the Key Value, so that inserts into this table are automatically rejected if another user holds a lock on the row in question. This also gives the DBA the information needed to determine who has locks set, and whether the user in question still has a connection to the server.

AcuOpenTables1 Table

The second locking table is called AcuOpenTables1; it holds information about open tables.

The columns in this table are

  • The DBID
  • The Table ID
  • The process ID (PID) of the process that has the table open
  • The Open Mode (Input, Output, I/O or Extend)
  • Whether Multiple records can be locked
  • Whether the file can be open for I/O by any other users
  • Whether the file can be open at all by any other users
  • Whether Mass Update was specified in the open

There are no indices on this table, but there is a trigger, which reject opens that are not allowed based on other users' open modes.

By using these lock tables, Database Connectors is able to support all the types of locking ordinarily supported. No special configuration variables are required.

This method of locking is all that is needed if no applications other than COBOL programs are going to be using Database Connectors for MSSQL. But if your site has other applications that access the MSSQL databases, you must use a method of locking that is inherent to Microsoft SQL Server.

Another method of locking that Microsoft SQL Server supports internally is the result of time stamping and the use of BROWSE MODE (see the discussion of BROWSE MODE in the Microsoft SQL Server Commands Reference Manual). If a table has a timestamp column, the Connector uses browse mode. This allows the server to detect whether another application has modified a record while locked by the server.

Parent topic: Database Connectors for Microsoft SQL Server


Limits and Ranges

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The following limits exist when working with MSSQL:
Maximum number of columns per key: | 16
Maximum number of columns: | 1024
Maximum number of bytes in a single row when using Database Connectors for MSSQL: | 8060

To achieve the same sort or retrieval sequence under MSSQL as under the file system, key fields that contain signed numeric data must be preceded by a BINARY XFD directive.

Database Connectors supports the data types shown below; when it's creating tables, the following conversion rules are used, in the sequence shown:

COBOL SQL Server
DATE XFD directive
DATETIME
BINARY XFD directive
VARBINARY(n) (if SIZE < 255)
IMAGE (if SIZE >255)
VAR_LENGTH XFD directive
VARCHAR(n) (if SIZE < 255)
Usage FLOAT
REAL (if SIZE = 4)
Usage DOUBLE
FLOAT (if SIZE = 8)

Any other numeric usage:

PIC 9(n)V9(m)
SMALLINT (if m = 0 and n < 5)
INT (if m = 0 and n < 10)
DECIMAL(n + m, m)(otherwise)

Any other usage:

PIC X(n)
CHAR(n) or NCHAR(n) (if n < 255)
(Note: NCHAR columns are dependent on the variable A_MSSQL_CREATE_UNICODE_COLUMNS set to TRUE)
TEXT (if n > 255)
Note: If the VAR_LENGTH XFD directive is in effect, VARCHAR and NVARCHAR types are created instead.
Parent topic: Database Connectors for Microsoft SQL Server


Supported Data Types for SQL Server

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The table below shows the mappings used by Database Connectors when interacting with Microsoft SQL Server.

Data type | Generated using...
DATETIME | The DATE XFD directive, specifying both date and time information.
DATE | The DATE XFD directive, specifying only date information.
TIME | The DATE XFD directive, specifying only time information.
BINARY(n) | The BINARY XFD directive, specifying a COBOL field 8000 bytes or less. n refers to the number of bytes.
IMAGE | The BINARY XFD directive, specifying a COBOL field greater than 8000 bytes.
CHAR(n) or NCHAR(n) | A COBOL field of type PIC X(n), where n is less than 8000 characters/digits. For NCHAR, the Unicode and COBOL conversion is also dependent on the COBOL item being of USAGE NATIONAL.
GUID | A COBOL field of type PIC X(36). Note: Support is only for existing tables containing this type; Database Connectors cannot create a new column of this type. If required, use the A_MSSQL_IGNORE_GUID_COLUMNS configuration variable to ignore the GUID column in a table.
TEXT | A COBOL field of type PIC X(n), where n is 8000 characters/digits or more.
VARCHAR(n) or NVARCHAR(n) | The VAR_LENGTH XFD directive and specifying a COBOL field of type PIC X(n), where n refers to the size of the COBOL field. For NVARCHAR, the Unicode and COBOL conversion is also dependent on the COBOL item being of USAGE NATIONAL.
FLOAT | A COBOL field of type DOUBLE.
REAL | A COBOL field of type FLOAT.
TINYINT | A COBOL field of type PIC 9 or PIC 99.
SMALLINT | A COBOL field of type PIC 9(3) or PIC 9(4).
INT | A COBOL field of type of PIC 9(5) to PIC 9(8).
BIGINT | A COBOL field of type PIC 9(9) to PIC 9(18).
DECIMAL(n,0) | A COBOL field of type PIC(19) or larger, where n is the number of digits.
DECIMAL(n,m) | A decimal COBOL field, where n refers to the number of digits to the left of the decimal point and m refers to the number of digits to the right of the decimal point.
Parent topic: Database Connectors for Microsoft SQL Server
Related reference
BINARY XFD directive
VAR_LENGTH XFD directive
DATE XFD directive
A_MSSQL_IGNORE_GUID_COLUMNS


Run-Time System Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic lists the Database Connectors for MSSQL error messages that could occur during execution of your program. For information on compile-time errors and several methods for retrieving run time system errors, see the chapter Performance and Troubleshooting.

Run time system errors have this format:

9/xxx

The 9 indicates a file system error and is reported as the first digit of the 2-byte FILE STATUS variable. The xxx is a binary value between 1 and 255 that provides more information. If xxx is 83, you can retrieve additional information with C$RERR. That additional information can come from either the database or the run time. Run-time codes returned with C$RERR include:

Code | Message
1 | Error reading the XFD file
2 | Corrupt XFD/dictionary file
3 | Error opening the XFD file
4 | Too many key fields (16 max)
5 | (no message associated with this error)
11 | Stored procedures not found
12 | A column of a key is of data type TEXT or IMAGE, which is illegal
13 | Internal error
14 | DB library function returned an unexpected error
16 | Trying to rename a table across databases
17 | Cache error
18 | Primary Key error
19 | Table Size Error
20 | (no message associated with this error)
21 | (no message associated with this error)

For a detailed description of a particular message, see the Error Messages section.

Parent topic: Database Connectors for Microsoft SQL Server
Related reference
Troubleshooting
Error Messages


Common Questions and Answers

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic contains some questions and answers specific to Database Connectors for MSSQL.

When I try to open a file for output, I get the error 9/83, with a secondary error of 2714. There is already an object named "*" in the database. Why?
One of your record's data items probably has the same name as an MSSQL reserved word. Locate the column by comparing a file trace of the CREATE TABLE to MSSQL's list of reserved words. Apply the NAME XFD directive to the field in the file descriptor (FD) that is associated with the invalid column, then recompile the program to create a new XFD file.
Can I open tables in different databases?
Yes. Use a file name like:
database.owner.tablename

Note that, because Database Connectors for MSSQL automatically determines an owner, you can also specify a file name like database..tablename. The two dots are mandatory in this case.

Can I use multiple servers (on the same machine or on different machines) on my network?
Yes. Each server has a unique name.
I'm getting an error 9/83, with a secondary error of 11, Micro Focus lock table missing. I know that I added the lock table during installation.
This is probably a permissions problem. All users must have READ, WRITE, UPDATE, and DELETE access to AcuLocks1 (and therefore to the database that contains it). Be sure to check your permissions.
I keep receiving an error message saying that my login is invalid. But I'm sure I'm using the correct username and password.
All usernames, passwords, and database names are case-sensitive. Be sure that you are typing the names exactly as they are set up.
Are there any library routines that do not work with or would not make sense to use with Database Connectors for MSSQL?
Two library routines that either don't work with or do not make sense to use with Database Connectors for MSSQL: C$COPY and C$RECOVER.
Parent topic: Database Connectors for Microsoft SQL Server


Database Connectors for ODBC

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

These topics provide information specific to Database Connectors for ODBC.

  • ODBC Concepts
  • Client Configuration
  • Configuring the File Handler for ODBC
  • Filename Translation
  • ACUFH Configuration File Variables for ODBC
  • Decimal Points
  • Mixed-case SQL Identifiers
  • Record and Table Locking
  • Limits and Ranges
  • Driver Requirements
  • Data Type Mapping
  • Run-time System Errors
  • Common Questions and Answers
Parent topic: Database Connectors User's Guide


ODBC Concepts

With Database Connectors for ODBC, your application can access the most common database formats found on desktop computer systems, as well as relational database management systems on UNIX or Windows servers.

These topics give a brief overview of concepts you’ll need to work with ODBC.

  • What Is ODBC?
  • Origins of ODBC
  • Restrictions
  • ODBC Structure
Parent topic: Database Connectors for ODBC


What Is ODBC?

Open Database Connectivity (ODBC) is a library of standardized data access functions. It’s intended to give programmers a way to access and manipulate data in a variety of data sources.

ODBC operates in a way that is similar to Informix ESQL/C and Oracle Pro*COBOL®. The main difference is that ODBC offers the advantage of being able to access almost any data source.

With traditional call-level interfaces (CLI), you are required to learn the Application Programming Interface (API) for each data source. If you want to port an application from one data source to another, you must write a complete new access module.

ODBC was designed expressly to access almost any data source. It offers a standard API that can be used to manipulate data in a Microsoft Access database on your PC, or connect from your PC to an Oracle database on a UNIX host. It can even access files that are not databases, such as Btrieve data files and Excel spreadsheets.

Parent topic: ODBC Concepts


Origins of ODBC

ODBC is able to access a wide variety of file systems because it takes advantage of their common properties and common standards. For example, most of the popular database systems on the market today bear a strong resemblance to each other, both in functionality and in the methods they use to access data. This is because the major vendors’ products are based in whole or in part on the relational database concepts of E. F. Codd. ODBC makes use of these commonalties.

Shared standards also lend power to ODBC. Several groups have been working to set standards in the UNIX environment, where much of the database technology originated. These groups include the ANSI standards committee, the X/Open consortium, and the SQL Access Group. Together, these groups have devised much of the core technology that Microsoft has organized into ODBC.

Parent topic: ODBC Concepts


Restrictions

ODBC does not make your application instantly portable to any database or data source that has ODBC support. Many layers of software are involved in the data retrieval process, and each layer adds its own restrictions.

The major component that makes an ODBC connection work is the ODBC driver. See ODBC Structure for more information. The driver processes API function calls, submits SQL requests to a specific data source or DBMS, and returns results.

ODBC drivers are available from a variety of vendors and offer very different levels of support and performance. The sources of the data that the drivers connect to also offer very different capabilities in areas such as record locking, file operations, and transaction management. These differences in performance and capability can have a significant impact on your application.

Parent topic: ODBC Concepts
Related information
ODBC Structure


ODBC Structure

A quick overview of the components of ODBC will help you interface your COBOL program to ODBC-compliant data sources.

ODBC requires four components: an ODBC-enabled application, the ODBC driver manager, ODBC database drivers, and data sources. The following diagram indicates how these components work together in a single-tier environment.

Single-tier ODBC architecture

The following diagram indicates how these components work together in a multiple-tier environment.

Multiple-tier ODBC architecture

Application

The application is your COBOL program, or more precisely, the COBOL run-time system together with Database Connectors for ODBC. The runtime generates the appropriate SQL queries to accomplish the file I/O task that your COBOL program is executing. This includes all file positioning and record locking. When the query results are returned to the COBOL run-time system, they are mapped either to a COBOL record or to the appropriate COBOL status code, if one exists.

Driver Manager

The driver manager loads the ODBC driver. The driver manager then passes requests to the driver and returns results to the COBOL run-time system. For the Microsoft Windows environment, the driver manager is called ODBC32.DLL for 32-bit architectures.

The driver manager is typically included with the ODBC driver and is often installed along with the driver. For some products, such as Microsoft Access and Excel, the driver manager is installed automatically if you choose the ODBC support option while installing the product. (The ODBC support option tends to be part of the custom install process.)

Driver

The driver processes ODBC requests and returns data to the driver manager and your application. If necessary, the driver translates the runtime’s SQL request into a form that is understood by the target data source.

Your application is not limited to communicating through just one driver, however. By setting the ACUFH configuration variable A_ODBC_DATASOURCE, you can direct the COBOL run-time system to connect to a different driver for any given file. Simply set this variable before opening the indexed data file. The Database Connectors interface for ODBC will then handle connecting to the new data source and performing any operations necessary to open the file.

The driver is the most important feature of ODBC. ODBC drivers for a given data source may be available from many different vendors. They vary greatly in performance and in the options they provide for a given data source. Be sure to carefully review a data source driver to determine its level of performance.

Your Database Connectors for ODBC disks include a program that tests your ODBC driver for the various functions the Database Connectors product requires. This program is called DRVTST32.EXE. You initiate it by selecting the appropriate icon in the Database Connectors for ODBC program group. Please see Driver Requirements for instructions on using the driver test program. This topic also describes the minimal requirements that your driver must meet to work with Database Connectors for ODBC.

Data Sources

Data sources are the files or databases accessed by a driver. Each data source must be identified during setup.

Some data sources are simple to identify. For example, to access a text file, you would provide the name and location of the file. Some are more complex, though. For example, to access a UNIX-hosted database such as Oracle, you would identify the Windows drivers, Windows applications, network connections, and database information.

In Windows, you set up an ODBC data source in the Windows control panel, Administrative Tools dialog. After you double-click the Data Sources (ODBC) icon, an ODBC Data Source Administrator dialog is displayed. You must designate the driver, the data source, and any other information necessary to access the data. Setup procedures are described in detail in the Installation section.

Parent topic: ODBC Concepts
Related reference
Driver Requirements
ACUFH Configuration File Variables for ODBC


Client Configuration

The following sections describe the steps you must perform before you begin using Database Connectors for ODBC on a new system:

  • ODBC Installation
  • Setting Up Data Sources
  • Setting Up the User Environment
  • Designating the Host File System
  • Designating the Host Data Source
Parent topic: Database Connectors for ODBC


ODBC Installation

To configure Database Connectors for ODBC, the ODBC core components (Windows) or a supported ODBC driver manager (UNIX) must be installed, then you can install one of the supported ODBC drivers.

These products are not provided by Micro Focus, but may have been installed alongside any ODBC drivers or data sources that you already have on your system. For example, if you have installed Microsoft Access on your computer, the Access drivers and ODBC may have been automatically installed.

Windows:

Since Windows XP and Windows Server 2003, the ODBC core components are included in the operating system. Follow these steps to determine if this is the case:

  1. Open the Windows control panel.
  2. Double-click the Administrative Tools icon, then select Data Sources (ODBC). (On older versions of Windows, select the 32-bit ODBC icon directly from the control panel.)

    The ODBC Data Source Administrator dialog box is displayed, showing all the data sources currently configured for your system.

    If the ODBC icon is not in your control panel, ODBC is probably not installed on your system. To install ODBC on your system, you have two options:

    • Buy an ODBC driver from a driver or database vendor and install it. ODBC is installed automatically.
    • Buy and install a Windows-based ODBC data source. The ODBC driver and ODBC will be one of the install options.

UNIX:

The following ODBC driver managers are supported:

  • unixODBC (www.unixodbc.org)
  • DataDirect (www.progress.com)
  • iODBC (www.iodbc.org)

Refer to the ODBC driver manager documentation for instructions on how to make ODBC driver manager communicate with one of the supported ODBC drivers.

When correctly configured, you need to ensure that the lib directory of the driver manager, and the lib sub-directory of your product installation directory is included in the LD_LIBRARY_PATH environment variable.

  • Supported Drivers
Parent topic: Client Configuration


Supported Drivers

Database Connectors for ODBC supports a number of different ODBC drivers, for connecting to a number of compatible databases.

Once the ODBC core components (Windows) or supported driver manager (UNIX) has been installed, you can install any of the following drivers:

  • Microsoft SQL Server ODBC driver versions 11 and 13 (Windows), or version 17 (UNIX/Linux).
  • IBM DB2 ODBC driver Version 9.5.
  • IBM Informix ODBC version 3.7.
  • Oracle ODBC driver version 9.2 10.1 10.2.

Refer to the vendor documentation for details on the database versions compatible with the supported drivers.

Parent topic: ODBC Installation


Setting Up Data Sources

You will need to set up a data source name for any item you want to be able to access from Database Connectors for ODBC.

On Windows, use the ODBC Data Source Administrator to add a data source. The exact steps required for this will vary for each individual driver, but the general steps for setting up an ODBC data source are:

  1. Open the Windows control panel and click Administrative Tools.
  2. Double-click the ODBC Data Sources.

    The ODBC Data Source Administrator dialog is displayed. This dialog lists all the data sources currently configured for your system.

  3. Double-click on the data source you plan to use to access a setup dialog. A subsequent window lets you add a description of the data source and allows you to supply other information the driver requires.

If the data source you want is not listed, choose Add to indicate which driver to use for the data source you will create. Remember, the exact steps required for setting up a driver vary greatly between drivers and driver vendors. Please refer to the driver’s documentation for precise details on this step. We recommend that you test the setup of your new data source. Many data sources come with a testing utility for this purpose.

On Linux and UNIX platforms, refer to the vendor instructions for the driver manager for details on how to add a data source.

Parent topic: Client Configuration


Setting Up the User Environment

In addition to setting the variables required for ODBC, you will need to do the following:

To set up your user environment to use Database Connectors, the most convenient method is to populate an ACUFH configuration file with the configuration variables to suit your requirements; you can make a personalized copy of the ACUFH configuration file and set the A_CONFIG variable to point to this. Populate this file with the variables as detailed in ACUFH Configuration File Variables.

Alternatively, if you do not use a configuration file, you must set each required variable directly in the environment, either from the command line or programmatically.

Whichever method you use, you must at least set the valid user login details for your data source. These are A_ODBC_LOGIN and A_ODBC_PASSWD.

Tip: For security reasons, we recommend setting A_ODBC_PASSWD from your COBOL program, by prompting for a password and then executing:
 SET ENVIRONMENT "A_ODBC_PASSWD" TO user-entry
Parent topic: Client Configuration


Designating the Host File System

Each time the COBOL application creates a new file, it needs to know which file system to use. The run-time checks the file system to use when the file is opened. You provide the name of the file system with one of two run-time configuration file variables. The first is:

DEFAULT_HOST filesystem

This will designate the file system to be used for newly created files that are not individually assigned. For example,

DEFAULT_HOST ODBC

means that all new files will be ODBC files unless otherwise specified by the second configuration variable, which is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. This configuration variable is used to assign an individual data file to a different file system. Any file so assigned will use the designated file system, and not the one specified by DEFAULT_HOST. For example,

myfile_HOST VISION

means that myfile will be under the Vision file system. The ability to designate a different file system for certain files enables you to tailor your application to a specific customer’s needs or to implement an incremental conversion for a customer. With relational databases, this is particularly useful in that it allows you to tune an application for processing speed and resource requirements.

You can use these run-time configuration file variables in combination to assign your new files in a default with exceptions manner; for example, this set of entries:

DEFAULT_HOST VISION
afile_HOST ODBC
bfile_HOST ODBC

means that all new files except afile and bfile will be assigned to Vision, and those two files will be assigned to ODBC.

You can also change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. This is not the typical way to specify a file system; normally it is designated in the run-time configuration file and is not changed in the COBOL program.

Note:

The Acu4GL for ODBC product allows you to create an ODBC table with an OPEN OUTPUT statement, just as you can create Vision indexed files, if the data source driver allows for table creation. The ODBC equivalent of a Vision file is a table, not a database. You must create a database for your ODBC tables before you run the COBOL program that creates the tables, just as you must create a directory for your files before you run a COBOL program that creates Vision files.

Parent topic: Client Configuration


Designating the Host Data Source

You must tell the run-time system which data source to use for your ODBC file. You accomplish this by setting the configuration variable A_ODBC_DATASOURCE to the exact name that you set up in the Windows ODBC driver manager. You can set this variable in your COBOL configuration file if using only one data source.

For example, if the data source you want to select is listed in the control panel ODBC window as:

MS Access Databases (Access Data (*.mdb))

you should add the following line to your configuration file:

A_ODBC_DATASOURCE MS Access Databases

If you used the Add option to configure a new data source driver, set A_ODBC_DATASOURCE to the personalized name that you entered in the Add window.

If you do not know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "MS Access Databases"

After you learn about and use this utility, you next find out about preparing and compiling your COBOL program, followed by learning to use the demonstration program.

Parent topic: Client Configuration


Configuring the File Handler for ODBC

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As well as the database-specific information that you specify in an ACUFH configuration file, you also need to inform the File Handler of which database type it is working with when performing file handling operations. You do this by specifying the IDXFORMAT, which can be set using one of the following methods:

  • Set at compile-time, either within your source code or on the command line.
  • Set in a File Handler configuration file, which is queried at run time.

The supported values for the IDXFORMAT option are:

IDXFORMAT No: | RDBMS:
18 | Microsoft SQL Server
19 | Oracle
20 | DB2
22 | ODBC

Set the format at compile-time

Set the option within your source code using the following syntax (replacing nn with the appropriate value from the table above):

      $set IDXFORMAT"nn"
       Identification Division.
       Program-id. Dbc-demo.
       ...
       End program Dbc-demo.

Or specify the IDXFORMAT on the command line, during compilation:

cob Dbc-demo.cbl IDXFORMAT"nn";
Note: Another method is to use the USE directive, specifying a directives file that contains the required IDXFORMAT.

Set the format at run time

Tip: Configuring the File Handler at run time enables you to use the same source code with more than one of the supported RDBMSs without the need to recompile. It also gives you greater control when setting different formats at once.

Set the option within a File Handler configuration file:

[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:/home/data/db2]
IDXFORMAT=20
[FOLDER:/home/data/oracle]
IDXFORMAT=19
Note: You cannot specify the values 18, 19, or 20 in the [XFH-DEFAULT] section of a configuration file. In the example above, IDXFORMAT 8 is used as default, but files placed in /home/data/db2, and /home/data/oracle use IDXFORMATs 20 and 19 respectively.

To use the configuration file at run time, you must specify it in the EXTFH environment variable:

EXTFH=/home/dbc/extfh.cfg
export EXTFH

sets the file name to /home/dbc/extfh.cfg.

Parent topic: Database Connectors for ODBC


Filename Translation

As you prepare to work with Database Connectors for ODBC, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the COBOL compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through configuration variables, the runtime translates the name in the COBOL program into the filename that is passed to the open() function in the runtime. The open() function determines which file system to pass the request to, but does not change the name of the file.

Database Connectors for ODBC translates the name to lowercase letters and changes hyphens to underscores unless the configuration variable, 4GL_COLUMN_CASE, is set. This “new” name is the one that Database Connectors for ODBC will use in the future for references to database tables.

Parent topic: Database Connectors for ODBC
Related information
4GL COLUMN CASE configuration variable


ACUFH Configuration File Variables for ODBC

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before running Database Connectors, you must set the A_CONFIG environment variable to the name of the ACUFH configuration file. You may want to make and use a personalized copy of the ACUFH configuration file to avoid impacting other users. Set the A_CONFIG environment variable to identify your own personal copy. For example:

SET A_CONFIG=directory-name\my-file-name

ensures the specified configuration file is used when interfacing with your database.

This section lists the ACUFH configuration file variables that are specific to ODBC connections. For ACUFH configuration file variables that are generally applicable to any RDBMS with which Database Connectors communicates, see ACUFH Configuration Variables in the Run Time Configuration section.

As a minimum, you should set the following configuration variables:

  • A_ODBC_DATASOURCE

and then:

  • A_ODBC_LOGIN
  • A_ODBC_PASSWD
Variable | Description
A_ODBC_ALTERNATE_COMMT_LOGIC | Determines how the connection responds to transaction requests
A_ODBC_CATALOG | Specifies the catalog in use for the connection
A_ODBC_COMMIT_ON_BEGIN | Marks the start of a transaction
A_ODBC_DATASOURCE | Determines the name of the datasource you connect to
A_ODBC_ERROR_MAP_FILE | Enables the use of a map file that maps database errors to your COBOL error codes
A_ODBC_ISOLATION_LEVEL | Determines the isolation level of the connection
A_ODBC_LOCK_METHOD | Determines the locking method for the connection
A_ODBC_LOGIN | Login details for the associated database
A_ODBC_NO_NULL_COLUMNS | Determines if NULL is permitted to be inserted into a database
A_ODBC_PASSWD | Login details for the associated database
A_ODBC_PRINT_LOG | Debugging variable; do not use unless instructed to
A_ODBC_QUOTE_IDENTIFIERS | Tests for the IDENTIFIER-QUOTE-CHAR, and if found, uses it
A_ODBC_STRICT_EQUAL | A performance enhancing variable that makes SELECT statements more efficient
A_ODBC_TABLE_TYPES | A performance enhancing variable that enables you to defines the type of table to search for
A_ODBC_UNSIGNED_TINYINT | Overrides driver behavior when a TINYINT data type is assigned to an internal unsigned type
A_ODBC_USE_CATALOG | Enables the use of a catalog in SQL queries
A_ODBC_USE_CHAR_FOR_BINARY | Allows you to store data that uses the BINARY directive as hexadecimal encoded CHAR types
A_ODBC_USE_SPACE_IN_DATES | Allows the use of spaces in dates
A_ODBC_USE_SQLCOLUMNS | Uses the SQLColumns() API function to call SQLDescribeCol(). This is a useful time-saving task for large databases.
A_ODBC_USE_SQLTABLES | Builds a test SQL query and uses the SQLTables() API function to call SQLNumResultCols() to determine if a table exists. This is a useful time-saving task for large databases.
Parent topic: Database Connectors for ODBC


Decimal Points

Database Connectors for ODBC reads the decimal point character from the environment variable DECIMAL_POINT. If DECIMAL_POINT is set, Database Connectors uses that character. If the variable is not set, Database Connectors uses the decimal character that is encoded in the XFD file.

The two most common decimal indicators are the period “.” and the comma “,” characters. The comma is used often in European code and is often indicated in COBOL programs by the "DECIMAL POINT IS COMMA" clause.

Parent topic: Database Connectors for ODBC


Mixed-case SQL Identifiers

Identifiers in SQL-92 are not case-sensitive. However, drivers that do not conform strictly to SQL-92 may require mixed-case identifiers.

If your driver enforces a mixed case, do the following:

  1. Compile your source COBOL program with the “-Fc” option to generate mixed-case identifiers in your XFD files.
  2. Modify the filename in your COBOL program to match the target identifier’s case.
  3. In your configuration file, set the configuration variable 4GL_COLUMN_CASE to “UNCHANGED”.

    Possible values are UPPER, LOWER, UNCHANGED.

Parent topic: Database Connectors for ODBC


Record and Table Locking

Database Connectors for ODBC supports record locking for multi-user systems, as long as your ODBC driver supports record locking. To complement your driver’s locking method, Database Connectors for ODBC can initiate three locking sequences:

  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

You specify which type of locking you want to use with the configuration file variable, A_ODBC_LOCK_METHOD. However, if your driver doesn’t support locking, Database Connectors for ODBC by itself cannot provide locking.

Record locking with ODBC drivers is a semi-random activity. Different ODBC drivers have different capabilities and even implement the same capabilities in different ways. For this reason, you will have to do some experimentation to determine which locking method to specify for A_ODBC_LOCK_METHOD. Only through trial and error will you be able to determine which method will lock records in the most efficient way for your particular ODBC driver.

Parent topic: Database Connectors for ODBC


Limits and Ranges

The following limits exist for the ODBC protocol:

  • Maximum number of columns per key: depends on driver/database
  • Maximum number of columns: depends on driver/database

Database Connectors allows an unlimited number of columns, but the database may have a limit, and the driver may have a smaller limit than the database. If you have too many columns, you will receive a database error on the table create (for example, open output).

To achieve the same sort or retrieval sequence under ODBC as under the Vision file system, place a BINARY directive immediately before each key field that contains signed numeric data. High values and low values can cause problems in key fields. If you want data that uses the BINARY directive to be stored as hexadecimal encoded CHAR types, you can specify A_ODBC_USE_CHAR_FOR_BINARY in the configuration file. Please note that this could potentially increase the size of your key beyond the driver maximum.

Parent topic: Database Connectors for ODBC


Driver Requirements

Your ODBC driver must include the following functions:

  • all Core ODBC driver functions
  • the Level 1 function SQLColumns
  • the Level 1 function SQLTables

Depending on the method of record locking you choose, your driver may also need to support some of the following function calls. See A_ODBC_LOCK_METHOD for more information.

  • SQLSetStmtOption
  • SQLSetScrollOptions
  • SQLExtendedFetch
  • SQLSetPos

To test the capabilities of your ODBC driver, we have included a driver test program on your Acu4GL for ODBC installation disks. You can also consult your driver documentation to ensure that it meets these requirements.

Parent topic: Database Connectors for ODBC


Data Type Mapping

Overview of ODBC data types

ODBC defines certain generic data types, which every data source driver maps to its own internal types. Each driver needs to be queried about which types it supports, because different drivers support different types.

The types that Database Connectors for ODBC uses, if they exist in the driver, are:

  • SQL_CHAR
  • SQL_VARCHAR
  • SQL_DECIMAL
  • SQL_NUMERIC
  • SQL_SMALLINT
  • SQL_INTEGER
  • SQL_REAL
  • SQL_FLOAT
  • SQL_DOUBLE
  • SQL_TINYINT
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_VARBINARY
  • SQL_LONGVARBINARY
  • SQL_DATE
  • SQL_TIMESTAMP

For example, Informix maps these types like this:

SQL_CHAR | CHAR
SQL_VARCHAR | VARCHAR
SQL_DECIMAL | DECIMAL or MONEY
SQL_NUMERIC | no such type
SQL_SMALLINT | SMALLINT
SQL_INTEGER | INTEGER or SERIAL
SQL_REAL | REAL
SQL_FLOAT | no such type
SQL_DOUBLE | FLOAT
SQL_TINYINT | no such type
SQL_BIGINT | no such type
SQL_BINARY | no such type
SQL_VARBINARY | no such type
SQL_LONGVARBINARY | BYTE
SQL_DATE | DATE
SQL_TIMESTAMP | DATETIME YEAR TO FRACTION(5)

Informix also defines a type that ODBC calls SQL_LONGVARCHAR, and Informix calls TEXT, which the Database Connectors for ODBC product doesn’t use.

Notice that Informix has two types that match the ODBC SQL_DECIMAL type, and two that match the SQL_INTEGER type. The Database Connectors product will usually use the first type that it finds that matches an ODBC type, unless there are restrictions on that type. For example, the SERIAL type is limited in that a table can have only one such column, while a typical table may have more than one column of integer data.

So the Database Connectors for ODBC product will use the Informix INTEGER type, instead of the SERIAL type for integer data.

For another example, MS Access maps these types like this:

SQL_CHAR | CHAR
SQL_VARCHAR | TEXT
SQL_DECIMAL | no such type
SQL_NUMERIC | CURRENCY
SQL_SMALLINT | SHORT
SQL_INTEGER | LONG or COUNTER
SQL_REAL | SINGLE
SQL_FLOAT | no such type
SQL_DOUBLE | DOUBLE
SQL_TINYINT | BYTE
SQL_BIGINT | no such type
SQL_BINARY | BINARY
SQL_VARBINARY | VARBINARY
SQL_LONGVARBINARY | LONGBINARY
SQL_DATE | no such type
SQL_TIMESTAMP | DATETIME

Access also defines types, SQL_BIT = BIT and SQL_LONGVARCHAR = LONGTEXT which the Database Connectors for ODBC product doesn’t use.

Mapping COBOL data types to ODBC data types

When the Database Connectors for ODBC product creates a table, it uses what it determines to be the best match of a data type for any particular column.

This means that the database column will be able to hold any data that the COBOL data type can hold, and is as close as possible to the type of data that the COBOL program is using. This determination is based in part on what data types the data source has available. Obviously, if a data source doesn’t support some data type, the Database Connectors for ODBC product can’t use it with that data source. The actual algorithm used is rather complicated, but the general rules are as follows:

  • User preferences take precedence. This means that the XFD directives specified are checked first. Therefore, when data should be of type DATE or BINARY, a DATE or BINARY type is located and used, if the data source supports it.
  • If the COBOL data type is usage float or usage double, a data source type of FLOAT, REAL, or DOUBLE is used, depending on what is available. If none of these is available, the Database Connectors product abides by the next rule.
  • If the COBOL data type is numeric, a numeric type is used in the data source. The numeric type chosen depends on how large the COBOL data type is, and how many digits to the right of the decimal point (if any) there are.
    • For example, if the COBOL data type is PIC 99, the data source types checked for are TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, NUMERIC, CHAR. The first of these that exists is the type that will be used for that column.
    • For another example, if the COBOL data type is PIC 9(6)v99, the data source types checked for are DECIMAL, NUMERIC, DOUBLE, FLOAT, REAL, CHAR. Again, the first of these types that exists is the type that will be used for that column.
    • Anything else will use CHAR.

Occasionally, you may encounter a data source type that supports only type CHAR (which is the only data type that is guaranteed to exist, according to the ODBC specification). Under these data sources, all the COBOL data types will be mapped to CHAR types.

Mapping ODBC data types to COBOL data types

Sometimes developers are in a situation where they need to create a COBOL File Description based on an existing data source table. The most important thing to understand in this situation is that there is almost nothing that you can do wrong! When the Database Connectors product opens a data source table, the only thing it checks is that the column names match the COBOL data names.

When the Database Connectors product reads data from the data source, it essentially does a COBOL-style MOVE from the native data type to the COBOL data type, whatever it is. And since most types have a CHAR representation (in other words, you can actually display most data types, using a standard ODBC-capable tool), using PIC X(nn) for each column will work perfectly well.

A better general rule is to use a COBOL type that closely matches the data source data type, but don’t worry about getting an exact fit. So you can use PIC 9(9) whenever the data source has an INTEGER type.

If you have more information about the data source type, you might be able to use a different COBOL representation. For example, if you know that a particular column in an ODBC data source has values only in the range 0 – 999, you could use PIC 999 for your COBOL data. The COMP-type you use is really determined by your own preferences, and should have little bearing on the COBOL data type you choose.

If you want to somehow choose your COBOL data types so that there is a best fit, you can use the following mapping:

SQL_CHAR | PIC X(nn) nn =size of item
SQL_VARCHAR | PIC X(nn) nn = maximum size of item
SQL_DECIMAL | PIC 9(n)v9(m)
SQL_NUMERIC | PIC 9(n)v9(m)
SQL_SMALLINT | PIC 9(5) COMP-5
SQL_INTEGER | PIC 9(9) COMP-5
SQL_REAL | USAGE FLOAT
SQL_FLOAT | USAGE FLOAT
SQL_DOUBLE | USAGE DOUBLE
SQL_TINYINT | PIC 9(3) COMP-5
SQL_BIGINT | PIC 9(9) COMP-5
SQL_BINARY | PIC X(nn)
SQL_VARBINARY | PIC X(nn)
SQL_LONGVARBINARY | PIC X(nn)
SQL_DATE | PIC 9(6) or PIC 9(8)
SQL_TIMESTAMP | USAGE DISPLAY
Note:

The BINARY data types are usually of a form that COBOL can’t understand anyway. You will usually just read these columns, and rewrite them unchanged. If you have more information about the data in the columns, you might be able to do something else, but this requires more knowledge about the columns.

The DECIMAL, NUMERIC, DATE, and TIMESTAMP types usually have special representations in a data source, which really doesn’t match any COBOL data type exactly. When the Database Connectors product binds the data (a technical term), it asks the data source to return it in character form, so the most efficient COBOL data type would probably be USAGE DISPLAY.

Parent topic: Database Connectors for ODBC


Run-time System Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic lists the Database Connectors for ODBC error messages that could occur during execution of your program. For information on compile-time errors and several methods for retrieving run time system errors, see the chapter Performance and Troubleshooting.

Run-time system errors have this format:

9/xxx

The 9 indicates a file system error and is reported as the first digit of the 2-byte FILE STATUS variable. The xxx is a binary value between 1 and 255 that provides more information. If xxx is 83, you can retrieve additional information with C$RERR . That additional information can come from either the database or the run time. Run-time codes returned with C$RERR include:

Code | Message
1 | Error reading the XFD file
2 | Corrupt XFD/dictionary file
3 | Error opening the XFD file
4 | Too many key fields (16 max)
6 | Mismatched dictionary file
11 | ODBC connection missing required functionality
12 | ODBC library function returned an unexpected error
13 | Illegal size or type of data for variable xxx
14 | More than one table with the same name
15 | ODBC driver missing needed types

For a detailed description of a particular message, see the Database Connectors Error Messages section.

Parent topic: Database Connectors for ODBC
Related reference
Database Connectors Error Messages


Common Questions and Answers

This topic contains some questions and answers specific to Database Connectors for ODBC.

Question

Can I open tables in different databases and share the data?

Answer

Yes. But you must set up the data sources one at a time. For example, you could first set your data source to be Oracle and open Oracle tables, and then you could change the data source to Access and open Access tables.

Remember, you can set up data sources dynamically at run time by adding a line like this before the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "data source name"

Question

I keep receiving an error message saying that my login is invalid. But I’m sure I’m using the correct username and password.

Answer

All usernames, passwords, and database names are case-sensitive. Be sure that you are typing the names exactly as they are set up.

Question

I’m using Microsoft Access version 2.0, and I’m having trouble accessing/writing tables from my COBOL program.

Answer

Check the version of the Access driver you are using. Microsoft Access version 2.0 requires version 2.0 of the driver. If you are using a previous version of the driver, the runtime will generate errors. To determine the version number of your driver, you can run the Database Connectors for ODBC driver test program DRVTST32.EXE (32-bit version).

Question

I’m noticing some performance degradation when accessing my ODBC data source. What is the cause of this?

Answer

You may notice some performance impact if you were previously accessing Vision indexed files directly. This is because ODBC adds a software layer between your applications and your data sources. In return for minor performance impact, you can reap the benefits of database independence and enhanced portability. Overall performance depends on several factors, including your network configuration and your specific data source.

Question

I wrote data with my Database Connectors for Oracle (or Informix) product. When I try to read it with Database Connectors for ODBC, the data is not the same.

Answer

By necessity, the BINARY data type is implemented differently in Database Connectors for ODBC than it is in Database Connectors for Oracle or Informix. For this reason, writing data with one Database Connectors product and then reading it with another will probably produce different results. Future releases of Database Connectors for Oracle and Informix will address this problem.

Question

When I create a table, I get an error saying I have placed too many BLOBs (binary large objects) in my table.

Answer

Some databases have restrictions about the number of BLOBS that can be placed into a single table. To work around this restriction, you can specify the configuration variable A_ODBC_USE_CHAR_FOR_BINARY. This allows you to encode binary data in hexadecimal and write it out as CHAR data instead of BINARY. See A_ODBC_USE_CHAR_FOR_BINARY for more information on this variable.

Question

Are there any library routines that do not work with or would not make sense to use with Database Connectors for ODBC?

Answer

Yes. The C$COPY and C$RENAME library routines do not work with Database Connectors for ODBC.

Parent topic: Database Connectors for ODBC


Database Connectors for Oracle

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This appendix provides information that is specific to Database Connectors for Oracle.
  • Oracle Concepts Overview
  • Client Configuration
  • Filename Translation
  • ACUFH Configuration File Variables for Oracle
  • Using the Database Table
  • Unsupported Features
  • Limits and Ranges
  • Data Type Mapping
  • Run-Time System Errors
  • Common Questions and Answers
Parent topic: Database Connectors User's Guide


Oracle Concepts Overview

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors for Oracle is based on the Oracle Call Interface (OCI), an API that makes the code more portable to the maximum number of platforms.

This quick overview of some basic design concepts underlying the Oracle Database Management System relational database system (RDBMS) help to interface your COBOL program to it.

  • Transactions
  • Record Locking Issues in Transactions
  • Database Connectors and Record Locking
  • The open_cursors Parameter
  • Table Ownership
  • Security
Parent topic: Database Connectors for Oracle


Transactions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The Oracle RDBMS is a transaction-based system. All of the work that you perform while using Oracle must occur within a transaction, whether that work is being done through Database Connectors for Oracle or another 4GL application. When you use the Database Connectors, a transaction is implicitly started for you by the database engine itself with the first file I/O operation performed on a file associated with Oracle. Because all operations with Database Connectors occur within a transaction, any record locked during processing remains locked until either a COMMIT WORK or ROLLBACK WORK is issued by Database Connectors. This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL.

The benefits of this transaction management system are best illustrated by an example. A COBOL application that handles order entry might perform these steps to accept an order:

  • Write an invoice record.
  • Update a customer record.
  • Write a payroll record for sales commissions.
  • Update an inventory record.

This series of four file operations is a logical unit. If the program were interrupted and had completed only some of the four file operations, the files would be in an inconsistent state. For example, if the program terminated unexpectedly after it updated the customer record, but before it updated the inventory record, a subsequent run might access non-existent inventory.

The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur. Then, if the program encounters an error or terminates, the files are left in a consistent state.

All file operations that are part of a transaction are logged. Once logged, they can be either committed or rolled back (undone) by the program.

If a program dies or the system fails, the log file can be used to reconstruct complete transactions, returning all files to a consistent state. Transaction logging thus offers these two facilities:

  • It provides the programmer with the ability to define transactions and the ability to commit them or undo them (usually in response to an error condition); this undo facility is called a rollback
  • It provides the ability to reconstruct files into a consistent state after a program dies or system failure occurs; this operation is called recovery
Parent topic: Oracle Concepts Overview


Record Locking Issues in Transactions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Applications that perform work in small operation-based logical units, benefit greatly from Oracle's transaction management systems. Other applications may encounter difficulty with record locking when operating against a system (Oracle) that enforces transaction management.

The difficulty can occur with an application that is performing more than one logical task at a time. Any operation that modifies or reads data in an I/O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system. As a result, the application may have many more record locks present than would be expected by the normal rule of COBOL file locking. The application would act similarly to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used. This can best be illustrated by an example:

  1. The user is entering a customer's order.
  2. As each line item is entered into the order, the inventory file is modified to reflect that items have been removed from the stock on hand.
  3. The user must switch to a different part of the application to perform a different task, perhaps as a result of a phone call from a new customer.
  4. All of the records that were locked, or modified, by the application before the switch remain locked because the first order is not complete. As no COMMIT or ROLLBACK has been issued, all of the records remain locked until the application ends, thus ending the transaction.
  5. Because one order is open and not yet committed, other applications may be locked out of certain order items if they are still locked by the processing of the first order. The second order entry may be held up until the first order is completed.

Note that the first application is not locked out. A process can read its own locked records.

Parent topic: Oracle Concepts Overview


Database Connectors and Record Locking

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors provides semi-automated ways to handle transaction logging based on the setting of the COMMIT_COUNT environment variable. You can also directly alter your source code to deal with this issue. Individual users determine how much work they wish to do to conform to the Oracle transaction management system by choosing the method that best fits their needs and resources. The following methods are listed in order of increasing amount of work:

COMMIT_COUNT = 0 (Default)

When you set this variable to zero (0), the run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement.

COMMIT_COUNT =n

When you set this variable to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released.

COMMIT_COUNT = –1

No commit is issued by the Connector. When COMMIT_COUNT is set to 1, two alternate ways to perform a commit or rollback are available:

  • Call your Oracle query tool with COMMIT WORK or ROLLBACK WORK.

A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

Parent topic: Oracle Concepts Overview
Related information
COMMIT_COUNT configuration variable


The open_cursors Parameter

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The Oracle system parameter open_cursors should be set to enhance communication with the Connector. For more information, see Checking System Parameters.

Parent topic: Oracle Concepts Overview
Related information
Checking System Parameters


Table Ownership

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Table names in Oracle have the form owner.table_name. If you are the owner of a given table, you can refer to it as just table_name. If you are not the owner, you must refer to it with the owner of the table as a prefix. Database Connectors provides a user-configurable method (the USER_PATH ACUFH configuration file) for implementing this.

Parent topic: Oracle Concepts Overview
Related information
USER_PATH configuration variable


Security

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Security is implemented in the Oracle RDBMS. A user is required to log in to the RDBMS before any file processing can occur. The Connector provides both a default and a user-configurable method for implementing this. Oracle's security considerations pose several challenges for COBOL programmers. Because of the various levels of permissions, certain operations are not allowed unless you have database administrator (DBA) privileges. These restricted operations include:

  • Creating a table under another user's name
  • Dropping a table owned by another user

Oracle versions 9i and later also provide additional security levels; however, you must consult the Oracle documentation to determine if any of these permission levels are appropriate for your site.

Generally, it is best for someone with DBA privileges to create and drop the tables, allowing others only the permissions to process information contained in them. A table can be referenced either by owner.table_name or by a public synonym that you have created for the table. See the Oracle documentation for more details on DBA privileges and public synonyms.

Note: By default, Database Connectors always checks to see if a public synonym is available for a file at open time, regardless of what USER_PATH is set to. If the name of a table owned by a current user is the same as a public synonym, the user-owned table is chosen.
Parent topic: Oracle Concepts Overview
Related information
USER_PATH configuration variable


Client Configuration

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following section covers the client configuration required before using Database Connectors for Oracle on a new system.

Before you begin, you need to have:

  • Access to an already installed and configured Oracle database.
  • Configured any client software (if the server is on a remote machine), and verify a successful connection to the intended database.

The Oracle RDBMS must be installed and configured prior to this, which also includes the setting of any environment variables that may be required (such as ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH) - consult your Oracle documentation for details on this.

Typically, you'll install Oracle client software to connect to a database not on the current machine, and then set up a service name that references the database that you want to connect to. The easiest way to do that is to use Oracle's Net Configuration Assistant. This tool also allows you to test the connection to the database. Some other versions of Oracle may require you to set specific environment variables (such as ORACLE_HOME, and ORACLE_SID); again, consult your Oracle documentation for further details.

Client installation can also be achieved using Instant Client - a lightweight solution to the Oracle client install. If using this client, we recommend downloading the following components to help test your connection:

  • Oracle's SQL*Plus interactive query tool. SQL*Plus allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.
  • Oracle's SCOTT/Tiger test schema. This is a schema that is installed by default on older Oracle versions. It can still be downloaded and installed separately, and is used for testing purposes.
Note: Micro Focus does not provide these downloads.

Once you have successfully connected to your Oracle database, continue with the Database Connectors-specific configuration.

  • Oracle's Instant Client
  • Checking System Parameters
  • Setting Up a User Account
  • Setting Up the User Environment
  • Configuring the File Handler for Oracle
  • Setting Up the Search Path
  • Handling Transactions
Parent topic: Database Connectors for Oracle
Related reference
To Set Up a Service Name for an Oracle Database


Oracle's Instant Client

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Instant Client is a free-to-download, lightweight Oracle database client designed to allow you to run your applications without installing the standard Oracle client or having an ORACLE_HOME. You can use it in place of the standard Oracle client when using Database Connectors for Oracle.

Setting up Oracle Instant Client can be challenging and should be performed by advanced users only. You will need the Basic Lite and SQL*Plus packages, available from the Oracle web site. Follow Oracle's instructions to install and configure the products.

If you also installed the SCOTT/Tiger test schema, you can test the connection to the Oracle database using SQL*Plus before proceeding with the Database Connectors client install.

Parent topic: Client Configuration
Related information
To test the installation of Oracle's Instant Client


Checking System Parameters

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Database Connectors makes use of cursor caching to process Oracle RDBMS data efficiently. A cursor is a prepared query, saved in a parameterized format. When a like function is to be performed on a different record (such as a GET NEXT), the task can be performed by executing the saved query with new parameters. This improves performance by eliminating the need to regenerate the query. You may need to adjust the number of cursors available to your COBOL application.

Parent topic: Client Configuration
Related information
To set the system parameters


Setting Up a User Account

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

For Database Connectors for Oracle to be able to communicate with the Oracle database, you must specify a valid user login that has the required read and write access to the database. For this, you can set up either one general account for all Database Connectors users or an account for each individual user. To set up an account, you must have database administrator (DBA) privileges.

Note: You may opt to use Oracle's Enterprise Manager on Windows platforms to simplify the login process. If you decide to use the Enterprise Manager, please refer to your Enterprise Manager documentation instead.
Parent topic: Client Configuration
Related reference
To Configure a Login


Setting Up the User Environment

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

To configure the client environment for Database Connectors, you usually use an ACUFH configuration file.

The minimum settings required would be the ORA_LOGIN, ORA_PASSWD, and A_ORA_DATABASE variables; refer to ACUFH Configuration File Variables for additional variables you can include. If you are accessing files that you do not personally own and that do not have public synonyms, you may also need to set USER_PATH.

You use the A_CONFIG environment variable to identify the ACUFH configuration file, which allows you to create your own personalized copy of the file, to avoid impacting other users.

If you are concerned about including passwords in a configuration file, you can set these details in your COBOL program or environment. The following syntax is an example of how you can set a variable within your code:

SET ENVIRONMENT ORA_PASSWD TO user-entry
Parent topic: Client Configuration


Configuring the File Handler for Oracle

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As well as the database-specific information that you specify in an ACUFH configuration file, you also need to inform the File Handler of which database type it is working with when performing file handling operations. You do this by specifying the IDXFORMAT, which can be set using one of the following methods:

  • Set at compile-time, either within your source code or on the command line.
  • Set in a File Handler configuration file, which is queried at run time.

The supported values for the IDXFORMAT option are:

IDXFORMAT No: | RDBMS:
18 | Microsoft SQL Server
19 | Oracle
20 | DB2
22 | ODBC

Set the format at compile-time

Set the option within your source code using the following syntax (replacing nn with the appropriate value from the table above):

      $set IDXFORMAT"nn"
       Identification Division.
       Program-id. Dbc-demo.
       ...
       End program Dbc-demo.

Or specify the IDXFORMAT on the command line, during compilation:

cob Dbc-demo.cbl IDXFORMAT"nn";
Note: Another method is to use the USE directive, specifying a directives file that contains the required IDXFORMAT.

Set the format at run time

Tip: Configuring the File Handler at run time enables you to use the same source code with more than one of the supported RDBMSs without the need to recompile. It also gives you greater control when setting different formats at once.

Set the option within a File Handler configuration file:

[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:/home/data/db2]
IDXFORMAT=20
[FOLDER:/home/data/oracle]
IDXFORMAT=19
Note: You cannot specify the values 18, 19, or 20 in the [XFH-DEFAULT] section of a configuration file. In the example above, IDXFORMAT 8 is used as default, but files placed in /home/data/db2, and /home/data/oracle use IDXFORMATs 20 and 19 respectively.

To use the configuration file at run time, you must specify it in the EXTFH environment variable:

EXTFH=/home/dbc/extfh.cfg
export EXTFH

sets the file name to /home/dbc/extfh.cfg.

Parent topic: Client Configuration


Setting Up the Search Path

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If you own a file because you created it with OPEN OUTPUT from COBOL, or because you created it using SQL, you don't need to do anything more to access the file. However, if you want to access files that are owned by other users on the system and do not have public synonyms, you must provide the run time system with information on how to locate these files.

The USER_PATH ACUFH configuration file variable is used by the run time system to locate files. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user on the system or a period (.), which indicates the files owned by yourself. For example, if you have the following settings:

ORA_LOGIN    =   OPS$ORACLE
ORA_PASSWD   =   DATA_FERIT
USER_PATH   =    barbara scott.

and then attempt to open for I/O the file myfile, the run time system uses the following search path:

OPEN I-O       barbara.myfile
OPEN I-O       scott.myfile
OPEN I-O       ops$oracle.myfile

Remember that another option for allowing access to a file to all users on the system is to create a public synonym for the file.

Parent topic: Client Configuration
Related information
USER_PATH configuration variable


Handling Transactions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When a COMMIT WORK database command is issued, it terminates a transaction and makes all work permanent and accessible to other users. The Database Connectors for Oracle run time system issues this command automatically when no locks are held, but you can cause it to happen under other conditions by setting the value of the COMMIT_COUNT ACUFH configuration file variable.

You are now ready to prepare and compile your COBOL program and run the demonstration program. For additional information, see Examples of Preparing and Compiling a Program and The Demonstration Program.

Parent topic: Client Configuration
Related reference
COMMIT_COUNT configuration variable
Examples of Preparing and Compiling a Program
The Demonstration Program


Filename Translation

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

As you prepare to work with Database Connectors for Oracle, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and eXtended File Descriptor (XFD) files are formed and work together. For detailed information on XFDs, see XFDs.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUFH configuration file variables, the run time system translates the file name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

At this point, Database Connectors translates the file name to uppercase letters and changes hyphens to underscores. This new name is the one that Database Connectors uses for references to the database table.

Parent topic: Database Connectors for Oracle


ACUFH Configuration File Variables for Oracle

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before running Database Connectors, you must set the A_CONFIG environment variable to the name of the ACUFH configuration file. You may want to make and use a personalized copy of the ACUFH configuration file to avoid impacting other users. You could use the A_CONFIG environment variable to identify a personal ACUFH configuration file. For example:

Windows:

SET A_CONFIG=directory-name\my-file-name

UNIX:

A_CONFIG=directory-name/my-file-name
export A_CONFIG

ensures the specified configuration file is used when interfacing with your database.

This section lists the ACUFH configuration file variables that are specific to Oracle. For ACUFH configuration file variables that are generally applicable to any RDBMS with which Database Connectors communicates, see ACUFH Configuration Variables in the Run Time Configuration section.

Variable | Description
A_ORA_DATABASE | Specifies the name of a network service that you have set up to refer to a database
A_ORA_HINTS | Enables the Oracle Hints feature
A_ORA_KEEP_START_CURSOR | Key value is saved for subsequent READ NEXT/PREVIOUS operations
A_ORA_LIMIT_DROPDOWN | Improve performance when the interface generates a sequence of DROP DOWN queries
A_ORA_MAX_FILE_CURSORS | Allows you to set the maximum number of cursors that the run time system is allowed to have per file
A_ORA_NLS_SORT | Forces the sort order of returned records to be in a binary order
A_ORA_WAIT_LOCK | Determines the type of Oracle locks used: wait or nowait
A_ORACLE_ERROR_FILE | Allows you to map errors using a text file to supplement the default method of providing errors
COMMIT_COUNT | Indicates the conditions under which you want to issue an automatic COMMIT_WORK operation
ORA_LOGIN | Indicates the user name under which you want to connect to the database system
ORA_PASSWD | Set to the password assigned to the database account associated with the user name specified by ORA_LOGIN
USER_PATH | Indicates the user name or names to be used when the Connector searches for files
Parent topic: Database Connectors for Oracle
Related information
ACUFH Configuration Variables


Using the Database Table

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The database table is built and accessed automatically when the COBOL application is executed. To the end user, the interaction between the COBOL and the Oracle database is transparent, as though they were part of one process.

You also can access the database information directly from Oracle, at your option.

To create a sample COBOL application, see Examples of Preparing and Compiling a Program.

Parent topic: Database Connectors for Oracle
Related reference
Examples of Preparing and Compiling a Program


Unsupported Features

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

OPEN ALLOWING READERS is not supported by Oracle. Your ACUFH configuration file determines how to interpret this phrase. Set the variable STRENGTHEN_LOCKS to 1 to cause this phrase to be treated as OPEN ALLOWING NO OTHERS. Set the variable to 0 to cause the phrase to be treated as OPEN ALLOWING ALL. The default value is 0.

Transactions are enforced in Oracle. Within a transaction, records locked by I/O operations that modify, delete, or otherwise result in a COBOL record-lock, remain locked until a COMMIT WORK or a ROLLBACK WORK is issued. See COMMIT_COUNT configuration variable for more information.

Oracle does not support record encryption, record compression, or alternate collating sequences. You may include these options in your program; however, they are disregarded if specified.

Whenever you are using the library routine RENAME, you must specify that you are using indexed files. This information is passed by the value I in the fourth parameter.

Unless you have DBA privileges, or special privileges introduced in Oracle Version 9i, you cannot:

  • Delete a table you don't own
  • Create a table under another user's name
Parent topic: Database Connectors for Oracle
Related information
COMMIT_COUNT configuration variable


Limits and Ranges

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following limits exist when working with Oracle:

Maximum indexed key size: | 250 bytes
Maximum number of fields per key: | 16
Maximum number of columns: | 254
Maximum length of a char field: | 255
Note: The limits and ranges differ between releases of Oracle.
Parent topic: Database Connectors for Oracle


Data Type Mapping

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Database Connectors for Oracle supports the following data types.
COBOL | Oracle
PIC X | CHAR
PIC X(n) | CHAR(n)
PIC X(n) | VARCHAR2 (VAR_LENGTH directive is required)
PIC X(n) | RAW(n)
PIC 9(n) | NUMBER(n)
PIC 9(n) | RAW(n)
PIC 9(n)V9(m) | NUMBER(n+m, m)
example: PIC999V99 | NUMBER(5,2)
Oracle | COBOL
CHAR | PIC X
CHAR(n) | PIC X(n)
VARCHAR2 | PIC X(n) (VAR_LENGTH directive is required)
DATE | PIC 9(6) or PIC 9(8)
NUMBER(n) | PIC 9(n)
NUMBER(n, m) | PIC 9(n-m)V9(m)
RAW(n) | PIC X(n) or PIC 9(n) (BINARY directive is required)
example: NUMBER(4,3) | PIC9V999

Internally, Database Connectors for Oracle uses VARCHAR to prevent key fields that are all spaces from being converted to null.

These Oracle data types are not currently supported:

  • LONG
  • LONG RAW
Parent topic: Database Connectors for Oracle
Related reference
VAR LENGTH XFD directive
BINARY XFD directive


Run-Time System Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This topic lists the Database Connectors for Oracle error messages that could occur during execution of your program. For information on compile-time errors and several methods for retrieving run time system errors, see the chapter Performance and Troubleshooting.

Run-time system errors have this format:

9/xxx

The 9 indicates a file system error and is reported as the first digit of the 2-byte FILE STATUS variable. The xxx is a binary value between 1 and 255 that provides more information. If xxx is 83, you can retrieve additional information with C$RERR. That additional information can come from either the database or the run time. Run-time codes returned with C$RERR include:

Code | Message
0 | Duplicate key
1 | Error reading the XFD file
2 | Corrupt XFD/dictionary file
3 | Error opening the XFD file
4 | Too many key fields (16 max)
5 | Too many key fields (16 max for Oracle)
1001 | Invalid Cursor

For a detailed description of a particular message, see the Error Messages section.

Parent topic: Database Connectors for Oracle
Related reference
Troubleshooting
Error Messages


Common Questions and Answers

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
On HP-UX platforms, which type of COBOL run time system - non-threaded or multi-threaded - should I use when connecting to the database?
You need to use the multi-threaded RTS, because Oracle is multi-threaded. If you use the non-threaded RTS, you will get a database connection error, because HP-UX does not allow the mixing of multi-threaded and non-threaded code.
On other UNIX/Linux platforms, you can use either run time system.
When I try to open a file for output, I get the error 9/83, with a secondary error of 904 Invalid Column Name. Why?
One of your record's data items probably has the same name as an Oracle reserved word. Locate the column by comparing a file trace of the CREATE TABLE to Oracle's list of reserved words and then apply the NAME XFD directive to the column in question.
I created a table the last time I ran the application, and now I can't find it. Why?
This is probably a file (table) ownership problem. If you were running the application under a different user name when you created the file, that table may not be visible unless the creating user's name is listed in your USER_PATH ACUFH configuration file variable.
Can Database Connectors support a full datetime format?
The finest time granularity that Oracle supports is one second. Fractions of a second are not supported. In order to achieve this, you must be sure the xfd date code is correct and specify a date-time string in your COBOL application, as opposed to just a date. For additional information, see the reference topic Date XFD directive.
Parent topic: Database Connectors for Oracle


Performance and Troubleshooting

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

These topics provide guidelines for improving system performance. Also included is an alphabetical listing of the error messages that can occur during the compilation of your program.

  • Performance Issues
  • Troubleshooting
Parent topic: Database Connectors User's Guide


Performance Issues

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Adding a relational database management system (RDBMS) brings significant complexity to any computer system. A few key guidelines may help to improve the performance of the system and prevent problems as the database grows.

  • Guidelines
  • The WHERE Constraint
Parent topic: Performance and Troubleshooting


Guidelines

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following sections describe some areas for you to consider as you prepare your database and your COBOL program.

  • Guideline 1 - Database Administrator
    A site with a database management system needs a database administrator (DBA).
  • Guideline 2 - Understand COBOL Operations and Database Operations
    Some COBOL operations are particularly stressful to a database. The more the application uses these operations, the more likely performance of the RDBMS suffers.
  • Guideline 3 - Program and Database Interaction
    A database can interact with your COBOL program in surprising ways. When you introduce a database to a mature COBOL application, your application may experience errors you have not seen before. Being aware of this possibility helps you to prepare your response.
  • Guideline 4 - Plan for Growth
    Planning ahead for growth is essential. You need to be able to predict the system resources that your application requires reaching a full load, both in terms of users and database size.
Parent topic: Performance Issues


Guideline 1 - Database Administrator

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
A site with a database management system needs a database administrator (DBA).

The administrator is critical in any large database installation. The DBA checks performance statistics and memory usage, performs general maintenance and backup for the database, initiates traces, executes database utilities, sets buffer sizes, determines how often buffers are flushing, and, in general, understands how database settings and events affect overall performance.

The DBA also performs periodic tuning of the database, including:

  • Using monitoring tools
  • Allocating table spaces
  • Examining output of the query optimizer to ensure that the most efficient paths are being used
  • Updating table statistics
  • Creating indexes

If a site experiences a performance problem, this usually means there is a bottleneck somewhere in the system. The DBA can help to isolate the bottleneck. Once the bottleneck is identified, the site can determine whether to apply more resources or correct the situation that is stressing the existing resources.

Parent topic: Guidelines


Guideline 2 - Understand COBOL Operations and Database Operations

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Some COBOL operations are particularly stressful to a database. The more the application uses these operations, the more likely performance of the RDBMS suffers.

The more you understand about your RDBMS and how it operates, the more you can help your COBOL applications to work efficiently with it.

File Input and Output

Consider these standard COBOL I/O operations:

  • READ
  • REWRITE
  • WRITE
  • DELETE
  • OPEN

Each has an associated cost in terms of database performance. Each asks the database to do something that takes time. So if there are I/O operations that are optional in your COBOL application, you may want to remove them.

For example, developers sometimes OPEN and CLOSE files unnecessarily, using the OPEN–CLOSE pairing as a way to demarcate each new procedure:

OPEN file-A
procedural code
CLOSE file-A

But it's important to know that file OPENs are expensive in terms of performance. If you can eliminate non-essential OPENs from portions of your application, you may improve performance.

READ operations can also affect performance. All COBOL I/O is based on key indexes. Examining the output of your query optimizer allows you to determine if the most efficient execution path is being used for READs. The execution path for a given query can change as your data changes and as the size of the tables changes. It is also affected by database initialization parameters and any statistical information that you may have gathered on your tables. It might be helpful to know that, typically, the index path is the most efficient for Database Connectors applications.

Tables with Multiple Indexes

If using tables with multiple indexes, keep in mind that when a record is written or updated, locks are put onto all of the indexes and they are all basically rewritten during the course of the write/update. This is a costly process. There may be multiple columns per index, and multiple indexes per table. Each rewrite implies a certain amount of wait time. Tables with a large number of indexes can be slow on writes/updates, possibly leading other operations in the database query optimizer to become confused.

There are two things you can do in this circumstance:

  • Restructure your data. The benefits of data restructuring may be significant. For example, if you have any situations in which two indexes start out with the same column or set of columns, you may be able to improve performance appreciably by changing your data definition.

    Suppose two indexes both start with MONTH, DAY, YEAR. These identical first three columns can cause the RDBMS's query optimizer to choose the wrong index, in which case you generate a significant amount of unnecessary and unproductive overhead. Restructuring one of the indexes can make a difference.

  • Use the file system for some of your data. If you cannot restructure your data but are finding certain operations to be too expensive, you might want to consider moving some data into the indexed file system.
Guiding the Data Searches
You can guide the data searches that result from database queries, and thus improve performance, by making use of an external variable called A4GL_WHERE_CONSTRAINT. This process is explained in The WHERE Constraint.
Parent topic: Guidelines


Guideline 3 - Program and Database Interaction

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
A database can interact with your COBOL program in surprising ways. When you introduce a database to a mature COBOL application, your application may experience errors you have not seen before. Being aware of this possibility helps you to prepare your response.

For example, your existing application without the database may rarely exceed the limit on the number of data files that can be open simultaneously. But when you add a database, you increase the likelihood of this significantly. This is because the query processing may often require temporary tables. Also, the ORDER BY clause (used in SQL statements to sequence retrieved data) opens temporary work files. So you may find that these files cause you to reach the limit sooner. (Note that proper tuning of the query optimizer can reduce the number of temporary files required.)

When upgrading to a new version of the RDBMS, new software components may interact with your applications differently than their predecessors did. It's important to rerun your pre-installation simulations (see Guideline 4 — Plan for Growth) to determine whether your system resources are still adequate. Investigate any differences in the two simulations. You may have to make adjustments to compensate for the differences in the RDBMS versions.

Upgrading or switching to a new database may also mean that you need to modify your makefile to coordinate with the settings of the new database. You can edit your makefile manually, or use one of the editing tools distributed with Database Connectors. For more information, see the Appendix specific to the Connector interface you are using.

If you notice a change in performance with a new release of your RDBMS, keep in mind that certain database settings can have a significant effect on speed. Fine-tuning your settings can make a difference.

Several other options to help you improve performance are listed below:

  • Try one of the many third-party monitoring tools available
  • Break up data onto several connected hard drives to free up space and resources
  • Limit the number of indexes you have assigned with each database table
Parent topic: Guidelines


Guideline 4 - Plan for Growth

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Planning ahead for growth is essential. You need to be able to predict the system resources that your application requires reaching a full load, both in terms of users and database size.

Before you choose and install hardware, it is best to run a simulation. Your hardware vendor or RDBMS vendor can help you to simulate a large number of users on a given platform with a given RDBMS.

Setting up and running a simulation that includes your own application lets you anticipate when moving into any installation, and can help to mitigate costly consequences.

A potentially costly mistake is to test in your office with a small database and a small number of users. Databases respond differently to small amounts of data and a small number of users than they do to large amounts of data and a large number of users. Functionally, the database works differently as the load increases. You might think of this adjustment as switching into a different gear. Significant changes in the load on your database can lead to large increases in overhead. The behaviors and loads encountered as the database expands cannot be determined from a linear projection based on the smaller scenario.

Parent topic: Guidelines


The WHERE Constraint

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The Database Connectors WHERE constraint is an external variable that gives the developer some control over the data searches that result from database queries. It can help to improve performance in some situations. This topic describes purpose of the WHERE constraint and shows how it is implemented.

COBOL data processing is based on keyed READ operations following a positioning operation. Records are read until the key value being processed changes. Because traditional COBOL data processing is based on a B+ tree file system, the overhead for such operations is relatively minor.

RDBMS data processing introduces a new level of complexity to data processing. The database's query optimizer receives the SQL query for the COBOL operation being performed and then builds a working set of data that satisfies that query. Because the database optimizer has many different possible execution methods, this can result in poor performance if the optimizer chooses a query execution path that is less than optimal.

Performance degradation may also result from the fact that queries generated by COBOL operations result in unbounded index queries. Unbounded queries are generated because COBOL positioning operations (Start Not Less Than and Start Not Greater Than) provide only one of the bounding conditions for the working set, instead of both an upper and lower boundary.

As an example, consider the case in which an application needs to process all items in a warehouse on aisle 17, shelf 8, and bin 2. If each of these items is a field in a key, the COBOL program might generate the following query for a READ operation:

Note: The following example applies to the Database Connectors for Oracle product. The SQL generated differs based on the interface.
SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf = 8 and
   bin = 2
ORDER BY aisle ASC, shelf ASC, bin ASC;

This query achieves the desired result but has one problem. For the COBOL program to end its processing, it must read a record that has a new value for bin. The COBOL application has no way of specifying an upper boundary for the read operation, so when all rows of data from bin 2 have been read, the Connector attempts to read the next record by generating the following query:

SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf = 8 and
   bin > 2
ORDER BY aisle ASC, shelf ASC, bin ASC;

This query causes the database query optimizer to gather all records pertaining to items on the remainder of shelf 8 to build its working set. This is excessive from the COBOL application's point of view, because the COBOL program needs only the first record of the working set to determine that it has finished processing.

This problem can be even more serious if the application is processing the last bin on a shelf. Because there are no more bins on that shelf, the query would drop down a level and generate the following:

SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf > 8
ORDER BY aisle ASC, shelf ASC, bin ASC;

This would select all items on the remainder of that aisle of the warehouse, which could be a very large working set if each aisle had 130 shelves.

The database query optimizer normally does not build the entire working set if it has been properly tuned, but instead performs INDEXED READS to process the query. This means that the query optimizer traverses an index tree to retrieve the records, much as COBOL index files do, as opposed to using combinations of indexes and sort and merge operations.

It can be helpful to influence precisely which information is to be returned. If the precise scope of the record processing performed by the read operations is known at compile time (or before the query is executed), information retrieval can be more finely tuned.

Database Connectors provides a method by which the COBOL programmer can provide additional information to the database query optimizer by providing more specific selection information to the Connector. This selection information is added to the WHERE clause of the SQL queries generated by the Connector. This can be particularly useful in providing upper boundaries to queries being generated, with the result that the working set is smaller.

Upper boundaries can be provided on the key segments for a select, or any other selection criteria needed to constrain the working set to just the desired subset of rows. This additional information is added to generated queries with the AND condition. It is not possible for the application developer to specify a larger working set than would otherwise have resulted. The developer may only constrain the working set to a smaller subset.

Parent topic: Performance Issues
Related information
To use the WHERE constraint from COBOL


Troubleshooting

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following topics list the possible error messages that can occur during compilation or run time.

Note: You may experience slower performance simply because the Database Connectors application is limited by of the rules of COBOL. There are many third-party tools available to help monitor performance levels.
  • Setting External Variables
  • Compiler Errors
  • Run-Time System Errors
Parent topic: Performance and Troubleshooting


Setting External Variables

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When using Database Connectors, file status variables and declarations may not be able to provide enough information to determine the cause of the error and the recommended resolution.

Setting external variables can provide additional information in troubleshooting situations. For example, if the database returns an error that does not map to one of the standard COBOL errors (record locked, duplicate key, etc.), the external variables F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO and F-ERRMSG contain additional information. Typically, F-ERRNO is E_INTERNAL (which has a value of 15). F-INT-ERRNO and F-INT2-ERRNO are the error values returned by the database, and F-ERRMSG points to a text message returned by the database.

Add the following EXTERNAL declarations to working-storage:

01  F-INT-ERRNO   BINARY-LONG  SIGNED 	EXTERNAL.
01  F-INT2-ERRNO  BINARY-LONG  SIGNED	 EXTERNAL.
01  F-ERRMSG      POINTER             	EXTERNAL.
77  F-ERRNO       BINARY-SHORT SIGNED 	EXTERNAL.
Note: Not all errors return textual messages.
Parent topic: Troubleshooting


Compiler Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Compilation errors can occur when you compile with the CREATEXFD directive. In some cases, the XFD file cannot be built until you remove the error condition. (XFD errors do not, however, prevent the object code from being generated.) For information about XFDs, see the XFDs section.

For detailed information about a particular error message, see the Compiler Errors section.

Parent topic: Troubleshooting
Related reference
Compiler Errors


Run-Time System Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

You can determine the meanings of your database error codes by referring to the database documentation.

You can see run-time system errors by using the FILE_TRACE ACUFH configuration variable with the Consolidated Tracing Facility (CTF).

Unless noted otherwise, this method applies to all RDBMSs supported by the Database Connectors family of interfaces. For a listing of run-time system errors, refer to the Run-Time System Errors topic of the section specific to your RDBMS.

  • Using the FILE_TRACE ACUFH Configuration Variable
Parent topic: Troubleshooting
Related reference
FILE TRACE configuration variable
Run-time System Errors for MSSQL
Run-time System Errors for DB2
Run-time System Errors for Oracle


Using the FILE_TRACE ACUFH Configuration Variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

At run time, if you specify a CTF trace file and set the FILE_TRACE ACUFH configuration variable, the run time system puts the extended error code and some text associated with the error into the error file.

The text of the error would then have this format in the file:

*** File system error value = 3 ***
*** Dictionary (.xfd) file not found***
File error 9S,03 on filename
Dictionary (.xfd) file not found

Occasionally you may receive an error message that means syntax error. You can examine the CTF trace file and determine the cause of the problem if you receive this error code.

Parent topic: Run-Time System Errors
Related reference
To enable tracing for Database Connectors


Questions and Answers

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following are some answers to common questions that can apply to any relational database management system (RDBMS) data source supported by the Database Connectors family of interfaces.

I can't seem to get ACUFH configuration file to create the files in my database. They keep coming up as indexed files.
Check to see that you have the correct IDXFORMAT in effect. Specify it in the source code, on the command line or in the project properties during compilation, or at run time in an EXTFH configuration file.
Can I use both an RDBMS and the Micro Focus EXTFH file system at the same time?
Yes, you can. In fact, you can configure both from the same EXTFH configuration file. For example, the following excerpt shows that any files within the two specified folders are configured to use their respective formats, and any other files are configured to use IDXFORMAT 8:
[XFH-DEFAULT]
IDXFORMAT=8
[FOLDER:C:\\files\\db2]
IDXFORMAT=20
[FOLDER:C:\\files\\oracle]
IDXFORMAT=19

See Configuring the File Handler for more information.

How can I find out what an error message is?
If you run your application with the FILE_TRACE ACUFH configuration file variable, you receive extended error numbers that include those returned by your RDBMS application.
Note: For Oracle, if you are using the OERR command-line utility, the error code must include five digits. If your error code does not already include five digits, you must add leading zeros to complete this requirement. For example, if your error code is code number 150, the syntax for this option is OERR ORA 00150.

If you have sent the errors to an output file with the FILE_TRACE ACUFH configuration variable, the run time system also attempts to include text that explains the errors. See the example in the section Runtime System Errors in the chapter Performance and Troubleshooting.

Do my eXtended File Descriptor (XFD) files have to be in the same directory as my object files?
No. You can instruct the compiler to put the XFD files in an alternate directory with the CREATEXFD directive. Then at run time, make sure you have the ACUFH configuration file variable XFD_PREFIX set to include that same directory.
Why aren't my KEYs being retrieved in the correct order?
If your KEY field is numeric or alphanumeric, you may have illegal data in the field. For example, if you've used LOW-VALUES or HIGH-VALUES to mark control records, those values are considered invalid and can cause the records containing them to be retrieved in an unexpected sequence.

To enable special values such as these to be processed, use the BINARY XFD directive in front of the key field. This allows data of any classification to be processed. Either designate an individual field as binary, or specify USE GROUP, BINARY in front of a group of fields.

The method of storing variables declared as binary is database-specific. For example, for Oracle databases, variables declared as binary are stored as raw fields. Refer to your database documentation for information specific to your data source or RDBMS.

Is it possible to use the same XFD file for data files with different names, if they all have the same structure? This would be useful when I create several customer files that use the same record definitions.
At run time, it is possible to use a single XFD for files that have different names. For example, suppose a site has customer files that have identical structures but different names (such as CUST0001, CUST0002, and CUST0003). It's not necessary to have a separate XFD for each file, as long as their record definitions are the same. The individual files can all be mapped to the same XFD via the configuration variable XFD_MAP. Here's how it works.

Suppose your COBOL application has a SELECT with a variable ASSIGN name, such as customer-file. This variable assumes different values (such as CUST0001 and CUST0002) during program execution.

Before compiling the application, you would use the FILE XFD directive to provide a base name for the XFD. Suppose you provide CUST as the base. The Compiler would then generate an XFD named cust.xfd. (The Compiler always converts XFD names to lower case.)

To ensure that all customer files, each having a unique name, use this same XFD, enter the following in your configuration file:

XFD_MAP  CUST* = CUST

The asterisk (*) in the example is a wildcard that matches any number of characters. The extension .xfd should not be included in the map. This statement would cause the XFD cust.xfd to be used for all files whose names begin with CUST.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...
where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:
* matches any number of characters
? matches a single occurrence of any character
For example:
CUST???? matches CUST0001 and CUSTOMER;

does not match CUST001 or CUST00001

CUST* matches all of the above
CUST*1 matches CUST001 and CUST0001 and CUST00001;

does not match CUSTOMER

*OMER matches CUSTOMER;

does not match CUST001 or CUST0001

The XFD_MAP variable is read during the open file stage with the run time system.
Parent topic: Database Connectors User's Guide
Related reference
Configuring the File Handler


Database Connectors Tasks

  • To Configure a Login
  • To create an error map
  • To enable tracing for Database Connectors connections
  • To install Database Connectors for Microsoft SQL Server
  • To prepare your program for execution using Database Connectors
  • To set the system parameters
  • To Set Up a Service Name for an Oracle Database
  • To Set Up The DB2 User Environment
  • To compile and run the demo program
  • To Test the Installation of Oracle's Instant Client
  • To use the WHERE constraint from COBOL
Parent topic: Database Connectors for Visual COBOL


To Configure a Login

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Note: You will probably need database administrator privileges to perform the following action.
If you want to specify a database login name other than the system login name, you can grant it the necessary privileges using the following SQL syntax, when connected to the database:
GRANT CONNECT, RESOURCE TO db_login_name IDENTIFIED BY
    password

where db_login_name is the name you want to use to log in to the database.

For more details on login, see your site's DBA and the Oracle Database Administrator's Guide.

Parent topic: Database Connectors Tasks
Related reference
Setting Up a User Account


To create an error map

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Create an error map file to map DB2 error messages to COBOL error responses. This file is optional.

Although you can check your data source documentation for error code information, the easiest way to determine which error codes need to be mapped to more appropriate COBOL codes is through trial and error. As users use Database Connectors DB2, they may report receiving error messages that don't make sense based on their situation. Research these errors and try to determine a more appropriate COBOL error response.

When you create your error map file, use the following guidelines:

  • Begin comment lines with "#". Blank lines are also considered comments
  • Break the rest of the file into sections, with each section header comprising all the information enclosed in brackets from the data source error function.

    The following example leads to the entry in the sample DB2 error file:

      OdbcOneInfo: State: 23505, Native Error: -803
  '[IBM][CLI Driver][DB2/NT]SQL0803N One or more values in the INSERT statement, UPDATE statement, or foreign key update caused by a DELETE statement are not valid because they would produce duplicate rows for a table with a primary key, unique constraint, or unique index.  SQLSTATE=23505'
  Setting f_errno = 19
Leaving, error
***File system error value = -803 ***
>>>file status = 9S,-803
  • Include two fields in each line in the section: the internal error number, and a mapping string.

    Using the same example, you would include this line in the error_map file:

    -803 E_DUPLICATE

    The valid values for the second field are as follows:

    E_SYS_ERR
E_PARAM_ERR
E_TOO_MANY_FILES
E_MODE_CLASH
E_REC_LOCKED
E_BROKEN
E_DUPLICATE
E_NOT_FOUND
E_UNDEF_RECORD
E_DISK_FULL
E_FILE_LOCKED
E_REC_CHANGED
E_MISMATCH
E_NO_MEMORY
E_MISSING_FILE
E_PERMISSION
E_NO_SUPPORT
E_NO_LOCKS
Parent topic: Database Connectors Tasks
Related reference
A DB2 ERROR MAP FILE configuration variable


To enable tracing for Database Connectors connections

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Edit a Consolidated Tracing Facility (CTF) configuration file to include the tracing elements for Database Connectors.

  1. Edit or create a CTF configuration file, config.ctf, and ensure it includes:
    mftrace.comp.mf.rts#eprintf
mftrace.level=info
  2. Set the MFTRACE_CONFIG and MFTRACE_LOGS environment variables:
    MFTRACE_CONFIG=config.ctf
MFTRACE_LOGS=.
    Note: These values specify that a configuration file called config.ctf is used within the current working directory, and that the tracing log file is also created in the current working directory. You may change these values to suit your needs.
  3. In your ACUFH configuration file, set the following variables:
    FILE-TRACE 1
FILE-TRACE-FLUSH 1
  4. Run your Database Connectors COBOL application.

    The interaction is traced in the log file, located in the current working directory.

Parent topic: Database Connectors Tasks
Related reference
FILE TRACE configuration variable
FILE TRACE FLUSH configuration variable


To install Database Connectors for Microsoft SQL Server

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
Note: Your Microsoft SQL Server can be installed on a separate server, or on the same machine as your client. See the Microsoft SQL Server help for details on how to configure the relevant communications.
  1. Install a supported version of Microsoft SQL Server.

    You must install and configure Microsoft SQL Server, version 6.5 or later, on the Windows or Linux server machine before you install Database Connectors for MSSQL on the client machine. Follow the installation instructions from the vendor.

  2. Copy ms_inst.cmd (Windows) or ms_inst.sh (Linux/UNIX) from the install (Windows), or /src/mssql (Linux/UNIX) sub-directory of your Micro Focus product installation directory to a directory on the server.

    This is the batch file supplied by Micro Focus that creates the stored procedures necessary for using Database Connectors.

  3. Execute the batch file using the following command:

    ms_inst LockDatabase

    where LockDatabase is the database you want to use for the internal lock tables; this does not need to be an existing database, as one will be created, if required, in the next step. However, you must ensure the required Database Connectors users have write access to this database.

    Executing this command produces a ms_inst.sql file.

  4. Execute the contents of this file (ms_inst.sql) using one of the appropriate database tools (such as SQL Query Analyzer or the SQL Server Management Studio on Windows, or the SQL Server command-line tools on Linux).

    When complete, the stored procedures necessary for the MSSQL connector are installed.

This completes the setup on the server machine.

Note: If you are updating from an earlier version of Database Connectors, be sure to install the new stored procedures. Stored procedures are always updated in such a way that they are compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software. Your new version of Database Connectors for MSSQL may not run properly without the corresponding stored procedures.

It can be difficult to maintain multiple copies of stored procedures; therefore, we recommend that you continue to create the stored procedures in the same database. If your installation does not permit this, you do have the flexibility to create the stored procedures elsewhere. However, to facilitate maintenance of the stored procedures, we recommend that you create as few databases as possible.

Parent topic: Database Connectors Tasks


To prepare your program for execution using Database Connectors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

There are a number of mandatory and optional steps that you must perform to prepare your COBOL program, and then run it to interface with an RDBMS. Some of these steps can be achieved a number of different ways, with some offering greater benefits over others.

The CREATEXFD directive
This directive must be specified in order to create the .XFD file required to interface with an RDBMS.
You would usually specify it within your source code or during compilation (either on the command line or within project properties). It does not matter where you specify it as long as it is picked up during compilation.
If you specify it without any further parameters, an XFD file is only created for each indexed file specified within your source code. Specify FILE-TYPE=ALL within parentheses to create XFD files for all file organizations.
By default, any XFD files are created in the current working folder, to specify another directory in which to place them, specify XFD-DIRECTORY=pathname within parentheses to create XFD files in another directory.
See CREATEXFD XFD Directive for more information.
Additional XFD directives
These directives are optional, and are used if you want to override the default settings when creating or amending a table in your RBDMS.
These directives are always placed within a COBOL FD in your source code. They do not affect Procedure Division I/O statements, and they do not change your COBOL fields in any way. Rather, they guide the building of the XFDs, giving you more control over the way COBOL data maps to database fields.
See XFD Directives for more information.
The IDXFORMAT directive or File Handler configuration option
The IDXFORMAT option is mandatory, and tells the COBOL run-time system which RDBMS it is interfacing with when your program executes a FILE I/O operation.
You can set the directive directly into your source code, or during compilation (either on the command line or within project properties), but if you specify the option within a File Handler configuration file, you can simply change the value at run time, enabling you to use the same compiled code to interface with different types of RDBMSs.
See Configuring the File Handler for more information.
Database configuration options
Each supported RDBMS has a number of specific configuration options that you can set. Some are mandatory (such as specifying the database to work with) and some are optional. There are also a number of general configuration options that can be applied to any RDBMS.
You specify these options within the ACUFH configuration file, and then use the A_CONFIG environment variable to make the file available at run time.
See ACUFH Configuration File Variables for RDBMS and ACUFH Configuration Variables for more information.
Parent topic: Database Connectors Tasks
Related reference
CREATEXFD XFD directive
XFD Directives
Configuring the File Handler
ACUFH Configuration Variables
ACUFH Configuration File Variables for DB2
ACUFH Configuration File Variables for MSSQL
ACUFH Configuration File Variables for Oracle


To set the system parameters

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Set the Oracle system parameter OPEN_CURSORS to indicate the total number of cursors you want to have. Look in Oracle's init.ora and initSID.ora, or any other database initialization files used at your site, and add or modify the line:

open_cursors = nnn

The number of cursors can be equal to the number of keys times the number of segments per key for each file. For example, if you have 5 files, each of which has 3 keys, and each key has 3 segments, you should set OPEN_CURSORS to a minimum of "45".

Note: Setting OPEN_CURSORS should be performed only by your system administrator or database administrator, because it affects all applications using the database.
Parent topic: Database Connectors Tasks


To Set Up a Service Name for an Oracle Database

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If you are using Oracle client software to connect to a database not on the current machine, you must set up a service name for your database. To set this up, you need the following details from your database administrator:

  • Service name
  • Protocol
  • Host name
  • Port

When you have these, you can use Oracle's Net Configuration Assistant, which is supplied with the Oracle client install. After entering the correct details, the wizard enables you to test the connection.

Tip: You can also test the connection using SQL*Plus: use user-name@service-name for the login.

If successful, you are ready to start configuring the Database Connectors client by editing the ACUFH configuration file. These connection details equate to the A_ORA_DATABASE (service name), ORA_LOGIN (user-name), and ORA_PASSWD (password) configuration variables.

Parent topic: Database Connectors Tasks
Related reference
A ORA DATABASE configuration variable
ORA LOGIN configuration variable
ORA PASSWD configuration variable


To Set Up The DB2 User Environment

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
  1. Create a plain text file that will serve as your ACUFH configuration file.
  2. Within the ACUFH configuration file, set the A_DB2_LOGIN and A_DB2_PASSWD variables, like so:
    A_DB2_LOGIN user-name
A_DB2_PASSWD passwd
    Note: Alternatively, you may not want to specify such details in a file. In which case, you can either set them as environment variables, or set the password variable from your COBOL program by prompting the user to enter a password and then executing:
    SET ENVIRONMENT "A_DB2_PASSWD" TO user-entry
  3. Set the A_DB2_DATASOURCE variable using one of the methods mentioned in the previous step.
  4. Define any other ACUFH configuration file variables you require for your unique environment. For example, consider whether or not setting the USER_PATH variable would be useful in your setup situation.
    Note: Due to current limitations with the interface, ensure A_DB2_USE_CHAR_FOR_BINARY is included and set to 1.
  5. Set the A_CONFIG environment variable to identify your ACUFH configuration file.
Parent topic: Database Connectors Tasks
Related reference
USER_PATH (for DB2) configuration variable
A_DB2_LOGIN configuration variable
A_DB2_PASSWD configuration variable
Run Time System Configuration
ACUFH Configuration File Variables for DB2
A_DB2_USE_CHAR_FOR_BINARY configuration variable


To compile and run the demo program

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Before you compile the demo program, ensure that your RDBMS data source is available and correctly configured. The demo program (demo.cbl) by default is located in the Connectors sub-directory within your $COBDIR/demo directory.

  1. From a Visual COBOL command or shell prompt, set the environment variable A_CONFIG to the path of your ACUFH configuration file.
    Note: See the specific RDBMS sections for details of the variables your configuration file should contain as a minimum requirement. You do not need to add the variables for user name and password, as these are prompted for when the program runs.
    A_CONFIG=/path/to/myconfig.cfg
export A_CONFIG
  2. Enter the compilation command:
    cob demo.cbl IDXFORMAT"nn";

    where nn is either 18 (for MSSQL), 19 (for Oracle), 20 (for DB2), or 22 (for ODBC).

    Note: The CREATEXFD directive is also a minimum requirement, but this is explicitly specified within the program.

    An executable file (demo.int) and an XFD file (orderfile.xfd) is built.

  3. After compilation, run the program:
    cobrun demo.int
    Note:

    If you are not running the executable from the same directory as the XFD file, you will also need to add XFD_PREFIX path/to/xfd-file to your ACUFH configuration file.

    On HP-UX platforms, you must use the cobrun_t syntax so that your application and the RDBMS both use a multi-threaded run time system; a mix of single- and multi-threaded run time systems will produce an error.

  4. When prompted, enter a valid username and password for your RDBMS.

  5. When the following screen appears, use A)dd to add a new record.

    When you save the record, it is written to a new table (orderfile) within the database specified in the ACUFH configuration file.

  6. Press Q)uit to end the demo program.
Parent topic: Database Connectors Tasks
Related reference
Run Time System Configuration
File Handling Configuration
Configuring the File Handler for DB2
Configuring the File Handler for Microsoft SQL Server
Configuring the File Handler for Oracle


To Test the Installation of Oracle's Instant Client

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Go to a different directory from the one on which you installed Oracle's Instant Client and enter the following command:

sqlplus scott@bigdb/tiger
select user from dual;

If this test is successful, you are ready to use the run-time. The run time loads the Oracle Instant Client dynamically from the specified path.

Parent topic: Database Connectors Tasks


To use the WHERE constraint from COBOL

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The following steps are required for using the WHERE constraint.

  1. Declare an External Variable

    To make use of WHERE constraints from COBOL, the application must declare an external variable for communication with the Database Connectors interface. This variable is declared as follows:

    77  a4gl-where-constraint  pic x(32750) external.
  2. Modify Your COBOL Procedures

    Your COBOL application should move the information that you want added to the WHERE clause to the new external variable before a COBOL positioning operation such as START or READ is performed. The additional constraint is then applied to any SQL read query performed on that file until a new positioning operation is performed.

    The additional query information is also stored in the Connector's cursor cache, so that if the same read conditions occur in later processing, the existing closed cursor can be reused with new bind variables instead of being regenerated.

    Be sure to fill the external variable before a positioning operation (START or READ). The WHERE constraint affects only READ NEXT operations preceded by a positioning operation. The WHERE constraint does not affect a READ NEXT that was not preceded by a positioning operation (such as a READ NEXT without a START immediately after opening a file).

Example

In your COBOL program you include this statement:

Move "ftest_key > 3 and ftest_key < 6" to
   A4GL_WHERE_CONSTRAINT.
Inspect A4GL_WHERE_CONSTRAINT replacing trailing spaces by
   low-values.
START FTEST-FILE KEY NOT LESS FTEST-KEY.

These results occur:

CURSOR 0:
SELECT *,ROWID FROM ftest WHERE (ftest_key1_seg1 = ? AND
ftest_key1_seg2 >= ?) AND (ftest_key > 3 and ftest_key < 6)
ORDER BY ftest_key1_seg1 ASC, ftest_key1_seg2 ASC;
CURSOR 1:
SELECT *,ROWID FROM ftest WHERE (ftest_key1_seg1 > ?) AND
(ftest_key > 3 and ftest_key < 6) ORDER BY ftest_key1_seg1 ASC,
ftest_key1_seg2 ASC;

Limitations

  • WHERE constraints added by the COBOL program may not be portable between databases.
  • The application may specify conditions of such complexity that they confuse the database query optimizer, resulting in poor performance. Be sure to examine the results of the optimizer trace facilities to ensure optimal performance.
  • Verify the COBOL application is not sending information that results in a syntax error that is not detected until run time.
  • The WHERE constraint should reference only columns in the primary table.
  • If users have different configurations at different sites, so that some files can be vision files at one site, but Database Connectors tables at another site, then the WHERE-CONSTRAINT can be difficult to use. This happens because after the WHERE-CONSTRAINT is used, it is marked empty so it won't be used again. However, if a file is a vision file, the WHERE-CONSTRAINT is not used, and might be used for the next file. For example: At site 1, files AA and AB are both SQL Server tables. At site 2, file AA is a vision file, and AB is a SQL Server table. If the COBOL program sets a WHERE-CONSTRAINT that would work with file AA, then at site 2, that WHERE-CONSTRAINT will instead be used for file AB, which will fail.
Parent topic: Database Connectors Tasks


Database Connectors Reference

  • Configuration Variables
    Use the following variables to configure Database Connectors.
  • Database Connectors Error Messages
  • XFD Directives
    The following are XFD directives for Database Connectors.
  • Compiler Directives Affecting XFD Creation
    The following are compiler directives that directly affect XFD creation.
Parent topic: Database Connectors for Visual COBOL


Configuration Variables

  • 4GL_2000_CUTOFF configuration variable
  • 4GL_8_DIGIT_CUTOFF configuration variable
  • 4GL_COLUMN_CASE configuration variable
  • 4GL_COMMIT_COUNT configuration variable
  • 4GL_CONVERT_DATE_ZERO configuration variable
  • 4GL_DB_MAP configuration variable
  • 4GL_FULL_DATA_TEST configuration variable
  • 4GL_IGNORED_SUFFIX_LIST configuration variable
  • 4GL_ILLEGAL_DATA configuration variable
  • 4GL_JULIAN_BASE_DATE configuration variable
  • 4GL_WHERE_CONSTRAINT configuration variable
  • A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable
  • A_DB2_CATALOG configuration variable
  • A_DB2_COMMIT_ON_BEGIN
  • A_DB2_DATASOURCE configuration variable
  • A_DB2_ERROR_MAP_FILE configuration variable
  • A_DB2_ISOLATION_LEVEL configuration variable
  • A_DB2_LOCK_METHOD configuration variable
  • A_DB2_LOGIN configuration variable
  • A_DB2_PASSWD configuration variable
  • A_DB2_STRICT_EQUAL configuration variable
  • A_DB2_TABLE_TYPES configuration variable
  • A_DB2_USE_CATALOG configuration variable
  • A_DB2_USE_CHAR_FOR_BINARY configuration variable
  • A_MSSQL_ADD_IDENTITY
  • A_MSSQL_ADD_TIMESTAMP
  • A_MSSQL_APPROLE_NAME
  • A_MSSQL_APPROLE_PASSWD
  • A_MSSQL_CREATE_UNICODE_COLUMNS
  • A_MSSQL_CURSOR_OPTION_1,2,3
  • A_MSSQL_DATABASE
  • A_MSSQL_DEADLOCK_LOOPS
  • A_MSSQL_DEFAULT_CONNECTION
  • A_MSSQL_DEFAULT_OWNER
  • A_MSSQL_DO_NOT_TRANSLATE_CHAR
  • A_MSSQL_FAILOVER_PARTNER
  • A_MSSQL_FAILOVER_PARTNER_SPN
  • A_MSSQL_FAST_ACCESS
  • A_MSSQL_IGNORE_GUID_COLUMNS
  • A_MSSQL_LIMIT_DROPDOWN
  • A_MSSQL_LOCK_DB
  • A_MSSQL_LOGIN
  • A_MSSQL_MAX_BINARY_LENGTH
  • A_MSSQL_MAX_CHAR_LENGTH
  • A_MSSQL_MAX_CHARACTERS
  • A_MSSQL_MAX_COLUMNS
  • A_MSSQL_MULTI_SUBNET_FAILOVER
  • A_MSSQL_NATIVE_LOCK_TIMEOUT
  • A_MSSQL_NO_23_ON_START
  • A_MSSQL_NO_CACHED_READ
  • A_MSSQL_NO_COUNT_CHECK
  • A_MSSQL_NO_DBID
  • A_MSSQL_NO_RECORD_LOCKS
  • A_MSSQL_NO_TABLE_LOCKS
  • A_MSSQL_NT_AUTHENTICATION
  • A_MSSQL_ODBC_DRIVER_NAME
  • A_MSSQL_PACKETSIZE
  • A_MSSQL_PASSWD
  • A_MSSQL_ROWCOUNT
  • A_MSSQL_SELECT_KEY_ONLY
  • A_MSSQL_SEPARATE_LOCK_CONN
  • A_MSSQL_SERVER_SPN
  • A_MSSQL_SKIP_ALTERNATE_KEYS
  • A_MSSQL_STRIP_PATH_INFO
  • A_MSSQL_TRANSACTION_LEVEL
  • A_MSSQL_TRANSLATE_TO_ANSI
  • A_MSSQL_UNLOCK_ON_EXECUTE
  • A_MSSQL_UPDATE_PRIMARY_COLS
  • A_MSSQL_USE_DROPDOWN_QUERIES
  • A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable
  • A_ODBC_CATALOG configuration variable
  • A_ODBC_COMMIT_ON_BEGIN configuration variable
  • A_ODBC_DATASOURCE configuration variable
  • A_ODBC_ERROR_MAP_FILE configuration variable
  • A_ODBC_ISOLATION_LEVEL configuration variable
  • A_ODBC_LOCK_METHOD configuration variable
  • A_ODBC_LOGIN configuration variable
  • A_ODBC_NO_NULL_COLUMNS
  • A_ODBC_PASSWD
  • A_ODBC_PRINT_LOG configuration variable
  • A_ODBC_QUOTE_IDENTIFIERS configuration variable
  • A_ODBC_STRICT_EQUAL configuration variable
  • A_ODBC_TABLE_TYPES configuration variable
  • A_ODBC_UNSIGNED_TINYINT configuration variable
  • A_ODBC_USE_CATALOG configuration variable
  • A_ODBC_USE_CHAR_FOR_BINARY configuration variable
  • A_ODBC_USE_SPACE_IN_DATES configuration variable
  • A_ODBC_USE_SQLCOLUMNS configuration variable
  • A_ODBC_USE_SQLTABLES configuration variable
  • A_ORA_DATABASE configuration variable
  • A_ORA_HINTS configuration variable
  • A_ORA_KEEP_START_CURSOR configuration variable
  • A_ORA_LIMIT_DROPDOWN configuration variable
  • A_ORA_MAX_FILE_CURSORS configuration variable
  • A_ORA_NLS_SORT configuration variable
  • A_ORA_WAIT_LOCK configuration variable
  • A_ORACLE_ERROR_FILE configuration variable
  • COMMIT_COUNT configuration variable
  • FILE_TRACE configuration variable
  • FILE TRACE FLUSH
  • ORA_LOGIN configuration variable
  • ORA_PASSWD configuration variable
  • USER_PATH (for Oracle) configuration variable
  • USER_PATH (for DB2) configuration variable
  • XFD_DIRECTORY configuration variable
  • XFD_MAP configuration variable
  • XFD_MAP_RESETS configuration variable
  • XFD_PREFIX configuration variable
Parent topic: Database Connectors Reference


4GL_2000_CUTOFF configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable implements "date windowing" for Database Connectors. It determines the two-digit years considered to be in the twentieth century and the two-digit years considered to be in the twenty-first century.

This variable accepts a two-digit value. Two-digit years that are smaller than this value are considered part of the twenty-first century ("2000" is added to these dates).

Two-digit years that are equal to or larger than this value are considered to be in the twentieth century ("1900" is added to them).

The default value for 4GL_2000_CUTOFF is 20.

Parent topic: Configuration Variables
Related information
4GL_8_DIGIT_CUTOFF configuration variable


4GL_8_DIGIT_CUTOFF configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable determines whether to use the 4GL_2000_CUTOFF variable for dates that do not use a format string and that are 8 digits. Setting this variable to 1 causes Database Connectors to apply the 4GL_2000_CUTOFF logic for 8-character-long dates. The default value is 0 (off, false, no). This variable can also take values of 1 (on, true, yes).

Parent topic: Configuration Variables
Related information
4GL_2000_CUTOFF configuration variable


4GL_COLUMN_CASE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This configuration variable causes Database Connectors to leave the case of the field names found in the XFD unchanged. Normally, all field names are converted to lower case by the Connector (except for Oracle, which converts all values to upper case), and all hyphens are converted to underscores.

Valid values are:

UNCHANGED | All field names are used unchanged when the database table is created. Be aware that hyphens are not converted to underscores in this situation. Most databases do not accept hyphens in column names, so the XFD must be modified by hand to replace hyphens with underscores
LOWER (default) | Field names are converted to lower case and hyphens are converted to underscores
Parent topic: Configuration Variables


4GL_COMMIT_COUNT configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The 4GL_COMMIT_COUNT variable sets the conditions in which Database Connectors issues an automatic COMMIT WORK operation. Valid values are:

0 (Default) | The run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement
n | When set to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of 4GL_COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released
-1 | No commit is issued by Database Connectors

When 4GL_COMMIT_COUNT is set to -1, the alternatives are:

  • Call your database query tool with COMMIT WORK or ROLLBACK WORK

A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

Examples

4GL_COMMIT_COUNT 0

A commit is issued when no locks are held, either because all files that had locked records are closed, or because a COBOL COMMIT verb has been issued. This is the default value.

Note that some data sources lose the current row when a COMMIT or ROLLBACK is executed. For these data sources, setting 4GL_COMMIT_COUNT to 0 can slow performance.

4GL_COMMIT_COUNT n

A commit is issued after n operations. WRITE, REWRITE, and DELETE count towards n; READ, START, and READ NEXT do not.

4GL_COMMIT_COUNT  -1

No commit is issued by Database Connectors. When 4GL_COMMIT_COUNT is set to -1, the only way to perform a commit or rollback is to call your database query tool with COMMIT WORK or ROLLBACK WORK.

Note:
  • 4GL_COMMIT_COUNT can be set in the ACUFH configuration file only
  • 4GL_COMMIT_COUNT is available only in the Database Connectors for DB2 interface
Parent topic: Configuration Variables


4GL_CONVERT_DATE_ZERO configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

If your data uses dates as part of database keys, some database dates cannot be written as NULL or illegal values. To write data that includes NULL or illegal values, the Connector converts the NULL or illegal date values used in keys to a value of 01/01/01 when writing data to some databases. Unfortunately, the code would not make a similar conversion when reading the same record, and those records written with 01/01/01 were not found. This could easily result in writing a record that cannot be read or deleted. When 4GL_CONVERT_DATE_ZERO is set to the default setting CONVERTED, the Connector locates and returns those records written using the date 01/01/01. This functionality can be disabled by setting the variable to UNCHANGED.

Parent topic: Configuration Variables


4GL_DB_MAP configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This configuration variable lets you set one map at a time, by using FILE-PREFIX as a list of directories, each of which maps to a different database. Note that in this case "database" refers to "collection of tables" rather than distinguishing between, say, DB2 and Microsoft SQL Server.

The syntax of the value of 4GL_DB_MAP is:

directory = database

where directory is matched against the file specification, and database is used when a directory matches. For example, if you have two databases, data01 and data02, and have COBOL programs written that reference data files in /home/dataA and /home/dataB, you can set 4GL_DB_MAP as follows:

4GL-DB-MAP /home/dataA = data01
4GL-DB-MAP /home/dataB = data02

When the run time attempts to open a file with a directory specification of /home/dataA, the Connector uses the table in database data01.

By setting this variable to blank, all maps are reset to nothing, so no mapping is performed.

Currently, this feature is available with the Database Connectors for Microsoft SQL Server interface. Any special instructions are included in the section describing support.

The 4GL_USEDIR_LEVEL variable determines how many levels of directory information to use as part of a table name. 4GL_DB_MAP interacts with 4GL_USEDIR_LEVEL, in the following way:

  • 4GL_DB_MAP is tested first, to determine which database to search for the table
  • Then 4GL_USEDIR_LEVEL is used to change the final name of the table
Parent topic: Configuration Variables


4GL_FULL_DATA_TEST configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The ACUFH configuration file variable 4GL_FULL_DATA_TEST lets you specify whether an entire field is tested for illegal data or if only the first byte is tested. The default value is False (0, off, no), meaning that only the first byte of data is tested. However, if set to True (1, on, yes), the entire field is tested for illegal data.

Parent topic: Configuration Variables


4GL_IGNORED_SUFFIX_LIST configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable is a space-delimited list of case-independent suffixes to ignore when opening Microsoft SQL Server tables or DB2 tables.

The standard syntax for MSSQL tables is

server.database.owner.table

with a dot (".") as the separator. This syntax causes the filename idx1.dat to be interpreted as "the table dat owned by the user idx1." By setting this variable (which must be set in the ACUFH configuration file, and cannot be set via SET ENVIRONMENT), the Connector ignores the listed suffixes.

There can be up to 10 ignored suffixes (more than that are not kept internally, and are ignored.) The default value for this variable is dat.

Example

4GL_IGNORED_SUFFIX_LIST dat idx txt
Parent topic: Configuration Variables


4GL_ILLEGAL_DATA configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

4GL_ILLEGAL_DATA determines how COBOL data considered illegal by the database is converted before being stored in the database.

The default value is NULL. This causes all illegal data (except key fields) to be converted to null before it is stored.

The value CONVERTED causes the following conversions to occur:

Illegal LOW-VALUES | Minimum possible value (0 or 99999...) Minimum possible date value (01/01/01)
Illegal HIGH-VALUES | Maximum possible value (99999...) Maximum possible date value (database dependent)
Illegal SPACES | Zero (or 01/01/01 for a date field)

Illegal data in key fields is always converted, regardless of the value of this variable.

Parent topic: Configuration Variables


4GL_JULIAN_BASE_DATE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable sets the base date to be used for Julian date calculations. It is used in conjunction with the DATE XFD directive.

To define your own base date for Julian dates, set this variable to a date having the format YYYYMMDD.

The default value is set internally at 01/01/4713 BC. (Dates other than the default must be greater than 01/02/4713 BC.)

For example, suppose your COBOL program uses dates in the form of the number of days since 12/31/1899. If you want to store these dates in a database accessed by Database Connectors, you can set your DATE XFD directives to be $XFD DATE=JJJJJJ (make sure that the number of characters matches your date field). Then you should set the configuration variable 4GL_JULIAN_BASE_DATE to 18991231.

If you are using the run time intrinsic functions that work with Julian dates, set 4GL_JULIAN_BASE_DATE to December 31, 1600 using the Gregorian calendar.

Parent topic: Configuration Variables
Related information
DATE directive


4GL_WHERE_CONSTRAINT configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

4GL_WHERE_CONSTRAINT lets you override any value given in the external variable A4GL-WHERE-CONSTRAINT. This ACUFH configuration file variable can have a value with any length (limited only by machine memory). If a value is set in 4GL_WHERE_CONSTRAINT, any value in the external variable is ignored. For information on the external variable, see The WHERE Constraint.

Parent topic: Configuration Variables
Related information
The WHERE Constraint


A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction-oriented database but have not explicitly coded transactions into their COBOL application.Note that explicitly coded transactions are not supported in this version of Database Connectors.

A_DB2_ALTERNATE_COMMIT_LOGIC determines how the interface responds to the setting of 4GL_COMMIT_COUNT.

Value | Result
0 or FALSE (the default) | The value of 4GL_COMMIT_COUNT is checked only at startup. The interface issues a commit when the criteria set by 4GL_COMMIT_COUNT is met, regardless of the current transaction state
1 | The value of 4GL_COMMIT_COUNT is checked after each WRITE, REWRITE, DELETE, or UNLOCK operation. A commit is issued; however, only if the run time is not currently in a transaction

Example

4GL_COMMIT_COUNT=1
A_DB2_ALTERNATE_COMMIT_LOGIC=0

Each WRITE operation is committed to the database immediately. This prevents an application from being able to rollback a WRITE.

Parent topic: Configuration Variables
Related information
4GL_COMMIT_COUNT configuration variable


A_DB2_CATALOG configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable indicates the catalog name to be used when Database Connectors searches for objects in the database. Note that not all data sources support a catalog. Using A_DB2_CATALOG with other variables, such as USER_PATH and A_DB2_TABLE_TYPES, can speed up the finding of tables in large databases. It can also prevent an error 9/14: More than one table with the same name, thereby enabling access to tables with identical names, but with different catalogs.

For example, If USER_PATH and A_DB2_CATALOG are used, the form of the SQL statement is modified from:

select COL1, ... from TABLENAME ...

to:

SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

Parent topic: Configuration Variables
Related information
A_DB2_TABLE_TYPES configuration variable
USER_PATH configuration variable


A_DB2_COMMIT_ON_BEGIN

DB2 has no START TRANSACTION method. Everything since the last COMMIT or ROLLBACK is considered part of the current transaction.

To ensure that the previous transaction has been ended before a new one begins, set A_DB2_COMMIT_ON_BEGIN to a nonzero value. This causes each COBOL START TRANSACTION to first issue a COMMIT. This ensures that the previous transaction has been ended before the new one starts.

If this variable is not set, or is set to 0, a COBOL ROLLBACK may affect file I/O that occurred before the most recent COBOL START TRANSACTION. While the default value is 0 (off, false, no), this configuration variable can also take values of On (true, yes).

Parent topic: Configuration Variables


A_DB2_DATASOURCE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Set A_DB2_DATASOURCE to the exact name of the host data source. You can set this variable in your COBOL ACUFH configuration file if using only one data source.

Example

A_DB2_DATASOURCE stores

If you don't know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_DB2_DATASOURCE" TO "data source name"

There is no default value for this variable.

Parent topic: Configuration Variables


A_DB2_ERROR_MAP_FILE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Set A_DB2_ERROR_MAP_FILE to the name of the file that maps database-specific errors to COBOL errors. This variable allows you to map errors using a text file to supplement the default method of providing errors. Create the file using the guidelines described in To create an error map, and then use this variable to indicate the name and location of the file you created.

Example

If the file used for mapping is called db2.err, and this file is located in the directory C:\DB2, you would specify:

A_DB2_ERROR_MAP_FILE  c:\DB2\db2.err

There is no default value for this variable.

Parent topic: Configuration Variables
Related information
To create an error map


A_DB2_ISOLATION_LEVEL configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Use the A_DB2_ISOLATION_LEVEL variable to set the isolation level. The default ordering of isolation levels is:

  1. SQL_TXN_READ_COMMITTED
  2. SQL_TXN_READ_UNCOMMITTED
  3. SQL_TXN_REPEATABLE_READ
  4. SQL_TXN_SERIALIZABLE

You can change the isolation level by setting this variable to an integer in the ACUFH configuration file. The settings are:

Isolation level | Setting in ACUFH configuration file
SQL_TXN_READ_UNCOMMITTED | 1
SQL_TXN_READ_COMMITTED | 2
SQL_TXN_REPEATABLE_READ | 3
SQL_TXN_SERIALIZABLE | 4

For example, to set the isolation level to SQL_TXN_READ_COMMITTED, add the following entry to the ACUFH configuration file:

A_DB2_ISOLATION_LEVEL 2

If the user-set isolation level is not supported by the driver, the default method of selecting a level is used.

Parent topic: Configuration Variables


A_DB2_LOCK_METHOD configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Use this configuration variable to specify the locking method that Database Connectors for DB2 should use when accessing your data source. Possible values are:

  • None
  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

The default is UPDATECOLUMN.

Example:

A_DB2_LOCK_METHOD UPDATECOLUMN

SETPOS

Specify SETPOS as your lock method to tell the Connector to perform the following locking sequence:

  • When setting up a statement handle for accessing the DB2 data source, Database Connectors calls a function called SQLSetScrollOptions, with values (SQL-CONCUR-LOCK, SQL-SCROLL-KEYSET-DRIVEN, 1)
  • When fetching rows from the data source, Database Connectors calls SQLExtendedFetch instead of SQLFetch
  • Finally, the Connector calls SQLSetPos, with the values (1, SQL-POSITION, SQL-LOCK-EXCLUSIVE)

If any of these functions do not exist, A_DB2_LOCK_METHOD reverts to None.

Note: Even if these functions do exist, there is no guarantee that any rows lock using this sequence of calls. Contact your database vendor to determine whether or not this sequence is effective for your data source.

SETSTMTOPTION

This option is similar to SETPOS, except a function called SQLSetStmtOption performs the task of SQLSetScrollOptions and has more functionality.

In particular, when using this method of locking, Database Connectors calls SQLSetStmtOption a number of times, with values (SQL-CONCURRENCY, SQL-CONCUR-LOCK), (SQL-CURSOR-TYPES, SQL-CURSOR-KEYSET-DRIVEN), and (SQL_KEYSET-SIZE, 1). Again, if the function does not exist, A_DB2_LOCK_METHOD reverts to None.

UPDATECOLUMN

Specifying UPDATECOLUMN as your lock method performs an entirely different type of locking. Instead of trying to lock a row while reading it, this method creates a new statement handle for the data source. Then, after fetching the data from the data source, it resubmits an SQL query to select the same row (based on the primary key) and adds an UPDATE clause. Last, it fetches the data from the data source. This method has the most overhead, but it is much more likely to succeed in locking records.

Parent topic: Configuration Variables


A_DB2_LOGIN configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_DB2_LOGIN indicates the user name under which you want to connect to the database system. Not all data sources require a user login name. Those that do may have case requirements. Check your data source documentation to determine if login is case-sensitive.

Example

To connect to the database with the user name MYNAME, you could specify:

A_DB2_LOGIN  MYNAME

or

A_DB2_LOGIN  myname

in the Database Connectors. There is no default value for this variable. If no login is specified, none is used.

Parent topic: Configuration Variables
Related information
A_DB2_PASSWD configuration variable


A_DB2_PASSWD configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_DB2_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_DB2_LOGIN. Not all data sources require a password. Those that do may have case requirements. Check your data source documentation to determine if password is case-sensitive.

Examples

If the account with the user name in A_DB2_LOGIN has the associated password CW021535, you would specify:

A_DB2_PASSWD  CW021535

in the Database Connectors.

For better security, you can accept a password from the user during program execution; set the A_DB2_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_DB2_PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set. There is no default value for this variable. If no password is specified, none is used.
Parent topic: Configuration Variables
Related information
A_DB2_LOGIN configuration variable


A_DB2_STRICT_EQUAL configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When Database Connectors for DB2 executes a START ... KEY EQUAL keyval, the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval. When fetching the data, Database Connectors eventually detects that there is no more data.

If A_DB2_STRICT_EQUAL is set to True at the time the START is executed, the interface returns the error END OF FILE (error 10) at this point. If A_DB2_STRICT_EQUAL is set to False (default), Database Connectors then generates a new SELECT statement to continue reading records until the end of the file rather than the subset of records represented by keyval, and these records may be discarded by the program. (Note that this is program-dependent behavior.)

Setting A_DB2_STRICT_EQUAL to True causes the interface to stop reading records earlier, which can make SELECT statements generated by Database Connectors more efficient.

Note the following conditions:

  • A_DB2_STRICT_EQUAL must be set to True when the START is executed
  • The START must be a KEY EQUAL start
  • There must be no COMMITs between the START and the end of the file. Because DB2 closes all cursors on COMMIT and ROLLBACK (according to the ANSI 92 SQL standard), the interface must regenerate a SELECT the first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK. This means that 4GL_COMMIT_COUNT should be set to -1, so that no COMMITs are issued by Database Connectors
  • A_DB2_STRICT_EQUAL is most useful with alternate keys that allow duplicates

While the default value is False (off, no, 0), this variable can also take the value True (on, yes, 1).

Note: This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT, but using A_DB2_STRICT_EQUAL requires less programming.
Parent topic: Configuration Variables
Related information
4GL_COMMIT_COUNT configuration variable
4GL_WHERE_CONSTRAINT configuration variable


A_DB2_TABLE_TYPES configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable is used to specify a table type (such as TABLE or VIEW) to search for when selecting a database table. Using A_DB2_TABLE_TYPES with other variables, such as USER_PATH, can speed up finding tables in large databases.

This information is passed to the API function call SQLTables() as the TableType parameter. Please refer to your driver’s documentation for supported types.

Example

A_DB2_TABLE_TYPES  TABLE,VIEW
Parent topic: Configuration Variables
Related information
USER_PATH configuration variable
A_DB2_CATALOG configuration variable


A_DB2_USE_CATALOG configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Not all data sources support a catalog, or the data sources may return a catalog name that is not useful. The default behavior of the run time is to not use the catalog in the actual SQL queries. This configuration variable lets you modify this behavior.

The default value is FALSE, which causes the catalog portion of the table name to be treated as blank in SQL queries. Setting this variable to TRUE uses the catalog value returned by SQLTables ODBC function subsequent SQL queries.

Parent topic: Configuration Variables


A_DB2_USE_CHAR_FOR_BINARY configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Some data sources have restrictions on the number of binary large objects (BLOBs) that can be placed into a single table. If your data source has such restrictions, specify A_DB2_USE_CHAR_FOR_BINARY in the ACUFH configuration file. Possible values for this variable are:

0 | use BINARY type
1 | use CHAR type

A nonzero value for A_DB2_USE_CHAR_FOR_BINARY lets you store data that uses the BINARY XFD directive as hexadecimal encoded CHAR types. This lets you work around your data source restriction. While the default value is 0 (off, false, no), this variable can also take values of On (true, yes).

Because of current limitations of the interface, you must set this variable to 1, or the database returns an error on file creation.

Example

A_DB2_USE_CHAR_FOR_BINARY 1
Parent topic: Configuration Variables


A_MSSQL_ADD_IDENTITY

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When set to the default of On (true, yes), A_MSSQL_ADD_IDENTITY adds an extra column to any table created by Database Connectors for MSSQL. You do not have to code this column in your COBOL FD. The extra column includes the identity property and is included on all indexes that are not unique. Otherwise, when A_MSSQL_ADD_IDENTITY is set to False (false, no), no extra column is added.

You can also add an identity column using the XFD directive IDENTITY-COLUMN. Using the XFD directive gives you greater control over where it appears.

You may only specify one identity column per table, and so after the first request has been processed, subsequent requests are ignored.

Example

A_MSSQL_ADD_IDENTITY TRUE

On keys that allow duplicates, this variable has been found to vastly improve performance. Note that the default value is True for a file that allows duplicates and is False for a file with no duplicate keys.

Parent topic: Configuration Variables


A_MSSQL_ADD_TIMESTAMP

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Using a timestamp column is the only way to absolutely ensure that modifications made to a row are not overwriting someone else's changes. When it's reading a table that is open for I/O,Database Connectors for MssQL uses BROWSE MODE if a timestamp column exists. When Database Connectors is creating a table, if the value of A_MSSQL_ADD_TIMESTAMP is TRUE, a timestamp column is included in the table. (Note that your COBOL FD should not include the timestamp column.) While the default value is Off (false, no), this variable can also take values of On (true, yes).

Note: Microsoft discourages the use of BROWSE MODE on Select statements because of performance reasons. Therefore, unless it is absolutely necessary, do not set this variable to On.

Example

A_MSSQL_ADD_TIMESTAMP  1
Note: If you do not use this option, be prepared for REWRITE statements to fail with an error stating that someone else has modified the row. Because of the AcuLocks1 tables, this can happen only from non-COBOL applications. For information about AcuLocks1 tables, see Table Locking.
Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_APPROLE_NAME

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable, in conjunction with A_MSSQL_APPROLE_PASSWD, allows Database Connectors to use approles. Before connecting to a database, set A_MSSQL_APPROLE_NAME to the name of a role. Note that you must also set A_MSSQL_APPROLE_PASSWD to a password for that role. By using these two variables, you set the run time to use this approle.

For more information on approles, please see the Microsoft SQL Server documentation.

Parent topic: Configuration Variables
Related information
A_MSSQL_APPROLE_PASSWD configuration variable


A_MSSQL_APPROLE_PASSWD

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable, in conjunction with A_MSSQL_APPROLE_NAME, enables use of approles. Before connecting to a database, set A_MSSQL_APPROLE_NAME to the name of a role. Then set A_MSSQL_APPROLE_PASSWD to a password for that role. By using these two variables, you set the run time to use this approle.

For more information on approles, please see the Microsoft SQL Server documentation.

Parent topic: Configuration Variables
Related information
A_MSSQL_APPROLE_NAME configuration variable


A_MSSQL_CREATE_UNICODE_COLUMNS

When A_MSSQL_CREATE_UNICODE_COLUMNS is set to TRUE, the Database Connectors for Microsoft for SQL Server interface creates nchar or nvarchar columns for all new text data. Note that existing tables are not affected.

The default value for this variable is FALSE.

Parent topic: Configuration Variables


A_MSSQL_CURSOR_OPTION_1,2,3

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
A_MSSQL_CURSOR_OPTION_1
A_MSSQL_CURSOR_OPTION_2
A_MSSQL_CURSOR_OPTION_3

These ACUFH configuration file variables allow you to fine-tune the declaration of cursors. In general, cursors are declared with the following syntax:

DECLARE cursor_name option_1 CURSOR option_2 FOR
  <select....> option_3

In other words, different phrases can go in each of the option_X places. Also, different versions of Microsoft SQL Server allow different options in each of those places. Because of this, Database Connectors allows customization of the cursor declaration via these three variables. The values of these variables are placed verbatim into the declare phrase when building a cursor. Note that any errors in the values of these variables may cause Database Connectors to be inoperable. Be sure to read the Microsoft SQL Server documentation to determine what phrases are allowed in each case.

The default values are as follows (the limit is 65 characters for each option):

OPTION_1: | "SCROLL"
OPTION_2: | blank
OPTION_3: | "For read only"
Note: This variable was added because of an issue in SQL Server 6.5 and SQL Server 7.0 that would return incorrect results if this phrase was not used.
Parent topic: Configuration Variables


A_MSSQL_DATABASE

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_DATABASE specifies the name of the particular database to be accessed. You cannot open any database files until you have set this variable.

Example

A_MSSQL_DATABASE stores

indicates the "stores" database is to be accessed.

Parent topic: Configuration Variables


A_MSSQL_DEADLOCK_LOOPS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Use A_MSSQL_DEADLOCK_LOOPS if user typically open a number of tables at the same time. This configuration variable can be used to instruct Database Connectors to re-execute an INSERT statement that could not execute because a row in the AcuOpen1Tables table was locked, or to return an error if the user chooses not to run the query again.

Valid values are:

0 (the default) | Returns an error 1205 indicating that a table is locked
A positive numeric value. | Re-executes by the number specified by the query that caused the deadlock. Note that it can be as long as 10 seconds until SQL Server detects the deadlock, and the application appears to stop responding while the repeated attempts to re-execute the query are in progress.
-1 or MESSAGE Displays a message box containing the text of the SQL Server error message and the option to rerun the query.
SQL Server has returned an error
(text of message from SQL Server)
Do you want to retry the operation?

If the user answers Yes, the interface reruns the query; if the user answers No, the interface returns an error.

Setting A_MSSQL_DEADLOCK_LOOPS to -1 or MESSAGE is the preferred action; the time it takes to inform users of the problem allows other connections to finish opening the tables, giving the AcuOpenTables1 table time to remove the deadlock. For information about AcuOpenTables1 table, see Table Locking.

Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_DEFAULT_CONNECTION

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_DEFAULT_CONNECTION specifies the name of the server to which the run time system connects. If A_MSSQL_DEFAULT_CONNECTION is not set, a server name of localhost is used. To reference tables on a server other than the one specified by this variable, open the file using the following syntax:servername.database.owner.table.

Example

Suppose you have two servers, one named TOM and one named HARRY. If most of the tables you want to access are on the server HARRY, you should set:

A_MSSQL_DEFAULT_CONNECTION  HARRY

For those occasions when you want to access the TOM server, you could open the file this way:

TOM.stores.johndoe.purch1
Parent topic: Configuration Variables


A_MSSQL_DEFAULT_OWNER

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

In Microsoft SQL Server, tables are named database.user.tablename. The value of A_MSSQL_DEFAULT_OWNER specifies the name of the user. If this variable is set, it must match the owner of a table. Tables are referenced as owner.table, where owner is the value of A_MSSQL_DEFAULT_OWNER. If this variable is set to a value for which owner.table does not exist, the interface fails to access the table.

Note that newly created tables are owned by the users who create them, not the owner named in A_MSSQL_DEFAULT_OWNER. The default value of this variable is blank, causing the interface to call an internal stored procedure to determine the actual owner of the table. Note also that we discourage multiple tables with the same tablename in a single database.

Parent topic: Configuration Variables


A_MSSQL_DO_NOT_TRANSLATE_CHAR

If an SQL Server database is configured with a collation that conflicts with the Locale of the client program, characters that can not be represented in the database's collation are turned into question marks.

Setting this variable to ON, causes all character fields, except those for date fields, to be treated as binary, storing them in the database and retrieving from the database without translation.

The default setting is OFF and means that character fields, except for date fields, will be translated.

Parent topic: Configuration Variables


A_MSSQL_FAILOVER_PARTNER

This configuration variable specifies the name of the failover partner used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER
A_MSSQL_SERVER_SPN
A_MSSQL_FAILOVER_PARTNER_SPN


A_MSSQL_FAILOVER_PARTNER_SPN

This configuration variable specifies the name of the failover partner SPN used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER
A_MSSQL_SERVER_SPN
A_MSSQL_FAILOVER_PARTNER


A_MSSQL_FAST_ACCESS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_FAST_ACCESS is set from your COBOL program. Files opened while this variable is set to a nonzero value are optimized for forward sequential access.

This option improves the READ NEXT performance in some cases. For example, benchmark testing yielded the following results for the READ AND SKIP operation:

No FAST_ACCESS: | 72.76 seconds
FAST_ACCESS, ROWCOUNT 0: | 148.88 seconds
FAST_ACCESS, ROWCOUNT 10: | 8.09 seconds

(10 is the perfect value for ROWCOUNT in this benchmark, because the program does a START, 10 READ NEXT operations, and then does it again.)

For certain reporting programs, this option can dramatically improve performance. However, please note the following restrictions:

  • Files must be open INPUT or open IO with MASS-UPDATE. FAST_ACCESS boosts performance only when no locking is required. In files that allow locking, a record must be reread after being locked; this prevents an uninterrupted forward sequential traversal.
  • Files opened with FAST_ACCESS use a dedicated connection for reading from the file. Since connections are memory-intensive (both on the client, and on the server), the number of files opened with FAST_ACCESS should be kept to a minimum. In the event that opening a connection fails, the file open continues, but FAST_ACCESS mode is disabled, with the following message appearing in the trace file:
    FAST_ACCESS mode not available.

    Also, a new connection technically uses a new concurrent Microsoft SQL Server license from Microsoft.

  • Files opened with FAST_ACCESS cannot be read backwards. In other words, READ PREVIOUS does not work with FAST_ACCESS files. If you try to READ PREVIOUS on a file opened with FAST_ACCESS, an error 9/83 with a secondary code of 20 occurs.
  • The ANSI standard states that READ NEXT after a READ returns the next record. Some applications depend on this, and some applications just want to read dynamically from a file, and don't use the positioning facility. Because of this ambiguity, files that are opened with FAST_ACCESS cannot be READ dynamically. If you try to READ on a file opened with FAST_ACCESS, an error 9/83 with a secondary code of 20 occurs.

There are no restrictions on WRITE, REWRITE, and DELETE. However, these operations use the cursor-based connection, not the dedicated connection. For this reason, transactions may stop responding.

While the default value is 0 (off, false, no), this variable can also take values of On (true, yes).

Parent topic: Configuration Variables


A_MSSQL_IGNORE_GUID_COLUMNS

This configuration variable determines the behavior when handling existing tables that contain a column of type GUID.

When A_MSSQL_IGNORE_GUID_COLUMNS is set to its default setting of false (Off, 0, or no), you must use COBOL data items that are at least 36 characters in size for GUID columns, otherwise an error is returned when the row is read. When writing or rewriting a row when the GUID data item is too small, SQL Server may produce an error. If you have a GUID that is larger than 36 characters, Database Connectors will only read the first 36 characters; the rest are padded with spaces.

Note: Older ODBC drivers may not be able to handle GUID column types, in which case, the results of those operations are undefined.

If you set A_MSSQL_IGNORE_GUID_COLUMNS to true (on, 1, or yes), columns of type GUID are ignored for any SELECT, UPDATE, or INSERT statements sent to the server. You do not need to specify a COBOL data item for these columns when reading or writing a row.

Parent topic: Configuration Variables


A_MSSQL_LIMIT_DROPDOWN

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This configuration option is closely related to A_MSSQL_USE_DROPDOWN_QUERIES.

When a sequence of START and READ NEXT/PREVIOUS operations are performed by an application, Database Connectors/MSSQL generates a sequence of queries to return the set of records matching the application's request. To improve performance, the interface generates a sequence of "drop down" queries based upon the key of reference's key segments going from the most specific subset using the most number of segments to the most general using the least number of segments. This functionality is turned on by setting the configuration variable A_MSSQL_USE_DROPDOWN_QUERIES to TRUE.

For example if a key is described by:

    03 MY-ALTKEY.
       05 MY-ALTKEY-SEG1        PIC X(2).
       05 MY-ALTKEY-SEG2        PIC X(2).
       05 MY-ALTKEY-SEG3        PIC X(2).

Then a START followed by a sequence of READ NEXT operations might generate the selection criteria of:

WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 = :w1 AND
MY-ALTKEY-SEG3 >= :w3
WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 > :w1
WHERE MY-ALTKEY-SEG1 > :w0

This can improve performance because the target for each query is kept to a minimal size. If a set of records is not required, the database does not need to spend the time building the working set. When a "DROP DOWN" does occur however, the subsequent working set can require a large amount of time to process because of the potential magnitude of records. Normally there is not a way for a COBOL application to instruct the interface to stop processing when it has finished with the records based on a given key segment.

To address this, use A_MSSQL_LIMIT_DROPDOWN configuration variable.

This variable allows an application to direct the interface not to perform "drop down" query generation and instead return "end of file" when the records matching the current query have been exhausted.

This variable may be set to one of the following options:

OFF | This is the current default. The interface performs "drop down" queries.
PARTIAL | If the record positioning was performed by a START with a SIZE clause such that the initial positioning was performed using fewer than the total number of columns in the key, the process stops after all records matching the START columns have been exhausted.
FULL | If the record positioning was performed by a START without a SIZE clause, the process stops after all records matching the START columns have been exhausted.
ALL | Regardless of what form of START was used for the initial positioning, the process stops after all records matching the START columns have been exhausted.

This variable is performed at the time of each start, so the application may change its value.

Parent topic: Configuration Variables
Related reference
A_MSSQL_USE_DROPDOWN_QUERIES


A_MSSQL_LOCK_DB

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_LOCK_DB specifies the name of the database that holds the lock table. For information about AcuLocks1 tables, see Table Locking.

Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_LOGIN

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_LOGIN indicates the user name under which you want to connect to the database system.

Example

To connect to the database with the user name MYNAME, specify A_MSSQL_LOGIN MYNAME in the ACUFH configuration file.

See A_MSSQL_NT_AUTHENTICATION configuration variable for an alternate method to log onto the server. See Setting Up a User Account for more information.

Parent topic: Configuration Variables
Related reference
A_MSSQL_NT_AUTHENTICATION
A_MSSQL_PASSWD
Related information
Setting Up a User Account


A_MSSQL_MAX_BINARY_LENGTH

This configuration variable specifies the maximum size of a COBOL variable that can be used as a BINARY data type in SQL Server. Data items larger than this value become IMAGE types in the server. The default value is 8001.

Parent topic: Configuration Variables


A_MSSQL_MAX_CHAR_LENGTH

This configuration variable specifies the maximum size of a COBOL variable that can be used as a VARCHAR data type in SQL Server. Data items larger than this value become IMAGE types in the server. The default value is 8001.

Parent topic: Configuration Variables


A_MSSQL_MAX_CHARACTERS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_MAX_CHARACTERS indicates the maximum number of bytes the Database Connectors allows in a table row.

Microsoft SQL Server places a limit on the number of bytes per table row. Database Connectors adheres to this limit, but sometimes it cannot accurately count how many bytes a particular row contains (because of overhead bytes that Microsoft SQL Server adds). This variable enables the developer to set Database Connectors upper bound.

You might want to try reducing this value if a table cannot be created. By reducing the upper bound, you may be able to prevent this problem.

If Microsoft SQL Server increases the maximum number of bytes allowed in a row (in a future release of the product), you can increase the value of this variable to take advantage of the new limit.

The A_MSSQL_MAX_CHARACTERS variable has a default value of 8060.

Parent topic: Configuration Variables


A_MSSQL_MAX_COLUMNS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_MAX_COLUMNS indicates the maximum number of columns Database Connectors allows in a table. The default value is 1024.

Microsoft SQL Server places a limit on the number of columns per table. Database Connectors adheres to this limit, but sometimes it cannot accurately count how many columns a table contains (because a column has been added to a table without Database Connectors knowledge). This variable enables the developer to set Database Connectors upper bound. You might want to try reducing the upper bound if you discover that a table cannot be created. By reducing the upper bound, you allow for uncountable columns and thus may be able to prevent this problem.

If Microsoft SQL Server increases the maximum number of columns allowed per table (in a future release of the product), you could increase the value of this variable to take advantage of the new limit. Consult your Microsoft SQL Server documentation to decide the new maximum number of columns allowed per table.

Parent topic: Configuration Variables


A_MSSQL_MULTI_SUBNET_FAILOVER

Set to TRUE to enable multi-subnet failover support for your Microsoft SQL Server connection. If set to FALSE (the default) the feature is not enabled, and the other configuration variables relating to multi-subnet failover have no effect.

Parent topic: Configuration Variables
Related reference
A_MSSQL_SERVER_SPN
A_MSSQL_FAILOVER_PARTNER_SPN
A_MSSQL_FAILOVER_PARTNER


A_MSSQL_NATIVE_LOCK_TIMEOUT

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This is one of two locking methods available with Database Connectors for MSSQL. The methods are accessed via the A_MSSQL_NATIVE_LOCK_TIMEOUT configuration variable. If A_MSSQL_NATIVE_LOCK_TIMEOUT is set to a positive value, native locking is used. Otherwise, the AcuLocks1 table is used to hold locks.

This locking method enables you to use Microsoft SQL Server native locks if you explicitly code transactions in your COBOL program. You can access this method by setting A_MSSQL_NATIVE_LOCK_TIMEOUT to a positive value. This value is the number of seconds that a connection waits for a timeout to occur. When such a timeout occurs, Database Connectors assumes that the timeout is caused by a locked record, and returns error 99 (record locked). If you set this variable but do not explicitly code transactions in your COBOL program, record locking does not occur. Note that Database Connectors waits the number of seconds specified, and your application may appear to stop responding if the timeout is too long. On the other hand, if the timeout is too short, you may get record locked errors when the network is slow.

Microsoft SQL Server uses a page-locking mechanism, and so this method of locking records may cause your application to return spurious record locked errors caused by a record being locked on the same page as the record you are trying to access. Microsoft SQL Server 7.0 uses row-level locking, but because of the timing issue, using this option is not recommended.

Note: Even with this variable set, the interface still needs the AcuOpenTables1 table. For information about AcuOpenTables1, see Table Locking.
Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_NO_23_ON_START

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When A_MSSQL_NO_23_ON_START is set to TRUE, START does not detect whether records matching the search criteria actually exist. Because it does not detect the existence of records, it is possible, when using this variable, to do a START without error, and for the next READ NEXT to return END_OF_FILE, contrary to the ANSI standard. The default value is FALSE.

Example

A_MSSQL_NO_23_ON_START TRUE
Parent topic: Configuration Variables


A_MSSQL_NO_CACHED_READ

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

By default, the Database Connectors for MSSQL run time applies the same READ logic on a previously-read record as is used for the Vision indexed file system. Instead of sending another request to MSSQL to read the same record, the run time gets the record from cache. This behavior is referred to as Cached Read and can improve performance.

A_MSSQL_NO_CACHED_READ controls this behavior. By default cached read is enabled. It can be disabled by setting A_MSSQL_NO_CACHED_READ to true or 1.

If the last operation was a successful READ with LOCK and the next operation is a READ with LOCK on the same key with the same key value then the cached record returneds without accessing the database. A trace file entry is made that says cached read.

Parent topic: Configuration Variables


A_MSSQL_NO_COUNT_CHECK

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When performing a REWRITE, the interface checks to see that a record was actually updated. If not, it returns an error 23. Setting this variable to ON disables that check. This improve REWRITE performance, at the risk of missing an error. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

Parent topic: Configuration Variables


A_MSSQL_NO_DBID

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The interface stores the Database ID in the AcuLocks1 and AcuOpenTables1 tables, to distinguish different tables in different databases. Sometimes this causes problems. Setting this variable to On causes the interface to use a Database ID of 0, instead of the actual ID of the database. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

For information about AcuLocks1 and AcuOpenTables1, see Table Locking.

Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_NO_RECORD_LOCKS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Setting this variable ON causes all READS to be treated as READ NO LOCK, which can improve performance (but has the obvious consequences). While the default value is Off (false, no), this variable can also take the value of On (true, yes).

Parent topic: Configuration Variables


A_MSSQL_NO_TABLE_LOCKS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Setting this variable to On means the interface does not use the AcuOpenTables1 table, which causes all table locking to be disabled. This can improve performance on OPEN and CLOSE statements. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

For information about AcuOpenTables1, see Table Locking.

Parent topic: Configuration Variables
Related information
Table Locking


A_MSSQL_NT_AUTHENTICATION

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The A_MSSQL_NT_AUTHENTICATION configuration variable indicates whether Microsoft SQL Server authenticates users based on their Windows login.

If this variable is set to True (on, yes), Database Connectors for MSSQL interface attempts to log users on using the Microsoft SQL Server Windows NT authentication mode. (See your SQL Server documentation for information about this authentication mode.) When A_MSSQL_NT_AUTHENTICATION is enabled, the A_MSSQL_LOGIN and A_MSSQL_PASSWD configuration variables are no longer needed or used. (They are still available if you are not using Windows NT authentication mode.) If you have not set up Microsoft SQL Server itself to allow this type of authentication, setting this variable to TRUE causes all login attempts to fail. See your Microsoft SQL Server documentation for information on how to set up this type of authentication.

The default is False (off, no), indicating that Database Connectors does not use Windows NT authentication mode when logging users on and continues to use login and password authentication.

Parent topic: Configuration Variables
Related reference
A_MSSQL_PASSWD
A_MSSQL_LOGIN


A_MSSQL_ODBC_DRIVER_NAME

This variable lets you specify a particular ODBC SQL Server driver name for the SQL Server interface. SQL Server is the value set by default, and is the most commonly found name; however, if you intend to use a different driver, set the value to the name of the intended driver, as shown in the ODBC Data Source dialog box (Windows) or odbcinst.ini (UNIX/Linux). Results are undefined if changed to a value which is not a valid supported SQL Server ODBC driver on your system.

The following is a list of currently supported drivers:
  • SQL Server
  • SQL Server Native Client 10.0
  • SQL Server Native Client 11.0
  • ODBC Driver 11 for SQL Server
  • ODBC Driver 12 for SQL Server
  • ODBC Driver 13 for SQL Server
  • ODBC Driver 13.1 for SQL Server
  • ODBC Driver 17 for SQL Server (UNIX/Linux only)
Parent topic: Configuration Variables


A_MSSQL_PACKETSIZE

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The A_MSSQL_PACKETSIZE configuration variable sets the size of network packets. Setting this variable can affect performance, since fewer and larger network calls can improve performance.

This variable must be set in the ACUFH configuration file and has no effect if set in a COBOL program via SET CONFIGURATION or SET ENVIRONMENT. The value of this variable is the largest size that the transport layer uses for network packets (although the underlying library may reduce the size specified; this is out of the control of the interface.) The largest value that can be specified is 32767. The default depends on which version of the client libraries are linked into the run time system, although 512 is the most common default.

Use this variable to tune your database performance. To set the packet size to 8192 use:

A_MSSQL_PACKETSIZE   8192

Setting this variable to 0 or to a negative value causes Database Connectors to use the default value.

Parent topic: Configuration Variables


A_MSSQL_PASSWD

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The variable A_MSSQL_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_MSSQL_LOGIN.

Examples

If the account with the user name in A_MSSQL_LOGIN has the associated password CW021535, specify:

A_MSSQL_PASSWD  CW021535

in the ACUFH configuration file.

For better security, you can accept a password from the user during program execution; set the A_MSSQL_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_MSSQL_PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set.
Parent topic: Configuration Variables
Related reference
A_MSSQL_NT_AUTHENTICATION
A_MSSQL_LOGIN


A_MSSQL_ROWCOUNT

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable has an effect only if you are reading on a key that does not allow duplicates, or if you have added an Identity column to the table. A_MSSQL_ROWCOUNT determines how many rows are returned by a SELECT statement sent to the server.

This variable can be used to speed up the Connector. For example, if only reading one record at a time, and reading from a unique key, you can set A_MSSQL_ROWCOUNT to 1, thus speeding up the processing.

If you know you are going to be reading records ten rows at a time, set A_MSSQL_ROWCOUNT to 10. If you don't have any information about how many rows are going to be requested, set this variable to 0, which is the default.

Note: Setting this variable to a non-optional value can actually degrade performance, since the interface may be forced to issue more SELECT statements once the rowcount has been determined. Use caution when setting this variable.
Parent topic: Configuration Variables
Related information
A_MSSQL_ADD_IDENTITY configuration variable


A_MSSQL_SELECT_KEY_ONLY

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable directs the interface to select key columns only when searching for records. Its use can improve READ performance on large tables with many rows.

When set to True (on, yes), the default value, A_MSSQL_SELECT_KEY_ONLY causes the interface to select only key columns when searching for records, and then select the entire row of the single record that must be returned to the COBOL program. This improves performance on large tables with many rows.

Setting A_MSSQL_SELECT_KEY_ONLY to False (off, no) does not affect how the select is created for files open I/O (since the record must be locked and then the rest of the data fetched), but causes the interface to select all the columns of the table for files open INPUT.

Parent topic: Configuration Variables


A_MSSQL_SEPARATE_LOCK_CONN

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When set to TRUE, this variable causes the Database Connectors for MSSQL interface to open two connections to any server it connects to. One of those connections performs all the normal COBOL data work (write, rewrite, read next, etc).

The second connection does all the internal work needed by the interface to do its normal work, such as updating the lock tables, testing for locks, etc.

The reason for the configuration variable is that a separate connection to SQL Server requires a separate license from Microsoft.

If you are experiencing frequent deadlocks during record locking or opening of tables, you may be able to solve those by setting this variable to TRUE.

Parent topic: Configuration Variables


A_MSSQL_SERVER_SPN

This configuration variable specifies the name of the server SPN used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER
A_MSSQL_FAILOVER_PARTNER_SPN
A_MSSQL_FAILOVER_PARTNER


A_MSSQL_SKIP_ALTERNATE_KEYS

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_MSSQL_SKIP_ALTERNATE_KEYS determines whether alternate keys are used to form indexes during table creation. The default value of this variable is 0, which allows alternate keys. This configuration variable can also take values of 1 (on, true, yes).

If you set this variable to a nonzero value (such as 1), alternate keys are not used to form indexes, which speeds up processing if many writes or rewrites are being performed. (Note that a value of 1 may slow processing if the application is reading sequentially using an alternate key.)

Parent topic: Configuration Variables


A_MSSQL_STRIP_PATH_INFO

This configuration variable addresses a change in the new naming syntax Microsoft SQL Server introduced for servers: Servername\Instancename. Database Connectors for SQL Server treats the naming as a path, and strips the Servername portion.

When set to the default value of TRUE (ON, YES, 1), then the interface behaves as it always has. When set to FALSE (OFF, NO, 0), the interface ignores the name.

Parent topic: Configuration Variables


A_MSSQL_TRANSACTION_LEVEL

Use this configuration variable to indicate the transaction nested level depth for Database Connectors for MSSQL. This is useful when sending embedded SQL Server BEGIN TRANSACTION statements to the server without using the interface. The default is zero (0).

Parent topic: Configuration Variables


A_MSSQL_TRANSLATE_TO_ANSI

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Setting this variable to True (on, yes) causes Database Connectors to call the same translation function used by the Windows run time to translate characters going to the server into the OEM character set, and to translate characters coming from the server to ANSI.

The default is False (off, no), which indicates that Database Connectors does not call the translation function, but passes the data as is to the library.

Parent topic: Configuration Variables


A_MSSQL_UNLOCK_ON_EXECUTE

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Setting this variable to True (on, yes) causes all invocations of I$IO using the EXECUTE opcode to unlock all records.The default value is Off (false, no).

Parent topic: Configuration Variables


A_MSSQL_UPDATE_PRIMARY_COLS

When set to TRUE, this variable causes the Database Connectors for MSSQL interface to update all the fields in a table in files that have only primary key fields. Normally, Database Connectors does not add the primary key fields to updated columns, since these can not be modified. Use this variable to change that behavior.

This variable is useful to update multiple files that have only fields that are in the primary key. The default variable value is FALSE.

Parent topic: Configuration Variables


A_MSSQL_USE_DROPDOWN_QUERIES

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Setting A_MSSQL_USE_DROPDOWN_QUERIES to TRUE causes selects sent to the database to be of the drop-down variety, instead of a single large query.

For example, if you have a file with three fields in the primary key, (keyseg1, keyseg2, keyseg3), and your COBOL program does a START, the following query is sent to the database:

select (columns) from (table) where
((keyseg1 = value1 and keyseg2 = value2 and
keyseg3 > value3) or (keyseg1 = value1 and
keyseg2 > value2) or (keyseg1 > value1))
order by keyseg1, keyseg2, keyseg3

If you use drop-down queries, the following collection of queries is sent instead:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 = value2 and keyseg3 >
value3) order by keyseg1, keyseg2, keyseg3

followed by:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 > value2) order by
keyseg1, keyseg2, keyseg3

and:

select (columns) from (table) where (keyseg1
> value1) order by keyseg1, keyseg2, keyseg3

There are advantages and disadvantages to each method. If you use the A4GL_WHERE_CONSTRAINT variable, you should probably set A_MSSQL_USE_DROPDOWN_QUERIES to FALSE, because the WHERE constraint limits the result set sufficiently that the larger query is more efficient. For additional information, see The WHERE Constraint.

If you usually START files and read to the end, you should set A_MSSQL_USE_DROPDOWN_QUERIES to FALSE, because a fewer number of queries need to be sent to the database. On the other hand, if you START files and stop reading after some condition, but have not used the WHERE constraint, you may get more efficient access by setting this variable to TRUE and using the drop-down style of query. In either case, run some tests to see which value makes the most sense for your application.

This variable is accessed only during a positioning operation, so you can set it at different times for different tables.

The default value is FALSE.

Example

A_MSSQL_USE_DROPDOWN_QUERIES TRUE
Parent topic: Configuration Variables
Related reference
A_MSSQL_LIMIT_DROPDOWN
Related information
The WHERE Constraint


A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable

The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction-oriented database but have not explicitly coded transactions into their COBOL application.

The configuration variable A_ODBC_ALTERNATE_COMMIT_LOGIC determines how the interface will respond to the setting of 4GL_COMMIT_COUNT. When A_ODBC_ALTERNATE_COMMIT_LOGIC is set to 0 or FALSE (the default), the value of 4GL_COMMIT_COUNT is checked only at startup. The interface will issue a commit when the criteria set by 4GL_COMMIT_COUNT is met, regardless of the current transaction state.

When A_ODBC_ALTERNATE_COMMIT_LOGIC is set to 1, the value of 4GL_COMMIT_COUNT is checked after each WRITE, REWRITE, DELETE, or UNLOCK operation. A commit is issued, however, only if the run time is not currently in a transaction. For example

4GL_COMMIT_COUNT=1
A_ODBC_ALTERNATE_COMMIT_LOGIC=0

Each WRITE operation is committed to the database immediately. This prevents an application from being able to rollback a WRITE.

See Also: 4GL_COMMIT_COUNT runtime configuration variable

Parent topic: Configuration Variables


A_ODBC_CATALOG configuration variable

This variable indicates the catalog name to be used when Database Connectors searches for objects in the database. Note that not all data sources will support a catalog. Using A_ODBC_CATALOG with other variables, such as USER_PATH and A_ODBC_TABLE_TYPES, can speed up the finding of tables in large databases. It can also prevent an error 9D,14: More than one table with the same name, thereby enabling access to tables with identical names, but with different catalogs.

For example, If USER_PATH and A_ODBC_CATALOG are used, the form of the SQL statement is modified from:

select COL1, ... from TABLENAME ...

to

    SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

See Also: USER_PATH (for DB2) configuration variable, USER_PATH (for Oracle) configuration variable, and A_ODBC_TABLE_TYPES.

Parent topic: Configuration Variables


A_ODBC_COMMIT_ON_BEGIN configuration variable

ODBC has no START TRANSACTION method. Everything since the last COMMIT or ROLLBACK is considered part of the current transaction.

To ensure that the previous transaction has been ended before a new one begins, set A_ODBC_COMMIT_ON_BEGIN to a nonzero value. This causes each COBOL START TRANSACTION to first issue a COMMIT to all applicable ODBC drivers in use. This ensures that the previous transaction has been ended before the new one starts.

If this variable is not set, or is set to 0, a COBOL ROLLBACK may affect file I/O that occurred before the most recent COBOL START TRANSACTION. While the default value is 0 (or OFF, FALSE, or NO), this configuration variable can also take values of ON (TRUE or YES).

Parent topic: Configuration Variables


A_ODBC_DATASOURCE configuration variable

Set A_ODBC_DATASOURCE to the exact name of the data source that you established in the Windows or Linux/UNIX ODBC driver manager. You can set this variable in your COBOL configuration file if you will be using only one data source.

For example, if the data source you want to select is listed in the Windows ODBC driver manager window as MS Access Databases (Access Data (*.mdb)), add the following line to your configuration file:

A_ODBC_DATASOURCE MS Access Databases

If you do not know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "data source name"

There is no default value for this variable. If you do not enter a name, ODBC uses the default ODBC driver.

Parent topic: Configuration Variables


A_ODBC_ERROR_MAP_FILE configuration variable

Because there are so many drivers available for ODBC, you may find that data source error codes don’t necessarily map well to COBOL error codes. To solve this problem, Database Connectors for ODBC allows you to create an error map file to map native database errors to COBOL errors. Create this file using the guidelines described below, and then use the configuration file variable, A_ODBC_ERROR_MAP_FILE, to indicate the name and location of the file you created.

For example, specify this in the rum time configuration file if the file used for mapping is called MAP, and this file is located in the directory C:\ODBC:

A_ODBC_ERROR_MAP_FILE  c:\ODBC\MAP

There is no default value for this variable.

Guidelines for creating a map file

Although you can check your data source documentation for error code information, the easiest way to determine what error codes need to be mapped to more appropriate COBOL codes is through trial and error. As users use Database Connectors for ODBC, they may report receiving error messages that don’t make sense based on their situation. Research these errors and try to determine a more appropriate COBOL error response.

When you create your error map file, use the following guidelines:

  • Begin comment lines with #. Blank lines are also considered comments.
  • Break the rest of the file into sections, with each section header comprising all the information enclosed in brackets from the data source error function.

    For example, if the data source returns this error:

    OdbcOneInfo: State: S1000, Native Error: -346
[Visigenic][ODBC Informix 5 Driver][Informix]Could not update a row in the table.

    make your section header:

    [Visigenic][ODBC Informix 5 Driver][Informix]
  • Include two fields in each line in the section: the internal error number, and a mapping string.

    Using the same example, if you wanted to map the Visigenic Informix driver error, -346 Could not update a row in the table to the COBOL error, Not found, you would include this line in the section:

    -346 E_NOT_FOUND

    Other Visigenic Informix error maps would follow in the same section. If you use other drivers, you could use multiple sections.

    The valid values for the second field are as follows:

    • E_SYS_ERR
    • E_PARAM_ERR
    • E_TOO_MANY_FILES
    • E_MODE_CLASH
    • E_REC_LOCKED
    • E_BROKEN
    • E_DUPLICATE
    • E_NOT_FOUND
    • E_UNDEF_RECORD
    • E_DISK_FULL
    • E_FILE_LOCKED
    • E_REC_CHANGED
    • E_MISMATCH
    • E_NO_MEMORY
    • E_MISSING_FILE
    • E_PERMISSION
    • E_NO_SUPPORT
    • E_NO_LOCKS
Parent topic: Configuration Variables


A_ODBC_ISOLATION_LEVEL configuration variable

Use the A_ODBC_ISOLATION_LEVEL configuration variable to set the isolation level. The default ordering of isolation levels is:

  • SQL_TXN_READ_COMMITTED
  • SQL_TXN_READ_UNCOMMITTED
  • SQL_TXN_REPEATABLE_READ
  • SQL_TXN_SERIALIZABLE

You can change the isolation level by setting the configuration variable A_ODBC_ISOLATION_LEVEL to an integer in the configuration file. The settings are:

Isolation level | Setting in configuration file
SQL_TXN_READ_UNCOMMITTED | 1
SQL_TXN_READ_COMMITTED | 2
SQL_TXN_REPEATABLE_READ | 3
SQL_TXN_SERIALIZABLE | 4

For example, to set the isolation level to SQL_TXN_READ_COMMITTED, add the following entry to the configuration file:

A_ODBC_ISOLATION_LEVEL 2

If the user-set isolation level is not supported by the driver, the default method of selecting a level is used.

Parent topic: Configuration Variables


A_ODBC_LOCK_METHOD configuration variable

Use this variable to specify the locking method that the Database Connectors product should use when accessing your data source. Possible values are:

  • none
  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

For example:

A_ODBC_LOCK_METHOD UPDATECOLUMN

The default value is none, meaning that the Database Connectors product will do nothing special to lock your data. This does not necessarily mean that your data won’t be locked. Locking depends mainly on your data source and driver. No value simply tells Database Connectors for ODBC not to perform any locking functions.

Note: Setting this variable may affect certain ODBC drivers. Locking depends mainly on the data source and the driver. You can use this variable to attempt to induce row locking. If none of the settings cause any rows to be locked, or if the machine stops responding, please report this behavior to Technical Services.
Parent topic: Configuration Variables


A_ODBC_LOGIN configuration variable

A_ODBC_LOGIN indicates the user name under which you want to connect to the database system. Not all data sources require a user login name. Those that do may have case requirements. Check your data source documentation to determine if login is case-sensitive.

Example

To connect to the database with the user name MYNAME, specify one of these in the run time configuration file.

A_ODBC_LOGIN MYNAME

or

A_ODBC_LOGIN myname

There is no default value for this variable. If no login is specified, none is used.

See also: A_ODBC_PASSWD

Parent topic: Configuration Variables


A_ODBC_NO_NULL_COLUMNS

When set to TRUE, ON or YES, the interface does not insert NULL into the database. While the default value is OFF (FALSE or NO).

Parent topic: Configuration Variables


A_ODBC_PASSWD

The variable A_ODBC_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_ODBC_LOGIN. Not all data sources require a password. Those that do may have case requirements. Check your data source documentation to determine if password is case-sensitive.

For example, specify the following in the run time configuration file if the account with the user name in A_ODBC_LOGIN has the associated password CW021535:

A_ODBC_PASSWD  CW021535

For better security, you can accept a password from the user during program execution; set the A_ODBC_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_ODBC_PASSWD" TO RESPONSE.
Note:

If the user has been set up without a password, this variable need not be set. There is no default value for this variable. If no password is specified, none is used.

Parent topic: Configuration Variables


A_ODBC_PRINT_LOG configuration variable

This variable is used for debugging only, and is best used under the direction of a Micro Focus SupportLine representative.

See Contacting Micro Focus for information on contacting a Technical Services representative.

Parent topic: Configuration Variables


A_ODBC_QUOTE_IDENTIFIERS configuration variable

A_ODBC_QUOTE_IDENTIFIERS tells the Database Connectors product whether to test for the IDENTIFIER-QUOTE-CHAR, and to use it if it is found. If this variable is nonzero, and if the driver returns information about the IDENTIFIER-QUOTE-CHAR, all identifiers sent in SQL to the driver will be quoted. This is useful for using Microsoft Excel, for example, if the spreadsheet has column names with quotes or other strange characters. Notice that some drivers mistakenly report that they can handle quoted identifiers, which is why this variable is needed.

If you set this variable to a nonzero value, and start getting errors table not found or column not found, this variable should not be used when communicating with that driver.

The default value is 0 (or OFF, FALSE, or NO). This configuration variable can also take values of ON, TRUE, or YES.

Note:

This variable is useful with Oracle, this variable is not recommended.

See Mixed-case SQL Identifiers for information on using mixed-cased identifiers.

Parent topic: Configuration Variables


A_ODBC_STRICT_EQUAL configuration variable

When Database Connectors for ODBC executes a START … KEY EQUAL keyval, the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval. When fetching the data, Database Connectors eventually detects that there is no more data. If A_ODBC_STRICT_EQUAL is set to TRUE at the time the START is executed, the interface returns the error END OF FILE (error 10) at this point. If A_ODBC_STRICT_EQUAL is set to FALSE (the default), Database Connectors for ODBC then generates a new SELECT statement to continue reading records until the end of the file rather than the subset of records represented by keyval, and these records may be discarded by the program. (Note that this is program-dependent behavior.) Setting A_ODBC_STRICT_EQUAL to TRUE causes the interface to stop reading records earlier, which can make SELECT statements generated by Database Connectors for ODBC more efficient.

A_ODBC_STRICT_EQUAL has these conditions:

  • A_ODBC_STRICT_EQUAL must be set to TRUE when the START is executed.
  • The START must be a KEY EQUAL start.
  • There must be no COMMITs between the START and the end of the file. Because most ODBC drivers close all cursors on COMMIT and ROLLBACK (according to the ANSI 92 SQL standard), the interface must regenerate a SELECT the first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK. For most drivers, this means that the 4GL_COMMIT_COUNT configuration variable should be set to -”, so that no COMMITs are issued by Database Connectors for ODBC. See 4GL_COMMIT_COUNT for additional information.
  • A_ODBC_STRICT_EQUAL is most useful with alternate keys that allow duplicates.
Note:

This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT, but using A_ODBC_STRICT_EQUAL requires less programming.

The default value is FALSE (or OFF, NO, or 0). This configuration variable can also take the value TRUE, ON, YES, or 1.

Parent topic: Configuration Variables


A_ODBC_TABLE_TYPES configuration variable

This variable is used to specify a table type (TABLE, VIEW, and so forth) that should be looked for when selecting a database table. Using A_ODBC_TABLE_TYPES with other variables, such as USER_PATH and A_ODBC_CATALOG, can speed up the finding of tables in large databases.

This information is passed to the API function call SQLTables() as the TableType parameter. Please refer to your driver’s documentation for supported types.

for example:

A_ODBC_TABLE_TYPES  TABLE,VIEW

See also: USER_PATH configuration variable, A_ODBC_CATALOG configuration variable

Parent topic: Configuration Variables


A_ODBC_UNSIGNED_TINYINT configuration variable

Some ODBC drivers may assign the TINYINT data type, a signed 1-byte variable that can store values from -128 to 127, to an internal unsigned type that can store values from 0 to 255. To determine if your ODBC driver does this, set a PIC s99 variable to a negative value and then write a record. If a value out of range message is returned, set A_ODBC_UNSIGNED_TINYINT to a nonzero value. As a result, PIC s99 variables are stored in a larger type (usually INT) that allows negative values.

The default value is 0 (OFF, FALSE, or NO). This configuration variable can also take values of ON, TRUE, or YES.

Parent topic: Configuration Variables


A_ODBC_USE_CATALOG configuration variable

Not all data sources will support a catalog, or the data sources may return a catalog name that is not useful. For example, Microsoft Access returns the full path to the database, which is not needed since this information is detailed in the datasource.

The default behavior of the runtime is to not use the catalog in the actual SQL queries. This configuration variable enables you to modify this behavior. The default value is FALSE, which causes the catalog portion of the table name to be treated as blank in SQL queries. Setting this variable to TRUE causes the value of the catalog returned by SQLTables ODBC function to be used in subsequent SQL queries.

See also: USER_PATH (for DB2) configuration variable, USER_PATH (for Oracle) configuration variable, and A_ODBC_CATALOG

Parent topic: Configuration Variables


A_ODBC_USE_CHAR_FOR_BINARY configuration variable

Some data sources have restrictions on the number of binary large objects (BLOBs) that can be placed into a single table. If your data source has such restrictions, specify A_ODBC_USE_CHAR_FOR_BINARY in the configuration file. The possible values for this variable are:

  • 0 = use BINARY type
  • 1 = use CHAR type

If A_ODBC_USE_CHAR_FOR_BINARY is set to a nonzero value, you can store data that uses the BINARY directive as hexadecimal encoded CHAR types. This allows you to work around your data source restriction. The default value is 0 (or OFF, FALSE, or NO), This configuration variable can also take values of ON, TRUE, or YES.

For example:

A_ODBC_USE_CHAR_FOR_BINARY 1
Parent topic: Configuration Variables


A_ODBC_USE_SPACE_IN_DATES configuration variable

Some ODBC drivers require spaces when sending dates or time stamps to the data source. For data sources that require spaces between the d and the quote ('), set the configuration variable A_ODBC_USE_SPACE_IN_DATES.

For example:

Set MYDATE={d '1999-3-20'}

(note that there is a space between d and ' )

Setting the A_ODBC_USE_SPACE_IN_DATES configuration variable to “1” causes the Database Connectors for ODBC product to use syntax as above, instead of:

Set MYDATE={d'1999-3-20'}

(note that there is not a space between d and ' )

Keep in mind that it is possible that all data sources may allow a space between the d and the ', and that it is always safe to set this variable.

The default value is 0 (or OFF, FALSE, or NO). This configuration variable can also take values of 1 (ON, TRUE, or YES).

For example:

A_ODBC_USE_SPACE_IN_DATES 1
Parent topic: Configuration Variables


A_ODBC_USE_SQLCOLUMNS configuration variable

For some large databases, the API function SQLColumns(), which is called to get a description of the columns in a table, sometimes takes a long time to execute. If you are experiencing such problems, you can use the API function call SQLDescribeCol() instead, which can improve performance for large databases.

To turn on this new functionality, set the A_ODBC_USE_SQLCOLUMNS configuration variable to FALSE.

The default value of this variable is TRUE, which means the interface will use the SQLColumns() API function.

Parent topic: Configuration Variables


A_ODBC_USE_SQLTABLES configuration variable

For some large databases, the API function SQLTables(), which is called to get a list of the tables and information about them, sometimes takes a long time to execute. If you are experiencing such problems, you can instruct the interface to build a test SQL query and use the API function call SQLNumResultCols() to determine if the table exists. This may improve performance for large databases.

To turn on this new functionality, set the A_ODBC_USE_SQLTABLES configuration variable to FALSE.

The default value of this variable is TRUE, which means the interface will use the SQLTables() API function.

Parent topic: Configuration Variables


A_ORA_DATABASE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

A_ORA_DATABASE specifies the name of a network service that you have set up to refer to a database using an Oracle tool such as "Net Configuration Assistant," or by manually editing tnsnames.ora.

Parent topic: Configuration Variables
Related information
ORA_LOGIN configuration variable
ORA_PASSWD configuration variable


A_ORA_HINTS configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable enables the Oracle Hints feature. The default value is 1 (on, true, yes). To turn off this feature, set it to 0 (off, false, no).

Oracle Hints can improve database performance considerably in some situations, by "strongly suggesting" to the Oracle query optimizer that it use a given index to process a query.

Note that keys must use your COBOL development system's naming convention for naming indexes in the database to use this function. For example, the primary key on the file ftest would be named "iftest_0".

Parent topic: Configuration Variables


A_ORA_KEEP_START_CURSOR configuration variable

When a COBOL application performs a start operation, Database Connectors builds a sequence of one or more SQL queries to satisfy the requirements of the start operation. When a result set is found that matches the criteria of the start operation, that key value is saved for use on a subsequent READ NEXT/PREVIOUS operation. The cursor used to locate the target key value is not left open in order to maximize concurrency. When a READ NEXT/PREVIOUS operation is subsequently performed, a new query is generated. This could result in a sequence of queries such as the following.

For the START operation:

WHERE ( partial_key1_seg1 = :w0 AND partial_key1_seg2 = :w1
 ) ORDER BY
    partial_key1_seg1 ASC, partial_key1_seg2 ASC,
partial_key1_seg3 ASC
For the READ NEXT operation:

WHERE ( partial_key1_seg1 = :w0 AND partial_key1_seg2 >= :w1
) ORDER BY
    partial_key1_seg1 ASC, partial_key1_seg2 ASC,
partial_key1_seg3 ASC

The configuration variable A_ORA_KEEP_START_CURSOR was created for this purpose.

Settings

FALSE | The current default. The interface functions as in previous versions.
TRUE | The cursor used for the start operation stays in an open state for use by subsequent operations. Setting this variable to TRUE eliminates the generation of the second SQL query for the READ operation.
Parent topic: Configuration Variables


A_ORA_LIMIT_DROPDOWN configuration variable

When a sequence of START and READ NEXT/PREVIOUS operations are performed by an application, Database Connectors generates a sequence of queries to return the set of records matching the application's request. To improve performance, the interface generates a sequence of DROP DOWN queries based upon the key of reference's key segments going from the most specific subset using the most number of segments to the most general using the least number of segments.

For example if a key is described by:

03 MY-ALTKEY.
   05 MY-ALTKEY-SEG1        PIC X(2).
   05 MY-ALTKEY-SEG2        PIC X(2).
   05 MY-ALTKEY-SEG3        PIC X(2).

then a START followed by a sequence of READ NEXT operations might generate the selection criteria of:

WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 = :w1 AND
MY-ALTKEY-SEG3 >= :w3
WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 > :w1
WHERE MY-ALTKEY-SEG1 > :w0

This can improve performance in that the target for each query is kept to a minimal size. If a set of records is not required, the database does not need to spend the time building the working set. When a DROP DOWN does occur however, the subsequent working set can require a large amount of time to process, because it may be an order of magnitude greater number of records. Normally there is not a way for a COBOL application to instruct the interface to stop processing when it has finished with the records based on a given key segment.

The A_ORA_LIMIT_DROPDOWN variable provides this instruction. It allows an application to direct the interface not to perform DROP DOWN query generation and instead return end of file when the records matching the current query have been exhausted.

Settings

OFF | The current default. The interface will perform DROP DOWN queries.
PARTIAL | If the record positioning was performed by a START with a SIZE clause, such that the initial positioning was performed using fewer than the total number of columns in the key, the process will cease after all records matching the START columns have been exhausted.
FULL | If the record positioning was performed by a START without a SIZE clause, the process will cease after all records matching the START columns have been exhausted.
ALL | Regardless of what form of START was used for the initial positioning, the process will cease after all records matching the START columns have been exhausted.

This variable is performed at the time of each start, so the application may change its value.

Parent topic: Configuration Variables


A_ORA_MAX_FILE_CURSORS configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable allows you to set the maximum number of cursors that the run time is allowed to have per file.

The default value for A_ORA_MAX_FILE_CURSORS is 0, meaning that the run time system uses all of the cursors that it can. Because each file must have access to at least two cursors, set this variable to a value greater than 2 if you want to specify a particular value. If all the allotted cursors for a file have been used, the least recently used cursor for that file is freed.

Note that this variable is read only at startup time, and should, therefore, be set in the ACUFH configuration file.

Parent topic: Configuration Variables


A_ORA_NLS_SORT configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable forces the sort order of returned records to be in a binary order. Set A_ORA_NLS_SORT to 1 to turn off the default binary order and use the native language sort (NLS) instead. The default is 0, which means that the sort order is not NLS order and will be binary.

This variable must be set before the first database file is accessed.

Parent topic: Configuration Variables


A_ORA_WAIT_LOCK configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This configuration variable determines the type of Oracle locks used: wait or nowait locks. The default is FALSE, nowait locks. This variable is read at file open time for each file.

Parent topic: Configuration Variables


A_ORACLE_ERROR_FILE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors. By adding the name of the file that contains the actual error mapping to A_ORACLE_ERROR_FILE, database-specific errors are mapped to COBOL errors.

Note: Some messages related to COBOL I/O cannot be supplemented.

Example

A sample syntax for this variable would be:

A_ORACLE_ERROR_FILE=ORCLerrs

where ORCLerrs is a file of a specified format containing a mapping of database-specific errors to COBOL errors. One such entry might be:

1 DUPLICATE_RECORD
Parent topic: Configuration Variables


COMMIT_COUNT configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The value of COMMIT_COUNT indicates the conditions under which you want Database Connectors to issue an automatic COMMIT_WORK operation.

COMMIT_COUNT <value>

Valid values are:

0 | A commit is issued when no locks are held, either because all files that had locked records have been closed, or because a COBOL COMMIT verb has been issued. This is the default value
"n" | A commit is issued after n operations. WRITE, REWRITE, and DELETE count towards n; READ, START, and READ NEXT do not
-1

No commit is issued by Database Connectors when COMMIT_COUNT is set to -1; the alternative when this is set:

  • Call your Oracle query tool with COMMIT WORK or ROLLBACK WORK

A COMMIT WORK, however, is issued on exit from the run time system (for example, on execution of a STOP RUN)

For information about supported features, see Supported Features for Oracle Information.

Parent topic: Configuration Variables
Related information
Supported Features


FILE_TRACE configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This variable allows you to start file tracing without opening the debugger. Set this variable to a non-zero value to save information about all file OPENs, READs, and WRITES in the error file. The default is 0.

Parent topic: Configuration Variables


FILE TRACE FLUSH

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Set this variable to 1 (on, true, yes) to flush the error file after every WRITE statement.

Parent topic: Configuration Variables


ORA_LOGIN configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

ORA_LOGIN indicates the user name under which you want to connect to the database system.

Example

To connect to the database with the user name MYNAME, you would specify:

ORA_LOGIN  MYNAME

in the Database Connectors.

For information on user accounts, see Setting up a User Account.

Parent topic: Configuration Variables
Related information
ORA_PASSWD configuration variable
A_ORA_DATABASE configuration variable


ORA_PASSWD configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

ORA_PASSWD should be set to the password assigned to the database account associated with the user name specified by ORA_LOGIN.

Example

If the account with the user name has the associated password CW021535, you would specify:

ORA_PASSWD  CW021535

in the ACUFH configuration file or the environment.

For a full login from a client to a remote server, you could have either of the following two settings:

ORA_LOGIN username
ORA_PASSWD userpass
A_ORA_DATABASE remotesrv

or

ORA_LOGIN username@remotesrv
ORA_PASSWD userpass

In this example, remotesrv is the net service name you have set up, as defined in A_ORA_DATABASE configuration variable.

Parent topic: Configuration Variables
Related information
ORA_LOGIN configuration variable


USER_PATH (for Oracle) configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

USER_PATH indicates the user name or names to be used when Database Connectors searches for files. The order of the names is significant. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user on the system, or a period ("."), which indicates the files owned by yourself.

The type of OPEN being issued for the file determines the effects of this setting.

Examples

If an OPEN INPUT or OPEN I/O is issued, and USER_PATH is defined in the ACUFH configuration file, Database Connectors searches for a user of the named file in the following sequence of locations:

  1. The list of users in USER_PATH
  2. The public synonyms

The first valid file is opened.

If USER_PATH is defined and the current user is the owner of the file, the current user must be included as one of the users (as indicated by a "."). If this is not the case, even though the current user has created the table, it is not be found and a file error "35" appears. This circumstance can occur if the file was created with the OPEN OUTPUT phrase and "." is not an element in USER_PATH. When the table is created, the current user is the owner of that table. When the run time system attempts to open the table, the system does not look for tables owned by the current user unless USER_PATH is not set, or unless "." is part of the setting.

If an OPEN INPUT or OPEN I/O is issued, and no USER_PATH variable is in the configuration file, Database Connectors searches for a user of the named file in the following sequence of locations:

  1. The user named for login (ORA_LOGIN or OPS$username)
  2. Public synonyms

Database Connectors opens the first file that has a valid combination of user and file name.

If an OPEN OUTPUT is issued (whether USER_PATH is present or not), a new table is created with the owner being:

  • The name specified in ORA_LOGIN
  • The name constructed by automatic login

For information on automatic login, see Setting Up a User Account, and for information on the search path, see Setting Up the Search Path.

Parent topic: Configuration Variables


USER_PATH (for DB2) configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

USER_PATH indicates the user name or names (schemas) to be used when Database Connectors searches for files. The order of the names is significant. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user (schema) on the system, or a period (“.”), which indicates the files owned by yourself.

The type of OPEN being issued for the file determines the effects of this setting.

Examples

If an OPEN INPUT or OPEN I/O is issued, and a USER_PATH variable is defined in the ACUFH configuration file, Database Connectors searches for a user of the named file in the list of users in USER_PATH. The first valid file is opened.

If USER_PATH is defined and the current user is the owner of the file, the current user must be included as one of the users, as indicated by a “.” or the setting of your login schema (A_DB2_LOGIN) in the USER_PATH. If this is not the case, even though the current user has created the table, it is not found and a file error 35 occurs. This circumstance can occur if the file is created with the OPEN OUTPUT phrase, and “.” is not an element in USER_PATH. When the table is created, the current user is the owner of that table. When the run time attempts to open the table, it does not look for tables owned by the current user unless USER_PATH is not set, or unless “.” or the user's current schema is part of the USER_PATH setting.

If an OPEN INPUT or OPEN I/O is issued, and no USER_PATH variable is in the ACUFH configuration file, Database Connectors searches for a user of the named file in the user named for login A_DB2_LOGIN). Database Connectors opens the first file that has a valid combination of user and file name.

If an OPEN OUTPUT is issued (whether USER_PATH is present or not), a new table is created with the owner being the name specified in A_DB2_LOGIN.

Using USER_PATH with other variables such as A_DB2_CATALOG can speed up the finding of tables in large databases. It can also prevent an error 14: More than one table with the same name, thereby enabling access to tables with identical names, but with different schemas.

For example, If using both USER_PATH and A_DB2_CATALOG , the form of the SQL statement changes from:

select COL1, ... from TABLENAME ...

to:

SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

Parent topic: Configuration Variables
Related information
A_DB2_LOGIN configuration variable
A_DB2_CATALOG configuration variable


XFD_DIRECTORY configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

XFD_DIRECTORY tells the run time system the name of the directory that contains the XFD files built by the compiler. The default value is the current directory.

Example

To tell the run time system that the XFDs are stored in the directory /usr/inventory/dictionaries, enter the following:

xfd–directory   /usr/inventory/dictionaries
Note: This variable is ignored if you have specified a search path for XFD files using the XFD_PREFIX configuration variable. XFD_PREFIX extends the functionality of XFD_DIRECTORY.

For information about the directive that tells the compiler where to put the XFDs, see the CREATEXFD directive. Unless you have moved the XFD files, you should use the same value in XFD_PREFIX (or for XFD_DIRECTORY) that you used with the CREATEXFD directive.

Parent topic: Configuration Variables


XFD_MAP configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

XFD_MAP tells the run time system to associate certain filenames with a particular XFD. This enables you to use one XFD for many different files. You can use XFD_MAP to add or replace the existing value, depending on the setting of the XFD_MAPS_RESETS configuration variable.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...

where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:

* | matches any number of characters
? | matches a single occurrence of any character

For example:

CUST???? | matches CUST0001 and CUSTOMER; does not match CUST001 or CUST00001
CUST* | matches all of the above
CUST*1 | matches CUST001 and CUST0001 and CUST00001; does not match CUSTOMER
*OMER | matches CUSTOMER; does not match CUST001 or CUST0001

Note that XFD_MAP cannot be read from the ACCEPT FROM ENVIRONMENT statement.

Parent topic: Configuration Variables
Related information
XFD_MAP_RESETS configuration variable


XFD_MAP_RESETS configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This ACUFH configuration file variable determines whether setting the XFD_MAP adds to or replaces the existing value.

Valid values are:

Value | Effect when setting the ACUFH configuration file variable
"0" (off, false, no) | Adds new value patterns to the end of the existing value
"1" (on, true, yes) the default | Replaces the existing value with a new value

This variable may be useful if you need to include multiple XFD_MAP lines in an ACUFH configuration file and want to avoid setting and resetting the variable. When multiple lines exist, all patterns are used in the order they are listed.

Parent topic: Configuration Variables
Related information
XFD_MAP configuration variable


XFD_PREFIX configuration variable

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When this ACUFH configuration file variable is assigned a value, it is used to locate the XFD file, and the variable XFD_DIRECTORY is ignored. XFD_PREFIX enables you to define a specific series of directories to search for XFD files, rather than indicating only one. The run time system searches each directory in the order specified until an XFD file matching the name of the desired file is found and then assumes that is the correct file.

Therefore, when using the XFD_PREFIX variable, be aware that the run time system:

  • Searches each named directory and not its subdirectories
  • Stops searching once a matching file name is found, even if other files of the same name are located in a different directory later in the series
  • Does not validate that the file specifications (such as key or record size parameters) of the XFD file match those in the COBOL program. Be sure the correct file you want to use is in the path specified

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. You separate entries using a semi-colon (;). For example:

XFD_PREFIX C:\"Sales Data";C:\Customers

You can specify up to 4096 characters for this variable.

Note: The default for XFD_PREFIX is empty. If this variable is set to any other value, the XFD_DIRECTORY (in which you specify only one directory) is ignored.
Parent topic: Configuration Variables
Related information
XFD_DIRECTORY configuration variable


Database Connectors Error Messages

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

All non-standard file status errors returned by Database Connectors are of the form 9/83, with a secondary error that can be determined by examining the external variable f-int-errno, or by calling C$RERR. The secondary errors that can be returned include the following.

  • Run Time - File Status Errors
  • Compiler Errors
Parent topic: Database Connectors Reference
Related information
Data Related


Run Time - File Status Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
  • 01 Read error on dictionary file
  • 02 Corrupt dictionary file
  • 04 Open error
  • 04 Too many fields in the key
  • 05 Too many fields in the key (more than 16 for Oracle)
  • 12 DB2 library function returned an unexpected error
  • 13 Illegal size or type of data for variable xxx
  • 14 More than one table with the same name
  • 1001 Invalid Cursor
  • 22007 Invalid Character value for Cast Specification
Parent topic: Database Connectors Error Messages


01 Read error on dictionary file

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

An error occurred while reading the XFD file; this probably means the XFD is corrupt.

Resolution:

Recompile with the CREATEXFD directive to re-create the XFD.

Parent topic: Run Time - File Status Errors
Related information
CREATEXFD directive


02 Corrupt dictionary file

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The XFD file for one of your COBOL files is corrupt and cannot be read.

Resolution:

Recompile with the CREATEXFD directive to re-create the XFD.

Parent topic: Run Time - File Status Errors
Related information
CREATEXFD directive


04 Open error

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

There was an error attempting to open the XFD file.

Resolution:

Recompile with the CREATEXFD directive to re-create the XFD.

Parent topic: Run Time - File Status Errors
Related information
CREATEXFD directive


04 Too many fields in the key

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

There are more than 16 fields in a key.

Resolution:

Check your key definitions and restructure the key that is illegal, then recompile with the CREATEXFD directive.

Parent topic: Run Time - File Status Errors
Related information
CREATEXFD directive


05 Too many fields in the key (more than 16 for Oracle)

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

There are more than 16 fields in a key.

Resolution:

Check your key definitions and restructure the key that is illegal, then recompile with the CREATEXFD directive.

Parent topic: Run Time - File Status Errors
Related information
CREATEXFD directive


12 DB2 library function returned an unexpected error

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

One of the DB2 library functions returned an error that was not expected.

Parent topic: Run Time - File Status Errors


13 Illegal size or type of data for variable xxx

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

An elementary data item in your FD was larger than 255 bytes, or there is no DB2 type that matches the current data type.

Parent topic: Run Time - File Status Errors


14 More than one table with the same name

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

When tables were listed, more than one table was found with the same name.

Resolution:

Consider whether or not setting the USER_PATH ACUFH configuration variable resolves the issue. This variable enables tables with identical names, but with different ownership (located in a different schema) to be found and accessed.

Parent topic: Run Time - File Status Errors
Related information
USER_PATH configuration variable


1001 Invalid Cursor

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The prepare portion is aged out of cache.

Resolution:

Re-enter the code while invalidating the prepare portion.

Parent topic: Run Time - File Status Errors


22007 Invalid Character value for Cast Specification

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The error sub-code 22007 indicates that an attempt was made to write non-numeric data into a numeric field (database column).
Parent topic: Run Time - File Status Errors


Compiler Errors

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
  • Bad picture for DATE: keyname
    The PICTURE must be six or eight bytes in length, either alphanumeric or numeric with no sign.
  • Data missing from key segment keyname
    This error occurs when some part of the named key cannot be placed in the XFD; the XFD cannot be generated in this situation.
  • Directive word too long: keyname
    With one exception, the words contained in an XFD directive, including field names, cannot exceed 30 characters. The value of a WHEN XFD directive may consist of up to 50 characters.
  • Field xxx causes duplicate database data
  • GROUP expected after USE
    The USE GROUP XFD directive must include both words.
  • Missing '=' in XFD directive
    The NAME XFD directive requires an equal ("=") sign. The WHEN XFD directive requires a comparison operator.
  • Missing field name after WHEN
    A valid field name, or the word "OTHER", must be specified with the WHEN XFD directive.
  • Value should be a literal: xxx
    This error occurs when the item to the right of an "=" should be a literal, and it isn't. The xxx in the message is the value found. A literal is either a quoted string or a numeric integer.
  • Value should be a name: xxx
    This error occurs when the item to the right of an "=" should be a name, and it isn't. For example, it would be an error to use a quoted string with the NAME XFD directive: $XFD NAME=some text. The xxx in the message is the value found.
  • Value should be numeric: xxx
    This error occurs when the item to the right of an "=" should be numeric and it isn't. The xxx in the message is the value found.
  • Variable file name requires FILE directive
    This message occurs when the Compiler cannot assign a name to the .xfd file, because the ASSIGN phrase for the file names a variable file name.
  • WHEN variable xxx not found in record
    This happens if you have a WHEN XFD directive that mentions a variable that doesn't exist in the record.
  • xxx not unique in first 30 characters
  • xxx: unknown XFD directive
    The Compiler did not recognize the XFD directive you used. The xxx is the XFD directive found.
Parent topic: Database Connectors Error Messages


Bad picture for DATE: keyname

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The PICTURE must be six or eight bytes in length, either alphanumeric or numeric with no sign.
Parent topic: Compiler Errors


Data missing from key segment keyname

This error occurs when some part of the named key cannot be placed in the XFD; the XFD cannot be generated in this situation.
Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This usually occurs because of filler. For example:

01  my-record.
    03  my-key.
        05  filler            pic xx.
        05  field-1           pic xx.

If my-key is declared as a record key, this error occurs because the area of the key described by filler is not included in the XFD.

Resolution:

To correct this error, ensure that every character that is part of the key is included in some field that is part of the XFD. Use an XFD to give a field name to each filler, to ensure that fillers are included:

 01  my-record.
     03  my-key.
$xfd name=myfiller
         05   filler            pic xx.
         05   field-1           pic xx.
Parent topic: Compiler Errors


Directive word too long: keyname

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
With one exception, the words contained in an XFD directive, including field names, cannot exceed 30 characters. The value of a WHEN XFD directive may consist of up to 50 characters.
Parent topic: Compiler Errors
Related information
WHEN directive


Field xxx causes duplicate database data

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The warning informs you of a special database situation that is not advisable. The XFD builds and the interface operates correctly.

This warning means that your record definition should be restructured. Your current definition is set up in such a way that:

  1. You have overlapping key fields, and
  2. Both keys must be represented in the database as separate items.

Database Connectors handles this situation by keeping the overlapping keys updated simultaneously, so that they always have the same value. However, the warning alerts you that you have the same data represented twice in the database. This is dangerous, because someone at the site might access the database via SQL and accidentally change only one of the keys.

Here's an example of the problem and a description of how to correct it (the example assumes that both key-1and key-2 have been declared as keys):

01  order–record.
    03  key–1.
        05  field–a                  pic x(5).
        05  field–b                  pic 9(5).
        05  key–2
            redefines field–b        pic x(3).

This example generates the warning message.

Because key-2 is a key, it must also be represented in the database. It doesn't correspond exactly to any other data field, so it must be entered as a separate column in the database.

In the COBOL view of the file, key-1and key-2 overlap. But the requirements of database storage force the same data (known to COBOL as field-b) to be physically represented twice in the database. Any updates to the data from any COBOL program correctly updates both columns. Updates from outside of this COBOL program carry no such guarantee.

Resolution

In this example, you can correct the situation by breaking field-b into two columns, so that key-2 corresponds exactly to another data field:

01  order–record.
    03  key–1.
        05  field–a                        pic x(5).
        05  field–b.
            07  field-b1                   pic x(3).
            07  field-b2                   pic 9(2).
        05  key–2
            redefines field–b              pic x(3).
Parent topic: Compiler Errors
Related information
CREATEXFD directive


GROUP expected after USE

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The USE GROUP XFD directive must include both words.
Parent topic: Compiler Errors
Related information
USE GROUP directive


Missing '=' in XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The NAME XFD directive requires an equal ("=") sign. The WHEN XFD directive requires a comparison operator.
Parent topic: Compiler Errors
Related information
NAME directive
WHEN directive


Missing field name after WHEN

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
A valid field name, or the word "OTHER", must be specified with the WHEN XFD directive.
Parent topic: Compiler Errors
Related information
WHEN directive


Value should be a literal: xxx

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This error occurs when the item to the right of an "=" should be a literal, and it isn't. The xxx in the message is the value found. A literal is either a quoted string or a numeric integer.
Parent topic: Compiler Errors


Value should be a name: xxx

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This error occurs when the item to the right of an "=" should be a name, and it isn't. For example, it would be an error to use a quoted string with the NAME XFD directive: $XFD NAME=some text. The xxx in the message is the value found.
Parent topic: Compiler Errors


Value should be numeric: xxx

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This error occurs when the item to the right of an "=" should be numeric and it isn't. The xxx in the message is the value found.
Parent topic: Compiler Errors


Variable file name requires FILE directive

This message occurs when the Compiler cannot assign a name to the .xfd file, because the ASSIGN phrase for the file names a variable file name.
Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Resolution:

In this case, you must use a FILE XDF directive to name the .xfd file.

Parent topic: Compiler Errors
Related information
FILE directive


WHEN variable xxx not found in record

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
This happens if you have a WHEN XFD directive that mentions a variable that doesn't exist in the record.
Parent topic: Compiler Errors
Related information
WHEN directive


xxx not unique in first 30 characters

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This message occurs if a field name is not unique within the first 30 characters. The xxx is the name found.

Resolution:

You can either change the field name or apply the NAME XFD directive.

Parent topic: Compiler Errors
Related information
NAME XFD directive


xxx: unknown XFD directive

The Compiler did not recognize the XFD directive you used. The xxx is the XFD directive found.
Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Resolution:

Check for a typographical error.

Parent topic: Compiler Errors


XFD Directives

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
The following are XFD directives for Database Connectors.

XFD directives provide extended control over how the database table is built. Among other things, they let you:

  • Specify a column name to be used in the database table, in place of a COBOL field name.
  • Map elementary items of a group item together into a single column.
  • Cause numeric COBOL data to be treated as a text string in the database.
  • Cause the fields from a specific record in a file to appear in the database table (rather than just the fields from the largest record).
  • Assign a column the DATE type, providing the built-in functionality that dates have in the RDBMS.
  • Give a name to the XFD file itself.

XFD directives are always placed within a COBOL FD. They do not affect Procedure Division I/O statements, and they do not change your COBOL fields in any way. Rather, they guide the building of the XFDs, giving you control over the way COBOL data maps to database fields.

  • ALPHA XFD directive
  • BINARY XFD directive
  • COBOL-TRIGGER XFD directive
  • IDENTITY-COLUMN XFD directive
  • COMMENT XFD directive
  • DATE XFD directive
  • FILE XFD directive
  • NAME XFD directive
  • NULL XFD Directive
  • NUMERIC XFD directive
  • SECONDARY_TABLE XFD directive
  • USE GROUP XFD directive
  • VAR_LENGTH XFD directive
  • WHEN XFD directive
  • XSL XFD directive
Parent topic: Database Connectors Reference


ALPHA XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The ALPHA XFD directive allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program.

Syntax

$XFD ALPHA

This is especially useful when you have numeric keys in which you occasionally store non-numeric data, such as LOW-VALUES or special codes. In this situation, treating the field as alphanumeric allows you to move any kind of data to it.

Example

Suppose you have specified KEY IS code-key. Then assume the following record definition:

01  code-record.
    03  code-key.
        05  code-num      pic 9(5).

In the database, group items are disregarded, so CODE-NUM is the actual key field. Suppose you needed to move a non-numeric value to the key:

MOVE "C0531" TO CODE-KEY.
WRITE CODE-RECORD.

In this case the results are not well-defined because a non-numeric value has been moved into a numeric field. The database might very well reject the record.

One way to solve this problem is to use the ALPHA XFD directive. This causes the corresponding database field to accept alphanumeric data:

 01  code-record.
     03  code-key.
$XFD ALPHA
         05  code-num      pic 9(5).

As an alternative, you could specify the USE GROUP XFD directive on the line before code-key. The USE GROUP XFD directive implies that the field is alphanumeric.

Parent topic: XFD Directives
Related information
USE GROUP directive


BINARY XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The BINARY XFD directive is used to specify that the data in the field could be alphanumeric data of any classification. Absolutely any data is allowed.

The BINARY XFD directive cannot be used in combination with the VAR_LENGTH XFD directive.

The method of storing fields declared as binary is database-specific. For example, Oracle uses the data type raw for the field.

Syntax

$XFD BINARY

Example

You might use this XFD directive when you need to store a key that contains LOW-VALUES; COBOL allows a numeric field to contain LOW or HIGH values, but these are invalid for a numeric field in the RDBMS:

 01  code-record.
     03  code-key.
         05  code-indic          pic x.
$XFD BINARY
         05  code-num            pic 9(5).
         05  code-suffix         pic x(3).
             .
             .
             .
 move low-values to code-num.
Parent topic: XFD Directives
Related information
VAR_LENGTH directive


COBOL-TRIGGER XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

This XFD directive indicates that a COBOL trigger is to be executed.

Note: This XFD directive must come immediately before the file descriptor of the file for which the trigger is defined. It uses the standard XFD directive syntax.

Syntax

XFD COBOL-TRIGGER=program-name
Restriction: program-name must be a native COBOL executable file, such as an .int or .gnt file.

The following three parameters are passed to the COBOL program:

01  OPCODE.
  88  READ-BEFORE       VALUE "r".
  88  READ-AFTER        VALUE "R".
  88  WRITE-BEFORE      VALUE "w".
  88  WRITE-AFTER       VALUE "W".
  88  REWRITE-BEFORE    VALUE "u".
  88  REWRITE-AFTER     VALUE "U".
  88  DELETE-BEFORE     VALUE "d".
  88  DELETE-AFTER      VALUE "D".

01  FILE-RECORD         PIC X(MAX-RECORD-SIZE).

01  ERROR-CODE          PIC 99.

In cases in which the record size is known, the actual record is passed [READ-AFTER (all), WRITE-BEFORE, WRITE-AFTER, REWRITE-BEFORE, REWRITE-AFTER].

In cases in which the record size is not known, the maximum record size is passed [READ-BEFORE (all), DELETE-BEFORE, DELETE-AFTER].

The contents of this field are identical to the record area given to the file operation. The BEFORE images have the value before the file operation, and the AFTER images have the value after the file operation.

Use the ERROR-CODE parameter to signal that an error occurred:

  • If you set this parameter in a BEFORE trigger, the file operation does not execute
  • If you set this parameter in an AFTER trigger, the run time system treats the file operation as an error, though in fact the file operation did execute. This means that, for sequential access (next or previous), the file position has changed and a subsequent next or previous act as if the prior file operation succeeded

Also, if you set an error in the REWRITE-AFTER or DELETE-AFTER, the record does not return to its prior state — the record is modified or deleted in the database.

Please note that if the COBOL program cannot be called (for any reason), it is treated as having succeeded.

Parent topic: XFD Directives


IDENTITY-COLUMN XFD directive

The IDENTITY-COLUMN XFD directive allows you to define an identity column in your database.

You must only specify this directive on a numeric field, and the column start number and incremental value will assume the database's defaults.

If you specify this directive on more than one numeric field, all but the first directive is ignored. If you specify the directive on a non-numeric field, a warning message is generated.

Parent topic: XFD Directives


COMMENT XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The COMMENT XFD directive lets you include comments in an XFD file. Because the information is embedded in a comment, it doesn't interfere with processing by the interfaces. Each comment entered with this XFD directive appears in the XFD file with the symbol "#" in column one.

Syntax

$XFD COMMENT text
Parent topic: XFD Directives


DATE XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The DATE XFD directive is used to store a field in the database as a date. Because there's no COBOL syntax that identifies a field as a date, you may want to add this XFD directive to differentiate dates from other numbers, so that they enjoy the properties associated with dates in the RDBMS. To view special options for two-digit dates, see the description of the ACUFH configuration file variable 4GL_2000_CUTOFF in 4GL_2000_CUTOFF configuration variable.

Syntax

$XFD DATE=date-format-string

This XFD directive implies the NUMERIC XFD directive.

If no date-format-string is specified, six-digit (or six-character) fields are retrieved as YYMMDD from the database. Eight-digit fields are retrieved as YYYYMMDD.

The date-format-string is a description of the desired date format, composed of characters from the following list:

M | Month (01–12)
Y | Year (two or four digits)
D | Day of month (01–31)
J | Julian day (00000000–99999999)
E | Day of year (001–366)
H | Hour (00–23)
N | Minute
S | Second
T | Hundredths of a second

Any other characters cause the date format string to be invalid and result in a corrupt XFD error or a compile-time warning.

Each character in a date format string can be considered a place holder that represents the type of information stored at that location. The characters also determine how many digits are used for each type of data.

For example, although you would typically represent the month with two digits, if you specify "MMM" as part of your date format, the resulting date uses three digits for the month, left-zero-filling the value. If the month is given as "M", the resulting date uses a single digit and truncates on the left.

Julian Dates

Because the definition of Julian day varies, the DATE XFD directive offers a great deal of flexibility for representing Julian dates. Many source books define the Julian day as the day of the year, with January 1st being 001, January 2nd being 002, and so forth. If you want to use this definition for Julian day, simply use "EEE" (day of year) in your date formats.

Other reference books define the Julian day as the number of days since some specific base date in the past. This definition is represented in the DATE XFD directive with the letter "J" (for example, a six-digit date field would be preceded with the XFD directive $XFD DATE=JJJJJJ). The default base date for this form of Julian date is 12/31/4714 BC.

You may define your own base date for Julian date calculations by setting the ACUFH configuration file variable 4GL_JULIAN_BASE_DATE.

Handling Invalid Dates

Dates in the following range are considered valid:

01/01/0001 to 12/31/9999

If the interface considers a date valid and passes it to an RDBMS that considers it invalid, the results depend on the particular RDBMS. Some systems return an error code. Some store the date as NULL and do not return an error. Some store the date in an unpredictable fashion and do not return an error. We recommend that you determine the error handling procedures of the RDBMS in use.

If a COBOL program attempts to write a record containing a date that the Database Connectors knows is invalid, the Database Connectors inserts NULLs into the date field and writes the record.

If a COBOL program attempts to read into a record from a table with a NULL date field, zeroes are inserted into that field in the COBOL record.

For date fields having two-digit years, by default years 0 through 19 are inserted as 2000 through 2019, and years 20 through 99 are inserted as 1920 through 1999.

You can control a number of these situations using configuration variables; see the links at the bottom of the page for more details.

Note:

If a field is used as part of a key, the field cannot be a NULL value. For information about converting date values using the 4GL_CONVERT_DATE_ZERO variable, see 4GL_CONVERT_DATE_ZERO configuration variable.

Using Group Items

You may place the DATE XFD directive in front of a group item, as long as you also use the USE GROUP XFD directive.

Examples

Example 1

 $xfd date
      03  date-hired    pic 9(8).
      03  pay-scale     pic x(3).

The column "date-hired" has eight digits is type DATE in the database, with a format of YYYYMMDD.

Example 2

$XFD DATE, USE GROUP
      03  date-hired.
          05  yyyy      pic 9(4).
          05  mm        pic 9(2).
          05  dd        pic 9(2).

This also produces a column named "date-hired" with eight digits and type DATE in the database, format YYYYMMDD.

Example 3

 $XFD DATE=EEEYYYY
      03  date-sold      pic 9(7).
      03  sales-rep      pic x(30).

This produces a column named "date-sold" with seven digits and type DATE in the database. The date contains the day of the year (for example, February 1st would be 032), followed by the four-digit year, such as 1999).

Parent topic: XFD Directives
Related information
4GL_2000_CUTOFF configuration variable
4GL_JULIAN_BASE_DATE configuration variable
4GL_CONVERT_DATE_ZERO configuration variable
NUMERIC directive
USE GROUP directive


FILE XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The FILE XFD directive supplies a starting name from which the XFD file name is formed. This XFD directive is required only when the file name in the COBOL code is nonspecific. For example, use this XFD directive when the SELECT for the file has a variable ASSIGN name (ASSIGN TO variable_name). In this case, the Connector cannot form a file name automatically, and you must provide a name. The starting name serves as the basis for the XFD name.

Syntax

$XFD FILE=name

This XFD directive must appear on the line immediately preceding the file's FD.

Example

Suppose your SELECT statement has a variable ASSIGN name such as the one shown here:

select my-file
assign to my-variable.

Then you would need to add the FILE XFD directive as shown here:

select my-file
 assign to my-variable.
    .
    .
    .
$xfd  file=payroll
 fd my-file
Parent topic: XFD Directives
Related information
XFD_MAP configuration variable


NAME XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The NAME XFD directive assigns a database field name to the field defined on the next line.

Syntax

$XFD NAME=fieldname

This XFD directive has several uses, as shown in the following examples.

Example 1 — Non-unique field names

Within a database file, all field names must be unique. (Multiple database tables may include the same field name, but duplicates may not exist within a single table.) Unique field names are not required in COBOL, because names can be qualified by group items.

For example, the following is acceptable in COBOL:

01  employee-record.
    03  date-hired.
        05  yy      pic 99.
        05  mm      pic 99.
        05  dd      pic 99.
    03  date-last-paid.
        05  yy      pic 99.
        05  mm      pic 99.
        05  dd      pic 99.

You need not change the field names in your COBOL program to access a database. Instead, you use the NAME XFD directive to provide unique database names for the fields. For example:

  01  employee-record.
      03  date-hired.
          05  yy      pic 99.
          05  mm      pic 99.
          05  dd      pic 99.
      03      date-last-paid.
 $xfd  name=year-paid
          05  yy      pic 99.
 $xfd  name=month-paid
          05  mm      pic 99.
 $xfd  name=day-paid
          05  dd      pic 99.

The dates portion of the resulting database table is as follows.

yy | mm | dd | year_paid | month_paid | day_paid
88 | 02 | 15 | 94 | 04 | 30

Example 2 — Names not unique within first 18 characters or longer than 18 characters

Some SQL-based databases require that names be unique within 18 characters, and some require that names be no longer than 18 characters. For those systems, the run time system truncates longer COBOL names after the first 18 characters.

For names that are identical within the first 18 characters, or are not meaningful if shortened to the first 18 characters, use the NAME XFD directive to assign them different database field names.

Suppose you had:

01  acme-employee-record.
    03  acme-employee-record-date-hired          pic x(6).
    03  acme-employee-record-date-last-paid      pic x(6).

You could add two NAME XFD directives to differentiate the two item names by making them meaningful within 18 characters:

  01  acme-employee-record.
 $xfd name=date-hired
      03  acme-employee-record-date-hired        pic x(6).
 $xfd name=date-last-paid
      03  acme-employee-record-date-last-paid    pic x(6).

Note that your COBOL names have not changed. The new names are used only for the database fields.

Each time you compile your program to create XFDs, any field names longer than 18 characters is checked for uniqueness within the first 18. If any field names are identical for the first 18 characters, a compiler warning message appears. A warning of this type does not prevent the program from compiling, and the XFD is generated.

Example 3 — Assigning shorter names

You may want to use the NAME XFD directive to assign shorter names than those used in your COBOL programs. This makes the formation of interactive SQL queries easier and quicker. For example:

 $XFD  NAME=EMPNO
      03  employee-number        pic x(8).

This XFD directive causes the XFD to map EMPLOYEE-NUMBER to EMPNO in the database.

Example 4 — Matching field names and COBOL FDs

If your database already exists, and a field name in the database does not match the name used in your COBOL FD, you can use a NAME XFD directive to associate the two names. For example:

 $xfd name=employee-no
      03  employee-number        pic x(8).

This XFD directive causes the XFD to map EMPLOYEE-NUMBER in the COBOL program to EMPLOYEE-NO in the database.

Example 5 — Renaming fields that begin with a numeric character

If your COBOL program uses field names that begin with a numeric character, use the NAME XFD directive to assign a different name for use with your database. SQL typically generates a syntax error when it encounters a column name that begins with a numeric character. For example:

    03  12-months-sales      pic 9(5)V99.

could be renamed this way:

 $xfd  name=twelve-months-sales
      03  12-months-sales    pic 9(5)V99.
Parent topic: XFD Directives


NULL XFD Directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The NULL XFD directive handles NULL values in numeric tables by comparing non-key field values when performing read and write actions on the database to determine and perform appropriate actions.

Syntax

$XFD NULL=literal
where literal is any literal value, or one of the following special literals to indicate that the field is comprised entirely of a specific type of value:
  • LOW-VALUES
  • HIGH-VALUES
  • SPACES
  • ZEROES

Specify the NULL XFD directive on individual numeric fields within the COBOL FD.

During a write to the database, this directive compares the value of the COBOL numeric field against its own set literal value. If the values are equal, it writes a NULL value to the database.

During a read of the database, if a NULL value is returned, this directive places its own set literal value into the COBOL numeric field before returning to the COBOL program.

Note: Fields allowing NULL values are not allowed as part of a record key. If the compiler encounters a record key containing NULL values, it returns a syntax error.
Parent topic: XFD Directives


NUMERIC XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The NUMERIC XFD directive allows you to treat a data item as an unsigned integer when it is declared as alphanumeric. You might use this when the data stored in the item is always numeric.

Syntax

$XFD NUMERIC

Example

$xfd numeric
 01  student-code      pic x(7).
Parent topic: XFD Directives


SECONDARY_TABLE XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Some Database Connectors interfaces (including MSSQL Server) permit subordinate tables. When this is the case, you can use the SECONDARY_TABLE XFD directive to indicate that the next data item may be placed into a subordinate table if more than one table is necessary to accommodate the data.

Up to 26 subordinate tables can be created from a single record description. Each table name is based on the original table name, with a letter from A to Z appended. For example, if the original table were named "my-table", subsequent subordinate tables would be given these names:

  • my-tableA
  • my-tableB
  • my-tableC
  • my-tableD

When the run time system accesses the XFD, it makes an initial pass through the data, taking all eligible data items for which the SECONDARY_TABLE XFD directive is not specified.

SECONDARY_TABLE is ignored for certain data items. These include:

  • Any field that is part of a key
  • Any field that is an indicator for a WHEN XFD directive

If the table size is not exceeded in the first pass, then, in a second pass, the run time system appends to the original table all items marked SECONDARY_TABLE that can be accommodated.

When the first table reaches a limit (either in total number of columns or total number of characters), that table is created, and a new table is begun. Items that did not fit into the previous table are placed into a subordinate table, in the order in which they are encountered.

The process repeats until all items have been accommodated.

It is permissible to place the SECONDARY_TABLE XFD directive just before a level 01 record definition. In this case, it applies to all fields underneath the level 01.

Syntax

$XFD SECONDARY_TABLE

Example

 $xfd secondary_table
  01  description      pic x(80).
Parent topic: XFD Directives
Related information
WHEN XFD directive


USE GROUP XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The USE GROUP XFD directive allows you to enter a group item into the database as a single field, instead of using the elements contained in the group. This is necessary if the item is stored in an existing database as a group, rather than as individual fields.

Combining fields of data into meaningful groups for database storage also improves I/O efficiency.

Syntax

$XFD USE GROUP

By default, the USE GROUP XFD directive implies that the consolidated field is alphanumeric. If you want a numeric field, simply add the word NUMERIC at the end of the XFD directive.

Example 1 – Combining DATE and USE GROUP XFD directives

For example, the XFD directive in the following code combines the functions of the USE GROUP and DATE XFD directives, and indicates that the date should be entered into the database as a single date-formatted data item instead of three distinct fields:

  $XFD  USE GROUP, DATE
       03  date-entered.
           05  yy      pic 99.
           05  mm      pic 99.
           05  dd      pic 99.

Either a comma or a space (or both) may separate the word "DATE" from the words "USE GROUP".

Example 2 – Forming larger units

Other fields with which you might use this XFD directive include multi-part account numbers or department numbers, or keys that are referenced as a unit but not by their individual pieces. Here's an example of an item that might be grouped:

 $xfd  use group
  01  gl-acct-no.
      03  main-acct     pic 9(4).
      03  sub-acct      pic 9(3).
      03  dept-no       pic 9(3).

If you are using an existing database in which certain fields are grouped, they must also be grouped in your COBOL file descriptor.

If the database does not yet exist, keep in mind that combining fields into groups can improve execution speed. Whether to group fields or not also depends on whether they are always stored and used together. Someone who really knows how the data is being used might help to identify groups of fields that can be combined to speed processing.

Parent topic: XFD Directives
Related information
DATE XFD directive
NUMERIC XFD directive


VAR_LENGTH XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

By default, the Compiler generates fixed-length fields in the XFD. The VAR_LENGTH XFD directive requests that the data item that immediately follows the XFD directive be assigned a type that implies variable length, if possible. This can save considerable space in your database.

The VAR_LENGTH XFD directive cannot be used in combination with the BINARY XFD directive.

The precise variable type that is assigned to the data item depends on which RDBMS is in use. Possible variable types that might be assigned are VARCHAR and VARBINARY.

Syntax

$XFD VAR_LENGTH

Example

For example, the XFD directive in the following code indicates that the employee-name field should be entered into a DB2 database as a VARCHAR data item.

 $XFD  VAR_LENGTH
      03  employee-notes      pic x(300).
Parent topic: XFD Directives
Related information
BINARY XFD directive


WHEN XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The WHEN XFD directive is used when you want to include multiple record definitions or REDEFINES in a database table. It's typically used when you want to force certain columns to be built that wouldn't be built by default (because you want to use them from the RDBMS side). For more information, see REDEFINES Clause.

Recall that the key fields and the fields from the largest record are automatically included as explicit columns in the database table. All fields are stored and retrieved from the database, whether they appear as explicit columns or not. So you don't need to use WHEN unless you want to ensure that some additional fields are explicitly listed by name in the table. For details about how fields are included in the database table, see How XFDs Are Formed.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follow the XFD directive must appear as a column (or columns) in the database table. It also states one condition under which the columns are to be used. The WHEN XFD directive guarantees that the fields are explicitly included in the table, as long as they aren't FILLER and don't occupy the same area as key fields.

The WHEN XFD directive results in a table that unites all fields subordinate to the WHEN XFD directive. This table might include more columns and could affect performance and storage requirements.

Syntax

$XFD WHEN field = value     (equals)
$XFD WHEN field <= value    (is less than or equals)
$XFD WHEN field < value     (is less than)
$XFD WHEN field >= value    (is greater than or equals)
$XFD WHEN field > value     (is greater than)
$XFD WHEN field != value    (is not equal to)
$XFD WHEN field = OTHER

The value may be an explicit data value (in quotes). The word "OTHER" can be used only with "=". It means use the following field(s) only if the WHEN condition(s) listed at the level of this field are not met.

Note: WHEN values must be on individual lines as single values in the code. WHEN values cannot be combined.

For example:

     03 ar-code-type                  pic x.
$xfd when ar-code-type = "s"
     03 ship-code-record              pic x(4).
$xfd when ar-code-type = "b"
     03 backorder-code-record redefines ship-code-record.
$xfd when ar-code-type = other
     03 obsolete-code-record redefines ship-code-record.

OTHER may be used before one record definition, and may be used once at each level within each record definition.

Note: A WHEN XFD directive with condition OTHER must be used if there is a possibility that the data in the field does not meet any of the explicit conditions specified in the other WHEN XFD directives. If this is not done, results are undefined.

Example 1

01 ar-codes-record.
  03 ar-codes-key.
    05 ar-code-type    pic x.
    05 ar-code-num     pic 999.
01 ship-code-record.
  03 filler            pic x(4).
  03 ship-instruct     pic x(15).
01 terms-code-record.
  03 filler            pic x(4).
  03 terms-rate-1      pic s9v999.
  03 terms-days-1      pic 9(3).
  03 terms-rate-2      pic s9v999.
  03 terms-descript    pic x(15).

If you add the WHEN XFD directive as shown below, it causes the fields from the SHIP-CODE-RECORD to be included in the database table, and determines when specific database columns are used. The underlined fields then appear as columns in the database table:

 01 ar-codes-record.
   03 ar-codes-key.
     05 ar-code-type      pic x.
     05 ar-code-num       pic 999.
$xfd when ar-code-type = "s"
 01 ship-code-record.
   03 filler              pic x(4).
   03 ship-instruct       pic x(15).
$xfd when ar-code-type = "t"
 01 terms-code-record.
   03 filler              pic x(4).
   03 terms-rate-1        pic s9v999.
   03 terms-days-1        pic 9(3)
   03 terms-rate-2        pic s9v999.
   03 terms-descript      pic x(15).

FILLER data items don't have unique names and are thus not used to form columns in the database table. You could use the NAME XFD directive to give them a name if you really need to see them in the database table.

Note: In this example, the FILLER data items implicitly redefine key fields. Thus, they would be disregarded even if you provided a name for them.

Example 2

In the following code, in which no WHEN XFD directives are used, the underlined fields are explicitly named in the database table. (Key fields have the suffix key in their names in this example.)

Note that REDEFINES records simply re-map the same data area and are not explicitly included in the database table by default:

01 archive-record.
  03 filler               pic x(33).
  03 archive-code         pic 9(6).
  03 archive-location     pic 9(2).
  03 filler               pic x(10).
01 master-record.
  03 animal-id-key.
    05 patient-id         pic 9(6).
    05 species-code-type  pic 9(5).
    05 species-name       pic x(6).
  03 service-code-key.
    05 service-code-type  pic 9(6).
    05 service-name       pic x(10).
  03 billing-code.
    05 billing-code-type  pic 9(4).
    05 plan-name          pic x(8).
  03 office-info.
    05 date-in-office     pic 9(8).
    05 served-by-name     pic x(10).
  03 remote-info redefines office-info.
    05 van-id             pic 9(4).
    05 proc-code          pic 9(8).
    05 vet-name           pic x(6).

If you add the WHEN XFD directives shown below, you add several columns to the database table. The fields which then appear in the table are underlined:

$xfd when animal-id-key = "00000000000000000"
 01 archive-record.
   03 filler              pic x(33).
   03 archive-code        pic 9(6).
   03 archive-location    pic 9(2).
   03 filler              pic x(10).
$xfd when animal-id-key = other
 01 master-record.
$xfd use group
   03 animal-id-key.
     05 patient-id        pic 9(6).
     05 species-code-type pic 9(5).
     05 species-name      pic x(6).
   03 service-code-key.
     05 service-code-type pic 9(6).
     05 service-name      pic x(10).
   03 billing-code.
     05 billing-code-type pic 9(4).
     05 plan-name         pic x(8).
$xfd when billing-code-type = "1440"
   03 office-info.
     05 date-in-office    pic 9(8).
     05 served-by-name    pic x(10).
$xfd when billing-code-type = other
   03 remote-info redefines office-info.
     05 van-id            pic 9(4).
     05 proc-code         pic 9(8).
     05 vet-name          pic x(6).

Example 3

If your application has a REDEFINES whose field names are more meaningful than the fields they redefine, you might consider switching the order of your code, rather than using a WHEN XFD directive. Use the less significant field names in the REDEFINES.

For example, you might change this:

   03 code-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
   03 patient-info redefines code-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).

to this:

   03 patient-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
   03 code-info redefines patient-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).

The fields that would appear in the database table by default are underlined above. This shows how the column names might become more meaningful when the order is reversed. Your application operates the same either way.

Note: When a WHEN XFD directive condition is met, COBOL record definitions or REDEFINES records that are subordinate to other WHEN XFD directives are not used. Database columns in rows that correspond to those records are set to the special database value NULL. This means that there is no value provided for those columns. NULL is not equivalent to zero, and it has special properties in the RDBMS. For example, you can select all rows for which a given column is NULL.

Example 4

This COBOL code:

01  col-type                         pic x.
 $xfd  when col-type = "a"
      03  def1                         pic x(2).
 $xfd  when col-type = "b"
      03  def2 redefines def1          pic 9(2).

results in this database table:

col_type | def1 | def2
a | Xx | <Null>
b | <Null> | 10
  • WHEN Complex Expressions
    Syntax and rules for using complex expressions with WHEN directives.
Parent topic: XFD Directives
Related information
How XFDs are Formed
NAME XFD directive
REDEFINES Clause


WHEN Complex Expressions

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The XFD WHEN directive supports complex expressions such as those containing multiple AND and OR operations and parentheses to group sub-expressions for proper order of evaluation. For example:

$XFD WHEN (var1 = "abc" or var1 = "def") and \
$XFD      (var2 > "000" or var3 > "000") and \
$XFD       var4 != "xyzzy"

Here is a more complete example:

       fd idx1-file.
       01 idx1-record1.
          03 filler pic x(46).

       01 idx1-record2.
          03 idx1-key.
             05 idx1-num1  pic 9(3).
             05 idx1-num2  pic 9(3).
             05 idx1-num3  pic 9(3).
          03 filler pic x(37).

      $xfd when ((idx1-num1 = "000" or idx1-num1 = "009") and  \
      $xfd       (idx1-num2 = "000" or idx1-num2 = "009"))     \
      $xfd   tablename=one
       01 idx1-record3.
          03 filler pic x(6).
          03 rec3-name1  pic x(20).
      $xfd when idx1-num3 = "333" or idx1-num3 = "444", tablename=two
          03 rec3-name2  pic x(20).

      $xfd when idx1-num1 = "001" AND idx1-num2 = "001"
       01 idx1-record4.
          03 filler pic x(6).
          03 rec4-name1  pic x(30).
          03 rec4-name2  pic x(10).

      $xfd when idx1-num1 > "001" OR idx1-num2 > "001"
       01 idx1-record5.
          03 filler pic x(6).
          03 rec5-text  pic x(40).

WHEN Expression Rules

  1. The AND operation takes precedence over the OR operation. If sc1, sc2, and sc3 are simple conditions (as defined above) then the expression sc1 or sc2 and sc3 is interpreted as sc1 or (sc2 and sc3) meaning that the AND of sc2 and sc3 is performed first and the result of that operation is OR'ed with sc1. If you want the OR operation performed first then you must specify (sc1 or sc2) and sc3 using parentheses.
  2. Since expressions are likely to use parentheses it is strongly recommended that the "$XFD" syntax be used rather than the "*(( XFD" with trailing "))" syntax.
  3. Mismatched parentheses cause an error to be reported.
  4. The maximum number of simple conditions in one expression is 50. An error is reported if the maximum is exceeded.
  5. Only one WHEN expression directive is allowed on consecutive lines. For example, the following three lines cause a syntax error to be reported:
    $XFD WHEN var1 = "abc" or var2 = "def"
$XFD WHEN var3 = "xyz"
01  record-type-2.

    If what you meant was:

    $XFD WHEN (var1 = "abc" or var2 = "def") \
$XFD   and var3 = "xyz"
01  record-type-2.

    then you must code it that way (note the use of parentheses and the backslash XFD directive line continuation character).

    "The optional condition tablename at the end of a WHEN directive applies to all simple conditions within the expression and to the overall combined expression. For example:

    $XFD WHEN (var1 = "abc" or var1 = "def") and \
$XFD      (var2 = "123" or var2 = "456") \
$XFD      tablename = table-2
01  record-type-2.

    The condition tablename table-2 is applied to all four simple conditions and propagated to the two OR conditions and to the final AND condition of the expression.

Parent topic: WHEN XFD directive


XSL XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

The XSL XFD directive allows you to include a stylesheet reference in the XML header.

Syntax

$XFD XSL=stylesheet

where stylesheet is an alphanumeric literal indicating the appropriate stylesheet. The Compiler includes the following line in all generated XML-style XFD files:

<?xml-stylesheet type="text/xsl" href="stylesheet"?>

For example:

$XFD XSL="myxsl.xsl"

generates this line:

<?xml-stylesheet type="text/xsl" href="myxsl.xsl"?>
Parent topic: XFD Directives


Compiler Directives Affecting XFD Creation

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.
  • CREATEXFD XFD directive
Parent topic: Database Connectors Reference


CREATEXFD XFD directive

Restriction: This topic applies only when a Database Connectors license has been installed via the Micro Focus License Management System.

Use the CREATEXFD directive to tell the compiler to generate XFDs for the COBOL files contained in your program.

This directive has the following format:

Syntax

$SET CREATEXFD ( version=n, xfd-directory=pathname, file-type=all )

All of the arguments are optional, and can be given in any order.

version=n | Causes XFD files of type n to be used. Currently, "6" is the only valid value here. Any other value causes XFD files of the latest version to be created
xfd-directory=pathname | Causes the XFD files to be created in the directory named by pathname. Pathname must be a valid directory, either absolute or relative, and must be writable to the user
file-type=all | Causes XFD files for all file types to be created. Without this argument, the Compiler creates XFD files for only indexed files. If anything other than "all" is specified, the Compiler creates XFD files only for indexed files
Parent topic: Compiler Directives Affecting XFD Creation


File Handling

  • File Handling Examples
  • File Handling Guide
  • File Systems
  • Fileshare Guide
Parent topic: Data Access


File Handling Examples

  • Example of Data and Key Compression
  • External Files
  • File Handler
  • File Names
  • File Status
  • Indexed Files
  • MFSORT
  • Rebuild
  • Example Relative File Definition
  • Sequential Files
Parent topic: File Handling
Related information
File Handling Guide
File Systems
Fileshare Guide


Example of Data and Key Compression

In the following program, data compression is specified for transfile but not for masterfile. For key compression, suppression of trailing spaces and of leading characters that are the same as in the previous key is specified for keys t-rec-key and m-rec-key.

Suppression of repetition of duplicate keys is also turned on for m-alt-key-1 and m-alt-key-2. This is ignored for m-alt-key-1 which does not allow duplicates.

$set callfh"extfh"
$set datacompress"1"
$set keycompress"6"
     select transfile
         assign to "user.dat"
         organization is indexed
         record key is t-rec-key.
$set nokeycompress
$set nodatacompress

     select masterfile
         assign to "stock.dat"
         organization is indexed
$set keycompress"6"
         record key is m-rec-key
$set keycompress"7"
         alternate key is m-alt-key-1 with duplicates
         alternate key is m-alt-key-2.
$set nokeycompress
Parent topic: File Handling Examples
Related information
External Files
File Handler
File Names
File Status
Indexed Files
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


External Files

  • Example External Files
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
File Handler
File Names
File Status
Indexed Files
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Example External Files

  1$set ans85 mf noosvs
  2*****************************************************
  3*
  4*    (C) 1997-2002 Micro Focus International Ltd.
  5*
  6*      EXTFILE.CBL
  7*
  8* This program demonstrates how to use EXTERNAL files
  9* It calls WRITEFIL to write some records to a data
 10* file and READFILE to read the same records back
 11* (without opening or closing the file between calls
 12* READFILE displays the output.
 13*
 14****************************************************
 15 identification division.
 16 program-id. extfile.
 17 environment division.
 18 input-output section.
 19 file-control.
 20 select finfile assign to "isamfil.dat"
 21  organization is indexed
 22  record key is fd-tran-date
 23  access mode is dynamic.
 24
 25 file section.
 26 fd finfile
 27  is external
 28   record contains 50 characters.
 29 01 fd-finfile-record.
 30   05 fd-tran-date   pic x(4).
 31   05 fd-with-or-dep   pic x(2).
 32   05 fd-amount    pic 9(5)v99.
 33
 34 procedure division.
 35 main-line.
 36   perform open-file
 37   perform write-to-the-file
 38   perform start-file
 39   perform read-the-file
 40   perform close-file
 41   stop run.
 42
 43 open-file.
 44   open i-o finfile.
 45
 46 start-file.
 47   move 1111 to fd-tran-date
 48   start finfile key = fd-tran-date.
 49
 50 write-to-the-file.
 51   call "writefil".
 52
 53 read-the-file.
 54   call "readfile".
 55
 56 close-file.
 57   close finfile.
 58 end program extfile.
 59*****************************************************
 60 identification division.
 61 program-id. readfile.
 62 environment division.
 63 input-output section.
 64 file-control.
 65 select finfile assign to "isamfil.dat"
 66   organization is indexed
 67   record key is fd-tran-date
 68   access mode is dynamic.
 69
 70 file section.
 71 fd finfile
 72   is external
 73   record contains 50 characters.
 74 01 fd-finfile-record.
 75   05 fd-tran-date   pic x(4).
 76   05 fd-with-or-dep  pic x(2).
 77   05 fd-amount    pic 9(5)v99.
 78
 79 working-storage section.
 80 01 ws-end-of-file   pic 9   value 0.
 81 01 ws-subtotal    pic s9(5)v99 value 0.
 82 01 ws-total     pic -(4)9.99.
 83
 84 procedure division.
 85 main-line.
 86   perform read-the-file.
 87   perform until ws-end-of-file = 1
 88   perform calculate-totals
 89   perform read-the-file
 90   end-perform.
 91   perform display-output.
 92   exit program.
 93   stop run.
 94
 95 read-the-file.
 96   read finfile next record at end
 97    move 1 to ws-end-of-file.
 98
 99 calculate-totals.
100   evaluate fd-with-or-dep
101    when "WI"
102     subtract fd-amount from ws-subtotal
103    when "DE"
104     add fd-amount to ws-subtotal
105   end-evaluate.
106
107 display-output.
108   move ws-subtotal to ws-total
109   display "account balance = ", ws-total.
110
111 end program readfile.
112****************************************************
113 identification division.
114 program-id. writefil.
115 environment division.
116 input-output section.
117 file-control.
118 select finfile assign to "isamfil.dat"
119   organization is indexed
120   record key is fd-tran-date
121   access mode is dynamic.
122
123 file section.
124 fd finfile
125  is external
126  record contains 50 characters.
127 01 fd-finfile-record.
128   05 fd-tran-date   pic x(4).
129   05 fd-with-or-dep   pic x(2).
130   05 fd-amount    pic 9(5)v99.
131
132 procedure division.
133 main-line.
134   perform write-records
135   exit program
136   stop run.
137
138 write-records.
139
140* write a WIthdrawal record
141   move 1111 to fd-tran-date.
142   move 'WI' to fd-with-or-dep.
143   move 23.55 to fd-amount.
144   write fd-finfile-record.
145
146* write a DEposit record
147   move 2222 to fd-tran-date.
148   move 'DE' to fd-with-or-dep.
149   move 123.55 to fd-amount.
150   write fd-finfile-record.
151
152 end program writefil.
Parent topic: External Files


File Handler

  • Example Configuration File
  • Example of Creating a New Index File
  • Example of Accessing the FCD
  • Example of Setting Up the Record Area
  • Example of Setting up the Filename Area
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Names
File Status
Indexed Files
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Example Configuration File

The following is an example of the contents of a file handler configuration file, extfh.cfg:

[XFH-DEFAULT]
trace=on
IdxDatBuf=0
IndexCount=22000
KeyCheck=off
NodeSize=512
TraceFileName=p:\data\trace.xfh

[test.dat]
IdxDatBuf=1024
trace=off

[test1.dat]
KeyCheck=on
Parent topic: File Handler
Related reference
File Handler Configuration Options
File Handler Configuration
Related information
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Creating a New Index File

 78 close-file   value x"fa80"
 78 open-new-index  value x"0007".
 78 get-next-rec  value x"0008".
 78 add-key-value  value x"0009".
  ...

     move open-new-index to fh-opcode
     perform extfh-op
     move get-next-rec to fh-opcode
     perform extfh-op
     perform until fcd-status (1:1) not = "0"
         perform varying fcd-key-id from 0 by 1
                 until fcd-key-id = key-count
                    or fcd-status (1:1) not = "0"
             move add-key-value to fh-opcode
             perform extfh-op
         end-perform
         move get-next-rec to fh-opcode
         perform extfh-op
     end-perform
     move close-file to fh-opcode
     perform extfh-op
       ...

 extfh-op.
     call "EXTFH" using fh-opcode, fcd
     if fcd-status of fcd (1:1) = "1"
         move 1 to return-code
     end-if.
Parent topic: File Handler
Related information
Example Configuration File
Example of Accessing the FCD
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Accessing the FCD

The following program turns on key compression in a file by setting the appropriate bits in the file's Key Definition Block.

$set fcdreg
 select masterfile
     assign to ...
     organization is indexed
     record key is rec-key
     alternate key is m-alt-key-1 with duplicates
     alternate key is m-alt-key-2
     alternate key is m-alt-key-3 with duplicates.

 select indexfile
     assign to ...
     organization is indexed
     record key is rec-key
     alternate key is t-alt-key-1 with duplicates.
 ...
 working-storage section.
 ...
 linkage section.
 01 key-def-block.
     03 filler     pic x(6).
     03 key-count    pic 9(4) comp-x.
     03 filler     pic x(6).
     03 key-def occurs 1 to 4 times depending on key-count.
         05 filler    pic x(5).
         05 key-compression pic 9(2) comp-x.
         05 filler    pic x(10).
   ...
 procedure division.
     set address of key-def-block to address of fh--keydef of masterfile
     move 6 to key-compression (1)
     move 7 to key-compression (2)
     move 6 to key-compression (3)
     move 7 to key-compression (4)
     open I-O masterfile
     ...
     set address of key-def-block to address of fh--keydef of indexfile
     move 4 to key-compression (1)
     move 1 to key-compression (2)
     open input indexfile
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Setting Up the Record Area
Example of Setting up the Filename Area


Example of Setting Up the Record Area

The following example shows how the FCD is set up to point to the record area:

 01 RECORD-AREA   PIC X(85).
...
     SET FCD-RECORD-ADDRESS TO ADDRESS OF RECORD-AREA
   ...
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting up the Filename Area


Example of Setting up the Filename Area

The following example shows how the FCD is set up to point to the filename area:

 01 FILENAME-AREA PIC X(65) VALUE "master.dat".
...
     SET FCD-FILENAME-ADDRESS TO ADDRESS OF FILENAME-AREA
   ...
Parent topic: File Handler
Related information
Example Configuration File
Example of Creating a New Index File
Example of Accessing the FCD
Example of Setting Up the Record Area


File Names

  • Examples of static filename assignment
  • Example of dynamic filename assignment
  • Example of external filename assignment
  • Examples of device name assignment
  • Example of Forced Filename Mapping
  • Example of Connecting a File to Standard Output
  • Example of Connecting a File to Standard Input
  • Example of Setting up a Two-way Pipe
  • Example of using the External File Mapper
  • Example of Specifying a Fileshare Client User ID and Password
  • Example Fileshare Client Configuration File
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Status
Indexed Files
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Examples of static filename assignment

 select stockfile
     assign to "b:warehs.buy".

In this example, opening stockfile will cause the warehs.buy file on the b: drive to be opened.

 select printfile
     assign to "prn:".

In this example, writing to printfile will cause data to be output to prn:, the first parallel printer.

 select input-file
     assign to "data\prog".

In this example, opening input-file will cause the file prog in the data directory (relative to the current directory) to be opened.

Parent topic: File Names
Related information
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of dynamic filename assignment

 select fd-in-name
     assign to dynamic ws-in-file.
  ...
 select fd-out-name
     assign to dynamic ws-out-file.
  ...
 working-storage section.
 01 ws-in-file  pic x(30) value "input.dat".
 01 ws-out-file pic x(40).
  ...
 procedure division.
     accept ws-out-file.
     open input fd-in-name fd-out-name
  ...

In this example, the file input.dat in the current directory and the file specified by the current value of ws-out-file, are opened.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of external filename assignment

 select fd-name
     assign to external envvar.

In this example, envvar must be an environment variable. Before executing the program, you must issue a export command to relate envvar to the physical filename you want to use:

export envvar=/tmp/test.dat

At run-time, the filename fd-name is assigned to the file test.dat in the specified directory.

Parent topic: File Names
Related reference
Filename Mapping
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File
Example of Reorganizing an Indexed File


Examples of device name assignment

 select fd-name
     assign to "con".

In this example, read/write operations on fd-name cause data to be read from/written to the console screen.

 select fd-name
     assign to dynamic ws-filename.
   ...
     move "lpt1:" to ws-filename.

In this example, write operations on fd-name cause data to be output to lpt1:, the first parallel printer.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of Forced Filename Mapping

 select fd-name
     assign to "$file1"

This causes the system to search for the environment variable dd_file1. If this is not found, the system searches for the environment variable file1. If this is not found, the system attempts to open the file $file1.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of Connecting a File to Standard Output

 select input-file
     assign to "fname"
     organization is line sequential.
  ...
 fd input-file
    record contains 80 characters.
 01 input-file-record pic x(80).
 ...
 procedure division.
     open input input-file.
     read input-file record.
  ...
     close input-file.
     stop run.

If, before running the above program, the following command is issued:

set dd_fname="<cmd /c dir c:\help"

then each READ operation on input-file returns the next line of output from the dir command.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of Connecting a File to Standard Input

 select output-file
     assign to external evar
     organization is line sequential.
  ...
 fd output-file
    record contains 80 characters.
 01 output-file-record pic x(80).
  ...
 procedure division.
     open output output-file.
     write output-file-record from "c:\dir\file".
   ...
     close output-file.
     stop run.

If, before running the above code, the following command is issued:

set evar=">cmd /c print"

then each WRITE operation on output-file is passed as input to the print command.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of Setting up a Two-way Pipe

 select i-o-file
     assign to "| cmd /c sort"
     organization is line sequential.
 fd i-o-file.
 01 i-o-file-record pic x(20).
 procedure division.
     open i-o i-o-file
     write i-o-file-record from "Hello world"
     write i-o-file-record from all "A"
     write i-o-file-record from all "Z"
     write i-o-file-record from x"1a"
     perform until exit
         read i-o-file
          at end
             exit perform
         end-read
         display i-o-file-record
     end-perform
     close i-o-file

In this example, the program launches the sort process and passes it three lines of text, followed by an end-of-file marker. It then reads all three lines back from the standard output of the sort process.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of using the External File Mapper

Suppose your program includes:

 select fd-name
     assign to external bigdata.

Create a text file called mfextmap.dat that contains the following line:

bigdata c:\big\bigdata.dat

At run-time:

  1. Ensure that mfextmap.dat is in the current directory, in a directory pointed to by the COBDIR environment variable or in a directory pointed to by the MFEXTMAP environment variable.
  2. Ensure that you have enabled the External File Mapper (Mfextmap) by adding the following line:
    set environment_mapper=TRUE

    to a configuration file pointed to by the COBCONFIG environment variable.

Then, when you run your program, the assigned filename bigdata is mapped to the physical file c:\big\bigdata.dat.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of Specifying a Fileshare Client User ID and Password
Example Fileshare Client Configuration File


Example of Specifying a Fileshare Client User ID and Password

This example shows how to code your program to supply a user-ID and password to a Fileshare Server:

 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
Note: This example supports long usernames and passwords.
Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example Fileshare Client Configuration File


Example Fileshare Client Configuration File

/s server1
/s server2
/f \orders\* /s server3
/f \accounts\payroll.dat
/f \transport\delivery\*

This example configuration file specifies that server1 and server2 are the default Fileshare Servers. This means that these Fileshare Servers will be searched, in this order, for any file which is not specified as either a local file or as located on a specific Fileshare Server. It also specifies that any files with a filename beginning orders\ are located on server3, that the file accounts\payroll.dat is a local file and that any file with a filename beginning transport\delivery\ is a local file.

Parent topic: File Names
Related information
Examples of static filename assignment
Example of dynamic filename assignment
Example of external filename assignment
Examples of device name assignment
Example of Forced Filename Mapping
Example of Connecting a File to Standard Output
Example of Connecting a File to Standard Input
Example of Setting up a Two-way Pipe
Example of using the External File Mapper
Example of Specifying a Fileshare Client User ID and Password


File Status

  • Example of Displaying File Status Codes
  • Example of Checking File Status Codes
  • Example of Extended File Status Codes
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
Indexed Files
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Example of Displaying File Status Codes

The example code that follows illustrates one method of retrieving the values of the second byte of the file status for display purposes. Note how truncation has been avoided by redefining the two status bytes as one numeric data item (length two bytes) capable of storing up to four decimal digits.

 select fd-name
     assign "user.dat"
     status is fd-name-stat.
  ...
 data division.
 file section.
 fd fd-name.
 01 fd-rec    pic x(80)
  ...
 working-storage section.
 01 fd-name-stat.
     03 sk1     pic x.
     03 sk2     pic x.
     03 stat-bin redefines sk2 pic 9(2) comp-x.
 01 disply-stat.
     03 sk1-displ   pic x.
     03 filler    pic x(3).
     03 sk2-displpic  pic zz9.
  ...
 procedure division.
 start-test.
     open input fd-name
     move sk1 to sk1-displ
     if sk1 not= 9
         move sk2 to sk2-displpic
     else
         move stat-bin to sk2-displpic
     end-if
     display disply-stat
     close fd-name
     stop run.
Parent topic: File Status
Related information
Example of Checking File Status Codes
Example of Extended File Status Codes


Example of Checking File Status Codes

The example code that follows illustrates how file status checking is performed: first the first byte (status key 1) is interrogated; then, if more information is required, the second byte (status key 2) is interrogated.

 select recseq
     assign to "recseq.dat"
     file status is ws-file-status
     organization is record sequential.
  ...
 file section.
 fd recseq
    record contains 80 characters.
 01 recseq-fd-record  pic x(80).
  ...
 working-storage section.
 01 ws-file-status.
     05 status-key-1  pic x.
     05 status-key-2  pic x.
     05 binary-status redefines status-key-2 pic 99 comp-x.
  ...
 procedure division.
  ...
 perform check-status.
  ...
 check-status.
     evaluate status-key-1
      when "0" next sentence
      when "1" display "end of file reached"
         perform check-eof-status
      when "2" display "invalid key"
         perform check-inv-key-status
      when "3" display "permanent error"
         perform check-perm-err-status
      when "4" display "logic error"
      when "9" display "run-time-system error"
         perform check-mf-error-message
     end-evaluate.
  ...
 check-eof-status.
     if status-key-2 = "0"
         display "no next logical record"
     end-if.
  ...
 check-inv-key-status.
      evaluate status-key-2
       when "2" display "attempt to write dup key"
       when "3" display "no record found"
      end-evaluate.
  ...
 check-perm-err-status.
      if status-key-2 = "5"
 display "file not found"
      end-if.
  ...
 check-mf-error-message.
      evaluate binary-status
       when 002 display "file not open"
       when 007 display "disk space exhausted"
       when 013 display "file not found"
       when 024 display "disk error    "
       when 065 display "file locked      "
       when 068 display "record locked    "
       when 039 display "record inconsistent"
       when 146 display "no current record  "
       when 180 display "file malformed     "
       when 208 display "network error      "
       when 213 display "too many locks     "
       when other display "not error status "
           display binary-status
     end-evaluate.
Parent topic: File Status
Related information
Example of Displaying File Status Codes
Example of Extended File Status Codes


Example of Extended File Status Codes

The example code that follows illustrates how to redefine a standard file status so that it can be used as an extended file status. Assume for this example that the input file does not exist - when the OPEN INPUT statement is executed, a file status of 9/013 ("file not found") is returned.

 select in-file
     assign to "user.dat".
     file status is file-status.
  ...
 working-storage section.
 01 file-status.
     05 status-key-1     pic x.
     05 status-key-2     pic x.
     05 status-key-2-binary redefines status-key-2 pic 99 comp-x.
  ...
 procedure division.
     open input in-file
     if file-status not = "00"
     if status-key-1 = "9"
     if status-key-2-binary = 13
         display "File not found"
  ...

If you want to display the extended file status code, you need to move the second byte of the file status data item to a display field large enough to hold the maximum value 255:

 select in-file
     assign to "user.dat"
     file status is file-status.
  ...
 working-storage section.
 01 ans74-file-status.
     05 status-key-1    pic x.
     05 status-key-2    pic x.
     05 status-key-2-binary redefines status-key-2 pic 99 comp-x.
 01 display-ext-status
     05 filler          pic xx value "9/"
     05 display-key 2   pic 999
  ...
 procedure division.
     open input in-file
     if file-status not = "00"
         display "Error. File status =" with no advancing
         if status-key-1 = "9"
             move status-key-2-binary to display-key-2
             display display-ext-status
         else
             display file-status
         end-if
  ...
Parent topic: File Status
Related reference
Run-time System Error Messages
Extended File Status Codes
Related information
Example of Displaying File Status Codes
Example of Checking File Status Codes


Indexed Files

  • Example of Indexed File Definition
  • Example of Primary Key Definition
  • Example of Alternate Key Definition
  • Example of Duplicate Key Definition
  • Example of Sparse Key Definition
  • Example of Indexed File Access Definition
  • Example of Creating Fixed-length Records
  • Example of Creating Variable Length Records
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
MFSORT
Rebuild
Example Relative File Definition
Sequential Files


Example of Indexed File Definition

To define an indexed file:

 file-control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         record key is fd-name-key
    ...
 fd fd-name.
 01 fd-name-record.
     03 fd-name-key  pic X(5).
Parent topic: Indexed Files
Related information
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Primary Key Definition

To define a primary key:

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         record key is fd-name-key.
    ...
 fd fd-name.
 01 fd-name-record.
     03 fd-name-key  pic X(5).
Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Alternate Key Definition

To define an alternate key:

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         record key is fd-name-key
         alternate record key is fd-name-alt-key.
    ...
 fd fd-name.
 01 fd-name-record.
     03 fd-name-key     pic X(5).
     03 fd-name-alt-key pic X(4).
Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Duplicate Key Definition

To define a duplicate key:

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         record key is fd-name-key
         alternate record key is fd-name-alt-key
          with duplicates.
    ...
 fd fd-name.
 01 fd-name-record.
     03 fd-name-key     pic X(5).
     03 fd-name-alt-key pic X(4).
Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Sparse Key Definition

To define a sparse key:

 file control.
     select fd_name
         assign to "user.dat"
         organization is indexed
         record key is fd-name-key
         alternate record key is fd-name-alt-key
          with duplicates
          suppress when all "A".
     ...
 fd fd-name.
 01 fd-name-record.
     03 fd-name-key  pic X(3).

In this example, if a record is written for which the value of the alternate key is all A's, the actual key value is not stored in the index file.

Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Indexed File Access Definition

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         access mode is dynamic
         record key is fd-name-key.
Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Creating Fixed-length Records
Example of Creating Variable Length Records


Example of Creating Fixed-length Records

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         access mode is dynamic
         record key is fd-name-key.
    ...
 file section.
 fd fd-name
    record contains 80 characters.
 01 fd-name-record.
     05 fd-name-key    pic x(5).
     05 fd-name-data   pic x(75).

In this example an indexed file with fixed-length 80-byte records, keyed on the first five bytes of each record, is defined.

Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Variable Length Records


Example of Creating Variable Length Records

 file control.
     select fd-name
         assign to "user.dat"
         organization is indexed
         access mode is dynamic
         record key is fd-name-key.
    ...
 file section.
 fd fd-name.
    record is varying in size
     from 5 to 80 characters depending on ws-record-count.
 01 fd-name-record.
     05 fd-name-key    pic x(5).
     05 fd-name-data   pic x(75).
 ...
 working-storage section.
 01 ws-record-count    pic 99 comp-x.

In this example an indexed file with variable-length records, varying in length from 5 to 80 bytes, is defined. Note that any key(s) must lie within the fixed part of the record.

Parent topic: Indexed Files
Related information
Example of Indexed File Definition
Example of Primary Key Definition
Example of Alternate Key Definition
Example of Duplicate Key Definition
Example of Sparse Key Definition
Example of Indexed File Access Definition
Example of Creating Fixed-length Records


MFSORT

  • Example Mfsort Command Line
  • Example Mfsort Fields Instruction
  • Example Mfsort Key Instruction
  • Example Mfsort Instruction File
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
Rebuild
Example Relative File Definition
Sequential Files


Example Mfsort Command Line

The following example shows the Mfsort command to sort four files:

mfsort use file1 record (v,4,8) use file2 use file3 use file4 give file5 sort fields (1, 1, s5, a, 2, 1, c5, d)
Parent topic: MFSORT
Related information
Example Mfsort Fields Instruction
Example Mfsort Key Instruction
Example Mfsort Instruction File


Example Mfsort Fields Instruction

The following example sorts the file on a 6-byte alphanumeric field which starts at the second byte of the record, in ascending order, with a secondary ordering on a 4-byte (PIC 9(8))COMP field starting at the tenth byte of the record, in descending order.

mfsort sort fields (2, 6, ch, a, 10, 4, bi, d)
Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Key Instruction
Example Mfsort Instruction File


Example Mfsort Key Instruction

The following example defines three keys:

key (4,5,p,10,5,c,20,2,ad,40,2,a,46,10,c)

The first key, the primary key, is split with its first component starting at character position 4 with a length of 5 bytes and its second component starting at character position 10 with a length of 5 bytes.

The second key (alternate key) enables duplicates, starts at character position 20 and is 2 bytes in length.

The third key 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 and with a length of 10 bytes.

Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Fields Instruction
Example Mfsort Instruction File


Example Mfsort Instruction File

The following is an example Mfsort instruction file, called sample.srt:

use file1 record (v,4,8)
use file2
use file3
use file4
give file5
merge fields (1,1,S5,a,2,1,c5,d)

Note that ORG is not needed here as SQ is the default, and that file2 through file5 and the merge workfile use the RECORD format specified for file1.

This instruction file would be used as follows:

mfsort take sample.srt
Parent topic: MFSORT
Related information
Example Mfsort Command Line
Example Mfsort Fields Instruction
Example Mfsort Key Instruction


Rebuild

  • Example of Reorganizing an Indexed File
  • Example of recovering a corrupt indexed file
  • Example of using Rebuild to convert a file
  • Example of validating the structure of an indexed file
  • Example of a Rebuild options file
  • Example of calling Rebuild from a COBOL program
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
MFSORT
Example Relative File Definition
Sequential Files


Example of Reorganizing an Indexed File

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

Example 1

rebuild infile.dat,outfile.dat

To reorganize the file, Rebuild reads the data file (infile.dat) using the index file (infile.idx) and then creates the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.

Example 2

rebuild infile.dat,outfile.dat /i

In addition to reorganizing the file, Rebuild displays processing information when the reorganization is complete.

Example 3

rebuild infile.dat,outfile.dat /s:lii /t:lii

Reorganizes a LEVEL II V2.5 COBOL format file and retains the LII structure on the output file. It is possible to combine /s and /t with other formats in a similar manner.

Example 4

set data=\tmp.dat
rebuild data /i

Rebuild reorganizes and displays information about the file \tmp.dat.

Example 5

rebuild infile001.dat,outfile.dat/x:3

In addition to reorganizing the file, Rebuild writes the data in the order of the third alternate key.

Note: You cannot use the same filename for the input file and the output file.
Parent topic: Rebuild
Related reference
Filename Mapping
Rebuild Options - /x
Related information
Example of recovering a corrupt indexed file
Example of using Rebuild to convert a file
Example of validating the structure of an indexed file
Example of a Rebuild options file
Example of calling Rebuild from a COBOL program
Example of external filename assignment


Example of recovering a corrupt indexed file

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

Example 1

rebuild infile.dat

To get the key information, Rebuild reads the .idx file. Rebuild then reads the data file infile.dat to create a new index file.

If the index file is not present, you must use /k to supply information about the key structure.

Example 2

rebuild infile.dat, outfile.dat /d /e

Rebuild reads the input file to get the key information, and creates a new indexed file, by working through the data in physical order, skipping over duplicate records.

If the index file is not present, you must use /k to supply information about the key structure.

Example 3

rebuild infile.dat/k:1+20/i

To rebuild the indexed file, Rebuild reads the key definition information supplied by the /k option. In this case, there is a single key, starting at character position 1 and 20 characters in length.

Rebuild ignores any index files that already exist.

The key definition information that you supply using the /k option does not need to correspond to the key definition used when the file was created.

The /i option ensures that processing information is displayed when the rebuild is complete.

Parent topic: Rebuild
Related information
Example of Reorganizing an Indexed File
Example of using Rebuild to convert a file
Example of validating the structure of an indexed file
Example of a Rebuild options file
Example of calling Rebuild from a COBOL program


Example of using Rebuild to convert a file

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.
rebuild infile.dat,outfile.dat /s:c-isam /c:d1 /t:mf

In this example, Rebuild converts a C-ISAM file into the format used by this system and compresses the data part of the file.

Parent topic: Rebuild
Related information
Example of Reorganizing an Indexed File
Example of recovering a corrupt indexed file
Example of validating the structure of an indexed file
Example of a Rebuild options file
Example of calling Rebuild from a COBOL program


Example of validating the structure of an indexed file

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.
rebuild test.dat /f

In this example Rebuild performs a full integrity check on the file, displaying full information.

Parent topic: Rebuild
Related information
Example of Reorganizing an Indexed File
Example of recovering a corrupt indexed file
Example of using Rebuild to convert a file
Example of a Rebuild options file
Example of calling Rebuild from a COBOL program


Example of a Rebuild options file

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.
rebuild infile.dat, outfile.dat @conv.par

In this example, conv.par is an ASCII text file containing the following Rebuild options:

/k:1+20,25+5:40+12:60+3,85+10d
Parent topic: Rebuild
Related information
Example of Reorganizing an Indexed File
Example of recovering a corrupt indexed file
Example of using Rebuild to convert a file
Example of validating the structure of an indexed file
Example of calling Rebuild from a COBOL program


Example of calling Rebuild from a COBOL program

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

This 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
Example of Reorganizing an Indexed File
Example of recovering a corrupt indexed file
Example of using Rebuild to convert a file
Example of validating the structure of an indexed file
Example of a Rebuild options file


Example Relative File Definition

To define a relative file with a record length of 80 characters:

 file-control.
     select relfil
         assign to "relfil.dat"
         organization is relative
         access mode is random
         relative key is relfil-key.
 file section.
 fd relfil
    record contains 80 characters.
 01 recseq-fd-record  pic x(80).
   ...
 working-storage section.
 01 relfil-key        pic 9(8) comp-x.

The record key is relfil-key. When you are randomly accessing this file, there is no KEY IS field on the READ statement, the number in relfil-key determines which record is read. For sequential access, a simple READ NEXT statement gets the next record.

Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
MFSORT
Rebuild
Sequential Files


Sequential Files

  • Example Record Sequential File Definition - Fixed-length Records
  • Example Record Sequential File Definition - Variable Length Records
  • Example Line Sequential File Definition
  • Example Printer Sequential File Definition
Parent topic: File Handling Examples
Related information
Example of Data and Key Compression
External Files
File Handler
File Names
File Status
Indexed Files
MFSORT
Rebuild
Example Relative File Definition


Example Record Sequential File Definition - Fixed-length Records

To define a record sequential file with fixed-length records:

 file-control.
     select recseq
         assign to "recseq.dat"
         organization is record sequential.
...
 file section.
 fd recseq
    record contains 80 characters.
 01 recseq-fd-record   pic x(80).

You could simply use ORGANIZATION IS SEQUENTIAL, as record sequential is the default for sequential files, as long as the SEQUENTIAL Compiler directive is not set.

Parent topic: Sequential Files
Related information
Example Record Sequential File Definition - Variable Length Records
Example Line Sequential File Definition
Example Printer Sequential File Definition


Example Record Sequential File Definition - Variable Length Records

To define a record sequential file with variable length records:

 file control.
     select recseqv
         assign to "recseqv.dat"
         organization is record sequential.
      ...
 file section.
 fd recseqv
    record varying from 3 to 80 characters depending on ws-record-length.
 01 recseqv-fd-record  pic x(80).
   ...
 working-storage section.
 01 ws-record-length   pic 99.

You could simply use ORGANIZATION IS SEQUENTIAL, as record sequential is the default for sequential files, as long as the SEQUENTIAL Compiler directive is not set.

Parent topic: Sequential Files
Related information
Example Record Sequential File Definition - Fixed-length Records
Example Line Sequential File Definition
Example Printer Sequential File Definition


Example Line Sequential File Definition

To define a line sequential file with a record length of 80 characters:

 file-control.
     select lineseq
         assign to "line.dat"
         organization is line sequential.
         ...

 file section.
 fd lineseq
    record contains 80 characters.
 01 lineseq-fd-record  pic x(80).
Parent topic: Sequential Files
Related information
Example Record Sequential File Definition - Fixed-length Records
Example Record Sequential File Definition - Variable Length Records
Example Printer Sequential File Definition


Example Printer Sequential File Definition

To define a printer sequential file:

 file control.
     select prseq
         assign to printer "prseq.dat"
   ...
Parent topic: Sequential Files
Related information
Example Record Sequential File Definition - Fixed-length Records
Example Record Sequential File Definition - Variable Length Records
Example Line Sequential File Definition


File Handling Guide

  • Introduction
    Visual COBOL provides two file handlers containing built-in file handling capabilities for all types of file organization.
  • File Organizations
    This chapter describes the file organizations supported by your COBOL system.
  • Filenames
    This chapter covers information about file names and their usage, and includes details of the search sequence employed by the run-time system to find dynamically or externally assigned files.
  • File Status
    File status codes are used by this COBOL system to indicate the success, or otherwise, of any file operation carried out by your program.
  • Sharing Files
    This chapter explains how to prevent more than one user from changing the same data at the same time in a multi-user environment through the use of file and record locks.
  • File Handler Configuration
    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, by setting run-time switches, or by setting environment variables.
  • File Handler and Sort APIs
    This chapter shows you how to make explicit calls to the File Handler and the Sort Module from your program.
  • Sort Utilities
    Visual COBOL provides MFSORT, a command line sort and merge utility.
  • Data and Key Compression
    Records and keys in files created using the File Handler can be compressed so they take up less physical disk space. You can enable data compression by using the File Handler to call compression routines from your program.
  • Tracing File Operations
    Use the tracing file operations, which are provided to help in investigations into problems with file handling.
Parent topic: File Handling
Related information
File Handling Examples
File Systems
Fileshare Guide


Introduction

  • Overview
    COBOL offers file handling capabilities for files of sequential, relative and indexed organization, using simple COBOL syntax. In addition, Micro Focus COBOL offers additional file handling features.
  • Micro Focus File Handler
    The Micro Focus File Handler, by default, performs all COBOL I/O operations on all the standard COBOL file organizations: sequential, relative and indexed files.
Parent topic: File Handling Guide
Related information
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


Overview

COBOL offers file handling capabilities for files of sequential, relative and indexed organization, using simple COBOL syntax. In addition, Micro Focus COBOL offers additional file handling features.
File Handling Feature | Use to...
Line sequential file organization | Access ASCII text files from your COBOL program
A set of COBOL system library routines | Manipulate files and directories
A set of COBOL system library routines | Handle files at the byte level
Fileshare | Access groups of files on network servers
A conversion module | Read from and write to Btrieve files
Parent topic: Introduction
Related information
Micro Focus File Handler


Micro Focus File Handler

The Micro Focus File Handler, by default, performs all COBOL I/O operations on all the standard COBOL file organizations: sequential, relative and indexed files.

In addition, you can use the File Handler's Applications Programming Interface (API) to call the file handler directly from your COBOL program, or you can create a custom file handler of your own.

Parent topic: Introduction
Related information
Overview


File Organizations

  • Overview
  • Sequential Files
  • Relative Files
  • Indexed Files
  • Fixed-length and Variable-length Records
  • File Headers
Parent topic: File Handling Guide
Related information
Introduction
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


Overview

A file is a collection of data that is, typically, stored on disk. As a logical entity, a file enables you to divide your data into meaningful groups. For example, you can use one file to hold all of a company's product information and another file to hold all personnel information. As a physical entity, a file should be considered in terms of its file organization, which refers to the way in which data is stored physically in a file. This determines the way that you access the data subsequently.

This COBOL system supports three file organizations: sequential, relative and indexed. Depending upon the file organization, you have up to three ways of accessing the data:

File Organization | Sequential Access | Random Access | Dynamic Access
Sequential | Yes | No | No
Relative | Yes | Yes | Yes
Indexed | Yes | Yes | Yes
Parent topic: File Organizations
Related information
Sequential Files
Relative Files
Indexed Files
Fixed-length and Variable-length Records
File Headers


Sequential Files

A sequential file is one in which the individual records can only be accessed sequentially, that is, in the same order as they were originally written to the file. New records are always added to the end of the file.

Several types of sequential file are supported by this COBOL system.

  • Record Sequential Files
  • Line Sequential Files
  • Printer Sequential Files
Parent topic: File Organizations
Related information
Overview
Relative Files
Indexed Files
Fixed-length and Variable-length Records
File Headers


Record Sequential Files

Record sequential files are nearly always referred to simply as sequential files because when you create a file and specify the organization as sequential, a record sequential file is created by default.

To define a file as record sequential, specify ORGANIZATION IS RECORD SEQUENTIAL in the SELECT clause for the file in your COBOL program, for example:

 select recseq assign to "recseq.dat"
     organization is record sequential.

Because record sequential is the default for sequential files, you don't need to specify ORGANIZATION IS RECORD SEQUENTIAL. As long as you do not set the SEQUENTIAL Compiler directive, you can simply use ORGANIZATION IS SEQUENTIAL.

Parent topic: Sequential Files
Related information
Line Sequential Files
Printer Sequential Files


Line Sequential Files

The primary use of line sequential files (which are also known as "text files" or "ASCII files") is for display-only data. Most PC editors, for example Notepad, produce line sequential files.

In a line sequential file, each record in the file is separated from the next by a record delimiter. The record delimiter, which is the line feed (x"0A") character, is inserted after the last non-space character in each record. A WRITE statement removes trailing spaces from the data record and appends the record delimiter. A READ statement removes the record delimiter and, if necessary, pads the data record (with trailing spaces) to the record size defined by the program reading the data.

If the record size in a line sequential file is greater than the record length, the data fills the record length and on the next READ it returns more data from that record. i.e. it uses the record length and the record delimiter.

To define a file as line sequential, specify ORGANIZATION IS LINE SEQUENTIAL in the SELECT clause for the file in your COBOL program, for example:

 select lineseq assign to "lineseq.dat"
     organization is line sequential.
Parent topic: Sequential Files
Related information
Record Sequential Files
Printer Sequential Files


Printer Sequential Files

Printer sequential files are files which are destined for a printer, either directly or by spooling to a disk file. They consist of a sequence of print records with zero or more vertical positioning characters (such as line-feed) between records. A print record consists of zero or more printable characters and is terminated by a carriage return (x"0D").

With a printer sequential file, the OPEN statement causes a x"0D" to be written to the file to ensure that the printer is located at the first character position before printing the first print record. The WRITE statement causes trailing spaces to be removed from the print record before it is written to the printer with a terminating carriage return (x"0D"). The BEFORE or AFTER clause can be specified in the WRITE statement to cause one or more line-feed characters (x"0A"), a form-feed character (x"0C") or a vertical tab character (x"0B") to be sent to the printer before or after writing the print record.

Printer sequential files should not be opened for INPUT or I/O.

You can define a file as printer sequential by specifying ASSIGN TO LINE ADVANCING FILE or ASSIGN TO PRINTER in the SELECT clause, for example:

 select printseq
     assign to line advancing file "printseq.dat".
Parent topic: Sequential Files
Related information
Record Sequential Files
Line Sequential Files


Relative Files

A relative file is a file in which each record is identified by its ordinal position in the file (record 1, record 2 and so on). This means that records can be accessed randomly as well as sequentially:

  • For sequential access, simply execute a READ or WRITE statement to access the next record in the file.
  • For random access, define a data item as the relative key. Then specify in the data item the ordinal number of the record that you need to READ or WRITE.

Because records can be accessed randomly, access to relative files is fast.

Although you can declare variable length records for a relative file, this can be wasteful of disk space because the system assumes the maximum record length for all WRITE statements to the file and pads the unused character positions. This is done so that the COBOL file handling routines can quickly calculate the physical location of any record, given the record's record number in the file.

As relative files always contain fixed length records, no space is saved by specifying data compression. In fact, if data compression is specified for a relative file, it is ignored by the File Handler.

Each record in a relative file is followed by a two-byte record marker which indicates the current status of the record. The status of a record can be:

x"0A" - record present

x"00" - record deleted or never written

When you delete a record from a relative file, the record's contents are not removed immediately. The record's record marker is updated to show that it has been deleted, but the contents of the deleted record remain physically in the file until a new record is written. If you need to remove the data from the file for security reasons, follow the procedure below:

  1. Use REWRITE to overwrite the record, for example with space characters.
  2. Delete the record.

To define a relative file, specify ORGANIZATION IS RELATIVE in the SELECT clause for the file in your COBOL program.

To access records randomly, you must also:

  • Specify ACCESS MODE IS RANDOM or ACCESS MODE IS DYNAMIC in the SELECT clause for the file
  • Define a relative key in the Working-Storage Section of your program

For example:

 select relfil assign to "relfil.dat"
     organization is relative
     access mode is random
     relative key is relfil-key.
 ...
 working-storage section.
 01 relfil-key   pic 9(8) comp-x.

The example code above defines a relative file. The access mode is random and so a relative key relfil-key is defined. For random access, you must always supply a record number in the relative key, before trying to read a record from the file.

If you specify ACCESS MODE IS DYNAMIC, you can access the file both sequentially and randomly.

Parent topic: File Organizations
Related information
Overview
Sequential Files
Indexed Files
Fixed-length and Variable-length Records
File Headers


Indexed Files

An indexed file is a file in which each record includes a primary key. To distinguish one record from another, the value of the primary key must be unique for each record. Records can then be accessed randomly by specifying the value of the record's primary key. Indexed file records can also be accessed sequentially.

As well as a primary key, indexed files can contain one or more additional keys known as alternate keys. The value of a record's alternate key(s) does not have to be unique.

To define a file as indexed, specify ORGANIZATION IS INDEXED in the SELECT clause for the file in your COBOL program. You must also specify a primary key using the RECORD KEY clause:

 select idxfile assign to "idx.dat"
    organization is indexed
    record key is idxfile-record-key.

Most types of indexed file actually comprise two separate files: the data file (containing the record data) and the index file (containing the index structure). Where this is the case, the name that you specify in your COBOL program is given to the data file and the name of the associated index file is produced by adding an .idx extension to the data file name. You should avoid using the .idx extension in other contexts.

The index is built up as an inverted tree structure that grows as records are added.

With indexed files, the number of disk accesses required to locate a randomly selected record depends primarily on the number of records in the file and the length of the record key. File I/O is faster when reading the file sequentially.

We strongly recommend that you take regular backups of files of all types. However, with indexed files there are events such as media corruption that can result in only one of the two files becoming unusable. If you do lose an index file, use the Rebuild utility to recover the index from the data file and so reduce the time lost due to a failure. For more information, see the topic Rebuild.

  • Primary Keys
  • Alternate Keys
  • Duplicate Keys
  • Sparse Keys
  • Indexed File Access
Parent topic: File Organizations
Related concepts
Rebuild
Related information
Overview
Sequential Files
Relative Files
Fixed-length and Variable-length Records
File Headers


Primary Keys

To define the primary key of an indexed file use the RECORD KEY IS clause in the SELECT clause:

 select idxfile assign to "idx.dat"
     organization is indexed
     record key is idxfile-record-key.
Parent topic: Indexed Files
Related information
Alternate Keys
Duplicate Keys
Sparse Keys
Indexed File Access


Alternate Keys

As well as the primary key, each record can have any number of additional keys, known as alternate keys. To define an alternate key use the ALTERNATE RECORD KEY IS clause in the SELECT clause:

 select idxfile assign to "idx.dat"
     organization is indexed
     record key is idxfile-record-key
     alternate record key is idxfile-alt-key.
Parent topic: Indexed Files
Related information
Primary Keys
Duplicate Keys
Sparse Keys
Indexed File Access


Duplicate Keys

You can define keys which allow duplicate values. However, do not allow duplicates on primary keys as the value of a record's primary key must be unique.

When you use duplicate keys, be aware that there is a limit on the number of times you can specify the same value for an individual key. Each time you specify the same value for a duplicate key, an increment of one is added to the key's occurrence number. The maximum number of duplicate values permitted for an individual key varies according to the type of indexed file. For a full list of indexed file types and their characteristics, see the topic Types of Indexed Files.

The duplicate occurrence value is a unique identifier, which is added to the key, which has duplicates in order to make it unique. When a new key is added, where keys of the same value exist, then 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 keys, which are not deleted and so if the highest occurrence of the series of duplicates is not deleted, then the highest value does not change. If the highest occurrence is deleted, then the highest occurrence value reduces to the next lower still existing occurrence value.

Your COBOL system uses the occurrence number to ensure that duplicate key records are read in the order in which they were created. Because of this, you cannot reuse an occurrence number whose record you have deleted. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted.

Some types of indexed file contain a duplicate occurrence record in the data file. Where an indexed file contains a duplicate occurrence record, each record in the data file is followed by a system record. This system record holds, for each duplicate key in that record, the occurrence number of the key. This number is just a counter of the number of times that key value has been used during the history of the file. The presence of the duplicate occurrence record makes REWRITE and DELETE operations on a record with many duplicates much faster but causes the data records of such files to be larger than those of a standard file.

To enable duplicate values to be specified for alternate keys, use WITH DUPLICATES in the ALTERNATE RECORD KEY clause in the SELECT clause:

 file-control.
     select idxfile assign to "idx.dat"
         organization is indexed
         record key is idxfile-record-key
         alternate record key is idxfile-alt-key
                                 with duplicates.
Parent topic: Indexed Files
Related information
Primary Keys
Alternate Keys
Sparse Keys
Indexed File Access
Types of Indexed File


Sparse Keys

A sparse key is a key for which no index entry is stored for a given value of that key. For example, if a key is defined as sparse when it contains all spaces, index entries for the key are not included when the part of the record it occupies contains only space characters.

Only alternate keys can be sparse.

Using this feature results in smaller index files. The larger your key(s) and the more records you have for which the alternate key has the given value, the larger your saving of disk space.

To enable sparse keys, use SUPPRESS WHEN ALL in the ALTERNATE RECORD KEY clause in the SELECT clause:

 file-control.
     select idxfile assign to "idx.dat"
         organization is indexed
         record key is idxfile-record-key
         alternate record key is idxfile-alt-key
                                 with duplicates
                                 suppress when all "A".

In this example, if a record is written for which the value of the alternate key is all As, the actual key value is not stored in the index file.

Parent topic: Indexed Files
Related information
Primary Keys
Alternate Keys
Duplicate Keys
Indexed File Access


Indexed File Access

You can use both the primary and alternate keys to read records from an indexed file, either directly (random access) or in key sequence (sequential access). The access mode can be:

  • SEQUENTIAL

    Access records in order of ascending or descending record key value (default)

  • RANDOM

    Access records according to the value of the record key

  • DYNAMIC

    Use the appropriate forms of I/O statement to switch between sequential and random access

The method of accessing an indexed file is defined using the ACCESS MODE IS clause in the SELECT clause, for example:

 file-control.
     select idxfile assign to "idx.dat"
         organization is indexed
         access mode is dynamic
         record key is idxfile-record-key
         alternate record key is idxfile-alt-key.
Parent topic: Indexed Files
Related information
Primary Keys
Alternate Keys
Duplicate Keys
Sparse Keys


Fixed-length and Variable-length Records

A file can contain:

  • Fixed-length records - all the records are exactly the same length
  • Variable-length records - the length of each record varies

Using variable-length records might enable you to save disk space. When you use fixed-length records, you need to make the record length equal to the length of the longest record. If your application generates many short records with occasional long ones, using fixed-length records wastes a lot of disk space, so variable-length records would be a better choice.

The type of record is determined as follows:
To use: | Specify the clause:
Variable-length records | RECORDING MODE IS V
Fixed-length records | RECORDING MODE IS F
Otherwise:
To use: | Specify the clause:
variable length records | RECORD IS VARYING
fixed length records | RECORD CONTAINS n CHARACTERS
Otherwise:
To use: | Specify the Compiler directive:
variable length records | RECMODE"V"
fixed length records | RECMODE"F"

Otherwise, to use variable length records, specify the RECMODE"OSVS" Compiler directive plus one of the following:

  • RECORD CONTAINS n TO m CHARACTERS
  • More than one record area of different lengths
Parent topic: File Organizations
Related information
Overview
Sequential Files
Relative Files
Indexed Files
File Headers


File Headers

A file header is a block of 128 bytes at the start of the file. Files with the following file organizations contain file headers:

  • Indexed files
  • Record sequential files with variable length records
  • Relative files with variable length records

In addition, each record in these files is preceded by a two- or four-byte record header.

Parent topic: File Organizations
Related information
Overview
Sequential Files
Relative Files
Indexed Files
Fixed-length and Variable-length Records


Filenames

  • Filename Conventions
  • Assigning Filenames
  • Library Names in Paths
  • Filename Mapping
  • Assigning Device Names
  • Setting Up Pipes
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


Filename Conventions

A file is identified in a COBOL program by a filename which is a user-defined word. Outside the COBOL system it is identified by a filename which must be in an external, operating-system format. There are four components:

  • A drive
  • A path
  • A base-name
  • An extension

The maximum length of the filename is 1023 characters.

COBOL imposes no other limits, but in order for the operating system to handle the filename correctly, any operating system limits must be observed when the program is run.

The following restrictions apply when naming your files:

  • Avoid using the following characters when you are creating Internet applications: % # ( ) @.
  • The Micro Focus COBOL products available on UNIX contain components that do not handle long filenames and filenames and folder names containing spaces. Avoid using long names and names containing spaces for files that will be published to UNIX.
  • The Oracle 1.8 version of Pro*Cobol does not support filenames that contain spaces.
Parent topic: Filenames
Related information
Assigning Filenames
Library Names in Paths
Filename Mapping
Assigning Device Names
Setting Up Pipes


Assigning Filenames

The ASSIGN clause in the SELECT clause is used to specify either a physical filename or a logical name which can be mapped to a physical name at run time.

There are three types of filename assignment:

  • STATIC

    The filename is specified as a literal in the ASSIGN clause

  • DYNAMIC

    The filename is specified as a data-item in the ASSIGN clause, and so can be changed by the program at run time

  • EXTERNAL

    The filename is specified as EXTERNAL in the ASSIGN clause and is resolved at run time

Run-time mapping of filenames is available for all three types of filename assignment.

 select input-file
     assign to "data/prog".
  • Static Filename Assignment
  • Dynamic Filename Assignment
  • External Filename Assignment
Parent topic: Filenames
Related information
Filename Conventions
Library Names in Paths
Filename Mapping
Assigning Device Names
Setting Up Pipes


Static Filename Assignment

With static filename assignment, the filename is specified in the SELECT clause as a literal:

 select filename
     assign to literal.

If the filename of the physical file that you are creating contains spaces, the filename is automatically surrounded by quotes for you.

In the following example, opening stockfile causes the file warehs.buy in the current directory to be opened:

 select stockfile
     assign to "warehs.buy".
Parent topic: Assigning Filenames
Related information
Dynamic Filename Assignment
External Filename Assignment


Dynamic Filename Assignment

With dynamic filename assignment, the filename is specified in the SELECT clause as a COBOL data item:

 select filename
     assign to dynamic data-item

where the parameters are:

filename
The filename of the file that is to be assigned.
data-item
The name of a COBOL data item. If the data item is not explicitly declared in your program, the Compiler creates one for you, with a picture of PIC X(255). Before the OPEN statement for the file is executed, the program must give a value to the data item.

Example

In the following example, the file input.dat is created in the current directory:

   ...
 select fd-in-name
     assign to dynamic ws-in-file.
       ...
 working-storage section.
 01 ws-in-file     pic x(30).
       ...
     move "input.dat" to ws-in-file.
       ...
     open output fd-in-name.
Note: If you use the ASSIGN"DYNAMIC" Compiler directive, you can omit the word DYNAMIC from the ASSIGN clause.
Parent topic: Assigning Filenames
Related information
Static Filename Assignment
External Filename Assignment


External Filename Assignment

With external filename assignment, the filename is specified in the SELECT clause as follows:

 select filename
     assign to external external-file-reference

where the parameters are:

filename
The filename of the file that is to be assigned.
external-file-reference
A COBOL word that identifies the specified file to the external environment for possible further mapping. If external-file-reference contains one or more hyphens, all characters up to and including the last hyphen are ignored.

See Filename Mapping for more information.

Parent topic: Assigning Filenames
Related information
Static Filename Assignment
Dynamic Filename Assignment
Filename Mapping


Library Names in Paths

You can include a library name in the name of a file you want to open. The file specification is of the form

 /library-name.lbr/filename.ext

Example

/appdir/applib.lbr/app.dat

This type of filename is only valid when used as the name of a data file being opened in read-only mode, using either OPEN INPUT syntax or the CBL_OPEN_FILE byte stream routine. If the library is not already open, this call will open that library on the given device and leave it open after the call. If the library does not exist, or if the given filename.ext does not exist in that library, a "file not found" error is returned.

Parent topic: Filenames
Related concepts
Filename Mapping
Related information
Filename Conventions
Assigning Filenames
Filename Mapping
Assigning Device Names
Setting Up Pipes
Defining Input and Output Files


Filename Mapping

This COBOL system provides several ways of mapping the filename supplied by the program via the ASSIGN clause onto a different name, for greater flexibility at run time. These rely on the use of environment variables.

Before you run the program, you should give any environment variables you are using an appropriate value using the operating system export command, for example:

export dir=d2

When presented with a filename (which may be a literal, the contents of a data item, or, in the case of the ASSIGN TO EXTERNAL syntax, an external reference), the File Handler follows this procedure:

  1. Isolates the first element of the filename, that is, all the text before the first slash character (/), all the text if the name does not include such a character or nothing if the filename starts with a slash character.
  2. If the first element begins with two dollar characters ($$), indicating that the file is located on a Fileshare server, switches the search process to that Fileshare server, and continues the filename mapping process with the next element.
  3. Removes the leading dollar character ($) if it is present, prefixes the characters "dd_" to this first element and searches for an environment variable with this name.
  4. If it does not find this environment variable and either the ASSIGN EXTERNAL syntax was used or the element began with a dollar character, looks for an environment variable with the same name as the element (minus the leading dollar character if present).
  5. If the search is unsuccessful, leaves the element unchanged, except in the case where the element begins with a dollar character and the whole filename contains at least one slash character. In this case, the whole of the first element, together with the first slash, is removed from the name.

This procedure is then repeated for the next element in the filename, and continues until all the elements in the name have been processed. The result is then considered to be the filename of the physical file.

Consider the following examples:

Filename in ASSIGN Clause | Environment Variables Searched For | Contents of Environment Variable | Filename of Physical File
dir/file1 | dd_dir | d2 | d2/file1
$dir/file1 | dd_dir;dir | d2/d4 | d2/d4/file1
dir1/dir2/file1 | dd_dir1 | d4 | d4/dir2/file1
$dir1/$dir2/file1 | First iteration: dd_dir1;dir1 Second iteration: dd_dir2;dir2 | dd_dir1 or dir1: d2/d4 dd_dir2 or dir2: d3 | d2/d4/d3/file1
file1 | dd_file1 | d2 | d2
  • Multiple Paths
  • Library Names
Parent topic: Filenames
Related reference
Printer Output is Written to Disk
Related information
Filename Conventions
Assigning Filenames
Library Names in Paths
Assigning Device Names
Setting Up Pipes
External Filename Assignment


Multiple Paths

An environment variable used for filename mapping can specify multiple pathnames. This causes the system to search for subsequent files if a "file not found" condition is returned for the first path specified by the environment variable.

Consider the following example contents of an environment variable named dd_dir.

dd_dir=/a/b;/c/d;
This causes the system to search /c/d for the assigned file if a "file not found" condition is returned on /a/b.
Note:
  • If an existing file is being opened, using OPEN INPUT, OPEN I-O, OPEN EXTEND or the CBL_OPEN_FILE byte stream routine, the environment variable is expanded to the first path on which the file is found.
  • If a new file is being created, using OPEN OUTPUT, OPEN I-O, OPEN EXTEND, or the CBL_CREATE_FILE byte stream routine, the environment variable is expanded to the first path named. For files which are opened with OPEN OUTPUT, you can override this behavior by setting the SEARCHONCREATE File Handler configuration option to ON.
  • The length of each path in a path list in an environment variable must be less than or equal to the permitted maximum number of characters for a path.
Parent topic: Filename Mapping
Related information
Library Names


Library Names

You can include library names in a multiple path environment variable. For example, if you have issued the command

set test=/apdir;/aplbr/aplbr.lbr;/aplbr/aplbr1.lbr
the filename $test/app.dat would be resolved to /aplbr/aplbr.lbr/app.dat if /apdir/app.dat did not exist.

The libraries are searched in the order they appear in the environment variable.

You can also specify a library as part of the search path for program calls. For example, if you have issued the command

set appath=/apdir/progs1.lbr;/appdir/progs2.lbr

you can use the format

call "$appath/prog"

Your COBOL development system will search the libraries progs1.lbr and progs2.lbr for the program prog1. The libraries are searched in the order they appear in the environment variable. Any library searched remains open during the execution of the application, unless the application itself explicitly closes it.

Parent topic: Filename Mapping
Related information
Multiple Paths


Assigning Device Names

You can write a COBOL program to send a report directly to the printer or to transfer data across a communications port. To do this, you need to assign a device-name to your COBOL filename.

You can specify the following device-names using static, dynamic or external filename assignment:
Device-name | Description
CON | Console keyboard or screen
PRN | First parallel printer
LPT1 | First parallel printer
LPT2 | Second parallel printer
LPT3 | Third parallel printer
COM1 | First asynchronous communications port
COM2 | Second asynchronous communications port

When specifying any of these device-names, a trailing colon(:) is optional.

In the following example, read or write operations on fd-name cause data to be read from or written to the console screen:

select fd-name
   assign to "con".

In the next example, write operations on fd-name cause data to be output to lpt1:, the first parallel printer:

select fd-name
   assign to dynamic ws-filename.
   ...
   move "lpt1:" to ws-filename.
Parent topic: Filenames
Related information
Filename Conventions
Assigning Filenames
Library Names in Paths
Filename Mapping
Setting Up Pipes


Setting Up Pipes

You can use COBOL file syntax to launch another process (such as the dir command) and either write data to the standard input of that other process or read data coming from the standard output of the other process. The COBOL file organization must be either LINE SEQUENTIAL or RECORD SEQUENTIAL.

  • Output Pipes
  • Input Pipes
  • Two-way Pipes
Parent topic: Filenames
Related information
Filename Conventions
Assigning Filenames
Library Names in Paths
Filename Mapping
Assigning Device Names


Output Pipes

To launch a process and write data to its standard input, the filename must consist of the > sign followed by the name of the command. The file should be opened for output.

For example:

 select output-file
     assign to ">cmd /c sort"
     organization is line sequential.
 fd output-file.
 01 output-file-record pic x(10).
 procedure division.
     open output output-file
     write output-file-record from "Charles"
     write output-file-record from "Bill"
     write output-file-record from "Alan"
     close output-file.
Parent topic: Setting Up Pipes
Related information
Input Pipes
Two-way Pipes


Input Pipes

To launch a process and read data from its standard output, the filename must consist of the < sign followed by the name of the command. The file should be opened for input.

For example:

 select input-file
     assign to "<cmd /c dir"
     organization is line sequential.
  ...
     open input input-file
     read input-file

In this example the program launches the dir process and reads in the first line that it writes to its standard output.

Parent topic: Setting Up Pipes
Related information
Output Pipes
Two-way Pipes


Two-way Pipes

Two-way pipes combine the functions of input and output pipes. To use a two-way pipe, the filename must consist of the pipe symbol (|) followed by the name of the command. The file should be opened for input-output i-o.

For example:

 select i-o-file
     assign to "| cmd /c sort"
     organization is line sequential.
 fd i-o-file.
 01 i-o-file-record pic x(20).
 procedure division.
     open i-o i-o-file
     write i-o-file-record from "Hello world"
     write i-o-file-record from all "A"
     write i-o-file-record from all "Z"
     write i-o-file-record from x"1a"
     perform until exit
         read i-o-file
          at end
             exit perform
         end-read
         display i-o-file-record
     end-perform
     close i-o-file

In this example, the program launches the sort process and passes it three lines of text, followed by an end-of-file marker. The program then reads all three lines back from the standard output of the sort process.

Parent topic: Setting Up Pipes
Related information
Output Pipes
Input Pipes


File Status

A full list of file status codes is given in the topic File Status Codes.

  • What is File Status?
  • Defining a File Status Data Item
  • File Status Conventions
  • Extended File Status Codes
Parent topic: File Handling Guide
Related reference
File Status Codes
Related information
Introduction
File Organizations
Filenames
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


What is File Status?

File status is a two-byte code that indicates how a file operation completed; either successfully, or with some form of error. If an error occurs, file status indicates the cause of the error.

If you have a file status data item defined for a file, after every input/output operation on the file (OPEN, CLOSE, READ, WRITE, REWRITE, START and DELETE) the run-time system updates it to indicate how the operation completed.

Defining a file status data item is optional. If a file status data item is not declared and a serious file error occurs, the COBOL run-time system displays an error message and aborts your program.

You should check the file status data item after each input/output operation, to see if the operation completed successfully. For example, when your program is writing to disk, there might not be enough disk space to complete the WRITE operation. If you have not defined a file status data item and you run out of disk space, the run-time system displays an error number and aborts the program. If you have a file status data item defined (for the file you are writing), it is updated and the program continues to run. The program can then check the file status data item, determine from it that the disk is full and take the appropriate action.

Parent topic: File Status
Related information
Defining a File Status Data Item
File Status Conventions
Extended File Status Codes


Defining a File Status Data Item

Each file in a program can have a file status data item associated with it by specifying FILE STATUS IS in the SELECT clause for the file and defining the file status data item in the Working-Storage Section:

 select in-file
     assign to "user.dat"
     file status is ws-file-status.
      ...
 working-storage section.
     01 ws-file-status        pic xx.

A separate data item can be used for each file or a single data item can be used for multiple files.

File status is a two-byte code. For all file status conventions, except extended file status codes, the data item is defined as two alphanumeric characters (PIC XX). For extended file status codes, the second byte contains a binary number.

The first byte of the file status data item is known as status key 1 and indicates one of the following conditions upon completion of an I/O operation:

Value | Condition
0 | Successful operation
1 | AT END
2 | Invalid key
3 | Permanent error
4 | Logic error (improper sequence of I/O operations)
9 | COBOL run-time system error message

If the first byte of the file status data item is other than 9, the second byte (known as status key 2) is an alphanumeric character.

If the first byte of the file status data item is 9, the second byte is a binary field containing a run-time system error code.

The example code that follows illustrates how file status checking is performed: first the first byte (status key 1) is interrogated; then, if more information is required, the second byte (status key 2) is interrogated.

     select recseq
         assign to "recseq.dat"
         file status is ws-file-status
         organization is record sequential.
 ...
 file section.
 fd recseq
     record contains 80 characters.
 01 recseq-fd-record    pic x(80).
 ...
 working-storage section.
 01 ws-file-status.
     05 status-key-1     pic x.
     05 status-key-2     pic x.
     05 binary-status redefines status-key-2  pic 99 comp-x.
 ...
 procedure division.
     ...
     perform check-status.
     ...
 check-status.
     evaluate status-key-1
      when "0"
         next sentence
      when "1"
         display "end of file reached"
         perform check-eof-status
      when "2"
         display "invalid key"
         perform check-inv-key-status
      when "3"
         display "permanent error"
         perform check-perm-err-status
      when "4"
         display "logic error"
      when "9"
         display "run-time-system error"
         perform check-mf-error-message
     end-evaluate.
     ...
 check-eof-status.
     if status-key-2 = "0"
         display "no next logical record"
     end-if.
     ...
 check-inv-key-status.
     evaluate status-key-2
        when "2" display "attempt to write dup key"
        when "3" display "no record found"
     end-evaluate.
     ...
 check-perm-err-status.
     if status-key-2 = "5"
         display "file not found"
     end-if.
     ...
 check-mf-error-message.
     evaluate binary-status
      when 002 display "file not open       "
      when 007 display "disk space exhausted"
      when 013 display "file not found      "
      when 024 display "disk error          "
      when 065 display "file locked         "
      when 068 display "record locked       "
      when 039 display "record inconsistent "
      when 146 display "no current record   "
      when 180 display "file malformed      "
      when 208 display "network error       "
      when 213 display "too many locks      "
      when other
         display "not error status "
         display binary-status
     end-evaluate.
Parent topic: File Status
Related information
What is File Status?
File Status Conventions
Extended File Status Codes


File Status Conventions

This COBOL system supports a number of file status conventions. Each convention has a separate set of codes defined, although there is some overlap between conventions.

The conventions supported are:

  • ANSI'85 File Status
  • ANSI'74 File Status
  • RM/COBOL
  • IBM Mainframe COBOL
  • Microsoft COBOL V2 File Status
  • ANSI'85 File Status
  • ANSI'74 File Status
  • File Status Conversions
Parent topic: File Status
Related information
What is File Status?
Defining a File Status Data Item
Extended File Status Codes


ANSI'85 File Status

If you are using the standard system loaded for ANSI'85 operation, ANSI'85 file status codes are produced by default.

Parent topic: File Status Conventions
Related information
ANSI'74 File Status
File Status Conversions


ANSI'74 File Status

If you compile your program with the Compiler directive NOANS85, ANSI'74 file status codes are produced.

If you need to use ANSI'85 syntax, but have ANSI'74 file status codes then replace the NOANS85 directive with ANS85"SYNTAX".

Parent topic: File Status Conventions
Related information
ANSI'85 File Status
File Status Conversions


File Status Conversions

For emulation purposes, you can arrange to return file status codes other than ANSI'85 and ANSI'74. To do so:

  1. Use the CONVERTSTATUS File Handler configuration option to specify the name of a program that is called to map returned status values. The program name depends upon the type of compiler:
    Compiler | CONVERTSTATUS=
    RM/COBOL | rmstat
    IBM Mainframe COBOL | hoststat
    Microsoft COBOL V2 | msstat

    You can add the CONVERTSTATUS parameter to the File Handler configuration file extfh.cfg. For more information, see the topic File Handler Configuration.

  2. When compiling, use the following compiler directives:
    • NOANS85
    • COBFSTATCONV
Note: A list of Microsoft COBOL V2 file status codes is given in the topic Microsoft COBOL V2 File Status Codes.
Parent topic: File Status Conventions
Related information
ANSI'85 File Status
ANSI'74 File Status
Microsoft COBOL V2 File Status Codes
File Handler Configuration


Extended File Status Codes

The ANSI'74 and ANSI'85 file status conventions are augmented with extended file status codes. Extended file status codes have the character "9" as the first byte of the file status. The second byte is a binary (COMP-X) number, which is equivalent to a run-time system error number.

Extended file status codes are written as 9/nnn where nnn is the binary number in the second byte.

For example, if you are writing a file to disk and the disk runs out of space, the ANSI'74 file status would be a "30", which translates into the error message:

Permanent error - no other information is available

This error message is very general; a "permanent error" could mean that the disk has failed, or that the disk drive door is open. So, rather than return a generic file status, this COBOL system returns an extended file status of 9/007, that is, the character "9", in the first byte, and the binary value 7 in the second, meaning "disk full".

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.

When using ANSI'74 or ANSI'85 file status codes, the run-time system returns extended file status codes if the extended file status code is more specific.

The example code that follows illustrates how to redefine a standard file status so that it can be used as an extended file status. Assume for this example that the input file does not exist - when the OPEN INPUT statement is executed, a file status of 9/013 ("File not found") is returned.

     select in-file
         assign to "user.dat".
         file status is file-status.
        ...
 working-storage section.
 01 file-status.
     05 status-key-1             pic x.
     05 status-key-2             pic x.
     05 status-key-2-binary redefines status-key-2
                                 pic 99 comp-x.
     ...
 procedure division.
     open input in-file
     if file-status not = "00"
         if status-key-1 = "9"
             if status-key-2-binary = 13
                 display "File not found"
        ...

To display the extended file status code, move the second byte of the file status data item to a display field large enough to hold the maximum value 255:

     select in-file
         assign to "user.dat"
         file status is file-status.
 ...
 working-storage section.
 01 ans74-file-status.
     05 status-key-1              pic x.
     05 status-key-2              pic x.
     05 status-key-2-binary redefines status-key-2
                                  pic 99 comp-x.
 01 display-ext-status
     05 filler                    pic xx value "9/"
     05 display-key 2             pic 999
     ...
 procedure division.
     open input in-file
     if file-status not = "00"
         display "Error. File status =" with no advancing
         if status-key-1 = "9"
             move status-key-2-binary to display-key-2
             display display-ext-status
         else
             display file-status
         end-if
     end-if
Parent topic: File Status
Related reference
Run-time System Error Messages
Example of Extended File Status Codes
Related information
What is File Status?
Defining a File Status Data Item
File Status Conventions
Data Related


Sharing Files

  • Sharing mode
  • Record Locking
  • File Status Codes
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


Sharing mode

The sharing mode indicates whether a file is to participate in file sharing and record locking.

Three sharing modes are available:

Sharing Mode | Description
SHARING WITH NO OTHER | Do not allow sharing with any other user of this file
SHARING WITH READ ONLY | Allow sharing with other users who have the file opened for input
SHARING WITH ALL OTHER | Allow sharing with all other users

For a full table showing the results when an OPEN is attempted in the various sharing modes, see the table Opening available shared files that are currently open by another file connector in the topic The OPEN Statement.

To specify one of these sharing modes, use the SHARING phrase either on an OPEN statement or as part of the SELECT clause. The SHARING phrase in the OPEN statement overrides that in the SELECT clause.

If you do not include the SHARING phrase in either the SELECT clause or the OPEN statement, the sharing mode is determined when the first of the following conditions is satisfied:

If You Specify ... | Sharing Mode
The WITH LOCK phrase on the OPEN statement | SHARING WITH NO OTHER
The LOCK MODE IS EXCLUSIVE phrase in the SELECT clause | SHARING WITH NO OTHER
Either the LOCK MODE IS MANUAL phrase or the LOCK MODE IS AUTOMATIC phrase in the SELECT clause | SHARING WITH ALL OTHER
The open mode as OUTPUT, I-O or EXTEND | SHARING WITH NO OTHER
The open mode as INPUT and the configuration option OPENINPUTSHARED set to OFF | SHARING WITH READ ONLY
The open mode as INPUT and the configuration option OPENINPUTSHARED set to ON | SHARING WITH ALL OTHER
Parent topic: Sharing Files
Related reference
Sharing Mode
The File Control Entry
File Handler Configuration Options
Related information
Record Locking
File Status Codes
The OPEN Statement


Record Locking

If file sharing is in effect, you can set locks on individual records. In this way, you can prevent other users from accessing the locked records whilst enabling these users to access other unlocked records.

Note: You cannot lock records in either a line sequential file or a file that you have opened for input.
  • Manual and Automatic Record Locking
  • Single and Multiple Record Locking
  • Handling Record Locks
  • Releasing Record Locks
Parent topic: Sharing Files
Related information
Sharing mode
File Status Codes


Manual and Automatic Record Locking

To lock a record, use either manual or automatic record locking.

  • Manual Record Locking
  • Automatic Record Locking
Parent topic: Record Locking
Related information
Single and Multiple Record Locking
Handling Record Locks
Releasing Record Locks


Manual Record Locking

If you are using manual record locking, use the READ statement to acquire a record lock.

To specify manual locking, use:

  1. The LOCK MODE IS MANUAL clause in the SELECT clause for the file
  2. The WITH LOCK clause on the READ statement

For example:

 select fd-name
     assign to "muser.dat"
     lock mode is manual
   ...
     read fd-name with lock
Parent topic: Manual and Automatic Record Locking
Related information
Automatic Record Locking


Automatic Record Locking

If you are using automatic record locking, the READ statement acquires a record lock automatically. To avoid locking a record, use the WITH NO LOCK clause in the READ statement.

Note: When the RM Compiler directive is set, automatic record locking is enabled by default.

To specify automatic locking, use the LOCK MODE IS AUTOMATIC clause in the SELECT clause for the file:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic
   ...
     read fd-name
Parent topic: Manual and Automatic Record Locking
Related information
Manual Record Locking


Single and Multiple Record Locking

You can lock either a single record or multiple records.

  • Single Record Locking
  • Multiple Record Locking
Parent topic: Record Locking
Related information
Manual and Automatic Record Locking
Handling Record Locks
Releasing Record Locks


Single Record Locking

If you are using single record locking, you can hold one record lock only at any one time. Each new i-o operation on the file releases any previous lock.

To specify single record locking, do not use the WITH LOCK ON MULTIPLE RECORDS clause after either the LOCK MODE IS MANUAL clause or the LOCK MODE IS AUTOMATIC clause.

Parent topic: Single and Multiple Record Locking
Related information
Multiple Record Locking


Multiple Record Locking

Multiple record locking permits many record locks to be held at once.

To specify multiple record locking, follow either the LOCK MODE IS MANUAL clause or the LOCK MODE IS AUTOMATIC clause with the WITH LOCK ON MULTIPLE RECORDS clause. For example:

 select fd-name
     assign to "muser.dat"
     lock mode is automatic with lock on multiple records
   ...
Note:
  • If you do not use the WITH LOCK ON MULTIPLE RECORDS clause, single record locking takes effect
  • If you specify multiple record locking for a file and you use the WRITELOCK Compiler directive when you compile your program, the program also acquires a record lock whenever it accesses the file with a WRITE or REWRITE statement
Parent topic: Single and Multiple Record Locking
Related information
Single Record Locking


Handling Record Locks

By default, when a read operation encounters a locked record, the operation returns a locked record status.

The operation will update the record area to show the contents of the record unless you set the environment variable ES_RLS_FILE_SUPPORT=Y, and set the /t parameter in the Fileshare Server configuration file to zero.

After this operation, the current record pointer remains associated with the locked record, so that a following READ NEXT operation continues to try and access the same record.

The following configuration options affect this behavior:
Configuration Option | Description
IGNORELOCK | When set to ON, specifies that record locks are to be ignored. When set to INPUT, specifies that record locks are to be ignored when reading files open for input.
RETRYLOCK | When set to ON, specifies that operations that try to read locked records should be retried until the operation is successful. Can also be set to an integer, which specifies the maximum number of retries before the operation is aborted.
LOCKTYPE | When set to 1, record locks are placed on the record itself, which means that a read operation that meets a locked record cannot return the data record. In this case the contents of the record area following the read are undefined.
SKIPLOCK | When set to ON specifies that, following a read encountering a locked record, a READ NEXT operation returns the following record
Note: To bypass the locked record, you can also use the START…KEY IS GREATER THAN.. statement.
Parent topic: Record Locking
Related information
Manual and Automatic Record Locking
Single and Multiple Record Locking
Releasing Record Locks


Releasing Record Locks

When the program that acquired the lock does one of the following, the action releases all record locks:

  • Closes the file
  • Executes a COMMIT statement
  • Executes a ROLLBACK statement
  • Executes an UNLOCK statement on the file
  • Deletes the locked record

Additionally, when the program that acquired the lock accesses any other record in the file with any file operation, except START, this action releases single record locks.

Parent topic: Record Locking
Related information
Manual and Automatic Record Locking
Single and Multiple Record Locking
Handling Record Locks


File Status Codes

If your program runs in a multi-user environment, you should always check for the following file status codes:

File Status Code | Description
9/065 | This status code is returned by an OPEN statement and indicates that the file is locked.
9/068 | This status code is returned by a READ, DELETE or REWRITE statement and indicates that the record is locked.
9/213 | This status code indicates that the maximum number of permitted locks has been reached. The maximum number of permitted locks depends on your network and/or operating system.
Parent topic: Sharing Files
Related information
Sharing mode
Record Locking


File Handler Configuration

  • Configuration File
  • Configurable Behavior
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler and Sort APIs
Sort Utilities
Data and Key Compression
Tracing File Operations


Configuration File

The default filename for the File Handler configuration file is extfh.cfg but you can use a different filename by setting the EXTFH environment variable. For example:

EXTFH=/mydir/test.cfg
export EXTFH
sets the filename to /mydir/test.cfg.

The File Handler searches for the configuration file in the following order:

  1. The file specified by the EXTFH variable.
  2. The file $COBDIR/etc/extfh.cfg.
  3. The file extfh.cfg in the current directory.
Parent topic: File Handler Configuration
Related reference
Format of the Configuration File
Related information
Configurable Behavior
Configuration File Options


Configurable Behavior

Those aspects of the File Handler's behavior which can be configured via the File Handler configuration file and require some further explanation than is given in the online help file, are detailed below.

  • Large Indexed Files
  • File Striping (deprecated)
  • Performance
Parent topic: File Handler Configuration
Related information
Configuration File


Large Indexed Files

By default, the File Handler can handle files that are up to a maximum of 32 Terabytes in size. However many operating systems have a limit on file size: in order to create large files on these systems, use IDXFORMAT"8".

Parent topic: Configurable Behavior
Related information
File Striping (deprecated)
Performance


File Striping (deprecated)

Note: This function is deprecated, and provided for backward compatibility only. We recommend that you use IDXFORMAT"8" instead.

The file striping option enables you to create logical files that are up to 512 Gigabytes in size. These logical files can comprise up to 256 physical files.

As these large logical files comprise multiple physical files, you cannot enable file striping on a global basis as this could lead to the operating system running out of file handles. You need to decide, therefore, the files on which you are going to use striping.

  • Headers in Striped Files (deprecated)
  • Options (deprecated)
  • Examples (deprecated)
Parent topic: Configurable Behavior
Related information
Large Indexed Files
Performance


Headers in Striped Files (deprecated)

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

In a striped file, the header of an individual stripe is 128 bytes long. The header contains an ASCII string of the form:

Stripe number nnn of file: filename

where nnn is a three-digit number containing the stripe number, and filename is the name of the associated file.

The string is padded with spaces up to the end of the 128 byte header.

Parent topic: File Striping (deprecated)
Related information
Options (deprecated)
Examples (deprecated)


Options (deprecated)

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

Striping options are not case sensitive.

Note:
  • If a striped file is in use, the required striping options must be present in the File Handler configuration file each time the file is opened
  • If file striping is enabled for a file and one of the stripes is deleted (or becomes unusable for any other reason, such as disk failure), the entire file becomes unusable
  • MAXSTRIPEDIGITS (deprecated)
    Specifies the number of digits to be appended to the name of the base file when naming the stripes. For example, if STRIPETYPENAME is 0, 2 would give test01.dat and 5 would give test00001.dat or tes0001.dat depending on the filename limitations of the operating system. The default value of n is 2. The minimum value is 1 and the maximum value is 5.
  • MAXSTRIPEFILES (deprecated)
    Specifies the number of stripe files, not including the base file. By default, 17 files are created, the base file and 16 stripes. The minimum value of n is 1 and the maximum value is 255.
  • MAXSTRIPESIZE (deprecated)
    Specifies the maximum size in bytes of an individual stripe. The default for n is 1 Gigabyte (1073741824 bytes). The minimum value is 65536 bytes. The maximum value is currently 2 Gigabytes (2147483648 bytes).
  • STRIPE-X (deprecated)
    Specifies the path and size for a stripe file where x is the stripe number, path is the location at which this stripe can be found and n is the size of the stripe. If n is omitted, the size is the same as that of the previous stripe.
  • STRIPENAMETYPE (deprecated)
    This option specifies the file naming convention used to name the stripes. The default setting is 0.
  • STRIPING (deprecated)
    Specifies whether a file is a striped file. The default setting is OFF.
Parent topic: File Striping (deprecated)
Related information
Headers in Striped Files (deprecated)
Examples (deprecated)


MAXSTRIPEDIGITS (deprecated)

Syntax:

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
MAXSTRIPEDIGITS=n
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEFILES (deprecated)
MAXSTRIPESIZE (deprecated)
STRIPE-X (deprecated)
STRIPENAMETYPE (deprecated)
STRIPING (deprecated)


MAXSTRIPEFILES (deprecated)

Syntax:

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
MAXSTRIPEFILES=n
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEDIGITS (deprecated)
MAXSTRIPESIZE (deprecated)
STRIPE-X (deprecated)
STRIPENAMETYPE (deprecated)
STRIPING (deprecated)


MAXSTRIPESIZE (deprecated)

Syntax:

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
MAXSTRIPESIZE=n
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEDIGITS (deprecated)
MAXSTRIPEFILES (deprecated)
STRIPE-X (deprecated)
STRIPENAMETYPE (deprecated)
STRIPING (deprecated)


STRIPE-X (deprecated)

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

Once set, the new path and size apply to all stripes until changed by another STRIPE-X option. The number following Stripe- is the stripe number, with 0 indicating the base file. For stripes other than the base file, the number must not start with a 0 character.

Syntax:

STRIPE-X=path[,n]
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEDIGITS (deprecated)
MAXSTRIPEFILES (deprecated)
MAXSTRIPESIZE (deprecated)
STRIPENAMETYPE (deprecated)
STRIPING (deprecated)


STRIPENAMETYPE (deprecated)

Syntax:

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
STRIPENAMETYPE=[0/1]

Comments:

If StripeNameType is set to 0, the stripe files use the same filename as the base file, but with a stripe number appended to the basename, before the file extension. For example, if the file test.dat has 3 stripes, the base file and its stripes are called:

File | Description
test.dat | base file
test01.dat | stripe number 1
test02.dat | stripe number 2
test03.dat | stripe number 3

If the basename is too long to accommodate the stripe file number, characters are removed from the right of the basename. For example, if the file testfile.dat has 3 stripes, the file and its stripes are called:

File | Description
testfile.dat | base file
testfi01.dat | stripe number 1
testfi02.dat | stripe number 2
testfi03.dat | stripe number 3

If StripeNameType is set to 1, the stripe files use the same filename as the base file but with a stripe number appended to the filename, after the file extension. Note that the base file becomes stripe 0 and is renamed. For example, if the file test.dat has 3 stripes, the base file and its stripes are called:

File | Description
test.dat.00 | base file
test.dat.01 | stripe number 1
test.dat.02 | stripe number 2
test.dat.03 | stripe number 3
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEDIGITS (deprecated)
MAXSTRIPEFILES (deprecated)
MAXSTRIPESIZE (deprecated)
STRIPE-X (deprecated)
STRIPING (deprecated)


STRIPING (deprecated)

Syntax:

Note: This function is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
STRIPING=[ON/OFF]
Parent topic: Options (deprecated)
Related reference
MAXSTRIPEDIGITS (deprecated)
MAXSTRIPEFILES (deprecated)
MAXSTRIPESIZE (deprecated)
STRIPE-X (deprecated)
STRIPENAMETYPE (deprecated)


Examples (deprecated)

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

Below are several examples of how to specify file striping.

Example 1

The file test.dat has 2 stripes, each of the same size:

[test.dat]
Striping=on
Stripe-1=dir2
Stripe-2=dir3

This causes test.dat to be in the current directory, test01.dat to be in dir2 and test02.dat to be in dir3.

Example 2

The file test.dat has 5 stripes:

[test.dat]
Striping=on
Stripe-0=dir1
Stripe-4=dir2

This causes test.dat to be in dir1, test01.dat to be in dir1,test02.dat to be in dir1, test03.dat to be in dir1, test04.dat to be in dir2 and test05.dat to be in dir2.

Example 3

The file test.dat has 3 stripes:

[test.dat]
Striping=on
Stripe-0=dir1,100000000
Stripe-1=dir2,200000000

This causes test.dat to be in dir1 with a file size of 100000000 bytes and test01.dat to be in dir2 with a file size of 200000000 bytes.

Parent topic: File Striping (deprecated)
Related information
Headers in Striped Files (deprecated)
Options (deprecated)


Performance

You can take various steps to improve the performance of the File Handler. These all involve the use of various configuration options. Details are as follows:

  • You can increase the number of indexed file nodes that are cached, as opposed to being held on disk. You specify the number of nodes with the INDEXCOUNT configuration option. We recommend a setting of 32, but you can choose a larger number up to 64, for further improvement at the expense of memory usage
  • You can stop the File Handler from obtaining a semaphore when it executes an I/O operation that does not modify the file and the file is shared. In this context a semaphore is a lock applied to a reserved location in the file, which inhibits access to the file by more than one user. This extra call impairs performance. To stop the File Handler from obtaining a semaphore, set the READSEMA configuration option to OFF.
  • You can adjust the use of record locks. By default the File Handler:
    • Returns a locked-record file status when it finds a locked record, but also returns the data in the record area
    • Tests for the presence of a file lock when it executes a read operation that does not request a lock.

    Testing for the presence of a lock is expensive in terms of performance. You can eliminate this step by the use of either of the following configuration options:

    • LOCKTYPE. Set this to 1 to prevent access to locked records.
    • IGNORELOCK. Set this to ON to stop the File Handler testing for locks when it performs a READ operation that is not itself trying to obtain a lock.

    If you set LOCKTYPE to 1, the setting of IGNORELOCK is irrelevant

  • You can force the File Handler to load an entire file into memory when it opens the file, and to execute all file operations in memory, only writing it back to disk when it is closed. You force this behavior by setting LOADONTOHEAP to ON. This setting is available only for non-shared files. You should use this setting with care and only on small files.
Parent topic: Configurable Behavior
Related information
Large Indexed Files
File Striping (deprecated)


File Handler and Sort APIs

  • Calling the File Handler
  • Sort Module
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
Sort Utilities
Data and Key Compression
Tracing File Operations


Calling the File Handler

You can call the File Handler to perform common actions such as opening a file and reading a record in an efficient and consistent way.

  • Overview
  • Data Structures
  • Accessing the FCD
  • Operation Codes
  • Relative Byte Addressing
  • Creating Your Own File Handler
  • Dynamic Redirection to a Custom File Handler
  • Creating a New Index File
  • Sort Module
  • Compression Routines
Parent topic: File Handler and Sort APIs
Related information
Sort Module


Overview

You can make explicit calls to the Callable File Handler from your program using the following syntax:

call "EXTFH" using opcode fcd

where the parameters are:

Parameter | Description
"EXTFH" | The module name of the File Handler interface.
opcode | A File Handler operation code. See the section Operation Codes.
fcd | The data area, known as the FCD (File Control Description) which is used by the File Handler to hold details of the file being accessed. See the section Data Structures.

Before the first call, you must follow these steps:

  1. Allocate data areas for the File Control Description (FCD), the record area, the filename area and the key definition block (if the file is indexed)
  2. Initialize all the data areas to binary zeros to ensure that the File Handler does not receive invalid values
  3. Set the pointers in the FCD to point to the:
    • Record area
    • Filename area
    • Key definition block (indexed files only)

You must then follow these steps for each File Handler operation:

  1. Fill in the appropriate fields in the FCD for the selected operation code
  2. Call the File Handler
  3. Determine the success of the file I/O operation by checking the file status
  4. Process the FCD fields and/or any data in the record area

This documentation includes a tutorial demonstrating a number of file handling operations using the callable File Handler; see Tutorial: Using the Callable File Handler.

Parent topic: Calling the File Handler
Related information
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Data Structures

The File Handler uses four data structures during file I/O operations:

Data Structure | Description
File Control Description (FCD) | A 100-byte data area containing information about the file in use.
Record area | A data area into which records are read and from which records are written.
Filename area | A data area which contains the name of the file in use, as recognized by the operating system.
Key definition block | Used by the File Handler to hold index key information during operations on indexed files.
  • File Control Description (FCD)
  • Record Area
  • Filename Area
  • Key Definition Block
Parent topic: Calling the File Handler
Related information
Overview
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


File Control Description (FCD)

The File Control Description (FCD) is a data area which contains information about the file in use. There are two versions of the FCD, and which one is used depends on whether your COBOL development environment is running in 32-bit or 64-bit, as shown in the following table:

COBOL Development System | FCD Used
Visual COBOL | FCD3
Mainframe Express | FCD2
32-bit Visual COBOL | FCD3
64-bit Visual COBOL | FCD3
Managed COBOL support within Visual COBOL | FCD3
32-bit Server Express | FCD2 or FCD3
64-bit Server Express | FCD3

Both FCD2 and FCD3 format can be used in 32-bit compilations. The copybook XFHFCD.CPY defines an FCD3 record unless the program is compiled with the Compiler directive NOFCD3. If the program is compiled with the NOFCD3 directive XFHFCD.CPY defines an FCD2 record. The FCD3 record is directly and unconditionally defined in the file xfhfcd3.cpy and the FCD2 record is directly and unconditionally defined in the file xfhfcd2.cpy.

To use the File Handler, your program must set up an FCD, complete the appropriate fields (these vary according to the operation code) and then call the File Handler. All unused or reserved areas of the FCD must be set to binary zeros. The File Handler returns information to your program by writing it to the appropriate fields in the FCD.

Note: Regardless of the system you are using, you must set the fcd-version field to the appropriate value for the FCD that you are using (0 for FCD2, 1 for FCD3); otherwise some of the operation codes will not behave as expected.

The FCD used on the call to open a file must be the one used on all subsequent accesses to that file. You can perform multiple open operations on a file but you must use a different FCD for each open.

The FCD includes pointers (that is, USAGE POINTER data items) that point to the record area, filename area and key definition block.

Parent topic: Data Structures
Related information
Record Area
Filename Area
Key Definition Block


Record Area

The record area is a data area into which records are read, and from which records are written.

The size of the record area must be four bytes larger than the largest record in the file.

The following example shows how the FCD is set up to point to the record area:

 01 RECORD-AREA      PIC X(85).
   ...
     SET FCD-RECORD-ADDRESS TO ADDRESS OF RECORD-AREA
       ...
Parent topic: Data Structures
Related information
File Control Description (FCD)
Filename Area
Key Definition Block


Filename Area

The filename area is a data area which contains the name of the file in use, as recognized by the operating system.

It can contain drive and/or path information as well as the actual name of the file. The name must be terminated by a space.

This filename area must be filled before the first operation on the file.

The following example shows how the FCD is set up to point to the filename area:

 01 FILENAME-AREA    PIC X(65) VALUE "master.dat".
   ...
     MOVE 65 TO FCD-NAME-LENGTH
     SET FCD-FILENAME-ADDRESS TO ADDRESS OF FILENAME-AREA
       ...
Parent topic: Data Structures
Related information
File Control Description (FCD)
Record Area
Key Definition Block


Key Definition Block

The key definition block is used to pass index key information to the File Handler when opening an indexed file. It consists of three data areas.

  • Global Information Area
  • Key Definition Area
  • Component Definition Area
Parent topic: Data Structures
Related information
File Control Description (FCD)
Record Area
Filename Area


Global Information Area

The size of the key definition area and the number of keys that are in the file are held in the global information area.

Parent topic: Key Definition Block
Related reference
Global Information Area
Related information
Key Definition Area
Component Definition Area


Key Definition Area

The key definition area describes the keys used in the indexed file.

The key definition area follows the global information area and contains one key definition for each key in the file.

You must define all keys before their components.

The order in which keys are defined is important as the ordinal position of the key is used to identify it. For example, if you have an indexed file with a prime key and two alternate keys, the Key Definition area contains three key definitions: the prime key is key 0, the first alternate is key 1, and the second alternate is key 2.

Parent topic: Key Definition Block
Related reference
Key Definition Area
Related information
Global Information Area
Component Definition Area


Component Definition Area

The component definition area follows the key definition area.

It contains a definition for each key component. Each key consists of one component, unless defined as a split key, when each component of the key requires its own component definition.

The component definitions define the position and length of the key component.

For numeric keys, you can use the component definition Area to specify the numeric type. You can then use the IXNUMKEY Compiler directive to specify that keys are ordered according to numeric type (the default situation is that keys are ordered according to their alphanumeric value).

Parent topic: Key Definition Block
Related reference
Component Definition Area
Related information
Global Information Area
Key Definition Area


Accessing the FCD

When file I/O operations are performed by your program, using ordinary COBOL syntax, a File Control Description (FCD) is created automatically for each file. You can access this automatically created FCD by compiling your program with the FCDREG Compiler directive. This enables you to read or change the FCD or to use it to make explicit calls to the File Handler.

To access the FCD, you must set up an FCD definition in the Linkage Section of your program. An example FCD definition is supplied in the copybook XFHFCD.CPY. This definition can be mapped onto the FCD you need to read or alter using the following SET statement in your program:

     set address of fcd to address of fh--fcd of file

where the parameters are:

fcd
The name of the FCD definition in the Linkage Section of your program
fh--fcd
The FCD used by this COBOL system to access the file (note the double hyphen)
file
The FD name of the file

Following this SET operation, you can access the file's FCD by accessing the data items in the FCD which you set up in your Linkage Section.

Similarly, you can access the key definition block as follows:

     set address of kdb to address of fh--keydef of file

where the parameters are:

kdb
The name of the key definition block in the Linkage Section of your program
fh--keydef
The key definition used by this COBOL system to access the file (note the double hyphen)
file
The FD name of the file
Parent topic: Calling the File Handler
Related information
Overview
Data Structures
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Operation Codes

Each file operation which can be performed by the File Handler is identified by a two-byte operation code.

There are two types of operation code:

Type of Operation Code | Description
Standard operation codes | The codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.
Special operation codes | The codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.

Full lists of standard and special operation codes and links to detailed information are provided in the topics Standard Operation Codes - Overview and Special Operation Codes - Overview.

Parent topic: Calling the File Handler
Related reference
Standard Operation Codes - Overview
Special Operation Codes - Overview
Related information
Overview
Data Structures
Accessing the FCD
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Relative Byte Addressing

The relative byte address of a record is placed in fcd-reladdr-offset in the FCD (or fcd-reladdr-big if bit 4 of fcd-config-flags is set) by all File Handler operations that involve specific records. To use the relative byte address of a record, simply save the contents of this field after a READ operation.

Using the relative byte address is a fast method of accessing records, but has limitations of which you should be aware:

  • A relative byte address operation does not affect the current record pointer. Therefore, a READ (sequential) after a relative byte address operation returns the record after the last one accessed using normal access methods. It does not return the record after the one you accessed using the relative byte address. It is possible, however, to update the current record pointer to point to the record you accessed using relative byte addressing by setting bit 5 of fcd-config-flags in the FCD before calling the File Handler to perform the relative byte address operation.
  • Relative byte address operations update the index when a record is rewritten or deleted.
  • If a record has been deleted since the relative byte address for it was obtained, a read or write using its relative byte address usually fails. However, it is possible for it to have been replaced by a different record and for this to go undetected.

Record locking is supported with relative byte address operations.

Once you have obtained the relative byte address of a record, you can use it to perform a number of operations.

  • Read a Record
  • Rewrite a Record
  • Delete a Record
Parent topic: Calling the File Handler
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Read a Record

You can read a specific record from a file in two ways using the relative byte address:

  • Put the address in fcd-reladdr-offset or fcd-reladdr-big in the FCD and set bit 6 of fcd-config-flags in the FCD. If you want to update the current record pointer, set bit 5 of fcd-config-flags.
  • Perform a READ (random) WITH NO LOCK, READ (random) WITH LOCK, READ (random) WITH KEPT LOCK or READ (random) operation on the file

The READ (direct) operations work in the same way, but do not require the bits in the FCD to be set. The READ (direct) operations always return the record at the address given in the relative byte address field of the FCD and update the current record pointer.

Both of the above methods provide a way of switching the current key-of-reference to a different key. For example, if READ (sequential) operations are performed via the prime key, you can start reading via the first alternate key from the current record using the following steps:

  1. Read the next record in the file (the address of this record is in the FCD relative byte address field)
  2. Put the new key-of-reference in fcd-key-id in the FCD
  3. Perform a READ (direct) operation to return the record at this address. The key-of-reference is changed to the new one
  4. Read the next record in the file. This is the next record in the new key-of-reference index
Parent topic: Relative Byte Addressing
Related information
Rewrite a Record
Delete a Record


Rewrite a Record

You can rewrite a record to a specific address by putting that address in fcd-reladdr-offset or fcd-reladdr-big in the FCD and setting bit 6 of fcd-config-flags in the FCD.

If you need to update the current record pointer, set bit 5 of fcd-config-flags in the FCD.

You then perform a REWRITE operation.

Parent topic: Relative Byte Addressing
Related information
Read a Record
Delete a Record


Delete a Record

You can delete a record at a specific address by putting that address in fcd-reladdr-offset or fcd-reladdr-big in the FCD and setting bit 6 of fcd-config-flags in the FCD.

You then perform a DELETE operation.

Parent topic: Relative Byte Addressing
Related information
Read a Record
Rewrite a Record


Creating Your Own File Handler

You can create your own, customised, file handler and use this in place of the File Handler supplied with your COBOL system.

To force programs to use your file handler for processing COBOL I/O syntax, use the CALLFH Compiler directive. For example, if you have a file handler called USERFH, compile your programs with the directive:

CALLFH"USERFH"

This causes all COBOL I/O operations to be compiled into calls to USERFH.

Alternatively, you can create a custom file handler that is dynamically loaded and invoked at run time by the Micro Focus File Handler. This removes the need to recompile the COBOL program performing the file I/O. For more information, see the section Dynamic Redirection to a Custom File Handler.

Important:
  • You must specify the NOCANCEL directive to stop your handler being canceled at STOP RUN before all the user programs have been canceled.
  • If you use CBL_EXIT_PROC, you must set the priority to 200, so that when the application calling your file handler terminates, your file handler shuts down properly.
Parent topic: Calling the File Handler
Related reference
CANCEL
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Dynamic Redirection to a Custom File Handler

The run-time system can load and invoke a custom file handler module without requiring the recompilation of the COBOL program performing the file I/O for which the custom file handler is to be used.

This can be enabled by either creating a list of file handlers to be called in turn or by using a configuration file that maps files to File Handlers.

  • Redirection Using Configurable DYNREDIR
  • Specifying a List of Custom File Handlers
  • Specifying Configurable Custom File Handlers
  • Writing a Custom File Handler
  • Restrictions
Parent topic: Calling the File Handler
Related reference
CANCEL
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Creating a New Index File
Sort Module
Compression Routines


Redirection Using Configurable DYNREDIR

When configured in this way, files are mapped to file handlers using the fhredir.cfgfile. If custom file handlers are not present, an XFHLOG entry will be emitted and the Micro Focus File Handler will be invoked instead. Up to three different custom file handlers can be used at any given time.

Parent topic: Dynamic Redirection to a Custom File Handler
Related information
Specifying a List of Custom File Handlers
Specifying Configurable Custom File Handlers
Writing a Custom File Handler
Restrictions


Specifying a List of Custom File Handlers

To specify your a list of custom file handlers, you use the DYNREDIR environment variable, as shown below:

set DYNREDIR=mod1!ep1[:mod2!ep2[:mod3!ep3]]
export DYNREDIR

where:

modn | is the module containing a custom file handler
epn | is the name of a custom file handler's entry point
Note: Parsing of the DYNREDIR environment variable stops if modn or epn is longer than 30 characters. If this happens, the custom file handler with the name that is longer than 30 characters and any custom file handlers defined after it are ignored.

For example, setting DYNREDIR as shown below specifies three separate file handlers:

set module1!userfh1:userfh2:module3!userfh3
export DYNREDIR

The file handlers specified are:

  • userfh1 in the module1shared library
  • userfh2
  • userfh3 in the module3shared library

If a module is configured for a given file handler, that module is loaded during Micro FocusFile Handler initialization.

Parent topic: Dynamic Redirection to a Custom File Handler
Related concepts
Redirection Using Configurable DYNREDIR
Related information
Specifying Configurable Custom File Handlers
Writing a Custom File Handler
Restrictions


Specifying Configurable Custom File Handlers

To specify your configurable custom file handlers, you use the DYNREDIR environment variable, as shown below:

set DYNREDIR=DYNCONFIG[:EXPAND]

where:

DYNCONFIG | enables configurable DYNREDIR
EXPAND | enables relative filename expansion of paths

When configurable DYNREDIR is enabled, the file/custom file handler mapping is taken from your fhredir.cfg file, which is pointed to by the environment variable FHREDIR. Entries for directories/files that use a custom file handler should be added to the file.

See the topic Configuration in the Fileshare Guide for details on mapping files to custom file handlers.

If you want to change configuration settings for custom DYNREDIR without stopping and restarting your system, your application can make a call to CBL_CFGREAD_DYNFH. For more information, see the library routine topic CBL_CFGREAD_DYNFH.

Note:
  • Restrictions for Client configuration apply to custom file handlers.
  • Filename mappings occur prior to the call to the custom file handlers.
  • Calls to FS_LOCATE_FILE will be routed to the custom file handler.
Parent topic: Dynamic Redirection to a Custom File Handler
Related concepts
Redirection Using Configurable DYNREDIR
Related information
Specifying a List of Custom File Handlers
Writing a Custom File Handler
Restrictions


Writing a Custom File Handler

When writing a custom file handler you must ensure that it:

  • conforms to the standard Micro Focus Call Handler interface. See the section Calling the File Handler for more information.

    Additionally, once a custom file handler has determined whether or not it will perform the I/O operations for a file, it must set the RETURN-CODE to 1 (to indicate that it will perform the file's I/O operations) or to 0 (to indicate that it will not).

    If a custom file handler sets RETURN-CODE to 0, the next specified custom file handler is tried. If no other custom file handler has been specified, the file's I/O operations are processed by the File Handler.

  • is compiled with CALLFH(EXTFH), CALLFH(MFFH) or CALLFH(FHREDIR). See The CALLFH Directive for more information.
  • does not call the Micro Focus File Handler (in order to avoid problems with recursion).
Note: For concatenated files, custom file handlers that use DYNREDIR are called for each part of the concatenated file. In such cases, the custom file handler is called using the original unmapped name. A file handler that uses DYNREDIR must handle the opening and closing of each individual file that creates the concatenated file.

The final CLOSE operation is called with the initial file handle that was returned by the first OPEN operation.

Parent topic: Dynamic Redirection to a Custom File Handler
Related concepts
Redirection Using Configurable DYNREDIR
Related reference
CALLFH
Related information
Specifying a List of Custom File Handlers
Specifying Configurable Custom File Handlers
Restrictions


Restrictions

You should note the following restrictions in behavior when using your own file handler:

  • Filenames passed to the custom file handler in the FCD are as specified by the caller; that is, they are not mapped.
  • The module name and entry point name for a custom file handler can each be up to 30 characters long.
  • The behavior of other file handling functionality (such as XFHTRACE and Rebuild) is undefined when using custom file handlers.
  • For configurable DYNREDIR, the format of the fhredir entries are the same as for the Fileshare server and have the same limitations.
  • Configurable DYNREDIR and non-configurable DYNREDIR cannot be used at the same time.
Parent topic: Dynamic Redirection to a Custom File Handler
Related concepts
Redirection Using Configurable DYNREDIR
Related information
Specifying a List of Custom File Handlers
Specifying Configurable Custom File Handlers
Writing a Custom File Handler


Creating a New Index File

You can use special operation codes to recreate an index file from the data file part of an existing indexed file as follows:

  1. Create the new index file using CREATE INDEX FILE (special operation code x"07")
  2. Read each record from the data file using GET NEXT RECORD (special operation code x"08")
  3. For each key value in the record, add the key value to the index file using ADD KEY VALUE (special operation code x"09")

The following example shows you how to create a new index file from an existing data file:

 78 close-file                  value x"fa80"
 78 open-new-index              value x"0007".
 78 get-next-rec                value x"0008".
 78 add-key-value               value x"0009".
   ...
     move open-new-index to fh-opcode
     perform extfh-op
     move get-next-rec to fh-opcode
     perform extfh-op
     perform until fcd-status (1:1) not = "0"
         perform varying fcd-key-id from 0 by 1
                   until fcd-key-id = key-count
                      or fcd-status (1:1) not = "0"
             move add-key-value to fh-opcode
             perform extfh-op
         end-perform
         move get-next-rec to fh-opcode
         perform extfh-op
     end-perform
     move close-file to fh-opcode
     perform extfh-op
     ...
 extfh-op.
     call "EXTFH" using fh-opcode, fcd
     if fcd-status of fcd (1:1) = "1"
         move 1 to return-code
     end-if.
Parent topic: Calling the File Handler
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Sort Module
Compression Routines


Sort Module

The Sort Module is a standalone sort module that enables you to sort and merge data files. It is invoked implicitly when your COBOL program uses the SORT or MERGE statements.

When you perform a SORT operation on a data file, any records with duplicate keys are returned in their original order, regardless of whether or not the DUPLICATES IN ORDER phrase was specified on the SORT statement.

To call the Callable Sort Module explicitly to sort or merge your files, include the following call statement in your program:

call "EXTSM" using function-code, sort-fcd

where the parameters are:

function-code
A two-byte code indicating the type of operation to be performed. For more information see the topic Sort Module Function Codes.
sort-fcd
The name of the Sort File Control Description (FCD) as specified in the Data Division of your program. The FCD contains pointers to the record area, filename, collating sequence, key definition block and file definition block for the file. You need to specify, in the Data Division of your program, a Sort FCD for each file involved in the SORT operation. For more information see the topic Sort File Control Description.
Parent topic: Calling the File Handler
Parent topic: File Handler and Sort APIs
Related reference
Sort Module Function Codes
Sort File Control Description
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Compression Routines
Calling the File Handler


Compression Routines

You can call the compression routines that the File Handler uses to compress data and keys in your own applications. For full details see the section Compression Routines in the chapter Data and Key Compression.

Parent topic: Calling the File Handler
Related information
Overview
Data Structures
Accessing the FCD
Operation Codes
Relative Byte Addressing
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler
Creating a New Index File
Sort Module
Compression Routines


Sort Utilities

  • Introduction
  • Invoking Mfsort
  • Creating a Statistics Report
  • Example Commands
  • Error Messages
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Data and Key Compression
Tracing File Operations


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.
Parent topic: Sort Utilities
Related reference
The SORT Statement
Sort Module
Related information
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


Invoking Mfsort

You can invoke mfsort from the command line in one of the following ways:

mfsort instructions
mfsort take filename

where the parameters are:

Parameter Description
instructions Mfsort instructions.
When specifying instructions on the command line:
  • The maximum length of the mfsort command is 1024 characters. Characters after this limit are ignored, and if this truncation causes an invalid command, an error is produced.
  • Allow the shell to pass through special characters such as parentheses or comment characters (*) in one of the following ways:
    • Use quotes """" to enclose parentheses
    • Place an escape character \ directly in front of a parenthesis or a comment character
filename A text file containing mfsort instructions. See the section Instructions. Use this method if you need to specify a lot of instructions.

This file must be a line sequential file, and the first 256 characters are processed as the command line. Characters that exceed this limit are processed separately if they form a valid command; however, this may result in undesired sort results. If this truncation causes an invalid or incomplete command, an error is produced.

  • Instructions
Parent topic: Sort Utilities
Related information
Introduction
Creating a Statistics Report
Example Commands
Error Messages
Instructions


Instructions

The following is a list of valid mfsort instructions:

Instruction | Meaning
* | The rest of the line is treated as a comment. This is useful if you are supplying instructions via a text file as you can add comments to the file which explain the purpose of each instruction.
CHAR-EBCDIC | EBCDIC data. CHAR-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SIGN-EBCDIC | Numeric DISPLAY items with included signs are interpreted according to the EBCDIC convention. SIGN-EBCDIC is not required when CHAR-EBCDIC is specified; it is required for data that is otherwise ASCII, such as when the program which created the data was compiled with the SIGN"EBCDIC" Compiler directive. SIGN-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SORT-EBCDIC | Record-sequential ASCII files are sorted in EBCDIC order. Important: SORT-EBCDIC cannot sort files that have keys containing non-printable characters.
SORT/MERGE | These instructions specify either a sort or a merge option and must be followed by a FIELDS instruction specifying the field(s) to be used. The FIELDS instruction may optionally be followed by a RECORD instruction specifying the record size and format of the work file. SORT and MERGE are mutually exclusive.
FIELDS (instructions) | The fields on which the file is to be sorted or merged. See the section Fields Instruction.
RECORD definition | Record size and format. A RECORD instruction can be used to specify these details for the work file, input file(s) and output file(s). See the section RECORD Instruction.
USE input-file | Each USE instruction specifies an input file. You must specify all USE instructions before any GIVE instructions. See the section Defining Input and Output Files.
GIVE output-file | Each GIVE instruction specifies an output file. See the section Defining Input and Output Files.
INCLUDE/OMIT | Specifies conditions in which records will be included or omitted from the sort process. For details, see the IBM documentation to be found on the IBM Knowledge Center. INCLUDE and OMIT are mutually exclusive.
INREC | Reformats records before the SORT/MERGE process.
OUTREC | Reformats records following the SORT/MERGE process.
MODS | Specifies external procedures (user exits) that are executed, each time a record is released to or returned from the SORT/MERGE process. This implementation supports the E15 and E35 user exits.
SUM | Specifies that records with the same key value are returned as a single record. Optionally, a field may be specified to accumulate totals for all records with equal keys. The SUM operation can be done for the following control field types:
OUTFIL | This is used to specify complex editing and reporting to one or more output files. Each output file should be specified using a GIVE command. Otherwise, OUTFIL works as described in the IBM documentation, found on the IBM Knowledge Center.
OPTION | This can be used to specify various options. One of these options is COPY which results in records being copied, rather than sorted, to the output file.
  • FIELDS Instruction
  • Defining Input and Output Files
Parent topic: Invoking Mfsort
Related information
Invoking Mfsort
Fields Instruction
RECORD Instruction
Defining Input and Output Files


FIELDS Instruction

A SORT or MERGE instruction must be followed by a FIELDS instruction which specifies the fields on which the input file is to be sorted or merged.

A fields instruction takes the following form:

fields({start,length,type,order},...)

where the parameters are:

Parameter | Description
start | The starting position of the field in the record, counting in bytes from 1
length | The length of the field (bytes)
type | The type of data in the field. See the section Field Types .
order | The ordering of output, which can be either of: A - ascending D - descending

You can specify up to 100 fields by repeating the parameter set (start, length, type and order). Use commas to separate the parameters and the parameter sets.

  • Field Types
Parent topic: Instructions


Field Types

The following is a list of some of the available field types:

Field Type | Definition
AQ | Character with alternate collating sequence.
BI | COMP
C5 | COMP-5
C6 | COMP-6
CH | PIC X DISPLAY
CX | COMP-X
FL | Floating point, signed.
FS/CSF | Signed numeric, with optional leading floating sign.
LI/OL/CLO | PIC S9 LEADING INCLUDED
LS/CSL | PIC S9 LEADING SEPARATE
NU | PIC 9 DISPLAY
PD | PIC S9 COMP-3
PD0 | Packed decimal with first semi-byte and sign semi-byte ignored.
SB/FI | PIC S9 COMP
S5 | S9 COMP-5
SS | Substring. Used in conditions only.
TS/CST | PIC S9 TRAILING SEPARATE
TI/ZD/OT/CTO | PIC S9 TRAILING INCLUDED
Y2B | Two-digit, one-byte binary year data.
Y2C/Y2Z | Two-digit, two-byte year data, with optional trailing included sign. PIC 99 or PIC S99.
Y2D | Two-digit, one-byte packed decimal year data. PIC 99 COMP-6.
Y2P | Two-digit, two-byte packed decimal year data. PIC 99 COMP-3.
Y2S | Two-digit, two-byte character year data with special indicators. Binary zeros, blanks and binary ones are treated as special cases.
Y2T | Full date format, yyx...
Y2U | Full date format, yyx..., COMP-3.
Y2V | Full date format, yyx..., COMP-3. Ignores first semi-byte.
Y2W | Full date format, x...yy.
Y2X | Full date format, x...yy, COMP-3.
Y2Y | Full date format, x...yy, COMP-3. Ignores first semi-byte.

You can find other field types defined in the IBM documentation at SORT Control Statement.

Suppose that golf.dat is a relative file defined in a COBOL program as follows:

 file-control.
     select members-file
         assign to "/home/user/workarea/golf.dat"
         organization is relative
         access mode is random
         relative key is relative-key.
 data division.
 file section.
 fd members-file
     record contains 28 characters.
 01 members-record.
     03 members-number pic 9(6).
     03 members-lname pic x(10).
     03 members-fname pic x(10).
     03 members-handicap pic 9(2).

You can then use the following mfsort command to sort the file golf.dat on the field containing the membership number in ascending order:

mfsort sort fields(1,6,nu,a)
   use golf.dat record f,28 org rl
   give members.dat

The sorted version of the file is written to the file members.dat.

Parent topic: FIELDS Instruction


Defining Input and Output Files

You need to give instructions to define both the input and output files:

File Instructions
Input
USE input-file [record definition]
   [org organization] [key structure]
Output
GIVE output-file [record definition]
   [org organization] [key structure]
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

You can create a statistical report by using the MFJSTATS environment variable. For more information, see the section MFJSTATS in the appendix Environment Variables in your User's Guide.

Parent topic: Sort Utilities
Related information
Introduction
Invoking Mfsort
Example Commands
Error Messages


Example Commands

This section gives some examples of mfsort commands and jobstreams.

You may find it helpful to refer to the Examples of DFSORT Job Streams section of your DFSORT Application Programming Guide.

  • Sorting Using More Than One File
  • Single File Sort Using INCLUDE and a Sub-string Comparison
  • Single File Sort Using Environment Variables
  • Transforming Records Using OUTREC
  • Sort Using OUTFIL for Complex Reporting
Parent topic: Sort Utilities
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Error Messages


Sorting Using More Than One File

Imagine four indexed files (north.dat, south.dat, east.dat and west.dat) which contain for the north, south, east and west of the country the scores achieved by members of a national organisation in a national competition. The COBOL syntax used to define north.dat is shown below:

 file-control.
     select idxfile assign to "north.dat"
         organization is indexed
         record key is member-id.
 data division.
 file section.
 fd idxfile
     record contains 39 characters.
 01 idxfile-record.
     03 member-id  pic 9(6).
     03 surname    pic x(15).
     03 first-name pic x(15).
     03 score      pic 9(3).

Each of the other files has been created in the same way and the results of the competition have been entered in the files. The following examples use these files.

  • Character Sort in Ascending Order
  • Numeric Sort in Descending Order
  • Omitting Records
Parent topic: Example Commands


Character Sort in Ascending Order

The following mfsort commands takes all of the records from each of the four files, sorts them on the member's surname in ascending order and outputs the result to the relative file members.dat:

mfsort sort fields(7,15,ch,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give members.dat org rl
Parent topic: Sorting Using More Than One File


Numeric Sort in Descending Order

The following mfsort command takes each of the four files, sorts them on the member's score (highest score first) and outputs the result to the relative file scores.dat:

mfsort sort fields(37,3,nu,d)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give scores.dat org rl
Parent topic: Sorting Using More Than One File


Omitting Records

The following mfsort command takes each of the four files, sorts them on the membership number (which is the primary key) and outputs the result to the indexed file national.dat. All records for which the score field is less than 20 are omitted:

mfsort sort fields(1,6,nu,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give national.dat
   omit cond (37,3,nu,lt,20)
Parent topic: Sorting Using More Than One File


Single File Sort Using INCLUDE and a Sub-string Comparison

The following mfsort command takes a line sequential file, sortin.dat and sorts its records on a character field starting at position 11 with a length of 4 bytes. The results are output to the file sortout.dat which will include only records for which the sub-string, starting at position 15 of length 3 bytes, is equal to any three consecutive characters in the string 'J69,L92,J82'.

mfsort sort fields=(11,4,ch,a)
   use sortin.dat org ls record (f 80)
   give sortout.dat
   include cond=(15,3,ss,eq,c'J69,L92,J82')
Parent topic: Example Commands


Single File Sort Using Environment Variables

The following mfsort command takes a text file, unsorted.txt and a file a.1, sorts its records in ascending order, and outputs the result to the file sorted.txt.

set $infile=unsorted.txt
set $outfile=sorted.txt

mfsort take a.1

where unsorted. txt contains:

BBBBBBBBBBBBBBBBBBBB
CCCCCCCCCCCCCCCCCCCC
AAAAAAAAAAAAAAAAAAAA

and a.1 contains:

use $infile org LS
sort
give $outfile
Parent topic: Example Commands


Transforming Records Using OUTREC

The following mfsort command transforms records containing a field of format cyymmdd to the format yyymmdd.

Sort C'cyymmdd'
     SORT FIELDS=(1,7,BI,A)        * sort C'cyymmdd'
     use mfs110a.in org ls record (f 40)
    * Transform C'cyymmdd' to C'yyyymmdd'
     OUTFIL OUTREC=(1,1,CHANGE=(2, * change C'c' as follows:
                      C'0',C'19',  *   C'0' to C'19'
                      C'1',C'20',  *   C'1' to C'20'
                      C'2',C'21'), *   C'2' to C'21'
                      NOMATCH=(C'99')
                    2,6)           * copy C'yymmdd'

     give sortout.dat
Parent topic: Example Commands


Sort Using OUTFIL for Complex Reporting

The following is an example of how to use the OUTFIL command to produce a complex report, in this case a Profit and Loss report for one of four divisions. The input file, mfs121a.dat is sorted on the first two fields and only records from the western region are output. The SECTIONS instruction produces a page throw when the field starting in position 3, length 10 bytes changes. The following shows:

  • The input data
  • The mfsort command
  • The resultant output
  • Input Data
  • Mfsort Command
  • Output
Parent topic: Example Commands


Input Data

  Chips        San Martin     0088902203 West
  Chips        Oakland        0023412432 West
  Chips        San Jose       0123213335 West
  Ice Cream    Marin          0054234123 West
  Chips        Gilroy         0055484342 West
  Ice Cream    Napa           0085734283 West
  Pretzels     San Jose       0123488534 West
  Ice Cream    San Francisco  0092231245 West
  Chips        San Francisco  000324343q West
  Chips        San Jose       0123213335 South
  Ice Cream    San Martin     0100346730 West
  Pretzels     Marin          0534332344 West
  Chips        Gilroy         0055484342 South
  Chips        Morgan Hill    0098732232 West
  Pretzels     Morgan Hill    0084384340 West
  Ice Cream    San Jose       000002345u West
  Pretzels     Napa           0531234856 West
  Chips        Oakland        0023412432 South
  Pretzels     San Martin     000023438r West
  Chips        Los Angeles    000223401t West
  Ice Cream    Marin          0054234123 South
  Pretzels     San Francisco  0541230005 West
  Ice Cream    Napa           0085734283 South
  Pretzels     San Jose       0123488534 South
  Ice Cream    San Francisco  0092231245 South
  Chips        San Francisco  000324343q South
  Ice Cream    San Martin     0100346730 South
  Pretzels     Marin          0534332344 South
  Chips        Morgan Hill    0098732232 South
  Pretzels     Morgan Hill    0084384340 South
  Ice Cream    San Jose       000002345u South
  Pretzels     Napa           0531234856 South
  Pretzels     San Martin     000023438r South
  Chips        Los Angeles    0002234014 South
  Pretzels     San Francisco  0541230005 South
Parent topic: Sort Using OUTFIL for Complex Reporting
Related information
Mfsort Command
Output


Mfsort Command

SORT FIELDS=(3,10,A,16,13,A),FORMAT=CH

  use mfs121a.dat  org ls record (f 80)
  OUTFIL
   INCLUDE=(42,6,CH,EQ,C'West'),
   HEADER1=(5/,18:'    Western Region',3/,
               18:'Profit and Loss Report',3/,
               18:'     for  ',&DATE,3/,
               18:'      Page',&PAGE),
   OUTREC=(6:16,13,24:31,10,ZD,M5,LENGTH=20,75:X),
   SECTIONS=(3,10,SKIP=P,
    HEADER3=(2:'Division:  ',3,10,5X,'Page:',&PAGE,2/,
             6:'Branch Office',24:'       Profit/(Loss)',/,
             6:'-------------',24:'--------------------'),
    TRAILER3=(6:'=============',24:'====================',/,
             6:'Total',24:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
             6:'Lowest',24:MIN=(31,10,ZD,M5,LENGTH=20),/,
             6:'Highest',24:MAX=(31,10,ZD,M5,LENGTH=20),/,
             6:'Average',24:AVG=(31,10,ZD,M5,LENGTH=20),/,
             3/,2:'Average for all Branch Offices so far:',
                X,SUBAVG=(31,10,ZD,M5))),
    TRAILER1=(8:'Page ',&PAGE,5X,'Date:  ',&DATE,5/,
            8:'Total Number of Branch Offices Reporting:  ',
              COUNT,2/,
            8:'Summary of Profit/(Loss) for all',
              ' Western Division Branch Offices',2/,
            12:'Total:',
                22:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
            12:'Lowest:',
                22:MIN=(31,10,ZD,M5,LENGTH=20),/,
            12:'Highest:',
                22:MAX=(31,10,ZD,M5,LENGTH=20),/,
            12:'Average:',
                22:AVG=(31,10,ZD,M5,LENGTH=20))
      give outfil1.dat
Parent topic: Sort Using OUTFIL for Complex Reporting
Related reference
Input Data
Related information
Output


Output

                     Western Region

                 Profit and Loss Report

                      for  11/05/95

                       Page     1
************************************************************
  Division:  Chips          Page:     2

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Gilroy                     554,843.42
     Los Angeles                (22,340.14)
     Morgan Hill                987,322.32
     Oakland                    234,124.32
     San Francisco              (32,434.31)
     San Jose                 1,232,133.35
     San Martin                 889,022.03
     =============     ====================
     Total                    3,842,670.99
     Lowest                     (32,434.31)
     Highest                  1,232,133.35
     Average                    548,952.99

 Average for all Branch Offices so far:     548,952.99
************************************************************
  Division:  Ice Cream      Page:     3

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                      542,341.23
     Napa                       857,342.83
     San Francisco              922,312.45
     San Jose                      (234.55)
     San Martin               1,003,467.30
     =============     ====================
     Total                    3,325,229.26
     Lowest                        (234.55)
     Highest                  1,003,467.30
     Average                    665,045.85

 Average for all Branch Offices so far:     597,325.02
************************************************************
  Division:  Pretzels       Page:     4

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                    5,343,323.44
     Morgan Hill                843,843.40
     Napa                     5,312,348.56
     San Francisco            5,412,300.05
     San Jose                 1,234,885.34
     San Martin                  (2,343.82)
     =============     ====================
     Total                   18,144,356.97
     Lowest                      (2,343.82)
     Highest                  5,412,300.05
     Average                  3,024,059.49

 Average for all Branch Offices so far:   1,406,236.51
************************************************************
        Page      5     Date:  11/05/95

       Total Number of Branch Offices Reporting:        18

       Summary of Profit/(Loss) for all Western Division
          Branch Offices

           Total:          25,312,257.22
           Lowest:            (32,434.31)
           Highest:         5,412,300.05
           Average:         1,406,236.51
Parent topic: Sort Using OUTFIL for Complex Reporting
Related reference
Input Data
Related information
Mfsort Command


Workfile

During a sort or merge operation, mfsort uses a temporary workfile. This workfile is paged to disk in the current directory or, if it is set, in the directory specified by the TMPDIR environment variable. If not set, the current working directory is used.

Mfsort copies all the records from each of the input files to the temporary workfile, truncated or padded as appropriate. The workfile is then sorted or merged according to its key description. After being sorted or merged in the workfile, the records are copied to each of the output files and truncated or padded as appropriate.

During this operation:

  • If you do not need any of the records to be truncated, you must ensure that the record length of the workfile is sufficient for the longest record to be sorted
  • If your input files are of variable length and the sort workfile is not, all concept of variable-length is lost
  • If your input file is fixed length and the workfile is variable length, the record length of the record in the workfile is either the fixed length of the input file or the maximum record length of the workfile, whichever is the smaller


Error Messages

A full list of mfsort error messages is given in the topic Mfsort Error Messages.

Parent topic: Sort Utilities
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Mfsort Error Messages


Data and Key Compression

  • Data Compression
  • Key Compression
  • Example of Using Data and Key Compression
  • Compression Routines
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Tracing File Operations


Data Compression

Data compression enables you to compress the data in a sequential or indexed file. There are two compression mechanisms provided with this COBOL system, run-length encoding (type 1), and extended run-length encoding (type 3).

When a file is defined with run-length encoding, any string of repeating characters is stored as a single character with a repetition count.

You enable data compression using the DATACOMPRESS Compiler directive.

Specifying data compression for a fixed structure sequential file changes it into a variable structure sequential file.

The compression used by a file is determined by the last processed DATACOMPRESS directive when the SELECT statement for the file is processed. Consequently, the compression type can be set for an individual file by using a line of the form:

$SET DATACOMPRESS

immediately before its SELECT statement. You must not forget to turn it off with a $SET NODATACOMPRESS before any other files are processed.

For details on the DATACOMPRESS Compiler directive, see the topic DATACOMPRESS.

Note:

We recommend that you do not use the REWRITE statement on compressed sequential files. This is because a REWRITE operation will only succeed if the length of the compressed new record is the same as the length of the compressed old record.

Parent topic: Data and Key Compression
Related reference
Line Sequential File Structure
Printer Sequential File Structure
Fixed Format Record Sequential File
Fixed Format Relative File
Standard File Header
Standard Record Header
Variable Format Record Sequential File
Variable Format Relative Structure
Index Files - Overview
Types of Indexed File
DATACOMPRESS
Related information
Key Compression
Example of Using Data and Key Compression
Compression Routines


Key Compression

Key compression is a technique that can be applied to the keys of an indexed file. There are four types of compression available:

  • Compression of trailing nulls
  • Compression of trailing spaces
  • Compression of identical leading characters
  • Compression of duplicate alternate key values.

You can specify key compression using the KEYCOMPRESS option in the File Handler configuration file. Use the following integers to indicate which type of compression you want:

1
Duplicate key compression.
2
Leading character compression.
4
Trailing space compression.
8
Trailing null compression.

You can add these numbers together to specify a combination of compression types (with the exception of trailing nulls and trailing spaces which are mutually exclusive).

Alternatively, you can use the KEYCOMPRESS Compiler directive when compiling the program.

The key compression used by a file is determined by the last processed KEYCOMPRESS directive when the SELECT statement for the file is processed so you can set key compression for an individual file by using a line of the form:

$SET KEYCOMPRESS"8"

immediately before its SELECT statement in your program. You can turn it off again by specifying $SET NOKEYCOMPRESS before any other files are processed.

  • Compression of Trailing Nulls
  • Compression of Trailing Spaces
  • Compression of Leading Characters
  • Compression of Duplicate Keys
Parent topic: Data and Key Compression
Related reference
KEYCOMPRESS
Related information
Data Compression
Example of Using Data and Key Compression
Compression Routines


Compression of Trailing Nulls

When a key is defined with compression of trailing nulls, trailing nulls in a key value are not stored in the file.

For example, assume you have a primary or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being nulls. Without compression, all 30 characters of the key are stored requiring 30 bytes. With compression of trailing nulls, only 11 bytes are required (10 bytes for the 10 characters of the key and 1 byte which is used to maintain a count of the trailing nulls).

Parent topic: Key Compression
Related information
Compression of Trailing Spaces
Compression of Leading Characters
Compression of Duplicate Keys


Compression of Trailing Spaces

When a key is defined with compression of trailing spaces, trailing spaces in a key value are not stored in the file. However, information is stored so that the key can be correctly located.

For example, assume you have a prime or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being spaces. Without compression, all 30 characters of the key are stored. With compression of trailing spaces, the key only occupies 11 bytes in the index file (10 bytes for the characters of the key and 1 byte as a count of the trailing spaces).

Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Leading Characters
Compression of Duplicate Keys


Compression of Leading Characters

When a key is defined with compression of leading characters, all leading characters that match leading characters in the preceding key are not stored in the index file. However, information is stored to enable the key to be correctly reconstructed.

For example, assume that records are written with the following key values in a key defined with compression of leading characters:

AXYZBBB BBCDEFG BBCXYZA BBCXYEF BEFGHIJ CABCDEF

The keys actually stored in the index file are:

AXYZBBB BBCDEFG XYZA    EF      EFGHIJ  CABCDEF
Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Trailing Spaces
Compression of Duplicate Keys


Compression of Duplicate Keys

When an alternate key is defined with compression of duplicates, only the first duplicate key is contained in the file. The rest are not stored, but information is stored to enable correct recreation of the keys.

For example, suppose you write a record with an alternate key value "ABC". If you have enabled compression of duplicate keys, and you write another record with the same key value, the file handler does not physically store the duplicate key value in the index file. However, the record is still available along the alternate key path.

Parent topic: Key Compression
Related information
Compression of Trailing Nulls
Compression of Trailing Spaces
Compression of Leading Characters


Example of Using Data and Key Compression

In the following program, data compression is specified for transfile but not for masterfile. For key compression, suppression of trailing spaces and of leading characters that are the same as in the previous key is specified for keys t-rec-key and m-rec-key. Suppression of repetition of duplicate keys is also turned on for m-alt-key-1 and m-alt-key-2.

$set callfh"extfh"
$set datacompress"1"
$set keycompress"6"
     select transfile
         assign to ...
         key is t-rec-key.
$set nokeycompress
$set nodatacompress
     select masterfile
         assign to ...
         organization is indexed
$set keycompress"6"
         record key is m-rec-key
$set keycompress"7"
         alternate key is m-alt-key-1 with duplicates
         alternate key is m-alt-key-2.
$set nokeycompress
Parent topic: Data and Key Compression
Related information
Data Compression
Key Compression
Compression Routines


Compression Routines

The routines that the File Handler uses to compress data are stand-alone modules. This means that you can use them in your own applications, or alternatively make the File Handler use your own data compression routine.

There can be up to 127 Micro Focus compression routines, and up to 127 user-supplied compression routines.

  • Micro Focus Compression Routines
  • Calling a Micro Focus Compression Routine
  • User-supplied Compression Routines
Parent topic: Data and Key Compression
Related information
Data Compression
Key Compression
Example of Using Data and Key Compression


Micro Focus Compression Routines

Micro Focus routines are stored in modules called CBLDCnnn, where nnn is within the range 001 to 127. To use Micro Focus compression routines, set fcd-data-compress in the FCD to a value between 001 and 127.

Routine CBLDC001

The compression routine CBLDC001 uses a form of run-length encoding. This is a method of compression that detects strings (runs) of the same character and reduces them to an identifier, a count and one occurrence of the character.

Note: The routine is not effective for use with files that contain significant occurrences of double-byte characters, including double-byte spaces, as these are not compressed.

The routine put special emphasis on runs of spaces, binary zeros and character zeros (that can be reduced to a single character) and printable characters (that are reduced to two characters consisting of a count followed by the repeated character).

In the compressed file, bytes have the following meanings (hexadecimal values shown):

20-7F | (most printable characters) normal ASCII meaning.
80-9F | 1-32 spaces respectively.
A0-BF | 1-32 binary zeros respectively.
C0-DF | 1-32 character zeros respectively.
E0-FF | 1-32 occurrences of the character following.
00-1F | 1-32 occurrences of the character following, and that it should be interpreted literally, not as a compression code. This is used when characters in the range 00-1F, 80-9F, A0-BF, C0-DF or E0-FF occur in the original data. (Thus, one such character is expanded to two bytes; otherwise, no penalty is incurred by the compression.)

Routine CBLDC003

Like CBLDC001, the CBLDC003 routine uses run-length encoding, but detects strings (runs) of single- or double-byte characters. This routine is therefore suitable for DBCS characters, but can also be used in place of CBLDC001.

The format of the compression is two header bytes followed by one or more characters. The bits in the header bytes indicate:

bit 15 | Unset - single character.
bit 14 | Set - compressed sequence. Unset - uncompressed sequence.
bit 0-13 | Compressed character(s) or count of uncompressed characters.

The length of the character string depends on the header bits:

bit 14 and 15 set | Two repeating characters.
Only bit 14 is set | One repeating character.
Otherwise | Between 1 and 63 uncompressed characters.
Parent topic: Compression Routines
Related information
Calling a Micro Focus Compression Routine
User-supplied Compression Routines


Calling a Micro Focus Compression Routine

For data file compression the File Handler calls the compression routine that you specify in the DATACOMPRESS Compiler directive.

To call a Micro Focus data compression routine use the syntax:

COBOL:

call "CBLDCnnn" using input-buffer,
                      input-buffer-size,
                      output-buffer,
                      output-buffer-size,
                      compression-type

C:

CBLDCnnn(input_buffer, &input_buffer_size,
         output_buffer, &output_buffer_size,
         &compression-type);

where the parameters are:

nnn | A data compression routine in the range 001 to 127.
input_buffer | A PIC X(size) data item. On entry to the routine it must contain the data to compress or decompress; maximum size is 65535.
input_buffer_size | A two-byte (int in C, PIC XX COMP-5 in COBOL) data item. On entry it must contain the length of data in the input buffer.
output_buffer | A PIC X(size) data item. On exit it contains the resulting data.
output_buffer_size | A two-byte (int in C, PIC XX COMP-5 in COBOL) data item. On entry it must contain the size of the output buffer available; on exit it contains the length of the data in the buffer.
compression-type | A one-byte (char in C, PIC X COMP-X in COBOL) data item. On entry this must specify if the input data is to be compressed or decompressed: 0 - compress 1 - decompress.

The RETURN-CODE special register indicates whether the operation succeeded or not. Compression or decompression fails only if the output buffer is too small to accept the results. 0 indicates success and 1 indicates failure.

Parent topic: Compression Routines
Related information
Micro Focus Compression Routines
User-supplied Compression Routines


User-supplied Compression Routines

User-supplied compression routines must be stored in modules called USRDCnnn, where nnn is within the range 128 to 255.

To call a user-supplied routine, use the same syntax as for calling a Micro Focus routine, but use the filename USRDCnnn instead of CBLDCnnn where nnn must be a value in the range 128 through 255.

To make your compression routine available to your system, you must create a callable shared object that can be called when needed.

You can map calls to data compression routines in programs from previous UNIX COBOL systems to the new calls using the cob option:

-m CBL_DATA_COMPRESS_nnn=CBLDCnnn
Note: Your compression routines must not make any calls to the File Handler, as this would result in a loop. If you need file access, use byte-stream file I/O.

Once you have enabled data compression for a file, you must always subsequently specify the same type of compression for that file. If you do not, you receive a run-time system error when you open the file.

Data compression has no effect on files other than those in indexed or record sequential format and is ignored at compile time for files that do not support it.

If you want to read a fixed-length sequential file that has had its data compressed, you must specify that the file is compressed in your program. You do this by specifying the DATACOMPRESS Compiler directive.

Parent topic: Compression Routines
Related information
Micro Focus Compression Routines
Calling a Micro Focus Compression Routine


Tracing File Operations

  • Introduction
  • Configuring Tracing and Logging
  • Dynamic Tracing
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
Filenames
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Data and Key Compression


Introduction

The File Handler includes tracing file operations that enable you to:

  • Set tracing on or off using file handler configuration parameters
  • Set a further level of tracing known as logging, again using file handler configuration parameters
  • Dynamically turn tracing on or off from your COBOL program, using library routines
Parent topic: Tracing File Operations
Related information
Configuring Tracing and Logging
Dynamic Tracing


Configuring Tracing and Logging

You use the File Handler configuration parameters TRACE, TRACEFILEEXTEND, TRACEFILENAME, LOG, and LOGFILENAME to control tracing and logging activities:

  • Set TRACE=ON to turn tracing on
  • Set TRACEFILEEXTEND=ON to indicate that you want trace information to be written to the end of the current trace file, if the trace file already exists
  • Set TRACEFILENAME=filename if you want the trace file to have a name other than the default, which is xfhtrace.xfh
  • Set LOG=ON to indicate that you want any unusual file-related situations, such as corrupted files, or automatic file recovery, to be recorded in a log file for later examination
  • Set LOGFILENAME=filename if you want the log file to have a name other than the default, which is xfhlog

You can set TRACE and LOG either globally or for individual files, but you can only set TRACEFILEEXTEND, TRACEFILENAME, and LOGFILENAME globally.

Here is an example configuration file:

[XFH-DEFAULT]
TRACE=OFF
TRACEFILENAME=/trace/mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=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 reference
LOG
LOGFILENAME
TRACE
TRACEFILEEXTEND
TRACEFILENAME
Related information
Introduction
Dynamic Tracing


Dynamic Tracing

You can turn tracing on and off from within a COBOL program either by setting the appropriate flags in the FCD or by using library routines. You might want to do this to focus on file handling problems in a subset of an application's operations. When you set FCD flags you do it for a particular file. When you use the library routines, the trace settings affect all the file operations executed by the program from that point on.

When you do dynamic tracing, you use two flags together. This is because file operations such as READs and WRITEs can be traced only if the OPEN operation was traced. If you execute a program with tracing turned off, open a file, then switch dynamic tracing on, the tracing mechanism won't be able to trace any subsequent operations. The best way to proceed is to switch dynamic tracing on for OPENs and CLOSEs at the beginning of the program, then switch tracing for all operations on and off as required. However, the tracing of OPEN and CLOSE operations on its own can also be useful.

  • Using the FCD to Control Tracing
  • Using Library Routines to Control Tracing
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging


Using the FCD to Control Tracing

To use the FCD flags you must have access to the FCD; see the topic Accessing the FCD in the section File Handler and Sort APIs.

File tracing is controlled by two flag bit settings within the FCD:

  • Bit 1 of fcd-flags-1 controls whether all file operations are traced.
  • Bit 3 of fcd-fs-flags controls whether OPEN and CLOSE operations only are traced.

Change these bit settings as required to control tracing for individual files.

Parent topic: Dynamic Tracing
Related concepts
Accessing the FCD
Related information
Using Library Routines to Control Tracing


Using Library Routines to Control Tracing

If you want to use dynamic tracing in a program you must first issue a call to the mFFH library routine or perform an I/O operation using a standard COBOL statement. This initializes the File Handler.

The library routines provide a means of obtaining the same tracing behavior as setting the FCD flags without the need to have the FCD available. All changes to tracing behavior made using the library routines affect all files subsequently accessed.

To control tracing, issue calls to the MFFH_MODIFY_TRACE library routine. You can:

  • Set the main tracing flag on and off
  • Set the OPEN/CLOSE tracing flag on and off
  • Disable a modification that you set earlier

To disable all the modifications that you have set, issue a call to the library routine MFFH_MODIFY_DISABLE.

For further information see the topics mFFH, MFFH_MODIFY_TRACE and MFFH_MODIFY_DISABLE.

Parent topic: Dynamic Tracing
Related information
Using the FCD to Control Tracing


File Systems

File systems on different operating systems can use different size addressing. Most current file systems use 32-bit or 64-bit addressing. The operating systems/file systems using these two sizes are listed in the links below.

The File Handler is configured to work with either 32-bit or 64-bit addressing by setting the FILEMAXSIZE configuration option. It is vital that all applications sharing a file use a File Handler that is configured in the same way, otherwise data corruption can occur.

You can configure the File Handler to use 32-bit addressing in a file system that uses 64-bit addressing. In this case, all files will be safely limited in size (to 32-bit addressing) by the File Handler.

  • 32-bit file systems
  • 64-bit file systems
  • File systems and FILEMAXSIZE
Parent topic: File Handling
Related information
File Handling Examples
File Handling Guide
Fileshare Guide


32-bit file systems

  • Windows (FAT)
  • UNIX without large file system enabled
Parent topic: File Systems
Related information
64-bit file systems
File systems and FILEMAXSIZE


64-bit file systems

  • Windows 2000 (NTFS)
  • UNIX large file system
  • Linux file systems
Parent topic: File Systems
Related information
32-bit file systems
File systems and FILEMAXSIZE


File systems and FILEMAXSIZE

The underlying file system affects the value to which this File Handler configuration option should be set.

CAUTION:
  • 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.
  • All applications accessing a file must run with the File Handler configured with the same value for FILEMAXSIZE.
  • Only 32-bit (4GB) support is provided for Novell systems.

In these situations you must set FILEMAXSIZE to 4.

Parent topic: File Systems
Related information
32-bit file systems
64-bit file systems


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 information
File Handling Examples
File Handling Guide
File Systems


Introduction

  • Overview
  • How Fileshare Works
Parent topic: Fileshare Guide
Related information
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling
Fileshare Server Messages


Overview

Fileshare is best suited to applications that share data files, concurrently, between many users, across a network. It supports all of the functionality provided by the base COBOL file handling system and provides several additional features:

  • Reduced network traffic
  • Transaction processing
  • Rollforward recovery logging
  • Logon and file open security checks

The ability of any one application to take advantage of these features depends on:

  • The way the application processes the shared data files
  • The type of data files the application shares
  • The operating system on which the Fileshare Server is running
  • The communications protocol being used between the Fileshare Client and the Fileshare Server

You do not need to make any program source code changes to use the basic Fileshare system. Source code changes are only needed to take advantage of some of the advanced features provided by Fileshare.

Parent topic: Introduction
Related information
How Fileshare Works


How Fileshare Works

Using the base COBOL file handling system, a typical COBOL I/O request to a shared data file causes the file handler to make several accesses to that data file across the network. See Figure 1.

Figure 1. Conventional Network
Conventional Network

With Fileshare, a program that needs to access a data file has its request processed by the File Handling Redirector (FHRedir) module. The FHRedir module sends the request over the network to a Fileshare Server that performs the low-level I/O operations and then passes the result of the I/O operation, including the file status, back to FHRedir. FHRedir returns the result to the program. See Figure 2.

Figure 2. Fileshare Network
Fileshare Network

A Fileshare System is made up of:

Fileshare Clients | A Fileshare Client comprises a user program, making data file I/O requests, via the FHRedir module. FHRedir redirects the I/O requests to a Fileshare Server.
Fileshare Servers | A Fileshare Server runs on the same machine as the data files that you want to access. The Fileshare Server accepts requests across the network from the Fileshare Client, processes them by calling a local copy of the Micro Focus File Handler and then returns the result to the Fileshare Client.
Note:
  • The Fileshare Server and the Fileshare Client can be running on the same physical machine. For example, with a multi-tasking operating system such as Windows, the Fileshare Client can run in one session and the Fileshare Server can run in another session. Using this method, you can develop Fileshare applications on a single PC without actually sending data across a network. You should be aware, however, that performance improvements will not be observed, as no network is being used.
  • You can also run the Fileshare Server in the same session as the Fileshare Client using the single user mode of operation. This enables you to take advantage of advanced Fileshare features, such as transaction processing, without the need for a network or multiple sessions. For more information on the single user mode of operation, see the section Single User Mode in the chapter Advanced Operations.

Since a single Fileshare Server processes all the requests from several Fileshare Clients, it can use a single copy of the Micro Focus File Handler, regardless of how many users are accessing the Fileshare Server. This has several advantages:

  • The Fileshare Server can open the data files exclusively making full use of both its own cache and the operating system's cache
  • The Fileshare Server does not need to obtain semaphores on the data file. Normally semaphores are needed to control concurrent access to shared data files.
  • The Fileshare Server can process record locks internally without the need to make calls to the operating system
Parent topic: Introduction
Related information
Overview
Single User Mode


Standard Operation

  • Fileshare Client
  • Fileshare Server
Parent topic: Fileshare Guide
Related information
Introduction
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling
Fileshare Server Messages


Fileshare Client

To enable your COBOL program to use Fileshare at the Fileshare Client machine, you need to do two things:

  • Force your program to pass file I/O requests to the File Handling Redirector module (FHR), thus creating a Fileshare Client
  • Configure your Fileshare Client, specifying the name of the Fileshare Server to connect to, and the communications protocol to use when connecting.

You might also need to configure CCI for the communications protocol you have chosen. For more details, please refer to:

  • Your online book Configuring CCI
  • Specifying the Fileshare Server
  • Specifying the Communications Protocol
  • Configuring Your Fileshare Client
  • Using the File Handling Redirector Module
  • FHREDIR Return Codes
Parent topic: Standard Operation
Related information
Fileshare Server


Specifying the Fileshare Server

Each Fileshare Server on the network is identified by a unique name, assigned when the Fileshare Server is started. The Fileshare Client uses this name to specify which Fileshare Server to use.

There are two ways to specify the Fileshare Server name:

  • As part of the filename in your program.

    This requires changes to your code.

  • In a Fileshare Client configuration file.

    This does not require changes to your code.

These methods are listed in the next two topics.

  • As a Filename
  • In a Configuration File
Parent topic: Fileshare Client
Related information
Specifying the Communications Protocol
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes


As a Filename

Specifying the server as a filename in your program overrides any configuration file settings.

Windows:

select account-file assign to	"$$server1\c:\accounts\main.dat"

This SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on drive c: on the Fileshare Server machine. The File Handling Redirector module passes the characters appearing after the text string $$server1\ to the Fileshare Server as the name of the file.

UNIX:

select account-file assign to	"$$server1//accounts/main.dat"

This SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on the Fileshare Server machine. The File Handling Redirector module passes the characters appearing after the text string $$server1/ to the Fileshare Server as the name of the file.

Parent topic: Specifying the Fileshare Server
Related information
In a Configuration File


In a Configuration File

To specify a default Fileshare Server, use the /s option in the Fileshare Client configuration file. For example:

Windows:

/s server2

UNIX:

-s server2

tells the Fileshare Client to use the default Fileshare Server named server2. The File Handling Redirector module redirects all file I/O to this server unless you:

  • Specifically define a file as a local file. See the section Client Configuration in the chapter Configuration for further information.
  • Specify that a file is on a different Fileshare Server, using the Fileshare Client configuration file. See the section Client Configuration in the chapter Configuration for further information
  • Specify a different Fileshare Server as part of the filename in your program (see above)
Note:

  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to the File Handling Redirector module on the first OPEN request passed by your program
Parent topic: Specifying the Fileshare Server
Related information
As a Filename
Client Configuration


Specifying the Communications Protocol

The default protocol for Fileshare over CCI is TCP/IP (CCITCP), and on UNIX platforms is the only supported protocol.

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
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
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Configuring Your Fileshare Client

The Fileshare Client configuration file is an ordinary text file that you can create using any text editor. By default, it is called fhredir.cfg. The Fileshare Client searches for this file in the current working directory of your application and then along the path specified by the COBDIR environment variable, if one has been set up. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable, for example:

Windows:

set FHREDIR=c:\client.cfg

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory on drive c:.

UNIX:

set FHREDIR=/client.cfg
export FHREDIR

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory.

Configuring the Fileshare Client enables you to specify how you want to treat your data files, that is, as either:

  • Local data files, located on the machine where the Fileshare Client is running. To access local data files, the Fileshare Client uses a local copy of the Micro Focus file handler. This is the default.
  • Remote data files, located on the machine where the Fileshare Server is running. To access remote files, I/O operations are redirected to the appropriate Fileshare Server by the File Handling Redirector module.

In order to redirect I/O operations successfully, the File Handling Redirector module needs to know:

  • Which Fileshare Server to communicate with
  • Which communications protocol to use when contacting the server
  • Fileshare Client Configuration Options
  • Example Client Configuration File
Parent topic: Fileshare Client
Related concepts
Fileshare Client Configuration Options
Specifying the Communications Protocol
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.
  • UNIX:
    • In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
    • Filenames are shown using the Windows file-naming convention. On UNIX, use the UNIX filenaming conventions.
Client Configuration Option Specifying
/bl
 Open a file exclusively to enable blocking, to improve performance.
/cm CCI-Protocol
 The default communications protocol for this Fileshare Client. Valid values for CCI-Protocol are listed in the table below.
/cm CCI-Protocol
/s ServerName
 The communications protocol to use when contacting the Fileshare Server, ServerName. Valid values for CCI-Protocol are listed in the table below.
/ct CCI-Timeout server-name
 The communications timeout period, specified in 1/10th seconds. The default is 1200 (120 seconds). See Configuring the CCI Timeout for more information.
/cr CCI-Timeout
 The connection retry timeout period, specified in 1/10th seconds. The default is 0. This timeout is only for the initial connection and only applies if the CCI module returns and is out of memory or resources. The client will re-attempt to connect at varying intervals up to the timeout period. However, the default is that the connection is only tried once.
/f Filename
/r Custom-File-Handler
 The data file Filename is a local file and should be actioned by the custom file handler. Repeat this option for every data file you want assigned to a specific custom file handler that is not the default File Handler. Valid values for Filename and Custom-File-Handler are listed in the table below.

This option only applies if the environment variable DYNREDIR is set to DYNCONFIG.

/f Filename
/s ServerName
 The data file Filename is a remote file on the Fileshare Server named server-name. Repeat this option for every data file you want assigned to a specific Fileshare Server that is not the default Fileshare Server. Valid values for Filename and ServerName are listed in the table below.
/f Filename
 Filename is a local data file held on the PC where the Fileshare Client resides. Valid values for Filename are listed in the table below.
/s ServerName
 The ServerName as a default Fileshare Server
/um
 Micro Focus Common Client (MFCC) shall be used to communicate with the Fileshare server/listener. MFCC can be configured using a mf-client.dat configuration file to automatically connect to servers on remote machines.
/ra
 The number of times a client will attempt to reconnect to a Fileshare server if its connection is lost. The default is 0. In a high availability environment fhredir will connect to a new fileshare listener if one becomes available.
/rd
 The length of time (in milliseconds) a client will wait between each re-connection attempt (specified by /ra). The default is 0.

Accesses to data files not directed to a particular Fileshare Server or not defined as local data files are directed to the default Fileshare Servers. The order in which the default Fileshare Servers are defined in the Fileshare Client configuration file is the order in which the Fileshare Client contacts each Fileshare Server in an attempt to locate the file.

If the data file is not found on any Fileshare Server, the request for that data file is directed to the first default Fileshare Server listed in the configuration file.

Valid values for options in the Fileshare Client configuration file are:

Option | Valid Values
CCI-Protocol

Windows:

  • TCP IP: /ccitcp
  • CCISMEM: /ccism

UNIX:

  • TCP IP: -ccitcp
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
Specifying the Communications Protocol
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:

Windows:

fs /s server1

UNIX:

fs -s server1

registers the name of the Fileshare Server as server1.

Note:

The Fileshare Server cannot be initialized unless it registers a name on the network. The server-name can be up to 16 characters in length, depending on the CCI protocol you are using.

Parent topic: Configuring the Fileshare Server
Related information
Specifying the Communications Protocol
Fileshare Server Configuration Options


Specifying the Communications Protocol

By default, the Fileshare Server uses CCITCP to communicate with Fileshare Clients using the TCP/IP protocol. 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: In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • UNIX: Filenames are shown using the Windows naming convention. On UNIX, use the UNIX file-naming conventions.
Server Configuration Options Specifying
/s server-name
 The name that the Fileshare Server registers on the network. This must be a character string up to 16 characters in length, depending on the CCI protocol that you are using. The name specified must be unique. If a Fileshare Server with the same name is already registered on the network, an error is returned.
/d database-reference-file
 The name of the database reference file that the Fileshare Server is to use. The database reference file is used to determine which additional Fileshare features you want to use.
/t timeout-period
 Setting the record lock timeout period after which the Fileshare Server releases all record locks held by a Fileshare Client and rolls back any outstanding transactions. The timeout period is specified in seconds. The default value is 60 seconds. Specifying a value of zero disables the timeout and record locks are only released under the control of your application program. Valid values are 0 thru 99999. The timeout only occurs if one Fileshare Client requests a record currently locked by another Fileshare Client.

Setting a value of zero in conjunction with setting the environment variable ES_RLS_FILE_SUPPORT=Y ensures that no information is returned to the record area following a READ operation on a locked record.

/m record-size
 The maximum record size that can be processed by the Fileshare Server. Setting a value lower than the default value reduces the amount of memory that the Fileshare Server needs to run. The record size is specified in kilobytes. Valid values are 16 thru 64. If you specify a value less than 16, the Fileshare Server uses a buffer size of 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:

Windows: ccitcp, or ccism UNIX: ccitcp

/pf password-file
 The name of the password file that the Fileshare Server uses.
/tr f
 Activating the Fileshare Server trace option on start-up. Trace messages are written to the screen and to a file called fsscreen.lst in the Fileshare Server's current directory. This option seriously impacts the Fileshare Server's performance, so you should only use it for problem investigation.
/sc
 Use this to get the best performance. Switching Fileshare into synchronous communications mode. This means that when there is nothing for Fileshare to process, it goes into a wait state until interrupted by a message from the communications layer. You need to use a password file, and provide a password for fsview so that you can shut down Fileshare remotely. You can shut it down from the screen, but you might need to wait up to two minutes before it responds to the screen action.
/ev event-emit
Indicates the types of error messages that are written to fsscreen.lst in order to cause events if you have Fileshare tracing enabled.
event-emit is any combination of IEWS, where
  • I = information
  • E = error
  • W = warning
  • S = severe
-b
 You must specify this if the Fileshare Server is to run as a background process. You can use it only on the command line.
/pt time
 Writes to fsscreen.lst details of processes that take longer than the time specified to complete. Time can be specified in 10ths of a second.
/fc
 Enables flush on commit, which flushes the cached file operations to disk after every COMMIT statement. Use this option in conjunction with /lw if you want to use advanced rollback recovery in the event of a device or operating system failure.
Note: Setting this option will degrade the performance of Fileshare.
/lw
 Enables write through 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.

  • Example Server Configuration File
Parent topic: Configuring the Fileshare Server
Related concepts
Handling Record Locks
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
  • 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
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
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
Enabling CCI Tracing
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
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
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
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 /opt/microfocus/VisualCOBOL/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

Windows:

fs /d dbase.ref /l \logdir\log.dat
fs /d dbase.ref /f test1.dat
fs /d dbase.ref /f test2.dat /o l
fs /d dbase.ref /f test3.dat /o s

UNIX:

fs -d dbase.ref -l /logdir/log.dat
fs -d dbase.ref -f test1.dat
fs -d dbase.ref -f test2.dat -o l
fs -d dbase.ref -f test3.dat -o s

This example specifies:

  • The database reference file is named dbase.ref
  • The log file is named log.dat in the logdir directory
  • Updates to the data file test1.dat are logged in the log file. By default, sequence number checking is on for any data file in the database reference file, and hence for this file
  • Updates to the data file test2.dat are not logged in the log file. The "/o l" option specifies that logging is omitted. However, sequence number checking is still active for this file.
  • Updates to the data file test3.dat are logged in the log file. However, sequence number checking is not activated for this data file. The "/o s" option specifies that sequence number checking is not used on this data file.
Parent topic: Database Sequence Numbering


Database Backup and Recovery

To alleviate data loss and optimize recovery time, ensure you back up your Fileshare database regularly.
  • Automatic Database Backup and Rollforward Recovery
    When basic logging is enabled, you can set Fileshare to back up and, if required, perform rollforward recovery each time Fileshare is started.
  • Hot Backups
    Hot backups enable you to take a backup of your database files and start a new log file without the need to shutdown and restart the Fileshare Server.
Parent topic: Database Integrity
Related information
Transaction Processing
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Reference File Maintenance
Best Practices for Backup and Recovery


Automatic Database Backup and Rollforward Recovery

When basic logging is enabled, you can set Fileshare to back up and, if required, perform rollforward recovery each time Fileshare is started.
Note: Automatic database backup and recovery is not supported if you have advanced logging enabled.

The recommended method of using Fileshare's basic recovery logging for rollforward recovery is:

  1. Periodically shut down the Fileshare Server
  2. Take a backup of all your database files
  3. Re-start the Fileshare Server with a fresh recovery log file

See the section Basic Recovery Logging for further details.

Fileshare can perform these actions automatically if you specify a backup directory-name in the database reference file using the /backup option. For example, the command:

fs /d dbase.ref /backup	/backdir

adds an entry to the database reference file called dbase.ref which specifies the backup directory as /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 /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 /backdir
fs /d dbase.ref /f /accounts/customer.txt
fs /d dbase.ref /f /finance/history.txt

These commands perform the following:

  • Create a database reference file called dbase.ref
  • Specify the recovery log file as logfile so that the first log file that the Fileshare Server creates is called logfile.L01
  • Specify that any updates to the files /accounts/customer.txt and /finance/history.txt are logged
  • Specify /backdir as the backup directory

On startup, the Fileshare Server automatically backs up these data files in the directory /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 /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.

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.

Note:
  • UNIX: In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • UNIX: Filenames are shown using the Windows naming convention. On UNIX, use the UNIX filenaming conventions.

Invoke the Database Reference File Maintenance Utility using the /d (database) option, for example:

fs /d dbase.ref [options]

where the parameters are:

dbase.ref
Name of the database reference file. If the database reference file does not exist, it is created.
options
These specify the operation to be carried out on the database reference file. Each initiation of the Database Reference File Maintenance Utility adds a record to or removes a record from the database reference file specified.

You can add several types of record to the database reference file.

  • Recovery Log File Records
  • Filename Record
  • File String Record
  • Backup Folder Record
Parent topic: Database Integrity
Related information
Transaction Processing
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Best Practices for Backup and Recovery
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:

  • Windows: Create a cobfhrdrpwd.dll containing your module and ensure it is on the search path, PATH (you can do that by copying the file on the search path).
  • UNIX: Create a cobfhrdrpwd shared object containing your module and ensure it is on the search path, LD_LIBRARY_PATH (or LIBPATH on AIX platforms).

You can create an object module and link it into any application executable as required.

Parent topic: Password System
Related information
Fileshare Client
Fileshare Server


Logon Validation Module

Introduction

If you have not activated the Fileshare Password System, the Fileshare Server validates requests to log on by calling the Fileshare Security Logon validation module (FSSecLog).

The FSSecLog module supplied with Fileshare allows any Fileshare Client to log on to a Fileshare Server. If you need to restrict the Fileshare Clients that can log on to a Fileshare Server, you must provide your own, alternative, FSSecLog module for the Fileshare Server to call.

For example, your own module can enable integration with the native operating system security, if this is needed.

The sequence of steps that your program and Fileshare follow is:

  1. Your program registers a user-ID and password by calling the File Handling Redirector password module (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 a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or LIBPATH on AIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
File Access Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


File Access Validation Module

Whenever a Fileshare Server receives an open request on a file from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open validation module (FSSecOpn).

The Fileshare Security at Open Validation module supplied with Fileshare allows any Fileshare Client to access a data file. If you need to restrict access to specific files, you must provide your own, alternative, Fileshare Security at Open Validation module for the Fileshare Server to call.

If the Fileshare Security at Open Validation module allows the file access, the operation is allowed to complete. If the module does not allow the file access, a file status of 9/037 "access denied" is returned to the Fileshare Client and the operation is not allowed to complete.

Note: This file access security check is entirely independent of the Fileshare Password System and the User Supplied Logon Validation Module.

The sequence of steps that your program and Fileshare follow are:

  1. Your program registers its user-ID and password with the File Handling Redirector password module. This information is used when the Fileshare Client first logs onto the Fileshare Server.
  2. When your program subsequently performs an I/O operation on a file that it does not have open (such as an Open or Delete file operation), the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn)

You can replace the supplied Fileshare Security at Open Validation module with one of your own in order to use your own criteria for validating the open request. Your new module must comply with the Fileshare Security at Open Validation module's interface described below

Syntax:

call "fssecopn" using filename
                      filename-length
                      operation-code
                      user-ID
                      return-status

Parameters:

filename
pic x(n).
filename-length
pic x(2) comp-x.
operation-code
pic x(2) comp-x.
user-ID
pic x(20).
return-status
pic x comp-x.

On Entry:

filename
The name of the data file that the Fileshare Client wants to open
filename-length
The length of filename
operation-code
The operation code specifying the I/O operation. These codes are those used by the Callable File Handler. See your online help for details on the Callable File Handler.
user-ID
The user-ID of the Fileshare Client making the open request

On Exit:

return-status
Set to 0 if the open request is allowed. Any other status indicates that the Fileshare Client is not allowed to open the data file and an error status is returned.

Comments:

You can create your own fssecopn module, link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or LIBPATH on AIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
Logon Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


Password File Maintenance

The password file contains details of user-IDs and passwords that the Fileshare Server uses when Fileshare Password Security is enabled. Because the information in the password file is encrypted for security reasons, you can only add records to and remove records from the password file using the Password File Maintenance Utility.

UNIX:

Note:
  • In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • Filenames are shown using the Windows naming convention. On UNIX, use the UNIX filenaming conventions.

Use the /pf (password file) option to add or remove entries in the password file, for example:

fs /pf pass.dat [options]

This invokes password file maintenance and appends the specified options to the password file pass.dat. If this file does not exist, it is created.

The following options are available:

  • /u user-ID
    /pw password
    These add the specified user-ID and password to the password file. Both user-ID and password are case-sensitive and can be up to 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 EBCIDIC.
  • [/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 Visual COBOL 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 Visual COBOL prior to version 3.0. The upgraded password file now supports long usernames and passwords.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
User-ID Groups
Supervisor Mode


User-ID Groups

You can group user-IDs by using the # character. If the # character is present in a user-ID, Fileshare registers the full passed user-ID but only performs logon validation on the portion of the user-ID prior to the # character.

When adding entries to the password file, you should create them as exclusive up to the # character. See the section Password File Maintenance for further information.

If you use view a user with a utility such as FSVIEW, the user information returned will show the full user-ID supplied by the client. Note that any reference to a user must be made using the full user-ID.

Example

fs /pf pass.dat /u pkel#1 /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel#1 and password of fishwife.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
Supervisor Mode
Password File Maintenance


Supervisor Mode

In order to use the password-restricted functions of Fileshare Manager, a supervisor password must be defined (see the section Fileshare Manager in the chapter Advanced Operation).

To define a supervisor password, an entry must be made in the password file using the reserved user-ID, FSVIEW. Note that the user-ID FSVIEW must be entered in upper case.

If you are already using Fileshare Password Security, simply add the FSVIEW entry to your existing file.

If you are not using Fileshare Password Security, you can create a password file that contains a single entry, the FSVIEW user-ID. This defines a supervisor password without enabling Fileshare Password Security.

Example

The following example defines a supervisor password of "abracadabra" in the password file password.fil. If the file does not exist, it is created.

fs /pf password.fil /u FSVIEW /pw abracadabra

Once you have defined a supervisor password, you must specify the password file, either in the Fileshare Server configuration file, or on the command line when the Fileshare Server is started.

Note:

If FSVIEW is the only entry in the password file, the Fileshare Server displays a message indicating that Fileshare Password Security is disabled, even though a password file has been specified.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
User-ID Groups
Fileshare Manager


Advanced Operation

  • Running Fileshare as a Background Process
  • The NFILES Setting
  • 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
  • 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


Running Fileshare as a Background Process

The Fileshare Server uses the Enhanced Accept/Display syntax (Adis module) for its screen displays and keyboard handling. Consequently, the Fileshare Server uses much more processor time if you start it as a background UNIX process. To avoid this overhead, you should configure the Fileshare Server using the -b option. This disables all Fileshare displays and keyboard reading.

Since Fileshare does not read the keyboard in background mode, you cannot close it down in the normal manner using the Esc key sequence.

CAUTION:

Do not kill the Fileshare process because this results in the corruption of any data files which are open.

Because you can only shut down the Fileshare Server remotely, the Fileshare Server must have been configured to use a password file. See Password File Maintenance in the Security section for details.

There are three methods you can use to shut down the Fileshare Server remotely:

  • Use the FSVIEW commands server set, admin password and server shutdown to identify the Fileshare Server, provide the admin password, and request shutdown. The server will only shut down when you have terminated the FSVIEW session using the exit command.
  • Use the supplied utility cobfsclose. The cobfsclose utility prompts you for the name of the Fileshare Server you want to shut down, the admin password, and the CCI protocol. Once these have been entered, the shutdown command will be passed to the server via calls to Fileshare Manager.
  • Write a program that calls Fileshare Manager, and issues the appropriate commands. Refer to the Fileshare Manager topic for details.

The Fileshare Server does not start in background mode unless you start it with a password file.

In background mode, any messages the Fileshare Server would normally display on the screen are written to the file fsscreen.lst in the Fileshare Server's current directory.

An example configuration file follows.

-s server-1
-pf password.fil
-cm ccitcp

This configuration file specifies:

  • Fileshare Server name is server-1
  • Password file is password.fil
  • Communications protocol to use is CCITCP
  • -b option invokes running in background mode

On UNIX, you can now start the Fileshare Server in background mode by entering:

fs -b > server-1.log 2>&1 &

On some UNIX systems, output can be sent to the terminal after it has been disconnected. When this happens the entire session terminates. Consequently, you need to redirect the output from the command.

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
The NFILES Setting
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
Password File Maintenance


The NFILES Setting

On UNIX systems, the NFILES setting defines how many separate file descriptors can be used in the File Handler configuration file. This can be set for individual accounts and for the system as a whole. You must ensure that the number of separate file descriptors is set sufficiently high for Fileshare which uses them as follows:

  • One file descriptor is used for every file opened on disk. So, two file descriptors are used for each indexed file opened. Note that two users sharing the same file only require the file to be opened once on disk.
  • CCITCP uses one file descriptor for every connected Fileshare client
  • CCITCP uses one file descriptor for every outstanding Fileshare request (normally this is a maximum of two)

For the user account that the Fileshare session uses, NFILES must be set to accommodate the maximum number of open files and the maximum number of Fileshare clients. In addition, the system setting of NFILES may need to be increased.

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
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


Single User Mode

You can configure Fileshare to run in single user mode. All network communication is bypassed and the Fileshare Client makes direct calls to the Fileshare Server module. The Fileshare Server does not run as a separate process in this mode of operation.

This is useful when:

  • You want to develop Fileshare applications without using a network or multiple sessions
  • A single-user application makes use of one of Fileshare's advanced features, such as transaction processing

To run Fileshare in single user mode, set the FSCOMMS environment variable to $local, for example:

Windows:

set FSCOMMS=$local /s servername

UNIX:

set FSCOMMS="\$local" /s servername
export FSCOMMS

Even when you are running in single user mode, you must still inform the Fileshare Client which Fileshare Server to use, either by specifying the Fileshare Server name as part of the filename in your program or by using a Fileshare Client configuration file.

The Fileshare Server is configured in the normal way using a Fileshare Server configuration file. At the minimum, you must define a Fileshare Server name in this file.

Note:

The Fileshare Server does not have control over the screen when it is running in single user mode. It directs all screen output to the file fsscreen.lst in the current Fileshare Client directory. If your program fails, check this file for messages.

The FSSERVER environment variable must be unset.

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
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


Filename Mapping

Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions, such as UNIX or NetWare.

You do not need to change the configuration of the Fileshare Client to use filename mapping.

  • Fileshare Server
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
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

To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.

The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of a filename. This is particularly useful for mapping pathnames.

For example:

fs /d dbase.ref /f old.dat /af new.dat
fs /d dbase.ref /fs c: /af e:

adds entries to the database reference file dbase.ref which specify that:

  • All requests to the data file old.dat are redirected to the data file new.dat
  • All accesses to data files starting with c: are directed to drive e:

If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.

After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.

Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.

All filenames and paths are forced to upper case by Fileshare Servers not running on the UNIX operating system and are expanded to include the full path to ensure matching. Filenames specified with the /af option are not modified.

Example 1:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat

This example adds entries to the database reference file dbase.ref that specify that file accesses to the file file1.dat are mapped to the alternate filename file2.dat.

Example 2:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
fs /d dbase.ref /fs c: /af e:

This example adds entries to the database reference file dbase.ref that specify that all requests made to the data file file1.dat are redirected to the alternate filename and, in addition, the alternate filename is changed, using string substitution, to be on drive e:.

Parent topic: Filename Mapping


Data and Key Compression

You can configure the Fileshare Server so that data files are created using data or key compression.

You do not need to change the Fileshare Client configuration in order to use data or key compression on a data file.

  • Data and Key Compression - Fileshare Server
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
Byte-stream I/O Calls
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
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Data and Key Compression
Monitoring Fileshare
Fileshare Manager Configuration
Byte-stream I/O Calls
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To specify a virtual file handler, use the /ap (application program) option with the /f option in the database reference file to specify the program to which I/O requests for a particular data file are passed by the Fileshare Server.

Example:

fs /d dbase.ref /f user1.dat /ap myprog

This adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data file user1.dat to the program myprog.

Windows:

UNIX:

On UNIX, your program should be compiled to intermediate or generated code, or to a callable shared object, and must be callable from the Fileshare process.

You also need to use the fcd3 copybook instead of the standard fcd layout.

Parent topic: Virtual File Handler Interface


Monitoring Fileshare

When the Fileshare Server is active, you can toggle the trace option on and off using the F2 key. If the trace option is on, the Fileshare Server displays the file access requests on the console as they happen. Each line of trace provides:

  • Input:
    • The user-ID assigned, in the order that the Fileshare Clients logged onto the Fileshare Server
    • The operation code, indicating the I/O operation requested (see the online help on the Micro Focus File Handler for further information about operation codes)
    • The name of the file being accessed
  • Output:
    • The status returned to the Fileshare Client, indicating the result of the operation
Note:

The trace option can degrade performance. You should only use it as a diagnostic aid in problem investigation.

You can activate the trace option when the Fileshare Server is started using the "/tr f" option. This causes the trace to be written to the file fsscreen.lst, as well as being displayed on the screen. Note, however, that this severely impacts the Fileshare Server performance if tracing is switched on. If, however, tracing is switched off, only information messages are written to the screen and to the file. This is a useful method of keeping a permanent record of Fileshare messages on disk.

If you are using Fileshare in single user mode (see the section Single User Mode), the trace display, together with all other output normally displayed on the Fileshare Server console screen, is written to the file fsscreen.lst in the Fileshare Server's current directory .

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Fileshare Manager Configuration
Byte-stream I/O Calls
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
Running Fileshare as a Background Process
The NFILES Setting
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
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
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Byte-stream I/O Calls
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
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
Performance Considerations
Large File Support with Fileshare


FS_LOCATE_FILE

The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:

  • You cannot use FS_LOCATE_FILE to search for files in libraries on remote Fileshare Servers
  • You can use CBL_LOCATE_FILE to search for files along each path specified in an environment variable. You can then use the returned actual-file-spec as the filename when opening the file.

    If you have specified a $$server-name prefix in user-file-spec, actual-file-spec must contain the same $$server-name prefix for an OPEN using actual-file-spec to be re-directed automatically. By default, Fileshare only returns the filename in actual-file-spec to your program. To return the $$server-name in actual-file-spec, set the most significant bit of user-mode before making the call to FS_LOCATE_FILE.

  • When a remote file is found, using an environment variable containing many paths, FS_LOCATE_FILE returns actual-file-spec including the full path where the file is located

When a call to FS_LOCATE_FILE is directed to a custom file handler by configurable DYNREDIR, the customer file handler is called with op-code FAF8 plus fcd(3:1) and uses the value 5 to specifiy it as an FS_LOCATE_FILE call.

On Entry Fields

On entry, the following fields are set:

fcd-name-ptr | Pointer to the user file
fcd-open-mode | User mode
fcd-optional | Path flag
fcd-name-length | Length of filename

On entry, the length of the fcd-name-length field is the same as the length of the filename pointed to by the field fcd-name-ptr.

On exit, you need to set the following fields:

fcd-record-ptr | Pointer to the actual file spec
fcd-access-mode | Exist flag
fcd-file-status | File status
Parent topic: Byte-stream I/O Calls
Related information
FS_SPLIT_FILENAME and FS_JOIN_FILENAME


FS_SPLIT_FILENAME and FS_JOIN_FILENAME

The functionality provided by FS_SPLIT_FILENAME and FS_JOIN_FILENAME is the same as that provided by the corresponding CBL_routines. In addition, using FS_SPLIT_FILENAME and FS_JOIN_FILENAME you can process filenames that specify Fileshare Server names using the $$server-name prefix at the front of the filename. When processing such filenames, the $$server-name prefix characters are included as part of the pathname parameter.

If you have included the callable sort, and receive error 173 after switching to release build, you need to include fhrsub.obj in your project.

Parent topic: Byte-stream I/O Calls
Related information
FS_LOCATE_FILE


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.

  • Fileshare Performance on UNIX
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
Byte-stream I/O Calls
Large File Support with Fileshare


Fileshare Performance on UNIX

Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve performance when the COBOL data resides on the same machine as the application. In this configuration, there is actually a performance overhead when using Fileshare instead of the standard Callable File Handler.

Although UNIX machines can be used as remote data servers, it is not uncommon for the application itself to run on the machine where the data resides. For example, multiple users may log in, across a network, to a machine where they run applications which share the same data. In such a configuration, you encounter the performance overhead of using Fileshare, making performance slower than when using the standard Callable File Handler.

Parent topic: Performance Considerations


Large File Support with Fileshare

Fileshare, by default, supports files that can be up to 32 Terabytes in size.

An alternative technology, file striping, was introduced in previous releases as an interim solution to overcome limitations on the maximum allowed file size some operating systems permit. It enables you to specify that a single data file is to be stored in multiple physical files (or stripes) on disk.

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.

    UNIX:

    For example, on UNIX:

    [/u/username/file.dat]
Striping=on
    Note:

    You need only do this for files accessed through Fileshare. To enable the file handler to find the setting in extfh.cfg the filename tag must match exactly that specified by the I/O request, which in the case of Fileshare includes a fully qualified path.

  • Backslash character

    The backslash character is treated as an escape character within the extfh.cfg file.

    Windows:

    On Windows platforms you must therefore specify two backslash characters for each backslash character in the pathname, for example:

    [d:\\fsrvr\\file.dat]
Striping=on
  • Alternate filenames

    You can specify file striping on an alternate filename (specified in the database reference file using filename mapping). In this case, the expanded filename is not required. For example, if the database reference file contains the following line:

    /f file1.dat /af file2.dat

    you can specify the following in the extfh.cfg file:

    [file2.dat]
Striping=on
  • StripeNameType

    StripeNameType=1 (the default is StripeNameType=0) only works with Fileshare if the base filename does not have an extension. If you specify StripeNameType=1 for a filename that has an extension, the file is created but it is not striped.

  • Back up and recovery

    The use of striping complicates the process of logging for rollforward recovery because the administrator has to ensure that the correct versions of the files are in the latest backup, and that they are correctly restored in the event of needing to run the Fileshare Recovery Utility. This process is much more complex if file stripes also have to be maintained.

    The Automatic Database Backup and Recovery facility does not work correctly on striped files because it uses low-level I/O routines for backups and restores which are unaware of the stripe configuration.

  • Not using Fileshare

    The filenames passed to the File Handler must match exactly so that the File Handler can locate the filename tags in the extfh.cfg file.

    Generally, only Fileshare passes fully qualified names. Therefore, if you have set up an extfh.cfg file for use under Fileshare with expanded pathnames and then want to access the files outside of Fileshare, you need to change the filename tags in extfh.cfg to match exactly the filenames passed by the application.

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
Running Fileshare as a Background Process
The NFILES Setting
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


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


Transaction Processing Errors

The COMMIT and ROLLBACK operations work across many data files. You cannot check the file status of any one data file to see if the COMMIT or ROLLBACK operation was successful. Instead, call the entry point fs_status to determine the status of the COMMIT or ROLLBACK operation.

The format of the call is:

call "fs_status" returning t-status

where the parameter is defined as:

01 t-status   pic x(2) comp-x.

A non-zero status indicates that the COMMIT or ROLLBACK operation failed. Fileshare cannot provide definitive information on transaction processing errors because of the complexity of multiple file transactions across networks.

Parent topic: Error Handling
Related information
Fileshare Extended Status Codes
Communications Errors


Fileshare Server Messages

These are of varying levels of severity:

  • Severe

    Severe level messages indicate that a problem has occurred that has prevented the Fileshare Server carrying out the requested operation. The cause of the error should be rectified and then the operation tried again.

  • Warning

    Warning level messages indicate that a situation was encountered that the Fileshare Server was not expecting, but was able to continue.

  • Informational

    Informational level messages provide information about the operations that the Fileshare Server is performing.

The format of each message is as follows:

FSnnn-x text

where:

Parameter | Description
FS | Fileshare Server message
nnn | Message number
x | Indicates the severity of the message ("S", "W" or "I")
text | Text of the message

For more information on the messages, see the links below.

  • Messages from FS001-S to FS050-W
  • Messages from FS051-W to FS099-W
  • Messages from FS101-I to FS149-I
  • Messages from FS151-I to FS200-W
  • Messages from FS201 to FS300
  • Messages from FS301 - FS400
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling


Messages from FS001-S to FS050-W

  • FS001-S The parameter "text " is not recognized as a valid parameter.
    This error status is displayed when the Fileshare Server parses the specified parameters and finds one which it does not recognize.
  • FS004-S The parameter "text " specifies a time-out value that is invalid.
    The /t parameter has been specified in a configuration file, but the characters following do not conform to a valid specification of a time-out value.
  • FS005-S The parameter "text " is too long or invalid.
    The parameter indicated could not be processed correctly. This can be for one of the following reasons:
  • FS006-S The parameter "text " has already been specified.
    A duplicate parameter has been specified and duplicates are not permitted for this parameter.
  • FS007-S Invalid parameter combination.
    Fileshare has processed the specified parameters and is unable to process the information given.
  • FS008-S Communications Initialization Failure.
    An error has occurred when the Fileshare Server initialized CCI or the Fileshare Server was unable to perform the CCI call because the required operating system and/or Micro Focus communication support modules are not available. This error can also indicate a problem with the network setup on the machine (for example, the required drivers have not been loaded).
  • FS009-S The required communications module cannot be found.
    The Fileshare Server tried to load the CCI module required for the protocol specified, but was unable to do so. This implies that the CCI module (or required support modules) cannot be found or they cannot be loaded.
  • FS011-W Communications send failure.
    The Fileshare Server encountered a communications error when it tried to return the result of an I-O operation to a Fileshare Client. This can imply that there is a problem with the network or that the Fileshare Client process terminated abnormally.
  • FS012-W Communications disconnect failure.
    The Fileshare Server tried to drop the connection with the Fileshare Client, but the communications system returned an error. The Fileshare Server tries to disconnect from Fileshare Clients when:
  • FS013-W Communications receive error.
    An unexpected error occurred while receiving information from the communications system. This error implies a problem with the network software or hardware because a message has been received but could not be processed correctly.
  • FS014-W Communications data length not as expected.
    The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error occurs when the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.
  • FS015-W Request from unknown user - request rejected.
    The information received by the Fileshare Server is not recognized as being from a Fileshare Client that is currently logged onto this Fileshare Server.
  • FS016-S The parameter "text " is invalid.
    The parameter has been recognized as a valid parameter, but the option specified for that parameter is not valid. For example, the /o (omit) parameter has been specified, but the option is not t (transaction processing), l (rollforward recovery logging) or s (sequence number checking).
  • FS017-S Unable to open the file : filename.
    The Fileshare Server is unable to create the file specified.
  • FS018-S Log file corrupt - unrecognizable record in file.
    Each record written to the recovery log file has a marker informing the Rollforward Recovery Utility of the type of data contained in the record.
  • FS019-S Log file corrupt - can't read header.
    Each record written to the recovery log file has a marker indicating the type of data contained in the record. This error indicates that the required header record at the beginning of the log file was not found. This implies that the log file has become corrupt, which can happen, for example, if the system crashed while records were being written to the recovery log file.
  • FS020-S The log file does not match the database sequence numbers - recovery aborted.
    Each index file (not C-ISAM) and all variable length record files have (by default) a sequence number stored in the header of the file. A corresponding sequence number is stored in the log file. Checks are made between the sequence numbers in the file headers and the log file to help ensure that the recovery process proceeds successfully.
  • FS021-S There is no log filename specified in the database reference file.
    You have tried to erase a log file entry from the database reference file but there is no log filename specified in the database reference file. The operation therefore cannot be completed successfully.
  • FS022-S The log filename given cannot be found in the database reference file.
    You have failed to erase a log file entry from the database reference file because the log filename specified is not the same as the log filename in the database reference file.
  • FS024-S Failed to open log file : filename.
    The Fileshare Server encountered an error while trying to open or create the rollforward recovery log file. Common causes of this error are:
  • FS025-S Write failure to the log file, Fileshare Server is closing down.
    The Fileshare Server encountered an error while writing a record to the recovery log file. Because the integrity of the log file cannot be guaranteed, the Fileshare Server shuts down so that the updates performed up to the point of failure are not lost.
  • FS026-W Failed to close the log file.
    The Fileshare Server encountered an error while closing the current log file.
  • FS027-S A second log file parameter has been found.
    While processing the database reference file, a second log file parameter was found. There should only ever be one log file specified in the database reference file and this error indicates that the database reference file is corrupt or has been changed without using the Database Reference File Maintenance Utility.
  • FS028-W The log file shows the last session was not shut down successfully.
    When the Fileshare Server shuts down successfully, the last record written to the recovery log file is a special record that marks the end of the recovery log file. This message indicates that the Fileshare Server could not find the special, last record when it opened the log file, suggesting that the log file was not closed in a controlled manner, probably due to a system crash. The log file could have been opened either to append to or read from in order to perform a rollforward recovery.
  • FS029-S The log filename is already specified in the database reference file.
    You have tried to add the name of the recovery log file to the database reference file. However a log filename already exists in the database reference file. A database reference file can only contain one log filename.
  • FS030-S Insufficient disk space to continue logging to log file.
    The amount of space remaining on the disk where the log file is being written has less than 200K bytes of free space remaining. This is not adequate to ensure that the recovery log file can continue to be successfully written.
  • FS031-I Record lock time-out failure on user : user.
    A record lock time-out has occurred on the user indicated. This is due to the user holding a lock on a record for a period of time longer than the record lock time-out period, when another user is trying to access that locked record.
  • FS034-S A filename or log file parameter must be specified.
    The Database Reference File Maintenance Utility has been invoked using the /d option, however a valid parameter for the utility has not been given
  • FS035-S A database reference file must be specified.
    The Database Reference File Maintenance Utility has been invoked, however the name of the database reference file to use has not been specified using the /d parameter. For example, the parameter /f (filename), /l (log filename), /fs (file string) or /backup (backup directory) has been used to invoke the Database Reference File Maintenance Utility but a /d option has not been specified to supply the name of the database reference file.
  • FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.
    The Fileshare Server has determined that the file indicated does not have a Micro Focus format file header. It is not possible to have sequence numbering on files that do not contain file headers. However, the configuration of the database reference file specifies that sequence number checking should be applied to this file.
  • FS038-S A matching sequence number not found in filename.
    This error message is displayed when the sequence number in the header of the named file does not match the sequence number in the rollforward recovery log file. See the section Database Sequence Numbering in the chapter Database Integrity for full details of database sequence numbering works.
  • FS039-S Improperly closed file - filename.
    The Fileshare Server has found that the file indicated has been marked as corrupt because it was not closed correctly. This implies that the file was not closed in a controlled manner and that the Fileshare Server last accessing the file terminated abnormally.
  • FS040-S Unable to read the file header record in the file filename.
    The Fileshare Server was able to open the file specified, but was not able to read the file header. The file header consists of the first 128 bytes of the file.
  • FS041-S Unable to update the sequence number in the file filename.
    The Fileshare Server was unable to update the sequence number in the header of the file specified. The sequence number in the header of this file cannot be relied on and hence messages relating to incorrect sequence numbers can be ignored. However, careful checks should be made to ensure that the correct version of the file are in place when starting the Fileshare Server or performing a rollforward recovery.
  • FS042-S Unable to open the database reference file: filename.
    The Fileshare Server was unable to open the database reference file indicated
  • FS043-S The database reference file contains an invalid entry.
    The Fileshare Server has found data in the database reference file which is not as expected. This implies that the database reference file has been changed without using the Database Reference File Maintenance Utility or that the database reference file is corrupt in some way.
  • FS044-S Error reading the database reference file.
    An error was encountered when reading the database reference file. The file was successfully opened by the Fileshare Server. This message implies that the file is corrupt or that a disk I/O error occurred. Alternatively, if the database reference file is on a remote drive, a network error could have occurred.
  • FS045-W Duplicate filename specified in the database reference file.
    A duplicate filename was found when the Fileshare Server processed the database reference file. This message implies that the database reference file has been modified, but not using the Database Reference File Maintenance Utility. A given filename should appear only once in the database reference file.
  • FS050-W A log file is not specified in the database reference file.
    The Fileshare Server processed the database reference file but could not find a rollforward recovery log filename. The database reference file should have a recovery log file specified in order that recovery logging can be performed.
Parent topic: Fileshare Server Messages
Related information
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS001-S The parameter "text " is not recognized as a valid parameter.

The operation did not complete.

Resolution:

Change the indicated parameter and retry the operation.

The valid parameters are given in the sections:

  • Server Configuration in the chapter Configuration
  • Database Reference File Maintenance and Rollforward Recovery Utility in the chapter Database Integrity
  • Password File Maintenance in the chapter Security
Parent topic: Messages from FS001-S to FS050-W
Related information
Server Configuration
Database Reference File Maintenance
Rollforward Recovery Utility
Password File Maintenance


FS004-S The parameter "text " specifies a time-out value that is invalid.

The time-out value is specified in seconds and must be in the range 0 through 99999.

See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

Resolution:

Retry the operation using a time-out value in the correct range.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS005-S The parameter "text " is too long or invalid.

  • The parameter specified is too long. For example a password has been specified which is more than 20 characters in length.
  • The parameter expects a value, but none has been given. For example, the /t parameter has been specified but no time-out value has been given.

Resolution:

Retry the operation using a correct value for the parameter indicated.

Parent topic: Messages from FS001-S to FS050-W


FS006-S The parameter "text " has already been specified.

Resolution:

Retry the operation ensuring that only one occurrence of the parameter exists.

Parent topic: Messages from FS001-S to FS050-W


FS007-S Invalid parameter combination.

This can be for the following reasons:

  • Not enough parameters have been specified in order for the operation to be processed. For example, you have tried to start the Fileshare Server without giving a server name.
  • The parameters specified do not indicate a valid operation that can be carried out. For example, the combination /s and /r is invalid as the first implies that the Fileshare Server is to start with the server name indicated, whereas the second parameter indicates that a Rollforward Recovery is to be performed.

Resolution:

Ensure that the parameters specified are correct and retry the operation.

Parent topic: Messages from FS001-S to FS050-W


FS008-S Communications Initialization Failure.

Resolution:

Ensure that the required CCI module(s) required for the protocol you are using is/are available. Use the CCI demo program supplied with the product to ensure that the CCI module required can be loaded and initialized.

Ensure that the network software on the machine is installed, configured and operational.

Parent topic: Messages from FS001-S to FS050-W


FS009-S The required communications module cannot be found.

Resolution:

Ensure that the CCI (and required network modules) are installed correctly on the machine.

Try out the CCI demo program supplied with the product with the same CCI protocols before trying the start the Fileshare Server again.

Parent topic: Messages from FS001-S to FS050-W


FS011-W Communications send failure.

See the message FS148-I for more information.

Resolution:

No user action is possible. However, if the error persists, this could indicate that there is a possible problem with the network or that the network has a high volume of traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS012-W Communications disconnect failure.

  • It receives a request from an unknown Fileshare Client
  • The CCI protocol indicated that the Fileshare Client application terminated abnormally

Resolution:

If the error persists, there could be a problem with the network that is being used. Also, ensure that users are closing down Fileshare Client applications correctly and not turning the workstation machines off or using utilities to terminate the Fileshare applications abnormally (for example kill on UNIX).

Parent topic: Messages from FS001-S to FS050-W


FS013-W Communications receive error.

See the message FS148-I for more information about the cause of the error.

Resolution:

No direct action by the user is possible. However, if the error persists, there could be a problem with the network that is being used or there could be a high volume of network traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS014-W Communications data length not as expected.

This error should not occur in normal circumstances. If found, it implies that there is a problem with the communications system or that the requester service has not been started when using the NETBIOS protocol.

The Fileshare Server has ignored the data sent from the Fileshare Client.

See also the messages FS151-I and FS082-S for additional information.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent back any reply. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS151-I
FS082-S


FS015-W Request from unknown user - request rejected.

The Fileshare Server has ignored the information that it has received and has returned a 9/125 error status to the Fileshare Client that sent the request.

With some CCI protocols, the session associated with this request is disconnected. See the message FS238-I for additional information.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS238-I


FS016-S The parameter "text " is invalid.

Resolution:

Change the parameter specified to a valid option.

Parent topic: Messages from FS001-S to FS050-W


FS017-S Unable to open the file : filename.

The file may be open already or marked as read-only.

Resolution:

Ensure that the path and filename are valid and that the Fileshare Server has read and write access to the directory.

Parent topic: Messages from FS001-S to FS050-W


FS018-S Log file corrupt - unrecognizable record in file.

This error indicates that the marker in the record header is not recognized which implies that the log file has become corrupted in some way.

This error can occur if the last record of the recovery log file was not written successfully because of a system crash. The Recovery Utility will have processed all of the records up to the point of failure.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility.

Parent topic: Messages from FS001-S to FS050-W


FS019-S Log file corrupt - can't read header.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility. If the correct log file is in place, then the file is corrupt and cannot be used in a rollforward recovery process.

Parent topic: Messages from FS001-S to FS050-W


FS020-S The log file does not match the database sequence numbers - recovery aborted.

This error indicates one of the following:

  • The sequence number in the file headers is greater than that in the log file. This indicates that updates have been applied to the files, without the updates being logged in the log file. Because the log file does not contain all of the updates, it is not possible to perform a rollforward recovery. This also indicates that the rollforward recovery is trying to use the wrong versions of the files.
  • The first sequence number in the recovery log file is larger than the sequence number in the file headers. This indicates that updates have been written to the log file but they have not been applied to the data files. It is not possible to apply the updates from the recovery log file because the versions of the data files and the recovery log file do not match.

Resolution:

Ensure that the correct versions of the data and rollforward recovery log file are being used.

See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS021-S There is no log filename specified in the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W


FS022-S The log filename given cannot be found in the database reference file.

Resolution:

Specify the correct name of the log file when trying to erase the entry from the database reference file.

Parent topic: Messages from FS001-S to FS050-W


FS024-S Failed to open log file : filename.

  • The Fileshare Server does not have read/write access to the log file and/or the directory where the log file resides.
  • The filename specified for the log file is invalid. The filename may not be a valid filename for the operating system on which the Fileshare Server resides or the path specified in the log filename specifies a drive/directory that does not exist.
  • The log file is in use by another process, preventing the Fileshare Server from obtaining exclusive access to the log file.
  • The operating system or the COBOL run-time system is unable to allocate a file handle to the log file.
Parent topic: Messages from FS001-S to FS050-W


FS025-S Write failure to the log file, Fileshare Server is closing down.

The cause of the failure should be investigated. Possible causes include the disk is full, a disk error or, if logging to a remote drive, a network error occurred.

Resolution:

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced. Also, the Fileshare Server cannot force the operating system to flush records to disk if the log file is not on the local machine.

Parent topic: Messages from FS001-S to FS050-W


FS026-W Failed to close the log file.

Possible causes are that the disk is full or, if logging to a remote drive, a network error occurred.

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced.

The cause of the failure should be investigated.

Resolution:

It should be possible to use this recovery log file in a rollforward recovery operation as the Fileshare Server has written all of the required information to the file.

Parent topic: Messages from FS001-S to FS050-W


FS027-S A second log file parameter has been found.

Resolution:

Ensure that the correct database reference file is used and that only one recovery log filename is specified in the database reference file.

Only use the Database Reference File Maintenance Utility to change the contents of the database reference file. In this situation however, it may be possible to remove the duplicate entry using a normal text editor. Alternatively the current database reference file can be discarded and a new one created using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS028-W The log file shows the last session was not shut down successfully.

If the Fileshare Server is starting up, the log file is backed up and a new log file created. If you have specified a backup directory in the database reference file, the Rollforward Recovery Utility is invoked automatically.

If a rollforward recovery is being performed, recovery proceeds up to the last full record in the recovery log file (any incomplete transactions are rolled back).

Resolution:

No action is required

Parent topic: Messages from FS001-S to FS050-W


FS029-S The log filename is already specified in the database reference file.

Resolution:

Remove the current log filename from the database reference file using the Database Reference File Maintenance Utility and then add the name of the new log file using the same utility.

Parent topic: Messages from FS001-S to FS050-W


FS030-S Insufficient disk space to continue logging to log file.

The Fileshare Server will close the current recovery log file and wait for it to be backed up before continuing.

Resolution:

Manually back up the current log file and then delete the file. This releases disk space and enables the Fileshare Server to continue logging with a new logfile.

Parent topic: Messages from FS001-S to FS050-W


FS031-I Record lock time-out failure on user : user.

This record lock time-out has caused any transactions that this user has outstanding to be automatically rolled back and all record locks held by this user have been released. See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

You can specify the record lock time-out period using the /t option when you configure the Fileshare Server.

On the next I/O operation, a status of 9/125 will be returned to the Fileshare Client application that held the lock.

Resolution:

No action is required, however the time-out period can be changed or disabled if required.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS034-S A filename or log file parameter must be specified.

Resolution:

Ensure that when invoking the Database Reference File Maintenance Utility, the option /f (filename), /l (log filename), /fs (file string) or /backup (log file backup directory) is used to specify which action should be taken

Parent topic: Messages from FS001-S to FS050-W


FS035-S A database reference file must be specified.

Resolution:

Include the /d option when invoking the Database Reference File Maintenance Utility to provide the name of the database reference file to use

Parent topic: Messages from FS001-S to FS050-W


FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.

The Fileshare Server will not apply sequence number checking to this file.

Resolution:

The programs accessing the files should be changed so that they define the files as variable length record files.

It is not possible to have sequence number checking on line sequential files.

If sequence number checking is required, the file must contain a file header. Fixed length indexed, sequential and relative files should be converted to variable length record format.

Alternatively, if sequence number checking is not required for this file, this message can be avoided by explicitly turning sequence number checking off using the /o s option in this file's entry in the database reference file. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


FS038-S A matching sequence number not found in filename.

The named file is listed in the database reference file and sequence number checking is active for the file. This message indicates that an incorrect version of the file is being used. The Fileshare Server does not start until this problem is rectified.

Resolution:

Ensure that the correct version of the file is available to the Fileshare Server and that if sequence numbering is used, all updates performed to the file are done via the Fileshare system. See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS039-S Improperly closed file - filename.

Resolution:

The file is corrupt and a backup should be put in place and recovery performed using the Rollforward Recovery Utility. See the section Rollforward Recovery Utility in the chapter Database Integrity for details. If you have specified a backup directory in the database reference file, the recovery will be performed automatically.

If updates to the file have not been logged then the file should be rebuilt using the REBUILD utility.

Parent topic: Messages from FS001-S to FS050-W
Related information
Rollforward Recovery Utility


FS040-S Unable to read the file header record in the file filename.

Resolution:

If sequence number checking is not required for this file then this feature should be omitted for this file using the /o s option in the database reference file.

All files that can have sequence number checking are at least 128 bytes in length as this is the size of a file header (which is required for sequence number checking to be performed).

Parent topic: Messages from FS001-S to FS050-W


FS041-S Unable to update the sequence number in the file filename.

Resolution:

This error is very rare and implies a disk I/O error (or a network error if the file is not on the local Fileshare Server machine).

Parent topic: Messages from FS001-S to FS050-W


FS042-S Unable to open the database reference file: filename.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has full read and write access to the file specified.

Also ensure that the Fileshare Server can gain exclusive access to the database reference file and that another process does not have the file open.

Parent topic: Messages from FS001-S to FS050-W


FS043-S The database reference file contains an invalid entry.

Resolution:

Ensure that only the Database Reference File Maintenance Utility is used to change the contents of the database reference file.

Alternatively, discard the current database reference file and re-create the contents of the file using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS044-S Error reading the database reference file.

Resolution:

Try the operation again. If the problem persists, the database reference file is probably corrupt - the current file should be discarded and a new database reference file created using the Database Reference File Maintenance Utility

Parent topic: Messages from FS001-S to FS050-W


FS045-W Duplicate filename specified in the database reference file.

Resolution:

Recreate the database reference file ensuring that each filename appears in the file only once.

Parent topic: Messages from FS001-S to FS050-W


FS050-W A log file is not specified in the database reference file.

Resolution:

If rollforward recovery logging is required, add an entry to the database reference file specifying a rollforward recovery log filename. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


Messages from FS051-W to FS099-W

  • FS051-W Failure to allocate a larger buffer, the I-O request failed.
    When using compression on the communication buffers, this message indicates that there was not enough memory available to the Fileshare Server to enable it to decompress the buffer. The I/O request has failed and the Fileshare Client was returned a 9/105 (out of memory) error.
  • FS052-S Failure to allocate required memory. The Fileshare Server is closing down.
    You see this message when the Fileshare Server is initializing and cannot allocate enough memory for the required internal tables
  • FS055-S The parameter "text " specifies a configuration file that does not exist.
    The Fileshare Server is unable to locate or open the configuration file indicated
  • FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.
    You have tried to add an entry to the database reference file. This entry specifies a value for the data compression outside of the permitted limits. The data compression option must specify a value within the range 0 through 255. To use the routine CBLDC001 as the compression method on records in the file, specify a compression value of 1.
  • FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.
    You have tried to add an entry to the database reference file which specifies a value for the key compression outside of the permitted limits.
  • FS058-S Failure to allocate memory for the decompression of the log file.
    The Rollforward Recovery Utility has been invoked but is unable to allocate the required memory so that it can process the recovery log file. This error is displayed during the initialization of the recovery process and indicates a shortage of available memory.
  • FS059-S Failure to allocate the memory required for processing the database reference file.
    When reading in a database reference file (either when the Fileshare Server or the Rollforward Recovery Utility is starting) this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the database reference file
  • FS062-S Failure creating the password file filename.
    The Fileshare Server was unable to create the password file indicated
  • FS063-S Failure opening the password file filename.
    The Fileshare Server was unable to open the password file indicated
  • FS064-S Failure reading the password file filename.
    The Fileshare Server encountered an error reading the information from the password file. This implies that an I/O error occurred, the password file has become corrupted in some way or that a network error occurred if the password file is located on a remote machine.
  • FS065-S The password file is not of a recognized format.
    The first record in the password file is a special record which indicates to the Fileshare Server that the file is a password file. This record also contains information regarding the version of the password file being used.
  • FS066-S The specified user name already exists in the password file.
    You see this message when using the Password File Maintenance Utility and you have tried to add a user name to the password file when the user name already exists in the password file
  • FS068-I The password file is now empty and has been deleted.
    You see this message when you have used /e (erase) option with the Password File Maintenance Utility to remove the last entry from the password file. As the password file is now empty, it has been deleted. If a new password file is required it is created automatically when you add an entry using the Password File Maintenance Utility.
  • FS069-S The specified entry could not be found in the password file.
    This message indicates that you have used /e (erase) option with the Password File Maintenance Utility to remove an entry, but the entry specified does not exist in the password file.
  • FS070-S Failure writing to the password file.
    The Password Maintenance Utility encountered an error when it tried to write information to the password file. This implies that an I/O error occurred (possibly a full disk) or a network error was encountered (if the password file is on a remote machine). The integrity of the password file cannot be guaranteed.
  • FS071-W Unable to load the module FHXSCOMP to decompress the data area.
    This message indicates that the Fileshare Server has received a compressed communications buffer. However, it is unable to load the decompression module FHXSCOMP in order to perform the necessary decompression. There may not be enough memory to load the module or the module may not be found.
  • FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.
    A parameter containing a wild card symbol was specified when invoking the Database Reference File Maintenance Utility but the parameter does not support wild cards.
  • FS073-S Failure to allocate memory to process the password file.
    When reading in a password file (when either the Fileshare Server or the Password File Maintenance Utility is starting), this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the password file.
  • FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.
    NLM: This message is only applicable to the Fileshare NLM.
  • FS075-W Unable to load the module FSSECLOG - LOGON has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS076-W Unable to load the module FSSECOPN - OPEN has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.
    When the Fileshare Server starts up, it registers its name on the network so that Fileshare Clients can connect to it. This message indicates that the Fileshare Server is trying to register with a name that is already in use by another Fileshare Server on the network.
  • FS078-S No password file has been specified for the use of background mode.
  • FS079-S A supervisor password entry must exist for the use of background mode.
  • FS080-S No password file has been specified for the use of the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a supervisor-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMgr. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a user-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMGR. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.
    You have tried to start the Fileshare Server using the Netbios protocol (CCINETB) but the required network software is not loaded or is not operational. The Fileshare Server is trying to use the NETBIOS software but is receiving invalid data.
  • FS083-S Incompatible CCIIPX.NLM version.
    The Fileshare NLM Server has detected that the version of cciipx.nlm being used is not a compatible version. You are probably trying to use an old version of the CCIIPX NLM with this version of the Fileshare NLM.
  • FS084-I Fileshare Server is starting.
    This message indicates that the Fileshare Server is in the process of initializing. The configuration, database reference and password files (if specified) are being processed and the communications software is being loaded and initialized.
  • FS085-I Fileshare Server is active.
    This message indicates that the Fileshare Server has completed its initialization processing and is now ready to accept incoming requests from Fileshare Clients. At this stage all of the configuration, database reference and password files have been processed and the communications software has been successfully initialized and is operational.
  • FS086-I Fileshare Server is closing down.
    This message indicates that the Fileshare Server has started the process of closing down and will shortly terminate. This can be invoked by the following:
  • FS087-I Fileshare Server has closed down.
    This message indicates that the Fileshare Server has completed all of its termination processing. All communications have stopped, all files closed, all transactions rolled back and any rollforward recovery log file shut. The Fileshare Server can now be restarted when necessary.
  • FS089-I Database Reference File Maintenance Utility.
    The Database Reference File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file. The Database Reference File Maintenance Utility will try to process the remaining parameters specified as options to this utility.
  • FS090-I Database Reference File installation completed successfully.
    The Database Reference File Maintenance Utility has been invoked successfully and the required change made to the database reference file has been made.
  • FS091-I Rollforward Recovery Utility
    The Rollforward Recovery Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS092-I Rollforward Recovery has completed.
    The recovery process is now complete: the files contain the updates recorded in the log file when the Fileshare Server was in use.
  • FS094-I Password File Maintenance Utility.
    The Password File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS096-I Password File installation has completed.
    The Password File Maintenance Utility has successfully updated the password file using the options specified when the Password File Maintenance Utility was invoked.
  • FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)
    You have used the Esc key sequence to close down the Fileshare Server. This message is an additional prompt to avoid closing down the Fileshare Server in error.
  • FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.
    This error occurs when a file is being recovered using the Rollforward Recovery Utility. When the log file is written during the normal operation of the Fileshare Server, a record is made in the log file of the status of each I/O operation performed. At the time of recovery, the status returned during the recovery process is compared with that stored in the recovery log file.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS051-W Failure to allocate a larger buffer, the I-O request failed.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that it is able to increase the size of its decompression buffers.

Alternatively, reconfigure the Fileshare System so that compression on the communications buffers is not used.

Parent topic: Messages from FS051-W to FS099-W


FS052-S Failure to allocate required memory. The Fileshare Server is closing down.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that more memory is available to the Fileshare Server.

Parent topic: Messages from FS051-W to FS099-W


FS055-S The parameter "text " specifies a configuration file that does not exist.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has read access to the file. Also ensure that no other process currently has the file open as the Fileshare Server requires exclusive access to the configuration file.

Parent topic: Messages from FS051-W to FS099-W


FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.

The specification of compression of records only takes effect when the file is created. Specifying data compression on a file that already exists and contains uncompressed records has no effect.

Resolution:

Specify a data compression value of 0 through 255

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.

The key compression option must specify a value within the range 0 through 7.

Specifying key compression only has an effect at the time that the file is created. Specifying key compression on a file that already exists, but does not have key compression, has no effect.

Resolution:

Specify a key compression value of 0 through 7.

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS058-S Failure to allocate memory for the decompression of the log file.

Resolution:

Increase the amount of available memory by reducing the number of processes and/or applications running on the same machine where you are running the Rollforward Recovery. Then try to run the Rollforward Recovery Utility again.

Parent topic: Messages from FS051-W to FS099-W


FS059-S Failure to allocate the memory required for processing the database reference file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. If this is not possible, reduce the amount of information that is contained in the database reference file.

Parent topic: Messages from FS051-W to FS099-W


FS062-S Failure creating the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to create the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS063-S Failure opening the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to open the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS064-S Failure reading the password file filename.

Resolution:

Retry the operation. If the message persists, the password file may be corrupt and should be discarded. A new password file should then be created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS065-S The password file is not of a recognized format.

This message indicates that the Fileshare Server has not recognized this record in the file as being that identifying a password file. Alternatively the password file has become corrupt.

Resolution:

Check that the path and filename of the password file specified are correct.

If they are correct then the current password file should be discarded and a new one created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS066-S The specified user name already exists in the password file.

Resolution:

To update a user entry that already exists in the password file, first erase the entry and then add the new entry to the file. See the section Password File Maintenance in the chapter Security for more details.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS068-I The password file is now empty and has been deleted.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS069-S The specified entry could not be found in the password file.

Resolution:

Ensure that the user name and password are correct (that is, exactly those which were specified for the entry to be erased when the entry was first added to the password file). If the user-ID or password are no longer known, you must create a new password file using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS070-S Failure writing to the password file.

Resolution:

Restore the password file from a backup and try to add the new entry again. If no backup is available, discard the current password file and create a new one using the Password File Maintenance Utility.

Ensure that there is enough disk space available on the drive where the password file resides.

Parent topic: Messages from FS051-W to FS099-W


FS071-W Unable to load the module FHXSCOMP to decompress the data area.

Alternatively there may be an insufficient number of file handles available to enable the operating system or run-time system to load the module.

The request received from the Fileshare Client has been discarded.

Resolution:

Ensure that the system module FHXSCOMP is available on your system. Also ensure that there is enough memory available for the module to be loaded and file handles are available to enable the run-time or operating system to load the file.

Parent topic: Messages from FS051-W to FS099-W


FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.

Wild cards are only permitted on database entries defining an alternate program.

See the /ap option in the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

Do not specify a wild card symbol for this parameter.

A full path or filename should be given.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS073-S Failure to allocate memory to process the password file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. Alternatively, reduce the amount of information that is contained in the password file.

Parent topic: Messages from FS051-W to FS099-W


FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.

You see this message when using the /nu option to force the Fileshare Server to log onto NetWare with the specified user-ID. However, the Fileshare NLM Server encountered an error when trying to connect with the user-ID specified. This implies that there is no user account with the user-ID set up on the NetWare server or that you entered an incorrect password when prompted to do so.

Resolution:

Check that the user-ID is correct and that a user account for that ID is defined on the NetWare operating system. Also check that the correct password for this user-ID was entered when prompted.

Parent topic: Messages from FS051-W to FS099-W


FS075-W Unable to load the module FSSECLOG - LOGON has been denied.

  • FSSECLOG is not available
  • There is insufficient memory available to load FSSECLOG
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECLOG

FSSECLOG is required to validate logon requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECLOG module has been removed on purpose, the Fileshare Server does not permit the logon to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECLOG is available to the Fileshare Server (this can be the FSSECLOG module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECLOG module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS076-W Unable to load the module FSSECOPN - OPEN has been denied.

  • FSSECOPN is not available
  • There is insufficient memory available to load FSSECOPN
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECOPN

FSSECOPN is required to validate open requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECOPN module has been removed on purpose, the Fileshare Server does not permit the open to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECOPN is available to the Fileshare Server (this can be the FSSECOPN module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECOPN module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.

Alternatively, this message can indicate that a Fileshare Server that was using this name terminated abnormally and did not de-register its name from the network.

Resolution:

Ensure that the Fileshare Server name is unique for this server. This is the name that the Fileshare Server is configured to register on the network. If a Fileshare Server that was using this name terminated abnormally, it may be necessary to re-initialize the network software on the machine where that Fileshare Server was running to ensure that its name is no longer registered (what action is required in this situation depends on the communications protocol that is being used).

Parent topic: Messages from FS051-W to FS099-W


FS078-S No password file has been specified for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process on UNIX so that information is neither accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain a FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSView, FSMgr or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but you have not specified a password file.

Resolution:

Create a password file using the Password File Maintenance Utility containing a user-ID of FSVIEW and a password. Then specify this password file (using the -pf option) in the Fileshare Server configuration file.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS079-S A supervisor password entry must exist for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process in the background on UNIX where no information is accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain an FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSMgr, FSView or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but the password file that you specified does not contain an FSVIEW (supervisor) user-ID or password.

Resolution:

Add a user-ID of FSVIEW and password to the password file specified using the Password File Maintenance Utility.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS080-S No password file has been specified for the use of the synchronous communications mode.

Resolution:

When starting the Fileshare Server, use the /pf option in the Fileshare Server configuration file to specify the name of a password file containing a user-ID of FSVIEW. See the sections Password System and Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password System
Password File Maintenance


FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.

This message indicates that a password file has been specified, however, there is no (supervisor) user-ID of FSVIEW in the password file.

Resolution:

Add a user-ID of FSVIEW and a password to the password file using the Password File Maintenance Utility and try the operation again. See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.

Resolution:

Ensure that the NETBIOS software has been loaded, is functioning and is configured correctly on the machine where you are trying to start the Fileshare Server. Try to start the Fileshare Server again. Alternatively, use another communications protocol.

See the message FS014 for further information.

Parent topic: Messages from FS051-W to FS099-W
Related information
FS014


FS083-S Incompatible CCIIPX.NLM version.

Resolution:

Ensure that the version of cciipx.nlm supplied with the Fileshare Server NLM is the one on the system and that this version is loaded in preference to any earlier version (meaning that this version is on the search path before any older version of the CCIIPX NLM)

Parent topic: Messages from FS051-W to FS099-W


FS084-I Fileshare Server is starting.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS085-I Fileshare Server is active.

Fileshare Client applications can now be started and communicate with this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS086-I Fileshare Server is closing down.

  • The Fileshare Server encountered an error when starting up, for example an error was found in a configuration, database reference or password file. Alternatively the communications support could not be started.
  • The user has requested to shut down the Fileshare Server (either by the Esc key sequence or a remote request from FSView or FSMgr)
  • The Fileshare Server has encountered an unrecoverable error during its operation. For example, the remaining disk space where the rollforward recovery log file resides is below the acceptable limits for logging to continue.
  • The Fileshare Server process was terminated by an event external to the Fileshare Server(for example a kill command on UNIX)

The Fileshare Server is closing all outstanding connections with Fileshare Clients, rolling back any outstanding transactions, closing all open files and shutting down the communication support.

Depending on the communications protocol that is in use, the Fileshare Client applications may appear to suspend if they are still trying to send requests to this Fileshare Server.

Resolution:

No action is required

Parent topic: Messages from FS051-W to FS099-W


FS087-I Fileshare Server has closed down.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS089-I Database Reference File Maintenance Utility.

If the Database Reference File Maintenance Utility should not have been invoked, check the command line to ensure that neither the /d option nor any other valid Database Reference File Maintenance option has been specified. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS090-I Database Reference File installation completed successfully.

The database reference file specified now contains the change required.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS091-I Rollforward Recovery Utility

If the Rollforward Recovery Utility should not have been invoked, check the command line to ensure that neither the /r option nor any other valid Rollforward Recovery Utility option has been specified. See the section Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Rollforward Recovery Utility


FS092-I Rollforward Recovery has completed.

If the updates have been applied successfully, you should back up the recovered files and use a new log file when you restart the Fileshare Server. This ensures that the new recovery log file is in step with the current data files.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS094-I Password File Maintenance Utility.

If the Password File Maintenance Utility should not have been invoked, check the command line to ensure that the /pf option has been used correctly and that no other option specific to the Password File Maintenance Utility has been used. See the section Password File Maintenance in the chapter Security for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS096-I Password File installation has completed.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)

The Fileshare Server does not accept input from Fileshare Clients whilst waiting for the response to this prompt. Consequently, you should respond quickly to this prompt.

Resolution:

Responding Y to this prompt causes the Fileshare Server to start its termination processing. If there are any files open or users logged onto this Fileshare Server, an additional prompt and confirmation are displayed. When the Fileshare Server shuts down, it rolls back all outstanding transactions, closes all open files, logs off all users and closes down the communication support modules.

If you give any reponse other than Y, the Fileshare Server continues operating as normal.

Parent topic: Messages from FS051-W to FS099-W


FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.

This message indicates that the status returned during the recovery process was not the same as that when the operation was performed during the normal Fileshare Server processing when the log file was written.

The Returned status is the status that the Rollforward Recovery Utility encountered when trying to apply the updates from the recovery log file to the data files.

The Expected Status is the status that was returned when this operation was originally performed by the Fileshare Server (and when the log file was being written).

The Action code is the operation code that is being performed.

The name of the file is included in the message.

This error indicates one of the following:

  • The files to which the recovery log file is being applied are not the ones that were in use at the time that the Fileshare Server was started and the log file was created
  • The recovery log file or the files being rolled forward are corrupt
  • A situation has arisen which did not occur when the rollforward recovery file was created during normal Fileshare Server operation

Resolution:

Note the expected and returned error codes and take appropriate action. Also ensure that the correct version of the data files are in place and try to re-run the rollforward recovery.

Parent topic: Messages from FS051-W to FS099-W


Messages from FS101-I to FS149-I

  • FS101-I text -- parameter has been accepted.
    The indicated parameter (and value if required) has been accepted by the Fileshare Server
  • FS103-I The log filename has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a recovery log filename to the database reference file and the operation has completed successfully. The database reference file now contains the name of the recovery log file specified.
  • FS104-I The log file cannot be found, creating a new recovery log file.
    The Fileshare Server on starting up has processed the database reference file and determined the name of the rollforward recovery log file to use. The recovery log file does not exist and so the Fileshare Server has created a new one.
  • FS105-W The disk free space for the log file is below acceptable limits.
    The Fileshare Server has detected that the amount of disk space remaining on the drive where the recovery log file is being written is below a certain level.
  • FS106-I filename - added to database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully added the filename indicated to the database reference file.
  • FS107-I filename - removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the filename indicated from the database reference file.
  • FS108-I Processing the files specified in the database reference file.
    This message indicates that the Fileshare Server has opened the database reference file and is now scanning through it, processing each filename listed. The type of processing that it performs depends on the utility being used:
  • FS109-W The file filename does not exist.
    You see this message when the filenames listed in the database reference file are being processed and indicates that the file indicated cannot be located physically on disk.
  • FS110-I filename - OK.
    The Fileshare system has successfully processed the entry indicated in the database reference file and the file has been physically located on disk.
  • FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?
    You have selected to close down the Fileshare Server using the Esc key sequence. This message indicates that Fileshare Clients are still connected to this Fileshare Server with files open, or at least one Fileshare Client application program has terminated abnormally leaving one or more files open. You are asked to confirm that you do want to shut down the Fileshare Server even though there are files open.
  • FS114-W Waiting for the old log file to be removed.
    The drive where the rollforward recovery log file is being written has become full and the Fileshare Server is no longer able to continue writing to the rollforward recovery log file. The Fileshare Server is waiting for the old log file to be backed up and then deleted so that it can continue writing to the directory where the log file resides.
  • FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.
    For files formats with file headers (all index files and variable length record relative and sequential files), the Fileshare Server stores a sequence number in the header. This sequence number is also placed in the recovery log file. The sequence numbers can be checked by the Fileshare Server in certain situations to ensure that the correct files are in use.
  • FS122-I Communications too busy on CCI SEND - retrying.
    The Fileshare Server tried to send a reply back to the Fileshare Client performing an I/O request. CCI returned a Too Busy error (error 10) to the Fileshare Server.
  • FS123-I Communications too busy on CCI RECEIVE - retrying.
    The Fileshare Server tried to receive information from the network but CCI returned a Too Busy error (error 10) to the Fileshare Server
  • FS124-I Checking the validity of the log file, please wait.
    You see this message when the Rollforward Recovery Utility has been invoked and it has not found a valid record as the last record in the recovery log file. The Rollforward Recovery Utility scans through the log file to find the last sequence number that was in use to validate the integrity of the recovery log file.
  • FS125-I Recovery possible to last valid recovery log file record.
    You see this message when the Rollforward Recovery Utility has been invoked. This message indicates that the recovery log file has been validated up to the point of the last complete record in the recovery log file. It is therefore possible to apply the updates stored in the recovery log file up to this point.
  • FS126-I Performing recovery, please wait.
    The Rollforward Recovery Utility has been invoked and has initialized successfully, processed the database reference file, checked the sequence numbers in the file listed in the database reference file and validated the recovery log file.
  • FS127-S Invalid name mapping command.
    You see this message when the Fileshare Server or Rollforward Recovery Utility is processing the command line or entries in the database reference file. An /fs (file string replacement) option has been specified without a corresponding /af option specifying the new string value. The /fs option must be used in conjunction with the /af option.
  • FS128-W Fileshare Server closedown invoked by Stop Run processing.
    This message indicates that the Fileshare Server has entered its termination routine not under the control of an administrator (that is, the Esc key sequence or FSView or FSMgr are not being used to shut down the Fileshare Server).
  • FS129-I The Fileshare Server is still active.
    The response to the prompt as to whether the Fileshare Server should be closed down (see messages FS097 and FS111) indicated that the Fileshare Server should not be shut down.
  • FS130-I Reading database reference file, please wait.
    The Fileshare Server, Database File Maintenance Utility or the Rollforward Recovery Utility is reading the information stored in the database reference file. The utility will try to open the database reference file and process the information held in it.
  • FS131-W Invalid communications mode - parameter ignored.
    You see this message when the Fileshare Server is processing a /cm (communications) option. The value specified for this parameter is not valid and the parameter has been ignored. See the chapters Communications and Configuration for details of valid communications modes.
  • FS132-I The Fileshare Server is running with the following communication protocol(s):
    This message gives a list of the communication protocols that the Fileshare Server is using, after it has performed all of its initialization processing.
  • FS133-I Processing the password file, please wait.
    You see this message displayed by the Fileshare Server when it is starting or by the Password File Maintenance Utility when the password file is being updated.
  • FS134-I The password file cannot be found - creating a new password file.
    The Password File Maintenance Utility displays this message when it cannot locate the password file specified with the /pf option.
  • FS135-I Fileshare Server security is active.
    Fileshare Server security is active and all Fileshare Client applications that try to access this Fileshare Server should supply a valid user-ID and password that are in the password file. If you do not provide a valid user-ID or password, access will be denied and a 9/037 error returned to the application.
  • FS136-I Fileshare Server security is not active.
    A password file has been specified, however the only user-ID specified in the file is the FSVIEW (supervisor) id. Because this is the only ID, Fileshare Server security is not active and Fileshare Client applications that try to access the Fileshare Server do not have to supply a valid user-ID or password.
  • FS138-W The log file has been backed up and a new one has been created.
    You see this message when the Fileshare Server is starting up and a recovery log file already exists. The Fileshare Server has determined that it is unable to append to the recovery log file because the last record in the log file indicates that it was not shut in a controlled manner.
  • FS139-I A matching date and time entry has been found in the log file.
    The Rollforward Recovery Utility displays this message when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and has applied the updates up to the date and time specified. This message implies that there were additional records stored in the recovery log file which were not processed as they were written after the time specified.
  • FS140-I No matching date and time entry has been found in the log file.
    You see this message displayed by the Rollforward Recovery Utility when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and reached the end of the log file before a record could be found that was written at the date and time specified. This implies that the date and time specified when performing the recovery is later than the date and time that the last record was written to the recovery log file. All the updates stored in the recovery log file have been applied to the data files.
  • FS142-W The Operating System does not permit the log file to be flushed to disk.
    You see this message when the Fileshare Server is using a recovery log file to store updates made to files. At certain points during its operation the Fileshare Server makes a call to the operating system to force it to flush the contents of the recovery log file to disk. This ensures that any data that has been written to the recovery log file is physically stored on disk and can be read in again after a system failure. The Fileshare Server performs this flush operation after every COMMIT operation is performed and at regular intervals (the default being after every 100 records have been written to the recovery log file, which can be changed using a /lc entry in the database reference file).
  • FS143-W The Operating System does not allow free disk space information to be obtained.
    When writing a recovery log file, it is important that there is enough disk space available. Consequently, the Fileshare Server makes periodic checks to see whether sufficient disk space remains.
  • FS144-W More than one communications protocol has been specified - synchronous communications mode not active.
    You have tried to start the Fileshare Server using the synchronous communications mode (as opposed to the asynchronous communications mode which is the default) using the /sc option.
  • FS145-W Fileshare Client disconnected, cannot contact user: text.
    The CCI has returned an error to the Fileshare Server indicating that a Fileshare Client has been disconnected. This message indicates that there may be a problem with the network or that the Fileshare Client application program is no longer functioning.
  • FS146-W Unexpected action code, action-code - discarded.
    You see this message when performing a rollforward recovery. The Rollforward Recovery Utility has read a record from the recovery log file which contains information not relating to any file currently being recovered. The information in the record cannot be processed and the Rollforward Recovery Utility has moved onto the next record in the recovery log file.
  • FS147-I A duplicate network message was received and discarded.
    This message only occurs when you are using the CCIIPX protocol and indicates that you are using an old version of the CCIIPX modules. The buffer sent between the Fileshare Client and Fileshare Server for each I/O request contains additional information which enables the Fileshare Server to check on the validity of the request. This message indicates that the Fileshare Server has received (in error) a duplicate of the previous buffer received from the communications system. This duplicate buffer has been discarded as it is not a valid I/O request.
  • FS148-I CCI return-code (function func) = code.
    You see this message when the Fileshare Server receives an unexpected error status from a CCI module. It is normally displayed in conjunction with a Fileshare Server message indicating the circumstances in which the error occurred.
  • FS149-I CCI SEND not complete, status will be checked later.
    A request sent back to a client application from the Fileshare Server has not completed within the expected time period. This message indicates that the Fileshare Server will continue processing requests from other client applications normally and will check the status of this request at a later time.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS101-I text -- parameter has been accepted.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS103-I The log filename has been added to the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS104-I The log file cannot be found, creating a new recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS105-W The disk free space for the log file is below acceptable limits.

The amount of disk space remaining is calculated as a percentage of the total size of the disk where the log file is being written. The default is for this warning to be displayed when less than 5 percent of the total disk space remains free. This percentage can be changed using the /p option when entering the log filename into the database reference file using the Database Reference File Maintenance Utility.

Note:

If disk space is not cleared, the drive where the recovery log file is located will become so full as to make rollforward recovery logging impossible.

Resolution:

Clear disk space on the drive where the recovery log file is being written so that the Fileshare Server can continue logging the updates being performed.

Alternatively, if the amount of free disk space is becoming very low, the Fileshare Server should be shut down and the recovery log file backed up and deleted before starting the Fileshare Server again.

Parent topic: Messages from FS101-I to FS149-I


FS106-I filename - added to database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS107-I filename - removed from the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS108-I Processing the files specified in the database reference file.

  • The Database Reference File Maintenance Utility searches through the list of files to check the integrity of each one and also determine the current sequence numbers that are in use (if any)
  • The Fileshare Server scans the names in the database reference file in order to determine the processing to be done on each file
  • The Rollforward Recovery Utility searches through the list of files to check the integrity of each file and the sequence number in the header of each one

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS109-W The file filename does not exist.

Resolution:

If the file should exist, ensure that the filename and the path specified are correct and that the Fileshare Server is able to open the file with read-write access. Also ensure that the file is not open by another process as the Fileshare system requires exclusive access to the file.

If the file should not exist (for example, it is expected that it will be created by an application program), then this warning can be ignored.

Parent topic: Messages from FS101-I to FS149-I


FS110-I filename - OK.

Resolution:

No action is required as this message is informational.

Parent topic: Messages from FS101-I to FS149-I


FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?

Resolution:

At the prompt enter Y or N depending on whether the Fileshare Server is to be closed down or not.

Parent topic: Messages from FS101-I to FS149-I


FS114-W Waiting for the old log file to be removed.

Resolution:

The current log file should be backed up. The log file should then be moved so that the Fileshare Server can continue writing to the directory. If a rollforward recovery is necessary, the log files should be provided in the order that they were created to the Rollforward Recovery Utility. The Rollforward Recovery Utility will prompt for the continuation log files as they are required, if they cannot be located automatically.

Parent topic: Messages from FS101-I to FS149-I


FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.

You see this message when the Rollforward Recovery Utility has been invoked to perform a rollforward recovery. The Rollforward Recovery Utility has read the sequence numbers from the header of the files and also the last one that was written to the recovery log file. The sequence number in the headers and in the log file are the same indicating that the last updates written to the recovery log file have been applied to the files. It is therefore not necessary to perform a rollforward recovery as there are no updates in the recovery log file that have not already been applied to the files.

It is not necessary to perform the rollforward recovery.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS122-I Communications too busy on CCI SEND - retrying.

The Fileshare Server will retry the operation until the CCI protocol has been able to complete the operation.

This message could indicate that the network or network software is reaching a limit or is very busy.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS123-I Communications too busy on CCI RECEIVE - retrying.

The Fileshare Server will retry the request until valid data is returned from CCI

This message could indicate that the network or network software is reaching a limit or is very busy

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS124-I Checking the validity of the log file, please wait.

The fact that the log file does not contain a valid last record indicates that the recovery log file was not closed in a controlled manner and that the Fileshare Server which was writing to the recovery log file terminated abnormally.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS125-I Recovery possible to last valid recovery log file record.

The Rollforward Recovery Utility will apply the updates up to the point of the last valid record stored in the recovery log file.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS126-I Performing recovery, please wait.

The Rollforward Recovery Utility will now start the recovery process. The time required to perform the recovery depends on the number of updates that are logged in the recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS127-S Invalid name mapping command.

See the section Filename Mapping in the chapter Advanced Operation and the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /fs option.

Resolution:

If the option has been specified on the command line, include the /af option to specify the name of the replacement string value and retry the operation.

If the option is specified in a database reference file, this error indicates that the database reference file has become corrupt or has been changed without using the Database Reference File Maintenance Utility.

In this situation, it may be possible to remove the invalid entry using a normal text editor. If this is unsuccessful, discard the current database reference file and create a new one using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS101-I to FS149-I
Related information
Filename Mapping
Database Reference File Maintenance


FS128-W Fileshare Server closedown invoked by Stop Run processing.

This message should not be displayed under normal circumstances. Possible causes for this error are:

  • Closing the Fileshare Session on Windows or a kill command on UNIX. Such methods of closing the Fileshare Server should not be used as it can lead to files being corrupted and the recovery log file not being written to disk correctly.
  • The Fileshare Server has encountered an internal processing error which has caused the closedown code in the run-time system to be invoked. In this situation you should contact our technical support department to try and ascertain the cause of this error.

The Fileshare Server terminates by closing all files, rolling back any outstanding transactions, clearing all communication links with Fileshare Clients and closing the recovery log file (if in use).

Resolution:

You should try to ascertain why the Fileshare Server closed in this manner.

Parent topic: Messages from FS101-I to FS149-I


FS129-I The Fileshare Server is still active.

This message indicates that the Fileshare Server is continuing to function as normal.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS097
FS111


FS130-I Reading database reference file, please wait.

The amount of time required to process the database reference file depends on the amount of information contained in the file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS131-W Invalid communications mode - parameter ignored.

Resolution:

Ensure that the value specified for the communications parameter is valid.

If you do not wish to specify a communications protocol you should not use the /cm option. The Fileshare Server uses the default communications protocol for the operating system on which it is running.

Parent topic: Messages from FS101-I to FS149-I
Related information
Communications


FS132-I The Fileshare Server is running with the following communication protocol(s):

The Fileshare Client application programs can use any of the protocols listed to contact this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS133-I Processing the password file, please wait.

The password file has been successfully located and opened and is now being processed.

The time required for this operation depends on the amount of information that is stored in the password file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS134-I The password file cannot be found - creating a new password file.

The Password File Maintenance Utility will therefore try to create a new password file of the name specified.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS135-I Fileshare Server security is active.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security


FS136-I Fileshare Server security is not active.

Logons are validated by the Fileshare Server by calling the FSSECLOG module.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

See the section Password File Maintenance in the chapter Security for more information about supervisor passwords.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security
Password File Maintenance


FS138-W The log file has been backed up and a new one has been created.

This implies that the Fileshare Server which was previously writing to this log file terminated abnormally.

Because the Fileshare Server is unable to append to the existing log file, it has been renamed and a new recovery log file has been created. This new recovery log file will be used.

Note:

This message implies that the correct sequence of regularly backing up data files and deleting recovery log files is not being performed as the Fileshare Server is being started when a recovery log file already exists.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging


FS139-I A matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS140-I No matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS142-W The Operating System does not permit the log file to be flushed to disk.

This message indicates that an error was returned from the operating system when it tried to flush the recovery log file to disk. This implies that the operating system does not enable application programs to force I/O buffers to be flushed to disk. Consequently, the Fileshare Server is unable to force the operating system to write the contents of the recovery log file to disk and in the event of a system failure, it is possible that not all of the contents of the recovery log file will be available when the recovery process is performed.

Resolution:

See the section Database Reference File Maintenance in the chapter Database Integrity and Rollforward Recovery for more details.

Parent topic: Messages from FS101-I to FS149-I
Related information
Database Reference File Maintenance


FS143-W The Operating System does not allow free disk space information to be obtained.

This message indicates that the call to the operating system to determine how much disk space is available has returned an error. This implies that the operating system does not enable applications to determine how much disk space is available.

Resolution:

It is the system administrator's responsibility to ensure that sufficient disk space is available, as the Fileshare Server is unable to determine the amount of free space available on the drive. If the Fileshare Server is unable to write a recovery log file because there is insufficient disk space, the Fileshare Server automatically closes down.

Parent topic: Messages from FS101-I to FS149-I


FS144-W More than one communications protocol has been specified - synchronous communications mode not active.

With this mode of communication it is only possible to start the Fileshare Server with one communications protocol.

This message indicates that the Fileshare Server is configured to use more than one communications protocol and so the synchronous communications option has been ignored.

The Fileshare Server has started, but it is not using the synchronous communications mode.

Resolution:

If the synchronous communications mode is required, make sure that the Fileshare Server is configured to use only one communications protocol.

Parent topic: Messages from FS101-I to FS149-I


FS145-W Fileshare Client disconnected, cannot contact user: text.

You see the user number and user name, if one was supplied at the time that this user logged onto the Fileshare Server.

The Fileshare Server has closed all files that this user had open and rolled back any outstanding transactions pending for this user.

The Fileshare Client application, if still active, will be returned a 9/124 error on its next I/O operation.

Resolution:

Check that the Fileshare Client application is still running. Also check for any adverse network conditions that could have forced the connection to have been dropped.

Parent topic: Messages from FS101-I to FS149-I


FS146-W Unexpected action code, action-code - discarded.

This message can indicate that the recovery log file has become corrupted in some way or that the recovery file contains invalid information.

Resolution:

As the rollforward recovery log file contains an invalid record, it is possible that not all of the record updates have been recovered from the file. After the recovery has completed the data in the files should be checked. If the problem recurs contact our technical support department.

Parent topic: Messages from FS101-I to FS149-I


FS147-I A duplicate network message was received and discarded.

Resolution:

Ensure that the latest CCIIPX modules are installed on the Fileshare Client and Fileshare Server machines.

Parent topic: Messages from FS101-I to FS149-I


FS148-I CCI return-code (function func) = code.

The message consists of a function code which indicates which CCI verb was being used at the time of the error and the return-code received from the CCI module.

The Fileshare Server calls CCI to determine details of the error that has occurred. This information is also displayed on the screen.

Resolution:

No action is required. However, the above information should indicate the cause of an error or unexpected occurrence during the Fileshare Server operation. This information should be used with any additional information contained in other messages to determine the cause of any errors.

When contacting our technical support department the above information is important and must be included with any problem report.

Parent topic: Messages from FS101-I to FS149-I


FS149-I CCI SEND not complete, status will be checked later.

Message FS228 is displayed when it is determined that the request eventually either completed or failed.

If you see this message frequently, it may be due to large record sizes taking longer to process than expected on slower network connections.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS228


Messages from FS151-I to FS200-W

  • FS151-I CCI message size received = text. Indicated send message size = text
    You see this message in conjunction with message FS014.
  • FS153-I The Fileshare Server name has been reregistered on the network.
    The Fileshare Server tried to register its name on the network so that Fileshare Clients can contact it. An error status was returned indicating that the Fileshare Server name was already registered on the network by a Fileshare Server which terminated abnormally. As this name is not being used by an active Fileshare Server, the name has been reregistered on the network by the Fileshare Server being started.
  • FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.
    The Fileshare Server is being started and is configured to use the CCI Trace option. This option can only be used by a supervisor because it can cause a large amount of disk space to be used for storing the CCI Trace file. When starting the Fileshare Server a password file should be specified that contains a user-ID of FSVIEW.
  • FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)
    You see this message displayed after the supervisor has entered the supervisor password to enable the use of CCI Trace. The Fileshare Server has confirmed that the password entered is correct and it is now possible to use CCI Trace.
  • FS156-W Incorrect password - CCI Trace is disabled.
    You see this message after the FSVIEW supervisor has entered the supervisor password to enable the use of CCI Trace.
  • FS158-I CCI Trace activated.
    This message indicates that the Fileshare Server has enabled the CCI Trace option and all requests made to CCI are being logged in the CCI Trace file.
  • FS159-I CCI Trace switched off.
    This message indicates that the Fileshare Server has turned off the CCI Trace option and all requests made to CCI are no longer being logged in the CCI Trace file. You see this message when the CCI Trace is either:
  • FS160-I Fileshare trace activated.
    You see this message displayed by the Fileshare Server when the trace option has been activated using the F2 key. All requests received by the Fileshare Server will be shown, with the operation code being requested, the name of the user performing the request and some additional information depending on the operation being performed. The result of the operation (including the file status) that is returned to the Fileshare Client is also shown.
  • FS161-I Fileshare trace switched off.
    You see this message displayed by the Fileshare Server when the trace option has been toggled off using the F2 key. The Fileshare Server no longer displays requests received or information about the data being returned to the Fileshare Clients. The Fileshare Server also is no longer writing to the trace file fsscreen.lst if the trace file option was specified when the Fileshare Server was started.
  • FS163-I Input useropcode [filename-1] [ filename-2].
    You see this message when the Fileshare Server trace option is activated and a request has been received by the Fileshare Server. The information displayed is as follows:
  • FS170-I Input- Logon.
    You see this message when the Fileshare Server trace option is activated and a logon request has been received by the Fileshare Server. The Fileshare Server will process the logon request and the result of the request will also be displayed. A logon request is always the first operation performed by a new Fileshare Client connecting to this Fileshare Server.
  • FS171-I Input- Logoff user.
    You see this message when the Fileshare Server trace option is activated and a log off request has been received by the Fileshare Server. If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Security is active. If no user name was supplied, then the user number is displayed.
  • FS172-I Input- Find File userfilename.
    You see this message when the trace option is activated and a Find File request has been received by the Fileshare Server from a Fileshare Client when a program tries to open a file. The Fileshare Server that should process the file has not been explicitly defined and more than one default Fileshare Server is configured.
  • FS173-I Output- userstatus.
    You see this message when the Fileshare Server trace option is activated and a request has been processed by the Fileshare Server and the result sent back to the Fileshare Client
  • FS176-W There is no backup directory specified in the database reference file.
    You tried to erase a backup directory entry from the database reference file but the database reference file does not contain a backup directory entry
  • FS177-S The backup directory specified cannot be found in the database reference file.
    You tried unsuccessfully to erase a backup directory-name from the database reference file. This is because the backup directory-name specified is not the same as the backup directory-name in the database reference file.
  • FS178-I The backup directory has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a backup directory-name to the database reference file and the operation has completed successfully. The database reference file now contains the name of the backup directory specified.
  • FS179-S A backup directory is already specified in the database reference file.
    You tried to add the name of the backup directory to the database reference file. However such an entry already exists in the database reference file which can only contain one recovery log file backup directory-name.
  • FS180-W The log filename specified has an extension. The name of the log file has been changed to "filename".
    The Database Reference File Maintenance Utility has been invoked to add the name of the recovery log file to the database reference file. The name of the log file specified contained an extension and this has been removed. The extension is removed to enable the Fileshare Server to automatically backup the recovery log file when necessary. The name of the log file added to the database reference file is shown.
  • FS182-W Output- Access Denied
    You see this message when the Fileshare Server trace option is activated and a logon request was received by the Fileshare Server from the Fileshare Client. This logon request has been denied, either because:
  • FS188-W Fileshare Server database reference file installation completed with errors.
    The Database Reference File Maintenance Utility has been used to update the contents of the database reference file. However, an error was found when parsing the command line passed to the utility or when processing the information stored in the database reference file.
  • FS189-W The backup directory does not exist.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS190-W The backup directory specifies the name of an existing file.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS191-W An error occurred accessing the backup directory.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS192-S More than one log file exists in the log file directory.
    You see this message when the Fileshare Server is starting up. The Fileshare Server has searched the directory where the recovery log file is to be written and has determined that more than one recovery log file exists in the directory. The Fileshare Server is unable to determine which of these recovery log files is a valid one and hence which one it can append data to.
  • FS193-S Unable to open the log file.
    The Fileshare Server has determined that a recovery log file exists in the directory where the recovery log file is specified but an error was returned when the Fileshare Server tried to open it.
  • FS194-I The log file "filename-1" has been backed up successfully to "filename-2".
    This message indicates that the Fileshare Server has successfully backed up the recovery log file. The backup operation was performed either as a request from FSVIEW or FSMGR or because the current recovery log file cannot be appended to and has been automatically backed up when the Fileshare Server has started. filename-1 is the name of the log file that has been backed up. filename-2 is the name of the file that the log file has been backed up to.
  • FS195-I The Fileshare Server is using the log file "filename".
    The Fileshare Server has successfully opened (and created if necessary) the recovery log file indicated and is writing recovery records to this log file.
  • FS196-W Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS197-S Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS198-W The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS199-S The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS200-W The attempt to backup the log file to "filename" failed.
    The Fileshare Server tried to copy the recovery log file to the directory and name specified but encountered an error when doing so. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS201 to FS300
Messages from FS301 - FS400


FS151-I CCI message size received = text. Indicated send message size = text

The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error states that the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.

This message shows the amount of data that has been received by the Fileshare Server and also the amount of data that was sent by the Fileshare Client.

The Fileshare Server has ignored the data sent from the Fileshare Client.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent any reply back. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS014-W


FS153-I The Fileshare Server name has been reregistered on the network.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.

See the section Password File Maintenance in the chapter Security for more information.

See also the messages FS155 and FS156.

Resolution:

At this prompt enter the supervisor password that corresponds to the entry in the password file for the user-ID of FSVIEW

Parent topic: Messages from FS151-I to FS200-W
Related information
Password File Maintenance
FS155
FS156


FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)

This prompt is to determine if the Fileshare Server is to trace communication requests immediately and include all of the CCI initialization requests made by the Fileshare Server.

Resolution:

Responding Y enables the Fileshare Server to start using CCI Trace immediately and causes all CCI initialization requests to be traced to the CCI Trace file. The CCI Trace remains operational until toggled off using the F3 key.

Entering any other response apart from Y does not enable CCI trace immediately. However, CCI trace can be toggled on at a later time using the F3 key.

See also the messages FS154 and FS156.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS154
FS156


FS156-W Incorrect password - CCI Trace is disabled.

The Fileshare Server has determined that the password entered is incorrect and has consequently disabled the use of the CCI Trace feature.

Resolution:

If CCI Trace is required then the Fileshare Server should be brought down using the Esc key sequence. Ensure that when starting the Fileshare Server the /pf option is used to specify a password file that contains a password for the user-ID FSVIEW. When prompted to enter the supervisor password the password for the FSVIEW user-ID should be entered.

If CCI Trace is not required then no action is required as the Fileshare Server has started and the CCI Trace feature is not enabled. However, to prevent this message in future, the Fileshare Server should be reconfigured not to use CCI Trace.

Parent topic: Messages from FS151-I to FS200-W


FS158-I CCI Trace activated.

You see this message when either CCI Trace is made active on start-up, or is toggled on using the F3 key while the Fileshare Server is operational.

Note:

The CCI Trace file can become very large. If no disk space remains to enable the CCI Trace file to be written, no errors are reported and the tracing of CCI requests is suspended.

Resolution:

No action is required

Parent topic: Messages from FS151-I to FS200-W


FS159-I CCI Trace switched off.

  • Not made active immediately on the Fileshare Server starting up (see the message FS155)

    or

  • Toggled off using the F3 key while the Fileshare Server is operational

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS155


FS160-I Fileshare trace activated.

If the trace to a file option was specified when the Fileshare Server was started then the information displayed on the screen is also written to a file called fsscreen.lst.

The trace option can be toggled off using the F2 key.

See also message FS161.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS161


FS161-I Fileshare trace switched off.

The trace option can be toggled on using the F2 key.

See also message FS160.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS160


FS163-I Input useropcode [filename-1] [ filename-2].

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here if Fileshare Security is active. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2, etc.
opcode | This is an indication of the type of action requested by the Fileshare Client. Most normal operations appear as an action-code. If a byte stream operation is being performed, the name of the operation is displayed. For COMMIT operations, an indication is given if the COMMIT is part of a prepare, confirm or abort stage of the transaction processing (if the transaction spans more than one Fileshare Server).
filename-1 | If the operation being performed is specific to a file then the name of the file is displayed here
filename-2 | If the operation being performed is specific to a file and requests to the file are being mapped to a different file using the alternate filename mapping option, the actual name of the file being processed is displayed here

The information displayed will also be written to a file called fsscreen.lst if the trace file option was specified when the Fileshare Server was started.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS170-I Input- Logon.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS171-I Input- Logoff user.

The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.

A logoff request is the last operation performed by a Fileshare Client when the Fileshare Client application program terminates.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS172-I Input- Find File userfilename.

The Fileshare Client is in the process of polling each default Fileshare Server to determine if that Fileshare Server should process requests for this file.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Server security is active. If no user name was supplied, then the user number is displayed. The user number is generated when the Fileshare Client logs on to this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
filename | The name of the file that the Fileshare Client is trying to open

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS173-I Output- userstatus.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
status | The error status generated from the result of the requested operation. For normal file I/O operations this is the same format as standard file I/O statuses. Note that this status may not be the status that is returned to the application program. The Fileshare Client uses the status displayed here to do any status conversion necessary (for example, to an RM COBOL status) 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


Using COBOL and Java Together

  • Java and COBOL Interoperability Options
  • Considerations
  • Linking to the Multi-threaded Run-time System
  • Calling Procedural COBOL from Java
    This chapter describes how you can access legacy procedural COBOL programs from Java using the support provided in the com.microfocus.cobol.RuntimeSystem class.
  • Calling Java from OO COBOL
    This chapter shows you how to code a COBOL program to call Java methods using the OO COBOL Java domain.
  • Calling OO COBOL from Java
    This chapter describes how you can access COBOL objects from Java programs. This is slightly different from the method for accessing procedural COBOL from Java programs.
  • Java Data Types
    This chapter describes how COBOL and Java data types are mapped on to each other.
  • JVM COBOL Interoperating with Java
    This section covers how to call JVM COBOL from Java, how to call Java from JVM COBOL and some examples.
Parent topic: Programming


Java and COBOL Interoperability Options

Visual COBOL offers a number of different ways in which you can integrate COBOL and Java. Certain methods may require changes to your existing application and some methods may be more suited to certain types of application than others. This topic outlines each method then summarizes the different factors that will influence the method that you choose.

Enterprise Server support for EJBs and Java Beans

Enterprise Server is an application server for COBOL applications. Enterprise Server provides high-performance and also provides mainframe subsystem emulation.

You use the Interface Mapping Toolkit functionality (IMTK) in Visual COBOL to generate an EJB or a J2SE bean which accesses the COBOL application running in Enterprise Server. The bean, in turn, uses a JCA resource adapter deployed into a Java application server.

Restriction:
  • It is not possible to access Java classes directly from the COBOL application.
  • The IMTK functionality is only available in Visual COBOL for Eclipse and is not available in Visual COBOL Development Hub.

For more information, see Tutorial: Interface Mapping Toolkit available in the product help of Visual COBOL for Eclipse.

Compiling COBOL application directly to Java byte code

This scenario is suitable for applications that do not require Enterprise Server or any transaction support and when the best possible integration with Java is required.

JVM COBOL compiles to Java byte code which runs directly inside the JVM, providing full integration of COBOL with Java. With this method, Java classes can call existing COBOL applications using a variety of techniques and COBOL applications can also call Java classes or routines provided by the Java SDK.

You must build the JVM COBOL applications on the platform they are deployed to.

Due to the nature of the JVM, COBOL applications are likely to see some reduction in performance in comparison to COBOL applications running outside of the JVM in a regular native environment. The reduction in performance varies from application to application. Heavily intensive batch applications may experience lower performance whereas an interactive application may have no appreciable difference in responsiveness.

It is recommended you conduct some performance testing against your existing application to determine if performance levels will be satisfactory.

For more information, see JVM COBOL Interoperability and the Managed COBOL Tutorials available in the product help of Visual COBOL for Eclipse.

Using the COBOL Java Domain and the Java Native Interface (JNI)

The following scenarios are most suitable for desktop applications where you require the highest performance. COBOL runs as native code in the COBOL Server runtime. To use COBOL and Java together, you code the calls using the supplied support libraries.

These are the approaches for integrating COBOL with Java 2 Standard Edition (J2SE):

  • Calling procedural COBOL from Java - you use the support provided in the com.microfocus.cobol.RuntimeSystem class. This class is extended to provide the CobolBean class. This RuntimeSystem class support also enables you to call Java from procedural COBOL, through the Java Native Interface (JNI).
  • Calling Java from OO COBOL - you use the Java object domain for OO COBOL via the INVOKE verb.
  • Calling OO COBOL from Java - you create a Java wrapper class that provides a function for each method in the OO COBOL class. See The Wrapper Class.

For more information, see Related Information.

The following is a summary of the technologies supported in each scenario and the mechanisms to integrate your applications with Java:

Table 1. COBOL and Java integration options
 | Enterprise Server | Java Byte Code | COBOL Java Domain
Java application server support | Yes, support is available for all popular application servers. See Additional Software Requirements. | Yes. See Additional Software Requirements. | Not available. It is not recommended to use JNI in Java application servers as this is not compliant with the EJB standard.
Database support | ODBC or a supported database vendor precompiler. | JDBC using OpenESQL. | ODBC or a supported database vendor precompiler.
Desktop Java applications | Not a typical usage. | Yes | Yes
EJB support | Yes | Yes | No
File IO transactions | Yes, through Fileshare. | Not available as Fileshare is not supported in a Java application server. Note: Fileshare is supported on the desktop*. | Yes, through Fileshare.
Fileshare support | Yes | No | Yes
Interoperability mechanism and performance | The COBOL application runs as native code in Enterprise Server. You use the IMTK to generate an EJB or a J2SE bean which accesses the COBOL code and which in turn uses a JCA resource adapter deployed into the Java application server. | The COBOL application is compiled to Java byte code which is directly accessed by Java. | The COBOL application runs as native code and Java is accessed using JNI.
Mainframe subsystem support | Yes | No | No
JEE container managed transaction support | Yes. There is a separate database connection but a coordinated transaction between the application server and Java. | Application-managed transaction support only. | Application-managed transaction support only.
Java SDK access from COBOL | No | Yes, fully supported. | All Java types are supported using the INVOKE verb. If using a native call through the JNI interface, you need to add some extra code. You can use the Micro Focus class library to create user-defined types and mappings.
Web Service endpoint | Yes | Not directly. Java must act as the endpoint and call COBOL. | No
Parent topic: Using COBOL and Java Together
Related concepts
Calling Java from OO COBOL
Calling OO COBOL from Java
Calling Procedural COBOL from Java
JVM COBOL Interoperating with Java
The Wrapper Class
* On the desktop, file handling uses the "native" file handler which supports Fileshare. In a server environment such as Java EE, however, Visual COBOL uses the managed file handler which has no support for Fileshare, ACU, or RM files.


Considerations

  • Setting Up the Environment for Java and COBOL
  • Java/COBOL Application Launcher
  • Compiling COBOL Programs that Call Java
  • Compiling COBOL Programs that Are Used from the CobolBean interface
  • Linking to the Multi-threaded Run-time System
  • Migrating Applications between JDK 8 and JDK 11
Parent topic: Using COBOL and Java Together


Setting Up the Environment for Java and COBOL

You need a Java run-time system on any machine that is going to execute Java applications. If you are going to develop mixed Java and COBOL applications, you will need either the Java Development Kit (JDK) available from Oracle or a compliant JDK such as OpenJDK from AdoptOpenJDK.

Your COBOL development system currently supports several Java run-time systems.

If you have installed the product to a directory other than the default one, ensure you run the cobsetenv script after installation, as described in this product's installation notes. The script sets or modifies the following environment variables: COBDIR, PATH, CLASSPATH and LD_LIBRARY_PATH (or LIBPATH on AIX). If you did install to the default directory, these variables already point to the correct locations.

The JDK install location must be included on PATH.

To run COBOL and Java together, you need to use the Java/COBOL application launcher, cobjrun, instead of the java or cobrun triggers.

If the JAVA_HOME environment variable is set to the Java install location, then cobjrun uses it in preference to the Java install location which is included on PATH.

Note:
  • On AIX, cobjrun requires that the OS Thread Stack Size is greater than 192k. If this value is lower than 192k, you must execute cobjrun run with the -Xmso192k option - for example, cobjrun -Xmso192k main.

    To check what the OS Thread Stack Size is, executing the following at a terminal: java -verbose:sizes. The OS Thread Stack Size is the number nnn for the "-Xmsonnn" option.

Parent topic: Considerations
Related reference
Using the Java/COBOL Application Launcher from the Command Line


Compiling COBOL Programs that Call Java

Restriction: This applies to native code only.

Any COBOL program which is going to call Java must be compiled with the following directive:

ooctrl"+p-f"

This does two things:

  • Adds type information to invoke statements, which the COBOL run-time system needs to convert data correctly between the COBOL and Java domains
  • Prevents the compiler from folding method names it invokes to lower-case - Java method names are case-sensitive
Parent topic: Considerations


Compiling COBOL Programs that Are Used from the CobolBean interface

Restriction: This applies to native code only.

Any COBOL program which is going to be called from Java using CobolBean.cobcall*() methods should be compiled with the DATA-CONTEXT Compiler directive. This enables the run-time system to create new application storage areas for each instance of a CobolBean that is created.

Parent topic: Considerations


Linking to the Multi-threaded Run-time System

Restriction: This applies to native code only.

All COBOL programs for use with Java must be linked to the multi-threaded run-time system.

Parent topic: Considerations
Parent topic: Using COBOL and Java Together


Migrating Applications between JDK 8 and JDK 11

The Java Standard Edition Development Kit (JDK) 11 has gone through important changes, enhancements, removal of APIs and features, and deprecation of APIs and features.

These changes might affect the behavior of COBOL JVM applications or the use of Micro Focus Java Class libraries. Micro Focus recommends that you consult the Oracle JDK Migration Guide before migrating your applications to JDK 11 - click here to view the guide.

Parent topic: Considerations


Calling Procedural COBOL from Java

This chapter describes how you can access legacy procedural COBOL programs from Java using the support provided in the com.microfocus.cobol.RuntimeSystem class.
Restriction: This applies to native code only.
  • Overview - Calling Procedural COBOL from Java
  • Coding Your Java Program
  • Multi-threading Considerations
  • Loading a COBOL Program or Library
  • Using the cobcall() Methods
  • Examples of Calling COBOL from Java
  • Changing Data Members in a Java Object
  • Using CobolBean for Instance Data
  • Canceling a COBOL Program
  • Handling Strings from a Java Program
  • Pointer Class
  • mfjstring
  • CobolNational Class
  • Using Custom Records to Pass Group Items
  • Using JNI with COBOL
  • Example of Throwing an Exception
Parent topic: Using COBOL and Java Together
Related concepts
Calling Java from OO COBOL
Calling OO COBOL from Java
Java and COBOL Interoperability Options
JVM COBOL Interoperating with Java
The Wrapper Class


Overview - Calling Procedural COBOL from Java

Restriction: This applies to native code only.

You can call procedural COBOL programs from Java or from EJBs written in any language, not necessarily COBOL. There are a number of ways of doing this, which are summarized in the chapter Using Java and COBOL Together chapter.

This chapter describes how to use the support provided in the com.microfocus.cobol.RuntimeSystem class and the CobolBean class, which is actually an extension to the RuntimeSystem class and uses RuntimeSystem.cobcall*() methods. Use this technique if you do not want to use OO COBOL and will not be using Enterprise Server.

Access to Java objects is available either through the Java Native Interface (JNI), or by use of the OO COBOL Java domain.

The Java support in the com.microfocus.cobol.RuntimeSystem class provides functions which enable you to load, call and cancel COBOL programs. It also enables you to pass parameters to a COBOL program using a Java array. The functions in com.microfocus.cobol.RuntimeSystem class unpack the array and pass the data to your COBOL program in a form it can use. The figure below shows a Java program calling a COBOL program and passing it two parameters.

Calling COBOL from Java

You need to have at least a basic knowledge of the Java language to be able to use this technology effectively. Oracle's Java Web site is a good starting place.

See the section Setting Up the Environment for Java and COBOL in the chapter Using Java and COBOL Together for instructions on how to set up the environments.

Parent topic: Calling Procedural COBOL from Java
Related information
Java Web site
Setting Up the Environment for Java and COBOL


Coding Your Java Program

Restriction: This applies to native code only.

A Java program calls a COBOL entry point by using the functions in RuntimeSystem.class, supplied in mfcobol.jar. This class contains a set of functions named cobcall_returntype(), where returntype is the data type returned by the COBOL program or entry point you want to call. For example, use cobcall_int() to call a COBOL program which returns an integer.

To make COBOL support available to your Java program, include the following statement at the start of your Java source file:

import com.microfocus.cobol.*;
Parent topic: Calling Procedural COBOL from Java


Multi-threading Considerations

Restriction: This applies to native code only.

Java run-time systems are multi-threaded, so any COBOL program you are going to use with Java must be linked with the COBOL multi-threaded run-time system whether or not the Java program calling it uses multi-threading. If your COBOL program is called from a multi-threaded Java program, you need to take care that COBOL data accessed from one thread is not corrupted by another thread.

There are several ways you can deal with this:

  • Compile your COBOL programs with the SERIAL directive.

    SERIAL causes the COBOL run-time system to serialize access to your COBOL code between different threads. Only one thread can access your program at a time. This is the safest option, although it has potentially the highest overhead for execution speed. It is suitable when the COBOL program is providing access to a shared resource (for example, a printer), or when the COBOL program called from Java is in turn calling other COBOL programs which have not been enabled for multi-threading.

  • Compile your COBOL programs with the REENTRANT"2" directive.

    REENTRANT"2" causes the COBOL run-time system to allocate separate user data and FD file areas to each different thread. This prevents any conflicts or data corruption within the program. But REENTRANT"2" can't guarantee thread safety if it calls other non-threaded programs, or accesses other shared resources - in these sorts of cases, SERIAL is a safer option. The REENTRANT"2" directive can provide better performance than SERIAL as one thread is not kept waiting for the next thread to finish.

  • Use thread-local storage in your COBOL programs instead of working storage.

    Thread-local storage is allocated per thread, so there is no possibility of one thread corrupting the data used by another thread. This is fairly efficient, but might not be always be an option with legacy code.

  • Multi-thread your COBOL program using COBOL multi-threading syntax or run-time system calls.

    This can be very efficient as you control which data is thread-local and which data is shared between threads. You could use this option with legacy COBOL code if you are ready to write COBOL driver programs to sit between the Java run-time environment and your legacy programs. Your driver program would be responsible for controlling access to the legacy programs, and would have to use semaphores or some similar mechanism to prevent two threads from accessing the same code at the same time.

    You need to be very careful when canceling a COBOL program in a threaded environment where the program is shared between threads. This applies whether you are using CANCEL or the com.microfocus.cobol.RuntimeSystem.cobcancel() method calls. If possible avoid canceling altogether.

Alternatively, consider using the CobolBean interface, which associates a COBOL programs working storage with a instance of a CobolBean class.

Parent topic: Calling Procedural COBOL from Java


Loading a COBOL Program or Library

Restriction: This applies to native code only.

If your COBOL programs are linked into a library file, or if you want to expose entry-points inside a COBOL program, you need to load the library file or programs before making any calls. You can do this using the runtime.cobload() method in runtime.class. For example, to load the programs inside mycbl:

{
  if (RuntimeSystem.cobload("mycbl") != 0)
     System.out.println("Could not load library\n") ;
  else
     System.out.println("Library loaded successfully\n") ;
}
Parent topic: Calling Procedural COBOL from Java


Using the cobcall() Methods

Restriction: This applies to native code only.

Once you have loaded the libraries or programs required by your Java application (see the previous section for details) you can make calls to COBOL using the cobcall_ methods. The cobcall_ methods are all static methods of RuntimeSystem.class, so you do not have to instantiate RuntimeSystem.class before starting. Each cobcall_ method takes two or three parameters (the third parameter is optional):

Style 1:

  • A string naming the COBOL program
  • A Java object array containing any parameters you want passed to the COBOL program, in the order they appear in the USING clause of the COBOL program's Procedure Division header. By default, parameters are passed by reference.
  • A Java integer array defining the USAGE clause for each parameter. You can select BY REFERENCE, BY VALUE or BY CONTENT, defined by static values of com.microfocus.cobol.RuntimeSystem

Style 2:

  • A string naming the COBOL program
  • A list of parameters encapsulated in a ParameterList()

Parameters are converted between Java and COBOL data types as described in the chapter Java Data Types. As explained in the section Coding Your Java Program there are different cobcall_ methods, each named according to the Java equivalent of the data type returned by the COBOL program or entry being called. For example, a COBOL program that returns a signed integer (such as a pic s9(9) comp-5) is returning the Java data type int. So you would call the COBOL program using the cobcall_int method. By default all parameters are passed by reference.

The copybook javatypes.cpy also provides a set of COBOL type definitions for Java data types. We advise you to use the data types defined in this file to declare COBOL data items that are going to be used for passing parameters between Java and COBOL. Using these data types helps keep your code portable between different COBOL platforms.

See the Java Run-time Class Library Reference, which is in docs/mfcobol.docs.zip in your COBOL development system installation.

Parent topic: Calling Procedural COBOL from Java


Examples of Calling COBOL from Java

Restriction: This applies to native code only.

This section shows you two short examples of calling a COBOL program from Java. The first example shows the following features:

  • Passing data to a COBOL program by reference (the default)
  • Returning an integer by using cobcall_int()

This is a simple COBOL subroutine, named legacy.cbl:

working-storage section.
copy "javatypes.cpy".
01 wsResult       jint.

linkage section.
01 wsOperand1     jint. *> type defined in javatypes.cpy
01 wsOperand2     jint.
01 wsOperation    pic x.

procedure division using wsOperand1 wsOperand2 wsOperation.
    evaluate wsOperation
    when "a"
        add wsOperand1 to wsOperand2 giving wsResult
    when "s"
        subtract wsOperand1 from wsOperand2 giving wsResult
    end-evaluate
    exit program returning wsResult.

This is a Java program which calls the subroutine:

import com.microfocus.cobol.* ;
class SimpleCall
{
   public static void main(String argv[]) throws Exception
   {
       int i = RuntimeSystem.cobcall_int("legacy",
                        new ParameterList()
                                   .add((int)4
                          .add((int)7
                                   .add((byte)'a'));
       System.out.println(i) ;
   }
}

The second example shows you how to pass data to a COBOL program with the equivalent of different usage clauses. The cobcall() method used does not return a value, but it takes an object as the first parameter, and returns the same object type from the COBOL program. SimpleCall2 passes the first parameter by reference, the second by value, and the third by content.

import com.microfocus.cobol.* ;

class SimpleCall2
{
   public static void main(String argv[]) throws Exception
   {
      RuntimeSystem.cobcall(null, "usages",
                    new ParameterList()
                    .add((int)1, RuntimeSystem.BY_REFERENCE)
                    .add((int)2, RuntimeSystem.BY_VALUE)
                    .add((int)3, RuntimeSystem.BY_CONTENT));
   }
}
Parent topic: Calling Procedural COBOL from Java


Changing Data Members in a Java Object

Restriction: This applies to native code only.

The example in this section is similar to the example in the previous section, except that the result from the COBOL program is also used to change the value of one of the data members in the Java object.

thread-local-storage section.
copy "javatypes.cpy".

linkage section.
01 wsOperand1               jint.
01 wsOperand2               jint.
01 wsOperation              pic x.
01 wsResult                 jint.

procedure division using wsOperand1 wsOperand2 wsOperation
                         wsResult.
    evaluate wsOperation
    when "a"
        add wsOperand1 to wsOperand2
    when "s"
        subtract wsOperand1 from wsOperand2
    end-evaluate
    exit program returning wsResult

The Java class SimpleCall2 assumes that legacy2.cbl is built into a library file called legacy2.ext. However, if this subroutine were built into a different library file, you would need to use the RuntimeSystem.cobload() method to load the library file before making calls to the legacy program.

import com.microfocus.cobol.* ;
class SimpleCall2
{
   Integer simpleInteger1;
   Integer simpleInteger2;
   Integer simpleResult;
   public SimpleCall2(int a, int b)
   {
      simpleInteger1 = new Integer(a);
      simpleInteger2 = new Integer(b);
      simpleResult   = new Integer(0);
   }
   public String toString()
   {
      return new String(
            "simple1Integer1 = "+simpleInteger1+"\n" +
            "simple1Integer2 = "+simpleInteger2+"\n" +
            "simpleResult    = "+simpleResult);
   }
   public static void main(String argv[]) throws Exception
   {
      SimpleCall2 firstDemo = new SimpleCall2(4,7);
      Object theParams[] = { firstDemo.simpleInteger1,
                             firstDemo.simpleInteger2,
                             new Byte((byte) 'a'),
                             firstDemo.simpleResult }
      System.out.println("Before call\n"+firstDemo) ;
      int i = RuntimeSystem.cobcall_int("legacy2",theParams);
      System.out.println("After call\n"+firstDemo) ;
   }
}
Parent topic: Calling Procedural COBOL from Java


Using CobolBean for Instance Data

Restriction: This applies to native code only.

The com.microfocus.cobol.CobolBean class enables you to associate an instance of CobolBean to an instance of a COBOL program's storage section without having to recode the COBOL application to either be thread-safe or take the parameters from the Java application.

For example, the following COBOL program shares the same data when it is called using cobcall() by more than one Java class.

$set data-context
 working-storage section.
 01 address-rec pic x(30).

 linkage section.
 01 lnk-address-rec pic x(30).

 procedure division.
    goback.
 entry "setAddressBook" using lnk-address-rec.
    move lnk-address-rec to address-rec
    exit program returning 0.
  entry "getAddressBook" using lnk-address-rec.
    move address-rec to lnk-address-rec
    exit program returning 0.

You can create a Java class that extends from com.microfocus.cobol.CobolBean, and this makes an instance (data-context) version of cobcall() available. You need to compile any COBOL programs called from CobolBean.cobcall() with the Compiler directive DATA-CONTEXT rather than using any threading directive such as RE-ENTRANT(1/2), SERIAL. The Compiler directive DATA-CONTEXT informs the COBOL run-time system to allocate a new COBOL Working-Storage Section whenever it is being used from CobolBean.cobcall().

In the following example, if the COBOL program shared data, bean1.getAddress() would be the same as bean2.getAddress(), causing problems. However because the Java program uses the cobcall() from CobolBean, the COBOL Working-Storage Section is associated with the bean.

import com.microfocus.cobol.*;
import com.microfocus.cobol.lang.*;

public class MyBean extends com.microfocus.cobol.CobolBean
{
   private StringBuffer address = new StringBuffer(30);

   public MyBean() throws Exception
   {
     super();
     super.cobload("addbook");
   }

   public String getAddress() throws Exception
   {
     Pointer addressPointer =
           new Pointer(this.address.toString(),30);
     super.cobcall("getAddressBook",
           new ParameterList().add(addressPointer));
     this.address.setLength(0);
     this.address.append(addressPointer.toString());
     return address.toString();
   }

   public void setAddress(String address) throws Exception
   {
     super.cobcall("setAddressBook",
           new ParameterList().add(new Pointer(address,30)));
   }

   public static void main(String[] args) throws Exception
   {
      MyBean bean1 =new MyBean();
      bean1.setAddress("Mr A");

      MyBean bean2 =new MyBean();
      bean2.setAddress("Mr B");

      System.out.println("bean1.getAddress="+
                            bean1.getAddress());
      System.out.println("bean2.getAddress="+
                            bean2.getAddress());
   }
}
Parent topic: Calling Procedural COBOL from Java


Canceling a COBOL Program

Restriction: This applies to native code only.

To prevent memory leaks you should cancel any COBOL programs you have loaded from Java before the owning Java object is subjected to garbage collection. Use the following call from the Finalize method of the Java object:

RuntimeSystem.cobcancel("program")

where program is the name of a COBOL program loaded using a RuntimeSystem.cobload() call. The following is an example of a Finalize method in a Java program:

private void Finalize()
      {
       try
          {
            RuntimeSystem.cobcancel("demoFinalizers");
            System.out.println("demoFinalizers - finalize'ed");
         }
       catch(Exception e)
         {
           System.out.println(
                "Error during finalize : "+e.getMessage());
             }
          }
CAUTION:
  • You should only cancel a program when you are sure you that no other program is using the program. This might be difficult in a server/threaded program.
  • This method is "Finalize" not "finalize" as we do not want the instance to be called during garbage collection as this may cause a memory block in the garbage collection process.
Parent topic: Calling Procedural COBOL from Java


Handling Strings from a Java Program

Restriction: This applies to native code only.

You pass strings to COBOL using either the String or StringBuffer class. You can use any the following mechanisms to do this:

  • Pointer class. This enables you to pass a Java string to a COBOL program without changing the COBOL source code. The Pointer class is in the com.microfocus.cobol.lang package.
  • mf-jstring. This enables you to convert a Java string to a user-defined type called mf-jstring, which is defined in javatypes.cpy. This user-defined type gives you full access to the information available from Java, this includes the data, the length of the string and the capacity of the string or string buffer.
  • CobolNational. This java class enables you to create UTF-16 strings that can be passed to a COBOL PIC N(...) USAGE NATIONAL field.
Parent topic: Calling Procedural COBOL from Java


Pointer Class

Restriction: This applies to native code only.

An intrinsic problem with passing Java strings to COBOL is that Java strings are variable length whereas COBOL strings are fixed length. For COBOL to modify a predefined fixed-length field, you need to wrap the instance in a new instance of the Pointer class. The Pointer class is in the com.microfocus.cobol.lang package.

For example, here is a COBOL program that defines a PIC X(20) data item:

showbytes.cbl:
       working-storage section.
       linkage section.
       01 lnk-string     pic x(20).
       procedure division using lnk-string.
          display "lnk-string = " lnk-string.
          move "Hello from COBOL - 1" to lnk-string.
          exit program returning 0.

The corresponding Java code would be:

showbytes.java:

import com.microfocus.cobol.RuntimeSystem;
import com.microfocus.cobol.lang.Pointer;
import com.microfocus.cobol.lang.ParameterList;

public class showbytes
{
  public static void main(String[] args) throws Exception
  {
   String myString = new String("Hello to COBOL");
   Pointer ptr2String = new Pointer(myString, 20);

   RuntimeSystem.cobcall("showbytes",
             new ParameterList().add(ptr2String));

   myString = ptr2String.toString();

   System.out.println(myString = ["+myString+"]");
  }
}
Parent topic: Calling Procedural COBOL from Java


mfjstring

Restriction: This applies to native code only.

A COBOL program cannot modify the contents of a String passed to it, but it can change a StringBuffer. To make handling strings easier, javatypes.cpy defines the type MF-JSTRING. This data type has the following structure:

01 mf-jstring is typedef.
    03 len                  jint.
    03 capacity             jint.
    03 ptr2string           pointer.

The len field defines the length of the string. The capacity field defines the size of the buffer - this field is always 0 for a String. The ptr2string field is a pointer to the start of the actual string. In the case of a StringBuffer, you can either modify the existing buffer, or allocate a new one and set ptr2string to the start of the new buffer.

The COBOL program below concatenates a String and StringBuffer from Java, and returns the result in the StringBuffer.

 program-id. StringAdd.
 thread-local-storage section.
 copy "javatypes.cpy".
 01 lsNewPtr                 pointer.
 01 lsSize         jint. *> type defined in javatypes.cpy
 01 i              jint.
 01 lsStatus       jint.
 01 lsBigBuffer              pic x(1024).
 linkage section.
 01 lnkJString               mf-jstring.
 01 lnkJStringBuffer         mf-jstring.
 01 lnkString                pic x(256).
 01 lnkStringbuffer          pic x(256).
 procedure division using lnkJString lnkJStringBuffer.
     set address of lnkStringBuffer to
                              ptr2string of lnkJStringBuffer
     set address of lnkString to ptr2string of lnkJString
*>   Check that lnkJStringBuffer is a Java StringBuffer
     if capacity of lnkJStringBuffer > 0
         add len of lnkJString to len of lnkJStringBuffer
                                   giving lsSize
*>   Check we don't overflow concatenation buffer
         if lsSize < 1024
             move len of lnkJString to i
             move lnkString(1:i) to lsBigBuffer
             add 1 to i
             move lnkStringBuffer to lsBigBuffer(i:lsSize)
             set ptr2string of lnkJStringBuffer
                                 to address of lsBigBuffer
             move lsSize to len of lnkJStringBuffer
         end-if
     end-if

The Java class StringsToCobol passes "fred" and "ginger" to StringAdd and then displays the result.

import mfcobol.*;
public class StringsToCobol {
  public static void main(String[] args) throws Exception
  {
      StringBuffer sb1 = new StringBuffer("ginger") ;
      Object theParams[] = {"fred" ,
                             sb1} ;
       RuntimeSystem.cobcall_int("stringadd", theParams) ;
       System.out.println(sb1) ;
  }
}
Parent topic: Calling Procedural COBOL from Java


CobolNational Class

Restriction: This applies to native code only.

The CobolNational Java class enables you to create UTF-16 strings that can be passed to a COBOL PIC N(...) usage is national field.

For example, the following COBOL program, hellonat, receives the string "Hello From Java" into a data item defined as PIC N(40) USAGE IS NATIONAL:

 $set unicode(portable)
  working-storage section.
  linkage section.
  01 lnk-natstring   pic n(40) usage is national.
  procedure division using lnk-natstring.
      display "Java said to COBOL [" lnk-natstring "]"
      move "Hello From Java" to lnk-natstring
      exit program returning 0.

The corresponding Java code passes the string "Hello From Java" to the COBOL program, hellonat:

CobolNational cobnat =
                 new CobolNational("Hello From Java", 40);
RuntimeSystem.cobcall("hellonat",
              new ParameterList().add(cobnat));
System.out.println(cobnat.toString());
Parent topic: Calling Procedural COBOL from Java


Using Custom Records to Pass Group Items

Restriction: This applies to native code only.

The CustomRecord interface in com.microfocus.cobol.lang enables you to pass group items to a legacy COBOL program, when using cobCall() and cobrcall().

The CustomRecord interface is:

package com.microfocus.cobol.lang;
public interface CustomRecord
{
  public Object[] getParameters();
  public void setParameters(Object[] parms);
}

The data item customerDetails can be defined as follows:

  01 customerDetails.
         03 customerName       pic x(30).
         03 customerAddress    pic x(30).
         03 customerRef        pic 9(6).

A Java implementation could be:

import com.microfocus.cobol.lang.*;
import java.text.*;

public class RecordData implements
             com.microfocus.cobol.lang.CustomRecord
{
    private String customerName;
    private StringBuffer customerAddress;
    private int customerRef;
    RecordData(String name, String address, int ref)
    {
      customerName = name;
      customerAddress = new StringBuffer(address);
      customerRef = ref;
    }
    public String getCustomerName()
    {
      return this.customerName;
    }
    public String getCustomerAddress()
    {
      return this.customerAddress.toString();
    }
    public int getCustomerRef()
    {
      return this.customerRef;
    }
    public Object[] getParameters()
    {
      String strCustomerRef =
                  Integer.toString(this.customerRef);
      while(strCustomerRef.length() <  6)
      {
         strCustomerRef = "0"+strCustomerRef;
      }
      customerAddress.setLength(30);
                  /* must ensure length is right! */
      customerAddress.ensureCapacity(30);
      return new ParameterList()
        .add(new Pointer(this.customerName,30))
        .add(this.customerAddress)
        .add(strCustomerRef.getBytes())
        .getArguments();
    }
    public void setParameters(Object[] parms)
    {
      Pointer ptr = (Pointer)parms[0];
      this.customerName = ptr.toString();
      this.customerAddress = (StringBuffer)parms[1];
      byte[] byteCustomerRef = (byte[])parms[2];
      this.customerRef =
              Integer.parseInt(new String(byteCustomerRef));
    }
    public String toString()
    {
      return "Customer Name : "+this.customerName+"\n"+
          "Customer Address : "+this.customerAddress+"\n"+
          "Customer Ref     : "+this.customerRef;
    }
}

The Java program could call the COBOL program as follows:

cobcall("RecordDemo",new ParameterList().add(
              new RecordData(myname, myaddress, myref)));
Parent topic: Calling Procedural COBOL from Java


Using JNI with COBOL

Restriction: This applies to native code only.

The Java Native Interface (JNI) enables non-Java programs to access Java objects and classes. One of the variants of the cobcall() method provided in the com.microfocus.cobol.RuntimeSystem class passes through a JNI pointer to the COBOL program being called. The JNI pointer is a pointer to a table of Java functions which enable non-Java code to access the Java run-time system.

For ease of use with COBOL, javatypes.cpy defines data type JNINativeInterface. JNINativeInterface is a group data item consisting of a set of procedure pointers to the JNI Java functions. One use of JNI with COBOL is to throw a Java exception from a COBOL program.

The other way to access Java from COBOL is to use the domain support.

Parent topic: Calling Procedural COBOL from Java


Example of Throwing an Exception

Restriction: This applies to native code only.

The following short COBOL program throws an exception using a JNI function.

 identification division.
 program-id.  "except".
 special-names.

**********************************************
* The call convention used for JNI calls needs
* to be defined here. For Win32 systems, it is
* 74 (which corresponds to the stdcall calling
* convention).
**********************************************
$if UNIX defined
     call-convention 0 is javaapi.
$else
     call-convention 74 is javaapi.
$end
 local-storage section.
 copy "javatypes.cpy".
 01 JavaException               pointer.
 01 ExceptionClass              pointer.
 linkage section.
 01 JEnv                        pointer.
 01 jobject                     pointer.
 01 lnk-JNINativeInterface      JNINativeInterface.
*  The first parameter (JEnv) is a pointer to the JNI
*  function table. It must be passed (by reference) as
*  the first parameter on all JNI function calls.
 procedure division
      using by reference JEnv.
* Map the pointer passed in JEnv to the
* JNINativeInterface structure so that we
* can call JNI functions.
     set address of lnk-JNINativeInterface to JEnv
* Get a reference to the exception class
      call javaapi FindClass
             using by reference JEnv
                   by reference
                   z"java/lang/IllegalArgumentException"
             returning ExceptionClass
      end-call
* Unable to find the exception class, so simply exit
     if ExceptionClass = NULL
             exit program
     end-if
* Throw the new exception
     call javaapi ThrowNew
             using by reference JEnv
                   by value ExceptionClass
                   by reference z"Thrown from COBOL code"
     end-call
     exit program
     .

This is the Java program which calls it:

import com.microfocus.cobol.*;
class testexcept
{
  public static void main(String argv[]) throws Exception
  {
    try
    {
       /* Last parameter is true for passing in JNIEnv... */
       RuntimeSystem.cobcall(null,"throwex",null,null,true);
    }
    catch(Exception e)
    {
       System.out.println(
                  "PASS - exception caught ("+ e + ")");
    }
  }
}
Parent topic: Calling Procedural COBOL from Java


Calling Java from OO COBOL

This chapter shows you how to code a COBOL program to call Java methods using the OO COBOL Java domain.
Restriction: This applies to native code only.
  • Overview of Calling Java from OO COBOL
  • Before You Start
  • Declaring Java Classes
  • Instantiating Java Objects
  • Calling Java Methods
  • Accessing Java Variables
  • Handling Java Exceptions
  • Accessing Native Java Objects
  • Finalizing Java Objects
Parent topic: Using COBOL and Java Together
Related concepts
Calling OO COBOL from Java
Calling Procedural COBOL from Java
Java and COBOL Interoperability Options
JVM COBOL Interoperating with Java
The Wrapper Class


Overview of Calling Java from OO COBOL

Restriction: This applies to native code only.

Micro Focus Java support enables you to send messages to Java objects from OO COBOL programs and classes.

Java is supported through a Java domain in OO COBOL. The Java domain enables you to declare Java classes inside a COBOL program. You can then send messages to the Java classes. The Java domain support works by creating a COBOL proxy object for each Java object, as shown in the figure below. The class itself that you declare is a proxy for the static methods of the Java class.

The Java Proxy

Your program needs to have a Repository paragraph, and needs to use the INVOKE verb each time you want to call a Java method, although it does not have to be written as an OO COBOL class.

The COBOL run-time system converts parameters sent with messages from COBOL data types to Java data types. If a method returns a parameter, it is converted from a Java data type to a COBOL data type.

Using the techniques described in this chapter, you can call any Java API, such as JDBC, Sockets and Swing.

You need to have at least a basic knowledge of the Java language to be able to use this technology effectively. The Java Web site is a good starting place.

You can also call COBOL programs from Java without using the OO COBOL Java domain.

Parent topic: Calling Java from OO COBOL
Related information
Java Web site
Calling Procedural COBOL from Java


Before You Start

Restriction: This applies to native code only.

Before you start, you need to set up your environment so that the COBOL and Java run-time systems can interact. See the section Setting Up the Environment for Java and COBOL in the chapter Using Java and COBOL Together.

Parent topic: Calling Java from OO COBOL
Parent topic: Calling OO COBOL from Java
Related information
Setting Up the Environment for Java and COBOL


Declaring Java Classes

Restriction: This applies to native code only.

Each Java class you want to use in a COBOL program must be declared in the Repository paragraph. You need to provide the full name of the package the Java class is in, prefixed by $java$. The prefix tells the COBOL run-time system to load the class from the Java domain.

Declare the Java class as follows:

repository.
     class COBOL-classname as "$java$class-name"
    .

where the names are:

COBOL-classname
The name by which the class is known to this COBOL program.
java
The name of the Java domain.
class-name
The name by which the class is known to the Java domain. This is usually determined by the name under which the class has been registered with the object model for that domain.

For example:

repository.
     class jRectangle as "$java$java.awt.Rectangle"
     .

This declares jRectangle as a COBOL proxy object for the Rectangle class in the java.awt package. The package must be available on your Java classpath or your program will fail at run time.

Parent topic: Calling Java from OO COBOL


Instantiating Java Objects

Restriction: This applies to native code only.

Each Java class has one or more constructor methods to instantiate objects. In Java, constructor methods have the same name as the class. To enable you to invoke these methods from COBOL, they are mapped to the "new" method name on the COBOL proxy object.

The different constructors on a Java class take different numbers and combinations of parameters to initialize the instance you are creating. For example, the Java Rectangle class can be instantiated in several different ways, including the two shown below in Java code:

 Rectangle r1 = new Rectangle ()
              //  rectangle (x,y) = 0,0, width=0, height=0
 Rectangle r2 = new Rectangle(4, 5, 10, 20)
             // rectangle (x,y) = (4,5), width=10, height=20

The equivalent COBOL code is shown below:

 working-storage section.
 01 r1                  object reference.
 01 r2                  object reference.
 ...

 procedure division.
 ...
     invoke jRectangle "new" returning r1
          *> rectangle (x,y) = 0,0, width=0, height=0
     invoke jRectangle "new" using 4, 5, 10, 20
                         returning r2
          *> rectangle (x,y) = (4,5), width=10, height=20

The COBOL run-time system uses the number and type of parameters to call the appropriate constructor on the Java class. You must be careful to provide parameters of the types expected by the Java class, as Java is a strongly typed language. The chapter Java Data Types explains how COBOL data types are mapped onto Java data types. The copybook javatypes.cpy also defines a set of data types for use in COBOL which correspond directly to Java data types; you are recommended to use these for transferring data between Java and COBOL.

Parent topic: Calling Java from OO COBOL


Calling Java Methods

Restriction: This applies to native code only.

You can call any of the methods on a Java object by sending it a message with the same name as the method. You can also call the static methods of a Java class - send the message to the classname declared in the Class-Control paragraph of your program. Method names in Java are case-sensitive, so the case of the message name in COBOL must match the case of the method in Java.

Java allows method overloading - where one method name has different implementations according to the number and type of parameters passed. COBOL handles this transparently for you, so that the correct Java method is always called.

For example, the Rectangle class has three different add() methods, which take different parameters. The Java code below shows three different ways you can call the add() method on a rectangle.

 Rectangle r1 = new Rectangle(0,0,0,0) ;
 Point pt = new Point(6,6) ;
 Rectangle r2 = new Rectangle(3,4,9,9) ;
 r1.add(4,5) ; // changes r1 to smallest rectangle
               //  containing r1 and point 4,5
 r1.add(pt) ;  // changes r1 to smallest rectangle
               //  containing r1 and Point pt.
 r1.add(r2) ;  // changes r1 to union of r1 & r2

The equivalent code in COBOL looks like this:

 repository.
     class jRectangle as"$java$java.awt.Rectangle"
     class jPoint as "$java$java.awt.Point"
     .
 working-storage section.
 01 r1                 object reference.
 01 r2                 object reference.
 01 pt                 object reference.

 procedure division.
     invoke jRectangle "new" returning r1
     invoke jPoint "new" using 4 5 returning pt
     invoke jRectangle "new" using 3 4 9 9 returning r2
     invoke r1 "add" using 4 5
     invoke r1 "add" using pt
     invoke r1 "add" using r2

Although r2 and pt are both data items of type object reference, the COBOL run-time system determines the type of Java object represented and calls the correct Java method.

Parent topic: Calling Java from OO COBOL


Accessing Java Variables

Restriction: This applies to native code only.

You can access the public members and static variables of a Java class by invoking "setname" and "getname" methods on the OO COBOL proxy. Variable names are case-sensitive in Java, so the case of name in your COBOL code must match the case declared in the Java code.

For example, the Java class below has public variables classVal and instVal:

public class x {
    static int classVal;
    int instVal;
};

This sample of COBOL code sets the static variable classVal, and then retrieves the member instVal.

$set ooctrl(-f+p)
repository.
     class x as "$Java$x"
     .

 working-storage section.
 copy "javatypes.cpy".
 01 anX                  object reference.
 01 anInt                jint.
 procedure division.
     invoke x "setclassVal" using by value 4
     invoke x "new" returning anX
     invoke anX "getinstVal" returning anInt
Parent topic: Calling Java from OO COBOL


Handling Java Exceptions

Restriction: This applies to native code only.

An exception thrown by Java is passed back to COBOL as an OO COBOL exception raised against the javaexpt class. The default exception behavior is for the COBOL run-time system to display a message warning of the exception, and then terminate. Alternatively, you can trap the exception by adding an exception handler to your COBOL program.

To trap Java exceptions:

  1. Declare the Exceptionmanager, JavaExceptionManager, and Callback or EntryCallback classes in the Class-Control paragraph. For example:
    repository.
    ...
    class JavaExceptionManager as "javaexpt"
    class ExceptionManager as "exptnmgr"
    class Callback as "callback"
    class EntryCallback as "entrycll"
    ...
    Tip: If you declare your own exception handling class method or entry-point, be aware that if it shares its name with one of the default Micro Focus exception handling methods shown above, you will not be able to invoke that default method.
  2. Write an exception handler (either a method in a class, or an entry-point) and create a Callback or EntryCallback to it. For example, a Callback looks like this:
    invoke Callback "new" using anObject z"methodName"
                  returning aHandler

    An EntryCallback looks like this:

    invoke EntryCallback "new" using  z"entryPointname"
                  returning aHandler
  3. Register your callback against the JavaExceptionManger class. For example:
    invoke ExceptionManager "register"
         using JavaExceptionManager aHandler

Now all Java exceptions thrown by classes you are calling through the OO COBOL Java domain get sent to your exception handler.

This is an example of a COBOL program which catches an exception thrown by a Java program:

$set ooctrl (+p-f)
 program-id. ExceptionCatcher.

 class-control.
     SimpleClass is class "$JAVA$SimpleClass"
     EntryCallback is class "entrycll"
     JavaExceptionManager is class "javaexpt"
     ExceptionManager is class "exptnmgr"
     .

 working-storage section.
 01 theInstance                  object reference.
 01 wsCallback                   object reference.
 local-storage section.
 01 filler pic x.   *> dummy storage to allow the local entry
                    *> point to be used for the callback
 linkage section.
 01 lnkException                 object reference.

 procedure division.
*>---Set up Exception handler
     invoke EntryCallback "new" using z"JException"
                            returning wsCallback
     invoke ExceptionManager "register"
                                  using javaexceptionmanager
                                        wsCallback
*>---Instantiate the class
     invoke SimpleClass "new" returning theInstance

     display "instantiated"
     invoke theInstance "TestException"
     display "excepted"
     stop run.

 entry "Jexception" using lnkException.
     invoke lnkException "display"
     .

The Local-Storage Section in the above program is simply to enable recursion - the COBOL run-time system treats the invocation of the EntryCallback as a recursive call. Without a Local-Storage Section, this will result in a run-time system error. This is the Java code for SimpleClass:

import java.lang.* ;

public class SimpleClass {

  public SimpleClass() {
  }

  public void TestException() throws Exception
  {
     Exception e = new Exception ("Test error" );
     throw e;
  }
}

See the Java Run-time Class Library Reference, which is in docs/mfcobol.docs.zip in your COBOL development system installation.

Parent topic: Calling Java from OO COBOL


Accessing Native Java Objects

Restriction: This applies to native code only.

Using the OO COBOL Java domain means that you never access Java objects directly - you are always going through a proxy. You can obtain a pointer to the actual Java object using the "getJavaObject" method of the javasup class. You can use this in conjunction with the Java Native Interface (JNI) if you want access to Java functionality not provided by the OO COBOL Java domain.

To get a JNI pointer invoke "getEnv" on the javasup class. The JNI pointer is a pointer to a table of functions; data type JNINativeInterface in copybook javatypes.cpy provides a structure that makes the JNI function table easier to use, as shown in the example below:

 working-storage section.
 01 JEnv                        pointer.
 linkage section.
 01 lnk-JNINativeInterface      JNINativeInterface.

*>
 procedure division.
     invoke javasup "getEnv" returning jEnv
*>   Map the pointer passed in JEnv to the
*>   JNINativeInterface structure so that we
*>   can call JNI functions.
     set address of lnk-JNINativeInterface to JEnv
*>

You can now call JNI functions using the names provided by the JNINativeInterface type definition.

See the Java Run-time Class Library Reference, which is in docs/java/mfcobol.docs.zip in your COBOL development system installation.

Parent topic: Calling Java from OO COBOL
Related information
Java Web Site


Finalizing Java Objects

Restriction: This applies to native code only.

The Java run-time system includes a garbage collector which automatically destroys unwanted objects. The garbage collector deletes any object which is not referenced by any other object. Once you have a proxy to a Java object in a COBOL program, the COBOL run-time system has a reference to the Java object which prevents the Java garbage collector from removing it.

When you have finished with a Java object, you must release the reference to it so that the garbage collector can delete the object - otherwise your application has a memory leak. To finalize the object:

invoke javaobject "finalize" returning javaobject

The returning parameter is important, as otherwise the COBOL run-time system passes the message on to the actual Java object instead of destroying the COBOL proxy. If the message is passed to the Java object, it invokes this function:

public void finalize()

This function is either inherited or implemented by all Java classes, and is called by the Java garbage collector before it destroys an object.

In the unlikely event that your Java class implements a finalize() method which returns a value, use the "delete" method to destroy the OO COBOL proxy instead:

invoke javaobject "delete" returning javaobject
Parent topic: Calling Java from OO COBOL


Calling OO COBOL from Java

This chapter describes how you can access COBOL objects from Java programs. This is slightly different from the method for accessing procedural COBOL from Java programs.
Restriction: This applies to native code only.
  • Overview - Calling OO COBOL from Java
  • Before You Start
  • Writing a Java Class in OO COBOL
  • Importing the COBOL Support
  • The Wrapper Class
  • Adding and Removing Methods
  • Throwing Exceptions from COBOL
  • Using BY REFERENCE Parameters
  • Working with Java Programs
Parent topic: Using COBOL and Java Together
Related concepts
Calling Java from OO COBOL
Calling Procedural COBOL from Java
Java and COBOL Interoperability Options
JVM COBOL Interoperating with Java
The Wrapper Class


Overview - Calling OO COBOL from Java

Restriction: This applies to native code only.

You can write classes in OO COBOL which can be called from Java programs as though they were Java classes. You do this by providing a Java wrapper class, which provides a function for each method in the OO COBOL class.You can then publish the resulting Java classes to your UNIX system.

The functions in the Java wrapper class put all the parameters for the method into a Java array, and then call one of the member functions of Java class com.microfocus.cobol.RuntimeSystem to invoke the method in the OO COBOL class and return the result. This is shown in the figure below:

Calling OO COBOL from Java

Parent topic: Calling OO COBOL from Java
Related information
Java Web Site


Writing a Java Class in OO COBOL

Restriction: This applies to native code only.

To write a class in OO COBOL which can be called from Java, you need to do the following:

  1. Set the following directive in your program:
    $set ooctrl"+p-f"
  2. Ensure that the OO COBOL class inherits from javabase.
  3. Create a Java wrapper class for the OO COBOL class. The wrapper class must have the same class name as the filename of the OO COBOL class.
  4. For each method that you create in your OO COBOL class, create a corresponding method in the Java wrapper class.
  5. Package the class inside a .dll file when deploying it on Windows platforms.

    You can also use classes compiled to .int or .gnt, but this does not allow you to package several classes inside one file.

Parent topic: Calling OO COBOL from Java


Importing the COBOL Support

Restriction: This applies to native code only.

The support needed for the Java wrapper class to communicate with the OO COBOL class is in the com.microfocus.cobol package. The wrapper must include the following statement:

import com.microfocus.cobol.* ;

You must also ensure mfcobol.jar is on the Java classpath, or your Java programs will not compile or run.

Parent topic: Calling OO COBOL from Java


The Wrapper Class

Restriction: This applies to native code only.

The Java wrapper class must extend either microfocus.cobol.RuntimeObject or microfocus.cobol.RuntimeSystem. This affects the lifetime of the OO COBOL instances represented by instances of the Java wrapper class:

  • When the wrapper inherits from microfocus.cobol.RuntimeObject, if a wrapper object is destroyed by the Java garbage collector, the corresponding OO COBOL instance is finalized.

  • When the wrapper inherits from microfocus.cobol.RuntimeSystem, the OO COBOL instance is finalized whenever execution exits from a method, losing any instance data.

The wrapper class needs to be initialized with the library and filename of the COBOL class it is wrapping. You do this by including the following code inside the Java wrapper class:

static
{
  cobloadclass("libname","filename","fullJavaClassName");
}

where:

libname
s the name of the .dll file which contains the OO COBOL class. You can leave this parameter as null if the class is not packaged inside a .dll file - for example, if it is running as .int or .gnt code.
filename
is the filename of the OO COBOL class.
FullJavaClassName
is the Java classname corresponding to the OO COBOL class.

There are three cobloadclass() methods, which provide slightly different ways of identifying the library, COBOL file and the Java wrapper class.

Parent topic: Calling OO COBOL from Java
Related concepts
Calling Java from OO COBOL
Calling OO COBOL from Java
Calling Procedural COBOL from Java
Java and COBOL Interoperability Options
JVM COBOL Interoperating with Java


Adding and Removing Methods

Restriction: This applies to native code only.

Every method you add to the COBOL class must have a corresponding function in the Java wrapper class.

The Java function must do the following:

  1. Declare the exceptions which can be thrown from an invoke of a COBOL method.

    By default, these are Exception (thrown if you raise an exception in COBOL) and CobolException (thrown by the COBOL run-time system). If your class is to be deployed either as an Enterprise JavaBean, or using Java Remote Method Invocation (RMI), you should also add RemoteException.

  2. Construct a Java array containing the parameters to be passed from Java to the COBOL method.

    Parameters are passed from Java to the COBOL run-time system in a Java array.

  3. Invoke one of the cobinvoke_ or cobinvokestatic_ methods provided by the class RuntimeSystem.java.

    There is a cobinvoke_ and cobinvokestatic_ method corresponding to each possible return type from a Java function (for example, cobinvoke_int returns an int). Use the cobinvoke_ methods for invoking OO COBOL instances. Use the cobinvokestatic_ methods for invoking OO COBOL classes.

    For the full list of cobinvoke_ functions, see the Java Run-time Class Library Reference, which is in docs/mfcobol.docs.zip in your COBOL development system installation.

    You need to determine which Java data type maps to the return type from the COBOL method, and then choose the appropriate cobinvoke_ function. See the chapter Java Data Types for more information.

OO COBOL factory methods are mapped onto static functions in the Java wrapper.

The two code samples below show a COBOL instance method, and the corresponding function in the Java wrapper. This is the COBOL method.

 method-id. "myMethod".
 local-storage section.
*>---USER-CODE. Add any local storage items needed below.
 linkage Section.
 01 myParameter            pic x(4) comp-5.
 01 myReturnValue          pic x(4) comp-5.
 procedure division using by reference myParameter
                    returning myReturnValue.
*>---USER-CODE. Add method implementation below.
     exit method.
end method "myMethod".

This is the Java wrapper method.

public int myMethod (Integer myParameter) throws Exception,
                          CobolException, RemoteException
{
    // Parameters are passed to COBOL in an array
    Object[] params = {myParameter};
    return ((int) cobinvoke_int ("myMethod", params)); }

Although the name of a method is usually the same for the Java wrapper class and the COBOL class, it does not have to be. This enables you to implement method overloading in the Java wrapper.

Method overloading enables you to have several methods with the same name, but which take different types or numbers of parameters. Java supports method overloading, but COBOL does not. But you can add overloaded functions to the Java wrapper, and have them call differently named methods in the COBOL class.

For example, you could have these overloaded functions in your Java wrapper class:

public int add (int a, int b)
{...}
public int add (int a, int b, int c)
{...}

And map them to methods "add2" and "add3" in your COBOL class.

Parent topic: Calling OO COBOL from Java


Throwing Exceptions from COBOL

Restriction: This applies to native code only.

You can throw a Java exception from your COBOL code. The exception object can be any Java class.

The javasup class provides two methods for throwing exceptions, namely: throwException and throwNewException. You use these methods as follows:

invoke javasup "throwException" using aCOBOLProxy

invoke javasup "throwNewException" using javaclassdescription

where:

aCOBOLProxy
is a COBOL proxy to any Java object of type Throwable.
javaclass
is the name of the class of Java exception to throw.
description
is a text description of the exception.

For details of the javasup class and its methods, see the Java Run-time Class Library Reference, which is in docs/mfcobol.docs.zip in your COBOL development system installation.

Parent topic: Calling OO COBOL from Java


Using BY REFERENCE Parameters

Restriction: This applies to native code only.

When parameters to a method are declared as BY REFERENCE, the default behavior is for any updates to those parameters to be reflected in the corresponding Java objects in the calling Java class on return from the OO COBOL method.

If you do not want the Java objects to be updated, you can set the following static variable:

static boolean mfcobol.runtimeProperties.updateByRefParams;

The default value for this variable is true. Set it to false if you do not want the Java objects to be updated.

Note: In an earlier version of this COBOL development system, the default behavior was for updates to BY REFERENCE parameters not to be reflected in the calling Java. If you have existing Java code that makes use of that behavior, you need to modify it to set mfcobol.runtimeProperties.updateByRefParams to false.

Your COBOL development system includes a demonstration program that illustrates the different ways of handling BY REFERENCE parameters.

Parent topic: Calling OO COBOL from Java


Working with Java Programs

Restriction: This applies to native code only.

When you develop mixed COBOL and Java programs, you need to be aware of the following:

  • The default Java build directives that your COBOL development system uses are -d $TARGETDIR -classpath "$CLASSPATH":$TARGETDIR $FILENAME. The "$CLASSPATH":$TARGETDIR section of the command appends the currently-specified target directory to the end of the current setting for the CLASSPATH environment variable, retaining any spaces specified in the current setting of CLASSPATH.
  • If you specify multiple classes in a .java program, only the resultant .class file with the same basename as the .java program is added to the project automatically. You must add any other .class files manually.
Parent topic: Calling OO COBOL from Java


Java Data Types

This chapter describes how COBOL and Java data types are mapped on to each other.
Restriction: This applies to native code only.
  • Overview
  • Java Data Type Conversion Rules
  • Java Typedefs
  • Using the Jarray Class
  • Adding Parameters Using ParameterList()
  • Using Structures
  • Creating Custom Records using com.microfocus.cobol.lang.CustomRecord Interface
Parent topic: Using COBOL and Java Together


Overview

Restriction: This applies to native code only.

The Java language defines its own data types, which are different to the ones used in COBOL. The COBOL run-time system automatically converts between COBOL and Java types whenever you call Java from COBOL or COBOL from Java, as shown below.

Mapping data between COBOL and Java

Numeric data types are converted in the same way whether the COBOL program is a procedural program, or OO COBOL. Objects and strings are converted differently, depending on whether you are using procedural COBOL or OO COBOL.

OO COBOL handles Java objects as COBOL object references, but procedural COBOL handles them as pointers.

Parent topic: Java Data Types


Java Data Type Conversion Rules

Restriction: This applies to native code only.

When you send COBOL data to Java, it is converted to an appropriate Java data type. Similarly, when a Java program sends Java data back to COBOL, it is converted to a COBOL data type. The table below defines the conversions which happen when data is passed between Java and COBOL. Some data types are handled differently depending on whether you are using procedural COBOL or the OO COBOL Java domain. The COBOL column in the table shows you the conversion rules for procedural COBOL, and the OO COBOL column shows you the rules for the OO COBOL Java domain.

Java Data Type | COBOL Data Type Used with .cobcall(...) | OO COBOL Data Type Used with .cobinvoke() | Description
byte pic s99 comp-5 pic s99 comp-5

pic s99 comp

Signed 1-byte integer
short pic s9(4) comp-5 pic s9(4) comp-5

pic s9(4) comp

Signed 2-byte integer
int pic s9(9) comp-5 pic s9(9) comp-5

pic s9(9) comp

Signed 4-byte integer
long pic s9(18) comp-5 pic s9(18) comp-5

pic s9(18) comp1

Signed 8-byte integer
boolean | pic 99 comp-5 | pic 99 comp-5 | Zero value is false, non-zero is true
char (Unicode) | pic 9(4) comp-5 | pic s9(4) comp | All characters in Java are represented by 2-byte Unicode characters
float | comp-11 | comp-1 1 | Floating-point number
double | comp-2 1 | comp-2 1 | Double-precision floating-point number
String mf-jstring2

pointer3

pic x(n) The capacity is always zero. You should consider a string passed into a COBOL program as read-only, and not to be amended.
StringBuffer4 mf-jstring 2

pointer 3

pic x(n) The capacity is the total size of the buffer, and the size the length of the string currently held in the buffer.
objects | pointer | object reference | Any Java object. The pointer returned to procedural COBOL can be used with JNI calls (see the section Using JNI with COBOL in the chapter Calling Procedural COBOL from Java).
object[] | pointer | object reference to instance of class jarray | An array of Java objects. The pointer returned to procedural COBOL can be used with JNI calls (see the section Using JNI with COBOL in the chapter Calling Procedural COBOL from Java). jarray is an OO COBOL class for accessing the contents of Java arrays, and is described in the section Using the Jarray Class.
DataType | structure | structure | Complex data structure
Comp3 | comp-3 | comp-3 | COMP(UTATIONAL)-3 or Packed-Decimal
Pointer(StringBuffer)

Pointer(String, int capacity)

pic x(99) pic x(99) Wraps a String, StringBuffer so it can safely be passed to COBOL with the right size allocated for the receiving COBOL to modify the Java object.

StringBuffer capacity is used as the largest possible length that COBOL can edit.

java.sql.Date(long)

CobolDate(date)

0x jyear pic 9(4).

0x filler pic x.

0x jmonth pic 99.

0x filler pic x.

0x jday pic 99.

same as for cobcall Standard SQL Date type as used by JDBC
java.sql.time(long)

CobolTime(time)

0x jhour pic 99.

0x filler pic x.

0x jminute pic 99.

0x filler pic x.

0x jseconds pic 99.

same as for cobcall Standard SQL Time type as used by JDBC

CobolBigDecimal(java.math.BigDecimal)

pic s9(19)v9(19) comp-3 same as for cobcall The CobolBigDecimal wrapper class enables COBOL to update the value of a BigDecimal. The constructor for CobolBigDecimal() takes an initial value and the updated value can be obtained by using the .getValue() method.

CobolBigInteger(java.math.BigInteger)

pic S9(38) comp-3 same as for cobcall The CobolBigInteger wrapper class enables COBOL to update the value of a BigInteger. The constructor for CobolBigInteger() takes an initial value and the updated value can be obtained by using the .getValue() method.
CustomRecord | Structure | Structure | Complex data structure represented in Java as an array of objects.
CobolN ational | pic x(n) usage is national. | same as for cobcall | This java class enables you to create UTF-16 strings that you can pass to COBOL.

1 The parameter can be passed only by reference. For floating point data types this restriction applies to UNIX platforms only. For long data types on 32-bit platforms the parameter can be passed by reference only, and on 64-bit platforms by reference or by value only.

2 Use mf-jstring for .cobcall(...). mf-jstring requires the receiving COBOL program to use ptr2string pointer to access the Java String or StringBuffer. Using mf-jstring gives you access to the size and capacity of the Java object.

3 Use pointer for .cobcall(...).

4 StringBuffer objects can be received by OO COBOL methods as pic x(n) data items but pic x(n) cannot be used to pass data to a Java method with a StringBuffer parameter.

The conversion of COBOL data types that are not listed in the COBOL or OO COBOL columns of the above table is not supported. If you need to use a COBOL data item of a type not listed above, use an intermediate data item of a supported type and move your data to and from the intermediate data item as necessary.

Parent topic: Java Data Types
Related information
Using the Jarray Class
Calling Procedural COBOL from Java
Calling OO COBOL from Java
Calling Java from OO COBOL


Java Typedefs

Restriction: This applies to native code only.

For convenience, copybook javatypes.cpy defines a set of COBOL data types corresponding to Java data types - you can use these as a shorthand way of declaring data items for use with Java in your COBOL programs. You can find the copybook in your $COBDIR/cpylib directory.

These typedefs all start with the prefix "j" and are shown in the following table:

Typedef | COBOL Type
jbyte | pic s99 comp-5
jshort | pic s9(4) comp-5
jint | pic s9(9) comp-5
jlong | pic s9(18) comp-5
jboolean JNI-TRUE is true JNI-FALSE is false | pic 99 comp-5
jchar | pic 9(4) comp-5
jfloat | comp-1
jdouble | comp-2
jobject | pointer
jbigdecimal | pic s9(19)v9(19) comp-3
jbiginteger | pic s9(38) comp-3
mf-sql-date (in javatypes.cpy) | 0x jyear pic 9(4). 0x filler pic x. 0x jmonth pic 99. 0x filler pic x. 0x jday pic 99.
mf-sql-time (in javatypes.cpy) | 0x jhour pic 99. 0x filler pic x. 0x jminute pic 99. 0x filler pic x. 0x jseconds pic 99.
Parent topic: Java Data Types


Using the Jarray Class

Restriction: This applies to native code only.

The jarray class provides an OO COBOL wrapper for manipulating Java arrays. It is fully documented in the Java Run-time Class Library Reference, which is in docs/mfcobol.docs.zip in your COBOL development system installation.

The following COBOL program gets an array from a Java object, finds its dimensions, and displays the contents of the array.

$set ooctrl(+p-f)
 Program-id. ReadArray.
 class-control.
     arraydemo is class "$Java$arraydemo"
     .

 thread-local-storage section.
 01 aJavaObj             object reference.

 01 theTotal        pic 9(9).
 01 CDims           pic x(4) comp-5.
 01 Dims.
   03 Dims-entry    pic x(4) comp-5 occurs 256.
 01 Bounds.
   03 Bounds-entry  pic x(4) comp-5 occurs 256.
 01 ind0            pic x(4) comp-5.
 01 ind1            pic x(4) comp-5.
 01 arrayElement    pic x(4) comp-5.
 01 wsTable         object reference.
 01 wsResult        pic x(4) comp-5.

 procedure division.
   invoke arraydemo "new" returning aJavaObj
   invoke aJavaObj "getArray" returning wsTable

*> find out the number of elements in the array
     invoke wsTable "getDimensions" returning CDims
     display "The array has " CDims " dimension(s)"

*> get the number of elements in each dimension
     display "dimensions are " with no advancing
     invoke wsTable "getBounds" using Bounds
     perform varying ind0 from 1 by 1 until ind0 > CDims
          display Bounds-entry(ind0) with no advancing
          if ind0 < CDims
             display " by " with no advancing
          end-if
     end-perform
     display " "

*> display each element in the array
     perform varying ind0 from 0 by 1
             until ind0 = Bounds-entry(1)
         move ind0 to Dims-entry(1)
         perform varying ind1 from 0 by 1
                   until ind1 = Bounds-entry(2)
             move ind1 to Dims-entry(2)
             invoke wsTable "getElement" using
                             by value CDims
                             by reference Dims
                             by reference arrayElement
             display "Element " ind0 ","
                   ind1 " is " arrayElement
*> modify the contents of the array
             add 50 to arrayElement
             invoke wsTable "putElement" using
                             by value CDims
                             by reference Dims
                             by reference arrayElement
         end-perform
     end-perform

This is an implementation of the Java arraydemo class used by ReadArray. This program creates a two-dimensional array.

import com.microfocus.cobol.*;
import java.io.*;

public class arraydemo extends RuntimeSystem
{
    int myArray[][];
    public arraydemo()
    {
        myArray = new int[5][2];
        int i,j;
        for (i = 0; i < 5; i++)
        {
            for (j = 0; j < 2; j++)
                myArray[i][j] = i * 100 + j;
        }
    }
    public int[][] getArray()
    {
        return myArray;
    }
}
Parent topic: Java Data Types


Adding Parameters Using ParameterList()

Restriction: This applies to native code only.

The ParameterList() class in com.microfocus.cobol.lang helps with coding parameters being passed between Java and COBOL.

The general mechanism for using ParameterList() is:

   RuntimeSystem.cobcall("myProgram",
    new ParameterList()
        .add(myOneInt,RuntimeSystem.BY_VALUE)
        .add(mySecondParameter,RuntimeSystem.BY_REFERENCE)
           .add(99)		// 99 by reference
           );

Where the parameters are:

myProgram
The program being called.
myOneInt
An integer parameter being passed by value.
mySecondParameter
A parameter being passed by reference.
99
A numeric value being passed by reference.
Parent topic: Java Data Types


Using Structures

Restriction: This applies to native code only.

COBOL programs and OO COBOL methods can use structures in their Linkage Sections and be passed data from a Java class, providing that the corresponding Java parameter is an object which implements the com.microfocus.cobol.lang.Datatype interface or com.microfocus.cobol.lang.CustomRecord, as described below:

package com.microfocus.cobol.lang;
public interface DataType
{
   void synchronizeData();
   byte[] getBytes();
}

and

package com.microfocus.cobol.lang;
public interface CustomRecord
{
   public Object[] getParameters();
   public void setParameters(Object[] parms);
}

Using com.microfocus.cobol.lang.Datatype/com.microfocus.cobol.lang.CustomRecord enables you to pass non-simple data into a COBOL program or method without needing to rearchitect the interface with numerous elementary data types.

An example of a class that implements the com.microfocus.cobol.lang.Datatype interface is com.microfocus.cobol.lang.Pointer, which is defined in mfcobol.jar. It has the following constructors:

/* Create a Pointer object from String initString*/
public Pointer(String initString);

/* Create a Pointer object from StringBuffer initString */
public Pointer(StringBuffer initString);

/* Create a pointer object containing 'capacity' bytes, */
/* space filling if initString has fewer characters     */
/* than 'capacity'                                      */
public Pointer(String initString, int capacity);
Parent topic: Java Data Types


Creating Custom Records using com.microfocus.cobol.lang.CustomRecord Interface

Restriction: This applies to native code only.

Custom records are useful for passing group items to existing COBOL programs. You use then in conjunction with the .cobcall mechanism.

The CustomRecord interface is:

package com.microfocus.cobol.lang;
public interface CustomRecord
{
        public Object[] getParameters();
        public void setParameters(Object[] parms);
}

The data item customerDetails can be defined as follows:

01 customerDetails.
                    03 customerName 				pic x(30).
                    03 customerAddress		pic x(30).
                    03 customerRef 					pic 9(6).

A Java implementation could be:

import com.microfocus.cobol.lang.*;
import java.text.*;
public class RecordData implements
       com.microfocus.cobol.lang.CustomRecord
{
    private String customerName;
    private StringBuffer customerAddress;
    private int customerRef;
    RecordData(String name, String address, int ref)
    {
        customerName = name;
        customerAddress = new StringBuffer(address);
        customerRef = ref;
    }
    public String getCustomerName()
    {
        return this.customerName;
    }
    public String getCustomerAddress()
    {
        return this.customerAddress.toString();
    }
    public int getCustomerRef()
    {
        return this.customerRef;
    }
    public Object[] getParameters()
    {
        String strCustomerRef =
                Integer.toString(this.customerRef);
        while(strCustomerRef.length() < 6)
        {
            strCustomerRef = "0"+strCustomerRef;
        }
        customerAddress.setLength(30);
            /* must ensure length is right! */
        customerAddress.ensureCapacity(30);
        return new ParameterList()
            .add(new Pointer(this.customerName,30))
            .add(this.customerAddress)
            .add(strCustomerRef.getBytes())
            .getArguments();
    }
    public void setParameters(Object[] parms)
    {
        Pointer ptr = (Pointer)parms[0];
        this.customerName = ptr.toString();
        this.customerAddress = (StringBuffer)parms[1];
        byte[] byteCustomerRef = (byte[])parms[2];
        this.customerRef =
            Integer.parseInt(new String(byteCustomerRef));
    }
    public String toString()
    {
        return "Customer Name :
        "+this.customerName+"\n"+ "Customer Address :
        "+this.customerAddress+"\n"+
        "Customer Ref : "+this.customerRef;
    }
}

and

package com.microfocus.cobol.lang;
public interface CustomRecord
{
   public Object[] getParameters();
   public void setParameters(Object[] parms);
}
Parent topic: Java Data Types


JVM COBOL Interoperating with Java

JVM COBOL compiles to JVM byte code. This allows for easy mixed-language programming with any other JVM language that compiles to JVM byte code such as Java or JRuby.

  • Java Calling JVM COBOL
  • JVM COBOL Calling Java
  • JVM COBOL Passing Java Instances to Native Procedural COBOL
  • JVM COBOL Passing Java Instances to Native Object COBOL
Parent topic: Using COBOL and Java Together
Parent topic: Interoperability
Related concepts
Calling Java from OO COBOL
Calling OO COBOL from Java
Calling Procedural COBOL from Java
Java and COBOL Interoperability Options
The Wrapper Class


Java Calling JVM COBOL

At the command line

To call from JVM COBOL from Java, add any locations that include the JVM COBOL classes or packages being called to the CLASSPATH environment variable.

Also, in the Java source code, add an import statement to import the COBOL class you want to use or the entire package into your Java source file as follows:

import com.microfocus.cobol.MyClass

or

import com.microfocus.cobol.*
Parent topic: JVM COBOL Interoperating with Java
Related reference
com.microfocus.cobol.runtimeservices


JVM COBOL Calling Java

At the command line

To call Java from JVM COBOL, add any locations that include the Java classes or packages being called to the CLASSPATH environment variable.

Parent topic: JVM COBOL Interoperating with Java


JVM COBOL Passing Java Instances to Native Procedural COBOL

You can pass Java instances to native procedural COBOL application using the com.microfocus.cobol.lang.JObject interface. The interface retrieves the object as a pointer, which requires that you use a Java JNI method.

In the following example, the myclass instance is passed to native COBOL:

 class-id. myclass implements type com.microfocus.cobol.lang.JObject.
 method-id. invokeMe.
   display "Hello from invokeMe method".
   goback.
 end method.

 method-id. main static public.
 local-storage section.
 01 myclass-instance type myclass.
 procedure division.
   set myclass-instance to type myclass::new()
   call "natsub" using by value myclass-instance
   stop run
 end method.

Then, native COBOL invokes the invokeMe method.

$set ooctrl(+p) ooctrl(-f) dialect(iso2002) mf warning(1)
 identification division.
 program-id. natsub as "natsub".
 repository.
            class javasup as "javasup"
            class cls-myclass as "$java$myclass".

 working-storage section.
 01 myclass                   object reference cls-myclass.
 linkage section.
 01 myclass-jptr               pointer.
 procedure division using by value myclass-jptr.
    invoke javasup "getCOBOLObject" using myclass-jptr
                      returning myclass

    invoke myclass "invokeMe"

    invoke myclass "finalize" returning myclass
    goback.
Parent topic: JVM COBOL Interoperating with Java


JVM COBOL Passing Java Instances to Native Object COBOL

In earlier Micro Focus products, COBOL and Java interoperability was achieved using a class and method Wizard to create Java classes that extend the class com.microfocus.cobol.RuntimeObject and its companion COBOL class.

You can now use these generated classes with JVM COBOL applications, enabling you to pass a Java instance to native object COBOL by creating an instance of the com.microfocus.cobol.RuntimeObject. The native COBOL receives these instances as native object references.

In the following example, the Java class addressbook extends com.microfocus.cobol.RuntimeObject and is used to create an instance:

 working-storage section.
 01 ab    type addressbook.
 procedure division.
     set ab to type addressbook::new()
     call "useab_oon" using by value ab

The receiving native COBOL program:

$set ooctrl(+p) ooctrl(-f) dialect(iso2002) mf warning(1)
 identification division.
 program-id. useab_con as "useab_oon".
 repository.
    class cls-sb as "$java$java.lang.StringBuffer".
 working-storage section.
 01 nameBuffer       object reference.
 01 nameBufferLength binary-long.
 01 nameBufferX       pic x(80).
 linkage section.
 01 ab                   object reference.
 procedure division using by value ab.
     invoke cls-sb "new" using
         by value 80 size 4
         returning nameBuffer
     invoke ab "getName" using nameBuffer
     invoke nameBuffer "length" returning nameBufferLength
     invoke nameBuffer "toString" returning nameBufferX
     display "Customer name : " nameBufferX(1:nameBufferLength)
     invoke nameBuffer "finalize" returning nameBuffer
     goback.

The native COBOL class:

$set ooctrl(+p) ooctrl(-f) dialect(iso2002) mf warning(1)
 identification division.
 class-id. addressBook as "addressbook"
           inherits from javabase.

 repository.
     class javabase as "javabase"
 factory.
 working-storage section.
 end factory.
 object.
 working-storage section.

 method-id.  getName .
 linkage Section.
 01 customerName           pic x(80).
 procedure division using by reference customerName.
     move "Mr Smith" to customerName
 exit method.
 end method getName.
 end object.

 end class addressBook.

And finally, addressbook.java, which is automatically generated:

import com.microfocus.cobol.*;
// OCWIZARD start imports
// OCWIZARD end imports

public class addressbook extends com.microfocus.cobol.RuntimeObject
{
 /* static methods - the COBOL runtime will register these */
 public native static boolean cobinvokestatic_boolean (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static byte cobinvokestatic_byte (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static char cobinvokestatic_char (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static short cobinvokestatic_short (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static int cobinvokestatic_int (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static long cobinvokestatic_long (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static float cobinvokestatic_float (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static double cobinvokestatic_double (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static void cobinvokestatic_void (String methodName, Object[] params)
  throws CobolException, Exception;
 public native static Object cobinvokestatic_Object (String methodName, Object[] params)
  throws CobolException, Exception;

 static private String javaClassName = "addressbook";
 static
 {
  /* Load the class */
  /* cobloadclass (libraryname, cobolname, fulljavaname); */
  cobloadclass ("addressbook", "addressbook", javaClassName);
 }

 // OCWIZARD - start java methods

 public  void getName (StringBuffer customerName) throws Exception, CobolException
 {
  // Parameters are passed to COBOL in an array
  Object[] params = {customerName};
  cobinvoke_void ("getName", params);
 }
 // OCWIZARD - end java methods
}
Parent topic: JVM COBOL Interoperating with Java


Managed COBOL Programming

Note: Visual COBOL for Eclipse supports managed COBOL. To develop applications for managed COBOL, install one of our Visual COBOL for Visual Studio products.
  • Moving Native COBOL Applications to Managed COBOL
    Managed code provides features that enable you to extend and modernize your existing procedural COBOL applications without having to rewrite them.
  • Native COBOL compared with managed COBOL
    Native COBOL and managed COBOL differ in how they compile and how the run-time management services, such as security, threading and memory management are provided.
  • Compiling and Calling JVM COBOL Applications as Part of a Package
    The mfjarprogmap utility enables you to create a Java property file that is required for the JVM COBOL run-time system to locate called programs that have been compiled as part of a package.
  • 64-bit applications in the Java environment
    Java COBOL applications running on a 64-bit platform can use either the 32-bit or the 64-bit JVM.
  • Using a File Handler in JVM COBOL
    File handling operations within JVM COBOL applications can be performed using the native Micro Focus File Handler or using the Managed File Handler.
  • Multiple user COBOL applications in Java
    In a multiple user environment, COBOL applications must use multiple run units, with each instance of the application running in its own run unit.
  • Introduction to Object-Oriented Programming for COBOL Developers
  • Interoperability
    Managed COBOL can invoke and be invoked by code in any other managed language. Managed COBOL can also invoke native COBOL. In addition, managed code in languages other than COBOL and native COBOL can interoperate by going through managed COBOL code.
Parent topic: Programming


Moving Native COBOL Applications to Managed COBOL

Modern deployment architectures such as are now industry standards for application development and provide a variety of features that facilitate the application development – vast libraries of reusable code snippets, run-time and memory management services, support through large developers’ communities of developers. Since a lot of the contemporary applications use managed technology it is imperative that COBOL is also portable to the managed environments to ensure you can modernize and extend your applications using the latest technologies.

Visual COBOL is the next generation of COBOL development and deployment environments. It includes a powerful modern Integrated Development Environment in that enables you to deploy key business-critical COBOL applications to and the cloud.

Moving to managed code is easy because COBOL has been extended over the years and offers syntax extensions for managed code that enable you to access all of the capabilities of the managed platforms and enhance your applications in various ways such as modernizing the User Interface, deploying as Web services or Web applications, and preparing for multi-user environments.

  • Why Move to Managed Code?
  • Considerations When Moving to Managed Code
  • Writing Multi-User Applications
  • Using Java Managed Beans to Manage and Monitor COBOL Applications
  • Accessing Procedural COBOL From Managed Code
  • Example of Using a Managed COBOL Wrapper Class
  • Example of Using the ILSMARTLINKAGE Compiler Directive
Parent topic: Managed COBOL Programming


Why Move to Managed Code?

Using managed code has many advantages such as:

Micro Focus COBOL already is a managed language:
The COBOL language has been extended over the years and supports a lot of the features in the .

In most cases, the process of moving to managed code entails recompiling the existing COBOL code to managed code in Visual COBOL. Also, you can use the ILSMARTLINKAGE COBOL compiler directive to recompile to managed code (see the Examples section in this topic). ILSMARTLINKAGE enables COBOL to interoperate with other managed languages.

Take full advantage of the capabilities of the :
  • Use the runtime services provided by the - these provide for integrity and the security of your COBOL applications, and provide exception handling and garbage collection. As the runtime services optimize how your code executes, this results in improved application performance over time.
  • Improve your application performance - the applies many optimizations including those based on how the code is actually executed at runtime; therefore, it can make optimizations that a static analysis cannot.
  • Create your own managed COBOL objects - with managed COBOL you can do a lot of what you can do with any other managed languages, such as creating your own methods, classes, delegates, and interfaces. See An Introduction to Object-Oriented Programming for COBOL Developers, available on the Micro Focus SupportLine Web site - click here to download it.
  • Easy to learn if you have experience with other managed languages - learning managed COBOL doesn't differ from learning any other managed language. If you already program in other managed languages, you only need to learn the syntax rules.
  • Access a variety of reusable libraries of code - the includes large libraries of reusable code snippets and constructs which you can reuse directly in managed COBOL code. This means you can easily solve just about any programming task, be more productive in your work, and get more done.
COBOL can interoperate with other languages:
  • Since all managed languages compile to the same , COBOL compiled to managed code can talk to other managed applications written in any other managed language, or be deployed on other managed platforms.
  • COBOL can interoperate with other languages - other languages can call COBOL and vice versa.
  • Debug COBOL and parts of your application in other managed languages together. You can step between the COBOL part and the part in the other managed language.
Create new, modern user interfaces:
Using managed code is a great way to modernize the look and feel of your applications. .
Deploy to Java application servers:
Java application servers are required when you provide "thin" client architecture for your applications. End users use a thin client installed on their machines to communicate with the main program which is deployed on the application server and processes all requests.

Visual COBOL supports all major Java application servers and enables you to create and deploy COBOL applications on Java application servers as Web services or Java interfaces.

Create applications for deployment on the Web and mobile:
Modern application servers are designed to be used by applications written in a managed language such as C#, Java, and managed COBOL. Using native COBOL for applications you upload to the server might not be possible or could lead to instabilities if the native program terminates due to an error condition.
Parent topic: Moving Native COBOL Applications to Managed COBOL


Considerations When Moving to Managed Code

Certain technologies have restrictions or may not be supported in managed code. Before you make the move to managed code, you need to consider the following:

Database Support

You can use OpenESQL with the SQL(DBMAN=JDBC) directive to compile your managed applications. Micro Focus tries to maintain as much source code compatibility as possible between the OpenESQL native and managed code run-time systems. Although each run-time system has extensions, limitations, and differences that are imposed by the underlying database APIs and execution environments, the majority of embedded SQL statements such as DECLARE CURSOR, OPEN, FETCH, CLOSE, SELECT, INSERT, UPDATE, DELETE, CONNECT, DISCONNECT, COMMIT and ROLLBACK, are completely compatible and require no change.

The JDBC run-time system supports object host variables as well as traditional COBOL host variables.

The following restrictions apply to database support in managed code:

  • Applications that use output parameters from stored procedure calls must use the COBOL directive NOILNATIVE, and object host variables cannot be used for output parameters on stored procedure calls.

Library Routines

Certain library routines are only supported in native code. See the Library Routines section of this documentation for details on the routines you can used in managed code.

Managed and Native Code

You can call native code from managed code although there are some environments that could prohibit this. .

Modernization of the User Interface

Visual COBOL offers great options for modernizing your application's user interface. You can use Java Swing in the JVM. Be aware that there might be potential issues depending on the application architecture and how tightly the original user interface is tied to the back-end module.

Object-Oriented Programming

You can still write and use procedural COBOL that compiles and runs in managed environments such as the JVM. However, to take full advantage of all features available in a managed environment, and to be able to expose your code to other managed languages, you might need to start using managed COBOL syntax. For information about writing managed COBOL code, explore the following resources:

  • An Introduction to Object-Oriented Programming for COBOL Developers, available on the Micro Focus SupportLine Web site - click here to download it.
  • Study the samples contained in the Moving to JVM section of the Visual COBOL Samples samples browser installed with Visual COBOL.

Third-party Software

Examine your existing procedural code for any third-party APIs that make calls to the operating system. Technology provided by other software vendors might need to be rewritten for use with managed code.

Parent topic: Moving Native COBOL Applications to Managed COBOL


Writing Multi-User Applications

Modern applications, both on the PC or those running on servers, have requirements to cater for multiple instances of the application running at the same time - for example, in a multi-user environment, each user running a session simultaneously with other users.

Many COBOL applications are traditionally single user programs that run in single sessions, each independent of each other. These applications are not coded to run in a multi-user environment. If you try to run several instances of the same application simultaneously, you can end up with file-locking issues, and in addition, memory isolation can break down when the same resource set is being used by multiple users.

You could rewrite the code, but that would almost certainly require significant and costly code changes.

Micro Focus Visual COBOL solves this with a construct called a Run Unit that can co-exist in the same process. A Run Unit is collection of one or more programs that share the same address space, lock tables, and OpenESQL connections. When using the runtime services type RunUnit you can create multiple Run Units in the same process, with all individual Run Units being isolated from each other.

A COBOL program in one Run Unit does not normally access the memory of a program in another Run Unit. There is isolation between them. Also, file locks are held for each Run Unit - if a program in one Run Unit holds a file lock, it is not accessible to a file-handling program in another Run Unit in the same process.

For complete details on using and coding multiple run units for procedural COBOL, see multiple user COBOL application in Java.

Run Units and SQL

Parent topic: Moving Native COBOL Applications to Managed COBOL


Using Java Managed Beans to Manage and Monitor COBOL Applications

Java technology includes support for managing and monitoring applications, objects and devices. JVM COBOL provides a managed bean (MBean) that enables you to manage and monitor RunUnits.

To enable the RunUnit MBean

You can enable a RunUnit MBean in one of the following ways:

  • For a particular RunUnit level
  • For all RunUnits you create

Using the RunUnit class to enable the RunUnit MBean for a particular RunUnit level:

A constructor on the RunUnit includes a RunUnitStartupOptions enum with a new value called UseManagementBean. The following illustrates how you can use the RunUnitStartupOptions enum with its UseManagementBean option:

 RunUnit myRUBean = new RunUnit("MyApplication",
                  RunUnitStartupOptions.UseManagementBean)
 try
 {
   myRUBean.add(new PROGRAM1());  // Where PROGRAM1 is the COBOL program
 }
 finally
 {
    myRUBean.stopRun();
 }

Using a cobconfig.properties text file to enable the MBean for all RunUnits you create:

  1. Use a text editor to create a file, cobconfig.properties.
  2. Add the following content to the file:
    mbeans=true
  3. Save the text file either in your application's .jar file or in the directory that stores your class files.

Using MBeans to identify issues

There are different programs such as Oracle's Java Mission Control or JConsole that enable you to view and use MBeans.

Before you can use the MBean with some versions of JRE, you need to enable your application for dynamic attachment. To do this, execute the following command from the Java command line:

-Dcom.sun.management.jmxremote

An MBean provides the following two attributes that enable a visual indication of how many RunUnits are live:

LogicalRunUnitCount
Provides a rolling counter of the numbers of RunUnits that have been created minus the number of RunUnits that have been ended.
LiveRunUnitCount
States the number of RunUnits that have not been garbage-collected.

If the values of LiveRunUnitCount and LogicalRunUnitCount, it could indicate one of the following issues:

  • One or more RunUnits have not been ended cleanly. You can end the RunUnit cleanly in one of the following ways:
    • Add an invoke to the StopRun method in the RunUnit class itself.
    • Add a STOP RUN call in the application. This automatically ends the RunUnit and causes a COBOLStopRunException.
  • If LiveRunUnitCount is larger than LogicalRunUnitCount, the RunUnit has most likely been kept alive because it is being held by another class. To resolve this, check where the RunUnit instance is stored and either set that instance to null or to end it, invoke the StopRun method in the RunUnit.
Note: There is always at least one RunUnit counter. This is because an initial or default RunUnit is created automatically for any application that does not use the RunUnit class.

The following figure shows an example of how the Java Mission Control tool displays a leak:

Figure 1. An example of a leak shown in Oracle's Java Mission Control Tool

Using MBeans to identify long-running RunUnits

You can use the MBean operation dumpAllLongRunninhRunUnitInfo to identify RunUnits that have been running for a specific period of time. The MBean operation takes a long parameter for the time in milliseconds.

In Oracle's Java Mission Control application, you can find this on the Operations tab for com.microfocus.runtimeservices and in the MBean Tree section - see the figure below.

Figure 2. Analysis of a long-running RunUnit in Oracle's Java Mission Control Tool Analysis of a long running RunUnit

The information returned from the MBean enables you to see the name, id, start time, GUID and a stack trace of where the RunUnit was created.

The oldest RunUnit is always the RunUnit with an id of 1 and this is the initial or default RunUnit.

Recommendation for best coding practice

If you create and use the RunUnit in the same method, Micro Focus recommends that you release the MBean in the finally clause - for example:

RunUnit myRUBean = new RunUnit("MyApplication",
                  RunUnitStartupOptions.UseManagementBean)
 try
 {
    ... use the myRUBean object
 }
 finally
 {
    myRUBean.stopRun();
 }

For more information, see:

  • The JConsole topic in the Java SE Documentation - the JConsole graphical user interface is a monitoring tool that complies with the Java Management Extensions (JMX) specification.
  • Oracle's Java Mission Control - the Java Flight Recorder and Java Mission Control tools together create a complete tool-chain to continuously collect low-level and detailed runtime information which enables you to perform an after-the-fact incident analysis.
Parent topic: Moving Native COBOL Applications to Managed COBOL


Accessing Procedural COBOL From Managed Code

There are different approaches to moving your existing applications to managed code.

Starting from scratch and rewriting existing procedural applications to managed COBOL is not recommended as it might be time-consuming and costly (and would mean more testing and more risk).

You can modernize your existing application without having to rewrite it. This is a safer approach and with it you preserve the existing procedural module that works well and create new managed parts that will reuse it. You have the flexibility of choosing the front-end application that will interact with the procedural module – a Web interface to access the functionality online, or a modern user interface to access the functionality on a tablet screen. As a result, your application will include a mixture of procedural and of Object-Oriented (OO) COBOL.

You could:

  • Use a managed COBOL wrapper class - you can preserve your procedural module and write a wrapper class in managed COBOL around it. Other managed languages can communicate directly with the wrapper class using OO syntax, The wrapper class, in turn, communicates with the procedural module.

  • Use ILSMARTLINKAGE - you can recompile the existing procedural code to managed code using the ILSMARTLINKAGE Compiler directive which exposes the linkage section data and creates the interfaces that other managed languages can interact with.

The following model shows what the architecture of your modernized application might look like:

With this model you:

  • Preserve the business logic - your existing procedural application uses data IO modules to access the data provided as data files or Relational Database Management System (RDBMS). You keep the business logic unchanged.
  • Use a new managed code front-end - you create an OO COBOL wrapper around the business logic or use Run Units to allow the front-end to talk to the business logic. You can use managed languages such as managed COBOL, Java, or C# to write the front-end application (for example, a User Interface or a Web service).
Parent topic: Moving Native COBOL Applications to Managed COBOL


Example of Using a Managed COBOL Wrapper Class

The following example illustrates how you can expose a procedural program to managed applications by wrapping the program in a managed COBOL wrapper class first. You then let other managed applications talk to the wrapper class using Object-Oriented (OO) syntax. The wrapper class, in its turn, talks to the procedural program.

There are different ways to write wrapper classes and this example two of them.

You are going to use a simple procedural COBOL program, a calculator, which performs the basic arithmetic operations. You will use Visual COBOL to create a managed project to hold the code of the procedural program and a managed COBOL wrapper class for the procedural code. You will also create a project for a managed COBOL front-end application that will communicate with the procedural module using the wrapper class.

Parent topic: Moving Native COBOL Applications to Managed COBOL


Example of Using the ILSMARTLINKAGE Compiler Directive

The following example illustrates how you can expose a procedural program to managed applications by compiling it to managed code with the ILSMARTLINKAGE Compiler directive. This helps expose the Linkage Section items and entry points in the procedural code to other managed languages by generating a class for each group item with the lower level data items being the members of the class.

In this example, you are going to use a slightly modified version of the calculator program which was used in the example of using wrapper classes.

Parent topic: Moving Native COBOL Applications to Managed COBOL


Native COBOL compared with managed COBOL

Native COBOL and managed COBOL differ in how they compile and how the run-time management services, such as security, threading and memory management are provided.

Managed COBOL for JVM compiles to Java bytecode, and native COBOL compiles to machine code. Both managed and native COBOL can run on any platform when compiled.

For JVM code, the management services are provided by JVM. For native COBOL, the management services are available in the operating system, and your code has to call the appropriate services depending on the operating system. The management services enable seamless interoperation of COBOL programs with programs in other managed languages.

Building native and managed COBOL applications

In the IDE (if you have Visual COBOL for Eclipse installed on a local machine) you can develop, compile and debug your applications, for both native and managed code.

When using Visual COBOL Development Hub in standalone scenarios, you use the command line to compile your native or managed code.

You can write new COBOL code or you can recompile existing COBOL as managed or native code, potentially without any code changes.

You can deploy and further debug the application under the run-time system provided by COBOL Server. JVM COBOL applications are deployed to the platform running the JVM.

Parent topic: Managed COBOL Programming
Related concepts
Executable File Formats
Procedural COBOL Compared with Managed COBOL


Compiling and Calling JVM COBOL Applications as Part of a Package

The mfjarprogmap utility enables you to create a Java property file that is required for the JVM COBOL run-time system to locate called programs that have been compiled as part of a package.

Without the Java property file generated by this utility, the run-time system cannot locate programs when called if they are compiled as part of a package; that is, compiled with the ILNAMESPACE Compiler directive. The property file contains a list of programs, and maps them to their packaged locations.

You can configure the run-time system to locate this Java property file by ensuring it is on the CLASSPATH (as shown in example 1), or by calling the .jar file that contains it directly from COBOL (as shown in example 2).

For full syntax available in the production of the Java property file, refer to Producing a Java Property File.

  • Producing a Java Property File
  • Example 1: Locating the Java Property File on the CLASSPATH
  • Example 2: Locating the Java Property File Directly from COBOL
Parent topic: Managed COBOL Programming


Producing a Java Property File

To produce the Java property file (named mfcobolprogmap.properties) required so that the run-time system can locate packaged programs when called, use the following script file:

mfjarprogmap [options] source-item

or .jar file:

java -jar "path/to/mfjarprogmap.jar" [options] source-item
Note: The default location for the script file is $COBDIR/bin. The default location for the .jar file is $COBDIR/lib.

where:

options
Can be one or more of:
-verbose
Displays verbose output during creation of the Java property file.
-time
Displays the time taken to create the Java property file.
-sort
Ensures that the programs in the Java property file are sorted in alphabetical order.
source-item

The location or file that contains the programs that will be mapped in the Java property file.

Can be one of:

-directory path\to\directory-name
The directory in which to search. The Java property file is also created in this location.
Note: Sub-directories of this directory are also searched.
-jar path\to\jar-name
The .jar file in which to search. The Java property file is added to the .jar file.
-file path\to\class-name
The .class file in which to search. The Java property file is created in the current working directory.
Parent topic: Compiling and Calling JVM COBOL Applications as Part of a Package
Related information
Example 1: Locating the Java Property File on the CLASSPATH
Example 2: Locating the Java Property File Directly from COBOL


Example 1: Locating the Java Property File on the CLASSPATH

This example demonstrates how the JVM COBOL run-time system uses a Java property file, created using the mfjarprogmap utility, to call a program that was compiled as part of a package. This example uses the CLASSPATH in order to locate the Java property file.

Note: The following example is designed to be run from a Visual COBOL command prompt.
  1. Copy and paste the following code into a new file, and save it as myapp.cbl.
            program-id myapp.
        procedure division.
        display "Hello world from myapp".
        goback.
        end program myapp.
  2. Create a trigger program to call the previous program: copy and paste the following code into a new file, and save it as caller.cbl.
            program-id caller.
        procedure division.
        call "myapp".
        goback.
        end program caller.
  3. Create a sub-directory in which to compile the source, and in which the Java property file will be created.
    mkdir bin
  4. Compile the source and trigger programs.
    cob -j caller.cbl
cob myapp.cbl -C 'jvmgen(sub)' -C 'iloutput(bin)'
              -C 'ilnamespace(com.mycompany.desktopapp)'
    A caller.class file is created in your current directory, and the myapp.class file is created in the bin/com/mycompany/desktopapp directory.
  5. Create the Java property file that the run-time system requires in order to locate myapp.class.
    mfjarprogmap -verbose -directory bin
    The mfcobolprogmap.properties file is created in the bin directory.
  6. Create a .jar file that contains the contents of the bin directory.
    jar cvf myapp.jar -C bin/ .
    myapp.jar is created in the current directory.
  7. Run the caller.class file, specifying myapp.jar on the CLASSPATH.
    java -classpath myapp.jar:.:$CLASSPATH caller
    The run-time system uses the Java property file within the .jar file to locate the program being called by caller.class, which results in the Hello world from myapp message being displayed.
Parent topic: Compiling and Calling JVM COBOL Applications as Part of a Package
Related information
Producing a Java Property File
Example 2: Locating the Java Property File Directly from COBOL


Example 2: Locating the Java Property File Directly from COBOL

This example demonstrates how the JVM COBOL run-time system uses the Java property file, created using the mfjarprogmap utility, to call a program that was compiled as part of a package. It shows how you can call a .jar file containing a Java property file, directly from COBOL.

Note: The following example is designed to be run from a Visual COBOL command prompt.
  1. Copy and paste the following code into a new file, and save it as myapp.cbl.
            program-id myapp.
        procedure division.
        display "Hello world from myapp".
        goback.
        end program myapp.
  2. Create a trigger program to call the previous program: copy and paste the following code into a new file, and save it as caller.cbl.
            program-id caller.
        01 p procedure-pointer.
        01 runner pic x(10).
        procedure division.
        set p to entry "myapp.jar".
        move "myapp" to runner.
        call runner.
        goback.
        end program caller.
  3. Create a sub-directory in which to compile the source, and in which the Java property file will be created.
    mkdir bin
  4. Compile the source and trigger programs.
    cob -j caller.cbl
cob myapp.cbl -C 'jvmgen(sub)' -C 'iloutput(bin)'
              -C 'ilnamespace(com.mycompany.desktopapp)'
    A caller.class file is created in your current directory, and the myapp.class file is created in the bin/com/mycompany/desktopapp directory.
  5. Create a .jar file that contains the contents of the bin directory.
    jar cvf myapp.jar -C bin/ .
    myapp.jar is created in the current directory.
  6. Create the Java property file, adding it to the .jar file in the process.
    mfjarprogmap -verbose -jar myapp.jar

    The mfcobolprogmap.properties file is created and added to myapp.jar.

  7. Run the trigger application.
    java caller
    The caller.class file runs, then calls myapp.jar, and because that .jar file contains the Java property file, the run-time system uses it to locate the called program in its packaged location. The result is that the Hello world from myapp message is displayed.
Parent topic: Compiling and Calling JVM COBOL Applications as Part of a Package
Related information
Producing a Java Property File
Example 1: Locating the Java Property File on the CLASSPATH


64-bit applications in the Java environment

Java COBOL applications running on a 64-bit platform can use either the 32-bit or the 64-bit JVM.
To set the platform to 64-bit, follow this procedure, which changes the JRE Library specified in the JVM Build Path:
  1. Right-click the project on the COBOL Explorer; then select Properties.
  2. Expand Micro Focus; then click JVM Build Path.
  3. On the Libraries tab, click Add library.
  4. Select JRE System Library; then click Next.
  5. Select Alternate JRE.
  6. If your 64-bit JRE is listed on the drop-down list, select it; if not, click Installed JREs and use the Preferences dialog box to add or find your 64-bit JRE library.
  7. On the JRE System Library wizard, click Finish to add the JRE library to the JVM Build Path.
    Note: Optionally, use the Order and Export tab to remove any unwanted JREs or to change the order in which JREs are accessed.
Parent topic: Managed COBOL Programming


Using a File Handler in JVM COBOL

File handling operations within JVM COBOL applications can be performed using the native Micro Focus File Handler or using the Managed File Handler.

The native Micro Focus File Handler is provided by the native run-time System, and the Managed File Handler is provided by the JRE itself.

By default, COBOL JVM project types within Eclipse use the native Micro Focus File Handler: if you view the project properties, you will see a reference to mfcobol.jar, as part of the COBOL JVM Runtime System library, in the Libraries tab of the Java Build Path settings. This jar file is what allows Java to access the native Micro Focus File Handler

There are certain circumstances in which the Micro Focus File Handler cannot be used, and in these situations, Visual COBOL automatically uses the Managed File Handler. For example, when running under environments such as Tomcat, WebSphere, or WebLogic, the JVM run-time system is unable to execute native COBOL code, and therefore the Managed File Handler is automatically used. Another example is when creating managed RunUnits via the RuntimeServices library API and you are accessing external files; again, this situation is not permitted to execute native COBOL code, and so defaults to using the Managed File Handler.

In situations where it is possible to use either File Handler, and you want to use the Managed File Handler, you must remove mfcobol.jar from the project: you do so by removing the COBOL JVM Runtime System library; also ensure that mfcobol.jar is not referenced on the CLASSPATH. Because the COBOL JVM Runtime System library also contained some other .jar files (other than mfcobol.jar) that are still required, you must add those files back into the project: on the Libraries tab, use the Add External Jar option to add the following .jar files: mfcobolrts.jar, mfsqljvm.jar, and mfunit.jar.

Note: These files are located in the bin or bin64 sub-directory of your project installation directory. You must select the bit-specific files for the JRE that the project is targeting.

For users working from the command line, you must similarly ensure that the files mentioned above are correctly included/excluded from the CLASSPATH; for example, to ensure that you exclude mfcobol.jar, you could specify set CLASSPATH=%CLASSPATH:mfcobol.jar=%.

Using the Managed File Handler has some inherent limitations; refer to File Handling Restrictions in Managed COBOL for more information.

Parent topic: Managed COBOL Programming
Related information
File Handling Restrictions in Managed COBOL


Multiple user COBOL applications in Java

  • Background to multiple run units and Java
  • Developing an application for multiple run units in Java
Parent topic: Managed COBOL Programming
Related reference
TRACELEVEL


Background to multiple run units and Java

Java server applications, such as servlet containers, typically have multiple users, each user running a session simultaneously with other users, whereas COBOL applications traditionally run single sessions each independent of each other. In Java, server applications are executed in a container. Each container can execute multiple instances of an application at the same time.

By default, when a procedural COBOL application runs in container, it is executed in the default COBOL run unit and it uses threads that share the same address space, by definition. If the application is executed several times simultaneously, that same run unit is used and consequently the same data is shared between all executions, which can cause problems.

In a multiple user environment, the COBOL application must use multiple run units, with each instance of the application running in its own run unit. To do this, you need to:

  • Compile the COBOL that you want to call. For procedural COBOL programs use the NOILSTATIC directive, which is the default. This enables any COBOL classes created to be included in a run unit.
  • Call the COBOL program within its own run unit. To do this, the calling program creates a run unit and creates an instance of the COBOL type that contains the program. Then the program instance can be invoked within the new run unit.
  • Include the run-time support for multiple run units, by adding a reference to the mfcobolrts.jar file.

Existing procedural COBOL is left unchanged:

Any COBOL program or CLASS with instance data/methods can be used with multiple run units providing you do not compile with the REENTRANT or ILSTATIC directives.

Parent topic: Multiple user COBOL applications in Java


Developing an application for multiple run units in Java

Note: The following applies to managed COBOL only.

You can use any existing COBOL program in a multiple user environment in Java. Do this as follows:

  1. Create a COBOL class library project and add your procedural COBOL program to that project.
  2. Rebuild the project.
Note: Managed COBOL code that uses EXEC SQL statements (including program, class, enum, and valuetype code) must exist in a managed run unit.

If the code requires a multi-user environment or a thread pool environment for proper execution, then the use of managed run units is also recommended, but is not required provided that the code is engineered for thread safety.

Whether the COBOL program to be called is procedural or OO COBOL, you need a program to call it:

  1. Create a project for the calling program.
  2. In the calling program, create a run unit using the com.microfocus.cobol.runtimeservices.RunUnit constructor.
  3. Use the Try ... Finally syntax to ensure that the program destroys the run unit if the program fails.
  4. Either use the RunUnit.Call() method to call the COBOL class, or:
    • Make sure that any parameters are Java primitive data types.
    • Create an instance of the procedural COBOL program to be called.
    • Add the program instance to the new run unit, using the RunUnit.Add() method.
    • Invoke the program instance within the new run unit.
  5. Use the StopRun() method to destroy the run unit when you have finished with it.
Notes:
  • If the run unit causes a run-time error, a java.lang.RuntimeException is thrown.
  • In OO COBOL programs in a mixed language environment, do not use static methods and data as they cause run-time errors.
  • Ensure that data access is synchronized, as each run unit executes in a different thread.

For details of the RunUnit class and further examples, see com.microfocus.cobol.runtimeservices topic.

Parent topic: Multiple user COBOL applications in Java
Related information
com.microfocus.cobol.runtimeservices


Introduction to Object-Oriented Programming for COBOL Developers

Managed COBOL is the collective term for .NET COBOL and JVM COBOL. Managed COBOL is regular procedural COBOL with extensions to take advantage of the features of the managed frameworks. This includes object-oriented (OO) syntax that allows access to large libraries of functionality you can use in your application, and much more. To take full advantage of Managed COBOL, it is helpful to understand the object-oriented concepts.

A guide that provides a basic introduction to Object-Oriented Programming (OOP) for COBOL developers, An Introduction to Object-Oriented Programming for COBOL Developers, with examples is available from the Product Documentation section on the Micro Focus SupportLine Web site - click here to download it.

Note: Visual COBOL for Eclipse supports managed COBOL. To develop applications for managed COBOL, install one of our Visual COBOL for Visual Studio products.
Parent topic: Managed COBOL Programming


Interoperability

Managed COBOL can invoke and be invoked by code in any other managed language. Managed COBOL can also invoke native COBOL. In addition, managed code in languages other than COBOL and native COBOL can interoperate by going through managed COBOL code.
  • Data Marshaling and Type Conversion for Managed Code Interoperation
    Data type compatibility is one of the main issues when managed COBOL interoperates with code in non-COBOL managed languages. Often, you need to manipulate the COBOL data into compatible types.
  • JVM COBOL Interoperating with Native COBOL
    This section covers how to CALL native COBOL, how to pass parameters of different types and some examples.
  • JVM COBOL Interoperating with Java
    This section covers how to call JVM COBOL from Java, how to call Java from JVM COBOL and some examples.
  • Mixed Language Programming
    This section covers parameters, return codes and call conventions for mixed language development with native COBOL.
Parent topic: Managed COBOL Programming


Data Marshaling and Type Conversion for Managed Code Interoperation

Data type compatibility is one of the main issues when managed COBOL interoperates with code in non-COBOL managed languages. Often, you need to manipulate the COBOL data into compatible types.
  • Type Compatibility in Interoperation with Managed Code
    For COBOL to interoperate with managed code in other languages, the COBOL must use data types that are compatible with those languages. Often there is not a strict one-to-one correspondence between types in different languages and so you need to manipulate the code to ensure compatibility.
  • Exposing COBOL Linkage Data as Managed Types
    You can expose the COBOL linkage section and entry points to other managed languages by compiling with the ILSMARTLINKAGE directive.
  • Type Mappings from Native COBOL to Managed Code
    COBOL data items are exposed as managed types, when the code is compiled with the ILSMARTLINKAGE directive.
  • Write a Proxy or Edit the COBOL for Managed Interoperation?
    If the COBOL types are incompatible with the managed non-COBOL you want to interoperate with, you can either re-engineer the existing COBOL, or write a proxy COBOL class to act as an interface between the existing COBOL and the non-COBOL.
Parent topic: Interoperability


Type Compatibility in Interoperation with Managed Code

For COBOL to interoperate with managed code in other languages, the COBOL must use data types that are compatible with those languages. Often there is not a strict one-to-one correspondence between types in different languages and so you need to manipulate the code to ensure compatibility.

Some ISO 2002 (or more precisely ISO/IEC 1989:2002) data types, such as binary-long and float-short are available, and we recommend you use these where appropriate. See COBOL Type Compatibility for details.

The techniques for ensuring data type compatibility include the following:

  • For integers, you could use the predefined type binary-long, which corresponds to int in both C# and Java.
  • For display types (PIC X fields), you could use a .NET System.String, a java.lang.String, or a portable string type.
  • For numeric types (PIC 9 fields), you could use a .NET System.Decimal, or in JVM a com.microfocus.cobol.program.ScaledInteger, and then you move the number out of there to whatever COBOL numerical field it was
  • For group items, you could use a value type to expose the items in the group.
  • For occurs types, you could use a .NET System.Collections.ArrayList, or java.util.ArrayList.
  • For other complex structures , you could use COBOL classes and value types with properties.
  • For object pointers, you could use a proxy class.

    For example, a program might invoke COBOL and want to pass an object pointer, where the object has properties containing the data to be passed. The called COBOL method has to extract the data required from the object properties and convert it into COBOL types, such as a group item containing PIC X fields. You could use a proxy class with properties to do this. The original COBOL can then handle the data in its traditional form.

Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation
Related information
Exposing COBOL Linkage Data as Managed Types
Write a Proxy or Edit the COBOL for Managed Interoperation?


Exposing COBOL Linkage Data as Managed Types

You can expose the COBOL linkage section and entry points to other managed languages by compiling with the ILSMARTLINKAGE directive.

Some items in the COBOL linkage section and in particular group items are not directly accessible from other languages. In the past, to access these items from other managed languages you had to create intermediate wrapper code, or modify the original COBOL code. You can now expose the linkage section and entry points to other managed languages by compiling with the ILSMARTLINKAGE directive.

For example, a COBOL group item can be defined as:

    linkage section.
        01 lnk-b-details.
            03 lnk-b-stockno      pic x(4).
            03 lnk-b-retail       pic 99v99.
            03 lnk-b-onhand       pic 9(5).
            03 lnk-b-sold         pic 9(5) comp-3.

The ILSMARTLINKAGE directive creates a class for each group item and exposes the lower level data items as members of the class. It exposes the data items with hyphens removed and an upper case letter following each removed hyphen. It also exposes COBOL native types as managed types. You can then access the data items in the group as properties of the class. For example:

    lnkBDetails.setlnkBStockno
    lnkBDetails.getlnkBStockno

The group item is exposed as a string property. If the group contains non-DISPLAY data (e.g. numeric COMP items), it will not be possible to use the property associated with the group to populate these non-DISPLAY items. In this case, these non-DISPLAY items must be populated using the individual properties associated with these non-DISPLAY items.

You can remove the prefixes from group item names, by compiling with the ILCUTPREFIX directive. For example, when you compile with ILCUTPREFIX(lnk-b), lnk-b-details is exposed as Details, and you can access the data items, like this:

    Details.setStockno
    Details.getStockno

In summary, to expose group items:

  • Compile the COBOL with ILSMARTLINKAGE and optionally with ILCUTPREFIX
  • In the non-COBOL project, add the COBOL project and Visual COBOL run-time system to the Java Build Path

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, ILCUTPREFIX(lnk-b-), ILCUTPREFIX(lnk-), and ILSMARTTRIM:

       program-id. BookLegacy.
                         ...
       linkage section.
       01 lnk-function            pic x.
       01 lnk-b-details.
          03 lnk-b-text-details.
             05 lnk-b-title       pic x(50).
             05 lnk-b-type        pic x(20).
             05 lnk-b-author      pic x(50).
          03 lnk-b-stockno        pic x(4).
          03 lnk-b-retail         pic 99v99.
          03 lnk-b-onhand         pic 9(5).
          03 lnk-b-sold           pic 9(5) comp-3.
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In Java, you can access the data in BookLegacy program in JVM COBOL as follows:

    BookLegacy myBook = new BookLegacy();
       //creates an object corresponding to the BookLegacy program
    Details myDetails = new Details();
       //creates an instance corresponding to the group lnk-bdetails
    . . .
       myDetails.setStockno("6666");
       myDetails.setTitle("Managed COBOL");
       myDetails.setAuthor("Mike Focus");
       myDetails.setType("Reference");
       myDetails.setRetail(new ScaledInteger(155, 5));
       myDetails.setOnhand(20);
Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation
Related information
Type Compatibility in Interoperation with Managed Code
Type Mappings from Native COBOL to Managed Code
ILCUTPREFIX
ILSMARTLINKAGE


Type Mappings from Native COBOL to Managed Code

COBOL data items are exposed as the following managed types, when the code is compiled with the ILSMARTLINKAGE directive:

Native COBOL | C# type | Java type | Managed COBOL
PIC X(n) | string | String | string
PIC S9(n) where n <= 2 | sbyte | byte | binary-char
PIC 9(n) where n <= 2 | byte | byte | binary-char unsigned Tip: You can use byte (or BYTE) as a synonym for binary-char unsigned.
PIC S9(n) where 2 < n <= 4 | short | short | binary-short
PIC 9(n) where 2 < n <= 4 | ushort | short | binary-short unsigned
PIC S9(n) where 4 < n <= 9 | int | int | binary-long
PIC 9(n) where 4 < n <= 9 | uint | int | binary-long unsigned
PIC S9(n) where 9 < n <= 19 | long | long | binary-double
PIC 9(n) where 9 < n <= 19 | ulong | long | binary-double unsigned
PIC 9(n)V9(m) | decimal | See JVMDECIMAL | decimal
COMP-1 | float | float | float-short
COMP-2 | double | double | float-long
PIC Z9 (and any numeric edited) | string | String | string
PIC A(n) | string | String | string
Group item | string | String | string
Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation
Parent topic: Concepts - Managed COBOL
Related reference
Type Specifier
Procedure Division Header
Related information
JVMDECIMAL
Types and Type Conversion
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Data Types - in COBOL and Java


Write a Proxy or Edit the COBOL for Managed Interoperation?

If the COBOL types are incompatible with the managed non-COBOL you want to interoperate with, you can either re-engineer the existing COBOL, or write a proxy COBOL class to act as an interface between the existing COBOL and the non-COBOL.

If the COBOL types are incompatible with the managed non-COBOL you want to interoperate with, you can either re-engineer the existing COBOL, or write a proxy COBOL class to act as an interface between the existing COBOL and the non-COBOL.

These two options have the following implications:

  • Editing the existing COBOL

    You manipulate the types so that the Linkage section uses compatible types. You might need to re-engineer the COBOL if there is more than one point of EXIT or GOBACK, so that you move data back into the new Linkage Section. Alternatively, you can re-engineer your COBOL as an OO COBOL class with one or more methods. Be aware that the more methods you use the more re-engineering you have to do.

    You compile your COBOL module to Java byte code, which exposes the module and its entry points as instance methods. Your managed code can then get the instance of the program and can then invoke the COBOL methods directly, just like any other methods.

  • Writing a proxy COBOL class

    You write a proxy class in managed COBOL, which adds a thin layer between the existing COBOL and the non-COBOL managed code. This class interfaces between COBOL and the managed application using objects and properties, using the standard COBOL CALL "program" USING… syntax.

    You recompile the existing COBOL to Java byte code (and in many cases there will be only a very few changes, particularly in non-UI COBOL subroutines).

    Your managed code can then invoke the proxy class, which in turn invokes the original COBOL.

The advantages of calling the COBOL directly are:

  • There might be a slight performance improvement, since there is no proxy layer
  • There are fewer modules to maintain
  • You don't need to write a proxy class

The advantages of using a proxy class are:

  • The same COBOL sources can be used in both managed and traditional applications and so they are usable on other platforms
  • The architecture is cleaner and easier to maintain
  • You don't need to modify the Linkage section of the original COBOL, or provide code to unpackage the data passed as properties in an object
  • If the proxy class implements an interface then standard coding patterns can be applied; that is, the implementation is separated from the definition.
Parent topic: Data Marshaling and Type Conversion for Managed Code Interoperation
Related information
Type Compatibility in Interoperation with Managed Code


JVM COBOL Interoperating with Native COBOL

This section covers how to CALL native COBOL, how to pass parameters of different types and some examples.
  • Calling Native COBOL from JVM COBOL
  • Passing Parameter Modes for JVM COBOL Calling Native COBOL
  • Pointers from Native Code to JVM COBOL
  • Strings in JVM COBOL Interoperation
  • Arrays of Bytes in JVM COBOL Interoperation
  • Limitations in JVM COBOL Interoperability
  • Example of JVM COBOL Interoperation with Native Code
Parent topic: Interoperability
Related reference
PC_WIN_INIT


Calling Native COBOL from JVM COBOL

In JVM COBOL, you use the CALL statement to interoperate with native code. For example:

 call xxx using by yyy p by zzz q returning r

Where:

xxx
is a storage or linkage item or a literal. This holds the entry point to which the CALL statement calls.
p and q

are the items between the using and returning key words. These are parameters. There can be zero or more parameters.

yyy and zzz
indicate the parameter passing mode (by content, by reference or by value). By reference is the default.
The returning clause
is optional

To call a native entry point in a shared library (.dll file on Windows or .so file on UNIX), you need to load the shared library to ensure that the JVM runtime system is aware of it. You must load the library before making the call to the native entry point.

For example, given program A compiled as JVM (JVMGEN):
       01 my-dll       procedure-pointer.

       set my-dll to entry "b"
       call "c"
And the native DLL containing COBOL programs B and C:
       program-id. b.
        display "IN B"
       end program b.

       program-id. c.
        display "INFO: in C"
        display "PASS"
       end program c.

This loads the native DLL (b.dll Windows) or CSO (b.so UNIX), making the programs it contains visible such that the CALL to program C succeeds.

The JVM run-time system attempts to resolve requested entry points to JVM methods that have the Callable attribute. If the entry point for a particular name is not found in JVM, the JVM run-time system attempts to resolve the entry point to a native entry point. If a native entry point is found, that entry point is called and that name is associated with the native entry point from then on, so that a full search is not done again.

Note:
  • You cannot call a native entry point that has the same name as a JVM entry point.
  • You cannot load two native libraries that have the same named entry point.
Parent topic: JVM COBOL Interoperating with Native COBOL
Related reference
JVM_LOAD_NATIVE (deprecated)


Passing Parameter Modes for JVM COBOL Calling Native COBOL

In JVM COBOL, you pass parameters to native COBOL entry points using the standard modes: by content, by reference and by value. Note that in native interoperation with JVM COBOL, parameter passing is controlled on the CALL statement, in the USING BY clauses. JVM COBOL does not inspect the USING information in the native COBOL entry point. For example:

JVM COBOL:

    call "x" using by reference y

Native COBOL:

    entry "x" using by value y

In the above example, 'entry x' receives a reference to y not the value of y despite the by value clause on the entry definition. This can cause undefined results.

Another Example

JVM COBOL:

    call "x" using by value y

C:

    int x(int* y)
    {...}

In this example the C will be expecting a pointer to y and it will receive the value of y.

Note:

We recommend that you use by content and by reference when calling native COBOL from JVM COBOL. The by value functionality is intended for interoperation with other languages like C and C++.

By Reference

When a parameter is passed by reference, a copy of the item in the JVM COBOL is passed to the native code. When the call to the native has finished, any changes to the information made in the native code are copied back to the JVM COBOL. However, this does mean that memory is shared between the JVM and native environments. In fact, what is actually passed to the native code is a pointer to the copied data. This is useful if you are calling non-COBOL programs.

The implications of this are very important, particularly in multi-threaded environments. Any changes to reference parameters are not visible to the JVM COBOL calling program until the call has completed.

Arbitrarily complex group items (within the memory limitations) can be passed by reference. The group definition must be identical in the native and JVM COBOL source code and it must not contain USAGE POINTER items.

Strings (java.lang.Strings) and tables (java.lang.byte arrays) can be passed by reference. All other objects (types that inherit from java.lang.Object, including valuetypes) cannot be passed by reference (or by value - see below).

By Content

Passing parameters by content is the same as passing by reference, except that the data is not copied back into the JVM COBOL memory when the call has completed.

Any item that can be passed by reference can be passed by content.

By Value

In JVM COBOL, the only items that can be passed by value are as follows:

  • binary-long - the recommended type for passing by value
  • pic x(4) comp-x
  • pic (9)9 comp
  • pic s(9)9 comp
  • pic (9)9 comp-5
  • pic s(9)9 comp-5

Returning Items

Only 32bit types are supported for returning items. Again, the recommended type is binary-long.

For example, where the native code uses GOBACK RETURNING x, x must be a 32-bit type. x is placed in the RETURN-VALUE special register of the RETURNING item, as defined in the CALL statement.

Parent topic: JVM COBOL Interoperating with Native COBOL


Pointers from Native Code to JVM COBOL

In theory, you can pass pointers from native code to managed code, but they have no meaning on the managed side, because if they were to be dereferenced they would give undefined results. This means you must not use data items defined as pointer in interoperation with native code.

To pass a pointer from native code to managed, you use an integer to hold the pointer. You must ensure that you allocate a storage item wide enough to store the pointer for the platform being used. We recommend using pic x for this purpose. For example:

    01 myPointer pic x(4).        *> on a 32-bit platform
    01 myPointer pic x(8).        *> on a 64-bit platform

On some platforms, the above example stores a pointer. So if we have an entry point 'getAPointer' which sets a reference to a pointer, you can call it as follows:

    call "getAPointer" using by reference myPointer

Equally, a pointer stored this way can be passed back to native code.

    call "setAPointer" using by reference myPointer

Note that callbacks are not supported in any form, since JVM COBOL entry point pointers have no meaning in native code

Parent topic: JVM COBOL Interoperating with Native COBOL


Strings in JVM COBOL Interoperation

In JVM COBOL, the String and type java.lang.String are identical, as in the following example:

 01 s String value "hello".
 01 s type java.lang.String value "hello".

When you pass strings from JVM COBOL to native code, we recommend that you pass them indirectly as pic x. For example:

 01 s String value "hello".
 01 toSend pic x(1024).
 01 sayer-ptr procedure-pointer.
 . . .
  move s to toSend
  set sayer-ptr to entry "sayer"
 call "say" using by reference toSend

You must ensure that the passed data is zero terminated if you are calling using the C string convention.

Parent topic: JVM COBOL Interoperating with Native COBOL


Arrays of Bytes in JVM COBOL Interoperation

In JVM COBOL, arrays of bytes are stored using the JVM special type java.lang.Byte[]. Byte arrays must be declared at the 01 level, as a COBOL table. Their size can be defined as part of the 01 definition or left undefined by using the ANY keyword. For example:

 01 b java.lang.Byte occurs any.

Arrays of type byte are objects but can be passed by reference to native entry points. This applies to single dimensional arrays only.

The bytes contained in the array are copied unchanged into a section of native memory of equal size and a reference to this piece of memory is passed to the native code. In COBOL this is equivalent to pic x data and in C to char* data. For example:

JVM COBOL:

 01 b java.lang.Byte occurs any.
 01 i binary-long.
 01 b-ptr procedure-pointer.
 set size of b to 1024
 perform varying i from 1 by 1 until i > 1024
   set b(i) to i /8
 end-perform
 set b-ptr to entry "doStuff"
 call "doStuffWith1k" using by reference b

Native COBOL:

 linkage section.
 01 b pic x(1024).
 ...
 entry "doStuffWith1k" using by reference b.
 ...
Parent topic: JVM COBOL Interoperating with Native COBOL


Limitations in JVM COBOL Interoperability

JVM COBOL currently has the following limitations:

  • The maximum size of any one data or group which can be passed to or from native code is 2GBytes or the platform limit, whichever is the smaller.
  • Callbacks are not supported in any form. JVM COBOL entry point pointers have no meaning in native code.
  • There is no correlation between JVM COBOL pointers and native pointers. This means that items declared as pointer in native interoperation give undefined results, but you can access the native memory from managed JVM via the JVM_UNSAFE_NATIVE_MEMCOPY API.
  • You cannot pass a JVM procedure-pointer to a native COBOL application.
Parent topic: JVM COBOL Interoperating with Native COBOL


Example of JVM COBOL Interoperation with Native Code

The following pair of programs show group items being used to interoperate between JVM COBOL and native COBOL.

Native COBOL:

    program-id. NativeProgram as "NativeProgram".
    linkage section.
    01 pets.
       03 p1 pic xxx.
       03 p2 pic xxx.
       03 result pic x(6).
    procedure division.
       goback.
       entry "SwapStrings" using pets.
          display "p1='" p1 "' p2='" p2 "'"
          move p1 to result(4:3)
          move p2 to result(1:3)
          goback.
    end program NativeProgram.

JVM COBOL:

    program-id. JVMProgram as "JVMProgram".
    01 pets.
        03 dog pic xxx value "dog".
        03 cat pic xxx value "cat".
        03 result pic x(6).
    01 nat-ptr procedure-pointer.
    procedure division.
       set nat-ptr to entry “NativeProgram"
        display ""
        display "Calling native program"
        display "======================="
        display "Pass in 2 strings: '" dog "' & '" cat "'"
        perform reset-all
       call "SwapStrings" using pets
        display "Native program swaps strings"
        display "result = '" result "'"
        display ""
        goback.
    reset-all section.
        move spaces to result
        .
    end program.
Parent topic: JVM COBOL Interoperating with Native COBOL


Avoiding data name conflicts

Some data names are shortened when used in an external context.

You can use the "#" character at the start of a COBOL data name in order to give an item a name that might otherwise be a reserved word (for example #Move). When the name is externalised, the "#" symbol is stripped from the name. Thus, if there are two COBOL names in the same context, which differ only by one having the initial '#' symbol, an error will result if the names are both to be externalised.

Examples of contexts in which names are externalised are fields that are instance or static data in a class, or the level 78 constants associated with an enum. For instance, the following enum definition will produce an error:

Enum-id MyEnum.
  78 Red value 1.
  78 #Red value 2.
End enum.
Parent topic: Mixed Language Programming


Multi-threaded Programming

  • Introduction to multi-threading
  • Synchronizing Execution and Resolving Contention
  • Writing Multi-threaded Applications
  • Multi-threading Compiler Directives
Parent topic: Programming


Introduction to multi-threading

Multi-threading is a term used to describe:
  • A facility provided by the operating system that enables an application to create threads of execution within a process
  • Applications whose architecture takes advantage of the multi-threading provided by the operating system
  • Multi-threading and the Operating System
  • Multi-threading and the Application
  • Multi-threading and the Command Line
Parent topic: Multi-threaded Programming
Related information
Synchronizing Execution and Resolving Contention
Writing Multi-threaded Applications
Multi-threading Compiler Directives


Multi-threading and the Operating System

On most modern operating systems, many different users can run programs (processes) at what appears to be the same time. If the operating system is hosted by a hardware system with a single Central Processing Unit (CPU) then these processes are not running at exactly the same time - it just appears that they are. The operating system allocates the CPU and other system resources to the processes that need them and (preemptively) switches these resources from one running program to another. This switching of resources gives the appearance that the programs are running at the same time.

In a very similar way, many modern operating systems allow multiple threads to exist within each process. Again, the operating system handles the allocation of the CPU and various resources to individual threads and switches these allocations from one running thread. Again, this gives the appearance that the threads are running at the same time.

If process and threads are handled in a similar way by the operating system, what distinguishes them from each other?

All processes have distinct address spaces, open files and other system resources; this enables each process to run with minimal or no effect on other processes running at the same time. However, this separation of resources has a run-time cost:

  • Each process consumes system memory for its address space
  • The operating system must update a lot of internal information whenever it switches execution context from one process to another

Because threads run within a single process, all of the threads associated with a process share the same data and code address space, the same open files and most other resources. Each thread also has its own register set and stack space. Creation of a thread, therefore, does not require extensive system memory. When the operating system finds it has to switch execution context from one thread to another within the same process, about the only thing the operating system needs to do is switch CPU ownership and register sets. This is the reason that threads are often called `light-weight processes'.

Parent topic: Introduction to multi-threading


Multi-threading and the Application

A multi-threaded application is an application whose architecture takes advantage of the multi-threading provided by the operating system. Usually, these applications assign specific jobs to individual threads within the process and the threads communicate, through various means, to synchronize their actions. For example, a data processing application might be designed so that the graphical user interface is completely handled by a single thread, while the actual work of the application is performed by another thread. This architecture would allow the complete separation of the business logic from the user-interface logic within the application.

Another interesting use for multi-threading within an application is in the server side of a client/server application. The server could be designed so that for each service request submitted to a main controller/communications thread, a separate service thread is created to process that request and communicate the results back to the controller. The controller would then communicate these results back to the client. The main benefit of such a design is that the server is not tied up acting on one client's request to the extent that it cannot respond to other client's requests quickly.

Of course, client-server applications that have immediate (or very fast) server response have been written without multi-threading for years. This is usually accomplished by a main controller/communications process creating separate service processes for each client request. So why does an application like this need multi-threading? The main answer is: efficient use of system resources.

The creation of a thread requires very little operating system resource (memory, context swap overhead and so on) and the sharing of files and other resources is simplified. The creation of a process requires more system resources and it tends to be much more difficult to communicate and share files between processes. Multi-threading allows you to make the best use out of your existing hardware resources and also allows simple resource sharing.

There are, of course, disadvantages in using multi-threaded applications. Each thread must be aware of the resources that it might be sharing with other threads in the same process. The programmer must remember that threads execute at the same time and that if two threads write to the same data item, without any form of execution synchronization, the data-item is likely to be corrupted.

For example, consider the following code fragments:

Working-Storage Section.
01 group-item.
  05 field-1  pic x.
  05 field-2  pic x.
procedure division.
move 'A' to field-1
move 'B' to field-2
display group-item

Working-Storage Section.
01 group-item.
  05 field-1  pic x.
  05 field-2  pic x.
procedure division.
move 'C' to field-2
move 'D' to field-1
display group-item

Consider the following possible order of thread execution:

Processing step Thread 1 execution Thread 2 execution
1
move 'A' to field-1
2
move 'C' to field-2
3
move 'B' to field-2
4
move 'D' to field-1
5
display group-item
6
display group-item

In this example, neither thread will display its expected result. The intended result of Thread 1 was to display 'AB', while the intended result of Thread 2 was to display 'DC'. However, the actual result is that both threads display 'DB'. If you are creating multi-threaded applications, you must synchronize execution between threads, and avoid and resolve data contention between threads, as described in the chapter Synchronizing Execution and Resolving Contention.

Parent topic: Introduction to multi-threading


Multi-threading and the Command Line

To run a multi-threaded application from the command line, use the cobrun_t command.

Parent topic: Introduction to multi-threading


Synchronizing Execution and Resolving Contention

This section describes how to control multi-threading within an application by synchronizing execution of threads, and resolving data contention between threads.

  • Introduction
  • Multi-threaded Program Attributes
  • Use of Data Attributes
  • Using Synchronization Primitives
Parent topic: Multi-threaded Programming
Related information
Introduction to multi-threading
Writing Multi-threaded Applications
Multi-threading Compiler Directives


Introduction

Uncontrolled multi-threading within an application can cause unpredictable end results. To achieve predictable results from an application, you need to synchronize execution of threads, and resolve data contention between threads; there are various methods you can use to achieve this. The methods you use depend on the characteristics of your application's data access, and the requirements for true multi-threading within the individual COBOL programs that make up your application. You can use:

  • Program attributes assigned by Compiler directives
  • The attributes of a data item to determine if there is a possibility that threads will contend for access to data items
  • Synchronization primitives
Parent topic: Synchronizing Execution and Resolving Contention


Multi-threaded Program Attributes

There are three main program attributes that affect multi-threading within a COBOL program. These attributes are assigned by including or omitting one of multi-threading Compiler directives when you compile your program. The directives used affect the allocation of the program's system work areas and can cause automatic system locking of the compiled program.

  • Specifying No Multi-threading
  • Serial Programs
  • Reentrant Programs
Parent topic: Synchronizing Execution and Resolving Contention


Specifying No Multi-threading

You can specify that a program is not a multi-threading program, by omitting any of the multi-threading Compiler directives when you compile your program.

If you do this, system work areas are allocated statically, and are thus subject to contention. This approach has several advantages, call speed and efficient stack usage among them, but it is up to your application to make sure that only one thread executes within a non-multi-threading program at a time. This can be accomplished through implicit program logic in any calling program; for example, when the application, by design, has only one thread calling a non-multi-threaded program. Alternatively, one of the synchronization primitives (such as a mutex) can be locked in the calling program just before the called program is entered and then unlocked when the called program has returned.

Parent topic: Multi-threaded Program Attributes


Serial Programs

In a program that has the serial attribute, system work areas are allocated statically, and the program is locked on entry and unlocked on exit.

This allows only one thread to execute the program at a given time and so eliminates any contention on system or user work areas. No other explicit application logic is required.

A program can be given the serial attribute by specifying the SERIAL Compiler directive when you compile it.

By specifying a traditional COBOL program as a serial program it can be included in a multi-threaded application without any source changes.

The disadvantages of serial programs are that:

  • The level of multi-threading is limited within the application. Ideally, a multi-threaded application should allow free execution of as much code as possible to allow maximum performance.
  • Locking and unlocking the program can have a major run-time cost. This can significantly affect call speed and overall application performance. For this reason, as few modules as possible should be compiled with this directive and, you should ensure that called programs have the no-multi-threading attribute. For example, if program A is to be compiled with the serial attribute and program A is the only program in the application that calls programs B and C, then by application design, program B and C are already serialized and can be compiled with the no-multi-threading attribute.
Parent topic: Multi-threaded Program Attributes


Reentrant Programs

You can specify that a multi-threaded program is to be reentrant by compiling it with the REENTRANT Compiler directive. You should use reentrant programs for most (if not all) of the modules in a multi-threaded application.

If you specify REENTRANT(1), all compiler-generated temporary work areas are allocated on a per-thread basis. All user data and FD file areas allocated in the Environment and Data Divisions are shared by all threads. It is the responsibility of the programmer to ensure serialization to the program's data by use of the CBL_ synchronization calls.

If you specify REENTRANT(2), all Working-Storage Section and File Section data, as well as system work areas, are allocated on a per-thread basis. Local storage is allocated dynamically on the stack. This eliminates thread contention on these areas, so that the program behaves safely if called from multiple threads concurrently. No program locking or unlocking is needed. The disadvantage with this Compiler directive setting is that there is no data shared (other than any data defined as EXTERNAL) between the threads.

REENTRANT(2) is a quick and simple way of getting a program running in a multi-threaded application, but you should aim to compile with REENTRANT(1).

A reentrant program must itself resolve all possible contention on data items in its Working-Storage Section and File Section. One or more of the techniques for resolving data contention must be used to accomplish this; see the next section for details.

Parent topic: Multi-threaded Program Attributes


Use of Data Attributes

The attributes of a data item determine if threads that access it can contend for it. Threads can never contend for data items defined:

  • In the Local-Storage Section or Thread-Local-Storage Section
  • With the THREAD-LOCAL data attribute

Any other data items defined within the program are shared between threads, so contention is possible. Contention might occur for:

  • Data defined in the Working-Storage Section and the File Section
  • Various other implicitly defined data items such as file-status fields
  • Data stored in some Compiler special registers (except the RETURN-CODE register)

Data defined in the Local-Storage Section is traditionally used in recursive COBOL programs; for every recursion of the program a new instance of this data is allocated on the stack. Since each thread in a multi-threaded application has its own stack, this attribute is ideal for defining contention-free temporary and work items within reentrant programs. By design, a reentrant COBOL program also allows recursion within a single thread.

The disadvantage of using data defined in the Local-Storage Section is that a data item disappears when the reentrant or recursive program exits. If a program has exited, then on the next entry into that program the data items defined in the Local-Storage Section have undefined values. If a thread requires the program to preserve state across calls, some other mechanism must be used.

Data defined as thread-local, either in the Thread-Local-Storage Section, or by the THREAD-LOCAL attribute, resolves these problems. Thread-local data is unique to each thread, persists across calls and can be initialized with value clauses. Thread-local data can be viewed as a thread-specific Working-Storage data item. This kind of data is very useful for resolving contention problems in most reentrant programs. In many cases, a program that does no file handling can be made completely reentrant by simply changing the Working-Storage Section header to a Thread-Local-Storage Section header. You can fine-tune data allocation by defining all read-only constants in the Working-Storage Section, and all read-write data items in Thread-Local-Storage Section.

The use of thread-local data has the following disadvantages:

  • Data values are not easily communicated between threads; for this it is better to define data in the Working-Storage Section and use appropriate thread synchronization.
  • It adds an overhead to program calls; if it is used in a high-traffic module then overall application performance can be seriously affected.
  • It is not possible to have EXTERNAL items within the Thread-Local-Storage Section. Currently, if thread-local data must be shared between application modules, the CBL_TSTORE_n routines must be used

Sometimes threads require more than just private data. Most multi-threaded applications communicate and coordinate thread execution through shared data that is accessed by each thread under a strict protocol. In COBOL this is accomplished through the use of Working-Storage Section or File Section data in conjunction with the use of various synchronization primitives that resolve any possibility for destructive contention on the data. See the next section for details of the synchronization primitives.

Parent topic: Synchronizing Execution and Resolving Contention


Using Synchronization Primitives

Synchronizing threads that access shared data is critical for predictable results in a multi-threaded application. Understanding the nature of the various data accesses between threads is the first step in determining what synchronization primitives and regimes should be used. Once the data access has been characterized, it is a simple matter to follow a synchronization regime for data items among all threads. The following sections outline common data sharing problems and their solutions.

  • Using a Mutex
  • Using a Monitor
  • Using a Semaphore
  • Using an Event
Parent topic: Synchronizing Execution and Resolving Contention


Using a Mutex

The simplest form of a data sharing problem is when multiple threads require mutually exclusive access to shared data at some point during their processing. The area of code that accesses this shared data is called a critical section and these critical sections can be protected by the use of a mutex that is logically associated with the shared data items. The term mutex comes from the phrase mutual exclusion. The mutex associated with the data items is locked before a critical section is entered and unlocked when that critical section is finished.

It is vital that all threads lock the mutex before accessing any of the data that is being protected. If even one thread fails to follow this regime, then unpredictable results could occur.

For example, the following code illustrates the protection of two critical sections that access a table, adding to it or counting items in it. The working storage data items table-xxx are protected by table-mutex.

Example

In this example the mutex is required to prevent a thread from adding data to the table while another thread reads the table at the same time.

 Working-Storage Section.
 78  table-length        value 20.
 01  table-mutex         usage mutex-pointer.
 01  table-current       pic x(4) comp-x value 0.
 01  table-max           pic x(4) comp-x value 0.
 01  table-1.
    05  table-item-1     pic x(10) occurs 20.

 Local-Storage Section.
 01  table-count         pic x(4) comp-x.
 01  table-i             pic x(4) comp-x.

* Initialization code executed while in single-threaded mode
     move 0 to table-max
     open table-mutex

* Add an item to table-1, this is a critical section
     set table-mutex to on
     if table-current < table-length
         add 1 to table-current
         move 'filled in' to table-item-1(table-current)
     end-if
     set table-mutex to off

* Count items in table-1, this is a critical section
     set table-mutex to on
     move 0 to table-count
     perform varying table-i from 1 by 1
             until table-i > table-current
         if  table-item-1(table-i) = 'filled in'
             add 1 to table-count
         end-if
     end-perform
     set table-mutex to off

One problem with using a mutex is that it can severely limit the level of multi-threading within an application. For example, say you have an application in which some programs add items to a table or count items in a table. In order to maximize multi-threading, you would want multiple threads to be able to count items in the table simultaneously. However, if a program was adding items to a table, you would not want a program to add items or count them.

A solution to this problem would be given by a synchronization primitive that enables multiple threads to be active in read-only critical sections but prevents any other access when a thread is active in a writer critical section; such a synchronization primitive is the monitor.

Parent topic: Using Synchronization Primitives


Using a Monitor

Monitors provide a solution to particular access problems not handled easily by mutexes. For example, you might want many threads to be able to simultaneously read data, but only one thread to be able write data. While the thread writes data, you might want to block read access by other threads.

A monitor is used by a critical section to declare what type of data access the critical section will be performing on the protected data; that is, reading, writing, or browsing.

The monitor synchronization facility can be extended to provide a critical section for browsing; this can be very useful in real world applications. A browser reads data and, depending on conditions you have set, might or might not write to protected data items. While a browser is active, any number of critical sections that simply read the data are allowed, while any other critical sections that browse or write are not allowed. If the browser thread determines that it needs to write to the protected data, it requests a conversion of the browse lock to a write lock. The conversion process waits until all critical sections that read the data are finished, and then bars any other critical sections that read or write data from accessing the data. The browser proceeds to write with exclusive access to the protected data items (whose state is guaranteed to be the same as it was when the browser was just reading the protected data).

Example

The following example code shows a monitor that controls the access of multiple threads that count items in, or add items to, a table. The code:

  • Enables multiple threads to access data for counting
  • Disables any threads that add items to the table when a thread that counts items is active
  • Enables one thread that adds items to a table; while this thread is active, the code disables access to the table by any thread that counts items
 Working-Storage Section.
 78  table-length                   value 20.
 01  table-monitor              usage monitor-pointer.
 01  table-current              pic x(4) comp-x value 0.
 01  table-1.
     05  table-item-1           pic x(10) occurs table-length.

 Local-Storage Section.
 01  table-count                pic x(4) comp-x.
 01  table-i                    pic x(4) comp-x.
  . . .
*> Initialization code, executed while in single
*> threaded mode
     move 0 to table-current
     open table-monitor

* Add an item to table-1, this is a writer critical section
     set table-monitor to writing
     if table-current < table-length
         add 1 to table-current
         move 'filled in' to table-item-1(table-current)
     end-if
     set table-monitor to not writing

* Count items in table-1, this is a reader critical section
     set table-monitor to reading
     move 0 to table-count
     perform varying table-i from 1 by 1
             until table-i > table-current
         if table-item-1 (table-i) = 'filled in'
             add 1 to table-count
         end-if
     end-perform
     set table-monitor to not reading

Example

The following is an example of a browser critical section:

 Working-Storage Section.
 01  data-monitor       usage monitor-pointer.
 01  data-value         pic x(4) comp-x value 0.

* Initialization code, executed while in single threaded
* mode
     open data-monitor

* Add an item to table-1, this is a browser critical section
     set data-monitor to browsing
     if data-value < 20
         set data-monitor to writing
             converting from browsing
         add 5 to data-value
         set data-monitor to not writing
     else
         set data-monitor to not browsing
     end-if

We do not recommend that you use a browse lock for such a simple check. Usually, you need only use a browser if a significant amount of work has to be done to determine if a write lock is actually required, and you want to maximize multi-threading throughout your application. There are various other monitor conversions available to help you maximize the level of multi-threading in your application

Parent topic: Using Synchronization Primitives


Using a Semaphore

A semaphore is a synchronization primitive that acts like a gate that lowers to prevent passage of a thread through code and raises to allow passage (of another thread) through that code. A semaphore is similar to a mutex, and can be used instead of a mutex.

Example

The following code illustrates the use of semaphores:

 Working-Storage Section.
 01  data-semaphore     usage semaphore-pointer.
 01  data-value         pic x(4) comp-x value 0.

* Initialization code executed while in single threaded mode
     open data-semaphore
     set data-semaphore up by 1      *> Initialize as raised

* Add change data-value, this is a critical section
     set data-semaphore down by 1
     add 1 to data-value
*  Allow other thread to pass semaphore
     set data-semaphore up by 1

Note that just after the OPEN verb, the semaphore is raised by 1. This enables the first acquisition of the semaphore to succeed but any following acquisitions to be blocked until the semaphore is released again.

A semaphore is less efficient than a mutex, but it is more flexible: one thread can simply release a semaphore while any other thread can then acquire it. Contrast this with a mutex. A mutex must always be acquired before it can be released, and the operations of acquiring and releasing it must happen within the same thread. Semaphores provide a way of signaling from one thread to another.

Example

The following code sample uses two different semaphores to establish handshaking between two threads. This handshaking enables one thread to signal the production of a new data value and the other thread to signal the corresponding consumption of that data value:

 Working-Storage Section.
 01  produced-semaphore         usage semaphore-pointer.
 01  data-value                 pic x(4) comp-x value 0.
 01  consumed-semaphore         usage semaphore-pointer.

* Initialization code executed while in single threaded mode
     open produced-semaphore
     open consumed-semaphore
     set consumed-semaphore up by 1

* This code is executed once to produce a data value
     set consumed-semaphore down by 1
     add 10 to data-value
*  Signal that data value has changed
     set produced-semaphore up by 1

* Another thread, waiting for the data-value to change,
* executes this code once as well.
     set produced-semaphore down by 1
     display data-value
*  Signal data value used
     set consumed-semaphore up by 1

This example illustrates another common synchronization problem known as the Producer-Consumer Problem. The simplest Producer-Consumer Problem is where there is one thread that produces data, and one thread that consumes that data, and you need to synchronize execution between the producing and consuming threads so that when the consumer is active it always has data to operate on.

The semaphores in this example count the number of releases that are outstanding on a semaphore and allow that many acquires to pass unblocked. This kind of counting semaphore enables the producer to produce multiple data values (usually in an array) before blocking to wait for the consumer to catch up.

Example

The following code illustrates a simple example of a producer/consumer pair where the producer is allowed to create data values until the data table cannot handle any more - at which point the producer blocks the creation of values until some values are consumed:

 Working-Storage Section.
 78  table-size    value 20.
 01  produced-semaphore   usage semaphore-pointer.
 01  filler.
     05  table-data-value pic x(4) comp-x
             occurs table-size times value 0.
 01  consumed-semaphore   usage semaphore-pointer.

 Local-Storage Section.
 01  table-i     pic x(4) comp-x.

* Initialization code executed while in single threaded mode
     open produced-semaphore
     open consumed-semaphore
*  Start raised 20 times
     set consumed-semaphore up by table-size

* Producer thread
     move 1 to table-i
     perform until 1 = 0
         set consumed-semaphore down by 1
         add table-i to table-data-value(table-i)
         set produced-semaphore up by 1
         add 1 to table-i
         if  table-i > table-size
             move 1 to table-i
         end-if
     end-perform.

* Consumer thread
     move 1 to table-i
     perform until 1 = 0
         set produced-semaphore down by 1
         display 'Current produced value is'
                 table-data-value(table-i)
         set consumed-semaphore up by 1
         add 1 to table-i
         if  table-i > table-size
             move 1 to table-i
         end-if
     end-perform.
Parent topic: Using Synchronization Primitives


Using an Event

An event is similar to a semaphore in that it enables one thread to signal to another that something has happened that requires attention. For several reasons an event is more flexible and slightly more complex. One reason is that an event, once posted, must be explicitly cleared.

Example

The following is an example of code that solves the Producer-Consumer problem by using event synchronization instead of semaphore synchronization:

 Working-Storage Section.
 01  produced-event     usage event-pointer.
 01  data-value         pic x(4) comp-x value 0.
 01  consumed-event     usage event-pointer.

* Initialization code executed while in single threaded mode
     open produced-event
     open consumed-event
     set consumed-event to true  *> Initialize as 'posted'

* Protocol for the producer side
     wait for consumed-event
     set consumed-event to false *> Clear event
     add 10 to data-value

* Signal that data value has changed
     set produced-event to true  *> Post event

* Protocol for the consumer side, waiting for the data-value
* to change
     wait for produced-event
     set produced-event to false *> Clear event
     display data-value

* Signal other thread that it can proceed, this thread has
* data-value
     set consumed-event to true  *> Post event

If there are only two threads (the producer and consumer threads) executing the above code, then everything will work as expected. If another thread comes in and starts executing as a producer or consumer, unexpected events will occur. This is because an event, once posted, wakes up all threads waiting for that event, unlike a semaphore which enables only one thread to pass after the semaphore has been released. After an event has been posted, and the waiting threads are woken, it is necessary for each of the woken threads to determine if it should take some form of action on the event (including clearing the event).

The last point can make events difficult to work with when there are multiple waiting threads but it also enables the building of custom synchronization objects for special needs.

Parent topic: Using Synchronization Primitives


Writing Multi-threaded Applications

This section describes and provides examples of writing multi-threaded applications.

  • Overview
  • Run-time System for Multi-threaded Applications
  • Thread Safety
  • Considerations When Creating Reentrant Programs
  • Multi-threading Library Routines
  • Manipulating Threads
  • Canceling Called Programs
  • Optimizations and Programming Tips
Parent topic: Multi-threaded Programming
Related information
Introduction to multi-threading
Synchronizing Execution and Resolving Contention
Multi-threading Compiler Directives


Overview

When you create a multi-threaded application you need to consider how each program in the application should operate: as a standard COBOL program, as a serial program, or as a reentrant program. Of the three types of program, programs compiled as REENTRANT(1) programs need most attention.

You also to need to consider how to:

  • Initialize applications
  • Manipulate threads
  • Create thread-local data

You should also be aware of common problems with multi-threaded programming.

Important: It is unsafe to modify or add environment variables in a threaded application on Linux systems. This is due to limitations of the underlying system libraries. It is however safe to read values from environment variables.
Parent topic: Writing Multi-threaded Applications


Run-time System for Multi-threaded Applications

The run-time system for multi-threaded applications needs to handle both multi-threaded and single-threaded applications. As a result, the multi-threaded run-time system incurs many of the synchronization costs that a standard multi-threaded COBOL application would. Further, most of these costs are incurred regardless of whether the application is multi-threaded or single-threaded. Because of this, and in order to enable single-threaded applications to run at maximum speed, Micro Focus provides two separate run-time systems: a multi-threaded run-time system that supports all applications, and a single-threaded run-time system that supports only single-threaded applications. You can choose between these run-time systems either when you run your application or when you link your application.

The files you need to ship with an application will depend in some cases on whether your application has been linked to the single-threaded or multi-threaded run-time system.

Parent topic: Writing Multi-threaded Applications


Thread Safety

It is unsafe to modify or add environment variables in a threaded application on Linux systems. This is due to limitations of the underlying system libraries. It is however safe to read values from environment variables.

Parent topic: Writing Multi-threaded Applications


Considerations When Creating Reentrant Programs

Not every program can be compiled as reentrant. Use of some COBOL features will preclude reentrant compilation; most of these COBOL features are obsolete or archaic in ANSI Standard COBOL and their use should be discontinued. Programs that use the following features cannot be compiled with the REENTRANT directive:

  • The ALTER statement
  • The ON statement
  • The COBOL DEBUG facility
  • Procedure Division overlays - note this can be overcome by using either the NOSEG or NOOVL directives
  • The IS INITIAL clause of the PROGRAM-ID statement - note this can be overcome by using REENTRANT"2"
  • The STICKY-LINKAGE Compiler directive
  • The STICKY-PERFORM Compiler directive

If you are creating a reentrant program, there are also other restrictions you should be aware of:

  • Most file handling verbs need explicit user protection with one of the synchronization primitives discussed earlier. Internally, the file handler is thread-safe; however, within the user program, file records, buffers and status fields are set without the benefit of locking. This can lead to contention and resulting corruption of these fields. You should take measures to protect file handling verbs.
  • Execution of any file operation is serialized within the file-handler with a global file-handling mutex. This means that only one thread can access any file at a given time. This could lead to problems if a read from a file is delayed for some reason; for example, because of a record lock. In this case, no other thread can perform any file handling operations until the delayed read is finished.
  • Execution of any sort operations is serialized within the sort handler with the global file-handling mutex. While a sort is occurring no other thread can perform other sort or file handling operations. Execution of the INPUT and OUTPUT procedures occur in the thread that started the sort operation. File handling within these procedures executes normally.
  • Execution of the DISPLAY verb requires user protection with one of the synchronization primitives. Internally, the console display handler is thread-safe; however, each complex display is broken down into multiple calls to the display handler. This can lead to interleaved displays of data items. In general, it is best to assign only one thread to console I/O within a multi-threaded application.
  • Nested programs cannot be the starting point of a newly created thread. Only ENTRY points, outermost programs in a compilation unit and other-language external entry points can be the starting point for thread creation.
  • Execution of the ACCEPT verb is serialized within the accept handler. This means that all other threads are prevented from doing any ACCEPT or DISPLAY operations while the original ACCEPT is outstanding.

The following performance and resource penalties are incurred in reentrant COBOL programs within a multi-threaded application:

  • Use of the THREAD-LOCAL-STORAGE section can incur significant program entry costs. If possible, use LOCAL-STORAGE instead for thread-local work variables. Program entry overhead can be minimized by the use of CALL speed optimizations.
  • A reentrant program consumes more stack space than either a standard or a serialized COBOL program. This is because system work-areas must be allocated on the stack, instead of statically.
Parent topic: Writing Multi-threaded Applications


Multi-threading Library Routines

Call-by-name library routines provide a programming interface through which you can implement and control multi-threading in your applications. While many facilities of multi-threading are accessible through the COBOL syntax, all facilities are also accessible through COBOL run-time library routines. The run-time library routines also offer advanced multi-threading programming capabilities that are unavailable through the COBOL syntax.

  • Thread-control Routines
  • Thread-synchronization Routines
  • Routines for Handling Thread-specific Data
  • Initializing Applications
Parent topic: Writing Multi-threaded Applications


Thread-control Routines

The library routines for controlling threads can be used to implement threads that wait for another thread to terminate and then pick up a return value.

You should terminate any thread created using these library routines by one of the following methods:

  • Exit using STOP RUN
  • Exit using CBL_THREAD_EXIT
  • Be killed by CBL_THREAD_KILL
  • Return from the original entry point

A thread might not have been created by the thread-control routines. However, such a thread might still be known to the run-time system by the thread's use of run-time system services. Such a thread can be accessed via the thread-control library routines; it can use:

  • The CBL_THREAD_LIST_START, CBL_THREAD_LIST_NEXT, and CBL_THREAD_LIST_END routines. The thread will also show up in the lists provided by these routines.
  • The CBL_THREAD_IDDATA_ALLOC and CBL_THREAD_IDDATA_GET routines.
  • The CBL_THREAD_SELF routine to get information on itself.
  • The CBL_THREAD_SUSPEND and CBL_THREAD_RESUME routine.
  • The CBL_THREAD_DETACH routine to detach itself while still alive; however this call is effectively a noop. Irrespective of any detach call, the resources of the thread from a program in another language are freed when it finishes using the run-time system and calls cobthreadtidy(). It is illegal for a thread from a program in another language to terminate without first calling cobthreadtidy().

In a mixed-language environment, any thread known to the run-time system from its use of the run-time system, but not created by the run-time system or any of the thread control routines, must do one of the following:

  • Call cobthreadtidy() before terminating. This call informs the run-time system that the thread no longer needs its services and allows it to cleanup its thread-state data.
  • Call cobtidy() to indicate that the COBOL run-time system will not be needed again in this application run.
  • Call cobexit() to terminate the run unit.
  • Not be killed by another thread calling CBL_THREAD_KILL. The user should use the kill mechanism that matches how the thread was created originally.
  • Not be waited on by another thread calling CBL_THREAD_WAIT. The user should use the wait mechanism that matches how the thread was created originally.
  • Not exit by using the routine CBL_THREAD_EXIT. The user should use the termination mechanism that matches how the thread was created originally.

An application can check that the run-time system used by a program supports the thread-control routines by calling either CBL_GET_OS_INFO or CBL_THREAD_SELF.

Example - Checking Which Run-time System a Program Supports

     call "CBL_THREAD_SELF" using thread-id
      on exeception
*       no cbl_thread routines support
     end-call
     if  return-code = 1008
*       running in a single-threaded-only rts
     end-if
Parent topic: Multi-threading Library Routines


Thread-synchronization Routines

This COBOL system provides four types of synchronization object: monitors, semaphores, mutexes, and events. Control of these synchronization objects is provided by COBOL syntax, and also by call-by-name library routines.

Parent topic: Multi-threading Library Routines


Routines for Handling Thread-specific Data

You can create dynamic data whose lifetime is that of the creating thread, or selective or external thread-local data, using the run-time library routine CBL_ALLOC_THREAD_MEM and the library routines CBL_TSTORE_n.

Parent topic: Multi-threading Library Routines


Initializing Applications

The initialization of multi-threaded applications needs some care. First, as good programming practice, the application should determine if it is running with a run-time system that supports multi-threading. See the following example.

Example - Checking the Run-time System

 Working-Storage Section.
 01 thread-id     usage pointer.
 . . .
* Initialization code executed while in single-threaded
* mode to check if the run-time system supports
* multi-threading or the CBL_THREAD_ routines.
     call 'CBL_THREAD_SELF' using thread-id
      on exception
*        No cbl_thread routines support
     end-call
     if return-code = 1008
*        Running in a single-threaded rts
     end-if

This example makes use of the run-time library routine CBL_THREAD_SELF to determine if the run-time system supports multi-threading.

After the application has determined that the run-time system supports multi-threading, all synchronization primitives should be be initialized using the appropriate OPEN syntax. It is easiest to do this as part of the main program, before any other threads are created within the application. However, if this not possible, either because of the way the application is designed, or because of modularity or mixed-language considerations, Micro Focus have provided a single pre-initialized mutex per program. This mutex is accessed using the CBL_THREAD_PROG_LOCK and CBL_THREAD_PROG_UNLOCK run-time library routines. Using these routines, it is possible to ensure that any handles for program -local synchronization primitives are initialized once (and only once) during the execution of the application.

Example - Thread Locking Using Library Routines

The following code illustrates a sample use of these routines for program initialization while running in multi-threaded mode:

 Working-Storage Section.
 01 first-flag         pic x comp-x value 1.
    88 first-time       value 1.
    88 not-first-time   value 0.

* Initialization code executed while in multi-threaded mode.
* Ensures that program local data is initialized properly.

     if first-time then
         call 'CBL_THREAD_PROG_LOCK'
         if first-time then
* Initialize program local data and synchronization objects
               ...
             set not-first-time   to true
         end-if
         call 'CBL_THREAD_PROG_UNLOCK'
     end-if

Note the double checking of the first-time level-88 data item. This is a good optimization technique in multi-threaded applications. The idea of the optimization is to avoid the overhead of locking a mutex if the intended action has already been performed. In this case, if multiple threads enter the program before it is properly initialized, they will all find that first-time is true and so issue a call to CBL_THREAD_PROG_LOCK. However, only one will acquire the lock while first-time is still true. This is the thread that will do the initialization.

After the initialization is completed, and while the initializing thread still owns the lock, the first-time flag is set to false. All successive threads acquiring the lock can see that the initialization has already been done, as first-time is now false, and unlock the program immediately. Any following threads that enter after initialization will also see the first-time flag is false and will not attempt to acquire the program lock (and so reduce program entry overhead).

The flag that specifies whether initialization has occurred should as simple as possible (that is, a single byte data item).

Parent topic: Multi-threading Library Routines


Manipulating Threads

The multi-threaded run-time system supports threads created by the run-time system itself, via the START verb or the CBL_THREAD_n library routines, and also other-language threads created directly by the operating system. Since the COBOL syntax and the CBL_THREAD_n routines are portable, these are the preferred methods of thread manipulation. Furthermore, the CBL_THREAD_n routines can also be called from programs written in other languages, allowing any multi-threaded application to take full advantage of the advanced facilities provided by the run-time system.

  • Thread Handles
  • Creating and Terminating a Thread
  • Canceling a Thread
  • Suspending a Thread
  • Identifying a Thread
  • Threads in Other Languages
Parent topic: Writing Multi-threaded Applications


Thread Handles

In general, threads are identified to the run-time system by thread handles. Thread handles are provided to:

  • The module that creates a thread, as a return value from the START verb, or from the CBL_THREAD_CREATE routine
  • An individual thread by the return value from the CBL_THREAD_SELF routine.

The thread handle uniquely identifies the thread to the various multi-threading COBOL verbs or to CBL_THREAD_n routines. With reasonable care, thread handles can be used by any of the active threads in the run-unit, not just the creator of a thread. It is important to remember that the lifetime of a thread and that of its thread handle might not be the same. Depending on how a thread was created and what operations have been done on it, a thread handle could still be valid even if the thread has terminated. In order to enable the system to recover the resources associated with the handle, it is up to the user to explicitly detach the handle for a thread.

A handle can become detached from its thread in one of several ways. When a thread is created with the START verb or CBL_THREAD_CREATE routine, its handle is, by default, created as detached. When another-language thread becomes known to the run-time system, its handle is automatically and always created as detached. A non-detached handle can be detached with a call to CBL_THREAD_DETACH. In any case, a detached handle must always be used with care, as when the thread terminates the handle immediately becomes invalid. If a thread with a non-detached handle has already terminated, then a call to CBL_THREAD_DETACH with that thread handle will immediately cause the handle to become invalid.

A non-detached handle is useful for retrieval of return values (via the WAIT verb or CBL_THREAD_WAIT routine), and for inspection of thread identification data (via the CBL_THREAD_IDDATA_GET routine) after a thread has potentially terminated. The START verb provides a way of identifying a newly created thread by returning a non-detached thread handle. The CBL_THREAD_CREATE routine provides a flag to indicate that the thread should be created and a non-detached handle returned.

Parent topic: Manipulating Threads


Creating and Terminating a Thread

Threads are either created by one of the following methods:

  • START verb
  • CBL_THREAD_CREATE routine
  • Specific operating system call for thread creation

Threads created by the first two methods are called COBOL threads. Threads created directly by the operating system are called other-language threads.

As the creation and manipulation of COBOL threads is portable, and the preferred method, we will only deal with them here.

The starting point for a thread must be either a non-nested Program-Id, a COBOL entry-point or an externally visible routine written in another language, such as C. It must not be a nested program, or a section or paragraph name.

The name of the starting point can be specified as a text string. The overhead in using a text string to find the entry point is equivalent to resolving the verb CALL identifier. It is possible to avoid this overhead by using a procedure pointer as the object of a START verb.

The starting point for every created thread is provided with only one parameter. If the BY CONTENT phrase is used in passing this parameter, a copy of it is made by the system before the thread is created, leaving the calling thread free to modify the original parameter upon return from the START verb.

Creation of a thread with a non-detached handle (via the IDENTIFIED BY clause) enables the return value to be obtained later by the WAIT verb. After the WAIT verb has completed the specified thread handle becomes invalid and all resources associated with the subject thread are released.

A STOP RUN RETURNING statement in the created thread does not end the run unit; it simply provides a return value and terminates the thread. It is equivalent to:

call 'CBL_THREAD_EXIT' using by value address of thread-parm.

A STOP RUN statement in other-language threads or in the main thread of a run unit not created by CBL_THREAD_CREATE will wait for all active COBOL threads to finish and then terminate the run unit.

Return values from threads are always pointers. This allows you to return both simple and complex data structures.

A thread can terminate itself with STOP RUN or a call to CBL_THREAD_EXIT. A thread also terminates normally when the starting point program exits via EXIT PROGRAM or GOBACK. It is also sometimes useful for another thread to cause a COBOL thread to be terminated. The CBL_THREAD_KILL routine achieves this.

Example - Creating and Terminating a Thread

$set reentrant

 Data Division.
 Working-Storage Section.
 01 thread-handle           usage pointer.
 01 thread-return           usage pointer.

 Linkage Section.
 01 thread-parm             picture x(32).
 01 thread-return-record    picture x(32).
 Procedure Division.
*> Starting point
     call 'CBL_THREAD_CREATE'
           using    'CREATED ' *> Note the space before the second single-quotation-mark
                    'This is a 32 character parameter'
           by value 0  *> Optional parameter size
                    1  *> Flag to create non-detached
                    0  *> Default priority
                    0  *> Default stack
           by reference thread-handle
     if return-code = 0
         call 'CBL_THREAD_WAIT' using
                             by value thread-handle
                             by reference thread-return
         set address of thread-return-record
                                          to thread-return
         display thread-return-record
     end-if
     stop run.

 Entry "CREATED" using thread-parm.
     display thread-parm
     stop run returning address of thread-parm.

This application simply creates a thread with the starting point CREATED. The thread displays its parameter and returns the address of that parameter for use in the parent thread. The STOP RUN RETURNING in the CREATED thread does not end the run unit, instead it simply provides a return value and terminates the thread. It is equivalent to:

call 'CBL_THREAD_EXIT' using by value address of thread-parm.
Parent topic: Manipulating Threads


Canceling a Thread

Threads created with CBL_THREAD_CREATE can be canceled with the CBL_THREAD_KILL routine. You cannot use CBL_THREAD_KILL to kill threads created in other ways. This call causes immediate, abnormal termination of a COBOL thread but, in general, it should not be used as part of general application thread control. The main reason for this is that some user and system synchronization resources will not be properly unlocked and/or freed when the thread terminates. This can affect the synchronization within the user application and the run-time system, which can cause serious problems with the application.

CBL_THREAD_KILL can reasonably be used within a critical error handler in the main thread. In this error handler, thread handles can be acquired by way of the CBL_THREAD_LIST_n routines, all threads can be canceled and the application can then exit via STOP RUN. This is less dangerous than the random use of CBL_THREAD_KILL as it minimizes the chance of needing a locked synchronization primitive but there is still a possibility of file corruption or deadlock during run-unit termination.

In any case, most applications should avoid using CBL_THREAD_KILL. This can be achieved by creating thread identification data (through the CBL_THREAD_IDDATA_ALLOC routine) that has a terminate flag in it. That data can then be polled in each thread at a level where no locks are held. If the terminate flag is set, then the polling thread can exit gracefully.

Example - Creating Thread Identification Data and Terminate Flags

      ******************** MAINPROG.CBL ********************
       identification division.
       program-id. mainprog.

       Data Division.
       Local-Storage Section.
       01  ret-ptr                 usage pointer.
       01  iddata-ptr              usage pointer.
       01  sub-iddata-ptr          usage pointer.
       01  sub-handle              usage thread-pointer.
       Linkage Section.
       01  iddata-record.
           05  iddata-name         pic x(20).
           05  iddata-term         pic x comp-x value 0.

       Procedure Division.

      * Establish identification data - don't provide
      * initialization data when it is allocated, instead
      * initialize it after the pointer is retrieved.

           call 'CBL_THREAD_IDDATA_ALLOC' using
                                      by value zero
                                  length of iddata-record
           call 'CBL_THREAD_IDDATA_GET'   using iddata-ptr
                                                omitted
           set address of iddata-record to iddata-ptr
           move 'main' to iddata-name

      * Create sub-thread

      * Starting point
           call 'CBL_THREAD_CREATE' using
                                 'SUBPROG '
                        by value 0   *> No parameters
                                 0   *> Optional - parameter size
                                 0   *> Flag to create detached
                                 0   *> Default priority
                                 0   *> Default stack
                    by reference sub-handle
           if  return-code not = 0
               display 'unable to create thread'
               stop run
           end-if

      * Wait until child creates its iddata and then flag
      * termination

           set sub-iddata-ptr to NULL
           perform until 1 = 0
               call 'CBL_THREAD_IDDATA_GET'
                      using    sub-iddata-ptr
                      by value sub-handle
               end-call
               if  sub-iddata-ptr not = null
                   exit perform
               end-if
               call 'CBL_THREAD_YIELD'
           end-perform
           set address of iddata-record to sub-iddata-ptr
           move "stop" to iddata-name
           move 1 to iddata-term

      * Wait till the child exits
           wait for sub-handle

           display 'All synchronization is complete on ' &
                   'RTS termination'
           stop run.
       end program mainprog.

      *************** SUBPROG.CBL  ********************************
       identification division.
       program-id. subprog.

       Data Division.
       Working-Storage Section.
       01 sub-iddata.
          05  sub-name             pic x(20) value 'sub'.
          05  sub-term             pic x comp-x value 0.
       Local-Storage Section.
       01  iddata-ptr              usage pointer.
       01  thread-handle           usage pointer.
       01  thread-state            pic x(4) comp-x.
       01  parent-handle           usage pointer.
       Linkage Section.
       01  iddata-record.
           05  iddata-name         pic x(20).
           05  iddata-term         pic x comp-x value 0.
       Procedure Division.

      * Establish identification data - provide initialization data
           call 'CBL_THREAD_IDDATA_ALLOC' using
                                        sub-iddata
                               by value length of sub-iddata

      * Find our parent thread and resume him
      *
           call 'CBL_THREAD_LIST_START' using thread-handle
                                              thread-state
                                              iddata-ptr
           set parent-handle to NULL
           perform until thread-handle = null
                      or return-code not = 0
               if iddata-ptr not = null
                   set address of iddata-record to iddata-ptr
                   if  iddata-name = 'main'
                       set parent-handle to thread-handle
                       exit perform
                   end-if
               end-if
               call 'CBL_THREAD_LIST_NEXT' using thread-handle
                                                 thread-state
                                                 iddata-ptr
           end-perform
           call 'CBL_THREAD_LIST_END'
           if  parent-handle = NULL
               display 'synchronization error'
               stop run
           end-if
           call 'CBL_THREAD_IDDATA_GET'   using iddata-ptr
                                                omitted
           set address of iddata-record to iddata-ptr
           perform until iddata-term = 1
               call 'CBL_THREAD_YIELD'
           end-perform
           exit program.
       end program subprog.

This rather lengthy example doesn't actually do anything but establish handshaking for thread and application termination. Before going into any discussion on it, it is worth noting that this kind of handshaking could have been accomplished more easily by passing the main thread's handle into the child as a parameter. This would have avoided the need to rely on identification data or to step through the thread list.

Consider the following points about the example application:

  • Thread identification data is created in two ways:
    • In the parent thread, data is created uninitialized; the thread then retrieves the iddata pointer and initializes the area of memory that was allocated.
    • The child thread provides initialization data to eliminate any possible execution window between iddata allocation and iddata initialization by the application.

    The method you use in your application depends on what level of contention you expect on identification data.

  • The loop in the parent thread waits for the child to create its thread identification data; the loop in the child thread waits for the parent to flag termination. The call to CBL_THREAD_YIELD prevents these loops from being hard busy waits, but would have been better coded using an event or condition synchronization object. In unmanaged code, you could use CBL_THREAD_SUSPEND and CBL_THREAD_RESUME, alternatively.
  • The use of CBL_THREAD_LIST, which enables a thread to step through all threads known to the run-time system, obtaining the thread handle, thread state and identification data pointer. The example relies only on the handle and identification data pointer but the state information can also be useful, as it lets the calling thread know if the subject thread is detached, suspended or an other-language thread.

    If a thread uses the CBL_THREAD_LIST routine:

    • That thread is limited in which other CBL_THREAD_n routines it can use
    • Other threads cannot use any CBL_THREAD_n routines, and the use of some other library routines is restricted

    For this reason you should:

    • Mimimize the amount of code executed while stepping the list
    • Avoid file or user I/O while the list is locked

    These restrictions are removed only after stepping is terminated by a call to CBL_THREAD_LIST_END.

Parent topic: Manipulating Threads


Suspending a Thread

In many multi-threaded applications it is not uncommon for a thread to 'run out of work' but not need to terminate just yet. In a client-server architecture, for example, the main service thread could be polling an input queue for requests and if it finds none then it makes sense to allow another process or thread to have the CPU before polling the input queue again. This is simply done by calling CBL_THREAD_YIELD which yields the processor to some other thread in the application (or some other thread in another process, depending on the operating system).

Another possibility is that a thread needs to yield the CPU indefinitely and obtain it only when some sort of event has definitely happened. CBL_THREAD_SUSPEND allows suspension of the calling thread until some other thread does a CBL_THREAD_RESUME using the thread handle for the suspended thread. A thread can call CBL_THREAD_RESUME one or more times before the targeted thread suspends itself and, in this case, the call to CBL_THREAD_SUSPEND returns to the calling thread immediately and does not give up ownership of the CPU. This operation is very similar to that of a counting semaphore; in fact, the Producer-Consumer problem can be solved using only the CBL_THREAD_SUSPEND and CBL_THREAD_RESUME routines.

Parent topic: Manipulating Threads


Identifying a Thread

It is sometimes useful for a thread to distinguish itself from any other created threads in an application. For example, if two threads in a four thread application establish a producer-consumer relationship, it can be useful for the two cooperating threads to find out what each other's thread handles are. Once these handles are obtained, all synchronization can be done using only the CBL_THREAD_SUSPEND and CBL_THREAD_RESUME calls. If each thread in the application creates a name for itself (and the name relates to its functionality) and associates the name with its thread handle, then the cooperating threads can scan the thread name list and find each other's handle.

Another possible use for associating globally accessible data to each thread and its handle is to hold a termination flag, obviating the possible need to use CBL_THREAD_KILL. Each thread in the application can poll its termination flag to check for a termination request. The terminating thread can then make sure no locks are held and no synchronization actions are required before terminating normally.

Globally accessible data for a thread is associated with the thread handle by the CBL_THREAD_IDDATA_ALLOC routine executed within the thread. This data is retrieved by the CBL_THREAD_IDDATA_GET routine, if the thread handle is already known, or by the CBL_THREAD_LIST_n routines if the thread handle is not yet known.

Example - Associating Globally Accessible Data With a Thread Handle

The following example shows how to associate globally accessible data with the thread handle by using the CBL_THREAD_IDDATA_ALLOC call executed within the thread. The data is retrieved by the CBL_THREAD_IDDATA_GET call, if the thread handle is already known, or by the CBL_THREAD_LIST_n routines if the thread handle is not yet known.

      *************** MAINPROG.CBL ************************
       identification division.
       program-id. mainprog.

       Data Division.
       Local-Storage Section.
       01 ret-wait         usage pointer.
       01 iddata-ptr       usage pointer.
       01 sub-iddata-ptr   usage pointer.
       01 sub-handle       usage thread-pointer.
       Linkage Section.
        01 iddata-record.
           05 iddata-name  pic x(20).
         05 iddata-term    pic x comp-x value 0.

       Procedure Division.

      * Establish identification data - don't provide
      * initialization data when it is allocated, instead
      * initialize it after the pointer is retrieved.

           call 'CBL_THREAD_IDDATA_ALLOC' using
                                          by value zero
                                          length of iddata-record
           call 'CBL_THREAD_IDDATA_GET'   using iddata-ptr
                                                omitted
           set address of iddata-record to iddata-ptr
           move 'main' to iddata-name

      * Create sub-thread

           start 'SUBPROG '  identified by sub-handle

      * Wait until child creates its iddata and then flag
      * termination

           set sub-iddata-ptr to NULL
           perform until 1 = 0
               call 'CBL_THREAD_IDDATA_GET' using sub-iddata-ptr
                                            by value sub-handle
               if sub-iddata-ptr not = null
                   exit perform
               end-if
               call 'CBL_THREAD_YIELD'
           end-perform
           set address of iddata-record to sub-iddata-ptr
           move 1 to iddata-term

      * Wait until the child ends
           wait for sub-handle   *> clear up thread's resources

           display 'All synchronization is complete on ' &
                   'RTS termination'
           stop run.
       end program mainprog.

      *************** SUBPROG.CBL ************************

       identification division.
       program-id. subprog.

       Data Division.
       Working-Storage Section.
       01 sub-iddata.
          05 sub-name	          pic x(20) value 'sub'.
          05 sub-term	          pic x comp-x value 0.
       Local-Storage Section.
       01 iddata-ptr            usage pointer.
       01 thread-handle         usage pointer.
       01 thread-state          pic x(4) comp-x.
       01 parent-handle         usage pointer.
       Linkage Section.
       01 iddata-record.
          05 iddata-name        pic x(20).
          05 iddata-term        pic x comp-x value 0.
       Procedure Division.

      * Establish identification data - provide
      * initialization data
           call 'CBL_THREAD_IDDATA_ALLOC'
                                using sub-iddata
                                by value length of sub-iddata

      * Find our parent thread and resume him

           call 'CBL_THREAD_LIST_START'
                             using thread-handle
                                   thread-state
                                   iddata-ptr
           set parent-handle to NULL
           perform until thread-handle = null
                      or return-code not = 0
               if iddata-ptr not = null
                   set address of iddata-record  to iddata-ptr
                   if iddata-name = 'main'
                       set parent-handle to thread-handle
                       exit perform
                  end-if
               end-if
               call 'CBL_THREAD_LIST_NEXT' using thread-handle
                                                 thread-state
                                                 iddata-ptr
           end-perform
           call 'CBL_THREAD_LIST_END'
           if parent-handle = NULL
               display 'synchronization error'
               stop run
           end-if
           call 'CBL_THREAD_IDDATA_GET' using iddata-ptr
                                              omitted
           set address of iddata-record to iddata-ptr
           perform until iddata-term = 1
               call 'CBL_THREAD_YIELD'
           end-perform
           exit program.
       end program subprog.

This example establishes handshaking for thread and application termination. Note that this kind of handshaking could have been accomplished more easily by passing the handle of the main thread into the child as a parameter. This would have avoided the need to rely on identification data or to step through the thread list.

Consider the following points about this example:

  • Thread identification data is created in two ways:
    • In the parent thread, data is created uninitialized; the thread then retrieves the iddata pointer and initializes the area of memory that was allocated.
    • The child thread provides initialization data to eliminate any possible execution window between iddata allocation and iddata initialization by the application.

    The method you use in your application depends on what level of contention you expect on identification data.

  • The loop in the parent thread waits for the child to create its thread identification data; the loop in the child thread waits for the parent to flag termination. The call to CBL_THREAD_YIELD prevents these loops from being hard busy waits, but would have been better coded using an event or condition synchronization object. In unmanaged code, you could use CBL_THREAD_SUSPEND and CBL_THREAD_RESUME, alternatively.
  • The use of CBL_THREAD_LIST_n routines, which enable a thread to step through all threads known to the run-time system, obtaining the thread handle, thread state and identification data pointer. The example relies only on the handle and identification data pointer but the state information can also be useful, as it lets the calling thread know if the subject thread is detached, suspended or an other-language thread.

    If a thread uses the CBL_THREAD_LIST_n routines:

    • That thread is limited in which other CBL_THREAD_n routines it can use
    • Other threads cannot use any CBL_THREAD_n routines, and the use of some other library routines is restricted

    For this reason you should:

    • Mimimize the amount of code executed while stepping the list
    • Avoid file or user I/O while the list is locked

    These restrictions are removed only after list stepping is terminated by a call to CBL_THREAD_LIST_END.

Parent topic: Manipulating Threads


Threads in Other Languages

In a mixed language environment, threads created directly by operating system facilities and not by the START verb or the CBL_THREAD_CREATE routine have several restrictions and requirements on them:

  • They must be terminated by the approved operating system method of thread termination and not by any function in the CBL_THREAD_n routines (for example, CBL_THREAD_EXIT or CBL_THREAD_KILL).
  • Their handles are always created detached. This means that they cannot be waited on by the WAIT verb or by the CBL_THREAD_WAIT routine, and no return value is available from them.
  • They must issue the call cobthreadtidy() or cobtidy() when the thread or the application, respectively, no longer needs COBOL run-time system services. This allows the run-time system to free memory and clean up thread-state information.
  • cobtidy(), cobexit() or the COBOL STOP RUN statement will cause the calling thread to be treated as the 'main' thread. As a result, the run-time system will wait for all CBL_THREAD_CREATE threads to terminate before any run-time system cleanup processing is completed.
Note: All the multi-threading functions supported by the run-time system detect handles created by threads in other languages, and reports invalid use of them. It is, however, entirely up to the application to ensure that run-time system resources are freed for any thread that has executed any COBOL or run-time system code in the course of its existence (as detailed above).
Parent topic: Manipulating Threads


Canceling Called Programs

As the CANCEL operation takes a finite time to complete it is possible for a thread to enter the canceled module before the CANCEL operation has finished. You are advised, therefore, not to use the CANCEL statement in multi-threaded applications.

Parent topic: Writing Multi-threaded Applications


Optimizations and Programming Tips

To create optimized and efficient programs, note the following:

  • It is unsafe to modify or add environment variables in a threaded application on Linux systems. This is due to limitations of the underlying system libraries. It is however safe to read values from environment variables.
  • Always add code to your application that checks whether the application is running under the single-threaded or multi-threaded run-time system.
  • Use the NOREENTRANT and NOSERIAL Compiler directives (the default) wherever possible. This minimizes stack space and call entry overhead but it is up to the programmer to ensure that a program that uses these directives is only active in one thread at a time.
  • The use of the REENTRANT(1) Compiler directive increases stack space usage but does not significantly affect the call speed of the program.
  • The use of the SERIAL program attribute significantly affects the speed of calls but does not affect the stack space requirements of the program.
  • Use the Local-Storage Section to hold thread work variables. While this increases stack space requirements, the allocation of data is very fast.
  • Using the Thread-Local-Storage Section significantly effects call speed. Replacing the Working-Storage Section with the Thread-Local-Storage Section is an easy way to make some applications to be made entirely thread-safe.
  • Use mutexes for simple locking. These are the fastest of the synchronization structures.
  • Use monitors to provide maximum multi-threading in programs that might cause readers and writers based problems.
  • If possible, initialize all synchronization data items while in single-threaded execution. If this is not possible, then use a first time flag which is checked once before a CBL_THREAD_PROG_LOCK and checked again after obtaining the lock.
  • Remember the difference between a thread and a thread handle. Create a non-detached thread only if necessary.
  • Use CBL_THREAD_KILL only if absolutely necessary and if you do use it, terminate the run-unit as soon as possible afterwards. Where possible, use termination polling instead.
  • Use CBL_THREAD_SUSPEND in preference to CBL_THREAD_YIELD. Avoid busy waits.
  • Keep the amount of work done between CBL_THREAD_LIST_START and CBL_THREAD_LIST_END calls to a minimum.
  • In certain circumstances, the application can conserve per thread memory by using the CBL_TSTORE_n routines in preference to the Thread-Local-Storage Section.
  • Try to avoid deadlock rather than attempting to correct it once it has occurred.
  • Avoid nesting read locks on monitors and, if you must, then be aware of the possibility of single thread deadlock.

The Compiler directives available for multi-threaded applications can affect the performance of your multi-threaded and single-threaded applications.

Parent topic: Writing Multi-threaded Applications


Multi-threading Compiler Directives

Compiler directives you can use with multi-threading programs.

  • Directives for Serial and Reentrant Programs
  • Directives that Optimize Performance
Parent topic: Multi-threaded Programming
Related information
Introduction to multi-threading
Synchronizing Execution and Resolving Contention
Writing Multi-threaded Applications


Directives for Serial and Reentrant Programs

The following two directives effect the serialization and reentrancy of multi-threaded programs:

  • REENTRANT - Controls reentrancy of a program
  • SERIAL - Controls serialization of a program
Parent topic: Multi-threading Compiler Directives


Directives that Optimize Performance

The following Compiler directives can optimize the performance of multi-threading programs:

  • FASTCALL - Controls the behavior of a called program

The following directive settings are made by default:

  • PARAMCOUNTCHECK
  • NOFASTCALL
  • NOREENTRANT
  • NOSERIAL

If you want your program to be optimized for speed, set the directives as follows:

  • FASTCALL
  • NOREENTRANT
  • NOSERIAL

However, you might have to change your program to take advantage of these Compiler directives.

Parent topic: Multi-threading Compiler Directives


Performance Programming

There are many ways that an application can be configured in order to affect its performance, with the goal being to achieve the most optimized application at run time. By optimized, this usually means that the application executes more rapidly, or is capable of operating with less memory storage or using fewer resources, or that it draws less power from the CPU.

Generally, improvements in one of these elements can come at a cost to another - an application may be optimized to run quicker, but in doing so, may use more memory in the process. Carefully consider what you hope to achieve when optimizing your application, as it will affect the types of optimizations you will apply.

Often, the biggest effect on performance comes from having good algorithms or logic in your code, and using the correct data structures for those operations. Something as simple as ensuring that you use integer arithmetic (as opposed to floating point) can produce big gains in performance. The Optimizing COBOL Syntax and Optimizing PL/I Syntax sections demonstrate many good practices that will help you optimize your code.

Compilation is another area of an application that can be optimized. During the debug phase of your development, you are going to have certain diagnostics switched on, which will affect performance but are necessary to step through your code to debug it. When compiling your production version of the application, you will want to turn some, if not all, diagnostics off.

Tip: Whilst it is true that an application configured with diagnostics switched off will be more optimized, it may also be of benefit to run with some diagnostics switched on. This is so that unexpected problems can be investigated when they first occur. Diagnostics consume resources, and there is always contention between problem determination facilities and performance. You need to decide how important it is to be able to diagnose a problem the first time it occurs rather than having to try to recreate it or having to just turn on diagnostics and wait for it to re-occur.

When compiling your production version, it is also important to think about the platforms you are targeting. For example, if you are designing an application that runs on as many platforms as possible, that may stop you from taking advantage of specific CPU features that aid optimization.

Regardless of the level of optimization that you are looking for, you should benchmark your applications during the testing/implementation phase, so that you have a set of results from an application performing at an acceptable level with which to compare when you experience performance problems during production. Benchmarking results should be clearly recorded, including the details of the environment in which the application was run (for example: platform, directives set, any specific memory strategy in place).

  • Benchmarking your Application
    Before your application goes into live production, you should record metrics that show it performing to an acceptable level. These metrics can then be used later for troubleshooting performance issues.
  • Troubleshooting Performance Issues
    When your application is in a production environment and you discover it is not performing at the level it was when you recorded your benchmarking results, you need to perform a diagnosis to locate the problem.
  • Optimizing COBOL Syntax
    This section covers a range of techniques to streamline the general COBOL syntax.
  • Optimizing Other Areas
    This section covers other syntax and configuration optimizations that are particular to other areas or technologies of Visual COBOL.
Parent topic: Programming


Benchmarking your Application

During the design and development stages of your application, you should think about what constitutes acceptable performance when your application will be running in a production environment; for example, should the application:
  • provide the same performance as it did on a previous platform, or;
  • run at an acceptable speed when a certain number of users are active, or;
  • some other criteria.
As you develop your application, the Profiler utility is a useful tool to obtain detailed statistics on the run-time performance of your native COBOL programs. As you near the end of the development phase, use third-party applications (for example, perf on UNIX, or the in-built performance analysis tool in Visual COBOL on Windows) to produce detailed statistics on your application as a whole. Use the statistics that these tools produce as your benchmarking results. In addition, you should record the following:
  • The Compiler directives set on compilation.
  • The environment variables and switches present during run time.
  • The version and service pack of the operating system.
  • The processor type and memory (physical and virtual) available.
  • A list of other applications and programs running at the same time.
  • Virtual machine configuration details (if part of the setup).

All this information can be used as a comparison when troubleshooting performance issues that later arise.

Parent topic: Performance Programming
Related reference
IDE - Profiler Overview


Troubleshooting Performance Issues

When your application is in a production environment and you discover it is not performing at the level it was when you recorded your benchmarking results, you need to perform a diagnosis to locate the problem.
Visual COBOL provides a number of tools that can help troubleshoot performance issues:
The Profiler tool
Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program. If you used the Profiler during development, you can compare results, to pin-point potential bottlenecks.
The Consolidated Trace 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.

There is also a detailed guide Enterprise and COBOL Product Troubleshooting Guide, that can help you set recommended tracing levels and interpret diagnostics. This guide can be downloaded from the Support Resources section of the SupportLine web site (https://supportline.microfocus.com/).

Parent topic: Performance Programming
Related reference
IDE - Profiler Overview
The Consolidated Trace Facility


Optimizing COBOL Syntax

There are a range of techniques for maximizing the performance of your COBOL programs. As a general rule, the simpler the operation, the faster it executes and the smaller the compiled code.

There are a number of optimizations that you can take advantage of without being required to make extensive changes to your source code. A number of compiler directives are available that apply low-level optimizations as part of the compilation process. Most directives focus on optimizing specific facets of your code, and so you should check that they are suitable for your application before applying; but there are other directives, such as OPT, that offer performance gains that should be considered for most applications.

The following optimizations refer to native COBOL applications; for managed COBOL applications different considerations apply.

  • Optimizing Data Definitions
    Defining data items appropriately and aligning them to give the best performance.
  • Optimizing IF Statements
    Optimize IF statements by using a temporary field of a required size for the operation.
  • Optimizing Decimal Point Alignment
    Optimize operations on non-integer numbers by matching the decimal point alignment of the operands.
  • Optimizing Data Structures
    Defining a correctly aligned data structure as a TYPEDEF ensures the data structure is optimized each time it is reused.
  • Optimizing Table Handling
    Optimize subscripted table items by defining them as COMP-5 items of the smallest optimum size for the values involved, and use the BOUND directive only when debugging.
  • Optimizing PERFORM Statements
    PERFORM statements are generally very efficient, although you can increase their performance in a number of ways.
  • Optimizing CALL Statements
    When using the CALL statement, there are a number of ways to optimize the calling of the subprogram.
  • Optimizing Parameter Handling
    When calling a subprogram, there are a number of ways to optimize the parameters being passed.
  • Optimizing File Sorting
    Optimize your input and output procedures for file sorting to produce more efficient SORT operations.
  • Aligning Bit Data Items
    Alignment of bit data items occurs in certain situations, even when the ALIGNED clause is not specified.
  • Compiler Directives for Optimizing Code
    Compiler directives that can be used to optimize native code in a production environment.
  • Examples
Parent topic: Performance Programming


Optimizing Data Definitions

Defining data items appropriately and aligning them to give the best performance.

The performance of your program is affected by the data type, size and alignment of the data items. Using the correct data type increases efficiency, particularly in arithmetic operations.

Use COMP-5 or COMP-X numeric data items; preferably COMP-5 (where possible).

COMP-5 usage is defined for binary storage with the value stored in the native byte sequence of the processor. This makes it ideal for arithmetic efficiency. However, it is not suitable for data stored in files or passed to other machines over a network as the data is not accessible by programs running in an environment in which COMP-5 is stored in a different sequence. In these cases use COMP-X.

In managed code programs, some COBOL numeric fields are optimised to 32-bit or 64-bit binary fields, regardless of their definition in the COBOL source. For example, fields defined as DISPLAY or COMP-3 and that do not form part of a group may be stored as binary fields. The Compiler inserts code necessary to make the behaviour of these fields the same as if they had not been optimised.

The speed in which data items are processed varies according to the type of data item.

Addition and subtraction on non-integer data items is fastest if the items are COMP-5 and the decimal alignment is the same in both.

Mixing different data types in the same statement is less efficient than using the same data types throughout. The main exception to this is mixing COMP-5 and COMP-X items, where there is very little impact on performance.

Use only numeric items that occupy one, two, four or eight bytes of storage.

The fastest and smallest code is produced for operations on items that contain up to nine digits, or four bytes for binary items.

Operations on numeric items that contain more than nine digits, or more than four bytes for binary items, produce the slowest and largest code.

Align items on even-byte boundaries, in general.

Do not redefine COMP-5 items to access individual bytes. If access to individual bytes is required, use COMP-X.

Use edited items only when necessary.

  • Speed of Processing of Different Data Types
  • Aligning Data Items for Efficiency
Parent topic: Optimizing COBOL Syntax


Speed of Processing of Different Data Types

The following list shows the order of speed (fastest to slowest) of processing data of different types; this applies to any size of numeric integer data item.

  • COMP-5 Performance
  • COMP-X Performance
  • COMP Performance
  • COMP-3 Performance
  • DISPLAY Performance
Parent topic: Optimizing Data Definitions


COMP-5 Performance

Operations on COMP-5 data items are performed as true native binary operations. The fastest performance of COMP-5 is given using the Compiler directive COMP-5"2", which is the default.

Parent topic: Speed of Processing of Different Data Types
Related reference
COMP-5


COMP-X Performance

Operations on COMP-X data items are performed as binary operations. The data items are stored in COBOL order, which might not be the same as the native byte order.In this case, arithmetic on items longer than one byte involve operations to change the byte order before the arithmetic can be carried out. This results in slightly slower arithmetic than on COMP-5 items.

Parent topic: Speed of Processing of Different Data Types


COMP Performance

Operations on COMP data items, by default, work as defined in the ANSI standard. This results in truncation of the result of operations before it is stored in a COMP item. This generally results in slower arithmetic than on COMP-X data items. However, if the directives COMP and NOTRUNC are used when the program is compiled, operations on COMP items behave exactly like operations on COMP-X items.

Parent topic: Speed of Processing of Different Data Types


COMP-3 Performance

Arithmetic on COMP-3 data items is performed in packed decimal and is much slower than arithmetic on COMP items. It should be avoided.

Parent topic: Speed of Processing of Different Data Types


DISPLAY Performance

Arithmetic on DISPLAY items is much slower than arithmetic on COMP items, and should be avoided.

  • Arithmetic on DISPLAY items in intermediate code is faster than on COMP-3 items.
  • In generated code, arithmetic on display items can be optimized if the numeric value can be stored in an eight byte COMP-5 item.
Parent topic: Speed of Processing of Different Data Types


Aligning Data Items for Efficiency

Items should be aligned for maximum efficiency. The best alignment for data items depends on their size. Aligned data items can be handled more efficiently at machine code level; by default, the ALIGN directive will do this. See the table in the ALIGN directive for more information.

To ensure that all items in a table are correctly aligned, check that the size of an occurrence in the table is a multiple of two or four bytes as required. Pad the table as necessary. For example, in the following table, a three-byte filler has been added to each occurrence in the table to ensure that the numeric data item is always aligned on a four-byte boundary:

 01 a OCCURS 10.
     03 b PIC X(4) COMP-5
     03 c PIC X.
     03 filler PIC X(3).

You can use the REF Compiler directive to find out how data items are aligned.

Parent topic: Optimizing Data Definitions
Related reference
ALIGN


Optimizing IF Statements

The IF statement is designed to evaluate its result in a temporary field of the largest possible significance to hold the result. This temporary field might be of a larger significance than is actually required, causing the operation to be slower than it could be. The temporary field is stored in the target field with any necessary truncation. For example:

IF a + b < c

It is often better to define a temporary data item of the required size and use that to hold the result of the arithmetic, as follows:

MOVE a TO temp
ADD b TO temp
IF temp < c
Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing Decimal Point Alignment


Optimizing Decimal Point Alignment

Operations are fastest on integers, but operations on non-integer numbers are at their most efficient when the operands have matching decimal point alignment (that is, the number of decimal positions to the right of the implied decimal point). For example:

  • ADD and SUBTRACT operations are at their fastest when the source and target have the same decimal alignment.
  • MULTIPLY operations are at their fastest when the decimal alignment of the target is the sum of the alignments of the sources.
  • DIVIDE operations are at their fastest when the divisor has no fractional part and the dividend and the target have the same decimal alignment.
Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing IF Statements


Optimizing Data Structures

Use the TYPEDEF clause on a data structure to create a programmer-defined type definition. That definition can subsequently be referenced in the USAGE clause for other data structures.

By defining the structure once, and making sure it is properly aligned, you are ensuring consistent optimization throughout the program.

01 grp-acc-block TYPEDEF.
   03 p-title  pointer.
   03 i-code   pic x(4) comp-5.
   03 ch-state pic x(3).
   03          pic x.       *> table padded so stride = multiple of 4

01 dest-grp       grp-acc-block.
01 curr-dest-grp  grp-acc-block.
Parent topic: Optimizing COBOL Syntax
Related reference
The TYPEDEF Clause


Optimizing Table Handling

When defining tables, a subscript should be a COMP-5 item.

Subscripts for items that have the same stride and which are used in consecutive statements are optimized so that they are only evaluated once.

When you compile a program for use in production, use the NOBOUND directive. Use BOUND only when debugging. It causes code to be generated every time a subscript or index is used, to check that it is within the defined bounds of the table.

If you are using USAGE DISPLAY subscripts, the BOUNDOPT directive (also switched on by NOBOUND) can improve performance.

Access to tables defined with OCCURS ... DEPENDING is less efficient than access to tables of fixed size, and so should be avoided where high performance is needed.

Bound checking on a variable length table checks only if the subscript or index points outside the maximum length of the table. It does not take account of the table's current length (that is, the value of the item specified in the DEPENDING phrase).

Parent topic: Optimizing COBOL Syntax
Related reference
Example of Optimized Subscripts to Table Elements
BOUND
BOUNDOPT


Optimizing Conditional Statements

IF Statements

In IF statements, conditions within combined conditions are evaluated in the order in which they occur. Therefore, put the conditions that are most likely to produce a false result before others. Similarly, put those conditions that can be evaluated fastest before slower conditions.

Comparisons using EQUALS (=) or NOT EQUAL are faster than comparisons using GREATER (>) or LESS (<). In some systems, comparisons against binary zero are more efficient than against other literal values.

In both alphanumeric and numeric comparisons, make the source and target items the same size.

EVALUATE Statements

Avoid large EVALUATE statements. They are compiled into a series of IF ... ELSE IF ... statements where the value of the expression is derived separately for each WHEN clause.

Order an EVALUATE statement so that the most commonly satisfied condition is tried first. Do not use complex expressions or items defined in the Linkage Section as conditions in an EVALUATE statement; instead, include statements to calculate the value in an item defined in the Working-Storage Section and use that item in the EVALUATE statement.

Related reference
The IF Statement
The EVALUATE Statement
The GO TO Statement


Optimizing PERFORM Statements

PERFORM statements are generally very efficient, although you can increase their performance in a number of ways.

Using PERFORM statements is a very good way of keeping the size of your program down as well as giving it an easy-to-maintain structure. The following rules enable you to use PERFORM in the most efficient ways.

  • Put commonly used pieces of code in sections and perform them.

    Apart from being good coding practice, this saves space.

  • When you increment or decrement a counter, terminate it with a literal value rather than a value held in a data item. For example, to execute a loop n times, set the counter to n and then decrement the counter until it becomes zero, rather than incrementing the counter from zero to n.
  • Perform sections, not paragraphs. Put EXIT PROGRAM and STOP RUN statements at the end of the first (main) section.

    The range of an out-of-line PERFORM statement should not contain the end of another perform range. If it does, the program is said to trickle, that is execution is allowed to go past the end of a perform range. Applying the rule above ensures that this does not happen.

    For example, see Example of Inefficient Use of the Perform Statement for an example of bad practice.

  • Only use GO TO for paragraphs in the same section.
  • Do not use PERFORM ... THRU statements.
  • Do not use ALTER statements.
  • Code a STOP RUN statement immediately after CALL statements that you know execution will not return from; for example, calls to programs that will tidy up and terminate an application. This technique ensures that there is no trickle effect in execution and also enables the Compiler to produce better code, in terms of run-time performance and analysis.
Parent topic: Optimizing COBOL Syntax
Related reference
Example of Inefficient Use of the PERFORM Statement


Optimizing CALL Statements

When using the CALL statement, there are a number of ways to optimize the calling of the subprogram.

You can optimize CALL statements in the following ways:

  • Use a literal in a CALL statement rather than a data-name, so that the statement can be optimized. For example:
    CALL "myprog" USING

    is faster than:

    CALL program-name USING

    where program-name is a data item containing the value myprog.

  • In native code, calling using a procedure pointer is efficient. However, in .NET managed code, it is not.
  • Each CALL statement takes time, so try not to arbitrarily split a program into too many subprograms. On the other hand, small dynamically loadable programs make efficient use of memory, and may improve performance even though the calls themselves take time. In which case, use CALL and CANCEL to dynamically load the subprograms when they are needed. Note that cancelling a program does not, by default, free any memory.
  • CALL statements that do not alter the RETURN-CODE special register, or whose effect on RETURN-CODE are of no interest, should use a calling convention of 4. The Compiler directive DEFAULTCALLS can be used to set this globally.
  • Calls to the COBOL system library routines that carry out logical operations, such as CBL_AND, are optimized by the Compiler to actual machine logic operators, provided the parameters are eight bytes long or less and the length parameter is a literal value. These too should use a calling convention of 4.
  • Calls can be made faster by using call convention 256, which eliminates parameter-count checking on individual entry points.
  • Use call prototypes as a way of type-checking your sub-programs at compile time, instead of encountering them at run time. See About Call Prototypes for more information.
  • Code a STOP RUN statement immediately after CALL statements that you know execution will not return from; for example, calls to programs that will tidy up and terminate an application. This technique ensures that there is no trickle effect in execution and also enables the Compiler to produce better code, in terms of run-time performance and analysis.
Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing Parameter Handling
Call Conventions for Interfacing with Mixed Languages
Manipulating Bits
Mixed Language Programming
Calling COBOL Programs
DEFAULTCALLS
About Call Prototypes


Optimizing Parameter Handling

When calling a subprogram, there are a number of ways to optimize the parameters being passed.

You can optimize the way parameters are handled as follows:

  • Put the parameters in the CALL statement in the same order as their descriptions in the called program's Linkage Section.
  • Ensure that any Linkage Section items that are not referenced in the Procedure Division header appear after those that are referenced.
  • Avoid making many references to linkage items. These include items that are defined in the Linkage Section, items set to CBL_ALLOC_MEM allocated memory, and items defined as EXTERNAL.

It is always slower to access Linkage Section items than Working-Storage Section items. If a Linkage Section item is used frequently, it is faster to move it into a Working-Storage Section when the program is entered and move it back to the Linkage Section, if necessary, before returning to the calling program. Instead of the Linkage Section item, the Working-Storage Section item should then be accessed throughout the program.

If a linkage parameter is optional, you can detect its presence using a statement such as:
IF address of linkage-item NOT = null

However, this statement works only if the NOPARAMCOUNTCHECK Compiler directive is specified, and its construct is considered poor programming practice.

Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing CALL Statements
CBL ALLOC MEM
Linkage Section


Optimizing File Sorting

Inefficient input and output procedures can make the sort process appear to be very slow.

During a SORT operation, the more file I/O operations that can be processed in memory, the more efficient the SORT will be. Therefore, there are a number of environment variables that allow you to set the amount of memory allocated to a SORT operation: SORTSPACE, SORTTEMPSPACE, SORTTYPE, SORTCOMPRESS, and SORTSCHEME. Topics on these variables give certain guidelines on the levels that may produce the best performance, but experimenting with these settings yourself is advisable.

Parent topic: Optimizing COBOL Syntax
Related reference
SORTTYPE
SORTSPACE
SORTSCHEME
SORTTEMPSPACE
SORTCOMPRESS
The File Control Entry
The I-O-Control Paragraph
The SORT Statement


Aligning Bit Data Items

Alignment of elementary bit data items and bit group items within a record, when an ALIGNED clause is not specified, is at the next bit position in storage when that item is:

  • an elementary bit data item immediately following an elementary bit data item or bit group item of the same level
  • bit group item immediately following a bit group item or elementary bit data item of the same level

Alignment of elementary bit data items of level 1 or level 77 and a level 1 bit group are at the first bit of a byte.

Implicit filler bit positions are generated:

  • Following a bit data item within an alphanumeric group item, within a strongly-typed group item, or within a bit group item, as needed to advance alignment to a required natural boundary for the next item within that group. The filler bit positions are implicitly described as a filler elementary bit data item of the necessary number of bits and of the same level number as the next item within that group.
  • Following a bit data item that is the last data item in a record that is an alphanumeric group or strongly-typed group item, as needed to increase the number of bits to fill an integral number of characters. The filler bit positions are implicitly described as a filler elementary bit data item of the necessary number of bits with a level number the same as the highest hierarchical level of any bit data item superordinate to the last item, or, if there is no such superordinate item, the same as the level number of the last data item in the record.
    Note: No filler is generated at the end of a record that is entirely a bit group, at the end of a level 77 item, or at the end of a level 1 elementary item.

The alignment of the start of a group item and the alignment of the first item within that group, when the first item is a bit data item, are at the same bit position in storage.

Note: Using the SYNCHRONIZED clause has no effect on the alignment of any type of bit data items.
Parent topic: Optimizing COBOL Syntax


Compiler Directives for Optimizing Code

The following Compiler directives are recommended when optimizing your native code for a production environment. You should review the function of each directive to ensure it is suitable for your application. Some of the directives are set by default, but others you will need to set explicitly.

  • ALIGN"8 OPT"
  • NOALTER
  • NOBOUND
  • BOUNDOPT
  • NOCHECK
  • NOCHECKDIV
  • FASTCALL
  • LNKALIGN
  • LINKALIAS"none"
  • LITLINK
  • NOODOSLIDE
  • OPT"4" (Intel x86) OPT"3" (Non-Intel x86)
  • NOSEG
Parent topic: Optimizing COBOL Syntax
Related reference
ALIGN
ALTER
BOUND
BOUNDOPT
CHECK
CHECKDIV
FASTCALL
LNKALIGN
LINKALIAS
LITLINK
ODOSLIDE
OPT (Intel x86 platforms)
OPT (Non-Intel x86 platforms)
SEG


Examples

  • Example of Inefficient Use of the PERFORM Statement
  • Example of Optimized Subscripts to Table Elements
Parent topic: Optimizing COBOL Syntax


Example of Inefficient Use of the PERFORM Statement

An example of code that uses PERFORM in an inefficient way. This is also poor programming style.

 procedure division.
     perform a thru c
     perform b thru d
     stop run.
 a.
     display "a".
 b.
     display "b".
 c.
     display "c".
 d.
     display "d".
Parent topic: Examples
Related information
Optimizing PERFORM Statements


Example of Optimized Subscripts to Table Elements

The following code shows the use of optimized subscripts:

 01 a pic xx occurs 10.
 01 b pic xx occurs 10.
 01 c pic xx occurs 10.
 01 d pic xx occurs 10.
  ...
     move a(i) to b(i)
     if c(i) = d(i)
         display "pass"
     end if

The result would be that the subscript i would be evaluated only once, although it is used four times in two statements. The stride of each of these tables is the same: two.

Parent topic: Examples
Related information
Optimizing Table Handling


Optimizing Other Areas

This section covers other syntax and configuration optimizations that are particular to other areas or technologies of Visual COBOL.
  • Database Access
  • File Handling
Parent topic: Performance Programming


Database Access

Use the following utilities and directives in your database applications to optimize performance:
The OpenESQL Configuration Utility
Use the OpenESQL Configuration utility to change the default behavior for the SQL(BEHAVIOR) directive when it has not been set explicitly in the program source code, the project settings, or a COBOL Compiler directives file.
The OPTPER Compiler Directive
This directive enhances performance for CHARSET EBCDIC processing. See the OPTPER DB2 Compiler directive and OPTPER SQL Compiler directive topics for details.
Parent topic: Optimizing Other Areas
Related reference
OPTPER DB2 compiler directive option
OPTPER SQL compiler directive option
OpenESQL Embedded SQL Cursor Behavior and Performance
OpenESQL Config Utility for Default SQL Cursor Behavior


File Handling

There are a number of fundamental decisions that you should consider at the design phase of your application that can have an impact on your application's performance, such as the organization of your files and how you plan to access them.

Once you have the structure in place, how you plan to interact with your data can also have an effect. I/O operations can be optimized in the source code and also at run time by using a configuration file.

  • Design Considerations
    During the design phase of your application, there are a number of fundamental decisions that you should consider concerning file handling, as these can have a big effect on performance.
  • Optimizing File Selection
    When associating your program with a file, the SELECT statement contains certain clauses, depending on the file organization, that can improve the performance when accessing the specified file.
  • Optimizing Your Application Using the File Handler Configuration File
    There are a number of configuration options that you can set in the File Handler configuration file to optimize the performance of your file handling operations.
Parent topic: Optimizing Other Areas


Design Considerations

During the design phase of your application, there are a number of fundamental decisions that you should consider concerning file handling, as these can have a big effect on performance.

You should give some consideration to the following:

The location of the data files
If possible, you should store your files locally, as this will give you the fastest access times.
If the files are required to be on a network - for example, so multiple users can them - you should use Fileshare. Fileshare is also a potential solution if you store your files locally, as it provides extra functionality, such as transaction processing. For full details of Fileshare, see Fileshare Guide.
If you are using Fileshare, which protocol to use?
Fileshare is capable of using more than one type of network protocol when accessing files. If you have clients that are using different types of protocol to access the same file, swapping between these protocols affects performance; if possible, use the same protocol for all clients.
For Fileshare systems running locally (that is, server and client on the same machine), on Windows, the CCISMEM protocol is faster than CCITCP.
The choice of file organization
The choice of file organization has an influence on the performance, and so it is important that you choose the right organization for the tasks required to be carried out.
Sequential files can only be read in the order in which they were written, so do not suit situations where large files are required to be read frequently; however, they are a good option for creating print output files.
Relative files can be read sequentially, but random access also gives fast access to records using a key relative to the start of the file. A drawback is that deleted records still occupy disk space.
Indexed files can also provide sequential and random access. The use of primary and alternate keys allow more direct access to records.
For full details of each file organization, refer to File Organizations in the File Handling Guide section.
Parent topic: File Handling
Related reference
Fileshare Guide
Configuring CCI Communications for Fileshare
File Organizations


Optimizing File Selection

When associating your program with a file, the SELECT statement contains certain clauses, depending on the file organization, that can improve the performance when accessing the specified file.

If you are specifying indexed files, only specify alternate keys that you truly need, as each insert and delete operation on the file requires that the key is updated; specifying keys that go unused can cause unnecessary processing. If you do require complex key structures, with multiple alternate keys, processing the file under Fileshare can reduce some of the I/O processing usually required under normal file handling

Use the WITH DUPLICATES phrase in the ALTERNATE KEY clause for keys that have duplicate values. This technique saves disk space.

Use the SUPPRESS WHEN ALL clause for keys that should not be indexed, for example, if they contain all spaces. This can also save disk space.

Sharing and locking techniques are available through both the SELECT statement and the configuration file. Being able to access a file exclusively is the most efficient method performance-wise.

The SELECT statement can also specify the physical file implicitly or explicitly. If the file is specified implicitly, one or more search methods must be performed to locate the file; therefore, naming the file explicitly, if possible, is the most efficient method. If you cannot name the explicitly, there are other techniques, sometimes depending on how the file is opened, that can speed up the process (for example, the SEARCHONCREATE option). See Filename Mapping for more information.

Disk space can also be conserved in the File Control Description block by setting the record length to variable (as opposed to fixed). See Fixed-length and Variable-length Records for more information.

Parent topic: File Handling
Related reference
The File Control Entry
Alternate Keys
Duplicate Keys
Sparse Keys
Fixed-length and Variable-length Records


Optimizing Your Application Using the File Handler Configuration File

There are a number of configuration options that you can set in the File Handler configuration file to optimize the performance of your file handling operations.

These include:

INDEXCOUNT
You can increase the number of indexed file nodes that are cached, as opposed to being held on disk, using the INDEXCOUNT configuration option. An increase from the default (32) may further improve performance, but this will be at the expense of memory usage.
READSEMA

You can stop the File Handler from obtaining a semaphore when it executes an I/O operation that does not modify a shared file. In such a context, a semaphore is a lock applied to a reserved location in the file, which inhibits access to the file by more than one user. This extra call impairs performance. To stop the File Handler from obtaining a semaphore, ensure the READSEMA configuration option is OFF; this option is OFF by default.

LOCKTYPE & IGNORELOCK
Testing for the presence of record locks is expensive in terms of performance, and by default the File Handler:
  • Returns a locked-record file status when it finds a locked record, but also returns the data in the record area.
  • Tests for the presence of a file lock when it executes a read operation that does not request a lock.

You can adjust the use of record locks to eliminate this step by using either of the following configuration options:

  • LOCKTYPE. Set this to 1 to prevent access to locked records.
  • IGNORELOCK. Set this to ON to stop the File Handler testing for locks when it performs an I/O operation that is not itself trying to obtain a lock. If you set LOCKTYPE to 1, the setting of IGNORELOCK is irrelevant.
LOADONTOHEAP
You can force the File Handler to load an entire file into memory when it opens the file, and to execute all file operations in memory, only writing back to disk when the file is closed. Force this behavior by setting LOADONTOHEAP to ON. This setting is available only for non-shared files. Micro Focus recommends setting this option with care and only on small files.
DATACOMPRESS
Use DATACOMPRESS to enable or disable data compression on sequential or indexed files. It is disabled by default. There is also a Compiler directive of the same name, which enables you to set data compression on a file by file basis, by setting, and then unsetting, the directive before and after the SELECT statement of the required file.
SEQDATBUF
For sequential files, use SEQDATBUF to set the buffer size when accessing the file. Increasing the buffer size has shown to greatly increase performance.
Parent topic: File Handling
Related reference
INDEXCOUNT
READSEMA
LOCKTYPE
IGNORELOCK
LOADONTOHEAP
DATACOMPRESS
SEQDATBUF


Problem Determination and Diagnostic Tools

  • Protection Violations
  • The Consolidated Tracing Facility
    The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to produce diagnostic information of Micro Focus software components and your own programs.
  • Stack Dump Production
Parent topic: Programming


Protection Violations

  • Overview - 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.
  • Correcting Protection Violations
  • Debugging Techniques
Parent topic: Problem Determination and Diagnostic Tools


Overview - Protection 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: Overview - 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: Overview - 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: Overview - 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: Overview - 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

This section describes the techniques you use to debug an application when you encounter a protection violation or an RTS error. It covers working with both intermediate and generated code.

The techniques you use to debug a program 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
Related information
Correcting Protection Violations


The Consolidated Tracing Facility

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

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

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

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

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

  • The severity level of tracing messages to capture. See CTF Configuration File.
  • The emitters to produce the tracing information (such as text or binary). See Emitter List.
  • To Enable CTF Tracing
  • CTF Trace File Formats
  • Components Traced by CTF
  • Configuration File for CTF
  • Emitter List
  • Tracing Examples
Parent topic: Problem Determination and Diagnostic Tools
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:
    export MFTRACE_CONFIG=/home/usr/ctf/ctf.cfg
  2. Set the MFTRACE_LOGS environment variable to specify the location in which to create the CTF trace files. If MFTRACE_LOGS is not set, the current folder is used.
  3. Edit the configuration file to specify the information to trace, for example:
    mftrace.dest = binfile
mftrace.emitter.binfile#location  = /home/usr/logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true
    Note: If the location of the 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 a JVM environment, you can also configure CTF tracing by using an mfjvm.ctf file, ensuring it is stored on the program's classpath. The format of this file is the same as the ctf.cfg file and is typically used when tracing web applications is required.

You can ensure the file is on the classpath by:
  • Specifying the path name to the directory the file is stored in, using the standard JVM CLASSPATH system variable.
  • Placing it in the root of a .jar file that is itself on the classpath.
  • Placing it in the WEB-INF/classes directory of a web services .war file.
Note: If the MFTRACE_CONFIG variable is also set, that is used in preference to this method.
Parent topic: The Consolidated Tracing Facility


CTF Trace File Formats

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

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

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

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

  • Compressed format. Usually at least 50% the size of an equivalent text-format trace file.
  • No record format needs to be specified before tracing begins. All relevant information about a trace event is recorded, such as the process id, thread id, date, time, component id, event id, trace data and so on.
Parent topic: The Consolidated Tracing Facility
Related information
Example CTF Configuration Files
BINFILE Emitter Properties


Components Traced by CTF

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

  • mf.cci Properties
    This component provides CCI activity.
  • mf.esmq Properties
    This component provides calls to the WebSphere MQ XA switch module.
  • mf.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.rts Properties
    This component provides behavior of the run-time system.
Parent topic: The 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


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.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
region | true|false | Region operations
resource_locking | true|false | Region resource locking operations

Example

To trace the datastore and file handling operations, set the following in your CTF configuration file:

...
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.rts Properties

This component provides behavior of the run-time system.

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

no property
Event Level | Event ID | Event Description
INFO | 69 | Command Line
INFO | 70 | Add Program Context
INFO | 71 | Delete Program Context
INFO | 74 | Version Info
INFO | 128 | Start of run-time system initialization
INFO | 129 | End of run-time system initialization
INFO | 130 | Start of run-time system de-initialization
INFO | 131 | End of run-time system de-initialization
INFO | 132 | Entered a COBOL container
INFO | 133 | Exited a COBOL container
INFO | 134 | Link level entered
INFO | 135 | Link level exited
INFO | 136 | Memory validating
INFO | 137 | Memory validated
INFO | 138 | Run-Unit Created
INFO | 139 | Environment Exit
INFO | 254 | STOP RUN
ERROR | 246 | Shared memory error
ERROR | 255 | Run-time system error
ALL
Enables/disables all of the other properties.
API
This property is for .NET managed code only. API events:
Event Level | Event ID | Event Description
INFO | 56 | Entry to API.
INFO | 57 | Exit from API.
CONFIG
Run-time configuration event:
Event Level | Event ID | Event Description
INFO | 61 | Run-time configuration operation (e.g. cobconfig file location and entries).
CONTAINER
COBOL container events:
Event Level | Event ID | Event Description
DEBUG | 40 | Server initialization (start/finish)
DEBUG | 41 | Server de-initialization (start/finish)
DEBUG | 42 | Server context initialization (start/finish)
DEBUG | 43 | Server callback (start/finish)
DEBUG | 49 | Request handler function (start/finish)
INFO | 9 | Initializing environment for application running in the COBOL container (start/finish)
INFO | 10 | Invoking application in the COBOL container (start/finish)
INFO | 11 | Restoring initial state following the execution of an application in the COBOL container (start/finish)
INFO | 25 | Request handler trace event
INFO | 46 | Service lookup callback (start/finish)
ERROR | 0 | Request handler "start/next request" error
ERROR | 1 | Request handler "response" error
ERROR | 2 | Request handler "end processing" error
ERROR | 3 | Error loading the main program of the application identified by the request handler "start/next request"
ERROR | 4 | Error loading the package containing the application identified by the request handler "start/next request"
ERROR | 5 | Syncpoint failure
ERROR | 12 | Application termination due to exit from Debugger
ENV
Environment variable events:
Event Level | Event ID | Event Description
INFO and WARN | 60 | Environment variable operation
EXTERNAL
External data events.
Event Level | Event ID | Event Description
INFO | 26 | External data item created
INFO | 27 | External data item destroyed
ERROR | 28 | External data item size mismatch
FSYS
Low-level I/O level events:
Event Level | Event ID | Event Description
INFO | 52 | Entry to I/O function
INFO | 53 | Exit from I/O function
INFO | 54 | Specific I/O operation
MEMORY
Memory allocation and de-allocation events:
Event Level | Event ID | Event Description
INFO | 13 | Memory allocated
INFO | 14 | Memory freed
INFO | 15 | Memory re-allocated (resized)
INFO | 16 | Re-allocated memory freed
INFO | 17 | Memory remaining allocated at RTS termination
INFO | 67 | Memory Strategy
INFO | 68 | Memory Info
ERROR | 248 | Memory allocation failure
ERROR | 249 | Memory corruption detected. (See table below.)
For the above event ID's, the memory types for memory allocated by a user application are as follows:
Memory type | Allocation method
51, 52 | CBL_ALLOC_MEM (with flags=0), or CBL_ALLOC_DYN_MEM (with flags=0)
55, 56 | CBL_ALLOC_MEM (with flags=8), or CBL_ALLOC_THREAD_MEM (with flags=0)
59, 60 | CBL_ALLOC_MEM (with flags=4), CBL_ALLOC_DYN_MEM (with flags=4), or CICS GETMAIN
63, 64 | CBL_ALLOC_MEM (with flags=12) or CBL_ALLOC_THREAD_MEM (with flags=4)
All other memory types are internal and used by the Micro Focus system.
In addition, for event ID 249, the stomp type is supplied, which is a category indicating how memory has been determined to be corrupted:
Stomp type | Reason | Description
0 | Run-In (Header) | Leading check bytes before header overwritten
1 | Run-Out (User Data) | Trailing check bytes after user data overwritten
2 | Bad Header | Corruption of memory header detected
3 | Freed Overwrite | Previously freed data has been overwritten
4 | Bad Header | User Unable to determine header start address
5 | Failed OS Check | Validation of OS memory heap failed
6 | Run-In (User Data) | Leading check bytes before user data overwritten
7 | Bad Track Data | Leading check bytes in track data overwritten
8 | Bad Link | Corruption of keyed data link
MFENTMAP
Entry Point Mapper event:
Event Level | Event ID | Event Description
INFO | 55 | Entry Point Mapper function
MFPM
Mainframe Pointer Manager events (AMODE programs):
Event Level | Event ID | Event Description
INFO | 29 | Absolute memory registration
INFO | 30 | External data registration
INFO | 31 | Memory registration
INFO | 32 | Working-storage memory registration
INFO | 33 | External data de-registration
INFO | 34 | Memory de-registration
INFO | 35 | Working-storage memory de-registration
INFO | 36 | Local-storage memory registration
INFO | 37 | Local-storage memory de-registration
ERROR | 250 | MFPM error.
PGM
User program entry, exit, chain, and link events:
Event Level | Event ID | Event Description
INFO | 6 | Program entry
INFO | 7 | Program exit
INFO | 8 | Program chain
INFO | 18 | Program link
INFO | 140 | Section Entered
INFO | 141 | Section Exited
PGMLOAD
Program load events:
Event Level | Event ID | Event Description
DEBUG | 50 | Subsystem function
INFO | 19 | .int or .gnt program load
INFO | 20 | Logical cancel
INFO | 21 | Physical cancel
INFO | 22 | Logical canceled program made live again
INFO | 23 | DLL or shared object load
INFO | 24 | DLL or shared object unload
INFO | 38 | .lbr load
INFO | 39 | .lbr unload
ERROR | 251 | Program load error
PGMSEARCH
Program searcher events:
Event Level | Event ID | Event Description
DEBUG | 58 | Entry to program searcher.
DEBUG | 59 | Exit from program searcher.
PROCESS
Process events:
Event Level | Event ID | Event Description
INFO | 63 | Execute Process
INFO | 64 | Wait On Process
DEBUG | 73 | Run-Unit resource handling
SIGNAL
Signal handling events:
Event Level | Event ID | Event Description
INFO | 247 | Signal Signinfo
ERROR | 252 | Apply previously ‘held’ signal
ERROR | 253 | Signal caught
SYSPGM
System program entry, exit, chain, and link events:
Event Level | Event ID | Event Description
INFO | 6 | Program entry
INFO | 7 | Program exit
INFO | 8 | Program chain
INFO | 18 | Program link
INFO | 140 | Section entered
INFO | 141 | Section exited
THREAD
Threading and synchronization events:
Event Level | Event ID | Event Description
INFO | 56 | Entry to API (Threading and synchronization APIs)
INFO | 57 | Exit from API (Threading and synchronization APIs)
INFO | 142 | Thread status
INFO | 143 | Thread killed
Parent topic: Components Traced by CTF
Related reference
mftrace.comp.component-name#property
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


Configuration File for CTF

You can configure the behavior of CTF using the CTF configuration file ctf.cfg, whose location is set in the MFTRACE_CONFIG environment variable.

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

You can use the following entries in configuration files:

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


mftrace.application

Restricts tracing to a specific application.

Syntax:

mftrace.application=executable-name

Parameters:

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

Specifies the time standard to use when time stamping CTF trace files.

Syntax:

mftrace.time=time-type

Parameters:

time-type
One of:
UTC
Coordinated Universal Time (UTC) is used to time stamp the CTF trace files.
local
The local time is used to time stamp the CTF trace files.

Default:

mftrace.time=local.

Comments:

On UNIX platforms, set mftrace.time=UTC if you are expecting signals to occur during the run of your application.

Examples:

To time stamp your CTF trace files with the UTC time:

...
mftrace.time=UTC
...

To time stamp your CTF trace files with the local time:

...
mftrace.time=local
...
Parent topic: Configuration File for CTF
Related information
Components Traced by CTF


Example CTF Configuration Files

Example ctf.cfg file 1

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

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

Example ctf.cfg file 2

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

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

where:

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


Emitter List

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

  • BINFILE Emitter Properties
    Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.
  • JAVALOGGER Emitter Properties
    Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.
  • TEXTFILE Emitter Properties
    Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.
Parent topic: The Consolidated Tracing Facility


BINFILE Emitter Properties

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

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

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

mftrace.dest = BINFILE

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

Property | Description | Default
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "cobrun".
$(EMITTER)
Always "BINFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).ctb, or $(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the BINFILE emitter is being used to output trace events for cobrun executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called cobrun.binfile.3456.ctb .
  • If the binfile emitter is being used to output trace events for myapp executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.binfile.1975.ctb_1, myapp.binfile.1975.ctb_2, and myapp.binfile.1975.ctb_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
LOCATION The folder where the trace files are to be written. The folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.

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

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

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
Rununitid | Controls whether the RunUnit information is included in the trace. | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).ctb

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the BINFILE emitter is not available.

Parent topic: Emitter List
Related information
Example CTF Configuration Files
CTF Trace File Formats


JAVALOGGER Emitter Properties

Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.

Use this type of emitter if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

Add the required properties for the JAVALOGGER emitter to the mfjvm.ctf configuration file:

Property Description Default
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warn
  • 3: error
  • 4: fatal
Note: See Comments below.
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)

Comments:

The tracing levels set by $(LEVEL) map to the following levels used in the Java logging API:

Micro Focus tracing levels | Java logging API tracing levels
Debug | Config
Info | Info
Warn | Warning
Error | Severe
Fatal | Severe

Refer to your Java logging API documentation for the details traced for each level.

Parent topic: Emitter List


TEXTFILE Emitter Properties

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

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

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "cobrun".
$(EMITTER)
Always "TEXTFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).log, or $(APPNAME).$(EMITTER).$(PID).log_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the TEXTFILE emitter is being used to output trace events for cobrun executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called cobrun.textfile.3456.log .
  • If the TEXTFILE emitter is being used to output trace events for myapp executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.textfile.1975.log_1, myapp.textfile.1975.log_2, and myapp.textfile.1975.log_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)
HEXBLOCKSIZE The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
 8
LOCATION The folder where the trace files are to be written.

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

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

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).log

When a JVM COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the TEXTFILE emitter is not available.

Parent topic: Emitter List


Tracing Examples

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

export MFTRACE_CONFIG=/home/mydir/ctf.cfg

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

mftrace.level=error

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

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

mymain.cbl:

       identification division.
       program-id. mymain.
       environment division.
       data division.
       working-storage section.
       01 my-var pic 9(9) external.
       procedure division.
       move 1 to my-var
       perform 5 times
         call 'mysub'
         add 1 to my-var
       end-perform

      cancel 'mysub'

      call 'myprog'
      goback.

mysub.cbl:

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

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

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

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

mftrace.level=info

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

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

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

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

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

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

The entries marked 1> and 2> show event type 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:

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

The entries marked 1> and 2> in the above excerpt show the start and end of the additional entries for an external data item.

Parent topic: The Consolidated Tracing Facility
Related information
To enable CTF tracing


Stack Dump Production

Restriction: This only applies to the following platforms: Linux Intel 64-bit, Solaris Intel 64-bit, and Linux/390.

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. Managed 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: Problem Determination and Diagnostic Tools
Related reference
stackdump_on_error
stackdump_filename
Run-time Tunables


To Produce a Stackdump File

Restriction: This only applies to the following platforms: Linux Intel 64-bit, Solaris Intel 64-bit, and Linux/390.

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.

Parent topic: Stack Dump Production
Related reference
stackdump_on_error
stackdump_filename
Run-time Tunables


Unit Testing from the Command Line

For native COBOL applications and procedural applications compiled as JVM COBOL, you can create, compile, run and debug unit tests from the command line.

The command line version includes much of the architecture you would expect of an xUnit framework. The test runner is a 32- or 64-bit executable that runs a test suite, which is a COBOL program compiled to .dll that includes the test case logic, and optionally, any supporting code that controls the environment the test is run within.

If your test run encounters failures, you can choose to invoke a just-in-time debugger, create a core dump file, or simply continue the test run.

The results of a test run are available in a number of formats. By default, results are displayed to screen and to a .txt file, but you can use additional parameters to produce reports in markdown format (compatible with GitHub), or format. You can package the reports if you have a number of related test suites, and then integrate them into your third-party testing and development applications, for example, Micro Focus Silk Central, or a Jenkins CI server.

  • Writing Tests
    Code your testing logic into a test case, and include optional setup and teardown code, to create a test fixture. You can code more than one test fixture in the same COBOL program to create a test suite.
  • Compiling Tests
    To create a test fixture, you must compile the COBOL program to a .so or .jar (JVM COBOL) file.
  • Running Tests
    Tests are run from the shell prompt.
  • Viewing Test Results
    Results of a test run can be displayed to screen and text file. A test run can also produce a JUnit-style format, which can be utilized in third party applications.
  • Dealing with Errors in Your Tests
    As your tests run, you can invoke a just-in-time debugger or generate a core dump file when it encounters an error.
Parent topic: Programming


Writing Tests

To test elements of your procedural COBOL application, you need to code the testing logic in a test case.

A self-contained unit test is a single COBOL program that includes the test case and the data to be tested. Special entry points in your unit test enable you to set up the data and testing environment (the setup), include the testing logic, and then tidy it up again after the test has run (the teardown). These three elements together make up a test fixture.

This section includes a simple test fixture that demonstrates a complete self-contained unit test, which uses the copybook, mfunit.cpy (supplied with your installation of Visual COBOL) to resolve to the correct entry point names that the test runner will recognize. For details of the test fixture syntax, see Elements of a Test Fixture.

If you have related test cases, you can include these in the same COBOL program, each with their own test setup and teardown. COBOL programs that contain more than one test case are referred to as test suites.

You may also write unit tests where the testing logic is completely separate from the data and testing environment (that is, in separate programs). This section also contains an advanced example that demonstrates this technique.

  • Elements of a Test Fixture
    There are a number of elements that you can code to produce a working unit test.
  • JCL Unit Tests
    There are two types of JCL unit test that you can run: a simple unit test that tests the validity of a JCL job card, and a more complex unit test that can query the job output to make test assertions.
  • Data-Driven Unit Tests
    Data-driven tests are a type of test suited to testing data where values read from a source are passed through the same tests.
  • Using Dynamic Metadata
    You can add metadata about a test case in your source code.
  • Determining a Test Outcome
    When coding test assertions within your test cases, there are library routines available to enable you to generate failing messages. Setting a non-zero return code also indicate a test failure.
  • Examples - Writing Tests
    You can write unit tests as self-contained single COBOL programs, or can separate the elements (the testing logic and the data) into programs and sub-programs; this section contains examples of both.
Parent topic: Unit Testing from the Command Line


Elements of a Test Fixture

The elements of a complete test fixture are coded as entry points in a COBOL program. The entry points shown in the code snippets below are using call prototypes found in the mfunit.cpy copybook, available from the cpylib folder of your product installation directory.

Note: If you are unable to use the copybook, due to its level-78 items, which are not supported with mainframe dialects, you must specify the following entry point names:
Element | Entry point
test setup | MFUS_test_case_name
test metadata setup | MFUM_test_case_name
test case | MFUT_test_case_name
test teardown | MFUE_test_case_name
global metadata | MFUGM_program_name
global command line arguments | MFUGA_CMDOptions

The main elements are:

The test setup
Any pre-requisite conditions that need to be satisfied before the test case is run can be set up in this section. For example, if the test case requires that a data file already exists or is open ready for input, you can code such things in this section. This section is optional.
...
entry MFU-TC-SETUP-PREFIX & "MyTestCase"
//initial setup code goes here//
goback
...
The test metadata setup
There are a number of metadata details that you add directly through your source code that can relate to a single test case, such as test description and test timeout; see Using Dynamic Metadata. For data-driven tests, this section must at least contain the MFU-MD-TESTDATA metadata declaration; for all other test types, this section is optional.
...
entry MFU-TC-METADATA-SETUP-PREFIX & "MyTestCase"
//initial metadata setup code goes here//
goback
...
The test case
This section contains the actual testing logic and test assertions.
...
entry MFU-TC-PREFIX & "MyTestCase"
//test case code goes here//
goback
...
The test teardown
This section enables you to tidy up the environment, such as releasing or closing resources, after the test has been run. This may be critical if you run multiple test cases within a test suite. This section is optional.
...
entry MFU-TC-TEARDOWN-PREFIX & "MyTestCase"
//clean-up code goes here//
goback
...

If you have multiple test cases, each must have their own setup and teardown. COBOL programs that contain more than one test fixture are commonly referred to as test suites.

These sections can appear in your code in any order, but are run in the order shown here.

There are also other elements that affect a test case, either by applying a number of attributes (metadata) to the test cases, or setting command line options for the test run:

The global command line options
You can add test runner command line arguments within the MFU-GLOBAL-COMMANDLINE-PREFIX entry point. The arguments should be set in the COBOL variable MFU-GLOBAL-COMMANDLINE-ARG, which is available through the mfunit.cpy copybook. This section is optional.
...
entry MFU-GLOBAL-COMMANDLINE-PREFIX & "MyProgramName"
//global command line arguments here//
//for example: move "-verbose -high-res-timer:true -report:markdown to MFU-GLOBAL-COMMANDLINE-ARG
goback
...
See Examples of Using Metadata for a more comprehensive example of using this entry point.
The global metadata setup
There are a number of metadata details that you add directly through your source code that can relate to all test cases within the test fixture. For example, you can add a trait to all test case in the test fixture file. This section is optional.
...
entry MFU-GLOBAL-METADATA-PREFIX & "CMDOptions"
//global metadata is set up here//
goback
...
Note: You can specify any literal name within parentheses in place of "CMDOptions".
See Examples of Using Metadata for a more comprehensive example of using this entry point.
Parent topic: Writing Tests


JCL Unit Tests

There are two types of JCL unit test that you can run: a simple unit test that tests the validity of a JCL job card, and a more complex unit test that can query the job output to make test assertions.

The simple, JCL-only unit tests determine whether a JCL job card can successfully be submitted to a particular enterprise server region. There is no separate test code written for this type of test; you simply specify the existing job card (.jcl file) with the relevant -es-* options on the command line. The job is actually submitted to the JES queue, and then depending on the result, a return code is generated and the result of the test is determined.

The second type of test combines COBOL and JCL syntax. It enables you to submit the JCL job card to an enterprise server region, but this time it is done under the control of a COBOL unit test program. The job details can be captured, and then queried within the unit test program to make test assertions. See Using Dynamic Metadata for a list of MFU-MD-JCL-* fields that can be used in the processing of the JCL output.

The Examples topic contains the required command line syntax to run both types of test. Also, source files for running the second type of test are supplied with your product; see JCL Test Case Example for details on how to compile and run it.

Parent topic: Writing Tests


Data-Driven Unit Tests

Data-driven tests are a type of test suited to testing data where values read from a source are passed through the same tests.

The Micro Focus Unit Testing Framework supports data-driven tests when connecting to data sources in comma separated values (CSV) format.

You can incorporate a data source into your traditional unit tests by specifying a data source descriptor, MFU-MD-TESTDATA, in the metadata entry point; for example:

ENTRY "MFUM_MYTESTCASE".
   move "csv:MyCSVSource.csv" to MFU-MD-TESTDATA.
When the test case is executed, it runs once for each row of selected data within the data source. It is possible to control which rows are tested by using a filtering condition to select rows based on one of its column values, by using the MFU-MD-DD-CSV-FILT-COND metadata; for example:
move "Surname = Jones" to MFU-MD-DD-CSV-FILT-COND
You can also selectively run the test case against a single row within the source if you are using the -csv-line-filter option from the command line test runner syntax.

To use the data in your test cases, you define external COBOL items in the Working Storage that correspond to the column headers; for example, to define and use data in a column titled EarnedPoints, define the COBOL item as such:

01 mfu-dd-EarnedPoints is MFU-DD-VALUE external.

You can then use the item in your source code as you would any other data item.

Refer to the Examples - Writing Tests section for a working example of a data-driven test.

Parent topic: Writing Tests


Using Dynamic Metadata

You can add metadata about a test case in your source code.

The Micro Focus Unit Testing Framework contains a number of COBOL fields within the mfunit.cpy copybook that enable you to add metadata to your test cases.

For metadata relating to a particular test case, set the COBOL fields within the MFU-TC-METADATA-SETUP-PREFIX & test-case-name entry point. (If you are unable to use level 78 constants, use the "MFUM_test-case-name" entry point name instead.) This entry point is called during the preparation stage of the test case.

For metadata relating to all test cases in your test suite, set the COBOL fields within the MFU-GLOBAL-METADATA-PREFIX & program-name entry point. (If you are unable to use level 78 constants, use the "MFUGM_program-name" entry point name instead.) This entry point is called before any of the test cases.

If you generate a test fixture file (.mfu file) from the test suite, you can see the metadata within the test cases, and in the [global] section.

Use the following COBOL fields to populate your test case-specific and global metadata entry points:

COBOL field | Description | Tag in the test fixture .mfu file
MFU-MD-TESTCASE-DESCRIPTION | Test case description | description
MFU-MD-TIMEOUT-IN-MS
The time limit (in ms) in which the test case should run. A non-zero return code is returned if the timeout is reached. The timeout must be set to at least 3 seconds.
Note: If a test uses a timeout, it must be run using one of the threaded test runners (cobmfurun32_t or cobmfurun64_t).
timeout
MFU-MD-TRAITS Test case traits. You can run test cases based on the trait; any tests that are not assigned the specified trait are skipped during the test run.
Tip: You can add more than one trait, delimited by a comma, if required.
traits
MFU-MD-SKIP-TESTCASE | Skip test case | skipped
MFU-MD-TESTCASE-PRIORITY Give priority to a test case. Permissible values are:
  • MFU-MD-TESTCASE-PRIORITY-HIGH
  • MFU-MD-TESTCASE-PRIORITY-MEDIUM
  • MFU-MD-TESTCASE-PRIORITY-LOW
Note: Any test cases that do not have a priority specified are run after all prioritized test cases have run.
priority
MFU-GLOBAL-COMMANDLINE-ARG Applies test runner arguments to the test run. Use this field in the MFU-GLOBAL-COMMANDLINE-PREFIX entry point.
Note: The length of this field is limited to 128 characters.
various
MFU-MD-TESTDATA Applies to data-driven tests. This option enables you to specify a data source for your data-driven tests. (Currently, only data sources in comma separated values format are supported.)

For example:

move "csv:payroll.csv" to MFU-MD-TESTDATA

data-source
MFU-MD-DD-CSV-FILT-COND Applies to data-driven tests. This option enables you to filter the data from the data source that is used in your test case. Specify a condition to select or ignore rows of data in the source.

For example:

move "column_name condition data-value" to MFU-MD-DD-CSV-FILT-COND

where:

column_name
The name of a column header in your data source.
condition
Can be one of:
  • =
  • !=
  • contains
  • !contains
data-value
The value on which to base the filter.
ds-csv-filter-condition
MFU-MD-DD-DSV Applies to data-driven tests. This option enables you to specify the separator in the data file. (By default, the separator is a comma.)

For example, to use a semi colon:

move ";" to MFU-MD-DD-DSV

ds-csv-separator
MFU-MD-JCL-FILE-NAME | The file name of the JCL job card to be submitted. | jcl-filename
MFU-MD-JCL-COND-TYPE | The reason that the job ended.
MFU-MD-JCL-COND-CODE | The resulting return code of the job.
MFU-MD-JCL-JOB-NBR | The JCL job number.
MFU-MD-JCL-TESTCASE-PASSED The metadata that determines if the test case has passed or failed. Set to true to mark the test as passed, and false to mark it failed.

For example:

set MFU-MD-JCL-TESTCASE-PASSED to true
MFU-MD-JCL-COPY-DD

Generates output files on the running and results of a JCL job. If you want to make test assertions on the job, this metadata is mandatory. The default is true.

See JCL Test Case Example for an example of how to use the output in your tests.

es-show-dd
MFU-MD-JCL-FLUSH-JOB | Determines if the completed job is flushed from the spool queue. Set to true to flush it on completion of the test, or false to retain the job within the queue. | es-flush-job
  • Examples of using Metadata
Parent topic: Writing Tests


Examples of using Metadata

The following excerpts show examples of how you can use dynamic metadata in your test code.

Configuring command line arguments

The following excerpt demonstrates how you can apply a conditional command line argument to your test run, based on the type of compiled file used to create the test fixture file or executable. By moving the appropriate -report value to the MFU-GLOBAL-COMMANDLINE-ARG variable, the appropriate report will be generated.

...
entry MFU-GLOBAL-COMMANDLINE-PREFIX & "CMDOPT".

       $if ilgen set
         $if nojvmgen set
            move "-verbose -high-res-timer:true -report:nunit" to MFU-GLOBAL-COMMANDLINE-ARG
        $else
           move "-verbose -high-res-timer:true -report:junit" to MFU-GLOBAL-COMMANDLINE-ARG
        $end
       $else
           move "-verbose -high-res-timer:true -report:markdown" to MFU-GLOBAL-COMMANDLINE-ARG
       $end
        goback
...

Configuring global metadata

The following excerpt demonstrates metadata being applied to all test cases in the test run. In this example, all test cases in the file TestRunName will be assigned the trait of 'fulltest'.

...
entry MFU-GLOBAL-METADATA-PREFIX & "TestRunName".
    move "fulltest" to MFU-MD-TRAITS
    goback
...

Configuring specific test case metadata

The following excerpt demonstrates metadata that can be applied to an individual test case. In this example, a number of details are added to the test case 'TestCase1'.

...
entry MFU-TC-METADATA-SETUP-PREFIX & "TestCase1".
           move "This is an example of a dynamic description" to MFU-MD-TESTCASE-DESCRIPTION
           move 3000 to MFU-MD-TIMEOUT-IN-MS
           move "smoke" to MFU-MD-TRAITS
           set MFU-MD-SKIP-TESTCASE to false
           move MFU-MD-TESTCASE-PRIORITY-LOW to MFU-MD-TESTCASE-PRIORITY
           goback.
...

Configuring a JCL unit test

The following excerpt demonstrates some of the environmental setup required to run a JCL unit test. The MFU-MD-JCL-FILE-NAME metadata specifies the JCL job card to be submitted, and the MFU-MD-JCL-COPY-DD metadata ensures that any JCL output from the job is saved to a text file, which can then be queried when making your test assertions. The MFU-MD-JCL-FLUSH-JOB metadata removes the job created by the test from your JES queues; this metadata is not mandatory. The other elements required to running a JCL test (the enterprise server region and the catalog) are specified on the command line.

...
entry "MFUM_TXTDIFF1".
   move "txtdiff.jcl" to MFU-MD-JCL-FILE-NAME
   move "COBOL/JCL Unit Test" to MFU-MD-TESTCASE-DESCRIPTION
   set MFU-MD-JCL-COPY-DD to true
   set MFU-MD-JCL-FLUSH-JOB to true
   goback.
...

Configuring a data source for a data-driven test

The following excerpt demonstrates how to configure a data source for your data-driven tests. In this example, the TestCSV test case will use the FrequentFlyer.csv data source. The separator used within the file is ';' (and not the default, comma). Each test case is run a number of times: once for each selected line within the file. In this instance, any line that has does not have a value of Platinum in the InitialStatus column is omitted.

...
entry MFU-TC-METADATA-SETUP-PREFIX & "TestCSV".
           move "This is an example of a data driven test" to MFU-MD-TESTCASE-DESCRIPTION
           move "csv:FrequentFlyer.csv" to MFU-MD-TESTDATA
           move "InitialStatus != Platinum" to MFU-MD-DD-CSV-FILT-COND
              move ";" to MFU-MD-DD-DSV
           goback.
...
Parent topic: Using Dynamic Metadata


Determining a Test Outcome

Failing COBOL syntax within a test case causes the test to fail and displays the standard COBOL error messaging in the test case summary, within the test output.

To control the outcome of a test case, you can place assertions within your test code that determine a failing or successful test. You can manually set a non-zero return code to mark a test as failed, or you can conditionally call one of the following library routines:

MFU_ASSERT_FAIL
Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report.
MFU_ASSERT_FAIL_Z
Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report.
MFUFMSG
Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report. (Mainframe dialects.)
MFUFMSGZ
Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report. (Mainframe dialects.)

These all mark the test as failed, and enable you to include user-defined messages within a test report.

To use these library routines, ensure that your test cases can access the mfunit_prototypes.cpy copybook. This copybook is supplied in the cpylib sub-directory of your installation directory, and is used for call prototyping when you call any of the above library routines.

Test cases that run to completion without any of the above occurring or are coded to return a return code of zero are considered to have passed.

Parent topic: Writing Tests


Examples - Writing Tests

You can write unit tests as self-contained single COBOL programs, or can separate the elements (the testing logic and the data) into programs and sub-programs; this section contains examples of both.
Your Visual COBOL installation also ships with a number of sample test suites that demonstrate a number of capabilities of the Micro Focus Unit Testing Framework. These samples are installed in the mfunit directory, located at $COBDIR/demo.
  • Simple Test Case Example
    An example unit test that uses a complete COBOL program as the self-contained test fixture; it contains the test case logic and the data to be tested (including the setup and teardown of the test environment).
  • Advanced Test Case Example
    An example unit test that uses one COBOL program as the test case, which tests data that is contained within a sub-program.
  • JCL Test Case Example
    An example unit test that can interpret the job return code of a JCL job submitted to an enterprise server region.
  • Data-Driven Test Case Example
    An example unit test that reads an external data source and passes values through a simple test, once for each line of data read.
Parent topic: Writing Tests


Simple Test Case Example

An example unit test that uses a complete COBOL program as the self-contained test fixture; it contains the test case logic and the data to be tested (including the setup and teardown of the test environment).

The following example tests if a file can be written to. If there is a problem writing to the file (for example, the file does not exist or is locked), the test will fail.

Compile the program to .so (see Compiling Tests), then run the resulting test suite (see Running Tests).

      $set case
       program-id. TestCases.
       environment division.
       input-output section.
       file-control.
       select cust assign to 'cust.txt'
         organization is line sequential.
       data division.
       file section.
       fd cust.
       01 cust-file.
          03 customer-id    pic 9(5).
          03 customer-info  pic x(65).

       working-storage section.
       copy "mfunit.cpy".
       procedure division.
       goback.

       entry MFU-TC-PREFIX & "FullTestCase".    *> the test case
       move 0 to customer-id
       perform 100 times
        add 1 to customer-id
        move "A customer" to customer-info
        write cust-file
       end-perform
       goback.

       entry MFU-TC-SETUP-PREFIX & "FullTestCase".  *> the test case setup
       open output cust
       goback

       entry MFU-TC-TEARDOWN-PREFIX & "FullTestCase". *> the test case teardown
       close cust
       goback

       end program.
Parent topic: Examples - Writing Tests


Advanced Test Case Example

An example unit test that uses one COBOL program as the test case, which tests data that is contained within a sub-program.

The first sample listed below is a complete test case; the second example is the sub-program containing the data that the test case uses.

Ensuring that DATECHK.CBL is in the same directory as the test case, compile MFUT_DATECHK.CBL to .so (see Compiling Tests), then run the resulting test suite (see Running Tests).

      $set case
      $set nestcall ans85
       copy "mfunit_prototypes.cpy".

      ****************************************************************
      *                                                              *
      *                      MFUT_DATECHK.CBL                        *
      *                                                              *
      * MFUT_DATECHK is a test program for the subprogram "DATECHK". *
      *                                                              *
      ****************************************************************

       identification division.
       program-id. MFUT_DATECHK.
       environment division.
       configuration section.
       data division.
       working-storage section.
       copy "mfunit.cpy".
       01 input-date                   pic x(10).
       01  output-date.
           02  day-name                pic xxx.
           02  day-no                  pic xx.
           02  month-name              pic xxx.
           02  year-no                 pic xxxx.
           02  days-since-jan-1-1900   pic x(8).

       01 tc-fail-count                binary-long.

       78 tc-usa     value  "U".
       78 tc-uk      value  "E".

       01 tc-msg-grp.
           03                         pic x(10) value "Test case ".
           03 tc-count                pic 999.
           03                         pic x(12) value " Failed -> ".
           03 tc-msg                  pic x(40).
           03                         pic x value x"0".

       procedure division.
       move 0 to tc-count tc-fail-count

       initialize output-date
       move "13/01/2000" to input-date, tc-msg
       call "datechk" using by reference input-date
                             by reference tc-usa
                             by reference output-date
       end-call
       perform expect-fail

       initialize output-date
       move "13/01/2000" to input-date, tc-msg
       call "datechk" using by reference input-date
                              by reference tc-uk
                              by reference output-date
       end-call
       perform expect-pass

      *>invalid year
       initialize output-date
       move "13/01/a000" to input-date, tc-msg
       call "datechk" using by reference input-date
                              by reference tc-uk
                              by reference output-date
       end-call
       perform expect-fail

      *>invalid month
       initialize output-date
       move "00/01/2000" to input-date, tc-msg
       call "datechk" using by reference input-date
                                by reference tc-uk
                                by reference output-date
       end-call
       perform expect-fail

       display "INFO: Test case count        : " tc-count
       display "INFO: Failed test case count : " tc-fail-count
       goback returning tc-fail-count.
       end-of-main section.

       expect-pass section.
           add 1 to tc-count
           if day-name equal spaces
               add 1 to tc-fail-count
               perform dump-output-values
               call MFU-ASSERT-FAIL-Z using
                   by reference tc-msg-grp
               end-call
            end-if
            .

       expect-fail section.
         add 1 to tc-count
         if day-name not equal spaces and
            day-no not equal spaces
            add 1 to tc-fail-count
            perform dump-output-values
            call MFU-ASSERT-FAIL-Z using
                  by reference tc-msg-grp
            end-call
         end-if.

       dump-output-values section.
         exhibit named tc-count input-date day-name
         exhibit named day-no month-name year-no days-since-jan-1-1900
           display "----------"
         .

      *> include the actual source code that we want to test.
       copy "datechk.cbl".

       end program MFUT_DATECHK.
       program-id. datechk.
      ********************************************************
      *    This subprogram validates dates input in either   *
      *      EUROPEAN or USA format. The result is returned  *
      *      as day-name, day, month-name, year.             *
      *    The program also calculates days since 1:1:1900   *
      ********************************************************
       data division.
       working-storage section.
       01  days-in-month-table         pic x(26)
                       value "31283130313031313031303129".
       01  filler redefines days-in-month-table.
           03 days-in-month            pic 99          occurs 13.
       01  month-name-table            pic x(36)
                       value "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC".
       01  filler redefines month-name-table.
           03 short-month-name         pic xxx         occurs 12.
       01  day-names                   pic x(21)
                       value "MONTUEWEDTHUFRISATSUN".
       01  filler redefines day-names.
           03 day-of-the-week          pic xxx         occurs 7.
       01  leap-year-indicator         pic 9.
           88  leap-year   value 0.
       01  subscript                   pic 99.
           88  february    value 2.
       01  quotient                    pic 9999.
       01  working-date.
           03  work-day                pic 99.
           03  work-month              pic 99.
           03  work-year               pic 9999.
       01  julian-calculation.
           03  days-to-1900            pic 9(8).
           03  extra-leap-days         pic 99.
           03  days-to-date            pic 9(8).
           03  total-days              pic 9(8).
           03  current-date-integer    pic 9(8).
       01  end-of-19th-century         pic 99999999.

       linkage section.

       01  input-date.
           03 input-day-or-month       pic 99.
           03 filler                   pic x.
           03 input-month-or-day       pic 99.
           03 filler                   pic x.
           03 input-year               pic 9999.

       01  usa-or-uk                   pic x.
           88  usa     value  "U".
           88  uk      value  "E".

       01  output-date.
           02  day-name                pic xxx.
           02  day-no                  pic xx.
           02  month-name              pic xxx.
           02  full-year-no.
               03  cent-no             pic xx.
               03  year-no             pic xx.
           02  days-since-jan-1-1900   pic x(8).

       procedure division using input-date, usa-or-uk, output-date.
       date-check section.
       prepare.
           if uk move input-day-or-month to work-day
                 move input-month-or-day to work-month
           else  move "U" to usa-or-uk
                 move input-day-or-month to work-month
                 move input-month-or-day to work-day
           end-if
           move input-year to work-year.
           move spaces to day-name
           move 0 TO days-since-jan-1-1900 total-days
           move work-day to day-no
           move work-month to month-name
           move work-year to full-year-no.

           if input-year not numeric
               move spaces to year-no
           else
               if work-year = 0
                   move 1 to leap-year-indicator
               else
                   divide work-year by 4 giving quotient
                                       remainder leap-year-indicator
               end-if
               if work-month is less than 1 or greater than 12
                   move spaces to month-name
               else
                   move work-month to subscript
                   move short-month-name (subscript) to month-name
                   if leap-year and february
                       move 13 to subscript
                   end-if
                   if   work-day is less than 1
                     or greater than days-in-month (subscript)
                       move spaces to day-no
                   else
                       perform calc-1900
                   end-if
               end-if
           end-if
           exit program.

      *Calculate days since start of century.
       calc-1900                 .
           move input-year to current-date-integer(1:4)
           move work-month to current-date-integer(5:2)
           move work-day to current-date-integer(7:2)
           move "18991231" to end-of-19th-century
           compute days-to-date =
           function integer-of-date(current-date-integer)
           compute days-to-1900 =
           function integer-of-date(end-of-19th-century)
           subtract days-to-1900 from days-to-date giving total-days
           move total-days to days-since-jan-1-1900
           subtract 1 from total-days
           divide total-days by 7 giving quotient remainder subscript.
           add 1 to subscript.
           move day-of-the-week (subscript) to day-name.

       end program datechk.

Parent topic: Examples - Writing Tests


JCL Test Case Example

Your Micro Focus product contains an example unit test and JCL job card that you can use together with a JES-enabled enterprise server region. Run using the test runner syntax on the command line, you can run the unit test which will submit the job card to the enterprise server region, and then query the resulting return code of the JCL job and perform a number of test assertions.

The example source files are located in the C:\Documents and Settings\All Users\Documents\Micro Focus\Visual COBOL\Samples\Mainframe\UnitTests\JCL_COBOL\Example1 directory.

  • txtdiff.jcl - the JCL job card. This job runs the IEBCOMPR utility to compare two blocks of data.
  • MFUT_TXTDIFF1.cbl - the test program that contains the unit test. The unit test uses JCL-specific metadata to identify the job card (MFU-MD-JCL-FILE-NAME), and then capture a number of job details (MFU-MD-JCL-COND-TYPE, MFU-MD-JCL-COND-CODE, and MFU-MD-JCL-JOB-NBR) after the test has run, then makes its test assertion by setting the MFU-MD-JCL-TESTCASE-PASSED variable accordingly (true or false).

To run the test, you also need a running JES-enabled enterprise server region - the following example uses a region called ESMFUJCL, and a catalog located in the c:\ESMFUJCL\ directory.

To run the example:

  1. Compile the test program:
    cbllink -D MFUT_TXTDIFF1.cbl

    This produces the required executable test file.

  2. Run the test, supplying details of the JES-enabled region and a JES catalog:
    The JCL job referenced in the unit test is submitted to the spool queue. The job requires a class A batch initiator, and so the test will wait, displaying the following output, if one is not already running within the region.
    Fixture : MFUT_TXTDIFF1
 Executing test case : MFUT_TXTDIFF1
  3. Start a batch initiator for class A, if required.

    The test runs and a summary similar to the following should display:

    Micro Focus COBOL - mfurun Utility
Unit Testing Framework for Windows/Native/32

Fixture : MFUT_TXTDIFF1
 Executing test case : MFUT_TXTDIFF1
  JCLCM0188I J0001037 IEBCOM01 JOB  STARTED 14:38:29
  JCLCM0182I J0001037 IEBCOM01 JOB  ENDED   - COND CODE 0008 14:38:29
 Completed test case : MFUT_TXTDIFF1 - Passed
 Generating report : MFUT_TXTDIFF1-report.txt

Test Run Summary
 Overall Result           Passed
 Tests run                1
 Tests passed             1
 Tests failed             0
 Total execution time     4255

    During the test run, the generated report (MFUT_TXTDIFF1-report.txt) was read by the COBOL program in order to make the test assertions shown in the summary.

Parent topic: Examples - Writing Tests


Data-Driven Test Case Example

Note: The following example is run from the command line, but the source can also be used just as easily from the IDE.

This example consists of four files; the source code for those file can be found in the appendix. The test also uses an additional copy book, mfunit.cpy, which should automatically be utilized if your environment is configured correctly.

The test case is run a number of times (once for each line in the data file), where it compares the initial and final statuses of a fictitious frequent flyers program.

Compile the two program to .so (see Compiling Tests), then run the resulting test suite (see Running Tests).

  1. Create a COBOL program entitled MFUT_TESTFLYER.cbl, and use the source code in the appendix.
  2. Create another COBOL program entitled GetFlyerLevel.cbl, and again use the appropriate source code in the appendix.
  3. Create a COBOL copy book entitled GetFlyerLevel.cpy (ensuring to save it to the same location as the two COBOL programs), and use the appropriate source code in the appendix.
  4. Finally, create a .CSV file entitled FrequentFlyer.csv, and use the data in the appendix. Again, ensure it is saved to the same location as the other files.
  5. Compile the test:
    cob -zU -e "" MFUT_TESTFLYER.cbl GetFlyerLevel.cbl
  6. Run the test:
    cobmfurun[32|64] -verbose:true MFUT_TESTFLYER.so

    The output should be similar to that shown below, indicating that the test passes after running 6 times (once for each row in the data source).

  • Appendix - Data-Driven Test Case Example
Parent topic: Examples - Writing Tests


Appendix - Data-Driven Test Case Example

MFUT_TESTFLYER.cbl

       program-id. MFUT_TESTFLYER.
       working-storage section.
       copy "mfunit.cpy".
       copy "GetFlyerLevel.cpy" replacing ==:prefix:== by ==ws==.

       01 ws-expected-award-level td-flyer-status.
       01 ws-earned               td-flyer-status-points.

       01 mfu-dd-InitialStatus    is MFU-DD-VALUE external.
       01 mfu-dd-FinalStatus      is MFU-DD-VALUE external.
       01 mfu-dd-InitialPoints    is MFU-DD-VALUE external.
       01 mfu-dd-EarnedPoints     is MFU-DD-VALUE external.
       procedure division.
           move mfu-dd-InitialStatus to ws-award-level
           move mfu-dd-FinalStatus   to ws-expected-award-level
           move function numval(mfu-dd-InitialPoints) to ws-award-points
           move function numval(mfu-dd-EarnedPoints) to ws-earned

      $if show-progress defined
           display " Data data driven test for " MFU-DD-DIAG-MSG
      $end
           call "GetFlyerLevel" using
               by reference ws-flyer-info
               by reference ws-earned
           end-call
           if ws-award-level not equal ws-expected-award-level
               goback returning MFU-FAIL-RETURN-CODE
           end-if
           goback returning MFU-PASS-RETURN-CODE.

       entry "MFUM_TESTFLYER".
           move "csv:FrequentFlyer.csv" to MFU-MD-TESTDATA
           goback.

       end program.

GetFlyerLevel.cbl

       program-id. GetFlyerLevel.
       linkage section.
       copy "GetFlyerLevel.cpy" replacing ==:prefix:== by ==lnk==.
       01 lnk-extra-status-points  td-flyer-status-points.
       procedure division using lnk-flyer-info, lnk-extra-status-points.
           add lnk-extra-status-points to lnk-award-points

           evaluate lnk-award-points
                when < 300
                   move "Bronze" to lnk-award-level
                when >= 300 and < 700
                   move "Silver" to lnk-award-level
                when >= 700 and < 1500
                   move "Gold" to lnk-award-level
                when >= 1500 and < 10000
                  move "Platinum" to lnk-award-level
               when other
                   move "Diamond" to lnk-award-level
           end-evaluate
       end program.

GetFlyerLevel.cpy

       01 td-flyer-status-points        pic 9(9) typedef.
       01 td-flyer-status               pic x(20) typedef.
       01 :prefix:-flyer-info.
           03 :prefix:-award-level      td-flyer-status.
           03 :prefix:-award-points    td-flyer-status-points.

FrequentFlyer.csv

InitialStatus,InitialPoints,EarnedPoints,Deductions,FinalStatus
Bronze,0,100,0,Bronze
Bronze,0,300,50,Silver
Bronze,100,200,66,Silver
Bronze,0,700,1,Gold
Bronze,0,1500,800,Platinum
Platinum,1600,12000,600,Diamond
Parent topic: Data-Driven Test Case Example


Compiling Tests

Restriction: Compiled fixture files with the base name mfunit will not run within the Micro Focus Unit Testing Framework.

The COBOL program that contains your test case(s) must be compiled to one of the executable formats: .so .int, or .gnt.

cob -zU -e "" mytestfixture.cbl
cob -e "" mytestfixture.cbl

Once it is compiled, you must run the resulting file from the shell.

Procedural managed code

You must compile the procedural managed COBOL programs as .dll using the JVMGEN (sub) Compiler directive. For example:

UNIX:

mkdir bin
cob -j myunittest.cbl -C 'jvmgen(sub)' -C 'iloutput(bin)'
cobmfjarprogmap -directory bin
jar -cvf myunittest.jar -C bin .
cobmfurunj myunittest.jar
Parent topic: Unit Testing from the Command Line


Running Tests

Using the test runner, you can run a test suite or the individual test cases within a suite. A test suite (a file containing multiple test cases) can be one of the following formats: .so .jar, .int, or .gnt.

If you run a test suite from the shell prompt, the options you specify are applied to all test cases that are run. You can also use metadata embedded in your test cases, enabling you to selectively run test cases that have been marked with a certain trait (the MFU-MD-TRAITS variable), or prioritize certain test cases over others (the MFU-MD-TESTCASE-PRIORITY variable).

Using test fixture files (.mfu files) is another way of running test suites or one or more test cases. These files provide some additional options that you can apply to individual test cases.

  • Configuring the Run-Time System Environment
    Configure run-time system configuration files that are specific to a test run. When you initiate the test run, the Micro Focus Unit Testing Framework automatically applies the environment settings in the file before the test is run.
  • Test Runner Syntax Options
    Use the following syntax from the shell prompt to run a test suite.
  • Using Color in Test Reports
    You can add basic colorization to test output.
  • Test Fixture Files
    A test fixture file is a configuration file that enables you to apply certain individual options to each test case within a test fixture.
  • Examples
    A collection of examples for running test suites and test cases from the shell prompt, and for creating skeleton test fixture files.
Parent topic: Unit Testing from the Command Line


Configuring the Run-Time System Environment

You can configure the run-time system environment in which your tests run using the usual methods (see Run-Time System Configuration), but those settings will remain in place for each subsequent set of tests run until the values are changed. A more efficient method is to configure an environment that is automatically applied when you initiate a particular test run. You can do this by creating an application configuration file or Java properties file containing the usual run-time system configurations. The naming of this file depends on the type of tests that are in your test run:
Native COBOL tests
The application configuration file must have the same base name as the base name of your test suite (i.e. the base name of your .int, .gnt, .so, or .mfu file), and an extension of .mfgcf. Place this file in the same location as your test suite and it will be used during the test run.
Use your IDE to create the application configuration file.
JVM Procedural COBOL tests
The Java properties file must have the same base name as the base name of your test suite (i.e. the base name of your .so, or .mfu file), and an extension of .envprops. Place this file in the same location as your test suite and it will be used during the test run. Create the plain-text file with any text editor, placing each setting/value pairing on a separate line.
Parent topic: Running Tests
Related concepts
Using Color in Test Reports
Test Fixture Files
Related reference
Test Runner Syntax Options
Examples


Test Runner Syntax Options

Use the following syntax from the shell prompt to run a test suite.

At the prompt, enter:

test-runner [options] [test-suite]

where:

test-runner
The name of the executable that will run the test suite, and then produce the test results:
  • cobmfurun32[_t] - for use with procedural COBOL
  • cobmfurun64[_t] - for use with procedural COBOL
  • cobmfurunj - for use with JVM COBOL

The optional _t runs the test suite in the multi-threaded run-time system, and is required for tests that use a timeout value.

options

The options that apply to the test run. These are optional, and you can apply one or more of the following:

-testcase:testcase-name
Only run the specified test case from the test suite; all other test cases are skipped. Not set by default.

Alternatively, you can specify multiple test cases using one of the following approaches:

  • List the test cases using comma as a separator:
    -testcase:testcase-name1,testcase-name2,... everything.dll

    Or:

  • Specify a side file that includes a list of test cases:
    -testcase:@filelist.txt everything.dll

Where:

  • everything.dll - all your source code compiled
  • filelist.txt - the file that includes a list of all test cases to execute
-ignore-options-in-mfu:{true|false}
Ignores any options in the specified test fixture file, enabling you to override them with ones specified on the command line.
-ignore-return-code:{true|false}
When set to true, the return-code indicating a test pass or fail is ignored, and the test continues running. The default is false.
-verbose:{true|false}
Displays verbose output to the screen. The default is true.
-process:{single|separate}
Use a single process for the entire test run, or multiple separate processes (one for the test runner and one for each test case within the run). If you are using separate processes, the parent test runner process can log errors and continue with the test run in the event of a test case failure. The default is separate.
-isolate:{true|false}
Isolates each test case, so that any resources shared between test cases start from their correct initial state for each test case. The default is true.
-report{printfile|noprintfile|junit|nojunit}...
Outputs the test results to a .txt file (printfile option) or .xml file (junit option). The default is to produce a .txt file. The JUnit report takes the form of TEST-<package-name>-<test-case-name>.xml. Set <package-name> using the -junit-packname:package-name option.
-generate-flist:filename
Outputs a list of failed test names to filename.
Tip: You can use the generated file to rerun the failed tests by using the -testcase:@filename test-suite syntax.
-report:markdown
Outputs the test results to a GitHub style markdown format file (.md).
Note: You can use various external utilities such as the pandoc utility (see http://pandoc.org/) to convert the markdown file into an .html or a .pdf file. Here are some example commands for converting the .md file when you use pandoc:
pandoc -thtml5 -s -S --toc -c pandoc.css -fmarkdown_github mfumeta.md -o mfumeta.html

Or

pandoc -s -S --toc -c pandoc.css -fmarkdown_github mfumeta.md -o mfumeta.pdf
-report:timings-csv
Generates a .csv file containing the timings for the test run.
-reportfile:filename
Changes the name of the .txt report file. It defaults to <test suite-name>-report.txt.
-junit-packname:package-name
Packages the JUnit formatted .xml files under package-name. Not set by default.
-outdir:directory
Specifies a directory for the reports. If not specified, the reports are created in the directory in which the tests were run.
-trait:trait-name(s)
Specifies that only test cases with the specified trait name should be run (and all other test cases skipped). You can specifiy more than one trait, separated by a comma, if required. You set a trait for a test case by using the MFU-MD-TRAITS variable in your source code, or specifying the traits=trait-name in the text fixture file.
Tip: You can combine this option with the -generate-mfu option to create a test fixture file designed to only run test cases with a particular trait; for example:
cobmfurun32|64[_t] -generate-mfu -trait:smoke test-suite.so
-jenkins-ci
Enables support for producing test results that will be used on a Jenkins CI server.
-jenkins-ci:junit-attachments
Enables support for producing test results that will be used on a Jenkins CI server, and also enables the Jenkins plugin for JUnit formatted results.
-diagnostics-color:off|ansi|jenkins|windows10
Enables colorisation of certain elelments of the output. Set the value to the intended viewing platform. The default is off. See Using Color in Test Reports for more information.
-silk-central

Outputs the results to an .xml file that is compatible with Silk Central. The output.xml file, along with any required assets (log and dump files), are placed in the location determined by the SCTM_EXEC_RESULTSFOLDER environment variable, where they can be picked up and processed by Silk Central (refer to your Silk Central Help for more information on ProcessExecuter Tests). If you specify this option when your Silk Central environment is not correctly configured, you receive an error.

-jit:{core|debug}
Produces a core dump file or invokes just-in-time debugging when a test case errors.
Note: This option has no effect when asserting a test failure.
-debugbreak
Immediately starts the debugger.
-debugstart:id
Issues a start/wait command to the debugger using the specified id.
-csv-line-filter:line-number testcase-name
For use when executing data-driven tests for a data source in CSV format. Use line-number to specify the only line of your data source to use when running testcase-name. This can be particularly useful when combined with the -debugbreak and -debugstart options to focus in on a particular piece of data.
-generate-csv-snippet:testcase-name data-source
Creates a test case that includes the basic structure for a data-driven test. It reads data-source (currently limited to CSV files) and creates the necessary data items required to test the data.
Note: Windows users: you can directly pipe the code snippet to the clipboard by appending | clip to the command.
-generate-mfu filename
Produces a skeleton test fixture file (.mfu file) from the test cases within filename (a .dll file or .so file).
-high-res-timer:{true|false}
When set to true, a native high-resolution performance counter is used to report the duration of the test run. The default is false.
Note: High-resolution timings cannot be displayed in the junit or Silk Central .xml formats; normal timings are always displayed.
-es-server-name:server-name
Specifies the enterprise server region name to which the JCL job card will be submitted. Use this option in conjunction with -es-use-mfcc:true to emulate the cassub /l command, or in conjunction with -es-use-mfcc:false to emulate the cassub /r command.
Note: The -es-server-name and -es-service options are mutually exclusive.
Tip: Set the MFUNIT_ES_SERVER_NAME environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-service:service-endpoint
Specifies the service-endpoint to which the JCL job card will be submitted. This takes the form of <protocol>:<address>:<port> (for example tcp:localhost:9023). Use this option to emulate the cassub /s command.
Note: The -es-server-name and -es-service options are mutually exclusive.
Tip: Set the MFUNIT_ES_SERVICE environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-use-mfcc:{true|false}
Use the Micro Focus Common Client (mfcc) for the server-name lookup. Use this option in conjunction with -es-server-name:server-name.
Tip: Set the MFUNIT_ES_USE_MFCC environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-syscat:catalog
Specifies the location and name of the system catalog file (catalog.dat). You must specify this option with either of the JCL submission options (-es-server-name:server-name or -es-service:service-endpoint).
Tip: Set the MFUNIT_ES_SYSCAT environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-userid:user
If the enterprise server region indicated by -es-service or -es-server-name has security enabled, use -es-userid to specify valid user credentials. This argument emulates the cassub /u command.
Tip: Set the MFUNIT_ES_USERID environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-password:password
If the enterprise server region indicated by -es-service or -es-server-name has security enabled, use -es-userid to specify valid user credentials. This argument emulates the cassub /p command.
Tip: Set the MFUNIT_ES_PASSWORD environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-auth-group:group
If the enterprise server region indicated by -es-service or -es-server-name has security enabled, use -es-userid to specify valid user credentials. This argument emulates the cassub /c command.
Tip: Set the MFUNIT_ES_AUTH_GROUP environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-jes-level:level
Specifies the JES version in effect, and if omitted, the level defaults to 2. This argument emulates the cassub /v command.
Tip: Set the MFUNIT_ES_JES_LEVEL environment variable, and then omit this command line option, to avoid having to re-enter the same information for multiple test runs.
-es-jcl-range-retc:range
The range of return code values that determines the test failure; if the return code falls within the range, the test is marked PASS, otherwise it's marked FAIL. Specify a range using nnn-nnn; for example, -es-jcl-range-retc:0-7.
test-suite
A COBOL program compiled to .so , or an .mfu test fixture file. For procedural managed program, specify a .jar file instead.
Tip: Use the following command to obtain a list of shortened arguments that you can use when running tests:
cobmfurun32|64[_t] -shortcuts
Parent topic: Running Tests
Related concepts
Configuring the Run-Time System Environment
Using Color in Test Reports
Test Fixture Files
Related reference
Examples


Using Color in Test Reports

If you want to introduce colorization into your test output, you can use the -diagnostics-color command line option or the MFUNIT_COLORS environment variable. These options embed Select Graphic Rendition (SGR) substrings within the output, which when viewed using a supported terminal emulator display color.

Set either of these options to one of the following supported emulations when running a test suite:

Windows10
Only use this option on Windows 10 platforms. It activates a new terminal mode that allows the use of VT terminal sequences to be used in a Windows command prompt.
ansi
Use on all non-Windows 10 platforms. On Windows, you need to use a third-party terminal emulator that includes ANSI/SGR escape code support. On UNIX/Linux platforms, this support is in-built.
Jenkins
Use this option when associating JUnit-style reports with tests on a Jenkins CI server. Your server must have the AnsiColor plugin active in order to interpret the escape sequences embedded in the reports.

These values will give a standard colorization (foreground color only), but you can choose from a greater range of colors when using the MFUNIT_COLORS variable by appending additional values to the emulations given above; for example, the following value uses the ansi mode, and displays all pass information in the output with the foreground color magenta:

set MFUNIT_COLOR=ansi:ps=35

Each additional pair of values is delimited by a colon (:). Refer to Test Results Color Coding for available values.

  • Test Results Color Coding
Parent topic: Running Tests
Related concepts
Configuring the Run-Time System Environment
Test Fixture Files
Related reference
Test Runner Syntax Options
Examples


Test Results Color Coding

To configure the colorization of test output beyond the standard colors, you append color coding pair values to the value of the MFUNIT_COLORS environment variable.

The following table shows the default colors used as the foreground text if you do not explicitly specify an identifier.

Color marker | identifier | default | description
Pass information | ps | 32 | Green
Fail information | fl | 31;1 | Red + bold
Error information | er | 31 | Red
Skipped information | sp | 34 | Blue
Note: To apply bold to any of the colors, append ;1 to the color value, as shown for the fail information.

Use the following values with an identifier to override the default:

Color | Value
Bold | 1
Black | 30
Red | 31
Green | 32
Yellow | 33
Blue | 34
Magenta | 35
Cyan | 36
White | 37
Bright black | 90
Bright red | 91
Bright green | 92
Bright yellow | 93
Bright blue | 94
Bright magenta | 95
Bright cyan | 96
Bright white | 97

Example:

The following variable results in the pass information displaying in bold cyan, and the error information displaying in green.

export MFUNIT_COLORS=ansi:ps=36;1:er=32
Parent topic: Using Color in Test Reports


Test Fixture Files

If you regularly run a number of test suites, using the same options each time, you should use a test fixture file (.mfu file). Using a test fixture file saves you from having to specify the test suites and their options individually each time you want to run them.

Another advantage of using a test fixture file is that you can utilize the Apache Ant support to run test suites. See Example Ant Project for a simple example of how to run test fixture files and configure the output.

Within a test fixture file, the Global section enables you to set options that apply to all test cases specified to run, and individually-named sections enable you to also specify options per individual test case. The options that you can set individually are: a description of the test; a timeout period (before the test is considered to have failed); and an option to skip the test. Some of this information can also be set programmatically, during the test setup; see Using Dynamic Metadata for more information.

See Example Test Fixture File for a sample format. Alternatively, you can create a skeleton .mfu file from a COBOL .so file, by using the -generate-mfu test-suite-name option, and then edit it to suit your needs.

  • Example Test Fixture File
  • Example Ant Project
Parent topic: Running Tests
Related concepts
Configuring the Run-Time System Environment
Using Color in Test Reports
Related reference
Test Runner Syntax Options
Examples


Example Test Fixture File

The following is an excerpt from a test fixture file containing two test cases; one (MFUT_FailingTest) is known to be causing the test run to fail and has therefore been removed (skipped) from the test run:

[global]
# By not supplying a platform specific extension (.dll or .so)
# with the fixture-filename, this can be used cross-platform
fixture-filename=MessageOverflow
process=separate
isolate=true
report=nojunit
report=printfile
reportfile=MessageOverflow-report.txt
ignore-return-code=false
summary=true
outdir=.

[MFUT_MyShortRunningTest]
# The test fails if not completed within 10 seconds
# You can also specify ms (milliseconds)
timeout=10s
description=Short running test that should complete in < 10 seconds
trait=smoke
skipped=false
# test cases with high priorty (3000) run first
priority=3000
# Mr Smith can you fix this ASAP..

[MFUT_FailingTest]
timeout=60s
description=This failing test needs attention... fix me and re-enable
trait=smoke
# Skip a test using:
skipped=true
Parent topic: Test Fixture Files
Related reference
Example Ant Project


Example Ant Project

Note: Full syntax support for the mfurun task is covered in the Micro Focus Ant User Manual, available from the Micro Focus SupportLine web site.

Running the following Ant project in your Ant framework and it will pick up any test fixture files (.mfu files) in the current directory, and as long as those files can also locate the test suites, will run them. The project is also configured to output the test results to a reports sub-directory; open the resulting index.html file in your browser to view the results of the test run. As these results have been generated in junit format, you can import them into your CI server solution.

The <taskdef> element points to the Micro Focus mfunit API, which is located in the mfunit.jar supplied with Visual COBOL; this .jar file must be on the current CLASSPATH in order to run the project.

<project>
<taskdef name="mfurun" classname="com.microfocus.mfunit.ant.MFURunMFUTask" />
    <condition property="src" else=".">
        <isset property="src"/>
    </condition>

    <echo>Source directory = ${src}</echo>

    <mfurun dir="${src}"
     printsummary="true"
     junitresults="true"
     junitreportpackage="com.mycompany.testcases">
         <fileset dir="${src}" includes="*.mfu" />
    </mfurun>

    <property environment="env"/>
    <mkdir dir="report"/>
    <junitreport todir="report">
     <fileset dir=".">
           <include name="TEST-*.xml"/>
     </fileset>
     <report format="frames" styledir="${env.ANT_HOME}/etc" todir="report"/>
    </junitreport>

</project>
Parent topic: Test Fixture Files
Related reference
Example Test Fixture File


Examples

Running test suites

The following command runs all test cases in myFullTestsuite, using the default options:

cobmfurun32 myFullTestsuite.so

The following command only runs the mySecondTestcase test case within the test suite, producing verbose output:

cobmfurun32 -testcase:mySecondTestcase -verbose myFullTestsuite.so

The following command runs all test cases in myFullTestsuite and produces a JUnit-style report (.xml file), and also produces a core dump file for each test case that encounters an error:

cobmfurun64 -report:junit -jit:core myFullTestsuite64.so

The following command runs all test cases in myFulltestsuite, and invokes just-in-time debugging each time a test case encounters an error. The test run continues when the debugger is closed:

cobmfurun32 -jit:debug myFulltestsuite.so

The following command runs all test cases in myFulltestsuite, ignoring any errors encountered:

cobmfurun32 -ignore-return-code:true myFulltestsuite.so

Running JCL tests

The following command tests whether a JCL job card was successfully submitted to a JES environment:

(The submission of the JCL emulates the cassub /r command.)

cobmfurun32 -es-server-name:ESDEMO -es-use-mfcc:false -es-syscat:/usr/ESDEMO/CATALOG.DAT MYJCL.JCL

The following command runs the MFUT_TXTDIFF1.dll test program, which specifies the JCL job card to submit to the enterprise server region corresponding to the -es-service details.

(The submission of the JCL emulates the cassub /s command.)

cobmfurun32 -sp -es-service:tcp:localhost:9003 -es-syscat:/ESMFUJCL/CATALOG.DAT MFUT_TXTDIFF1.so

Creating and running test fixture files

The following command produces an .mfu file with the same base name as the test suite file:

cobmfurun32 -generate-mfu myFulltestsuite.so

The following command runs all test cases in the test fixture file:

cobmfurun32 myFulltestsuite.mfu

The following command runs all test cases in the test fixture file, but any options in the .mfu are ignored:

cobmfurun32 -ignore-options-in-mfu:true myFulltestsuite.mfu
Parent topic: Running Tests
Related concepts
Configuring the Run-Time System Environment
Using Color in Test Reports
Test Fixture Files
Related reference
Test Runner Syntax Options


Viewing Test Results

On completion of a test run, the results are displayed to screen and to a .txt file by default. You can also output the results to a JUnit-style XML format.

The details displayed to screen are a high-level summary of the test run. More detailed information is included in the reports that are produced.

  • Example - Test Results Text File
  • Example - Test Results JUnit Format
  • Using the Results in Silk Central
  • Using the Results on a Jenkins CI Server
Parent topic: Unit Testing from the Command Line


Example - Test Results Text File

This type of results format is a plain-text file that is produced by default; use the -report:{printfile|noprintfile} option to control if the report is produced, and use the -reportfile:<filename> option to specify a custom name for the report.

This report is located in the same directory as the test suite by default; use the -outdir:<directory> option to specify a different output directory.

The following report details a test run that ran 4 tests - 3 passed and 1 failed. The error for the failing test is given. Cross reference the number stated before the error message (in this case, 148) with the Run-time System Error Messages section for details on a possible resolution.

Micro Focus COBOL - mfurun Utility
Unit Testing Framework for Windows/32/Native

Options : verbose=true,process=separate,junit=false,printfile=true
Testsuite filename : MultiTest.dll

Test case                  : MFUT_FullTestCase1
 Status                    : Completed / Passed
 Time taken in ms          : 000000014
 Return Code               : 000000000

Test case                  : MFUT_FullTestCase2
 Status                    : Errored
 Time taken in ms          : 000000002
 Runtime error             :
  I/O error : file 'cust.txt'
  error code: 4/8 (ANS85), pc=0, call=1, seg=0
  148     Wrong open mode or access mode for write
 Fail message count        : 000000000

Test case                  : MFUT_FullTestCase3
 Status                    : Completed / Passed
 Time taken in ms          : 000000014
 Return Code               : 000000000

Test case                  : MFUT_FullTestCase4
 Status                    : Completed / Passed
 Time taken in ms          : 000000002
 Return Code               : 000000000

Test Run Summary
 Overall Result            : Failed
 Tests run                 : 4
 Tests passed              : 3
 Tests failed              : 0
 Tests errored             : 1
 Total execution time      : 32
Parent topic: Viewing Test Results


Example - Test Results JUnit Format

JUnit is a unit testing framework designed for Java programming (visit http://junit.org/junit4/ for more information). The Micro Focus Unit Testing Framework is capable of producing JUnit-style reports for each individual test case, even when there are multiple test cases in a test run.

This type of results format is not produced by default; use the -report:{junit|nojunit} option to control if the report is produced, and use the -junit-packname:<package-name> option to group the reports under one package name.

These reports are located in the same directory as the test suite by default; use the -outdir:<directory> option to specify a different output directory.

The following example shows a failing test displayed inside a browser, but you can use this format of file in other third-party applications, such as a Jenkins CI server.

Parent topic: Viewing Test Results


Using the Results in Silk Central

If you are running in a Silk Central environment, you can output test results from the Micro Focus Unit Testing Framework that are compatible with Silk Central.

By using the -silk-central option when running the test, the Micro Focus Unit Testing Framework places the files in a location that Silk Central can process the test results.

If you specify this option when your Silk Central environment is not correctly configured, you receive an error.

For more information, refer to your Silk Central Help on ProcessExecuter Tests.

Parent topic: Viewing Test Results


Using the Results on a Jenkins CI Server

If you are using a Jenkins Continuous Integration (CI) server within your development and testing process, you can use the JUnit-style reports to associate the unit test results with particular details, such as a code change, on your server.

Enable Jenkins CI support for your test run by specifying -jenkins-ci as an option on the shell prompt. To include additional support, such as displaying the results within the Jenkins CI system, specify -jenkins-ci:junit-attachments instead. For more information about both of these options, visit the third-party links below:
  • https://wiki.jenkins-ci.org/display/JENKINS/JUnit+Plugin
  • https://wiki.jenkins-ci.org/display/JENKINS/JUnit+Attachments+Plugin

Additionally, if you want to introduce some colorization into your test output, you can use the -diagnostics-color:jenkins command line option or the MFUNIT_COLORS=jenkins environment variable to embed the necessary ANSI escape sequences to give basic color to the report. Using this method requires that you have the AnsiColor plugin active on your Jenkins server in order to interpret the escape sequences embedded in the report. See Using Color in Test Reports for more information.

Parent topic: Viewing Test Results


Dealing with Errors in Your Tests

Using the following test runner options, you can determine the action when an error is encountered whilst running each test case within the test suite:

  • The ignore-return-code:true option ignores any errors (based on a non-zero return code), and continues processing the next test case.
  • The -jit:core option produces a core dump file as each error is encountered, and continues processing the next test case.
  • The -jit:debug option invokes just-in-time debugging as an error is encountered, and only continues processing the next test case when you have closed the debugger.
  • From within a test case, you can also call the CBL_DEBUGBREAK library routine, which invokes the just-in-time debugger.
Parent topic: Unit Testing from the Command Line


Programming Tips

There is a range of programming of techniques for designing and writing COBOL applications.

  • Accessing Data on the Command Line from COBOL
  • Accessing Environment Variables from COBOL
  • Manipulating Data with Reference Modification and STRING
  • Writing Recursive Routines
  • Coding an Intrinsic Function
  • Manipulating Bits
  • Examples
Parent topic: Programming
Related information
Overview - Mixed Language Programming
Overview - Performance Programming


Accessing Data on the Command Line from COBOL

You can use the following methods to enable a program to access and use data on the command line:

  • To move the complete contents of the command line to a data-name, use ACCEPT data-name FROM COMMAND-LINE. For example:
    …
working-storage section.
01 cmdline pic x(100).

procedure division.
accept cmdline from command-line
…
  • To access individual arguments on the command line, use one of the following:
    • DISPLAY ... UPON ARGUMENT-NUMBER
    • ACCEPT ... FROM ARGUMENT-NUMBER
In managed COBOL, you can use the following construct:
    program-id. Program1.
    data division.
    Procedure division using by value cmds as string occurs any.
    Perform varying s as string thru CMDS
            Display s
           End-perform

Comments:

Only in native COBOL can you use the command_line_linkage run-time system tunable to have parameters passed to your main program.

Parent topic: Programming Tips
Related reference
command line linkage
Related information
The ACCEPT Statement


Accessing Environment Variables from COBOL

Use the following construct to access environment variables from the COBOL source code:

working-storage section.
01 val pic x(100).
Procedure division.

display "USERNAME" upon environment-name
accept val from environment-value
display val
goback.
...
Important: It is unsafe to modify or add environment variables in a threaded application on Linux systems. This is due to limitations of the underlying system libraries. It is however safe to read values from environment variables.
Parent topic: Programming Tips
Related information
Accessing Data on the Command Line


Manipulating Data with Reference Modification and STRING

You can manipulate data items in detail in two ways:

  • The STRING statement. This statement concatenates the partial or complete contents of two or more data items and stores the result.

    In general, using STRING is easier to read and implement. However, it can be resource-intensive, particularly if used many times in a program. You can use STRING in programs that do not incur a lot of overhead for other reasons, such as significant file I/O.

  • Reference modification. This technique enables you to make references to (and change) parts of a data item by starting values, for a specified length.

    Reference modification is more efficient, but can lead to code that is more difficult to read and maintain. It is a way to improve performance in programs that use STRING heavily and are running slowly or growing too large.

For example, the following two statements are equivalent. In both examples, street-address is 25 bytes long:

STRING street-address DELIMITED BY SIZE INTO print-rec
    WITH POINTER num-char
MOVE street-address TO print-rec (num-char: 25)
Parent topic: Programming Tips


Writing Recursive Routines

A recursive routine is a routine that calls itself. Recursion is the most natural method of solving certain problems, such as:

  • Searching a tree
  • Calculating certain mathematical functions
  • Following paths through a network
  • Processing a bill of materials
  • Choosing the best solution from a set of possible solutions

Although you can write any recursive routine as a straight iterative routine, the use of a recursive routine can simplify the program's logic.

In this COBOL system, a program can be recursive provided it is not nested inside another program and it has a Local-Storage Section. A program can call itself via either its program-id or an entry point.

Each call of a recursive routine is called an instance. Each instance needs a different set of the data items used by the routine; so this COBOL system enables you to have a Local-Storage Section. A run-time error message is issued if you try to use recursion in a program that does not contain a Local-Storage Section.

See Related information for examples of recursion and recursive routines.

Parent topic: Programming Tips
Related reference
RECURSECHECK
Related information
Example of Recursion
Example of Recursive Routines


Coding an Intrinsic Function

A function is a temporary data item whose value is determined when the function is referenced during execution. Your COBOL system provides a library of intrinsic functions.

As an example of an intrinsic function, consider the following statement:

COMPUTE x = FUNCTION COS(y)

The intrinsic function cos computes a numeric value that approximates the cosine of an angle (expressed in y radians) and stores that value in x.

Parent topic: Programming Tips


Manipulating Bits

When you program in a COBOL environment, you deal with data that is composed of characters, fields, records, or files. However, there are occasions when you must deal with individual data bits. For example, bit manipulation is an important feature in applications that deal with:

  • Screen and graphics interfaces
  • Encryption techniques
  • System-level routines
  • Table lookup, that is, converting an incoming code to an expanded value
  • Packing and unpacking data

Manipulating Bits with Logic Routines

There is a set of library routines for bit manipulation. These routines are:

CBL_NOT | logical NOT
CBL_AND | logical AND
CBL_OR | logical OR
CBL_EQ | logical EQuivalence
CBL_XOR | logical eXclusive OR
CBL_IMP | logical IMPlies

These logical operations give the results shown in the following truth tables.

A |  | 0 | 0 | 1 | 1
CBL_NOT | (not A) | 1 | 1 | 0 | 0
A |  | 0 | 0 | 1 | 1
B |  | 0 | 1 | 0 | 1
CBL_AND | (A AND B) | 0 | 0 | 0 | 1
CBL_OR | (A OR B) | 0 | 1 | 1 | 1
CBL_EQ | (A EQ B) | 1 | 0 | 0 | 1
CBL_XOR | (A XOR B) | 0 | 1 | 1 | 0
CBL_IMP | (A IMP B) | 1 | 1 | 0 | 1

For example, when the CBL_EQ routine compares bits A and B, the resulting bit is set to 1 if both A and B are 0 or if both A and B are 1. Otherwise the resulting bit is set to 0.

Manipulating Bits as Boolean Data Items

You can also define data items as boolean using picture character 1, and use the boolean operators B-AND, B-OR, B-XOR, and B-NOT to perform "and", "or", "exclusive or", and "negate" operations. These operators are used in boolean expressions; for example:

 01 My-flag PIC 1111 USAGE BIT VALUE B"0000".
01 My-flag-2 PIC 1111 USAGE BIT.
...
MOVE B"0011" to My-flag-2 *> Initialize My-flag-2
...
COMPUTE My-flag = B-NOT My-flag-2 *> set the bits in My-flag to the
*> reverse of My-flag-2, 1100.
...
COMPUTE My-flag = My-flag B-AND B"0000" *> turn off all the bits in My-flag.
...
COMPUTE My-flag-2 = My-flag-2 B-OR B"1000" *> set bit 1 ON in My-flag-2, keeping
*> other bits unchanged.

Boolean items can be tested in two ways:

  • as a boolean condition, if the length of an item is 1 bit position or 1 character position; for example:
    01 Single-bit-item pic 1 usage bit.
01 Multiple-bit-item pic 1(7) usage bit.
...
IF Single-bit-item THEN CALL a-program *> calls if Single-bit-item is true (1)
  • as a relation condition, testing for equal or not equal; for example:
    IF My-flag-2 EQUAL B"1000" THEN CALL a-program

Converting boolean data items to integers

Boolean items can be converted to integer with the INTEGER-OF-BOOLEAN intrinsic function, and integer items can be converted to boolean with the BOOLEAN-OF-INTEGER intrinsic function. For example:

01 bit-item PIC 1(6) usage BIT.

01 integer-item PIC 9(5) VALUE 544. *>  1000100000 in binary
01 integer-item-2 PIC 9(3).
...
MOVE FUNCTION BOOLEAN-OF-INTEGER ( integer-item , 6) TO bit-item.
*> the function returns the low order 6 bits of the binary representation of the
*> integer value, and MOVE stores it in bit-item, padding on the right with 0’s
...
COMPUTE integer-item-2 = FUNCTION INTEGER-OF-BOOLEAN (bit-item).
*> the function returns the numeric value of the leading 6 bits (100000 in binary), 32, and
*> COMPUTE puts 032 in integer-item-2
Parent topic: Programming Tips


Examples

  • Example of Recursion
  • Example of Recursive Routines
  • Example of Intrinsic Functions
  • Example of Bit Manipulation
Parent topic: Programming Tips


Example of Recursion

In the following example, the table in the item family-tree contains an entry for each of Fred Smith's descendants. Assume the data has been put in the table by an earlier program. The first entry is Fred Smith's own. Each entry contains, as well as the person's name, a data item called eldest-pointer containing the position in the table of the entry for that person's eldest child. Someone with no children has 99 in this item. Similarly each entry has a data item sibling-pointer pointing to the entry for the person's next younger sibling. Someone with no younger siblings has 99 in this item.

An example that shows how to use recursion to search a family tree:

 identification division.
 program-id. family.
    . . .
 working-storage section.
 01  family-tree.
     03  individual    occurs 50.
         05  ind-name           pic x(30).
         05  eldest-pointer     pic 9(2).
         05  sibling-pointer    pic 9(2).

 local-storage section.
 01  tree-pointer      pic 9(2).

 linkage section.
 01  parent-pointer    pic 9(2).

 procedure division.
     move 1 to tree-pointer
     call "children" using tree-pointer
     stop run.

* If this person has no eldest child, routine "children"
* displays the person's name and does nothing more. Otherwise,
* this routine starts with the person's eldest child and calls
* itself for each sibling in turn.
 entry "children" using parent-pointer
     move eldest-pointer(parent-pointer) to tree-pointer
     if tree-pointer = 99
         display ind-name(parent-pointer)
     else
         perform until tree-pointer = 99
             call "children" using tree-pointer
             move sibling-pointer(tree-pointer)to tree-pointer
         end-perform
     end-if.
Parent topic: Examples
Related information
Writing Recursive Routines


Example of Recursive Routines

The following sample code illustrates some of the features of a recursive routine. This routine, identified by the entry point factorl, computes the factorial of a number that you enter.

 1 working-storage section.
 2 01 n             pic x(4) comp-x.
 3 01 factorial     pic x(4) comp-x.
 4 01 m             pic x(4) comp-x.
 5
 6 local-storage section.
 7
 8 procedure division.
 9     accept n
10     move 1 to factorial
11     call 'factorl' using n
12     display 'factorial of ' n ' is ' factorial
13     stop run.
14
15 entry 'factorl' using m.
16     if m < 1
17         move 1 to factorial
18     else
19         if m > 1
20             multiply m by factorial
21             subtract 1 from m
22             call 'factorl' using m
23         end-if
24     end-if
25
26     exit program.
Note:
  • Line 6

    local-storage section

    Since the recursive routine can be called several times, the local data from one call must be protected from another call to the same code. This protection is done using a Local-Storage Section. Each time a new instance of the routine starts, an initialized copy of this section is created in memory. If you try to use recursion in a program that does not contain a Local-Storage Section, an RTS error message is issued.

    Notice that this routine does not have any local storage data items, but it still requires the local storage declaration.

  • Line 15

    entry 'factorl' using m

    This is the entry point of the recursive routine factorl. A program can call itself via its Program-ID or an entry point.

  • Lines 19-23

    if m > 1

    multiply m by factorial

    subtract 1 from m

    call 'factorl' using m

    end-if

    This loop contains the recursive call.

  • Line 22

    call 'factorl' using m

    The recursive call statement.

Parent topic: Examples
Related information
Writing Recursive Routines


Example of Intrinsic Functions

This example program, intrins.cbl, shows some of the ways you can use intrinsic functions in your programs.

Note:

There are three types of intrinsic function: integer, numeric and alpha. The FACTORIAL function used in the sample below is a numeric function. The coding technique shown might not apply for the other function types.

  1$set mf noosvs ans85
  2
  3*************************************************************
  4* Copyright Micro Focus Limited 1991. All Rights Reserved.  *
  5* This demonstration program is provided for use by users   *
  6* of Micro Focus products and may be used, modified and     *
  7* distributed as part of your application provided that you *
  8* properly acknowledge the copyright of Micro Focus in this *
  9* material.                                                 *
 10*************************************************************
 11
 12*************************************************************
 13*                                                           *
 14*                     INTRINS.CBL                           *
 15*                                                           *
 16*    This program demonstrates some of the ways you can     *
 17*    use Intrinsic Functions in your COBOL application.     *
 18*    This program uses the FACTORIAL Intrinsic Function     *
 19*    to illustrate the following capabilities:              *
 20*                                                           *
 21*    1) Data item is assigned the value of a function       *
 22*    2) Function is used as a data item in an EVALUATE      *
 23*           statement                                       *
 24*    3) Function is used as a data item in an IF            *
 25*           statement                                       *
 26*    4) Function uses an array element (fixed index) as     *
 27*           an argument                                     *
 28*    5) Function uses an array element (variable index)     *
 29*           as an argument                                  *
 30*    6) Data item is assigned the value of a function of    *
 31*           a function                                      *
 32*    7) Data item, assigned the value of the function,      *
 33*           is used in a COMPUTE statement                  *
 34*    8) Data item is assigned the value of the sum of       *
 35*           two functions                                   *
 36*    9) Function is used in the UNTIL condition of a        *
 37*           PERFORM ... UNTIL statement                     *
 38*                                                           *
 39*                                                           *
 40*    To familiarize yourself with the Intrinsic function    *
 41*    syntax, try running INTRINS under Debugger.            *
 42*                                                           *
 43*    Compile the program using:                             *
 44*                                                           *
 45*           COBOL INTRINS ANIM;                             *
 46*                                                           *
 47*    then debug the program:                                *
 48*                                                           *
 49*           ANIMATE INTRINS                                 *
 50*                                                           *
 51*                                                           *
 52*                                                           *
 53*                                                           *
 54*                                                           *
 55*************************************************************
 56 working-storage section.
 57 78 fals value 0.
 58 78 tru  value 1.
 59
 60 01 true-or-false               pic 9(1).
 61
 62 01 factor                      pic s9(10).
 63
 64 01 val                         pic s9(10).
 65
 66 01 indx                        pic 9(5) comp-x.
 67
 68 01 arg                         pic 9(2) comp-x  value 5.
 69
 70 01 arr                                         value "40537".
 71     03 elem   occurs 5 times   pic 9.
 72
 73 procedure division.
 74
 75 main-section.
 76
 77************************************************************
 78* Form 1 - Data item is assigned the value of the function *
 79************************************************************
 80
 81     compute factor = function factorial(0)
 82
 83************************************************************
 84* Form 2 - Function is used as a data item in an EVALUATE  *
 85*          statement                                       *
 86************************************************************
 87
 88     evaluate function integer(6.5)
 89      when 6
 90         move tru to true-or-false
 91      when other
 92         move fals to true-or-false
 93     end-evaluate
 94
 95************************************************************
 96* Form 3 - Function is used as a data item in an IF        *
 97*          statement                                       *
 98************************************************************
 99
100     if function integer (function factorial(arg)) = 120 then
101         move tru to true-or-false
102     else
103         move fals to true-or-false
104     end-if
105
106  ************************************************************
107  * Form 4 - Function uses an array element (fixed index) as *
108  *          an argument                                     *
109  ************************************************************
110
111     compute factor = function factorial(elem(4))
112
113  ************************************************************
114  * Form 5 - Function uses an array element (variable index) *
115  *          as an argument                                  *
116  ************************************************************
117
118       move 4 to indx
119       compute factor = function factorial(elem(indx))
120
121  ************************************************************
122  * Form 6 - Data item is assigned the value of a function   *
123  *          of a function                                   *
124  ************************************************************
125
126     compute factor = function factorial(
127                        function factorial(3))
128
129  ************************************************************
130  * Form 7 - Data item, assigned the value of the function,  *
131  *          is used in a COMPUTE statement                  *
132  ************************************************************
133
134     compute val = function factorial(3) + 5
135
136  ************************************************************
137  * Form 8 - Data item is assigned the value of the sum of   *
138  *          two functions                                   *
139  ************************************************************
140
141     compute val = function factorial(3) +
142                   function factorial(5)
143
144  ************************************************************
145  * Form 9 - Function is used in the UNTIL condition of a    *
146  *          PERFORM ... UNTIL statement                     *
147  ************************************************************
148
149     move 1 to indx
150     perform para-1 until function integer (function
151           factorial(indx))  = 120
152     stop run.
153
154 para-1.
155     compute indx = indx + 1.
Note:
  • Line 81
     compute factor = function factorial(0)

    Data item is assigned the value of the function

  • Lines 88-93
     evaluate function integer(6.5)
  when 6
     move tru to true-or-false
  when other
     move fals to true-or-false
 end-evaluate

    Function is used as a data item in an EVALUATE statement

  • Lines 100-104
     if function integer (function factorial(arg)) = 120 then
     move tru to true-or-false
 else
     move fals to true-or-false
 end-if

    Function is used as a data item in an IF statement

    The result of a numeric function is in floating-point format, so it cannot be expected to hold an exact integer value. In this example, the integer function is used to obtain an exact integer value for the IF statement.

  • Line 111
     compute factor = function factorial(elem(4))

    Function uses an array element (fixed index) as an argument

  • Lines 118-119
     move 4 to indx
 compute factor = function factorial(elem(indx))

    Function uses an array element (variable index) as an argument

  • Lines 126-127
     compute factor = function factorial (function factorial(3))

    Data item is assigned the value of a function of a function

  • Line 134
     compute val = function factorial(3) + 5

    Data item, assigned the value of the function, is used in a COMPUTE statement

  • Lines 141-142
     compute val = function factorial(3) + function factorial(5)

    Data item is assigned the value of the sum of two functions

  • Lines 149-155
        move 1 to indx
    perform para-1 until function integer (function
       factorial(indx)) = 120
  stop run.

 para-1.
    compute indx = indx + 1.

    Function is used in the UNTIL condition of a PERFORM ... UNTIL statement

Parent topic: Examples


Example of Bit Manipulation

The sample program logoper.cbl, shown below, illustrates the use of bit manipulation routines. It uses three of the logical call-by-name routines, namely, CBL_OR, CBL_AND, and CBL_XOR.

working-storage section.
01  clr-char            pic x value space.
01  clr-attr            pic x value x"0f".

78  text-start          value 29.
78  text-len            value 23.
78  text-end            value 51.

01  text-scr-pos.
    03  text-row        pic 9(2) comp-x value 12.
    03  text-col        pic 9(2) comp-x value text-start.
01  text-char-buffer    pic x(text-len)
                        value "Text-in-various-colours".
01  text-attr-buffer.
    03  first-word      pic x(4) value all x"0f".
    03  second-word     pic x(4) value all x"2c".
    03  third-word      pic x(7) value all x"14".
    03  third-space     pic x value x"30".
    03  fourth-word     pic x(7) value all x"59".
01  text-length         pic 9(4) comp-x value text-len.

01  char-read           pic x.
01  char-length         pic 9(9) comp-5 value 1.

01  quit-flag           pic 9 comp-x.
    88 not-ready-to-quit    value 0.
    88 ready-to-quit        value 1.

01  csr-pos.
    03  csr-row         pic 9(2) comp-x value 12.
    03  csr-col         pic 9(2) comp-x value 39.
01  csr-attr            pic x.
01  csr-length          pic 9(4) comp-x value 1.

01  blink-mask          pic x value x"80".
01  steady-mask         pic x value x"7f".

01  invert-mask         pic x(text-len) value all x"7f".

78  instr-len           value 41.
01  instr-length        pic 9(4) comp-x value instr-len.
01  instr               pic x(instr-len)
        value "Press (L)eft, (R)ight, (I)nvert or (Q)uit".
01  instr-pos.
    03  instr-row       pic 9(2) comp-x value 8.
    03  instr-col       pic 9(2) comp-x value 19.

procedure division.

main section.
    perform init-screen
    set not-ready-to-quit to true
    perform until ready-to-quit
        perform read-keyboard
        evaluate char-read
            when "L"
                perform csr-move-left
            when "R"
                perform csr-move-right
            when "I"
                perform invert-text
            when "Q"
                set ready-to-quit to true
        end-evaluate
    end-perform
    stop run
    .

init-screen section.
    call "CBL_CLEAR_SCR" using clr-char
                               clr-attr
    call "CBL_WRITE_SCR_CHARS" using instr-pos
                                     instr
                                     instr-length
    call "CBL_WRITE_SCR_CHARS" using text-scr-pos
                                     text-char-buffer
                                     text-length
    perform put-attrs-on-screen
    perform blink-cursor
    .

read-keyboard section.
    call "CBL_READ_KBD_CHAR" using char-read
    call "CBL_TOUPPER" using char-read
                             by value char-length
    .

csr-move-left section.
    perform steady-cursor
    subtract 1 from csr-col
    if csr-col < text-start
        move text-end to csr-col
    end-if
    perform blink-cursor
    .

csr-move-right section.
    perform steady-cursor
    add 1 to csr-col
    if csr-col > text-end
        move text-start to csr-col
    end-if
    perform blink-cursor
    .

blink-cursor section.

*> Turn on the blink bit at the current attribute.

    call "CBL_READ_SCR_ATTRS" using csr-pos
                                    csr-attr
                                    csr-length
    call "CBL_OR" using blink-mask
                        csr-attr
                        by value 1
    call "CBL_WRITE_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length
    .

steady-cursor section.

*> Turn off the blink bit at the current attribute.

    call "CBL_READ_SCR_ATTRS" using csr-pos
                                    csr-attr
                                    csr-length
    call "CBL_AND" using steady-mask
                         csr-attr
                         by value 1
    call "CBL_WRITE_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length
    .

invert-text section.

*> invert the bits that set the foreground colour, the background
*> colour, and the intensity bits, but leave the blink bit alone.

    call "CBL_READ_SCR_ATTRS" using text-scr-pos
                                    text-attr-buffer
                                    text-length
    call "CBL_XOR" using invert-mask
                         text-attr-buffer
                         by value text-len
    perform put-attrs-on-screen
    .

put-attrs-on-screen section.
    call "CBL_WRITE_SCR_ATTRS" using text-scr-pos
                                     text-attr-buffer
                                     text-length
    .

In the sample program, the section blink-cursor makes the cursor character (the character the cursor is pointing to) blink by its attributes. To see how you would create code to make the cursor blink, first consider the form of the display attribute. The following table shows the structure of the attribute byte for a personal computer with a monochrome display.

Bit | Attribute
7 | Blink
6-4 | Turns off display or sets reverse video
3 | Intensity
2-0 | Normal or underline select

Thus, for example, setting bit 7 to 1 turns blinking on. In the Working-Storage Section of the program, the mask for the "blink" attribute is defined as:

01 blink-mask pic x value x"80".

This hex value translates to the following bit pattern:

1 0 0 0 0 0 0 0

The CBL_READ_SCR_ATTRS routine reads the current attributes of the screen into an attribute buffer that in this case is one character long.

     call "CBL_READ_SCR_ATTRS" using csr-pos
                                     csr-attr
                                     csr-length

The CBL_OR routine does a logical OR on the current attributes and the blinking mask. This in effect turns on the blinking attribute. Note that the length parameter is 1. This says the OR operation is for one byte.

     call "CBL_OR" using blink-mask csr-attr by value 1

The CBL_WRITE_SCR_ATTRS routine writes the updated attributes buffer to the screen causing the character to "blink".

     call "CBL_OR" using blink-mask
                         csr-attr
                         by value 1
Parent topic: Examples


General Reference

  • C Functions for Calling COBOL
  • COBOL Language Reference
  • Language References
    See the reference material for the COBOL language and for .NET and JVM COBOL.
  • Command line reference
  • Compiler Directives
  • Environment Variables
  • Error Messages
  • File Handling Reference
  • Integrated Preprocessor Interface
  • Java Artifacts
  • Language Environment (LE) Support
  • Library Routines
  • Restrictions, Compiler Limits, and System Limits
  • JVM COBOL
  • Panels
  • Run-time System Configuration
  • Terminfo Database and Terminal Devices
  • UNIX Key Usage Chart
Parent topic: Visual COBOL Development Hub 5.0


C Functions for Calling COBOL

Restriction: These functions are supported for native COBOL only.

This section lists the functions that you can use from C programs to call COBOL. For more information about using these functions, see the topic Interfacing with C Programs.

  • cobaddch
    Displays the specified character on the screen at the virtual cursor's current position.
  • cobaddstr
    Displays the specified string on the screen starting at the virtual cursor's current position.
  • cobaddstrc
    Displays the specified string on the screen starting at the virtual cursor's current position.
  • cobcall
    Calls a COBOL program, subprogram or entry point from C.
  • cobcallpp
    Calls a COBOL program, subprogram or entry point from C, using a function pointer.
  • cobcancel
    Cancels a program previously loaded by the COBOL run-time system.
  • cobclear
    Clears the screen and positions the cursor at line 0, column 0.
  • cobcols
    Returns the number of columns on the screen.
  • cobcommandline
    Sets up the COBOL command line.
  • cobexit
    Closes down the global COBOL run-time environment.
  • cobfunc
    Calls a COBOL program, subprogram or entry point and then cancels it.
  • cobget
    Converts COBOL-based data to native C language types. There are a number of cobget functions, each for a different type of COBOL data.
  • cobgetch
    Gets a character from the keyboard.
  • cobgetenv
    Obtains the value of an environment variable.
  • cobgetfuncaddr
    Returns a function pointer to a COBOL program, subprogram or entry point.
  • cobinit
    Initializes the COBOL environment, so that a COBOL program can be called from a non-COBOL program.
  • cobkeypad
    Puts the numeric keypad of the terminal keypad into local mode or transmit mode.
  • coblines
    Returns the number of lines on the screen.
  • coblongjmp
    Along with the cobsetjmp() function, this function provides the capability of a non-local GO TO, for use in error or exception handling.
  • cobmove
    Moves the virtual cursor to the specified line and column on the screen.
  • cobpostsighandler
    Adds the specified handler to the list of handlers for the specified signal, at the specified priority.
  • cobprintf
    Displays the specified formatted string on the screen at the virtual cursor's current position.
  • cobput
    Converts data from native C language types to COBOL types. There are a number of cobput functions, each for a different type of COBOL data.
  • cobputenv
    Dynamically changes the value of an environment variable.
  • cobremovesighandler
    Removes a posted handler from the list of handlers for a signal.
  • cobrescanenv
    Causes the run-time system to rescan the environment for COBOL environment strings.
  • cobscroll
    Scrolls the screen display starting and finishing at the specified lines up one line.
  • cobsetjmp
    Along with the coblongjmp() function, this function provides the capability of a non-local GO TO, for use in error or exception handling.
  • cobtermmode
    Toggles the terminal screen between standard and wide modes.
  • cobthreadtidy
    Tidies up the thread-local COBOL run-time environment.
  • cobtidy
    Tidies up the global COBOL run-time environment.
  • SYSTEM
    Runs an executable via a system shell.
Parent topic: General Reference
Related information
Interfacing with C Programs


cobaddch

Displays the specified character on the screen at the virtual cursor's current position.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

void cobaddch (cobchtype ch);

Parameters:

ch The required character and any attributes.

Comments:

The specified character and attribute ch are displayed on the screen at the current position of the virtual cursor.

A character of \n (new line) is a valid character, and moves the virtual cursor to the beginning of the next line. No other control characters are valid; their use causes undefined results.

Equivalent COBOL Syntax:

None. However, this routine is similar to the COBOL syntax:

call "CBL_WRITE_SCR_CHATTRS" using ...

Example:

To display the character "X" in reverse-video, use:

cobaddch('X' | A_REVERSE)
Parent topic: C Functions for Calling COBOL


cobaddstr

Displays the specified string on the screen starting at the virtual cursor's current position.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobaddstr (const cobchtype *str);

Parameters:

str The required string and any attributes.

Comments:

The specified string of characters and attributes str is displayed starting at the current position of the virtual cursor. If the string is longer than the remaining width of the line, it wraps when it reaches the edge of the screen.

A character of \n (new line) is a valid character, and moves the virtual cursor to the beginning of the next line. The null character \0 terminates the string. No other control characters are valid; their use causes undefined results.

str cannot contain more than 255 characters.

This routine returns 0 on success.

Equivalent COBOL Syntax:

call "CBL_WRITE_SCR_CHATTRS" using ...

Example:

To display the string "HUB" with highlighting, underline and blink attributes, use:

cobchtype s[4] = { 'H' | A_BOLD, 'U' | A_UNDER, 'B' |
                  A_BLINK, 0 };

cobaddstr(s);
Parent topic: C Functions for Calling COBOL


cobaddstrc

Displays the specified string on the screen starting at the virtual cursor's current position.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobaddstrc (const cobchar_t *cstr);

Parameters:

cstr The required string.

Comments:

The specified string of characters cstr is displayed with the default attribute (A_NORMAL), starting at the current position of the virtual cursor. If the string is longer than the remaining width of the line, it wraps when it reaches the edge of the screen.

A character of \n (new line) is a valid character, and moves the virtual cursor to the beginning of the next line. The null character \0 terminates the string. No other control characters are valid; their use causes undefined results.

cstr cannot contain more than 255 characters.

This routine returns 0 on success.

Equivalent COBOL Syntax:

call "CBL_WRITE_SCR_CHARS" using ...

or

display cstr at yyxx

Example:

To display the string "Hello World" followed by a new line, use:

cobaddstrc("Hello World\n");
Parent topic: C Functions for Calling COBOL


cobcall

Calls a COBOL program, subprogram or entry point from C.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

cobrtncode_t cobcall (const cobchar_t *name, int argc,
                      cobchar_t **argv);

Parameters:

name | A null-terminated string that specifies the name of the COBOL program to be called
argc | The number of arguments passed in argv
argv | Arguments to be passed to the COBOL program

Comments:

This function is used to call the COBOL program of the specified name using the arguments passed in argv. Parameters are passed BY REFERENCE.

The result of a cobcall() is a COBOL type call as defined in the ANSI '74 standard and behaves in the same way as if the COBOL entry point had been called from COBOL.

Using this function is equivalent to calling a COBOL program directly from C code, using C syntax.

If the specified name is an entry point of an already loaded COBOL program, that program is called. Alternatively, if the specified name is a C function, then that is called. Otherwise, a program with a basename of the specified name is searched for on disk using the following search order:

  • If the sub-program is already loaded, or is statically linked, it is located and the search ends.
  • On UNIX platforms, if you are calling shared objects (.so files) without a specific path, the LD_LIBRARY_PATH or LIBPATH environment variable is searched.
  • If COBPATH is set, the list of paths in the variable are searched, in order; if COBPATH is not set, the current directory is searched.
  • The path of the calling program is searched.

If no program of the specified name can be found a run-time error is produced.

If the COBOL entry point does not expect any arguments then argc should be 0 and argv should be NULL.

Equivalent COBOL Syntax:

call "name" [using ...] [returning ...]

Example:

To call a COBOL entry point cobep with two string arguments from a C function, use either:

cobchar_t *argv[2];
argv[0] = arg1;
argv[1] = arg2;
cobcall("cobep", 2, argv);

or:

cobep(arg1, arg2);
Parent topic: C Functions for Calling COBOL
Related reference
cobgetfuncaddr


cobcallpp

Calls a COBOL program, subprogram or entry point from C, using a function pointer.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

cobrtncode_t cobcallpp (PFR rtn, int argc,
                      cobchar_t **argv);

Parameters:

var | A function pointer to the COBOL program, subprogram or entry point to be called
argc | The number of arguments passed in argv
argv | Arguments to be passed to the COBOL program

Comments:

This function is used to call a COBOL program, subprogram or entry point using a function pointer, and using the arguments passed in argv. Parameters are passed BY REFERENCE.

You can initialize rtn either by directly referencing the COBOL entry point if it is linked into the application, or by using cobgetfuncaddr(). In the latter case, the program will be searched for when cobgetfuncaddr() is called, not when cobcallpp() is called.

The result of a cobcallpp() is a COBOL type call as defined in the ANSI '74 standard and behaves in the same way as if the COBOL entry point had been called from COBOL.

If the COBOL entry point does not expect any arguments then argc should be 0 and argv should be NULL.

Equivalent COBOL Syntax:

call "name" [using ...] [returning ...]

Example:

To call a COBOL entry point cobep with two string arguments from a C function, use either:

PFR rtn = cobgetfuncaddr("cobep");
cobchar_t *argv[2];
argv[0] = arg1;
argv[1] = arg2;
cobcallpp(rtn, 2, argv);

or:

cobep(arg1, arg2);
Parent topic: C Functions for Calling COBOL
Related reference
cobgetfuncaddr


cobcancel

Cancels a program previously loaded by the COBOL run-time system.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

void cobcancel (const cobchar_t *name);

Parameters:

name A null terminated string that specifies the name of the COBOL program to be canceled.

Comments:

If name is a COBOL program, the data contained in the program is returned to its initial state as defined for the COBOL CANCEL verb.

If name is a C function then its data is unchanged.

If name does not correspond to any loaded COBOL entry point or C function no action occurs and this function returns as normal.

Equivalent COBOL Syntax:

cancel "name"

Example:

To cancel the COBOL entry point cobep:

cobcancel("cobep");
Parent topic: C Functions for Calling COBOL
Related information
The CANCEL Statement


cobclear

Clears the screen and positions the cursor at line 0, column 0.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

void cobclear (void);

Parameters:

None.

Comments:

This routine causes the screen to be cleared. The virtual cursor is reset to the home position, at line 0, column 0.

Equivalent COBOL Syntax:

call "CBL_CLEAR_SCREEN" using ...

or

display spaces upon crt

Example:

To clear the screen and display a message in the top left-hand corner, use:

cobclear();
cobaddstrc("Cursor home occurs on cobclear\n");
Parent topic: C Functions for Calling COBOL


cobcols

Returns the number of columns on the screen.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobcols (void);

Parameters:

None.

Comments:

This function returns the width in columns of the screen.

Equivalent COBOL Syntax:

call "CBL_GET_SCR_SIZE" using ...

Example:

To find out and display the width of the screen use:

int width = cobcols();

cobprintf("Width of screen = %d\n", width);
Parent topic: C Functions for Calling COBOL


cobcommandline

Sets up the COBOL command line.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

cobchar_t *cobcommandline(int flags, int *argcp,
           cobchar_t ***argvp, cobchar_t ***envpp,
           cobchar_t **namep);

Parameters:

flags | Reserved for future use. Must be 0.
argcp | Address of the argc argument passed to the C main().
argvp | Address of the argv argument passed to the C main().
envpp | Address of the envp argument passed to the C main().
namep | Reserved for future use. Should be NULL.

Comments:

This routine sets up the COBOL run-time environment with the passed command line.

If your application has a C main() and the command line is accessed from COBOL, then this routine must be called.

Equivalent COBOL Syntax:

None.

Example:

The following example shows how to use this routine:

main(int argc, char **argv, char **envp)
{
    cobinit();
    cobcommandline(0, &argc, &argv, &envp, NULL);

    /* Rest of code here */

    cobexit(0);
}
Parent topic: C Functions for Calling COBOL


cobexit

Closes down the global COBOL run-time environment.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobmain.h"

void cobexit (cobrtncode_t exitstatus);

Parameters:

exitstatus The exit status returned to the calling process.

Comments:

This function terminates a running application in the same way as if a COBOL STOP RUN statement had been executed, emptying buffers, closing files and freeing any data areas allocated by the COBOL system.

You must use the cobexit() function to exit from non-COBOL applications rather than just using the C library function exit().

This function will ultimately call exit() and so will not return.

The specified exit status is returned to the calling process. Standard operating system practice is to use an exit status of 0 on success.

The COBOL run-time system returns values of -1 (255) and -2 (254) if it exits due to an error or signal.

Equivalent COBOL Syntax:

stop run

Example:

To exit an application that has used COBOL, returning an error value of +123 to the parent process, use

cobexit(123);.
Parent topic: C Functions for Calling COBOL


cobfunc

Calls a COBOL program, subprogram or entry point and then cancels it.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

cobrtncode_t cobfunc (const cobchar_t *name, int argc,
                     cobchar_t **argv);

Parameters:

name | A null-terminated string that specifies the name of the COBOL program or entry point to be called
argc | The number of arguments passed in argv
argv | Arguments to be passed to the COBOL program

Comments:

This function has the same effect as specifying cobcall() and then cobcancel(). That is, it calls the specified program and then cancels it, leaving the data contained in the program in its initial state. See the descriptions of cobcall() and cobcancel() for more details.

This function, unlike cobcall(), causes the program to behave as if it had been called using C function rules rather than COBOL call rules. cobfunc() returns the return code of the called program.

Equivalent COBOL Syntax:

call "name" [using ...] [returning ...]
cancel "name"

Example:

To call and then cancel a COBOL entry point cobep which takes no arguments use:

cobfunc("cobep", 0, NULL);
Parent topic: C Functions for Calling COBOL
Related reference
cobcall
cobcancel


cobget

Converts COBOL-based data to native C language types. There are a number of cobget functions, each for a different type of COBOL data.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cbltypes.h"    /* Includes cbltypes.h and cobgetput.h */

cobuns8_t   cobget_x1_compx(const cbl_x1_compx_t *cbldata);
cobuns16_t  cobget_x2_compx(const cbl_x2_compx_t *cbldata);
cobuns32_t  cobget_x4_compx(const cbl_x4_compx_t *cbldata);
cobuns64_t  cobget_x8_compx(const cbl_x8_compx_t *cbldata);

cobuns8_t   cobget_x1_comp5(const cbl_x1_comp5_t *cbldata);
cobuns16_t  cobget_x2_comp5(const cbl_x2_comp5_t *cbldata);
cobuns32_t  cobget_x4_comp5(const cbl_x4_comp5_t *cbldata);
cobuns64_t  cobget_x8_comp5(const cbl_x8_comp5_t *cbldata);

cobs8_t     cobget_sx1_comp5(const cbl_sx1_comp5_t *cbldata);
cobs16_t    cobget_sx2_comp5(const cbl_sx2_comp5_t *cbldata);
cobs32_t    cobget_sx4_comp5(const cbl_sx4_comp5_t *cbldata);
cobs64_t    cobget_sx8_comp5(const cbl_sx8_comp5_t *cbldata);

cobuns64_t  cobget_xn_comp5(const cbl_x1_t *cbldata, cobuns8_t n);
cobuns64_t  cobget_xn_compx(const cbl_x1_t *cbldata, cobuns8_t n);

cobs64_t    cobget_sxn_comp5(const cbl_x1_t *cbldata, cobuns8_t n);

void       *cobget_pointer(const cbl_pointer_t *cbldata);
PFR         cobget_ppointer(const cbl_ppointer_t *cbldata);

Parameters:

cbldata | Pointer to the COBOL data item and data description as indicated by the cobget function name.
n | For cobget_xn_ functions. Describes the number of COBOL character positions cbldata occupies.

Comments:

The cobget_xn_compx functions enable you to extract data from data items with descriptions such as PIC X(3).

Equivalent COBOL Syntax:

None.

Example:

COBOL program:

program-id.  mycblprog.

 copy "cbltypes.cpy".

 01  myrec.
      05 myrec-key   		cblt-x4-compx value 10.
 procedure division.
     call 'mycprog'  using myrec-key
     if  myrec-key = 20
         display "First call to 'mycblprog'"
     else
         display "Subsequent call to 'mycblprog'"
     end-if
     exit program
 end program mycblprog.

C program:

#include "cbltypes.h"
 void
 mycprog(cbl_x4_compx_t *cbldata)
 {
  cobput_x4_compx(cbldata, cobget_x4_compx(cbldata) + 10);
 }
Parent topic: C Functions for Calling COBOL
Related reference
cobput
Related information
Passing Data between C and COBOL
Interfacing with C Programs
Signal Handling Overview


cobgetch

Gets a character from the keyboard.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobgetch (void);

Parameters:

None.

Comments:

Reads a character from the keyboard and returns it. If no character is pending this routine waits until a key is pressed.

A value of -1 is returned on error (for example, EOF).

Equivalent COBOL Syntax:

call "CBL_READ_KBD_CHAR" using ...

Example:

The following code asks for a Yes/No response:

int ch;

cobaddstrc("Continue [y/n]? ");

ch = cobgetch();

if (ch == 'Y' || ch == 'y')
{
    /* Yes */
Parent topic: C Functions for Calling COBOL


cobgetenv

Obtains the value of an environment variable.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobenv.h"

cobchar_t *cobgetenv(const cobchar_t *name);

Parameters:

name A null-terminated string, specifying the environment variable name to be searched for.

Comments:

This function provides the same functionality as the C library call getenv(). The specified environment variable is searched for and returned. If the environment variable does not exist then NULL is returned.

Equivalent COBOL Syntax:

display name upon environment-name
accept ... from environment-value

Example:

The following code displays the value of $COBDIR:

cobchar_t *cobdir;

if ((cobdir = cobgetenv("COBDIR")) == NULL)
    cobdir = "<unset>";

cobprintf("COBDIR=%s\n", cobdir);

cobchar_t *cobdir;

if ((cobdir = cobgetenv("COBDIR")) == NULL)
    cobdir = "<unset>";

printf("COBDIR=%s\n", cobdir);
Parent topic: C Functions for Calling COBOL
Related reference
cobputenv


cobgetfuncaddr

Returns a function pointer to a COBOL program, subprogram or entry point.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobcall.h"

PFR cobgetfuncaddr(int type, const cobchar_t *name);

Parameters:

type
Indicates what is returned if the specified program is not found.
Bit | Description
0 Can be either 0 or 1, where
  • 0 means a null pointer is returned
  • 1 means the address of an error function is returned
1-31 | Reserved
name
A null terminated string that specifies the name of the COBOL program to be found.

Comments:

This function returns a function pointer to the COBOL program of the specified name.

If the specified name is an entry point of an already loaded COBOL program, that program is used. Alternatively, if the specified name is a C function, then that is used. Otherwise, a program with a basename of the specified name is searched for on disk using the standard COBOL search order and paths.

If an error function is returned (bit 0 set to 1) and it is subsequently called then a run-time error is produced, as for cobcall().

This function only loads the program of the specified name; it does not call it. This enables programs to be preloaded. This is especially useful if you want to call an entry point within the program, but not the main entry point of the program.

Equivalent COBOL Syntax:

set procedure-pointer to entry "name"

Example:

The following C code calls a COBOL program cobprog with two arguments, coping with any error condition:

PFR cobprog;

if ((cobprog = cobgetfuncaddr(0, "cobprog")) == NULL)
{
    /* Error case */
}
else
{
    /* Loaded */
    (*cobprog)(arg1, arg2);    /* Call it! */
}
Parent topic: C Functions for Calling COBOL
Related concepts
cobcallpp


cobinit

Initializes the COBOL environment, so that a COBOL program can be called from a non-COBOL program.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobmain.h"

int cobinit (void);

Parameters:

None.

Comments:

You must call cobinit() before calling a COBOL program if the main program is not written in COBOL.

If you do not, you might receive an initialization error when you enter your COBOL code.

On some platforms, the COBOL environment is initialized when the COBOL run-time system is loaded (for example, at process startup).

If the COBOL environment has already been initialized then cobinit() returns successfully.

This function returns 0 on success.

Equivalent COBOL Syntax:

None.

Example:

The following example shows how to initialize (and close down) the COBOL environment from a C main(), so that a COBOL program can be called:

main(int argv, char *argv)
{
    cobinit();             /* Initialize COBOL environment */

    cobcall("cobep", 0, NULL); /* Call a COBOL program */

    cobtidy();             /* Close down COBOL environment */

    return(0);
)
Parent topic: C Functions for Calling COBOL


cobkeypad

Puts the numeric keypad of the terminal keypad into local mode or transmit mode.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

void cobkeypad(int mode);

Parameters:

mode The keypad mode; either 0 or 1.

Comments:

This routine puts the numeric keypad of the terminal keypad (if there is one) into local mode or transmit mode. To function correctly, the smkx (transmit mode) and rmkx (local mode) entries must be present in the terminfo database for the terminal type you are using.

The mode parameter should be 0 to put the keypad into local mode or 1 to put the keypad into transmit mode. Any other value is undefined.

By default, the run-time system puts the numeric keypad into transmit mode when smkx is present in your terminfo database.

Equivalent COBOL Syntax:

None.

Parent topic: C Functions for Calling COBOL


coblines

Returns the number of lines on the screen.
Note: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int coblines (void);

Parameters:

None.

Comments:

This function returns the depth in lines of the screen.

Equivalent COBOL Syntax:

call "CBL_GET_SCR_SIZE" using ...

Example:

To find out and display the depth of the screen use:

int depth = coblines();

cobprintf("Depth of screen = %d\n", depth);
Parent topic: C Functions for Calling COBOL


coblongjmp

Along with the cobsetjmp() function, this function provides the capability of a non-local GO TO, for use in error or exception handling.
Restriction:

This function is supported for native COBOL only.

Syntax:

#include "cobsetjmp.h"

void coblongjmp(struct cobjmp_buf *buf);

Parameters:

buf A buffer in which the current execution environment is saved.

Comments:

The cobsetjmp() function saves the environment of the current COBOL program and C function in the buffer pointed to by buf. It calls the C library function setjmp(), which immediately returns a value of 0.

A subsequent call to coblongjmp() either from elsewhere in the C function that called cobsetjmp(), or from one of its C or COBOL subprograms, causes execution to be resumed at the point immediately after the call to cobsetjmp().

After calling coblongjmp(), cobsetjmp() returns a non-zero value, thus enabling the value to be tested after the cobsetjmp() call.

The following restrictions apply when using the coblongjmp() and cobsetjmp() functions:

  • cobsetjmp() and coblongjmp() can be called from a C program only; they cannot be called from COBOL.
  • coblongjmp() must be called from the same or from a lower level in the CALL/PERFORM hierarchy of control flow as cobsetjmp(). In the intervening time, control must not have been returned to a higher level. Specifically, control must not have been returned from the C function that called cobsetjmp().
  • If coblongjmp() returns control to a different call level than that used by cobsetjmp(), programs exited by this mechanism appear to have been exited normally and can be called again later in the program's run.
  • coblongjmp() cannot be used if a CHAIN has been made since cobsetjmp() was last called.
  • coblongjmp() cannot be used in an error procedure, exit procedure or asynchronous signal handler.
  • coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().
  • coblongjmp() does not reset any thread synchronization objects that have been initialized or changed since the corresponding cobsetjmp(). These may need be reset to prevent potential thread deadlocks.
  • coblongjmp() does not free any memory allocated since the corresponding cobsetjmp(), which could lead to memory leaks.

Equivalent COBOL Syntax:

None.

Example:

The following shows how to use the coblongjmp() and cobsetjmp() functions:

void
some_c_func(void)
{
    struct cobjmp_buf buf;

    if (cobsetjmp(&buf) != 0)
    {
        cobprintf("Returned from coblongjmp\n");
        return;
    }

    /* Valid code here - for example can call COBOL */

    coblongjmp(&cobjmp_buf);
}
Parent topic: C Functions for Calling COBOL


cobmove

Moves the virtual cursor to the specified line and column on the screen.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

void cobmove (int y, int x);

Parameters:

y | The line number to move the virtual cursor to
x | The column number to move the virtual cursor to

Comments:

The virtual cursor as used by the routines in this section is moved to the line and column values as specified by the y and x parameters.

The virtual cursor home position of the top left-hand corner is (0,0), that is, a y value of 0 and an x value of 0. The virtual cursor is thread-local, that is, each thread has its own virtual cursor.

Equivalent COBOL Syntax:

call "CBL_PUT_SCR_POS" using ...

Example:

The following code displays a simple counter:

int secs = 10;
char *message = "Time Left: ";

cobmove(10, 10);
cobprintf("%s%d", message, secs);
while (secs--)
{
    sleep(1);
    cobmove(10, 10 + strlen(message));
    cobprintf("%2d", secs);
}
Parent topic: C Functions for Calling COBOL


cobpostsighandler

Adds the specified handler to the list of handlers for the specified signal, at the specified priority.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobsignal.h"

cobsigtype_t cobpostsighandler (int signal, int priority,
    PFI_SIG handler);

Parameters:

signal | Signal number, as defined in the <signal.h> include file.
priority | The priority of handler in the range 1 to 254, where 254 is the highest priority. Values 127 and 129 through 139 are reserved for our use.
handler | Address of your signal handler. This must be a C function that returns an integer value.

Comments:

  • This function adds the specified handler to the list of handles for the specified signal, at the specified priority.
  • This function returns a pointer that you can use to remove your signal handler later. If the return value is NULL, a signal handler was not posted for this signal. This could be due to lack of memory or the signal being disabled by the signal_regime run-time tunable.
  • Refer to cobsignal.h for the definition of PFI_SIG, which defines the additional information that is passed to your handler.

Equivalent COBOL Syntax:

None.

Parent topic: C Functions for Calling COBOL
Related reference
cobremovesighandler
signal_regime
Related information
Signal Handling Overview
Example of Posting a Signal Handler
Third Party Software that Uses Signals
cobremovesighandler
signal_regime


cobprintf

Displays the specified formatted string on the screen at the virtual cursor's current position.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobprintf (const cobchar_t *fmt, ...);

Parameters:

fmt The formatted string to display

Comments:

The formatted character string fmt is displayed with the default attribute (A_NORMAL), starting at the current position of the virtual cursor. If the string is longer than the remaining width of the line it wraps when it reaches the edge of the screen.

The fmt parameter is formatted as it would be by the C library routine, printf(). For example, any %s in fmt is substituted for the string in the subsequent arguments passed to cobprintf().

The character \n (new line) is a valid character and moves the virtual cursor to the beginning of the next line. The null character \0 terminates the string. No other control characters are valid; their use causes undefined results.

The specified string must not be longer than 255 characters in length when fmt has been fully expanded.

This routine returns either the number of arguments output or -1 for an error condition.

Equivalent COBOL Syntax:

None.

Example:

The following code displays a simple counter:

int secs = 10;
char *message = "Time Left: ";

cobmove(10, 10);
cobprintf("%s%d", message, secs);
while (secs--)
{
    sleep(1);
    cobmove(10, 10 + strlen(message));
    cobprintf("%2d", secs);
}
Parent topic: C Functions for Calling COBOL


cobput

Converts data from native C language types to COBOL types. There are a number of cobput functions, each for a different type of COBOL data.
Restriction: This function is supported for native COBOL only.

Syntax:

include "cbltypes.h"    /* Includes cbltypes.h and cobgetput.h */

void        cobput_x1_compx(cbl_x1_compx_t *cbldata, cobuns8_t val);
void        cobput_x2_compx(cbl_x2_compx_t *cbldata, cobuns16_t val);
void        cobput_x4_compx(cbl_x4_compx_t *cbldata, cobuns32_t val);
void        cobput_x8_compx(cbl_x8_compx_t *cbldata, cobuns64_t val);

void        cobput_x1_comp5(cbl_x1_comp5_t *cbldata, cobuns8_t val);
void        cobput_x2_comp5(cbl_x2_comp5_t *cbldata, cobuns16_t val);
void        cobput_x4_comp5(cbl_x4_comp5_t *cbldata, cobuns32_t val);
void        cobput_x8_comp5(cbl_x8_comp5_t *cbldata, cobuns64_t val);

void        cobput_sx1_comp5(cbl_sx1_comp5_t *cbldata, cobs8_t val);
void        cobput_sx2_comp5(cbl_sx2_comp5_t *cbldata, cobs16_t val);
void        cobput_sx4_comp5(cbl_sx4_comp5_t *cbldata, cobs32_t val);
void        cobput_sx8_comp5(cbl_sx8_comp5_t *cbldata, cobs64_t val);

void        cobput_xn_comp5(cbl_x1_t *cbldata, cobuns8_t n, cobuns64_t vall);
void        cobput_xn_compx(cbl_x1_t *cbldata, cobuns8_t n, cobuns64_t val);

void        cobput_sxn_comp5(cbl_x1_t *cbldata, cobuns8_t n, cobs64_t val);

void        cobput_pointer(cbl_pointer_t *cbldata, void *val);
void        cobput_ppointer(cbl_ppointer_t *cbldata, PFR val);

Parameters:

cbldata | Pointer to the COBOL data item and data description as indicated by the cobget function name.
val | Value to be placed in the COBOL data item cbldata.

Comments:

The cobput_xn_compx functions enable you to put data into data items with descriptions such as PIC X(3).

Equivalent COBOL Syntax:

None.

Example:

COBOL program:

program-id.  mycblprog.

 copy "cbltypes.cpy".

 01  myrec.
      05 myrec-key   		cblt-x4-compx value 10.
 procedure division.
     call 'mycprog'  using myrec-key
     if  myrec-key = 20
         display "First call to 'mycblprog'"
     else
         display "Subsequent call to 'mycblprog'"
     end-if
     exit program
 end program mycblprog.

C program:

#include "cbltypes.h"
 void
 mycprog(cbl_x4_compx_t *cbldata)
 {
  cobput_x4_compx(cbldata, cobget_x4_compx(cbldata) + 10);
 }
Parent topic: C Functions for Calling COBOL
Related reference
cobget
Related information
Passing Data between C and COBOL
Interfacing with C Programs
Signal Handling Overview


cobputenv

Dynamically changes the value of an environment variable.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobenv.h"

int cobputenv (const cobchar_t *envstr);

Parameters:

envstr
The null terminated string to be placed into the environment.

Comments:

The environment string envstr is put into the environment. By convention, environment strings have the format:

NAME=VALUE

but the run-time system does not check that envstr is in this format.

This function ultimately passes envstr into the C library function putenv(), which puts envstr into the operating system environment.

This function returns a value of zero if the operation was successful; any other value indicates an unsuccessful operation. Illegal environment names lead to undefined results.

Equivalent COBOL Syntax:

display name upon environment-name
display value upon environment-value

Example:

The following code shows how to set $ABC to XYZ:

cobputenv("ABC=XYZ");
Parent topic: C Functions for Calling COBOL


cobremovesighandler

Removes a posted handler from the list of handlers for a signal.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobsignal.h"

void cobremovesighandler (cobsigtype_t sighandler);

Parameters:

sighandler Pointer returned when posting your signal handler using a previous cobpostsighandler() call.

Comments:

This function removes a previously posted signal handler.

There is no return value from this function.

Equivalent COBOL Syntax:

None.

Parent topic: C Functions for Calling COBOL
Related reference
cobpostsighandler
signal_regime
Related information
Signal Handling Overview
Example of Posting a Signal Handler
Third Party Software that Uses Signals


cobrescanenv

Causes the run-time system to rescan the environment for COBOL environment strings.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobenv.h"

int cobrescanenv(void);

Parameters:

None.

Comments:

This function causes the run-time system to rescan the environment for COBOL environment strings, such as file-name mapping entries (that is, dd_ entries). This can be useful if the environment has been changed without the knowledge of the run-time system.

A value of zero is returned on success; any other value indicates an unsuccessful call.

Equivalent COBOL Syntax:

None.

Example:

The following code shows how to set a dd_ environment variable so that an open of file abc will instead open xyz:

cobputenv("dd_abc=xyz");
cobrescanenv();
Parent topic: C Functions for Calling COBOL
Related information
Filename Mapping


cobscroll

Scrolls the screen display starting and finishing at the specified lines up one line.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

void cobscroll (int top, int bot);

Parameters:

top | The first line of the area of screen to be scrolled up one line. This must be two lines less than the physical screen size to prevent the top line from scrolling off the screen.
bot | The last line of the area of screen to be scrolled up one line

Equivalent COBOL Syntax:

None.

Example:

The top line of the screen is 0. The bottom line of the screen can be found using coblines(). Hence, to scroll the entire screen use:

cobscroll(0, coblines() - 1);
Parent topic: C Functions for Calling COBOL


cobsetjmp

Along with the coblongjmp() function, this function provides the capability of a non-local GO TO, for use in error or exception handling.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobsetjmp.h"

int cobsetjmp(struct cobjmp_buf *buf);

Parameters:

buf A buffer in which the current execution environment is saved.

Comments:

The cobsetjmp() function saves the environment of the current COBOL program and C function in the buffer pointed to by buf. It calls the C library function setjmp(), which immediately returns a value of 0.

A subsequent call to coblongjmp() either from elsewhere in the C function that called cobsetjmp(), or from one of its C or COBOL subprograms, causes execution to be resumed at the point immediately after the call to cobsetjmp().

After calling coblongjmp(), cobsetjmp() returns a non-zero value, thus enabling the value to be tested after the cobsetjmp() call.

The following restrictions apply when using the coblongjmp() and cobsetjmp() functions:

  • cobsetjmp() and coblongjmp() can be called from a C program only; they cannot be called from COBOL.
  • coblongjmp() must be called from the same or from a lower level in the CALL/PERFORM hierarchy of control flow as cobsetjmp(). In the intervening time, control must not have been returned to a higher level. Specifically, control must not have been returned from the C function that called cobsetjmp().
  • If coblongjmp() returns control to a different call level than that used by cobsetjmp(), programs exited by this mechanism appear to have been exited normally and can be called again later in the program's run.
  • coblongjmp() cannot be used if a CHAIN has been made since cobsetjmp() was last called.
  • coblongjmp() cannot be used in an error procedure, exit procedure or signal handler.
  • coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().
  • coblongjmp() does not reset any thread synchronization objects that have been initialized or changed since the corresponding cobsetjmp(). These may need be reset to prevent potential thread deadlocks.
  • coblongjmp() does not free any memory allocated since the corresponding cobsetjmp(), which could lead to memory leaks.

Equivalent COBOL Syntax:

None.

Example:

The following shows how to use the coblongjmp() and cobsetjmp() functions:

void
some_c_func(void)
{
    struct cobjmp_buf buf;

    if (cobsetjmp(&buf) != 0)
    {
        cobprintf("Returned from coblongjmp\n");
        return;
    }

    /* Valid code here - for example can call COBOL */

    coblongjmp(&cobjmp_buf);
}
Parent topic: C Functions for Calling COBOL


cobtermmode

Toggles the terminal screen between standard and wide modes.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobtermmode(const cobuns8_t *mode);

Parameters:

mode The terminal mode; the address of a byte that is either 0 or 1.

Comments:

This routine toggles the terminal screen between default and wide modes, if this functionality is present in the terminfo database for the terminal type you are using.

To function correctly, the terminfo database must support a terminal whose name is the current terminal type with a -w suffix, and the terminfo entries must also have appropriate initialization and/or reset capabilities. For example, if the current terminal is vt100 then there also needs to be a vt100-w in the terminfo database and the vt100 and vt100-w need appropriate is1, is2, is3, rs1, rs2 and/or rs3 entries.

The mode parameter should be 0 to put the terminal into standard (default) terminal mode or 1 to put the terminal into wide terminal mode. Any other value gives undefined results.

When the terminal mode is successfully toggled, the screen handling system is initialised (if it wasn't already), the screen is cleared and the cursor positioned in the home position.

This routine can be safely called from COBOL. See the section Wide Terminal Modein the chapter Terminfo Database and Terminal Devices of yourUser's Guide for more details.

When using this routine, you must be aware of the following:

  • The number of columns in wide mode must not exceed 255
  • When running under Animator, this call causes the terminal to be initialized to the new mode which can produce some flicker of the display. Switching between Animator and user screens causes mode changes as the wide terminal mode is not supported for Animator's screen.
  • When the run-time system exits, the terminal is restored to normal mode. This applies only to mode changes made under the control of this call.
  • The usual terminfo path-searching rules are used. Therefore, if the directory pointed to by COBTERMINFO contains an entry for the terminal in normal mode, but not wide mode and the system terminfo directory does contain an entry for the terminal in wide mode, the normal mode uses the COBTERMINFO version and the wide mode uses the system version. This can cause unexpected results where the two files differ in capabilities other than column size changes.

    See the chapter Terminfo Database and Terminal Devicesin yourUser's Guide for more details on the terminfo search order.

  • If you have already set the TERM environment variable to indicate that a wide mode is required (that is the TERM value already has a -w suffix), issuing the call to use wide mode results in a suffix of "-w-w". This almost certainly fails, unless the terminal has a double wide mode and a terminfo file for this mode is available.

This routine returns 0 on success, non-zero on error. The following error values are currently returned

1 | The terminfo file has not been found, is not readable, is corrupt or there is not enough memory.
2 | The terminfo file does not contain one or more of the required capabilities.
3 | The environment does not support the requested code.

Equivalent COBOL Syntax:

call "cobtermmode" using mode

Example:

The following code switches the terminal into wide mode, displays some text, waits for a keypress and restores the terminal back to normal mode:

cobuns8_t mode_on=1, mode_off=0;

if (cobtermmode(&mode_on) == 0)
{
    /* Display some text over beyond column 80 to demo */
    /* wide mode */
    cobmove(10, 100);
    cobprintf("Line 10, Column 100");
    cobgetch();
    /* Wait for a key press */

    cobtermmode(&mode_off);
    /* Back into standard mode */
}
Parent topic: C Functions for Calling COBOL
Related information
Wide Terminal Mode
Terminfo Database and Terminal Devices


cobthreadtidy

Tidies up the thread-local COBOL run-time environment.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobmain.h"

int cobthreadtidy(void);

Parameters:

None.

Comments:

This function deinitializes the COBOL environment for the current thread, cleaning up any thread-state information and freeing any data allocated as thread-local. It returns 0 on success.

This function can be used only when the current thread was created by non-COBOL API calls; that is, if the thread was created by C library, operating system or third-party threading API calls. It must not be called if the thread was created by COBOL syntax or the CBL_THREAD_CREATE library routine. You cannot call cobthreadtidy() directly from a COBOL program.

You should call this function only when all COBOL modules have been exited in this thread and you do not intend to reenter them. If you do call any COBOL entry points or COBOL routines (such as cobinit()) after you have called cobthreadtidy(), the results are undefined.

Equivalent COBOL Syntax:

None.

Example:

When a C thread is created, you need to specify a C function that is the initial entry point for the thread. If this entry point is c_thread(), then the following shows how to:

  • Call a COBOL entry point cobep which takes no arguments
  • Call cobthreadtidy() before the thread dies
c_thread(void)
{
    cobinit();                  /* Only required if not   */
                                /* already called in this */
                                /* process                */
    cobcall("cobep", 0, NULL);  /* Call COBOL */
    cobthreadtidy();            /* Tidy up COBOL in this  */
                                /* thread */

    return 0;                   /* Exit thread */
}
Parent topic: C Functions for Calling COBOL


cobtidy

Tidies up the global COBOL run-time environment.
Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobmain.h"

int cobtidy (void);

Parameters:

None.

Comments:

This function deinitializes the COBOL environment, emptying buffers, closing files and freeing any data areas allocated by the COBOL system.

Use this function if you want to close down the COBOL system, but are not yet ready to exit. It returns 0 on success.

Do not call cobtidy() directly from a COBOL program.

You can call this function only when all COBOL modules have been exited, and you do not intend to re-enter them. If you do call any COBOL entry points or COBOL routines (such as cobinit()) after you have called cobtidy(), the results are undefined.

Equivalent COBOL Syntax:

None.

Example:

The following example shows how to initialise and close down the COBOL environment from a C main(), so that a COBOL program can be called:

main(int argv, char *argv)
{
    cobinit();            /* Initialize COBOL environment */

    cobcall("cobep", 0, NULL); /* Call a COBOL program */

    cobtidy();            /* Close down COBOL environment */

    return(0);
}
Parent topic: C Functions for Calling COBOL


SYSTEM

Runs an executable via a system shell.
Restriction: This function is supported for native COBOL only.

Syntax:

#include <sys/wait.h>

int SYSTEM (const unsigned char *cmd);

Parameters:

cmd A null-terminated system command line to be executed.

Comments:

The specified command line is passed to a shell and executed, as for the C library routine system().

As the COBOL environment is unaware of any output from another process, such as the shell or command executed during SYSTEM(), you must ensure that the screen is either not updated during the SYSTEM() call or is redisplayed after execution of the call.

The return value from this routine is the same format as that returned from the C library routine system(). There are macros in the C library include file sys/wait.h to manipulate this value and get the return code of the executed command. See your system documentation for more information.

Equivalent COBOL Syntax:

call "CBL_EXEC_RUN_UNIT" using ...

Example:

The code below copies one file to another, redirecting standard output and standard error to an error file (which could be subsequently opened and read to see if any output was generated by running the command) and displays the return code of the command:

int res;

res = SYSTEM("cp f1 f2 > errfile 2>&1");

if (WIFEXITED(res))
    cobprintf("Exit status: %d\n", WEXITSTATUS(res));
Parent topic: C Functions for Calling COBOL


COBOL Language Reference

  • COBOL Language Supported and Copyrights
  • Notations
  • Part 1. Concepts
  • Part 2. Program Definition
  • Part 3. Additional Topics
  • Part 4: Appendices
Parent topic: General Reference
Related reference
Managed COBOL Reference


COBOL Language Supported and Copyrights

This describes the base COBOL language supported by this system: this COBOL language is based on the ANSI COBOL standards X3.23-1985, X3.23a-1989 and X3.23b-1993, and is supported by a number of COBOL systems. In addition, support has been added for some of the features from ISO/IEC 1989:2002, Programming language COBOL.

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL Programming Language Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection herewith.

The authors and copyright holders of the copyrighted material used herein:

  • FLOW-MATIC Programming for the Univac I and II, Data Automation Systems copyrighted 1958,1959, by Sperry Rand Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell

have specifically authorized the use of this material in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications.

Parent topic: COBOL Language Reference


Notations

Throughout this book, the following notation is used to describe the format of COBOL statements:

  1. Words printed in capital letters which are underlined must always be present when the functions of which they are a part are used. An error will be reported by your COBOL system if the underlined words are absent or incorrectly spelled. The underlining is not necessary when writing a COBOL source program.
  2. Words printed in capital letters which are not underlined are used in the COBOL source program for readability only. They may be written, or not, as the programmer wishes, but if written, must be correctly spelled.
  3. All words printed in small letters are generic terms representing names which will be devised by the programmer.
  4. When material is enclosed in braces { }, a choice must be made from the options within them.
  5. When material is enclosed in choice indicators { | | } (or sometimes simply | |), one or more of the unique options must be specified, but a single option may be specified only once.
  6. When material is enclosed in square brackets [ ] , it is an indication that the material is an option which may be included or omitted as required.
  7. When material is enclosed in boxed, square brackets:

    it is an indication that the material is mandatory for ANSI'74 COBOL (American National Standards Institute publication X3.23-1974) but may be optionally omitted as an extension to that language specification. The symbol adjacent to the box or appearing in the margin indicates the dialects of COBOL in which that material is optional. See rule 12 for further details on dialect features.

  8. In text, the ellipsis (...) shows the omission of a portion of a source program or a sequence. This meaning becomes apparent in context.

    In the General Formats, the ellipsis represents the position at which repetition may occur at the user's option. The portion of the format that may be repeated is determined as follows:

    Given ... in a clause or statement format, scanning right to left, determine the } or ] immediately to the left of the ...; continue scanning right to left and determine the logically matching { or [; the ... applies to the words between the determined pair of delimiters.

  9. In the text, any required relational characters '<', '>', and '=' are not underlined to avoid confusion with other symbols such as '>' (greater than or equal to).
  10. Where the term "integer" appears in the general formats, integer must be a numeric literal which is an integer, and must be neither signed nor zero unless explicitly allowed by the rules of that format.
  11. This Reference presents the syntax of IBM SAA AD/Cycle COBOL370 (COBOL/370) statements and the rules for writing source programs that are to be compiled by the COBOL/370 compiler.

    The only distinction Micro Focus COBOL makes between COBOL/370 and IBM VS COBOL II is that for the procedure-pointer format, the default length is eight bytes rather than four bytes.

  12. This Reference presents the syntax of Multivendor Integration Architecture (MIA) - Technical Requirements for the programming language COBOL. No boxes or dialect symbols for MIA are used in this book.
  13. The COBOL language accepted by most COBOL compilers includes extensions to the COBOL language defined in American National Standard X3.23-1974. Different compilers allow different extensions to this standard which means that different versions, called 'dialects', of COBOL exist. This COBOL product is designed for use in cross-development; it can be used for developing not only programs for use on your COBOL system itself but also programs for use with IBM OS/VS COBOL, IBM VS COBOL II, IBM COBOL/370 or IBM COBOL for OS/390 & V2R2, or programs that conform entirely to ANS X3.23-1974 or its successor ANS X3.23-1985. It allows most extensions that are in the IBM COBOLs, and all the features from ANS X3.23-1985 and X3.23a-1989.

    To help you keep to the appropriate dialect - that of your target system - this book shows the dialects in which each feature appears:

    • In the text, features outside ANS X3.23-1974 are in separate paragraphs, with a symbol indicating the dialect at the start of the paragraph.
    • Where a complete section is a separate dialect, the heading of the section is followed by a symbol in a paragraph by itself.
    • A phrase which is part of a separate dialect is separated out into a paragraph on its own, marked as indicated above.
    • In syntax diagrams, features outside ANS X3.23-1974 are enclosed in boxes, with symbols adjacent to the boxes or in the margin. For example:

    The symbols used are as follows:

    OSVS | These features are extensions to ANS X3.23-1974 that appear in IBM OS/VS COBOL.
    VSC2 | These features are extensions to ANS X3.23-1985 that appear in IBM VS COBOL II.
    COB370 | These features are extensions to ANS X3.23-1985 that are supported in IBM SAA AD/Cycle COBOL/370, but not in IBM VS COBOL II.
    OS390 | These features are extensions to ANS X3.23-1985 that are supported in IBM COBOL for OS/390 & V2R2, but not in IBM SAA AD/Cycle COBOL/370.
    ENT | These features are extensions to ANS X3.23-1985 that are supported in Enterprise COBOL for z/OS, but not IBM COBOL for OS/390.
    ANS85 | These features are features defined in ANS X3.23-1985 which are not supported under ANS X3.23-1974.
    XOPEN | These features are extensions to ANS X3.23-1985 that appear in the X/Open CAE Specification, COBOL language (XPG-4).
    MF | These features are extensions to ANS X3.23-1985 that are specific to Micro Focus COBOL.
    ISO2002 | These features are features defined in ISO/IEC 1989:2002 which are not supported under ANS X3.23-1985.
    NET | These Micro Focus features are only supported under the Microsoft .NET managed CLR platform. These features may be referred to as COBOL for .NET or NET COBOL.
    JVM | These Micro Focus features are only supported under the JVM managed platform. These features may be referred to as COBOL for JVM or JVM COBOL.
    Note:
    • The Micro Focus, VS COBOL II, COBOL/370, OS/390 and X/Open dialects are all based on the ANS X3.23-1985 COBOL Standard. Therefore, any syntax (or rules) which are marked as valid for ANS85 are also valid for Micro Focus, VS COBOL II, COBOL/370, OS/390 and X/Open unless explicitly designated otherwise.
    • The COBOL/370 dialect includes all of the syntax included in VS COBOL II which is marked with a VSC2 bubble in this book. The only time that a COB370 bubble appears in this book are cases where COBOL370 (with the NOCMPR2 compiler option) includes additional or different text than that included with VS COBOL II (with the NOCMPR2 compiler option).
    • The OS390 dialect includes all of the syntax included in VS COBOL II that is marked with a VSC2 bubble. The only time that an OS390 bubble appears in this book are cases where OS390 (with the NOCMPR2 compiler option) includes additional or different text than that is included with VS COBOL II (with the NOCMPR2 compiler option).
    • The Enterprise Cobol dialect includes all of the syntax included in VS COBOL II which is marked with a VSC2 bubble. The only time that an ENT bubble appears in this book is in cases where Enterprise Cobol (with the NOCMPR2 compiler option) includes additional or different text than that included with VS COBOL II (with the NOCMPR2 compiler option).

    These bubbles reflect support only for a particular syntax and its semantics. You have to use Compiler directives to effect a set of reserved words associated with a particular dialect. See the appendix Reserved Words in this book and your Compatibility Guide, if your COBOL system has one, for a list of the reserved words for various dialects.

    Thus, for example, if you are developing a program for use on IBM OS/VS COBOL, you can use the unmarked features plus any marked OSVS; while if developing solely for your COBOL environment you can use any feature. If you supply the FLAG Compiler directive when you invoke the system software, your COBOL system software flags any features outside the given dialect. You can also use the FLAGAS Compiler directive to turn flagging messages into error messages.

  14. Elements within a diagram, which are marked for particular dialect(s), may enclose some other elements in the diagram, which are marked for other dialect(s). This indicates that the enclosed elements extend the syntax when the nested dialects are used.

    In the following example, the ID element is valid with OSVS, VSC2 and Micro Focus dialects:

  15. Some features have different effects in different dialects; you specify a dialect-control directive to select the dialect with which you want compatibility. The boxes around such features are double-ruled.

    Extra reserved words needed by features outside ANS X3.23-1985 are reserved only when the appropriate dialect-control directive is present; this means you can ensure that only the words reserved in the specified dialect are reserved on your target system. If you use only features that need no extra reserved words, and whose effects are the same in all dialects, you need not specify a dialect-control directive.

    The dialect-control directive specifying the ANS X3.23-1985 dialect also causes the few ANS 3.23-1974 features not allowed in ANS X3.23-1985 to be flagged with a warning message.

  16. The phrase "is documentary only" in the text of this book means that the associated coding is accepted syntactically by your COBOL system software, but is ignored when producing the object program.
  17. Hexadecimal values are enclosed in quotation marks and preceded by a lowercase x for nonnumeric values and by a lowercase h for numeric values; for example, x"9D".
Parent topic: COBOL Language Reference


Part 1. Concepts

  • Introduction to the COBOL Language
  • Concepts of the COBOL Language
  • Language Fundamentals
Parent topic: COBOL Language Reference


Introduction to the COBOL Language

This chapter introduces you to the COBOL language.

  • The COBOL Language
  • Source Format
Parent topic: Part 1. Concepts


The COBOL Language

COBOL (COmmon Business Oriented Language) is the programming language most widely and extensively used in commercial and administrative data processing.

This COBOL implementation is a superset of the ANSI and ISO COBOL standard as specified in ANSI X3.23-1974 (ISO 1989-1978), and of the current ANSI and ISO COBOL standard as specified in ANSI X3.23-1985 (IS 1989:1985), ANSI X3.23a-1989 (IS 1989:1985/AM1), and ANSI X3.23b-1993 (IS 1989:1985/AM2). Language extensions include:

  • Most of the more commonly used extensions of IBM OS/VS COBOL (Release 2.3 and later)
  • Most of the language constructs of IBM VS COBOL II (all releases), IBM DOS/VS COBOL and IBM SAA AD/Cycle COBOL/370
  • X/Open conforming extensions
  • Extensions specific to this system.

Combinations of these extensions are permissible in program source.

The ANSI COBOL 1974 and 1985 modules that are fully implemented are:

  • Nucleus
  • Table Handling (In the Nucleus as of the ANSI'85 Standard)
  • Record Sequential I/O
  • Relative I/O
  • Indexed I/O
  • Sort-Merge
  • Segmentation
  • Library/Source Text Manipulation
  • Inter-Program Communication
  • Debug
  • Report Writer
  • ANS85 Intrinsic Functions

This COBOL system meets the certification requirements for the above modules of the COBOL Compiler Validation System (CCVS) of the U.S. Department of Commerce, National Institute of Standards and Technology.

MF A number of additional enhancements to the COBOL language are present:

  • A screen-handling module, comprising a Screen Section and additional formats of ACCEPT and DISPLAY statements, which enable the user to specify exact location of fields on a screen, accept data entered at specified positions, display literal text at specified positions, define screen attributes, and control console features.
  • Enhanced file I/O with an additional organization to handle text files efficiently; optional definition of file-names either within a program source (data variable or literal) or at run time from operating system environment variables; multiuser file-sharing facilities.
  • Systems programming extension which enhances interlanguage calls and supports recursive COBOL programs.
Parent topic: Introduction to the COBOL Language


Source Format

Source code can be in

MF XOPEN free format,

fixed format, or variable format.

  • Fixed Format
  • Free Format
  • Variable Format
Parent topic: Introduction to the COBOL Language


Fixed Format

In fixed format, the COBOL source record is divided into the following areas:

Columns 1 - 6 | Sequence number
Column 7 | Indicator area
Column 8 - 11 | Area A
Columns 12 - 72 | Area B

MF A COBOL source record can extend up to a maximum of 80 columns in length. The contents of columns 73 to 80 are ignored by the COBOL system.

  • Sequence Number
  • Indicator Area
  • Areas A and B
  • Sample Program
Parent topic: Source Format


Sequence Number

A sequence number of six digits can be used to identify each source program line.

MF If the first character position of the sequence number field contains an asterisk, or any nonprinting control character (less than the character SPACE in the ASCII collating sequence), then the line is treated as comment and is not output to the listing file or device. This facility allows an output listing file to be used as a source file to a subsequent compilation.

MF This support is sensitive to the MFCOMMENT Compiler directive.

ANS85 The sequence number can contain any character in the computer's character set.

Parent topic: Fixed Format


Indicator Area

An asterisk (*) in the indicator area marks the line as documentary comment only. Such a comment line can appear anywhere in the program after the IDENTIFICATION DIVISION header. Any characters from the ASCII character set can be included in area A and area B of the line.

OSVS VSC2 MF A comment line can appear before the IDENTIFICATION DIVISION header.

A slash (/) in the indicator area acts as a comment line above but causes the page to eject before the comment is printed.

A "D" or "d" in the indicator area represents a debugging line. Areas A and B can contain any valid COBOL sentence.

A "–" in the indicator area represents a continuation of the previous line without spaces or the continuation of a nonnumeric literal (see the section Continuation of Lines in the chapter Language Fundamentals).

MF A "$" in the indicator area indicates a special line for setting directives or conditional compilation.

Parent topic: Fixed Format
Related information
Continuation of Lines


Areas A and B

Section names and paragraph names begin in area A and are followed by a period and a space. Level indicators FD, SD, CD and RD begin in area A and are followed in area B.

ANS85 or area A

by the appropriate description. Level numbers 01 and 77 begin in area A and are followed in area B

ANS85 or area A

by the data description. Level numbers 02 through 49, 66 and 88 begin in area B.

MF Level number 78 can begin in area A or area B.

MF No rules regarding area A and area B are enforced except in relation to comment-entries in the Identification Division.

MF XOPEN The concept of area A and area B is removed when free format source code is used. See the next section in this chapter for additional information on free format source code.

More than one sentence is permitted in each source record.

Parent topic: Fixed Format


Sample Program

Below is the source of a typical program in fixed format.

000010 identification division.
000020 program-id. stock-file-set-up.
000030 author. MicroFocus.
000040 environment division.
000050 configuration section.
000060 source-computer. mds-800.
000070 object-computer. mds-800.
000075 special-names. console is crt.
000080 input-output section.
000090 file-control.
000100  select stock-file assign "stock.it"
000110  organization indexed
000120  access dynamic
000130  record key stock-code.
000140 data division.
000150 file section.
000160 fd   stock-file record 32.
000170 01   stock-item.
000180  02  stock-code       pic x(4).
000190  02  product-desc     pic x(24).
000200  02  unit-size        pic 9(4).
000210 working-storage section.
000220 01   screen-headings.
000230  02  ask-code pic x(21) value "stock code    <    >".
000240  02  filler   pic x(59).
000250  02  ask-desc pic x(16) value "description   <".
000260  02  si-desc  pic x(25) value "                 >".
000270  02  filler   pic x(39).
000280  02  ask-size pic x(21) value "unit size <    >".
000290 01   enter-it redefines screen-headings.
000300  02      filler       pic x(12).
000310  02  crt-stock-code   pic x(4).
000320  02      filler       pic x(80).
000330  02  crt-prod-desc    pic x(24).
000340  02      filler       pic x(51).
000350  02  crt-unit-size    pic 9(4).
000360  02  filler           pic x.
000370 procedure division.
000380 sr1.
000390  display space.
000400  open i-o stock-file.
000410  display screen-headings.
000420 normal-input.
000430  move space to enter-it.
000440  display enter-it.
000450 correct-error.
000460  accept enter-it.
000470  if crt-stock-code = space go to end-it.
000480  if crt-unit-size not numeric go to correct-error.
000490  move crt-prod-desc to product-desc.
000500  move crt-unit-size to unit-size.
000510  move crt-stock-code to stock-code.
000520  write stock-item invalid key go to correct-error.
000530  go to normal-input. 000540 end-it.
000550  close stock-file.
000560  display space.
000570  display "end of program".
000580  stop run.
<---->|<--><----------------------------------------------------------->
  |   | |     |
  |   | |     +-- Columns 12-72 - Area B
  |   | +-- Columns 8-11 - Area A
  |   +-- Column 7 - Indicator Area
  +-- Columns 1-6 - Sequence Numbers
Parent topic: Fixed Format


Free Format

Free format COBOL is selected using the SOURCEFORMAT"FREE" directive.

The first six characters are considered part of the normal source line and may contain COBOL source code. Column 1 takes the role of the indicator area as follows:

* | comment line
/ | comment line starting on a new page in the listing file
D or d | followed by space, debugging line
$ | special line (for example, directive, conditional compilation)
any other character | normal source line

There are no continuation lines. Continuation of alphanumeric literals is achieved through concatenation (for example, "A" & "B").

There is no distinction between area A and area B.

There is no fixed right margin, though for practical purposes this implementation restricts the maximum length of a source line to 256 bytes of source when represented in UTF8 encoding.

Comment-entries are only allowed on the same line as the paragraph header and must not continue onto another line.

Parent topic: Source Format


Variable Format

Variable format COBOL is selected using the SOURCEFORMAT"VARIABLE" directive.

The COBOL source record is divided into areas as in fixed format. The only difference from fixed format is that the B area has no fixed right margin, though for practical purposes this implementation restricts the maximum length of a source line to 250 single-byte or 125 double-byte characters.

Parent topic: Source Format


Concepts of the COBOL Language

This chapter explains the concepts of the COBOL language.

  • Character Set
  • Language Structure
  • Formats and Rules
  • Concept of Computer-independent Data Description
  • Concept of Levels
  • Class and Category of Data
Parent topic: Part 1. Concepts


Character Set

The most basic and indivisible unit of the language is the character. The set of characters used to form COBOL character-strings and separators includes the letters of the alphabet, digits and special characters, and is defined below:

Character | Meaning
0 to 9 | Digits
A to Z | Upper-case letters
a to z | Lower-case letters
 | Space
+ | Plus sign
- | Minus sign or hyphen
* | Asterisk
/ | Oblique stroke/slash
= | Equal sign
$ | Dollar sign
. | Period or decimal point
, | Comma or decimal point
; | Semicolon
" | Quotation mark
' | Apostrophe
( | Left parenthesis
) | Right parenthesis
> | Greater than symbol
< | Less than symbol
: | Colon
& | Ampersand
_ | Underscore

ANS85 Lower-case letters can be used in character strings and text words; except when used in nonnumeric literals and except for some picture symbols, each lower-case letter is equivalent to the corresponding upper-case letter.

This COBOL implementation is restricted to the above character set, but the content of nonnumeric literals, comment lines, comment entries and data can include any of the printable characters available under the character encoding scheme used for the COBOL compilation group. (See the topic Character Sets and Collating Sequences.)

Parent topic: Concepts of the COBOL Language
Related information
Character Sets and Collating Sequences


Language Structure

The individual characters of the language are concatenated to form character-strings and separators. A separator can be concatenated with another separator or with a character-string. A character-string can be concatenated only with a separator. The concatenation of character-strings and separators forms your source text.

  • Separators
  • Character-strings
  • Scope of Names
  • Literals
  • Nonnumeric Literals
  • Numeric Literals
    Numeric literals can be either fixed-point or floating-point numbers.
  • National Literals
    A national literal is a string of national characters represented in the storage of the computer as characters of a uniform size. See your COBOL system documentation on national data (Unicode) for further information.
  • Figurative Constant Values
    Figurative constant values are generated by your COBOL system and referenced through the use of the reserved words given below. These words must not be bounded by quotation marks when used as figurative constants. The singular and plural forms of figurative constants are equivalent and can be used interchangeably.
  • Constant-names
  • Concatenation Expressions
    A concatenation expression consists of two operands separated by the concatenation operator.
  • Special Registers
  • Predefined Object Identifiers
  • PICTURE Character-Strings
  • Comment-entries
Parent topic: Concepts of the COBOL Language


Separators

A separator is a string of one or more punctuation characters. The rules for formation of separators are:

  1. The punctuation character space is a separator. Wherever a space is used as a separator or as part of a separator, more than one space can be used. All spaces immediately following the separators comma, semicolon, or period are considered part of that separator and are not considered to be the separator space.
  2. Except when the comma is used in a PICTURE character-string, the punctuation characters comma and semicolon, immediately followed by a space, are separators that can be used anywhere the separator space is used.
  3. The punctuation character period, when followed by a space, is a separator. It must be used only to indicate the end of a sentence, or as shown in formats.
  4. The punctuation characters right and left parenthesis are separators. Except in pseudo-text, parentheses can appear only in balanced pairs of left and right parentheses delimiting subscripts,

    ANS85 a list of function arguments, reference modifiers,

    arithmetic expressions, or conditions.

  5. The opening delimiters and closing delimiters of literals are separators.

    ISO2002 OSVS VSC2 MF Either an apostrophe or a quotation mark may be used as the quotation symbol character in opening and closing delimiters.

    The opening delimiters of literals are:

    • A quotation mark symbol
    • MF Any of the following pairs of contiguous characters: G", G', H", H', N", N', X", X', Z", Z'

    The closing delimiters of literals are:

    • A quotation mark when the opening delimiter uses a quotation mark
    • An apostrophe when the opening delimiter uses an apostrophe

    The opening delimiter must be immediately preceded by a space, left parenthesis or opening pseudo-text delimiter. The closing delimiter must be immediately followed by one of the separators space, comma, semicolon, period, right parenthesis or closing pseudo-text delimiter. Separators immediately preceding the opening delimiter are not part of the opening delimiter. Separators immediately following the closing delimiter are not part of the closing delimiter.

  6. Pseudo-text delimiters are separators. An opening pseudo-text delimiter must be immediately preceded by a space; a closing pseudo-text delimiter must be immediately followed by one of the separators space, comma, semicolon, or period.

    MF The space immediately preceding the opening pseudo-text delimiter can be omitted.

    Pseudo-text delimiters can appear only in balanced pairs delimiting pseudo-text

    MF and verb-signatures

    . (See the topic Source Text Manipulation and the topic Method Interface Definition.)

  7. The COBOL character colon, except as part of the invocation operator, is a separator and is required when shown in the general formats.
  8. The separator space can immediately precede all separators except the following:
    1. As specified by reference format (see the section Reference Format in the chapter Language Fundamentals).
    2. The separator closing quotation mark. In this case, a preceding space is considered as part of the nonnumeric literal and not as a separator.
    3. The opening pseudo-text delimiter, where the preceding space is required.
  9. The separator space can optionally immediately follow any separator except the opening quotation mark. In this case, a following space is considered as part of the nonnumeric literal and not as a separator.

Any punctuation character which appears as part of the specification of a PICTURE character-string (see the topic The PICTURE Clause) or numeric literal is not considered to be a punctuation character, but rather a symbol. PICTURE character-strings are delimited only by the separators space, comma, semicolon, or period.

The rules established for the formation of separators do not apply to the characters which comprise the contents of nonnumeric literals, comment-entries, or comment lines.

Parent topic: Language Structure
Related reference
Reference Format
Related information
Source Text Manipulation
Method Interface Definition
Reference Format
The PICTURE Clause


Character-strings

A character-string is a character or a sequence of contiguous characters forming a COBOL word, a literal, a PICTURE character-string, or a comment-entry. A character-string is delimited by separators.

  • COBOL Words
Parent topic: Language Structure


COBOL Words

ANS85 A COBOL word is a character-string of not more than 30 characters which forms a compiler-directive word, a context-sensitive word, user-defined word, a system-name, a reserved word, or an intrinsic-function-name. Each character of a COBOL word that is not a special character word is selected from the set of letters, digits, the hyphen

ISO2002 and the underscore

.

The hyphen

ISO2002 or the underscore

may not appear as the first or last character in such words. Each lower-case letter is considered to be equivalent to its corresponding upper-case letter.

ISO2002 The character-string may contain 31 characters.

ANS85 Within a source element the following apply:

  1. ANS85 For all COBOL words excluding the words LENGTH, RANDOM, and SUM:
    1. Reserved words form disjoint sets with user-defined words, system-names and intrinsic-function-names.
    2. User-defined words, system-names and intrinsic-function-names form intersecting sets. The same COBOL word may be used as a user-defined word, a system-name and an intrinsic-function-name. The classification of a specific occurrence of such COBOL words is determined by the context of the clause or phrase in which it occurs.
  2. ANS85 For the COBOL words LENGTH, RANDOM, and SUM:
    1. The reserved words LENGTH, RANDOM and SUM form an identical set with the intrinsic-function-names LENGTH, RANDOM and SUM. The same COBOL word LENGTH, RANDOM, or SUM may be used as an intrinsic-function-name and as a reserved word. The classification of a specific occurrence of such COBOL words is determined by the context in which it occurs.
    2. The COBOL words LENGTH, RANDOM, and SUM form disjoint sets with user-defined words and system-names. They may not be used as a system-name or user-defined word regardless of context.

User-Defined Words

A user-defined word is a COBOL word that must be supplied by the user to satisfy the format of a clause or statement.

The types of user-defined words are:

  • alphabet-name
  • ISO2002 MF class-name for object orientation
  • ANS85 class-name for truth value proposition
  • condition-name
  • MF constant-name
  • data-name
  • NET delegate-name
  • NET JVM enum-name
  • file-name
  • ISO2002 function-prototype-name
  • index-name
  • ISO2002 MF interface-name
  • level-number
  • library-name
  • ISO2002 MF method-name
  • mnemonic-name
  • paragraph-name
  • ISO2002 parameter-name
  • program-name
  • ISO2002 program-prototype-name
  • ISO2002 property-name
  • record-name
  • report-name
  • MF routine-name
  • ISO2002 MF XOPEN screen-name
  • section-name
  • segment-number
  • ISO2002 MF split-key-name
  • ANS85 symbolic-character
  • text-name
  • MF typedef-name
  • ISO2002 user-function-name
  • NET JVM valuetype-name

Within a given source element the following user-defined words are grouped into the following disjoint sets:

  • alphabet-names
  • ISO2002 MF class-names for object orientation
  • ANS85 class-names for truth value proposition
  • condition-names,

    MF constant-names,

    data-names,

    ISO2002 property-names,

    record-names,

    ISO2002 MF split-key-names

    MF typedef-names

  • NET delegate-name
  • NET JVM enum-name
  • file-names
  • ISO2002 function-prototype-names
  • index-names
  • ISO2002 interface-names
  • library-names
  • ISO2002 MF method-names
  • mnemonic-names
  • paragraph-names
  • ISO2002 parameter-names
  • program-names
  • ISO2002 MF program-prototype-names
  • report-names
  • MF routine-names
  • ISO2002 MF XOPEN screen-names
  • section-names
  • ANS85 symbolic-characters
  • text-names.
  • ISO2002 user-function-names
  • NET JVM valuetype-name

All user-defined words, except segment-numbers and level-numbers, can belong to one and only one of these disjoint sets. Furthermore, all user-defined words within a given disjoint set must be unique, except as specified in the section Uniqueness Of Reference.

With the exception of paragraph-name, section-name, level-number and segment-number, all user-defined words must contain at least one alphabetic character

MF or one occurrence of the hyphen character

.

Segment-numbers and level-numbers need not be unique; a given specification of a segment-number or level-number can be identical to any other segment-number or level-number and can even be identical to a paragraph-name or section-name.

The following user-defined words are externalized to the operating environment:

  1. Program-names of programs that are not contained in other programs,

    ISO2002 MF class-names,

    ISO2002 function-prototype-names, interface-names,

    ISO2002 MF method-names,

    ISO2002 program-prototype-names, user-function-names

    .

  2. ANS85 Data-names, file-names, and record-names of items described with the EXTERNAL attribute.

If a literal is specified in place of or in addition to one of these names, the content of the literal is the name that is externalized to the operating environment in a case-sensitive manner. If no literal is specified, the externalized name is created by folding the name to upper case. The Compiler directive FOLD-CALL-NAME can be used to control the case of externalized class-names, interface-names and program-names. The F and U options of the Compiler directive OOCTRL can be used to control the case of externalized method-names. +F and -U cause method-names to be folded to lower case, which is the default.

Condition-name: A condition-name is a name which is assigned to a specific value, set of values, or range of values, within a complete set of values that a data item can assume. The data item itself is called a conditional variable. Condition-names can be defined in the Data Division or in the Special-Names paragraph within the Environment Division where a condition-name must be assigned to one or both of the ON STATUS or OFF STATUS of the run-time switches.

A condition-name is used only as follows:

  1. In the RERUN clause.
  2. In conditions as an abbreviation for a relation condition. This relation condition posits that the associated conditional variable is equal to one of the set of values to which that condition-name is assigned.
  3. In a SET statement indicating that the associated value is to be moved to the conditional variable.
Constant-name: A constant-name is a name which is assigned as the name of a fixed value.
Mnemonic-name: A mnemonic-name assigns a user-defined word to an implementor-name. These associations are established in the Special-Names paragraph of the Environment Division. (See the topic The Special-Names Paragraph.)
Paragraph-name: A paragraph-name is a word that names a paragraph in the Procedure Division. Paragraph-names are equivalent if, and only if, they are composed of the same sequence of the same number of characters.
Section-name: A section-name is a word that names a section in the Procedure Division. Section-names are equivalent if, and only if, they are composed of the same sequence of the same number of characters.
Other user-defined words: See the Glossary for definitions of all other types of user-defined words.

System-names

A system-name is a COBOL word that is used to communicate with the operating environment.

System-names must contain at least one alphabetic character

MF or one occurrence of the hyphen character

.

There are three types of system-names:

  • Computer-name
  • Implementor-name
  • Language-name.

Within a given implementation these three types of system-names form disjoint sets; a given system-name can belong to one and only one of them.

The system-names listed above are individually defined in the Glossary.

Intrinsic-function-names

ANS85 An intrinsic-function-name is a word that is one of a specified list of words which can be used in COBOL source elements. The same word, with the exception of LENGTH, RANDOM and SUM, in a different context, can appear in a source element as a user-defined word or a system-name. (See the topic Definitions of Functions.)

Reserved words

A reserved word is a COBOL word that is one of a specified list of words which can be used in COBOL compilation groups, but which must not appear in the compilation groups as user-defined words or system-names. Reserved words can be used only as specified in the general formats. (See the topic Reserved Words.)

The types of reserved words are:

  • Key words
  • Optional words
  • Special registers
  • Figurative constants
  • Special-character words
  • ISO2002 MF Predefined object identifiers.

Key words: A key word is a word whose presence is required when the format in which it appears is used in a compilation group. Within each format, such words are upper-case and underlined.

Key words are of three types:

  1. Verbs such as ADD, READ, and ENTER
  2. Required words, which appear in statement and entry formats
  3. Words which have a specific functional meaning, such as NEGATIVE, SECTION, and so on.
Optional words: Within each format, upper-case words that are not underlined are called optional words and can appear at the user's discretion. The presence or absence of an optional word does not alter the semantics of the COBOL source element in which it appears.
Special registers: Certain words are used to name and reference special registers: special registers are certain storage areas created by your COBOL system, whose primary use is to store information produced in conjunction with the use of specific COBOL features. They are specified in the section Special Registers.
Figurative constants: Certain reserved words are used to name and reference specific constant values. These reserved words are specified in the section Figurative Constant Values.
Special character words: The arithmetic operators and relation characters are reserved words.
Predefined object identifiers: Certain reserved words are used as predefined object identifiers. The predefined object identifiers are:
  • SELF
  • SUPER
  • MF SELFCLASS

Context-sensitive words

ISO2002 A context-sensitive word is a COBOL word that is reserved only in the general formats in which it is specified. The same word may also be used as an intrinsic-function-name, a user-defined word or a system-name. Context-sensitive words and the contexts in which they are reserved are specified in the section Context-sensitive Words Table in the appendix Reserved Words.

Parent topic: Character-strings
Related information
Uniqueness Of Reference
The Special-Names Paragraph
Glossary
Definitions of Functions
Reserved Words
Special Registers
Figurative Constant Values
Context-sensitive Words Table


Scope of Names

When source elements are directly or indirectly contained within other source elements, each source element can use identical user-defined words to name items independent of the use of these user-defined words by other elements. (See the discussion of user-defined words in the section COBOL Words.) When identically named items exist, a source elements's reference to such a name, even when it is a different type of user-defined word, is to the item which that source element describes rather than to the item possessing the same name, described in another source element.

Delegate-names, enum-names and valuetype-names are special cases of class-names for object orientation.

The following types of user-defined words can be referenced only by statements and entries in the source element in which the user-defined word is declared:

  • paragraph-name
  • section-name

The following types of user-defined words can be referenced throughout a compilation group:

  • library-name
  • text-name

The following types of names, when declared in a Configuration Section, can be referenced only by statements and entries either in the source element that contains that Configuration Section or in any source element contained within that source element:

  • alphabet-name
  • class-name (for truth value proposition)
  • condition-name
  • mnemonic-name
  • symbolic-character

Specific conventions, for declarations and references, apply to the following types of user-defined words when the conditions listed above do not apply:

  • ISO2002 MF class-name (for object orientation)
  • condition-name
  • data-name
  • file-name
  • ISO2002 MF function-prototype-name
  • index-name
  • ISO2002 interface-name
  • ISO2002 MF method-name
  • program-name
  • ISO2002 MF program-prototype-name
  • record-name
  • report-name
  • ISO2002 MF XOPEN screen-name
  • MF typedef-name
  • ISO2002 user-function-name
  • Conventions for Program-names
  • Conventions for Condition-names, Data-names, File-names, Record-names, Report-names and Typedef-names
  • Conventions for Index-names
  • Conventions for Class-names (for Object Orientation) and Interface-names
  • Conventions for Method-names
  • Conventions for Function-prototype-names
  • Conventions for Program-prototype-names
Parent topic: Language Structure
Related information
COBOL Words


Conventions for Program-names

The program-name of a program is declared in the Program-ID paragraph of the program's Identification Division. A program-name can be referenced only by the CALL statement,

MF the CHAIN statement,

the CANCEL statement,

MF the SET statement

and the END PROGRAM header. If two programs in a run unit are identically named, at least one of those two programs must be directly or indirectly contained within a separate program which does not contain the other of those two programs.

The following rules regulate the scope of a program-name:

  1. If the program-name is that of a program which does not possess the common attribute and which is directly contained within another program, that program-name can be referenced only by statements included in that containing program

    ISO2002 MF OS390 or, if the program possesses the recursive attribute, in the program itself

    .

  2. If the program-name is that of a program which does possess the common attribute and which is directly contained within another program, that program-name can be referenced only by statements included in that containing program and any programs directly or indirectly contained within that containing program

    ISO2002 MF OS390 , except that the program possessing the common attribute and any programs contained within it may reference the program-name only if the program possesses the recursive attribute.

  3. If the program-name is that of a program that is not contained in another program, it can be referenced by statements included in any source element in the run unit.

For example, suppose that ProgA contains ProgB and ProgC, ProgC contains ProgD and ProgF, and ProgD contains ProgE, as shown below.

Example of Scope of Program-Names

If ProgD does not possess the COMMON attribute, then ProgD can only be referenced by the program that directly contains ProgD, that is, ProgC.

If ProgD does possess the COMMON attribute, then ProgD can be referenced by ProgC since it contains ProgD and by any programs contained in ProgC except for programs contained in ProgD, that is, by ProgF but not by ProgE. Also it cannot be referenced by ProgA or ProgB.

Parent topic: Scope of Names


Conventions for Condition-names, Data-names, File-names, Record-names, Report-names and Typedef-names

Conventions for Condition-names, Data-names, File-names, Record-names, Report-names and MF Typedef-names

When condition-names, data-names, file-names, record-names and report-names

MF and typedef-names

are declared in a source element, they can be referenced only by that source element unless one or more of the names is global and the source element contains other source elements.

The requirements governing the uniqueness of the names declared by a single source element to be condition-names, data-names, file-names, record-names and report-names

MF and typedef-names

are explained in the discussion of user-defined words in the section COBOL Words.

A source element cannot reference any condition-name, data-name, file-name, record-name or report-name

MF or typedef-name

declared in any source element it contains.

A global name can be referenced in the source element in which it is declared or in any source elements which are directly or indirectly contained within that source element.

When a source element, source element B, is directly contained within another source element, source element A, both source elements can define a condition-name, a data-name, a file-name, a record-name or a report-name

MF or a typedef-name

using the same user-defined word. When such a duplicate-name is referenced in source element B, the following rules are used to determine the referenced item:

  1. The set of names to be used for determination of a referenced item consists of all names that are defined in source element B and all global names that are defined in source element A and in any source elements which directly or indirectly contain source element A. Using this set of names, the normal rules for qualification and any other rules for uniqueness of reference are applied until one or more item is identified.
  2. If only one item is identified, it is the referenced item.
  3. If more than one item is identified, no more than one of them can have a name local to source element B. If zero or one of the items has a name local to source element B, the following rules apply:
    1. If the name is declared in source element B, the item in source element B is the referenced item.
    2. Otherwise, if source element A is contained within another source, the referenced item is:
      1. The item in source element A if the name is declared in source element A.
      2. The item in the containing source element if the name is not declared in source element A and is declared in the source element containing source element A. This rule is applied to further containing source elements until a single valid name has been found.
Parent topic: Scope of Names
Related information
COBOL Words


Conventions for Index-names

If a data item possessing the global attribute includes a table described with an index-name, that index-name also possesses the global attribute. Therefore, the scope of an index-name is identical to that of the data-name which names the table whose index is named by that index-name and the scope of name rules for data-names apply.

Index-names cannot be qualified.

OSVS Index-names can be qualified.

Parent topic: Scope of Names


Conventions for Class-names (for Object Orientation) and Interface-names

The class-name of a class referenced within a source element must be either the name of the containing class definition or declared in the Repository paragraph

MF or the Class-Control paragraph

of that or a containing source element.

Within a compilation group, there must be at most one class definition for a given class-name.

The interface-name of an interface referenced within a source element must be either the name of the containing interface definition or declared in the Repository paragraph of that or a containing source element.

Within a compilation group, there must be at most one interface definition for a given interface-name.

A class-name or interface-name declared in the Repository paragraph of a source element may be used in that source element and any nested source element.

MF A class-name or interface-name declared in the Class-Control paragraph of a source element may be used in that source element and any nested source element.

Parent topic: Scope of Names


Conventions for Method-names

A method-name of a method is declared in the Method-ID paragraph. A method-name must be referenced only by the INVOKE statement, an inline method invocation and the end method header.

The methods declared in a class definition must have unique method-names within that class definition. The methods declared in a child class may have the same name as a method in the parent class, subject to the conditions for the Method-ID paragraph.

The methods declared in an interface definition must have unique method-names within that interface definition. The methods declared in an inheriting interface can have the same name as a method in the inherited interface, subject to the conditions stated for the Method-ID paragraph.

Parent topic: Scope of Names


Conventions for Function-prototype-names

Function-prototype-names referenced within a source element must be either the name of the containing function definition or declared in the Repository paragraph of that or a containing source element.

If a function prototype is specified in a Repository paragraph and the function prototype declaring the same function-prototype-name is also specified within the same compilation group, the function prototype specification is used and the information in the external repository for this prototype is ignored.

Parent topic: Scope of Names


Conventions for Program-prototype-names

Program-prototype-names referenced within a source element must be either the program-name of a containing program definition or a program-prototype-name declared in the Repository paragraph

If a program prototype is specified in a Repository paragraph and the program prototype declaring the same program-prototype-name is also specified within the same compilation group, the program prototype specification is used and the information in the external repository for this prototype is ignored.

Parent topic: Scope of Names


Literals

A literal is any of:

  • A character-string whose value is implied by the ordered set of characters of which it is composed
  • A reserved word which references a figurative constant
  • MF A user-defined word which references a constant value

Every literal belongs to one of three types; nonnumeric, numeric and national.

Parent topic: Language Structure


Nonnumeric Literals

A nonnumeric literal is a character string delimited at both ends by quotation marks

ISO2002 OSVS VSC2 MF or apostrophes

and consisting of any allowable character in the computer's character set. In native COBOL, nonnumeric literals may be between 1 and 8192 bytes in length. When compiling for managed COBOL, the minimum length of a nonnumeric literal is 0. In most cases, a literal with zero length is equivalent to a single character literal with value space, except where the literal is the source of an assignment to a string object, or is a parameter to a method expecting a string parameter, where the distinction is important.

Whether quotation marks

ISO2002 OSVS VSC2 MF or apostrophes

are used as delimiters, the presence of that delimiter character within the character string can be represented by two contiguous occurrences. The presence of the character that is not serving as the delimiter is represented by a single occurrence. The value of a nonnumeric literal in the run-time element is the string of characters itself, except:

  • The delimiting quotation marks are excluded, and
  • Each embedded pair of contiguous delimiter characters represents a single character.

All other punctuation characters are part of the value of the nonnumeric literal rather than separators; all nonnumeric literals are category alphanumeric. (See the topic The PICTURE Clause.)

VSC2 MF In addition, hexadecimal binary values can be attributed to nonnumeric literals by expressing literals as: X"nn", where each n is a hexadecimal digit in the set 0 through 9, A through F; nn can be repeated up to 160 times, but the number of hexadecimal digits must be even.

MF The number of hexadecimal digits may be odd.

MF In addition, a nonnumeric literal can be null-terminated (i.e. have a null byte x"00" at the end of the literal) by expressing it as: Z"string", where string is a nonnumeric literal.

Parent topic: Language Structure
Related information
The PICTURE Clause


Numeric Literals

Numeric literals can be either fixed-point or floating-point numbers.

Fixed-Point Numeric Literals

A numeric literal is a character-string whose characters are selected from the digits 0 through 9, the plus sign, the minus sign, and the decimal point. This implementation allows for numeric literals of 1 to 18 digits in length. The rules for the formation of numeric literals are as follows:

  • A literal must contain at least one digit.
  • A literal must not contain more than one sign character. If a sign is used, it must appear as the leftmost character of the literal. If the literal is unsigned, the literal is positive.
  • A literal must not contain more than one decimal point. The decimal point is treated as an assumed decimal point, and can appear anywhere within the literal except as the rightmost character. If the literal contains no decimal point, the literal is an integer.
  • The value of a numeric literal is the algebraic quantity represented by the characters in the numeric literal. Every numeric literal is category numeric. (See the topic The PICTURE Clause.)

If a literal conforms to the rules for the formation of numeric literals, but is enclosed in quotation marks, it is a nonnumeric literal and is treated as such by your COBOL system.

The size of a numeric literal in standard data format characters is equal to the number of digits specified by the user.

MF In addition, hexadecimal binary values can be attributed to numeric literals by expressing literals as:
H"nn"
where each n is a hexadecimal digit in the set 0-9 A-F; nn can be repeated up to 8 times, but the number of hexadecimal digits must be even.

Floating-Point Numeric Literals

A floating-point literal is written in the form:

If you omit a sign, the system assumes a positive number.

The significand can contain between 1 and 16 digits. A decimal point must be included in the significand.

The exponent is represented by an E followed by an optional sign and one or two digits.

The magnitude of a floating-point literal value must fall between 0.54E-78 and 0.72E+76. For values outside this range, an error message is produced and the value is replaced by 0 or 0.72E+76 respectively. You must not use a floating-point literal when an integer literal is required.

Parent topic: Language Structure
Related information
The PICTURE Clause


National Literals

A national literal is a string of national characters represented in the storage of the computer as characters of a uniform size. See your COBOL system documentation on national data (Unicode) for further information.

General Formats for Format 1

General Formats for Format 2

Syntax Rules for All Formats

  1. The length of a national literal, excluding the separators that delimit the literal, must be greater than zero and less than or equal to 160 national character positions.
  2. Character 1 can be any character in the alphanumeric coded character set such that a correspondence exists between that alphanumeric character and a national character.

Syntax Rules for Format 1

  3. Two contiguous quotation symbol characters matching the quotation symbol used in the opening delimiter represent a single occurrence of that quotation symbol character in the content of the literal. The two contiguous quotation symbol characters must be in the same coded character set representation as the opening quotation symbol.

Syntax Rules for Format 2

  4. Each hex-character-sequence-1 must consist of four hexadecimal digits (two bytes) coded with the high-order byte first

General Rules for All Formats

  1. The separators that delimit the national literal are not included in the value of the national literal.
  2. National literals are of the class and category national.

General Rules for Format 1

  3. The value of the literal at compile time is the string of occurrences of character-1 represented in the computer’s compile-time coded character set.

    The value of the literal at runtime is the string of national characters that results from converting the compile-time value of the literal to its runtime equivalent.

General Rules for Format 2

  4. The value of the literal at runtime is a string of national characters, each of which has the bit configuration specified by one occurrence of hex-character-sequence-1.
Parent topic: Language Structure


Figurative Constant Values

Figurative constant values are generated by your COBOL system and referenced through the use of the reserved words given below. These words must not be bounded by quotation marks when used as figurative constants. The singular and plural forms of figurative constants are equivalent and can be used interchangeably.

The figurative constant values and the reserved words used to reference them are shown in the table below.

Table 1. Figurative Constants and Their Reserved Words
Constant | Representation
ZERO ZEROS ZEROES | Represents the value "0", or one or more of the character "0" depending on the context.
SPACE SPACES | Represents one or more of the character space from the computer's character set.
HIGH-VALUE HIGH-VALUES | Represents one or more of the character that has the highest ordinal position in the program collating sequence. (x"FF" for the extended ASCII character set.)
LOW-VALUE LOW-VALUES | Represents one or more of the character that has the lowest ordinal position in the program collating sequence. (x"00" for the ASCII character set.)
QUOTE QUOTES | Represents one or more of the character """. The word QUOTE or QUOTES cannot be used in place of a quotation mark in a source program to bound a nonnumeric literal. Thus QUOTE ABD QUOTE is incorrect as a way of stating "ABD".
ALL literal | Represents one or more characters of the string of characters comprising the literal. The literal must be either a nonnumeric literal or ISO2002 MF a national literal or a figurative constant other than ALL literal. ISO2002 MF XOPEN This nonnumeric literal and this national literal may be concatenation expressions. When a figurative constant is used, the word ALL is redundant and is used for readability only.
NULL NULLS | Represents one or more unset pointer MF COB370 or procedure-pointer values. A data item with USAGE POINTER MF COB370 or PROCEDURE-POINTER and with a value of NULL is guaranteed not to represent the address of any data item MF COB370 or procedure . The NULL value varies between environments and is generally consistent with the equivalent value used in non-COBOL languages for each environment.

When a figurative constant represents a string of one or more characters, the length of the string is determined by your COBOL system from context by applying the following rules in order:

  1. ISO2002 MF XOPEN When a figurative constant is specified in a concatenation expression, the length of the string is one character.
  2. When a figurative constant is either specified in a VALUE clause, or associated with another data item, (for example, when the figurative constant is moved to or compared with another data item), the string of characters specified is repeated character by character on the right until the size of the resultant string is greater than or equal to the number of character positions in the associated data item. This resultant string is then truncated from the right until the number of character positions remaining is equal either to 1 or to the number of character positions in the associated data item, whichever is greater. This is done prior to and independent of the application of any JUSTIFIED clause that can be associated with the data item.
  3. When a figurative constant is other than ALL literal, the length of the string is one character.
  4. The length of the string is the length of the literal.

    MF Use of figurative constants in Format 3 DISPLAY statements has specific effects, described in the General Rules for that statement.

A figurative constant can be used wherever a literal appears in a format, except that whenever the literal is restricted to having only numeric characters in it, the only figurative constant permitted is ZERO (ZEROS, ZEROES).

When the figurative constants HIGH-VALUE(S) or LOW-VALUE(S) are used , the actual character associated with each figurative constant depends upon the program collating sequence specified. (See the topics The Object-Computer Paragraph and the The Special-Names Paragraph.)

Each reserved word that is used to reference a figurative constant value is a distinct character-string, with the exception of the construction "ALL literal" which is composed of two distinct character-strings.

OSVS VSC2 MF The value associated with the QUOTE/QUOTES figurative constant is sensitive to the APOST and QUOTE directives.

ANS85 The figurative constant ALL literal, when associated with a numeric or numeric edited item, and when its length is greater than one, is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects within this COBOL implementation fully support this obsolete ALL literal syntax. The FLAGSTD directive can be used to detect all occurrences of this syntax.

XOPEN Although this obsolete ALL literal syntax is a part of the standard COBOL definition, this syntax is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

Parent topic: Language Structure
Related information
The Object-Computer Paragraph
The Special-Names Paragraph


Constant-names

Constant-names are user-defined words described in the Data Division in level-78 data description entries. A constant-name may be used wherever a literal appears in a format. Its effect is as if the literal in the VALUE clause of its data description had been written instead. A constant-name with an integer value can also be used wherever a format requires an integer; for example, as a level number or segment number, or in a PICTURE character-string.

A constant-name can only be used after it has been described; that is, it cannot be the object of a forward reference.

Parent topic: Language Structure


Concatenation Expressions

A concatenation expression consists of two operands separated by the concatenation operator.

General Format

Syntax Rules

  1. Both operands must be of the same class, except that a figurative constant may be specified as one or both operands. Neither operand must be numeric. Neither literal-1 nor literal-2 must be a figurative constant that begins with the word ALL.
  2. ISO2002 The length of the value resulting from concatenation must be less than or equal to 160 character positions.

General Rules

  1. The class of the concatenation expression resulting from the concatenation operation must be:
    1. When one of the operands is a figurative constant, the class of the literal or concatenation expression that constitutes the other operand, or
    2. When both of the operands are figurative constants, the class alphanumeric, or
    3. The same class as the operands.
  2. The value of a concatenation expression must be the concatenation of values of the literals, figurative constants and concatenation expressions of which it is composed.
  3. A concatenation expression must be equivalent to a literal of the same class and value, and may be used anywhere a literal of that class may be used.
Parent topic: Language Structure


Special Registers

Special registers are data items or transient values generated by your COBOL system and referenced through the use of their associated names or expressions. These special registers are subject to special rules of reference and have implicit data descriptions (PICTUREs), as individually described.
Table 1. Special Registers
Special Register Name or Expression | Implicit Data Description Picture | Usage
VSC2 MF ADDRESS OF data-name-1 USAGE IS POINTER The expression generates a pointer value representing the address of data-name-1. The expression is explicitly shown in the general format for statements in which it can be used. Data-name-1 must be a data item declared in the Linkage Section with a level number or 01 or 77

MF or must be declared anywhere in the Data Division and with any level number

.

OSVS CURRENT-DATE 1 | X(8) | The CURRENT-DATE special register contains the value of the current date (as supplied by the COBOL execution environment), in the form: MM/DD/YY where MM is the month number, DD is the day of the month, and YY is the year number (from 1900). CURRENT-DATE is valid only as the sending area of a MOVE statement.
DEBUG-ITEM | A group item of variable size | The DEBUG-ITEM special register provides information about the conditions that caused the execution of a Debugging Section. For further information see the section Debug Module.
ENT MF JSON-CODE 2 S9(9) BINARY VALUE 0

The JSON-CODE special register is used to indicate that a JSON PARSE or JSON GENERATE statement executed successfully, or that an exception occurred during JSON generation.

When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.

Following termination of a JSON PARSE or JSON GENERATE statement, JSON-CODE contains either a zero to indicate a successful processing, or a non-zero error code to indicate an exception condition.

ENT MF JSON-STATUS 3 S9(9) BINARY VALUE 0

The JSON-STATUS special register is used to indicate when non-exception conditions have occurred during a JSON PARSE statement.

When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.

Following termination of a JSON PARSE statement, JSON-STATUS contains either zero to indicate no non-exception conditions have occurred or non-zero to indicate which non-exception condition(s) have occurred. (The reason code values are additive.)

VSC2 MF LENGTH OF data-name-2 4 9(9) The expression generates a value representing the current number of bytes of storage used by data-name-2. The expression can be used wherever a numeric data item can be used except as a subscript or a reference modifier.

MF It can also be used to set the value of a level 78 item.

LINAGE-COUNTER | The LINAGE-COUNTER special register is generated by the presence of a LINAGE clause in a file description entry for a record sequential file. The implicit description is that of an unsigned integer whose size is equal to the size of integer-1 or the data item referenced by data-name-1 in the LINAGE clause.
OSVS VSC2 MF RETURN-CODE 5 S9(4) COMP

XOPEN S9(9) COMP

S9(18) COMP

The RETURN-CODE special register can:
  • be set by a program, prior to the execution of a STOP RUN, EXIT PROGRAM or GOBACK statement, to pass a value to the calling run-time element (or the execution environment)
  • be read, subsequent to a CALL to another COBOL program, to obtain the value of the RETURN-CODE special register set by that CALLed program.

A program's RETURN-CODE special register is set to zero when that program is first entered. RETURN-CODE is valid as a data-name in a Procedure Division statement wherever an elementary data item can be referenced.

VSC2 SHIFT-IN | X(1) | Used to switch the character representation from double-byte characters (DBCS) back to single-byte characters (SBCS) in environments where this is applicable.
VSC2 SHIFT-OUT | X(1) | Used to switch the character representation from single-byte characters (SBCS) to double-byte characters (DBCS) in environments where this is applicable.
VSC2 SORT-CONTROL | X(8) | Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
OSVS VSC2 SORT-CORE-SIZE | S9(8) COMP | Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
OSVS VSC2 SORT-FILE-SIZE | S9(8) COMP | Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
OSVS VSC2 SORT-MESSAGE | X(8) | Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
OSVS VSC2 SORT-MODE-SIZE | S9(5) COMP | Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
OSVS VSC2 MF SORT-RETURN | S9(4) COMP | SORT-RETURN can be used to cause an abnormal termination of a SORT procedure. If a value of 16 is moved into this field, the SORT operation is terminated after the next RELEASE or RETURN.
OSVS VSC2 TALLY | 9(5) COMP | The TALLY special register contains information produced by the EXAMINE...TALLYING statement. It is valid as a data-name in a Procedure Division statement wherever an elementary data item can be referenced.
OSVS TIME-OF-DAY | 9(6) DISPLAY | The TIME-OF-DAY special register contains the value of the current time of day (24-hour clock) (as supplied by the COBOL execution environment), in the form: hhmmss where hh =hour, mm =minutes, and ss =seconds. TIME-OF-DAY is valid only as the sending area of a MOVE statement.
OSVS WHEN-COMPILED X(20) The WHEN-COMPILED special register contains the time and date that the COBOL compilation group was submitted to your COBOL system, in the form: hh.mm.ssMMM DD, YYYY where hh =hours (24-hour clock), mm =minutes, ss =seconds, MMM =month name (first 3 characters), DD =day of month, and YYYY =year.

WHEN-COMPILED is valid only as the sending area of a MOVE statement.

VSC2 WHEN-COMPILED X(20) The WHEN-COMPILED special register contains the time and date that the COBOL compilation group was submitted to your COBOL system, in the form: MM/DD/YYhh.mm.ss where DD, hh, mm and ss are as above. YY =year in century and MM =month in year.

WHEN-COMPILED is valid only as the sending area of a MOVE statement.

ENT MF XML-CODE 6 S9(9) COMP The XML-CODE special register is used to communicate status between the XML parser and the processing procedure identified in the XML PARSE statement and to indicate either that an XML GENERATE statement executed successfully or that an exception occurred during XML generation.

The XML parser sets XML-CODE for each event and at parser termination. You can reset XML-CODE in the processing procedure to -1 after a normal event, to indicate that the parser is to terminate with a user-initiated exception, which is not an EXCEPTION XML event, indicated by the returned XML-CODE value of -1.

Following termination of an XML GENERATE statement, XML-CODE contains either a zero to indicate a successful XML generation, or a non-zero error code to indicate an exception.

ENT MF XML-EVENT 7 | X(30) | The XML-EVENT special register is used to communicate event information from the XML parser to the processing procedure that was identified in the XML PARSE statement. Before passing control to the processing procedure, the XML parser sets the XML-EVENT special register to the name of the XML event. XML-EVENT cannot be used as a receiving data item.
ENT MF XML-NTEXT The XML-NTEXT special register is defined during XML parsing to contain document fragments that are USAGE NATIONAL. XML-NTEXT is an elementary national data item of the length of the contained XML document fragment. The length of XML-NTEXT varies dynamically at run time.
The parser sets XML-NTEXT to the document fragment associated with an event before transferring control to the processing procedure in these cases:
  • When the operand of the XML PARSE statement is a data item of category national or the RETURNING NATIONAL phrase is specified in the XML PARSE statement
  • For the ATTRIBUTE-NATIONAL-CHARACTER event
  • For the CONTENT-NATIONAL-CHARACTER event

When XML-NTEXT is set, the XML-TEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length.

Use the LENGTH function to determine the number of national characters that XML-NTEXT contains.

XML-NTEXT cannot be used as a receiving item.

ENT MF XML-TEXT The XML-TEXT special register is defined during XML parsing to contain document fragments that are of class alphanumeric. XML-TEXT is an elementary alphanumeric data item of the length of the contained XML document fragment. The length of XML-TEXT varies dynamically at run time.

The parser sets XML-TEXT to the document fragment associated with an event before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified in the XML PARSE statement, except for the ATTRIBUTE-NATIONAL-CHARACTER event and the CONTENT-NATIONAL-CHARACTER event.

When XML-TEXT is set, the XML-NTEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length.

Use the LENGTH function or the LENGTH OF special register for XML-TEXT to determine the number of bytes that XML-TEXT contains.

XML-TEXT cannot be used as a receiving item.

ENT MF XML-INFORMATION S9(9) USAGE BINARY VALUE 0 The XML-INFORMATION special register is used to provide additional information to an XML PARSE processing procedure about the status of the parse.

This register provides a mechanism to easily determine whether an XML EVENT is complete. Sometimes XML content might be split across multiple events and the application must concatenate the pieces of content together. The XML-INFORMATION register is used to indicate whether or not content of the XML event is complete.

The value of the XML-INFORMATION register is set as follows for the various XML events:

  • ATTRIBUTE-CHARACTERS
    • 1 indicates that the attribute value in XML-TEXT or XML-NTEXT special register is complete
    • 2 indicates that the attribute value in XML-TEXT or XML-NTEXT special register is not complete
    • 4, 8, 16, ... are reserved for future use
  • CONTENT-CHARACTERS
    • 1 indicates that the content value in XML-TEXT or XML-NTEXT special register is complete
    • 2 indicates that the content value in XML-TEXT or XML-NTEXT special register is not complete
    • 4, 8, 16, ... are reserved for future use
  • All other events
    • 0 indicates that no additional information is currently available
    • 2, 4, 8, 16, ... are reserved for future use
ENT MF XML-NAMESPACE The XML-NAMESPACE special register is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION.

The parser sets XML-NAMESPACE to the identifier of the namespace associated with a name before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified in the XML PARSE statement.

To use XML-NAMESPACE, you must compile with the XMLPARSE(XMLSS) compiler option.

XML-NAMESPACE is an elementary data item of category alphanumeric. The length at run time is the length of the contained namespace identifier.

XML-NAMESPACE has a length of zero for:
  • The START-OF-ELEMENT, END-OF-ELEMENT and ATTRIBUTE-NAME XML events if there is no namespace associated with a name
  • The NAMESPACE-DECLARATION XML event if the namespace is undeclared by specifying the empty string
  • All other XML events

When XML-NAMESPACE is set, the XML-NNAMESPACE special register has a length of zero. At any given time, only one of the two special registers XML-NAMESPACE and XML-NNAMESPACE has a nonzero length.

Use the LENGTH function or the LENGTH OF special register to determine the number of bytes that XML-NAMESPACE contains.

XML-NAMESPACE cannot be used as a receiving item.

ENT MF XML-NAMESPACE-PREFIX The XML-NAMESPACE-PREFIX special register is defined during XML parsing to contain the prefix, if any, of the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier.

The parser sets XML-NAMESPACE-PREFIX before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified.

To use XML-NAMESPACE-PREFIX, you must compile with the XMLPARSE(XMLSS) compiler option.

XML-NAMESPACE-PREFIX is an elementary data item of category alphanumeric. The length at run time is the length of the contained namespace prefix.

XML-NAMESPACE-PREFIX has a length of zero for:
  • The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML events if the name does not have a prefix
  • The NAMESPACE-DECLARATION XML event if the declaration is for the default namespace, in which case the namespace declaration attribute name is not prefixed.
  • All other XML events

When XML-NAMESPACE-PREFIX is set, the XML-NNAMESPACE-PREFIX special register has a length of zero. At any given time, only one of the two special registers XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX has a nonzero length.

Use the LENGTH function or the LENGTH OF special register to determine the number of bytes that XML-NAMESPACE-PREFIX contains.

XML-NAMESPACE-PREFIX cannot be used as a receiving item.

ENT MF XML-NNAMESPACE

The XML-NNAMESPACE special register is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION.

The parser sets XML-NNAMESPACE to the identifier of the namespace associated with a name before transferring control to the processing procedure when the RETURNING NATIONAL phrase is specified in the XML PARSE statement or the operand of the XML PARSE statement is a national data item.

To use XML-NNAMESPACE, you must compile with the XMLPARSE(XMLSS) compiler option.

XML-NNAMESPACE is an elementary data item of category national. The length at run time is the length of the contained namespace identifier.

XML-NNAMESPACE has a length of zero for:
  1. The START-OF-ELEMENT, END-OF-ELEMENT and ATTRIBUTE-NAME XML events, if there is no namespace associated with a name
  2. The NAMESPACE-DECLARATION XML event if the namespace is undeclared by specifying the empty string
  3. All other XML events

When XML-NNAMESPACE is set, the XML-NAMESPACE special register has a length of zero. At any given time, only one of the two special registers XML-NNAMESPACE and XML-NAMESPACE has a nonzero length.

Use the LENGTH function to determine the number of national character positions that XML-NNAMESPACE contains; use the LENGTH OF special register to determine the number of bytes.

XML-NNAMESPACE cannot be used as a receiving item.

ENT MF XML-NNAMESPACE-PREFIX The XML-NNAMESPACE-PREFIX special register is defined during XML parsing to contain the prefix, if any, of the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier.

The parser sets XML-NNAMESPACE-PREFIX before transferring control to the processing procedure when the operand of the XML PARSE statement is a national data item or the RETURNING NATIONAL phrase is specified in the XML PARSE statement.

To use XML-NNAMESPACE-PREFIX, you must compile with the XMLPARSE(XMLSS) compiler option.

XML-NNAMESPACE-PREFIX is an elementary data item of category national. The length at run time is the length of the contained namespace prefix.

XML-NNAMESPACE-PREFIX has a length of zero for:
  • The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML events if the name does not have a prefix
  • NAMESPACE-DECLARATION XML event if the declaration is for the default namespace, in which case the namespace declaration attribute name is not prefixed.
  • All other XML events

When XML-NNAMESPACE-PREFIX is set, the XML-NAMESPACE-PREFIX special register has a length of zero. At any given time, only one of the two special registers XML-NNAMESPACE-PREFIX and XML-NAMESPACE-PREFIX has a nonzero length.

Use the LENGTH function to determine the number of national character positions that XML-NNAMESPACE contains; use the LENGTH OF special register to determine the number of bytes.

XML-NNAMESPACE-PREFIX cannot be used as a receiving item.

Table 2. Contents of XML events and associated special register contents
XML-EVENT8 | XMLPARSE(XMLSS) | XMLPARSE(COMPAT)
ATTRIBUTE-CHARACTER | N/A | XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the attribute value.
ATTRIBUTE-CHARACTERS | XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value. | XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value if the value includes a character reference or an entity reference.
ATTRIBUTE-NAME | For attribute names that are not in a namespace, XML-TEXT or XML-NTEXT contains the attribute name. For attributes with names in a non-default namespace, attribute names are always prefixed and have the form: prefix: local-part = " AttValue ". XML-TEXT or XML-NTEXT contains the local-part , XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier, and XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix . | XML-TEXT or XML-NTEXT contains the attribute name (the string to the left of the equal sign).
ATTRIBUTE-NATIONAL-CHARACTER | Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
COMMENT | XML-TEXT or XML-NTEXT contains the text of the comment between the opening character sequence "<!--" and the closing character sequence "-->". This can be a substring of the text. | XML-TEXT or XML-NTEXT always contains the complete text of the comment.
CONTENT-CHARACTER | N/A | XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the element content.
CONTENT-CHARACTERS | XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the content. | XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the character content if the content includes a character reference or an entity reference.
CONTENT-NATIONAL-CHARACTER | Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
DOCUMENT-TYPE-DECLARATION | XML-TEXT or XML-NTEXT contains the name of the root element, as specified in the document type declaration. | XML-TEXT or XML-NTEXT contains the entire document type declaration, including the opening and closing character sequences "<!DOCTYPE" and ">".
ENCODING-DECLARATION | XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the encoding declaration in the XML declaration. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-CDATA-SECTION | All XML special registers except XML-CODE and XML-EVENT are empty with length zero. | XML-TEXT or XML-NTEXT contains the string "]]>".
END-OF-DOCUMENT | All XML special registers except XML-CODE and XML-EVENT are empty with length zero. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-ELEMENT | XML-TEXT or XML-NTEXT contains the local part of the end element tag or empty element tag name. If the element name is in a non-default namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier. If the element name is in a namespace and is prefixed (of the form prefix: local-part ), XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix. | XML-TEXT or XML-NTEXT contains the name of the end element tag or empty element tag.
END-OF-INPUT | All XML special registers except XML-CODE and XML-EVENT are empty with length zero. To parse an additional segment of an XML document, move the next segment to identifier-1 and set XML-CODE to 1. | N/A
EXCEPTION | XML-CODE contains the unique return code and reason code that identifies the exception. XML-TEXT or XML-NTEXT contains the document fragment up to the point of the error or anomaly that caused the exception. All other XML special registers are empty with length zero. | XML-CODE contains the unique error code that identifies the exception. XML-TEXT or XML-NTEXT contains the part of the document that was successfully scanned, up to and including the point at which the exception was detected.
NAMESPACE-DECLARATION | XML-TEXT and XML-NTEXT are both empty with length zero. XML-NAMESPACE or XML-NNAMESPACE contains the declared namespace identifier. If the namespace is "undeclared" by specifying the empty string, XML-NAMESPACE and XML-NNAMESPACE are empty with length zero. XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix if the namespace declaration is of the form xmlns: prefix = " namespace-identifier "; otherwise, if the declaration is for the default namespace and thus the attribute name is xmlns , XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX are both empty with length zero. | N/A (ATTRIBUTE-NAME and ATTRIBUTE-CHARACTERS events are signaled instead.)
PROCESSING-INSTRUCTION-DATA | XML-TEXT or XML-NTEXT contains the rest of the processing instruction (after the target name), not including the closing sequence "?>", but including trailing, and not leading, white space characters. This can be a substring of the processing instruction data. | XML-TEXT or XML-NTEXT always contains the complete processing instruction data.
PROCESSING-INSTRUCTION-TARGET | XML-TEXT or XML-NTEXT contains the processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?". This event can occur multiple times for a given processing instruction: one occurrence preceding each substring of the data. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). This event occurs only once for a given processing instruction.
STANDALONE-DECLARATION | XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes ("yes" or "no"), of the stand-alone declaration in the XML declaration. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
START-OF-CDATA-SECTION | All XML special registers except XML-CODE and XML-EVENT are empty with length zero. | XML-TEXT or XML-NTEXT contains the string "<![CDATA[".
START-OF-DOCUMENT | All XML special registers except XML-CODE and XML-EVENT are empty with length zero. | XML-TEXT or XML-NTEXT contains the entire document.
START-OF-ELEMENT | XML-TEXT or XML-NTEXT contains the local part of the start element tag name or the local part of the empty element tag name. If the element name is in a namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier. If the element name is in a namespace and is prefixed (of the form prefix: local-part , XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix. | XML-TEXT or XML-NTEXT contains the name of the start element tag or empty element tag, also known as the element type.
UNKNOWN-REFERENCE-IN-ATTRIBUTE | For XMLPARSE(XMLSS), the parser always signals EXCEPTION. | XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNKNOWN-REFERENCE-IN-CONTENT | For XMLPARSE(XMLSS), the parser signals UNRESOLVED-REFERENCE or EXCEPTION instead. | XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNRESOLVED-REFERENCE | XML-TEXT or XML-NTEXT contains the entity name from XML content, not including the "&" and ";" delimiters. | N/A (The parser signals UNKNOWN-REFERENCE-IN-CONTENT instead.)
VERSION-INFORMATION | XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the version information in the XML declaration. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
Parent topic: Language Structure
Related reference
XML-CODE Exception Codes
JSON-STATUS Non-Exception Codes
JSON-CODE Exception Codes
1 The format of the contents of the CURRENT-DATE special register is sensitive to the CURRENT-DATE directive.
2 For a list of supported exception codes, see the topic JSON-CODE Exception Codes
3 For a list of supported non-exception condition codes, see the topic JSON-STATUS Non-Exception Codes
4 The LENGTH OF special register may be followed by a literal when using the Micro Focus dialect. For a nonnumeric literal, the length is the length of the nonnumeric literal. For a numeric literal other than a floating point literal, the length is the number of digits in the numeric literal, including leading zeroes; the sign and decimal point are not counted, if specified. For a floating point numeric literal, the length includes a sign character (whether specified or not), the digits of the mantissa and exponent (excluding leading zeroes), the decimal point, the "E" or "e" character and the exponent sign (whether specified or not). The length of a figurative constant is 1.
5 The size of the RETURN-CODE special register is sensitive to the XOPEN, RTNCODE-SIZE, and RTNCODE-TYPE directives.
6 For a list of supported exception codes, see the topic XML-CODE Exception Codes.
7 The contents of XML-TEXT and XML-NTEXT vary depending on the contents of XML-EVENT. See Table 2 for additional information.
8 For all events except EXCEPTION, XML-CODE contains zero. Unless stated otherwise, the namespace XML registers (XML-NAMESPACE, XML-NNAMESPACE, XML-NAMESPACE-PREFIX, and XML-NNAMESPACE-PREFIX) are empty and have length zero.


Predefined Object Identifiers

The predefined object identifiers are:

Predefined Object Identifier | Usage
SELF | References the object on which the current method is executing. May be used in the Procedure Division of a method. References the object that was used to invoke the method in which SELF appears. If SELF is specified for a method invocation, the search for the method includes all methods declared for the object.
SELFCLASS | References the object that is the class object of the current object (SELF). If SELF is itself a class object, SELFCLASS is the system class BEHAVIOR. The class object BEHAVIOR terminates this self-reference. (i.e., If SELF is the BEHAVIOR of class, so is SELFCLASS.)
SUPER | References the object on which the current method is executing. May be used in the Procedure Division of a method. May be the object used to invoke a method with the INVOKE statement or inline invocation. References the object that was used to invoke the method in which SELF appears. If SUPER is specified for a method invocation, the search for the method ignores all the methods defined in the same class as the executing method.
NULL | References the null object reference value, which is a unique value that is guaranteed to never reference an object. NULL is implicitly described as class object and category object reference, and is not a universal object reference. NULL must not be specified as a receiving operand.
Parent topic: Language Structure


PICTURE Character-Strings

A PICTURE character-string consists of certain combinations of characters in the COBOL character set, used as symbols. See the topic The PICTURE Clause for the PICTURE character-string and for the rules that govern its use.

Any punctuation character that appears as part of the specification of a PICTURE character-string is not considered to be a punctuation character, but a symbol used in the specification of that PICTURE character-string.

Parent topic: Language Structure
Related information
The PICTURE Clause


Comment-entries

A comment-entry is an entry in the Identification Division that can be any combination of characters from the computer's character set. A comment-entry is for documentary purposes only, may extend over more than one line and is terminated upon encountering a division, section or paragraph name that is a reserved word

OSVS or encountering any character

in area A of a line. The continuation of a comment-entry by the use of the hyphen in the indicator area is not permitted.

Parent topic: Language Structure


Formats and Rules

  • General Format
  • Syntax Rules
  • General Rules
  • Elements
Parent topic: Concepts of the COBOL Language


General Format

A general format is the specific arrangement of the elements of a clause or a statement. Throughout this document a format is shown adjacent to information defining the clause or statement. When more than one specific arrangement is permitted, the general format is separated into numbered formats. Clauses must be written in the sequence given in the general formats. (Clauses that are optional must appear in the sequence shown if they are used.) In certain cases, stated explicitly in the rules associated with a given format, the clauses can appear in sequences other than that shown. Applications, requirements or restrictions are shown as rules.

Parent topic: Formats and Rules


Syntax Rules

Syntax rules are those rules that define or clarify the order in which words or elements are arranged to form larger elements, such as phrases, clauses, or statements. Syntax rules also impose restrictions on individual words or elements.

These rules are used to define or clarify how the statement must be written; that is, the order of the elements of the statement and restrictions on what each element may represent.

Parent topic: Formats and Rules


General Rules

General rules are those rules that define or clarify the meaning or relationship of meanings of an element or set of elements. They are used to define or clarify the semantics of the statement and the effect that it has on either execution or on the way intermediate code is produced.

Parent topic: Formats and Rules


Elements

Elements which make up a clause or a statement consist of upper-case words, lower-case words, level-numbers, brackets, braces, connectives and special characters.

Parent topic: Formats and Rules


Concept of Computer-independent Data Description

To make data as computer-independent as possible, the characteristics or properties of the data are described in relation to a standard data format rather than to an equipment-oriented format. This standard data format is oriented to general data processing applications and uses the decimal system to represent numbers (regardless of the radix used by the computer) and the remaining characters in the COBOL character set to describe nonnumeric data items.

Parent topic: Concepts of the COBOL Language


Concept of Levels

A level concept or hierarchy is inherent in the structure of a logical data record. This concept arises from the need to specify subdivisions of a record for the purpose of data reference. Once a subdivision has been specified, it can be further subdivided to permit more detailed data referral.

The most basic subdivisions of a record, that is, those not further subdivided, are called elementary items; consequently, a record is said to consist of a sequence of elementary items, or the record itself can be an elementary item.

In order to refer to a set of elementary items, the elementary items are combined into groups. Each group consists of a named sequence of one or more elementary items. Groups, in turn, can be combined into groups of two or more groups, and so on. Thus, an elementary item can belong to more than one group.

  • Level-Numbers
Parent topic: Concepts of the COBOL Language


Level-Numbers

A system of level-numbers shows the organization of elementary items and group items. Since records are the most inclusive data items, level-numbers for records start at 01. Less inclusive data items are assigned higher (not necessarily successive) level-numbers not greater in value than 49. A maximum of 49 levels in a record is allowed. There are special level-numbers, 66, 77

MF , 78

and 88 which are exceptions to this rule (see below). Separate entries are written for each level-number used.

A group includes all group and elementary items following it until a level-number less than or equal to the level-number of that group is encountered. All items which are immediately subordinate to a given group item should be described using identical level-numbers greater than the level-number used to describe that group item

OSVS VSC2 ; this rule is not insisted upon

.

Example

Correct OSVS VSC2 MF Incorrect but Permitted
01 A.
  05 C-1.
    10 D PICTURE X.
    10 E PICTURE X.
  05 C-2.

01  A.
  05 C-1.
    10 D PICTURE X.
    10 E PICTURE X.
 04 C-2.

Four types of entries exist for which there is no true concept of level. These are:

  1. Entries that specify elementary items or groups introduced by a RENAMES clause.
  2. Entries that specify noncontiguous working storage and linkage data items.
  3. Entries that specify condition-names.
  4. MF Entries that specify constant-names.

Entries describing items by means of RENAMES clauses for the purpose of regrouping data items have been assigned the special level-number 66.

Entries that specify noncontiguous data items, which are not subdivisions of other items, and are not themselves subdivided, have been assigned the special level-number 77.

Entries that specify condition-names, to be associated with particular values of a conditional variable, have been assigned the special level-number 88.

MF Entries that specify constant-names, to be associated with the value of a particular literal, have been assigned the special level-number 78.

Figure 1. Example of Level-numbers Representing a Data Hierarchy
Example of Level-numbers Representing a Data Hierarchy

Note that indentation of COBOL source code is a readability convention only and is not part of the language.

Elementary items are by definition those items without any subordinate entries (entries without numerically greater level-numbers) following, and must have a storage definition associated with them (see the topics The PICTURE Clause and the The USAGE Clause).

Note that only elementary items (marked with an asterisk, "*", above) and FILLER items (marked with a "#" sign above) have storage explicitly reserved for them (in accordance with the associated PICTURE clause); non-elementary items have implicit storage associated with them of size determined by their subordinate items plus any FILLER bytes needed for synchronization (see the topic The SYNCHRONIZED Clause).

Level-numbers need not be consecutively ascending or descending as shown above for clarity; thus, the next subordinate level after 01 could be 05, and the next level 10, and so on.

The above data descriptions would produce storage allocation in the following manner:

Data Record Storage Allocation

where:

R-E-I | is Record-Entry-Item
M-G-I | is Major-Group-Item
R-G-I | is Regular-Group-Item
S-G | is Sub-Group
EI | is Elementary-Item
NEI | is Noncontiguous Elementary-Item
Parent topic: Concept of Levels
Related information
The PICTURE Clause
The USAGE Clause
The SYNCHRONIZED Clause


Class and Category of Data

Every elementary data item, every literal, and every function has a class and a category. The class and category of a data item are defined by its picture character string, by the BLANK WHEN ZERO clause, or by its usage; the class and category of a literal are defined in the section Literals.

ANS85 and the class and category of an intrinsic function are specified by the definition of that intrinsic function (see the topic Intrinsic Functions).

The category of a group item is alphanumeric.

The following table depicts the relationship of categories to classes of data for elementary items.

Table 1. Category and class relationships for elementary items
Class Category
Alphabetic
  • Alphabetic
Alphanumeric
  • Numeric edited
  • Alphanumeric edited
  • Alphanumeric
  • VSC2 MF DBCS
Index
  • Index
National
  • National
Numeric
  • Numeric
  • OSVS VSC2 MF Internal floating-point
  • OSVS VSC2 MF External floating-point
Object
  • ISO2002 MF Object-reference
Pointer
  • ISO2002 VSC2 MF Pointer
  • MF COB370 Procedure-pointer
  • Algebraic Signs
  • Standard Alignment Rules
  • Item Alignment for Increased Object-code Efficiency
  • Selection of Character Representation and Radix
  • Uniqueness of Reference
  • Explicit and Implicit Specifications
Parent topic: Concepts of the COBOL Language
Related information
Literals
Intrinsic Functions


Algebraic Signs

Algebraic signs fall into two categories:

  1. Operational signs, which are associated with signed numeric data items and signed numeric literals to indicate their algebraic properties.
  2. Editing signs, which appear on edited reports to identify the sign of the item.

The SIGN clause permits you to state explicitly the location of the operational sign. The clause is optional; if it is not used, operational signs are represented as described in the section Selection Of Character Representation And Radix.

Editing signs are inserted into a data item through the use of the sign control symbols of the PICTURE clause.

Parent topic: Class and Category of Data
Related information
Selection Of Character Representation And Radix


Standard Alignment Rules

The standard rules for positioning data within an elementary item depend on the category of the receiving item. These rules are:

  1. If the receiving data item is described as numeric:
    1. The data is aligned by decimal point and is moved to the receiving character positions with zero fill or truncation on either end as required
    2. When an assumed decimal point is not explicitly specified, the data item is treated as if it had an assumed decimal point immediately following its rightmost character and is aligned as in paragraph a. above.
  2. If the receiving data item is a numeric edited data item, the data moved to the edited item is aligned by decimal point with zero fill or truncation at either end as required within the receiving character positions of the data item, except where editing requirements cause replacement of the leading zeros.
  3. If the receiving data item is alphanumeric (other than a numeric edited data item), alphanumeric edited or alphabetic, the sending data is moved to the receiving character position and aligned at the leftmost character position in the data item with space fill or truncation to the right, as required.
  4. OSVS VSC2 MF If the receiving data item is external floating-point, the leftmost non-zero digit, if one exists, is aligned on the leftmost digit position: the exponent is adjusted accordingly.

If the JUSTIFIED clause is specified for the receiving item, these standard rules are modified as described in the section The JUSTIFIED Clause in the chapter Data Division - File and Data Description.

Parent topic: Class and Category of Data
Related information
The JUSTIFIED Clause


Item Alignment for Increased Object-code Efficiency

Some computer memories are organized so that natural addressing boundaries exist in the computer memory (for example, word boundaries, half-word boundaries, byte boundaries). The way in which data is stored need not respect these natural boundaries.

However, certain uses of data (for example, in arithmetic operations or in subscripting) can be facilitated if the data is stored so as to be aligned on these boundaries. Specifically, additional machine operations in the run-time element can be repeated for the accessing and storage of data if portions of two or more data items appear between adjacent natural boundaries, or if certain natural boundaries divide a single data item.

Data items which are aligned on these natural boundaries in such a way as to avoid additional machine operations are defined to be synchronized. A synchronized item is assumed to be introduced and carried in that form; conversion to synchronized form occurs only during the execution of a statement (other than READ or WRITE) which stores data in the item.

Synchronization can be accomplished in two ways:

  1. By use of the SYNCHRONIZED clause
  2. By organizing the data suitably on the appropriate natural boundaries without the use of the SYNCHRONIZED clause.

By use of the SYNCHRONIZED clause, the use of special types of alignment within a group can affect the results of statements in which the group is used as an operand. The effect of the implicit FILLER and the semantics of any statement referencing these groups is described later in this chapter.

Parent topic: Class and Category of Data


Selection of Character Representation and Radix

The value of a numeric item (defined as numeric by its PICTURE, see the topic The PICTURE Clause) can be represented in the computer's storage in either binary or decimal form depending on the USAGE clause of the declaration (see the topic The USAGE Clause). These numeric formats are:

  • DISPLAY
  • COMPUTATIONAL, COMP,

    ANS85 BINARY,

    OSVS VSC2 MF COMPUTATIONAL-4 or COMP-4

  • OSVS VSC2 MF XOPEN COMPUTATIONAL-3, COMP-3 or

    ANS85 PACKED-DECIMAL

  • MF XOPEN OS390 COMPUTATIONAL-5, COMP-5,
  • MF COMPUTATIONAL-X or COMP-X

  • OSVS VSC2 MF COMPUTATIONAL-1, COMPUTATIONAL-2

    ,

    ISO2002 FLOAT-SHORT or FLOAT-LONG

  • VSC2 MF POINTER
  • MF COB370 PROCEDURE-POINTER

ANS85 An alphanumeric function is always represented in the standard data format. Its size is determined by the definition of the function.

The representation of integer and numeric functions is as follows:

  • COMP-2 if the function is trigonometric or if one or more function arguments are COMP-2 and the function is not defined as returning an integer.
  • Otherwise, as PIC SV9(39)ES9(4). The exponent is S9(4) COMP and so has a range of approximately +/-32k.

Integer and numeric functions can be used only in arithmetic expressions, and represent the value resulting from the evaluation of the function without the restriction on composite of operands and/or receiving data items.

When a computer provides more than one means of representing data, the standard data format must be used for data items

ANS85 other than integer and numeric functions,

if not otherwise specified by the data description.

  • DISPLAY Format
  • COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format
  • COMPUTATIONAL-1, COMPUTATIONAL-2,FLOAT-SHORT and FLOAT-LONG Formats
  • COMPUTATIONAL-3 or PACKED-DECIMAL Format
  • COMPUTATIONAL-X and COMPUTATIONAL-5 Formats
  • POINTER Format
  • PROCEDURE-POINTER Format
Parent topic: Class and Category of Data
Related information
The PICTURE Clause
The USAGE Clause


DISPLAY Format (COBOL)

DISPLAY Format

The COBOL digit characters from 0 through 9 that represent the number value are held in radix 10, one digit character per byte of computer storage. This is the standard data format of the COBOL language.

If the data item is signed and the sign is not specified as SEPARATE (see the topic The SIGN Clause and the rules for the NUMERIC SIGN clause in the topic The Special-Names Paragraph) the numeric sign is incorporated into either the leading or trailing digit, according to the LEADING or TRAILING phrase in the SIGN clause. Signed data is incorporated into the requisite digit as shown in Table 4 below. (Effectively, bit 6 (hexadecimal value "40" ) of the character is set from 0 to 1 if the number has a negative value.)

If the data item is signed and the sign is specified as SEPARATE, then the sign is held as a separate single COBOL character, additional to the digits, either plus (+) or minus (-) as necessary.

If the data item is signed and no SIGN clause applies, the numeric sign is incorporated into the trailing digit, unless the NUMERIC SIGN clause is specified in the Special-Names paragraph. If the SIGN clause is specified in a data description entry, the NUMERIC SIGN clause, if specified, is ignored for that entry.

In the following table, the numbers in brackets represent the hexadecimal encoding for the COBOL character. On some systems, the encoding can be varied by the CHARSET and SIGN Compiler directives.

Table 1. DISPLAY Non-SEPARATE Sign-Digit Characters
Leading or trailing value digit before sign incorporation | Sign Digit Character for:
 | Positively-signed values |  |  | Negatively-signed values
 | Charset (ASCII) |  | Charset (EBCDIC) | Charset (ASCII) |  | Charset (EBCDIC)
 | Sign (ASCII) | Sign (EBCDIC) | Sign (EBCDIC) | Sign (ASCII) | Sign (EBCDIC) | Sign (EBCDIC)
0 | 0(30) | {(7B) | {(C0) | p(70) | }(7D) | }(D0)
1 | 1(31) | A(41) | A(C1) | q(71) | J(4A) | J(D1)
2 | 2(32) | B(42) | B(C2) | r(72) | K(4B) | K(D2)
3 | 3(33) | C(43) | C(C3) | s(73) | L(4C) | L(D3)
4 | 4(34) | D(44) | D(C4) | t(74) | M(4D) | M(D4)
5 | 5(35) | E(45) | E(C5) | u(75) | N(4E) | N(D5)
6 | 6(36) | F(46) | F(C6) | v(76) | O(4F) | O(D6)
7 | 7(37) | G(47) | G(C7) | w(77) | P(50) | P(D7)
8 | 8(38) | H(48) | H(C8) | x(78) | Q(51) | Q(D8)
9 | 9(39) | I(49) | I(C9) | y(79) | R(52) | R(D9)

Storage character position requirements for DISPLAY data items are thus equal to the number of "9"s in the PICTURE clause plus one if the sign is specified as SEPARATE. The SYNCHRONIZED clause has no effect on DISPLAY format data declarations.

Parent topic: Selection of Character Representation and Radix
Related information
The SIGN Clause
The Special-Names Paragraph


COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format

COMPUTATIONAL, ANS85 BINARY, or OSVS VSC2 MF COMPUTATIONAL-4 Format

This format holds numeric data items in computer storage in pure binary two's complement representation. In this format, number values are held in radix of 2 where each computer bit in the representation starting from the right (least-significant) end represents the presence or absence of an increasingly significant power of 2 in that value. Negative numbers are represented by complementing (inverting all the bit values of) their positive counterpart, and then adding one to the whole. Storage requirements depend on the number of "9"s in the PICTURE clause, and whether the numeric data item is signed or unsigned (see the topics The PICTURE Clause, The SIGN Clause and The USAGE Clause); also your COBOL system assigns storage for COMPUTATIONAL items in one of two modes; byte-storage and word-storage. Byte-storage is the default storage-assignment mode for this COBOL implementation.

  • Computer Memory Natural Boundaries
  • Synchronization
  • Implicit Synchronization
  • Example of Implicit FILLER Assignments
  • Truncation
Parent topic: Selection of Character Representation and Radix
Related information
The PICTURE Clause
The SIGN Clause
The USAGE Clause


Computer Memory Natural Boundaries

The fundamental natural boundaries of a modern computer's memory are usually based on an eight-bit character, known as a byte. Within this fundamental framework, machines fall into two broad categories; those with no other natural boundaries, called here byte-storage computers, and those with other natural boundaries based upon multiples of the fundamental boundary of the byte, called here word-storage computers.

In byte-storage mode, COBOL assigns numeric storage so that each numeric item occupies the minimum number of bytes (see the section Selection Of Character Representation And Radix); the SYNCHRONIZED clause has no meaning in the context and hence has no effect.

Within word-storage computers, natural boundaries can occur at 2-byte, 4-byte and/or 8-byte boundaries. The COBOL language can provide such data item storage-assignment and synchronization when the COMPUTATIONAL clause and possibly the SYNCHRONIZED clause are used. This word-storage assignment of COMPUTATIONAL format data is controlled by the Compiler directive IBMCOMP.

Table 1. COMP(UTATIONAL) Format Data Item Character-Position (Byte) Storage Assignment
Number of Digits (9s) in PICTURE Representation |  | Number of Characters (Bytes) of Storage Assigned
Signed | Unsigned | Byte-Storage Mode | Word-Storage Mode
1-2 | 1-2 | 1 | 2
3-4 | 3-4 | 2 | 2
5-6 | 5-7 | 3 | 4
7-9 | 8-9 | 4 | 4
10-11 | 10-12 | 5 | 8
12-14 | 13-14 | 6 | 8
15-16 | 15-16 | 7 | 8
17-18 | 17-19 | 8 | 8
19-21 | 20-21 | 9 | 16
22-23 | 22-24 | 10 | 16
24-26 | 25-26 | 11 | 16
27-28 | 27-28 | 12 | 16
29-31 | 29-31 | 13 | 16
32-33 | 23-33 | 14 | 16
34-35 | 34-36 | 15 | 16
36-38 | 37-38 | 16 | 16
Parent topic: COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format
Related information
Selection Of Character Representation And Radix


Synchronization

If a data item description contains the SYNCHRONIZED clause, and word-storage mode is enabled, the position of that item within the computer storage is aligned so that the right-hand (least-significant) end is on a natural boundary of the computer's storage. Extra character positions (bytes) of computer storage are reserved adjacent to synchronized items to achieve this alignment; these bytes, known as padding bytes or implicit FILLER bytes, are normally inaccessible to the computer program except as part of a group item.

Each elementary data item that is described as SYNCHRONIZED is aligned to the natural storage boundary that corresponds to its data item storage assignment (according to Table 5 in the topic Computer Memory Natural Boundaries above). Thus, in word-storage mode, a numeric data item with a PICTURE description of S9(5) would be assigned 4 bytes of storage (being 1 padding byte and 3 data bytes). If SYNCHRONIZED was specified, it would be aligned to the next nearest 4-byte boundary (that is, with the total (4-byte) storage assignment aligned such that the number of bytes from the beginning of the record containing that item to the left-hand (most-significant) end of that item was a multiple of four). If the previous item does not end on a 4-byte boundary, implicit FILLER assignments are necessary to achieve this.

Other such implicit FILLER bytes can be generated by the use of SYNCHRONIZED items in non-elementary data descriptions containing an OCCURS clause (see the topic The OCCURS Clause). This is because further bytes may need to be reserved for each group item occurrence in order that the second or subsequent occurrences have the same alignment to the natural boundaries of the computer storage as did the first occurrence.

Parent topic: COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format
Related information
Computer Memory Natural Boundaries
The OCCURS Clause


Implicit Synchronization

With word-storage mode enabled, all record-level data descriptions are automatically synchronized to a full 8-byte boundary.

MF Where automatic alignment is enabled, it is sensitive to the ALIGN directive.

Parent topic: COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format


Example of Implicit FILLER Assignments

The following COBOL data description produces the computer storage allocation shown in the figure below. An explanation of the symbols used is given below the figure.

01 UNSYNCHRONIZED-RECORD.
    02 UNSYNCHRONIZED-DATA-1        PIC 9(3) DISPLAY.
    02 UNSYNCHRONIZED-DATA-2        PIC X(2).
01 COMPOUND-REPEATED-RECORD.
    02 ELEMENTARY-ITEM-1            PIC X(2).
    02 GROUP-ITEM OCCURS 3 TIMES.
 03 ELEMENTARY-ITEM-2        PIC X.
 03 ELEMENTARY-ITEM-3        PIC S9(2) COMP SYNC.
 03 ELEMENTARY-ITEM-4        PIC S9(4)V9(2) COMP SYNC.
 03 ELEMENTARY-ITEM-5        PIC X(5).
Figure 1. Sample Computer Storage Allocation
Sample Computer Storage Allocation

where:

@ | indicates implicit FILLER bytes allocated due to automatic synchronization of a record (01-level) description.
# | indicates implicit FILLER bytes allocated when following data item is explicitly synchronized.
$ | indicates implicit FILLER bytes allocated when a non-elementary item is subject to an OCCURS clause.
9 | indicates bytes allocated for a numeric DISPLAY character.
A | indicates bytes allocated for an alphanumeric DISPLAY character.
C | indicates bytes allocated for a COMPUTATIONAL data storage.
Parent topic: COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format


Truncation

In data items of USAGE COMP, data is held in binary format as described in the previous sections. The storage allocated for an item can have space for larger numbers than specified by the PICTURE clause. For example, an item described as PIC 99 COMP is normally assigned one byte, which can hold numbers up to 255.

To conform with the rules of ANSI COBOL, numbers behave as decimal numbers, regardless of their format. If, in an arithmetic statement, the result is bigger than the PICTURE clause of a receiving item allows, a size error occurs, and if the ON SIZE ERROR phrase is specified the result is not stored in the receiving item. In a non-arithmetic statement, if this situation occurs, the decimal value is truncated on the left, to the number of digits specified in the PICTURE clause.

OSVS VSC2 MF However, data in USAGE COMP items can be forced to behave as binary data, that is, truncation occurs only if it is necessary in order for the data to fit the space allocated. The behavior of USAGE COMP items is controlled by the setting of the COBOL Compiler directive TRUNC. This directive selects whether the decimal value is truncated to the picture size, or the binary value is truncated to the space available. It distinguishes between results of arithmetic statements, and data being moved by non-arithmetic statements.

Regardless of the setting of any directive, an arithmetic statement gives the size error condition if the result has more decimal digits than specified in the PICTURE clause of a receiving item.

  • Example of Truncation
Parent topic: COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format


Example of Truncation

The TRUNC Compiler directive can change the results of some operations, as demonstrated in the following examples in which item A is described as PIC 99 COMP.

Operation | Result
 | TRUNC | NOTRUNC | TRUNC"ANSI"
MOVE 163 TO A | 63 | 163 | 63
MOVE 263 TO A | 63 | 7 | 63
MOVE 13 TO A, ADD 150 TO A | 63 | 163 | undefined results
MOVE 13 TO A, ADD 250 TO A | 63 | undefined results | undefined results
Note:
  1. This directive has no effect on the truncation of low-order digits in non-integer data. This always conforms with the behavior specified in ANSI COBOL.
  2. If the IBMCOMP Compiler directive is set, extra upper bytes may be allocated to a COMP item. These are counted in the space allocated. When IBMCOMP is on, padding bytes may be generated before a COMP item with a SYNC clause; these are not part of the item, and are never affected by data stored in the item.
  3. When a value being stored into a signed item is limited to the number of digits by the PICTURE clause, it can never be big enough to overwrite the sign bit. When the NOTRUNC directive is set this is not true, and the value, if large enough, overwrites the sign bit.
Parent topic: Truncation


COMPUTATIONAL-1, COMPUTATIONAL-2,FLOAT-SHORT and FLOAT-LONG Formats

OSVS VSC2 MF COMPUTATIONAL-1, COMPUTATIONAL-2, ISO2002 FLOAT-SHORT and FLOAT-LONG Formats

These formats are used for internal floating-point data items. Such data items can be used in all syntax where a numeric data item can be used and where the syntax is a part of the ANSI'74, ANSI'85, ISO2000, OSVS, or VSC2 COBOL language definition. Such data items cannot be used where integer data items are required unless explicitly allowed by the rules for a specific COBOL verb. An internal floating-point data item cannot be used in other syntax unless a specific rule allows it.

The internal storage format can differ from operating system to operating system. In all storage formats, four pieces of information are encoded:

  1. The exponent - the power of 10 to which the specific numeric value is multiplied.
  2. The exponent sign - an indication of whether the specific numeric value (significand) is multiplied by a "whole" number in the series, 1, 10, 100, and so on, or by a fractional number in the series 1/10, 1/100, 1/1000, and so on.
  3. The significand - the specific value, which when multiplied by a power of 10 provides the numeric value of the data item.
  4. The significand sign - an indication of whether the resultant value of the data item is negative or positive.

ISO2002 USAGE FLOAT-SHORT is equivalent to USAGE COMPUTATIONAL-1. USAGE FLOAT-LONG is equivalent to USAGE COMPUTATIONAL-2.

Items that are USAGE COMPUTATIONAL-1 (COMP-1) are usually referred to as single precision floating-point items while items that are USAGE COMPUTATIONAL-2 (COMP-2) are usually referred to as double precision floating-point items. Depending on the operating system or mathematical support libraries available to this COBOL system, different constraints can exist for single and double precision floating-point items. There can be constraints on the maximum exponent sizes, on the maximum significand sizes, or both. See your operating system or mathematical library floating-point support documentation for additional information.

COMPUTATIONAL-1 and COMPUTATIONAL-2 are equivalent to Single Format and Double Format, respectively, for operating systems that conform to ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point Arithmetic.

It is important to understand that internal floating-point representation is not a continuous numeric spectrum. Internal floating-point representations are not standard from operating system to operating system. For example, in one representation of internal floating-point values, the following shows internal to decimal equivalence:

Internal (Hexadecimal) Storage | Decimal Value (Scientific Notation)
x"AD17E148" | -0.12345673E-23
x"AD17E149" | -0.12345810E-23

Therefore, any application which tested for or expected an internal floating-point item with an exact decimal value of -0.12345678E-23, would never find it, while in some other system of internal floating-point storage, that value might be found while the values listed above would never exist. Therefore, any application which tests for exact equivalence between internal floating-point items and other numeric values (including external floating-point items and floating-point literals) cannot be portable and may result in different logic flow even when using the same input data.

For internal floating-point items, the size of the item in storage is determined by its USAGE clause. USAGE COMPUTATIONAL-1 reserves 4 bytes of storage for the item; USAGE COMPUTATIONAL-2 reserves 8 bytes of storage.

When the IBMCOMP Compiler directive is on, padding bytes can be generated before an internal floating-point item with a SYNC clause; these bytes are not part of the item, and are never affected by data stored in the item.

Within the COBOL system, COMP-1 items are accurate to 7 decimal digits and COMP-2 items to 16 decimal digits. However, for mainframe compatibility the DISPLAY statement shows 8 decimal places for COMP-1 and 18 for COMP-2. Any operations using floating-point items should take the limits of accuracy into account, and should disregard decimal places beyond the limits of accuracy.

Parent topic: Selection of Character Representation and Radix


COMPUTATIONAL-3 or PACKED-DECIMAL Format

COMPUTATIONAL-3 ANS85 or PACKED-DECIMAL Format

This format, commonly called binary-coded decimal format, represents numeric data items in radix 10, but with each digit of the value held in only one half of one computer character, as described in the table below. The sign is held in a separate trailing digit (half-character) position; that is, at the right-hand or least significant end of the item.

MF Any unused half bytes are set to zero.

Table 1. COMPUTATIONAL-3 Digit Representation
Digit Value | Digit Representation in Hexadecimal
 | Left Half-Character (odd digit) | Right Half-Character (even digit)
0 | x"00" | x"00"
1 | x"10" | x"01"
2 | x"20" | x"02"
3 | x"30" | x"03"
4 | x"40" | x"04"
5 | x"50" | x"05"
6 | x"60" | x"06"
7 | x"70" | x"07"
8 | x"80" | x"08"
9 | x"90" | x"09"
OSVS VSC2 MF XOPEN Note: Count even and odd starting from the right.

The table immediately below shows the sign digit used for COMPUTATIONAL-3. Storage requirements for this format depend only on the number of "9s" in the PICTURE clause of the data item as shown in the second table.

Table 2. COMPUTATIONAL-3 Sign Digit Representation
Sign Convention in the PICTURE Clause | Sign of Data Item Value | Sign Half-character, in Hexadecimal
Unsigned | n/a | x"0F"
Signed | + | x"0C"
Signed | - | x"0D"
Table 3. Numeric Data Storage for the COMP(UTATIONAL)-3 ANS85 or PACKED-DECIMAL PICTURE Clause.
Bytes Required | Number of Digits (Signed or Unsigned)
1 | 1
2 | 2-3
3 | 4-5
4 | 6-7
5 | 8-9
6 | 10-11
7 | 12-13
8 | 14-15
9 | 16-17
10 | 18-19
11 | 20-21
12 | 22-23
13 | 24-25
14 | 26-27
15 | 28-29
16 | 30-31
17 | 32-33
18 | 34-35
19 | 36-37
20 | 38

Example:

  1. For COMPUTATIONAL-3 and PICTURE 9999, the number +1234 would be stored as follows:

    where F represents the non-printing plus sign.

  2. For COMPUTATIONAL-3 and PICTURE S9999, the number + 1234 would be stored as follows:

    where C represents the plus sign.

  3. For COMPUTATIONAL-3 and PICTURE S9999, the number -1234 would be stored as follows:

    where D represents the minus sign.

The SYNCHRONIZED clause (with or without the LEFT or RIGHT phrase) has no effect on COMPUTATIONAL-3 data declarations.

Parent topic: Selection of Character Representation and Radix


COMPUTATIONAL-X and COMPUTATIONAL-5 Formats

MF COMPUTATIONAL-X and COMPUTATIONAL-5 Formats

These formats are as for COMPUTATIONAL format except for the differences given below. See the section COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format.

They both differ in the following ways from the COMPUTATIONAL format:

  • The PICTURE character-string can consist of all "x"s. If it does, the number of "x"s gives the length of the item in bytes.
  • Whether the PICTURE character-string consists of "x" s or "9"s, the value that can be stored is limited to the largest binary number for which the allocated storage has space. The item is not affected by the TRUNC, COMP, and ALIGN Compiler directives. However, the 38-digit system limit can be affected by the ARITH and DIALECT directives.
  • The number of "9"s in the PICTURE character string affect the run-time element if the item is a destination field in an arithmetic operation including an ON SIZE ERROR or NOT ON SIZE ERROR clause: the number of "9"s determines whether or not a size error condition is deemed to have arisen due to a decimal digit overflow. When either clause is present, only arithmetic results falling within this range, that is, not causing a size error, are stored.
  • The following are the only differences between COMPUTATIONAL-X and COMPUTATIONAL-5 formats:
    • A COMPUTATIONAL-5 data item can be signed; a COMPUTATIONAL-X data item must not be signed. When "x"s are used in the PICTURE clause for a COMP-5 data item, it is treated as unsigned, not signed.
    • A COMPUTATIONAL-X item is always stored using the same storage scheme as BINARY items, that is with the high-order bytes stored at the lowest addresses and successively lower-order bytes at successively higher addresses.

      The storage of COMPUTATIONAL-5 items is operating system-specific. In some operating systems COMPUTATIONAL-5 items are stored in the same format as COMPUTATIONAL-X items and in others they are stored with the low-order bytes stored at the lowest addresses and successively higher-order bytes stored at successively higher addresses. For example, under operating systems which store numeric items in reverse order, a PIC X(5) COMPUTATIONAL-5 item with a numeric internal value of:

      h "12 34 56 78 9A"

      would be stored as:

      9A 78 56 34 12

      while a COMPUTATIONAL-X item (or a COMPUTATIONAL-5 item on an operating system without reverse numeric storage) would be stored as:

      12 34 56 78 9A

    • A COMPUTATIONAL-5 item is affected by the IBMCOMP Compiler directive and possibly the SYNCHRONIZED clause; a COMPUTATIONAL-X item is not.
  • If a non-arithmetic statement attempts to store a negative value in a COMPUTATIONAL-X or unsigned COMPUTATIONAL-5 item, the value is stored in two's complement, as if the item had been signed.

    The result of a statement attempting to store a negative value in an unsigned COMPUTATIONAL-5 item is sensitive to the COMP-5 Compiler directive.

Parent topic: Selection of Character Representation and Radix
Related information
COMPUTATIONAL, BINARY, or COMPUTATIONAL-4 Format


POINTER Format

The POINTER format holds a value that represents the memory address of an available data item. If the data item becomes unavailable (for example, because it is in a program that has been canceled) then the POINTER format is considered to hold a value that is incompatible with the format.

The default amount of storage allocated for the POINTER format may vary depending on the operating environment but is at least four bytes. The method of representation of the memory address varies between environments and is in general consistent with the representation used in non-COBOL languages.

When the IBMCOMP system directive is on, padding bytes can be generated before a pointer data item with a SYNC clause; these bytes are not part of the data item and are never affected by data stored in the item.

Parent topic: Selection of Character Representation and Radix


PROCEDURE-POINTER Format

The PROCEDURE-POINTER format holds a value that represents the memory address of an available procedure. If the procedure becomes unavailable (for example, because it is in a program that has been canceled) then the PROCEDURE-POINTER format is considered to hold a value that is incompatible with the format.

The default amount of storage allocated for the PROCEDURE-POINTER format may vary depending on the operating environment but is at least four bytes. If the COBOL370 directive is specified, then eight bytes of storage are allocated. The method of representation of the memory address varies between environments and is in general consistent with the representation used in non-COBOL languages.

When the IBMCOMP system directive is on, padding bytes can be generated before a procedure-pointer data item with a SYNC clause; these bytes are not part of the data item and are never affected by data stored in the item.

Parent topic: Selection of Character Representation and Radix


Uniqueness of Reference

  • Qualification
  • Subscripting
  • Indexing
  • Function-identifier
    A function-identifier references the unique data item that results from the evaluation of a function.
  • Reference Modification
    Reference modification defines a unique data item by specifying an identifier, a leftmost position and a length.
  • Identifier
    An identifier is a sequence of character-strings and separators used to reference data uniquely.
  • Condition-name
    Each condition-name must be unique, or be made unique through qualification and/or indexing, or subscripting. If qualification is used to make a condition-name unique, the associated conditional variable can be used as the first qualifier. The hierarchy of names associated with the conditional variable or the conditional variable itself must be used to make the condition-name unique.
  • Object property
    Object properties provide a special syntax to get information out of and pass information back into an object. The mechanisms for accessing object properties are get property methods and set property methods. A get property method is a method explicitly defined with the GET PROPERTY phrase or a method implicitly generated for a data item described with the PROPERTY clause; a set property method is a method explicitly defined with the SET PROPERTY phrase or a method implicitly generated for a data item described with the PROPERTY clause.
  • Inline method invocation
    Inline method invocation references a temporary data item returned from invocation of a method.
  • Object-view
    An object-view causes an object reference to be treated as though it had the specified description. A runtime conformance check for this description will be done on the object.
  • Data-address-identifier
    A data-address-identifer references the unique data item that contains the address of a data item.
  • Type of identifier
    The TYPE OF identifier obtains the System.Type object for a class, interface, delegate or enumeration.
  • Program-address-identifier
Parent topic: Class and Category of Data


Qualification

Every user-specified name that defines an element in a COBOL source element.

ANS85 and is referenced in that source element

must be unique, either because no other name has the identical spelling and hyphenation, or because the name exists within a hierarchy of names such that references to the name can be made unique by mentioning one or more of the higher levels of the hierarchy. The higher levels are called qualifiers and the process that specifies uniqueness is called qualification. Enough qualification must be mentioned to make the name unique; however, it may not be necessary to mention all levels of the hierarchy.

In the Data Division, all data-names used for qualification must be associated with a level indicator or a level-number. Therefore, two identical data-names must not appear as entries subordinate to a group item unless they are capable of being made unique through qualification

ANS85 or they are never referenced

. In the Procedure Division, two identical paragraph-names must not appear in the same section.

In the hierarchy of qualification, names associated with a level indicator are the most significant, followed by those names associated with level-number 01, followed by names associated with level-number 02 through 49. A section-name is the highest (and the only) qualifier available for a paragraph-name. Thus, the most significant name in the hierarchy must be unique and cannot be qualified. Subscripted or indexed data-names and conditional variables, as well as procedure-names and data-names, can be made unique by qualification. The name of a conditional variable can be used as a qualifier for any of its condition-names. Regardless of the available qualification, no name can be both a data-name and procedure-name.

Qualification is performed by following a data-name, a condition-name, a paragraph-name, or a text-name by one or more phrases composed of a qualifier preceded by IN or OF, which are logically equivalent.

ANS85 When the resource named is a function, the function definition may require the user to specify in the reference to the function a value or set of values for one or more parameters which determine the value of the function for that particular reference. This is accomplished through the specification of arguments as described in the section Function-identifier.

General Format: for Format 1

General Format: for Format 2

General Format: for Format 3

General Format: for Format 4

General Rules:

  1. Each qualifier must be of a successively higher level and within the same hierarchy as the name it qualifies.
  2. The same name must not appear at two levels in a hierarchy

    ANS85 if it is explicitly referenced within the source unit

    .

  3. If a data-name or a condition-name is assigned to more than one data item in a source element, the data-name or condition-name must be qualified each time it is referred to in the Procedure, Environment, and Data Divisions (except in the REDEFINES clause, where qualification must not be used).
  4. A paragraph-name must not be duplicated within a section. When a paragraph-name is qualified by a section-name, the word SECTION must not appear. A paragraph-name need not be qualified when referred to from within the same section.

    ANS85 Neither a paragraph-name nor a section-name need be unique, or capable of being made unique, unless explicitly referenced.

  5. A data-name cannot be subscripted when it is being used as a qualifier.
  6. A name can be qualified even when it does not need qualification; if there is more than one combination of qualifiers that ensures uniqueness, then any such set can be used. The complete set of qualifiers for a data-name must not be the same as any partial set of qualifiers for another data-name.

    Qualified data-names can have up to five qualifiers.

    ANS85 Up to fifty qualifiers are permitted.

  7. If more than one COBOL library is available to your COBOL system, text-name must be qualified each time it is referenced.

    OSVS VSC2 MF This restriction is not enforced.

Parent topic: Uniqueness of Reference
Related information
Function-identifier


Subscripting

Subscripts can be used only when reference is made to an individual element within a list or table of like elements that have not been assigned individual data-names (see the topic The OCCURS Clause).

The subscript can be represented either by a numeric literal that is an integer, by a data-name, or by a data-name followed by the operator "+" or "-" , followed by an unsigned integer numeric literal. The data-name must be a numeric elementary item that represents an integer, and the whole subscript must be delimited by the balanced pair of separators, left-parenthesis and right-parenthesis.

The subscript data-name can be signed and, if signed, must be positive. The lowest possible subscript value is 1. This value points to the first element of the table. The next sequential elements of the table are pointed to by subscripts whose values are 2, 3, ... . The highest permissible subscript value, in any particular case, is the maximum number of occurrences of the item as specified in the OCCURS clause.

The subscript, or set of subscripts, that identifies the table element is delimited by the balanced pair of separators, left parenthesis and right parenthesis following the table element data-name. The table element data-name appended with a subscript is called a subscripted data-name or an identifier. When more than one subscript is required, they are written in the order of successively less inclusive dimensions of the data organization. Up to 3 subscripts are permitted.

ANS85 Up to 7 subscripts are permitted.

MF Up to 16 subscripts are permitted.

General Format

Syntax Rules

  1. The data description entry containing data-name-1 or the data-name associated with condition-name-1 must contain an OCCURS clause or must be subordinate to a data description entry which contains an OCCURS clause.
  2. Except as defined in Syntax Rule 7, when a reference is made to a table element, the number of subscripts must equal the number of OCCURS clauses in the description of the table element being referenced. When more than one subscript is required, the subscripts are written in the order of successively less inclusive dimensions of the table.
  3. ANS85 The subscript ALL can be used only when the subscripted identifier is used as a function argument and cannot be used when condition-name-1 is specified. (See the topic Arguments.)
  4. Integer-1 can be signed, and if signed, must be positive.
  5. Data-name-2 can be qualified and must be a numeric elementary item representing an integer.
  6. Index-name-1 must correspond to a data description entry in the hierarchy of the table being referenced which contains an INDEXED BY phrase specifying that index-name.

    OSVS VSC2 MF An index described for some other table can be used instead, provided the two tables have elements of the same size.

  7. Each table element reference must be subscripted except when such reference appears:
    1. In a USE FOR DEBUGGING statement
    2. As the subject of a SEARCH or SORT statement
    3. In a REDEFINES clause
    4. In the KEY IS phrase of an OCCURS clause.
  8. OSVS The mixing of subscripts and indices in the same identifier is illegal.

    ANS85 The mixing of subscripts and indices in the same identifier is legal.

General Rules

  1. The value of the subscript must be a positive integer. The lowest possible occurrence number represented by a subscript is 1. The first element of any given dimension of a table is referenced by an occurrence number of 1. Each successive element within that dimension of the table is referenced by occurrence numbers of 2, 3, ... . The highest permissible occurrence number for any given dimension of the table is the maximum number of occurrences of the item specified in the associated OCCURS clause.

    MF If the subscript is a floating-point data item, the value is rounded to the nearest integer, otherwise any fractional part is truncated.

    If arithmetic-expression-1 is specified, and the final result of the arithmetic expression is not an integer, the final result is truncated. Intermediate results are not truncated.

    If arithmetic-expression-1 is specified, and if the final result or any intermediate result of the arithmetic expression is negative, the effect is unpredictable.

  2. The value of the index referenced by index-name-1 corresponds to the occurrence number of an element in the associated table.
  3. The value of the index referenced by index-name-1 must be initialized before it is used as a subscript. An index can be given an initial value by either a PERFORM statement with the VARYING phrase, a SEARCH statement with the ALL phrase, or a SET statement. An index can be modified only by the PERFORM, SEARCH, and SET statements.
  4. If

    ANS85 integer-2 or

    integer-3 is specified, the value of the subscript is determined by incrementing by the value of

    ANS85 integer-2 or

    integer-3 (when the operator "+" is used) or by decrementing by the value of

    ANS85 integer-2 or

    integer-3 (when the operator "-" is used),

    ANS85 either

    the occurrence number represented by the value of the index referenced by index-name-1

    ANS85 or the value of the data item referenced by data-name-2

    .

Comments:

MF If the NOBOUND Compiler directive is specified, the General Rules are not applicable at run time.

Parent topic: Uniqueness of Reference


Indexing

References can be made to individual elements within a table of like elements by specifying indexing for that reference. An index is assigned to that level of the table by using the INDEXED BY phrase in the definition of a table. A name given in the INDEXED BY phrase is known as an index-name and is used to refer to the assigned index. The value of an index corresponds to the occurrence number of an element in the associated table or any other table. An index-name must be initialized before it is used as a table reference. An index-name can be given an initial value by a SET statement.

Unlike a subscript, which is simply a numeric data item or literal, an index is a special type of item and holds a representation of an occurrence number. The form of this representation can vary; the contents of an index cannot be regarded as a numeric value.

Direct indexing is specified by using an index-name in the form of a subscript. Relative indexing is specified when the index-name is followed by the operator "+" or "-", followed by an unsigned integer numeric literal, all delimited by the balanced pair of separators left parenthesis and right parenthesis following the table element data-name. The occurrence number resulting from relative indexing is determined by incrementing (where the operator "+" is used) or decrementing (where the operator "-" is used), by the value of the literal, the occurrence number represented by the value of the index. When more than one index-name is required, they are written in the order of successively less inclusive dimensions of the data organization.

A table can be indexed only by the index described in its INDEXED BY phrase.

OSVS VSC2 MF An index described for some other table can be used instead provided the two tables have elements of the same size.

At the time of execution of a statement which refers to an indexed table element, the value contained in the index used to index it must neither correspond to a value less than one nor to a value greater than the highest permissible occurrence number of an element of the associated table. This restriction also applies to the value resulting from relative indexing.

MF If the NOBOUND Compiler directive is specified, this rule is not applicable at run time.

Up to 3 index-names can be used with a data-name.

ANS85 Up to 7 index-names can be used with a data-name.

MF Up to 16 index-names can be used with a data-name.

The general format for indexing is included in the general format for subscripting; see the section Subscripting.

Parent topic: Uniqueness of Reference
Related information
Subscripting


Function-identifier

A function-identifier references the unique data item that results from the evaluation of a function.

General Format

Syntax Rules

  1. A function-identifier must not be specified as a receiving operand.
  2. The word FUNCTION is required

    ISO2002 unless either of the following apply:

    ISO2002
    1. ISO2002 intrinsic-function-name-1 is specified in the Repository paragraph
    2. ISO2002 function-prototype-name-1 is specified.
  3. ISO2002 Function-prototype-name-1 must be a function prototype specified in the Repository paragraph.
  4. ISO2002 The word OMITTED must not be specified if intrinsic-function-name-1 is specified.
  5. Argument-1 must be an identifier, a literal, or an arithmetic expression. Specific rules governing the number, class, and category of argument-1 are given for intrinsic functions in the definition of that intrinsic function in the section Definitions of Functions in the chapter Procedure Division - Intrinsic Functions

    ISO2002 and for user-defined functions in the section Conformance for Parameters and Returning Items in the chapter Procedure Division

    .

  6. ISO2002 If the word OMITTED is specified, the OPTIONAL phrase must be specified for the corresponding formal parameter.
  7. ISO2002 If function-prototype-name-1 is specified and the formal parameter corresponding to argument-1 is specified with a BY VALUE phrase, argument-1 must be of class numeric, object or pointer.
  8. A numeric function must not be specified where an integer operand is required, even though a particular reference of the numeric function might yield an integer value.
  9. An integer function other than the integer form of the ABS function must not be specified where an unsigned integer is required.
  10. A function-identifier which references an integer or numeric function can only be used in an arithmetic expression.
  11. ISO2002 If function-prototype-name-1 is specified, the rules for conformance specified in the section Conformance for Parameters and Returning Items in the chapter Procedure Division apply.
  12. A reference modifier can be specified only for functions of the category alphanumeric

    ISO2002 MF or national

    .

  13. If a function's definition permits arguments and a left parenthesis immediately follows function-prototype-name-1 or intrinsic-function-name-1, the left parenthesis is always treated as the left parenthesis of that function's arguments.
    Note: For a function that may be referenced either with or without arguments, such as the RANDOM function, careful coding is necessary to ensure correct interpretation. For example, in the following:
     FUNCTION MAX (FUNCTION RANDOM (A) B)

    'A' is treated as an argument to the RANDOM function. If 'A' is instead meant to be a second argument to the MAX function, different coding is necessary - either:

     FUNCTION MAX (FUNCTION RANDOM () A B)

   or
     FUNCTION MAX ( (FUNCTION RANDOM) (A) B)

   or
     FUNCTION MAX (FUNCTION RANDOM A B)

General Rules

  1. A function-identifier references a temporary data item whose value is determined when the function is referenced at run time.

    If intrinsic-function-name-1 is specified, the temporary data item is an elementary data item whose description and category are specified by the definition of that intrinsic function in the section Definitions of Functions in the chapter Procedure Division - Intrinsic Functions.

    ISO2002 If function-prototype-name-1 is specified, the description, class, and category of the temporary data item is that specified by the description in the Linkage Section of the item specified in the RETURNING phrase of the PROCEDURE DIVISION header of the function prototype identified by function-prototype-name-1.

  2. At the time reference is made to a function, its arguments are evaluated individually in the order specified in the list of arguments, from left to right. An argument being evaluated may itself be a function-identifier or may be an expression containing function-identifiers. There is no restriction preventing the function referenced in evaluating an argument from being the same function as that for which the argument is specified. In other words, recursion is permitted. Additional rules for intrinsic functions are given in the section Intrinsic Functions.

    ISO2002 for user-defined functions in the sections The PROCEDURE DIVISION Header and Conformance for Parameters and Returning Items in the chapter Procedure Division

    MF If a function is expecting an integer argument, then if a floating-point argument is provided, the value is rounded to the nearest integer, otherwise any fractional part is truncated.

  3. ISO2002 If function-prototype-name-1 is specified, the function to be activated is identified by function-prototype-name-1 in accordance with the rules specified in the section The Repository Paragraph in the chapter Environment Division, and function-prototype-name-1 is used to determine the characteristics of the activated function.
  4. ISO2002 If function-prototype-name-1 is specified, the manner used for passing each argument is determined as follows:
    1. BY REFERENCE is assumed when the BY REFERENCE phrase is specified or implied for the corresponding formal parameter and argument-1 is an identifier that is permitted as a receiving operand, other than an object property, object data item or factory object data item.
    2. BY CONTENT is assumed when the BY REFERENCE phrase is specified or implied for the corresponding formal parameter and argument-1 is a literal, an arithmetic expression, an object property, object data item, factory object data item or any identifier that is not permitted as a receiving operand.
    3. BY VALUE is assumed when the BY VALUE phrase is specified for the corresponding formal parameter.
  5. Evaluation of the function-identifier proceeds as follows:
    1. Each argument-1 is evaluated at the beginning of the evaluation of the function-identifier. The values of argument-1 are made available to the activated function at the time control is transferred to that function.
    2. The run-time system attempts to locate the function being activated.

      ISO2002 If function-prototype-name-1 is specified, the rules are specified in the section Conventions for Function-prototype-names. Additional rules are given in the section The Repository Paragraph in the chapter Environment Division.

    3. If the function is located but the resources necessary to execute the function are not available, the function is not activated. The run-time resources that are checked in order to determine the availability of the function for execution are defined by the implementor.
    4. The function specified by the function-identifier is made available for execution and control is transferred to the activated function in a manner consistent with the call convention specified for the function.

      ISO2002 If function-prototype- name-1 is specified and the function to be activated is a COBOL function, its execution is as described in the section The PROCEDURE DIVISION Header in the chapter Procedure Division.

      If intrinsic-function-name-1 is specified, its execution is as described in the chapter Procedure Division - Intrinsic Functions.

      ISO2002 If function-prototype-name-1 is specified and the function to be activated is not a COBOL function, the execution is as defined in your COBOL system documentation on interfacing.

  6. If the word OMITTED is specified or a trailing argument is omitted, the omitted-argument condition for that parameter evaluates to TRUE in the activated function. (See the topic The Omitted-Argument Condition.)
  7. If a parameter for which the omitted-argument condition is true is referenced in an activated function, except as an argument or in the omitted-argument condition, you will get runtime error 203.
Parent topic: Uniqueness of Reference
Related information
Definitions of Functions
Conformance for Parameters and Returning Items
Intrinsic Functions
The PROCEDURE DIVISION Header
The Repository Paragraph
Conventions for Function-prototype-names
Procedure Division - Intrinsic Functions
The Omitted-Argument Condition


Reference Modification

Reference modification defines a unique data item by specifying an identifier, a leftmost position and a length.

General Format

identifier-1 ( leftmost-position : [length] )

Syntax Rules

  1. Identifier-1 must reference a data item that is one of the following:
    • An elementary item of class alphanumeric or national
    • A numeric item of usage display
    • A group item
    Note: Identifier-1 must not be an individual boolean data item or a group item defined by the GROUP-USAGE BIT clause.
  2. Leftmost-position and length must be arithmetic expressions.
  3. Unless otherwise specified, reference modification is allowed anywhere an identifier referencing a data item of the class alphanumeric or national is permitted.
  4. Identifier-1 must not include reference-modification.
  5. If identifier-1 is a function-identifier, it must reference an alphanumeric or national function.

General Rules

  1. Leftmost-position represents an alphanumeric position or national position when identifier-1 references an alphanumeric or national data item, respectively.
  2. Each position of the data item referenced identifier-1 is assigned an ordinal number incrementing by one from the leftmost position to the rightmost position. The leftmost position is assigned the ordinal number one. If the data description entry for identifier-1 contains a SIGN IS SEPARATE clause, the sign position is assigned an ordinal number within that data item.
  3. If the data item referenced by identifier-1 is explicitly or implicitly described as usage DISPLAY and the category is numeric,

    OSVS VSC2 MF external floating-point,

    numeric edited, alphabetic, or alphanumeric edited, it is operated upon for purposes of reference modification as if it were redefined as an alphanumeric data item of the same size as the data item referenced by identiifer-1.

  4. Reference modification for an operand is evaluated as follows:
    1. If subscripting is specified for the operand, the reference modification is evaluated immediately after evaluation of the subscripts. If an ALL subscript is specified for an operand, the reference-modifier is applied to each of the implicitly specified elements of the table.
    2. If subscripting is not specified for the operand, the reference modification is evaluated at the time subscripting would have been evaluated if subscripts had been specified.
    3. If reference modification is specified in a function reference, the reference modification is evaluated immediately after evaluation of the function.
    4. If reference modification is specified in an object property reference, the reference modification is evaluated immediately after evaluation of the object property.
  5. Reference modification creates a unique data item that is a subset of the data item referenced by identifier-1. This unique data item is defined as follows:
    1. The evaluation of leftmost-position specifies the ordinal position of the leftmost character of the unique data item in relation to the leftmost character of the data item referenced by identifier-1. Evaluation of leftmost-position must result in a positive nonzero integer less than or equal to the number of positions in the data item referenced by identifier-1.

      VSC2 MF The results are rounded if the expression is in floating-point, and truncated if the expression is in fixed-point.

    2. The evaluation of length specifies the size in characters of the data item to be used in the operation. The evaluation of length must result in a positive nonzero integer. The sum of leftmost-position and length minus the value one, must be less than, or equal to, the number of characters in the data item referenced by identifier-1. If length is not specified, the unique data item extends from and includes the character identified by leftmost-position, up to and including the rightmost character of the data item referenced by identifier-1.

      VSC2 MF The results are rounded if the expression is in floating-point, and truncated if the expression is in fixed-point.

      Note: There is no check that the evaluation of leftmost-position and length produce valid values. If these evaluations do not conform to the restrictions stated in this rule, the result is undefined and other data items may be corrupted.
  6. The unique data item is considered an elementary data item without the JUSTIFIED clause. The unique data item has the same class, category and usage as that defined for the data item referenced by identifier-1, except that:
    • The categories numeric, numeric edited, alphanumeric edited

      OSVS VSC2 MF and external floating-point

      are considered class and category alphanumeric

    • ISO2002 MF The category national-edited is considered class and category national.
  7. OSVS If the OSVS Compiler directive is set, reference modification cannot be used in conditional expressions (see the topic Conditional Expressions).
Parent topic: Uniqueness of Reference
Related information
Conditional Expressions


Identifier

An identifier is a sequence of character-strings and separators used to reference data uniquely.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

   object-property-1

General Formats for Format 4

   inline-invocation-1

General Formats for Format 5

   identifier-2 object-view-1

General Formats for Format 6

General Formats for Format 7

   type-of-identifier-1

Syntax Rules:

  1. Subscript-1 represents either subscripting (see the section Subscripting) or indexing (see the section Indexing).

General Rules: for Format 2

  1. The words IN and OF are equivalent.
  2. A data-name must neither be subscripted nor indexed when it is being used as an index, or subscript.
  3. Indexing is not permitted where subscripting is not permitted.
  4. An index can be modified only by the SET, SEARCH, and PERFORM statements. Data items described by the USAGE IS INDEX clause permit storage of the values associated with index-names as data. Such data items are called index data items.
  5. Literals used as subscripts must be positive numeric integers. Literals used for relative subscripting and indexing must be unsigned numeric integers.

General Rules: for Format 3

  6. ISO2002 MF NET JVM Object-property-1 is defined by the section Object property

General Rules: for Format 4

  7. ISO2002 MF Inline-invocation-1 is defined by the section Inline Method Invocation

General Rules: for Format 5

  8. ISO2002 MF Object-view-1 is defined by the section Object-view

General Rules: for Format 6

  9. ISO2002 MF Address-identifiers are defined by the section Data-address-identifier and the section Program-address-identifier.

General Rules: for Format 7

  10. NET JVM Type-of-1 is defined by the section Type of identifier.
Parent topic: Uniqueness of Reference
Related information
Subscripting
Indexing
Object property
Inline Method Invocation
Object-view
Data-address-identifier
Program-address-identifier
Type of identifier


Condition-name

Each condition-name must be unique, or be made unique through qualification and/or indexing, or subscripting. If qualification is used to make a condition-name unique, the associated conditional variable can be used as the first qualifier. The hierarchy of names associated with the conditional variable or the conditional variable itself must be used to make the condition-name unique.

If references to a conditional variable require indexing or subscripting, references to any of its condition-names require the same combination of indexing or subscripting.

The format and restrictions on the combined use of qualification, subscripting, and indexing of condition-names are exactly those of "identifier" except that data-name-1 is replaced by condition-name-1.

In the general formats, "condition-name" refers to a condition-name qualified, indexed or subscripted, as necessary.

Parent topic: Uniqueness of Reference


Object property

Object properties provide a special syntax to get information out of and pass information back into an object. The mechanisms for accessing object properties are get property methods and set property methods. A get property method is a method explicitly defined with the GET PROPERTY phrase or a method implicitly generated for a data item described with the PROPERTY clause; a set property method is a method explicitly defined with the SET PROPERTY phrase or a method implicitly generated for a data item described with the PROPERTY clause.

General Format for Format 1

   property-name-1 OF identifier-1

General Format for Format 2

  identifier-1::literal-1

Syntax Rules

  1. ISO2002 Property-name-1 must be an object property specified in the Repository paragraph.
  2. ISO2002 Identifier-1 must be an object reference; neither a universal object reference, nor the predefined object reference NULL can be specified.
  3. ISO2002 If the object property is used as a sending item, a get property method must exist for property-name-1 in the object referenced by identifier-1.
  4. ISO2002 If the object property is used as a receiving item, a set property method must exist for property-name-1 in the object referenced by identifier-1.
  5. ISO2002 The description of an object property used as a sending item is the same as the description of the returning item of the get property method. This object property can be specified wherever a data item with that description would be valid as a sending item.
  6. ISO2002 The description of an object property used as a receiving item is the same as the description of the using parameter of the set property method. This object property may be specified wherever a data item with that description would be valid as a receiving item.
  7. ISO2002 The data description of the item specified in the RETURNING phrase of the get property method must be the same as the data description of the item specified as the USING parameter of the set property method.
  8. NET JVM Literal-1 must specify the name of a property of the object referenced by identifier-1.

General Rules

  1. ISO2002 When an object property is used only as a sending item, a conceptual temporary data item, temp-1 is used in its place. The value of the property is determined as though the associated get property method were invoked, in accordance with the rules of the INVOKE statement, and the returned value placed in temp-1. The data description of temp-1 is the same as the data description of the item specified in the RETURNING phrase of the get property method.
  2. ISO2002 When an object property is used only as a receiving item, a conceptual temporary data item, temp-2, is used in its place. The value of the property is assigned as though the associated set property method were invoked, in accordance with the rules of the INVOKE statement, passing the content of temp-2 as the parameter. The data description of temp-2 is the same as the data description of the item specified as the USING parameter of the set property method.
  3. ISO2002 When an object property is used as both a sending item and a receiving item, conceptual temporary data items temp-1 and temp-2 are used in its place; temp-1 and temp-2 are the same temporary data item, where temp-2 redefines temp-1. For sending operations, the value of the property is determined in the same manner as for sending items in general rule 1; for receiving operations, the value of the property is assigned in the same manner as for receiving items in general rule 2. The data descriptions of temp-1 and temp-2 are the same as the data description of the item specified in the RETURNING phrase of the get property method.
Parent topic: Uniqueness of Reference


Inline method invocation

Inline method invocation references a temporary data item returned from invocation of a method.

General Format

Syntax Rules

  1. Inline method invocation must not be specified as a receiving operand.
  2. Identifier-1 must be of class object; neither the predefined object reference NULL nor a universal object reference may be specified.
  3. One of the INVOKE statements specified in general rule 1 must be valid according to syntax rules for the INVOKE statement.
  4. The data item referenced in the RETURNING phrase of the invoked method's PROCEDURE DIVISION header must not be described with the ANY LENGTH clause.

General Rules

  1. An inline method invocation references a temporary data item with the same class, category, and content as the temp-identifier that would be returned from the execution of the applicable form of INVOKE statement, as follows:
    INVOKE identifier-1 literal-1 USING arguments RETURNING temp-identifier INVOKE identifier-1 literal-1 RETURNING temp-identifier INVOKE class-name-1 literal-1 USING arguments RETURNING temp-identifier INVOKE class-name-1 literal-1 RETURNING temp-identifier
    where:
    1. arguments are the operands specified within parentheses in the inline method invocation, if any
    2. temp-identifier has the same description, class, and category as the RETURNING parameter in the specification of the method identified by literal-1 and either identifier-1 or class-name-1
    3. temp-identifier is a temporary item that exists for the purpose of effecting the inline invocation in this way and for no other purpose
Parent topic: Uniqueness of Reference


Object-view

An object-view causes an object reference to be treated as though it had the specified description. A runtime conformance check for this description will be done on the object.

General Format

Syntax Rules

  1. Identifier-1 must be of class object; the predefined object references SUPER and NULL must not be specified.
  2. An object-view must not be specified as a receiving operand.

General Rules

  1. This reference of identifier-1 is treated at compile-time as though it had the description specified by the AS phrase.
  2. If class-name-1 is specified without either of the optional phrases, identifier-1 is treated as though it were described as USAGE IS OBJECT REFERENCE class-name-1. If the object referenced by identifier-1 is not an object of class-name-1 or an object of a subclass of class-name-1, the EC-OO-CONFORMANCE exception condition is set to exist.
  3. If the FACTORY phrase is specified and the ONLY phrase is not specified, identifier-1 is treated as though it were described as USAGE OBJECT REFERENCE FACTORY OF class-name-1. If the object referenced by identifier-1 is not the factory object of class-name-1 or the factory object of a subclass of class-name-1, the EC-OO-CONFORMANCE exception condition is set to exist.
  4. If the ONLY phrase is specified and the FACTORY phrase is not specified, identifier-1 is treated as though it were described as USAGE OBJECT REFERENCE class-name-1 ONLY. If the object referenced by identifier-1 is not an object of class-name-1, the EC-OO-CONFORMANCE exception condition is set to exist.
  5. If both the FACTORY phrase and the ONLY phrase are specified, identifier-1 is treated as though it were described as USAGE OBJECT REFERENCE FACTORY OF class-name-1 ONLY. If the object referenced by identifier-1 is not the factory object of class-name-1, the EC-OO-CONFORMANCE exception condition is set to exist.
  6. If interface-name-1 is specified, identifier-1 is treated as though it were described as USAGE OBJECT REFERENCE interface-name-1. If the object referenced by identifier-1 does not implement interface-name-1, the EC-OO-CONFORMANCE exception condition is set to exist.
  7. If UNIVERSAL is specified, identifier-1 is treated as though it were described as USAGE OBJECT REFERENCE without any of the optional phrases to indicate the class or interface for objects referenced by identifier-1. The EC-OO-CONFORMANCE exception condition is not set to exist.
Parent topic: Uniqueness of Reference


Data-address-identifier

A data-address-identifer references the unique data item that contains the address of a data item.

General Format

ADDRESS of identifier-1

Syntax Rules

  1. Identifier-1 must reference a data item defined in the File Section, Working-Storage Section, Local-Storage Section or Linkage Section. Identifier-1 must not be defined in the Working-Storage or the File Section of an instance object or a factory object.
  2. Identifier-1 must not reference an object reference.
  3. This identifier format must not be specified as a receiving opernad.

General Rules

  1. Data-address-identifier creates a unique data item of class pointer and category data-pointer that contains the address of identifier-1.
Parent topic: Uniqueness of Reference


Type of identifier

The TYPE OF identifier obtains the System.Type object for a class, interface, delegate or enumeration.

General Format

TYPE OF identifier-1

Syntax Rules

  1. NET JVM Identifier-1 must reference a class, an interface, a delegate or an enumeration.

General Rules

  1. NET JVM Type-of-identifier creates a unique data item that contains the System.Type object for identifier-1.
Parent topic: Uniqueness of Reference


Program-address-identifier

General Format

Syntax Rules

  1. Identifier-1 must of of category alphanumeric or national.
  2. Literal-1 must be an alphanumeric or national literal.
  3. Program-prototype-name-1 must be a program prototype specified in the Repository paragraph.
  4. This identifier format must not be specified as a receiving operand.

General Rules

  1. Program-address-identifier creates a unique data item of class pointer and category program-pointer that contains the address of a program identified by one of the following:
    1. the content of the data item referenced by identifier-1
    2. the value of literal-1
    3. program-prototype-name-1.

    If identifier-1 or literal-1 is specified, COBOL Words in the chapter Concepts of the COBOL Language describes how this value is used to identify the referenced program.

  2. The program may be written in COBOL or in another language. For a COBOL program, the address is that of the outermost program identified by the externalized program-name in its Program-ID paragraph.
  3. When program-prototype-name-1 is specified, the program-address-identifier has the characteristics of a program-pointer restricted to program-prototype-name-1.
  4. If the runtime system cannot locate the program, the value of the address-identifier is the predefined address NULL.
Parent topic: Uniqueness of Reference
Related information
COBOL Words


Explicit and Implicit Specifications

There are four types of explicit and implicit specifications that occur in COBOL source elements:

  1. Explicit and implicit Procedure Division references.
  2. Explicit and implicit transfers of control.
  3. Explicit and implicit attributes.
  4. ANS85 Explicit and implicit scope terminators.
  • Explicit and Implicit Procedure Division References
  • Explicit and Implicit Transfers of Control
  • Explicit and Implicit Attributes
  • Explicit and Implicit Scope Terminators
Parent topic: Class and Category of Data


Explicit and Implicit Procedure Division References

A COBOL source element can reference data items either explicitly or implicitly in Procedure Division statements. An explicit reference occurs when the name of the referenced item is written in a Procedure Division statement or when the name of the referenced item is copied into the Procedure Division by the processing of a COPY statement

ANS85 , a REPLACE statement

OSVS VSC2 , an -INC statement, or ++INCLUDE statement

. An implicit reference occurs when the item is referenced by a Procedure Division statement without the name of the referenced item being written in the source statement.

An implicit reference also occurs during the execution of a PERFORM statement, when the index or data item referenced by the index-name or identifier specified in the VARYING, AFTER or UNTIL phrase is initialized, modified, or evaluated by the control mechanism associated with that PERFORM statement. Such an implicit reference occurs if and only if the data item contributes to the execution of the statement.

Parent topic: Explicit and Implicit Specifications


Explicit and Implicit Transfers of Control

The flow of control mechanism transfers control from statement to statement in the sequence in which they were written unless an explicit transfer of control overrides this sequence or there is no next executable statement to which control may be passed. The transfer of control from statement to statement occurs without the writing of an explicit Procedure Division statement, and, therefore, is an implicit transfer of control.

COBOL provides both an explicit and an implicit means of altering the implicit control transfer mechanism.

In addition to the implicit transfer of control between consecutive statements, implicit transfer of control occurs when the normal flow is altered without the execution of a procedure branching statement. COBOL provides the following types of implicit control flow alterations which override the statement-to-statement transfers of control:

  1. If a paragraph is being executed under control of another COBOL statement (for example, PERFORM, USE, SORT and MERGE) and the paragraph is the last paragraph in the range of the controling statement, then an implied transfer of control occurs from the last statement in the paragraph to the control mechanism of the last executed controling statement. Further, if a paragraph is being executed under the control of a PERFORM statement which causes iterative execution and that paragraph is the first paragraph in the range of that PERFORM statement, an implicit transfer of control occurs between the control mechanism associated with that PERFORM statement and the first statement in that paragraph for each iterative execution of the paragraph.
  2. When a SORT or MERGE statement is executed, an implicit transfer of control occurs to any associated input or output procedures.
  3. When any COBOL statement is executed that results in the execution of a declarative section, an implicit transfer of control to the declarative section occurs.
    Note: Another implicit transfer of control occurs after execution of the declarative section, as described in item 1. above.
  4. MF In any file operation (including OPEN and CLOSE), if a file does not have a FILE STATUS data item declared for it and the file is not explicitly covered by a USE statement, then it is covered by an implicit USE statement. The implied USE procedure is equivalent to:
    USE AFTER ERROR PROCEDURE ON file-name.
IF status-key-1 >= 3
  DISPLAY error-message UPON CONSOLE
  STOP RUN.

    See your COBOL system documentation for descriptions of error messages.

An explicit transfer of control consists of an alteration of the implicit control transfer mechanism by the execution of a procedure branching, ending or conditional statement. An explicit transfer of control between statements can be caused only by the execution of a procedure branching or conditional statement. An explicit transfer of control between sentences can be caused only by the execution of the NEXT SENTENCE phrase of an IF or SEARCH statement.

The execution of the procedure branching statement ALTER does not in itself constitute an explicit transfer of control, but affects the explicit transfer of control that occurs when the associated GO TO statement is executed. The procedure branching statement EXIT PROGRAM causes an explicit transfer of control only when the statement is executed in a called program.

The term "next executable sentence" is used to refer to the next COBOL sentence to which control is either implicitly transferred according to the rules above, or explicitly transferred as a result of execution of the NEXT SENTENCE phrase. The next executable sentence is the first sentence following the separator period that terminates the current sentence. There is no next executable sentence when there is no next executable statement as described below.

The term "next executable statement" is used to refer to the next COBOL statement to which control is transferred according to the rules above and the rules associated with each language element in the Procedure Division.

There is no next executable statement following:

  • The last statement in a declarative section when the paragraph in which it appears is not being executed under the control of some other COBOL statement
  • The last statement in a source element when the paragraph in which it appears is not being executed under the control of some other COBOL statement in that source element
  • The last statement in a declarative section, when the statement is in the range of an active PERFORM statement executed in a different section, and this last statement of the declarative section is not also the last statement of the procedure that is the exit of the active PERFORM statement
  • A STOP RUN statement

    ISO2002 OSVS VSC2 MF , GOBACK statement

    ISO2002 MF , EXIT METHOD

    ISO2002 , EXIT FUNCTION

    or EXIT PROGRAM statement that transfers control outside the COBOL source element

  • The end marker.
Parent topic: Explicit and Implicit Specifications


Explicit and Implicit Attributes

Attributes can be implicitly or explicitly specified. Any attribute which has been explicitly specified is called an explicit attribute. If an attribute has not been specified explicitly, then the attribute takes on the default specification. Such an attribute is known as an implicit attribute.

For example, the usage of a data item need not be specified, in which case a data item's usage is DISPLAY

OSVS VSC2 MF , unless the PICTURE character-string contains a "G" or an "N", in which case a data item's usage is DISPLAY-1

.

Parent topic: Explicit and Implicit Specifications


Explicit and Implicit Scope Terminators

Scope terminators delimit the scope of certain Procedure Division statements (delimited scope statements), and are of two types: explicit and implicit.

The explicit scope terminators are listed below:

  • END-ADD
  • END-PERFORM
  • MF XOPEN END-ACCEPT
  • END-CALL
  • MF END-CHAIN
  • END-COMPUTE
  • END-DELETE
  • MF XOPEN END-DISPLAY
  • END-DIVIDE
  • END-EVALUATE
  • END-IF
  • END-MULTIPLY
  • END-READ
  • END-RETURN
  • END-REWRITE
  • END-SEARCH
  • END-START
  • END-STRING
  • END-SUBTRACT
  • END-UNSTRING
  • END-WRITE
Note: In some cases the delimited scope statement with which an explicit scope delimiter is paired is determined differently for different COBOL language specifications.

Implicit scope termination occurs:

  • At the end of any sentence, where the separator period terminates the scope of all previous statements not yet terminated
  • Within any statement containing another statement. The next phrase of the containing statement (for example, ELSE, WHEN, AT END, and so on) following the contained statement terminates the scope of any unterminated contained statement.
Parent topic: Explicit and Implicit Specifications
Related information
The EVALUATE Statement
The STRING Statement


Language Fundamentals

  • Optional Division, Section and Paragraph Headings
  • Reserved Words
  • External Repository
  • Call Prototypes
  • Files
  • Object-oriented COBOL Concepts
  • Managed Code Concepts
  • Run Unit Communication
  • Data Division
  • Procedure Division
  • Reference Format
Parent topic: Part 1. Concepts


Optional Division, Section and Paragraph Headings

Some of the "red-tape" statements required by the ANSI Standard COBOL specifications are optional when using this COBOL system. It is, however, possible to have your COBOL system output warning messages when such statements are found to be missing by use of the FLAG directive. Such statements are identified as optional in this manual by enclosing them between brackets which have boxes around them. The symbols next to these boxes indicate the dialect in which these features are optional.

Parent topic: Language Fundamentals


Reserved Words

A full list of reserved words is given in the appendix Reserved Words.

Parent topic: Language Fundamentals
Related information
Reserved Words


External Repository

The external repository stores information specified in function prototypes, program definitions, class definitions and interface definitions.

The information stored about these source units must consist of all information required for activation and checking conformance. This information includes

  • The externalized name of the source unit
  • The type of the source unit - program, function, class or interface
  • The parameters of the source unit, if any
  • The returning item of the source unit, if any
  • The object properties of the source unit, if any
  • The methods contained in the source unit, if any, and details about the method's externalized name, parameters and returning item
  • Whether the DECIMAL-POINT IS COMMA clause is specified in the source unit; for a class, this detail must be stored for both its factory and object
  • Whether the CURRENCY clause is specified in the source unit; for a class, this detail must be stored for both its factory and object

This information about a source unit, excluding the externalized name of the source unit, is called its signature.

If a REPOSITORY directive is specified with the ON phrase, the compiler puts this information into the external repository as it compiles each compilation unit.

If a REPOSITORY directive is specified with the CHECKING phrase, either explicitly or by default, the compiler issues a warning when these characteristics of definitions and prototypes do not exactly match the information, if any, in the external repository for the associated definition.

The details on the association of the name of a source unit with information in the external repository are specified in the section The Repository Paragraph in the chapter Environment Division.

Parent topic: Language Fundamentals
Related information
The Repository Paragraph


Call Prototypes

A call prototype is a program declaration or skeleton program which serves to define the characteristics of a called subprogram. These characteristics include the number of parameters required, the type of these parameters and the calling convention. If a source element contains a CALL statement referring to a subprogram for which a prototype exists, the CALL statement is checked against the prototype. If there is an explicit mismatch, an error is given. If the CALL statement leaves some characteristics (such as the call convention) undefined, this is derived from the prototype.

The call prototype is defined as a complete program in which the EXTERNAL clause is specified in the Program-ID paragraph. The program structure should consist only of an Identification Division with a Program-ID paragraph, a Data Division with a Linkage Section, a PROCEDURE DIVISION header, and optional ENTRY statements. These call prototypes are placed before the other types of compilation units in a similar way to multi-program source files.

Note that you must include a copy of the call prototype for every subprogram to which you want your CALL statements checked before the IDENTIFICATION DIVISION header of your compilation unit containing the CALL statements.

Parent topic: Language Fundamentals


Files

  • File Connector
  • Sequential Input/Output
  • Relative Input/Output
  • Indexed Input/Output
  • Sharing Mode
Parent topic: Language Fundamentals


File Connector

A file connector is a storage area which contains information about a file and is used as the linkage between a file-name and a physical file and between a file-name and its associated record area.

Parent topic: Files


Sequential Input/Output

If the words sequential file or sequential organization are used in this chapter without specifying LINE or RECORD, then the sentence applies to both forms. The default behavior for sequential files is sensitive to the SEQUENTIAL Compiler directive.

  • Record Sequential Input/Output
  • Line Sequential Input/Output
  • Organization of Line and Record Sequential Files
  • Access Mode
Parent topic: Files


Record Sequential Input/Output

Record sequential I/O allows you to access records of a file in an established sequence. The sequence is established as a result of writing the records to the file.

Parent topic: Sequential Input/Output


Line Sequential Input/Output

Line sequential I/O allows you to access records of a text file in an established sequence. The records are stored with trailing spaces removed.

If the records are written to a line sequential file using unqualified WRITE commands, the file will be identical in format to those files produced by your operating system editor.

If the records are written to a line sequential file using qualified WRITE commands (for example using WRITE AFTER or WRITE BEFORE commands), the file will not be identical in format to those files produced by your operating system editor.

Parent topic: Sequential Input/Output
Related information
WRITE


Organization of Line and Record Sequential Files

Organization of MF Line and Record Sequential Files

Sequential files are organized such that each record in the file except the first has a unique predecessor record, and each record except the last has a unique successor record. These predecessor-successor relationships are established by the order of WRITE statements when the file is created. Once established, the predecessor-successor relationships do not change except in the case where records are added to the end of the file.

Parent topic: Sequential Input/Output


Access Mode

The only access available for sequential files is sequential access mode; the sequence in which records are accessed is the order in which the records were originally written.

If the record size in a line sequential file is greater than the record length, the data fills the record length and on the next READ it returns more data from that record. i.e. it uses the record length and the record delimiter.

Parent topic: Sequential Input/Output


Relative Input/Output

Relative I/O allows you to access records within a mass storage file in either a random or sequential manner. Each record in a relative file is identified by an integer value greater than zero which specifies the record's ordinal position in the file.

  • Organization of Relative Files
  • Access Mode
Parent topic: Files


Organization of Relative Files

Relative file organization is permitted only on disk devices. A relative file consists of records which are identified by relative record numbers. The file can be thought of as being composed of a serial string of areas, each capable of holding a logical record. Each of these areas has a relative record number. Records are stored and retrieved via this number. For example, ten denotes the tenth record area.

Parent topic: Relative Input/Output


Access Mode

In sequential access mode, records are accessed in the ascending order of the relative record numbers of those records which currently exist within the file, except that, if the program specifies the PREVIOUS phrase, records are accessed in the descending order of the relative record numbers of those records which currently exist within the file.

In random access mode, you control the sequence in which records are accessed. The desired record is accessed by placing its relative record number in a relative key data item.

In dynamic access mode, you can change at will between sequential access and random access, using the appropriate forms of input/output statements.

Parent topic: Relative Input/Output


Indexed Input/Output

Indexed I/O allows you to access records within a mass storage file in either a random or sequential manner. Each record in an indexed file is identified by the value of one or more keys within that record.

  • Organization of Indexed Files
  • Access Mode
Parent topic: Files


Organization of Indexed Files

An indexed file is a mass storage file in which data records can be accessed by the value of a key. A record description can include one or more key data items, each of which is associated with an index. Each index provides a logical path to the data records, according to the contents of a data item within each record which is the record key for that index.

The data item named in the RECORD KEY clause of the file control entry for a file is the prime record key for that file. For purposes of inserting, updating and deleting records in a file, each record is identified solely by the value of its prime record key. This value should, therefore, be unique and must not be changed when updating the record.

The data item named in the ALTERNATE RECORD KEY clause of the file control entry for a file is an alternative record key for that file. The value of an alternative record key can be non-unique if the DUPLICATES phrase is specified. These keys provide alternative access paths for retrieval of records from the file.

MF Your COBOL system provides an extension which allows the key field to be a split key. A split key is a key comprising two or more data items, which may or may not be contiguous, in the record description.

Parent topic: Indexed Input/Output


Access Mode

In sequential access mode, records are accessed in the ascending order of the record key values, except that, if the program specifies the PREVIOUS phrase, records are accessed in the descending order of the record key values. Records within a set of records that have duplicate record key values are retrieved in the order in which the records were written into the set, except that, if the program specifies the PREVIOUS phrase, records are retrieved in the reverse order in which the records were written into the set.

In random access mode, you control the sequence in which records are accessed. The desired record is accessed by placing the value of its record key in the record key data item.

In dynamic access mode, you can change at will between sequential access and random access, using appropriate forms of input/output statements.

Parent topic: Indexed Input/Output


Sharing Mode

The sharing mode indicates whether a file is to participate in file sharing and record locking, and specifies the degree of file sharing (or non-sharing) to be permitted for the file. The sharing mode specifies the types of operations that may be performed on the shared file through other file connectors while this file connector is open.

The SHARING phrase on an OPEN statement overrides the SHARING clause in the file control entry for establishing the sharing mode. If there is no SHARING phrase on the OPEN statement, the sharing mode is completely determined by the SHARING clause in the file control entry. If no specification is made in either location, the sharing mode is determined by the first of the following conditions that is satisfied:

  • If you specify the WITH LOCK phrase on the OPEN statement, the sharing mode is SHARING WITH NO OTHER.
  • If you specify the LOCK MODE IS EXCLUSIVE phrase in the SELECT clause, the sharing mode is SHARING WITH NO OTHER.
  • If you specify either the LOCK MODE IS MANUAL phrase or the LOCK MODE IS AUTOMATIC phrase in the SELECT clause, the sharing mode is SHARING WITH ALL OTHER.
  • If the open mode is OUTPUT, I-O, or EXTEND, the sharing mode is SHARING WITH NO OTHER.
  • If the open mode is INPUT, the sharing mode depends on the setting of the configuration option OPENINPUTSHARED. If you set this option to ON, the sharing mode is SHARING WITH ALL OTHER. Otherwise the sharing mode is SHARING WITH READ ONLY.

The rules are the same for a given standard sharing mode whether the sharing mode is specified on the OPEN statement, specified in the file control entry, or determined from the list above.

COBOL file sharing does not interoperate with other file sharing facilities in the environment.

A shared file must reside on disk.

Before access to a shared file is allowed through an OPEN statement, the sharing mode and the open mode must be allowed by all other file connectors that are currently associated with the file. Additionally, the sharing mode for the current OPEN statement shall permit all of the sharing modes and open modes that exist for all other file connectors that are currently associated with the file. (See the topic The OPEN Statement, particularly the table Opening available shared files that are currently open by another file connector.)

The sharing mode controls access to a file as follows:

  1. The SHARING WITH NO OTHER mode specifies exclusive access to a file. Associating this file connector with the file will be unsuccessful if the file is currently open through other file connectors. If the OPEN statement is successful, subsequent requests to open the file through other file connectors before this file connector is closed will be unsuccessful. Record locks are ignored.
  2. The SHARING WITH READ ONLY mode restricts concurrent access to a file through file connectors other than this one, to input mode. Associating this file connector with the file will be unsuccessful if the file is currently open in a mode other than input. If the OPEN statement is successful, subsequent requests to open the file through other file connectors in a mode other than input before this file connector is closed will be unsuccessful. Record locks are in effect.
  3. The SHARING WITH ALL OTHER mode allows concurrent access to a file through other file connectors specifying input, I-O, or extend mode, subject to any further restrictions that apply. Record locks are in effect.

Multiple paths of access may exist in the same runtime element, contained elements, separate runtime modules within the same run unit, or different run units. The file sharing conflict condition can exist regardless of the location of the file connector that holds the file lock of the file to be opened.

The setting of a file lock is part of the atomic operation of an I/O statement.

The file lock and all record locks established for a file connector are removed by an explicit or implicit CLOSE statement executed for that file connector.

Parent topic: Files
Related information
The OPEN Statement


Object-oriented COBOL Concepts

  • Objects and Classes
  • Object References
  • Predefined Object References
  • Methods
  • Method Invocation
  • Conformance and Interfaces
  • Polymorphism
  • Class Inheritance
  • Interface Inheritance
  • Interface Implementation
  • Parameterized Classes
  • Parameterized Interfaces
Parent topic: Language Fundamentals


Objects and Classes

An object is a runtime element that consists of its own data and shares the methods defined in its class definition. An object is defined by a class. The class definition describes the characteristics of the data and the methods that may be invoked on each of the objects of the class.

Every class also has a single factory object with its own unique set of data and methods. The factory object is typically used to create object instances, and to maintain data common to all instances of the class.

Parent topic: Object-oriented COBOL Concepts


Object References

An object reference is an implicitly- or explicitly-defined data item containing a value - an object reference value - that uniquely references an object for the lifetime of the object. Implicitly-defined object references are the predefined object references and object references returned from an object property, an object-view, an inline method invocation or a function. Explicitly-defined object references are data items defined by a data description entry specifying a USAGE OBJECT REFERENCE clause.

No two distinct objects have the same object reference value and every object has at least one object reference.

Parent topic: Object-oriented COBOL Concepts


Predefined Object References

A predefined object reference is an implicitly-generated data item referenced by one of the identifiers NULL, SELF,

MF SELFCLASS,

and SUPER. Each predefined object reference has a specific meaning, as described in the section Predefined Object Identifiers in the chapter Concepts of the COBOL Language.

Parent topic: Object-oriented COBOL Concepts
Related information
Predefined Object Identifiers


Methods

The procedural code in an object is placed in methods. Each method has its own method-name and its own Data Division and Procedure Division. When a method is invoked, the procedural code it contains is executed. A method is invoked by specifying an identifier that references the object and the name of the method. A method may specify parameters and a returning item.

Parent topic: Object-oriented COBOL Concepts


Method Invocation

The procedural code in a method is executed by invoking the method with an INVOKE statement, an inline method invocation or

MF referencing a verb-signature, or

referencing an object property. The method implementation that is bound to the invocation depends on the class, at runtime, of the object on which the method is invoked. In particular, it is not necessarily the class specified statically in the definition of the object reference; it is the class of the actual object referenced at runtime that is used in resolving a method invocation to a particular method implementation.

If an invocation specifies the object using an object reference, then:

  1. If the identified object is a factory object, the method invocation will resolve to a factory method
  2. Otherwise, the resolution will be to an object method.

If an invocation specifies the object using a class name, the factory object of the specified class is used as the object on which the method is invoked, and the method invocation will resolve to a factory method.

Method resolution proceeds by applying the first one of the following rules that is applicable:

  1. If a method with the method-name specified in the invocation is defined in the class of the object, that method is bound.
  2. If a method with the method-name specified in the invocation is defined in the class that is inherited by the class of the object, that method is bound, including any classes inherited from higher levels of the class hierarchy.
  3. If the method is not found, a runtime error will result.
Parent topic: Object-oriented COBOL Concepts


Conformance and Interfaces

The term "conformance" is used in this document with several different meanings. In the context of object orientation, the term "conformance" is used to describe a relationship between object interfaces, and it is the basis of such fundamental features as inheritance, interface definitions, and conformance checking.

Note: Conformance checking is done at compile time only, except when using an object modifier and when invoking a method using a universal object reference.
  • Conformance for Object Orientation
Parent topic: Object-oriented COBOL Concepts


Conformance for Object Orientation

Conformance for objects allows an object to be used according to an interface other than the interface of its own class. Conformance is a unidirectional relation from one interface to another interface and from an object to an interface.

  • Interfaces
  • Conformance between Interfaces
  • Conformance for Parameterized Classes and Parameterized Interfaces
Parent topic: Conformance and Interfaces


Interfaces

Every object has an interface consisting of the names and parameter specifications for each method supported by the object, including inherited methods. Each class has two interfaces: an interface for the factory object and an interface for the objects.

Interfaces may also be defined independently from a specific class by specifying method prototypes in an interface definition.

Parent topic: Conformance for Object Orientation


Conformance between Interfaces

An interface interface-1 conforms to an interface interface-2 if and only if:

  1. For every method in interface-2 there is a method in interface-1 with the same name taking the same number of parameters, with consistent BY REFERENCE and BY VALUE specifications.
  2. If the formal parameter of a given method in interface-2 is an object reference, the corresponding parameter in interface-1 is an object reference following these rules:
    1. If the parameter in interface-2 is a universal object reference, the corresponding parameter in interface-1 is a universal object reference.
    2. If the parameter in interface-2 is described with an interface-name, the corresponding parameter in interface-1 is described with the same interface- name.
    3. If the parameter in interface-2 is described with a class-name, the corresponding parameter in interface-1 is described with the same class-name, and the presence or absence of the FACTORY and ONLY phrases is the same in both interfaces.
    4. If the parameter in interface-2 is described with the ACTIVE-CLASS phrase, the corresponding parameter in interface-1 is described with the ACTIVE-CLASS phrase, and the presence or absence of the FACTORY phrase is the same in both interfaces.
  3. If the formal parameter of a given method in interface-2 is not an object reference, the corresponding formal parameter in interface-1 has the same ANY LENGTH, PICTURE, USAGE, SIGN, SYNCHRONIZED, JUSTIFIED, and BLANK WHEN ZERO clauses, with the following exceptions:
    1. Currency symbols match if and only if the corresponding currency strings are the same.
    2. Period picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both or for neither of these interfaces. Comma picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both or for neither of these interfaces.
  4. The presence or absence of the Procedure Division RETURNING phrase is the same in the corresponding methods.
  5. If the returning item in a given method of interface-2 is an object reference, the corresponding returning item in interface-1 is an object reference following these rules:
    1. If the returning item in interface-2 is a universal object reference, the corresponding returning item in interface-1 is an object reference.
    2. If the returning item in interface-2 is described with an interface-name that identifies the interface int-r, the corresponding returning item in interface-1 is either of the following:
      1. an object reference described with an interface-name that identifies int-r or an interface described with an INHERITS clause that references int-r,
      2. an object reference described with a class-name, subject to the following rules:
        1. if described with the FACTORY phrase, the factory object of the specified class must be described with an IMPLEMENTS clause that references int-r
        2. if described without the FACTORY phrase, the instance objects of the specified class must be described with an IMPLEMENTS clause that references int-r.
    3. If the returning item in interface-2 is described with a class-name, the corresponding returning item in interface-1 is an object reference, subject to the following rules:
      1. If the returning item in interface-2 is described with the ONLY phrase, the returning item in interface-1 is described with the ONLY phrase and the same class-name.
      2. If the returning item in interface-2 is described without the ONLY phrase, the returning item in interface-1 is described with the same class-name or a subclass of that class-name.
      3. The presence or absence of the FACTORY phrase is the same.
    4. If the returning item in interface-2 is described with the ACTIVE-CLASS phrase, the corresponding returning item in interface-1 is described with the ACTIVE-CLASS phrase, and the presence or absence of the FACTORY phrase is the same.

    If the description of the returning item of a method in interface-1 directly or indirectly references interface-2, the description of the returning item of the corresponding method in interface-2 does not directly or indirectly reference interface-1.

  6. If the returning item in a given method of interface-2 is not an object reference, the corresponding returning item has the same ANY LENGTH,PICTURE, USAGE, SIGN, SYNCHRONIZED, JUSTIFIED, and BLANK WHEN ZERO clauses, with the following exceptions:
    1. Currency symbols match if and only if the corresponding currency strings are the same.
    2. Period picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both or for neither of these interfaces. Comma picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both or for neither of these interfaces.
  7. A group item is, for the purpose of conformance checking, considered to be equivalent to an elementary alphanumeric data item of the same length.
  8. The presence or absence of the OPTIONAL phrase is the same for corresponding parameters.
Parent topic: Conformance for Object Orientation


Conformance for Parameterized Classes and Parameterized Interfaces

When using a parameterized class or interface, the class or interface is treated as if the actual parameter classes or interfaces were substituted for the parameters throughout the class definition or interface definition.

Parent topic: Conformance for Object Orientation


Polymorphism

Polymorphism is a feature that allows a given statement to do different things. In COBOL, the ability for a data item to contain various objects of different classes means that a method invocation on that data item can be bound to one of many possible methods. Sometimes the method can be identified before execution, but in general, the method cannot be identified until run time.

A data item can be declared to contain objects of a given class or any sub-class of that class; it can also be declared to contain objects that conform to a given interface. When a given interface is used, the classes of the objects may be completely unrelated.

Parent topic: Object-oriented COBOL Concepts


Class Inheritance

Class inheritance is a mechanism for using the interface and implementation of one or more classes as the basis for another class. The inheriting class, also known as a subclass, inherits from one or more classes, known as superclasses. The subclass has all the methods defined for the inherited class definition or definitions, including any methods that the inherited definition inherited. The subclass has all the data definitions defined for the inherited class or classes, including any data definitions that the inherited class or classes inherited.

ISO2002 MF Note: This does not mean that the actual source code that describes the data is accessible or that the data items described in that source code can be directly referenced in the subclass. It means that the subclasses are treated as if their source code had a copy of the superclass definitions; in other words, the inherited data items are considered to be defined in the subclass.

The inherited data definitions define data for every instance object of the subclass and for its factory object. Each instance object has its own copy of inherited data, distinct from the copy belonging to an instance object of an inherited class. Each factory object has its own copy of inherited data, distinct from the copy belonging to a factory object of an inherited class. Names and attributes of inherited data items are not visible in the inheriting class. The inherited object data is initialized when an object is created. The inherited factory data is allocated independently from the factory data of the inherited class or classes and is initialized when the factory of the subclass is created. The inherited factory data is accessible only via methods and properties specified in the factory definition of the class that describes the data. The inherited object data is accessible only via methods and properties specified in the object definition of the class that describes the data. The subclass inherits all the file definitions in the same way as the data definitions, subject to the same provisions as data definitions. The subclass may define methods in addition to or in place of the inherited methods and may specify data definitions and file definitions in addition to, but not in place of, the inherited data definitions and file definitions.

The interface of a subclass must always conform to the interface of the inherited class, although the subclass may override some of the methods of the inherited class to provide different implementations.

User-defined words in an inherited class are not inherited in the subclass, and may be used in the subclass definition as if they were not defined in the inherited class.

Parent topic: Object-oriented COBOL Concepts


Interface Inheritance

Interface inheritance is a mechanism for using one or more interface definitions as the basis for another interface. The inheriting interface has all the method specifications defined for the inherited interface definition or definitions, including any method specifications that the inherited definition or definitions inherited. The inheriting interface may define new methods augmenting the set of inherited method specifications. The inheriting interface must always conform to each of the inherited interfaces.

Parent topic: Object-oriented COBOL Concepts


Interface Implementation

Interface implementation is a mechanism for using one or more interface definitions as the basis for a class. The implementing class must implement all the method specifications defined for the implemented interface definition or definitions, including any method specifications that the implemented definition or definitions inherited. The interface of the factory object of the implementing class must conform to the interfaces to be implemented by the factory object, and the interface of the instance objects of the implementing class must conform to the interfaces to be implemented by the instance object.

Parent topic: Object-oriented COBOL Concepts


Parameterized Classes

A parameterized class is a generic or skeleton class, which has formal parameters that will be replaced by one or more class-names or interface-names. When it is expanded by substituting specific class-names or interface-names as actual parameters, a class is created that functions as a non-parameterized class. See the ACTUAL-PARAMS Compiler directive for details of this expansion.

The life cycle for a parameterized class is defined in the section Life Cycle of Parameterized Classes.

Parent topic: Object-oriented COBOL Concepts
Related information
Life Cycle of Parameterized Classes


Parameterized Interfaces

A parameterized interface is a generic or skeleton interface, which has formal parameters that will be replaced by one or more class-names or interface-names. When it is expanded by substituting specific class-names or interface-names as actual parameters, an interface is created that functions as a non-parameterized interface. See the ACTUAL-PARAMS Compiler directive for details of this expansion.

The life cycle for a parameterized interface is defined in the section Life Cycle of Parameterized Interfaces.

  • Object Life Cycle
  • Life Cycle of Factory Objects
  • Life Cycle of Objects
  • Life Cycle of Parameterized Classes
  • Life Cycle of Parameterized Interfaces
Parent topic: Object-oriented COBOL Concepts
Related information
Life Cycle of Parameterized Interfaces


Object Life Cycle

The life cycle for an object begins when it is created and ends when it is destroyed.

Parent topic: Parameterized Interfaces


Life Cycle of Factory Objects

A factory object is created before it is first referenced by a run unit.

A factory object is destroyed after it is last referenced by a run unit.

Parent topic: Parameterized Interfaces


Life Cycle of Objects

An object is created as the result of the NEW method being invoked on a factory object.

An object is destroyed when the run unit terminates.

MF An object is also destroyed as the result of the FINALIZE method being invoked on an object, if that occurs before the run unit terminates.

Parent topic: Parameterized Interfaces


Life Cycle of Parameterized Classes

An expansion of a parameterized class is treated in all respects the same as if it were a class that is not a parameterized class.

When a parameterized class is specified in the Repository paragraph, a new class (an instance of a parameterized class) is created based on the specification of the parameterized class. This class has its own factory object and is completely separate from any other instance of the same parameterized class.

Within a run unit, two classes with the same externalized class-name that are created by expanding the same parameterized class with the same actual parameters are the same class instance. If two classes expand a parameterized class with different actual parameters, they are not the same class instance and shall not have the same externalized class-name.

Parent topic: Parameterized Interfaces


Life Cycle of Parameterized Interfaces

An expansion of a parameterized interface is treated in all respects as if it were an interface that is not parameterized.

When a parameterized interface is specified in the Repository paragraph, a new interface (an instance of a parameterized interface) is created based on the specification of the parameterized interface.

Within a run unit, two interfaces with the same externalized interface-name that are created by expanding the same parameterized interface with the same actual parameters are the same interface instance. If two interfaces expand a parameterized interface with different actual parameters, they are not the same interface instance and shall not have the same externalized interface-name.

Parent topic: Parameterized Interfaces


Managed Code Concepts

Note: Visual COBOL for Eclipse supports managed COBOL. To develop applications for managed COBOL, install one of our Visual COBOL for Visual Studio products.
  • Attributes, Custom Attributes
  • Delegates and Events
    The delegate system is the object-oriented equivalent of the procedure pointer and is a type safe solution. The use of procedure or function pointers is a common enough occurrence in many languages, and in .NET they are generally used as a mechanism for one software component to notify another about an event which has occurred. Delegates and events are also implemented on the JVM platform.
  • Enumerations and Enum types
  • Extension Methods in Managed COBOL
  • Nested Classes in Managed COBOL
    In managed COBOL, you can define a nested class within another class, following all the methods belonging to the containing class.
  • Data Types in Managed COBOL
  • Specifying Type Names
  • Simplified Class Layout
Parent topic: Language Fundamentals


Attributes, Custom Attributes

Attributes (previously custom attributes) are used to provide additional information about elements within your program. Much of the syntax used in a COBOL program describes program elements, such as the visibility of methods and fields (PUBLIC, PRIVATE, PROTECTED, etc.). All these descriptions are embedded as ‘Metadata’ into the dll or exe file output by the Compiler, and can be interrogated by other programs using Reflection. Attributes are a way of adding additional metadata to program elements in a way that is open ended and unlimited. Attributes are attached to COBOL items using the ATTRIBUTE reserved word.

Attributes may be used to describe methods, data items, properties, events, delegates, method parameters, assemblies, classes and method return values.

The arguments you specify for the attribute are of two types:

  • Ordinary parameters - the arguments to the constructor for that attribute
  • Named parameters - correspond to properties defined on the attribute class

For example:

 01 a binary-long attribute xml("UpperB").

The ordinary parameters used in the attribute specification must match a constructor defined by the attribute. In the example above, the constructor expects a single parameter of type string.

As another example:

attribute WebService(NAME Description="My service")

The named parameters must match properties defined by the attribute. In this example, Description is a property of type string defined for the attribute class WebService.

The attributes supported in COBOL are broadly similar to annotations supported in other languages for JVM.

Parent topic: Managed Code Concepts
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


Delegates and Events

The delegate system is the object-oriented equivalent of the procedure pointer and is a type safe solution. The use of procedure or function pointers is a common enough occurrence in many languages, and in .NET they are generally used as a mechanism for one software component to notify another about an event which has occurred. Delegates and events are also implemented on the JVM platform.

Delegates

A delegate is a class that can hold a reference to a method and, in the case of an instance method, an object on which that method can be invoked.

Once an instance of a delegate class has been created, it can be invoked, at which point the referenced method is invoked on the stored instance.

A delegate type can only hold references to methods of a particular signature, so creating and invoking delegates is type safe.

To define a delegate in COBOL, you use the DELEGATE-ID keyword, and the PROCEDURE DIVISION header to specify the signature. For example, to declare a delegate that has a string parameter and returns a binary-long:

delegate-id MyDelegate.
procedure division using by value s1 as string returning n1 as binary-long.
end delegate.
Method Groups

A method group is a method invocation expression preceded by the keyword METHOD, and without any parameters. When a method group is specified, it denotes one of the set of methods with the specified name in the specified class.

An implicit conversion exists between a method group and a specific delegate type, if one of the methods identified by the method group has a signature which is compatible with that delegate type.

For example, to create an instance of the delegate MyDelegate you declared above, that points to a suitable method:

01 d type MyDelegate.
01 c type Class1.
...
set d to method c::m

class-id Class1.
method-id m.
procedure division using by value s1 as string returning n1 as binary-long.
end method.

method-id m.
procedure division using by value s1 as string s2 as string returning n1 as binary-long.
end method.

end class.

In the example above, the SET statement automatically selects the first overload of the method m as it has a signature which is compatible with that of the delegate type MyDelegate.

A method group can also be used as a parameter to a method, when that method has an argument of a compatible delegate type. Again, an implicit conversion from the method group to the delegate type will take place, and that delegate will be passed as the parameter to the target method.

Anonymous methods

You can set a delegate to point to a piece of code, without formally setting that code up as a specific method. Such a piece of code is called an Anonymous Method, and you use the keywords DELEGATE and END-DELEGATE to specify it.

You specify any parameters and return values with the words USING and RETURNING attached to the word DELEGATE.

The following shows how you can attach an anonymous method to the delegate MyDelegate you created in the previous examples:

01 d type MyDelegate.
set d to delegate using s1 as string
                                returning n1 as binary-long
                  set n1 to s1::Length
              end-delegate.
Invoking delegates

To invoke a delegate after it has been created, you use the keyword RUN followed by the delegate name, and any parameters enclosed in parentheses. For example, to run the delegate d created above and displaying the results, type:

display run d("Hello")

This statement causes the anonymous method to be invoked and return a value of 5. This value is then displayed.

Example of creating and invoking delegates
       delegate-id MyDelegate.
       procedure division using by value s1 as string returning n1 as binary-long.
       end delegate.

       class-id a.
       method-id main static.
       01 d type MyDelegate.
       01 c type Class1 value new Class1.

       set d to method c::m
       display run d("ABC")

       set d to delegate using s1 as string
                         returning n1 as binary-long
                    set n1 to s1::Length
                end-delegate
       display run d("XYZ")
       end method.
       end class.

       class-id Class1.
       method-id m.
       procedure division using by value s1 as string returning n1 as binary-long.
           set n1 to size of s1 + 3
       end method.
       method-id m.
       procedure division using by value s1 as string s2 as string returning n1 as binary-long.
       end method.
       end class.
Combining delegates

A single delegate can hold references to more than one object/method pair. In such cases, at the time when the delegate is invoked, each one of the methods will be invoked in the order in which they were added to the delegate.

  • You use the operator '+' to add a method group, anonymous method or another delegate to a delegate.
  • You use the operator '-' to remove methods from a delegate.
Note: At least one side of such an expression must be an instance of a delegate type.

For example:

       class-id DelegateCombining.
       method-id main static.
       01 cd1 type D.
       01 cd2 type D.
       01 cd3 type D.
       01 c type C value new C.
           set cd1 to method type C::M1
           invoke cd1(-1)
           set cd2 to method type C::M2
           invoke cd2(-2)
           set cd3 to cd2 + method type C::M1
           invoke cd3(10)
           set cd3 to method type C::M1 + cd3
           invoke cd3(20)

           set cd3 to cd3 + method c::M3
           invoke cd3(30)

           set cd3 to cd3 - method type C::M1
           invoke cd3(40)
           set cd3 to cd3 - method c::M3
           invoke cd3(50)
           set cd3 to cd3 - method type C::M2
           invoke cd3(60)
           set cd3 to cd3 - cd2
           invoke cd3(60)
           set cd3 to cd3 - cd1
           try
               invoke cd3(70)
           catch
               display "null reference exception caught"
           end-try
           set cd3 to cd3 - cd1

           set cd1 to method type C::M1
           set cd2 to method type C::M2
           set cd3 to cd1 + cd2 + cd2 + cd1
           invoke cd3(80)
           set cd3 to cd3 - cd1
           invoke cd3(90)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd1 + cd2)
           invoke cd3(100)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd2 + cd2)
           invoke cd3(110)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd2 + cd1)
           invoke cd3(120)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd1 + cd1)
           invoke cd3(130)

       end method.
       end class.

       delegate-id D.
       procedure division using by value i as binary-long.
       end delegate.

       class-id C.
       method-id M1 static.
       procedure division using by value i as binary-long.
           display "C::M1 --> " i
       end method.
       method-id M2 static.
       procedure division using by value i as binary-long.
           display "C::M2 --> " i
       end method.
       method-id M3.
       procedure division using by value i as binary-long.
           display "C::M3 --> " i
       end method.
       end class.

Events

An event is a way in which a class can provide notifications when something of interest happens, such as a key being pressed in a GUI environment.

To define an event, you add the keyword EVENT to a delegate field. For example:

       01 ChangeEvent type ChangeDelegate event public.

Delegates of the same type, or compatible method groups or anonymous methods can be attached to the event, and will be invoked at the time when the owning class of the event invokes the backing delegate.

The relationship between an event and its backing delegate is very similar to the relationship between a property and its backing storage.

Attaching a method or a delegate to an event

You use the ATTACH statement to attach a delegate, method group or an anonymous method to an event:

ATTACH {delegate-instance}    TO event-expression
                {method-group}
                {anonymous-method}

For example:

       01 names type myList.
       01 MyDelegate type ChangeDelegate.
       procedure division.
           set names to new myList
           attach method ListChanged to names::ChangeEvent
           set MyDelegate to method ListChanged
           attach MyDelegate to names::ChangeEvent
To detach a method or a delegate from an event

To detach a delegate or method group from an event use the DETACH statement:

DETACH {delegate-instance}    FROM  event-expression
                {method-group}

For example:

           detach MyDelegate from names::ChangeEvent
           detach method ListChanged from names::ChangeEvent
Parent topic: Managed Code Concepts
Related information
The Delegate-ID Paragraph


Enumerations and Enum types

An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.

For example, you could declare an enum type for the days of the week, as follows:

enum-id DaysOfWeek as "DaysOfWeek".
       01 binary-long.
          78 Sunday value 0. *> optional, as 0 is the default
          78 Monday.         *> by default, this is value 1
          78 Tuesday.        *> by default, this is value 2 and so on
          78 Wednesday.
          78 Thursday.
          78 Friday.
          78 Saturday.
       end enum.

You can then refer to the enum type in your code, as follows:

set today to type DaysOfWeek::Monday

Where DaysOfWeek::Monday represents the binary-long value 1.

The Compiler adds a static method called 'values' that returns an array containing the values of the enum. You can use this method together with the PERFORM THROUGH construct to iterate over the values of an enum type.

You declare an enum using the ENUM-ID paragraph. This is followed by a working-storage section consisting of:

  • A single numeric field of one of the predefined types. By default, this is binary-long corresponding to the 32Java type int.
  • Any number of level 78 items defining the values for the enum. The default value of the first item is 0 and the values of subsequent items are incremented by default.
Note: In COBOL for JVM, as in Java, the enum declaration defines an enum class, which is a class that derives from java.lang.Enum. In Java, this enum class can include methods and other fields explicitly declared by the user, whereas this is not allowed in COBOL.
Parent topic: Managed Code Concepts
Related information
The Enum-ID Paragraph


Extension Methods in Managed COBOL

Extension methods enable you to add methods to existing types without the need to edit or recompile the code. Extension methods appear as additional methods available on an object instance while they are implemented elsewhere.

To declare an extension method, you use the EXTENSION keyword. The extension method must be a static method in a static class that is not nested or generic.

       class-id MyExtension static.
       method-id MyExtensionMethod [static] [is] extension.
       local-storage section.
       procedure division using myName as type classToExtend
                       returning myReturnName as type returnType.
           set myReturnName to my code...
           goback.
       end method.
       end class.

There is no special syntax for calling extension methods from managed COBOL. You consume an extension method in the same way as any other method, except you specify the first parameter as the type of the method, using this syntax:

parameter-1::method-name(more parameters)
Parent topic: Managed Code Concepts
Related information
The Operator-ID Paragraph
The Method-ID Paragraph


Nested Classes in Managed COBOL

In managed COBOL, you can define a nested class within another class, following all the methods belonging to the containing class.

Nested classes can access static fields, properties and methods within the containing classes.

The optional SHARING PARENT phrase in the nested class definition enables instance methods and properties in the nested class to access the instance fields, properties and methods in the containing class.

    class-id ContainingClass.
    ...
    class-id Nested1.
        ...
    end class.
    class-id Nested2 sharing parent.
       ...
    end class.
    end class.

Nested Classes with SHARING PARENT

Nested classes with the SHARING PARENT phrase may only be instantiated from within an instance method in the enclosing class. They can access the instance members from that containing class, even when those instance members are private.

Such a nested class contains an implicit reference to an instance of its containing class. The nested class uses this reference to access the enclosing class's instance members. This means that the containing class instance will not be garbage collected until all references to the inner class held externally have themselves been garbage collected.

For example:

    class-id ContainingClass.
    01 companyName string value "Micro Focus".

    method-id instance1.
    01 o type Nested2.
        set o to new Nested2
        ...
    end method

    class-id Nested2 SHARING PARENT.
    method-id method2
        display companyName
    end method.
    end class.

    end class.

Nested Classes without SHARING PARENT

Nested classes defined without the SHARING PARENT phrase may be declared as public, private or internal. Depending on the visibility specified, they can be instantiated from any context, not just from the containing class, and not just from instance methods. They can only access instance members of the containing class using an explicit object reference.

Parent topic: Managed Code Concepts
Related reference
Classes


Data Types in Managed COBOL

COBOL provides predefined usages corresponding to many of the most commonly used managed code types. These names can be used when declaring a data item, and anywhere a type specifier is expected - see Specifying Type Names. For example:

    01 anInteger binary-long.

Predefined Managed Types

Managed COBOL (.NET or JVM COBOL) | .NET type | JVM type | C# keyword | Description
Integer types:
binary-char | System.SByte | byte | sbyte | An 8-bit signed integer Not CLS-compliant
binary-char unsigned | System.Byte |  | byte | An 8-bit unsigned integer
binary-short | System.Int16 | short | short | A 16-bit signed integer Not CLS-compliant
binary-short unsigned | System.UInt16 |  | ushort | A 16-bit unsigned integer
binary-long | System.Int32 | int | int | A 32-bit signed integer
binary-long unsigned | System.UInt32 |  | uint | A 32-bit unsigned integer Not CLS-compliant.
binary-double | System.Int64 | long | long | A 64-bit signed integer
binary-double unsigned | System.UInt64 |  | ulong | A 64-bit unsigned integer Not CLS-compliant
Floating point types:
float-short | System.Single | float | float | A single-precision (32-bit) floating-point number
float-long | System.Double | double | double | A double-precision (64-bit) floating-point number
Logical types:
condition-value | System.Boolean | boolean | bool | A boolean value (true or false)
Other types:
character | System.Char | char | char | A unicode (16-bit) character
decimal | System.Decimal | see JVMDECIMAL. | decimal | A 96-bit decimal value
Class objects:
object | System.Object | java.lang.Object | object | The root of the object hierarchy
string | System.String | java.lang.String | string | An immutable, fixed-length string of Unicode characters
Collection types:
list | System.Collections.Generic.IList<T> | java.util.List |  | An ordered collection of items
dictionary | System.Collections.Generic.IDictionary<TKey, TValue> | java.util.Map |  | A mapping of keys to values
set | System.Collections.Generic.ISet<T> | java.util.Set<T> |  | An unordered collection of items

Referencing Types Using the TYPE Keyword

Further managed types can be specified in COBOL using the syntax TYPE classname in the data item definition. For example:

    01 objMyType type MyType.

All the COBOL data types in the table above and any further managed types that you define are mapped onto the corresponding native type (.NET or JVM), but they must conform to the following rules. They:

  • Must be declared at 01 (or 77) level
  • Must have no REDEFINES or RENAMES
  • Must never be the subject of reference modification
  • Must never be the subject of the ADDRESS OF clause
  • May use format 3 of the OCCURS clause to declare an array

Any COBOL data item that does not follow these rules, or is of any other category, is not considered to be a native type (.NET or JVM) and is allocated by the Compiler within an internally managed byte array. COBOL pointer data items always point into one of these byte arrays.

Resolving Types

If your code references a type without specifying the namespace it belongs to, the Compiler first attempts to resolve this to a type formed by adding the namespace of the current class to the type name. For example:

$set ilusing"System"
class-id MyNamespace.EventHandler.
01 o type EventHandler.
end class.

In the example above 01 o type EventHandler. resolves to MyNamespace.EventHandler and not to System.EventHandler.

If no such type exists then the Compiler tries to resolve the unspecified type in the order listed below:

  1. if the current compilation includes a single type with this name and with no namespace, the Compiler resolves it to this type.
  2. if a referenced assembly includes a single type with the same name and with no namespace, the Compiler resolves to this type.
  3. if the current compilation includes a single type with this name and with the same namespace as the current type, the Compiler resolves it to this type
  4. if a referenced assembly includes a single type with this name and with the same namespace as the current type, the Compiler resolves it to this type
  5. if among the namespaces specified with the ILUSING directives a single type with the same name, the Compiler resolves to this type.
  6. if among the namespaces specified with the ILUSING directives there are more than one namespaces that include the same type, the Compiler emits an error.

Value Types, Reference Types and Boxing

Managed COBOL distinguishes between:

  • Value types (such as binary-long and System.DateTime in .NET). Value type data items contain the actual data. For example, a COBOL binary-long data item contains a 32 bit integer.
  • Reference types, which are allocated on the object heap. Reference type data items hold a reference into the object heap. Reference types are under the management of the garbage collector.

All value types can be turned into reference types by a process known as boxing. For example, you can set an object reference to a value type, such as a binary-long.

Boxing happens automatically when needed, for example when a value type is passed as a parameter to a method that expects an object as a parameter.

You can box explicitly by assigning a value type to a generic object (such as System.Object in .NET COBOL or java.lang.Object in JVM COBOL).

You can unbox value types to restore the original value type.

When you specify TYPE classname in the data item definition:

  • If classname represents a reference type, you get a reference type object.
  • If classname represents a value type, you get a value type object.

During boxing, the system copies the value into the object heap and returns a reference to it. When the reference is no longer active (because nothing in the program is holding on to it), the space in the object heap will eventually be regained by the garbage collector.

See the ValueTypes sample, available from

Parent topic: Managed Code Concepts
Related information
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Specifying Type Names


Specifying Type Names

You can refer to class and interface names in managed COBOL by using a type-specifier, which can be defined by using:

  • Managed COBOL data types that correspond to types in other managed languages, such as binary-long, which corresponds to System.Int32 in .NET COBOL and int in JVM COBOL. For example:
        01 anInteger binary-long
    01 aFloatingPointItem float-short
    01 aString string
  • The TYPE keyword followed by the class name. For example:
        01 objMyType type MyType.
    01 objDateTime type DateTime.         *> .NET COBOL
    01 objDateTime type java.util.Date.   *> JVM COBOL

    Where:

    • objMyType is defined as an object of type myType
    • objDateTime is defined as an object of type DateTime in .NET COBOL or java.util.Date in JVM COBOL
  • The class defined in a repository entry (for backward compatibility only)

To define a namespace to represent long class names so that you need to type a short name only, use the ILUSING directive.

Parent topic: Managed Code Concepts
Related information
Data Types in Managed COBOL
ILUSING
Type Compatibility of .NET and JVM COBOL with Other Managed Languages


Simplified Class Layout

We recommend that you use the simplified class layout when writing managed COBOL. In this layout, you put data and methods directly under the CLASS-ID header.

In this case, both method and data are instance by default. To define methods and data as static, you use the STATIC keyword. For example:

Class-id a.
01 str string.
01 static-str string static.
Method-id m1.
End method.
Method-id m2 static.
End method.
End class.

The previous layout is still supported for backward compatibility. Previously, you had to embed methods and data within the STATIC/END STATIC and OBJECT/END OBJECT markers.

Parent topic: Managed Code Concepts


Run Unit Communication

  • Common, Initial and Recursive Attributes
  • Sharing Data
  • Sharing File Connectors
Parent topic: Language Fundamentals


Common, Initial and Recursive Attributes

A program can be described with attributes that affect its initial state or that define the manner in which it can be called.

ANS85 A common program is one that is directly contained within another program and that can be called by programs directly or indirectly contained in that other program, as described in the section Scope of Names in the chapter Concepts of the COBOL Language. The common attribute is attained by specifying the COMMON clause in a program's Identification Division. When the COMMON clause is not specified, a contained program that is not recursive can be called only from the directly-containing program. The COMMON clause facilitates the writing of subprograms that can be used by all the programs contained within a program.

ANS85 An initial program is one whose program state is initialized when the program is called. During the process of initializing an initial program, that program's internal data is initialized as described in the section State of a Function, Method, Object or Program. The initial attribute is attained by specifying the INITIAL clause in the program's Identification Division.

ISO2002 MF OS390 A recursive program may call itself directly or indirectly. The program's internal data is initialized as described in the section State of a Function, Method, Object or Program. The recursive attribute is attained as specified in the section The Program-ID Paragraph in the chapter Identification Division.

ISO2002 MF OS390 Methods are always recursive. Their data is initialized in the same way as recursive programs.

ISO2002 MF OS390 If a program is neither initial nor recursive, the program's data is in the last-used state on other than the first activation of the program as described in the section State of a Function, Method, Object or Program. The program cannot be activated while it is active unless it has the recursive attribute.

Parent topic: Run Unit Communication
Related information
Scope of Names
State of a Function, Method, Object or Program
The Program-ID Paragraph


Sharing Data

Two runtime elements in a run unit can reference common data in the following circumstances:

  • The data content of an external data record can be referenced from any runtime element provided that element has described that data record.
  • If a program is contained in another program, both programs can refer to data possessing the global attribute either in the containing program or in any program which directly or indirectly contains the containing program.
  • The mechanism whereby a parameter value is passed by reference from an activating runtime element to an activated runtime element establishes a common data item; the activated runtime element, which can use a different identifier, can refer to a data item in the activating runtime element.
Parent topic: Run Unit Communication


Sharing File Connectors

Two runtime elements in a run unit can reference common file connectors in the following circumstances:

  • An external file connector can be referenced from any runtime element which describes that file connector.
  • If a program is contained in another program, both programs can refer to a common file connector by referring to an associated global file-name either in the containing program or in any program which directly or indirectly contains the containing program.
Parent topic: Run Unit Communication


Data Division

  • Overview
  • Automatic, Initial and Static
  • State of a Function, Method, Object or Program
  • Global Names and Local Names
  • External and Internal Items
Parent topic: Language Fundamentals


Overview

The Data Division is subdivided into the following sections:

  1. File Section
  2. Working-Storage Section
  3. MF Thread-Local-Storage Section
  4. MF Object-Storage Section
  5. ISO2002 MF Local-Storage Section
  6. Linkage Section
  7. Report Section
  8. ISO2002 MF XOPEN Screen Section.

The File Section defines the structure of data files. Each file is defined by a file description entry and one or more record descriptions. Record descriptions are written immediately following the file description entry.

The Working-Storage Section describes records and noncontiguous data items which are not part of external data files but are developed and processed internally. It also describes data items whose values are assigned in the source text and do not change during execution.

MF The Thread-Local-Storage Section describes data which is unique to each thread, and is persistent across calls. Thread-local-storage can be viewed as thread-specific working-storage. This is useful for resolving contention problems in most reentrant programs. In many cases, a non-file-handling program can be made completely reentrant by simply changing the WORKING-STORAGE SECTION header to a THREAD-LOCAL-STORAGE SECTION header.

MF The Object-Storage Section describes class object data and instance object data. Its structure is the same as the Linkage and Working-Storage Sections.

ISO2002 MF The Local-Storage Section identifies a program as eligible for recursion. The Local-Storage Section can also be specified in a method, which is also eligible for recursion. A separate copy of the Local-Storage Section is created each time the runtime element is activated and exists only during the lifetime of that runtime element.

The Linkage Section appears in a source element that can be activated by another source element. It describes data items that are to be referred to by both the activating and the activated elements. Its structure is the same as the Working-Storage Section.

The Report Section contains one or more report description entries (RD entries), each of which forms the complete description of a report.

ISO2002 MF XOPEN The Screen Section defines the attributes of the screens. It offers the facility to specify the exact location of fields when they are displayed on the screen as well as to control certain console features during an ACCEPT or DISPLAY operation.

MF Data records and items that are described in the same way have the same type. The descriptions of such items can be conveniently manipulated by declaring a type definition. A type definition can appear in the Working-Storage and Linkage Sections. A type definition in a call prototype may be referenced in a program definition.

Parent topic: Data Division


Automatic, Initial and Static

There are three kinds of internal data items and file connectors: automatic, initial, and static. The designation of automatic, initial, and static items relates to their persistence and the persistence of their contents during the execution of a run unit.

Data items and file connectors have an initial and last-used state. The initial state of a data item depends on the presence or absence of a VALUE clause in its data description entry, the section in which the data item is described, and the description of the data item. The initial state of a file connector is that it is not in an open mode.

Last-used state means that the content of the data item or file connector is that of the last time it was modified.

Automatic items are set to their initial state any time a function, method or program is activated, and each instance of the function, method or program has its own copy of the item. An automatic item is an item described in the Local-Storage Section.

Initial items are set to their initial state any time an initial program is activated. All data items and file connectors in an initial program are initial items. Also, an attribute of a screen item in an initial program is treated as an initial item.

Static items are set to their initial state any time a function, method, object, or program is set to its initial state. (See the section State of a Function, Method, Object or Program.) A static item is an item described in the File or Working-Storage Section of a source element that is not an initial program. Also, an attribute of a screen item in a source element that is not an initial program is treated as a static item.

Parent topic: Data Division
Related information
State of a Function, Method, Object or Program


State of a Function, Method, Object or Program

  • State of a Function, Method or Program
  • Initial State of an Object
Parent topic: Data Division


State of a Function, Method or Program

The state of a function, method or program at any point in time in a run unit may be active or inactive. When a function, method or program is activated, its state may also be initial or last-used.

  • Active State
  • Initial and Last-used States of Data
Parent topic: State of a Function, Method, Object or Program


Active State

A function, method or program may be activated recursively. Therefore, several instances of a function, method or program may be active at once.

An instance of a function is placed in an active state when it is successfully activated and remains active until the execution of a STOP statement or an implicit or explicit function format of the EXIT statement with this instance of this function.

An instance of a method is placed in an active state when it is successfully activated and remains active until the execution of a STOP statement or an implicit or explicit EXIT METHOD statement within this instance of this method.

An instance of a program is placed in an active state when it is successfully activated by the operating system or successfully called from a runtime element. An instance of a program remains active until the execution of one of the following:

  • A STOP statement
  • In a called program, an implicit or explicit EXIT PROGRAM statement within that program
  • A GOBACK statement within either that same called program or a program that is not under the control of a calling runtime element.

Whenever an instance of a function, method or program is activated, the control mechanisms for PERFORM statements contained in that instance of the function, method or program are set to their initial states and the GO TO statements referred to by ALTER statements are set to their initial states.

Parent topic: State of a Function, Method or Program


Initial and Last-used States of Data

When a function, method or program is activated, the data within is in either the initial state or the last-used state.

  • Initial State
  • Last-used State
Parent topic: State of a Function, Method or Program


Initial State

Automatic data and initial data is placed in the initial state every time the function, method or program in which it is described is activated.

Static data is placed in the initial state:

  1. The first time the function, method or program in which it is described is activated in a run unit.
  2. The first time the program in which it is described is activated after the execution of an activating statement referencing a program that possesses the initial attribute and directly or indirectly contains the program.
  3. The first time the program in which it is described is activated after the execution of a CANCEL statement referencing the program or CANCEL statement referencing a program that directly or indirectly contains the program.

When data in a function, method or program is placed in the initial state, the following occurs:

  1. Internal data items in the Working-Storage Section

    ISO2002 MF OS390 and Local-Storage Section

    that are subject to VALUE clauses are initialized as described in the section The VALUE Clause in the chapter Data Division - File and Data Description.

  2. Internal data items in the Working-Storage Section that are not subject to VALUE clauses and internal data items in the File Section are initialized in accordance with the setting of the DEFAULTBYTE Compiler directive.
  3. Internal data items in the Linkage Section

    ISO2002 MF OS390 and Local-Storage Section

    that are not subject to VALUE clauses and are undefined.

  4. MF Internal data items in the Thread-Local Section and the Object Section are treated in the same way as internal data items in the Working-Storage Section.
  5. The function, method or program's internal file connectors are initialized by setting them to not be in any open mode.
  6. The attributes of screen items are set as specified in the screen description entry.
Parent topic: Initial and Last-used States of Data
Related information
The VALUE Clause


Last-used State

MF , 78

Static and external data are the only data that are in the last-used state. External data is always in the last-used state except when the run unit is activated. Static data is in the last-used state except when it is in the initial state as defined above.

Parent topic: Initial and Last-used States of Data


Initial State of an Object

The initial state of an object is the state of the object immediately after it is created. Internal data, internal file connectors, and the attributes of screen items are initialized in the same manner as when data in a method or program is placed in the initial state, in accordance with the section Initial State.

Parent topic: State of a Function, Method, Object or Program
Related information
Initial State


Global Names and Local Names

A data-name names a data item. A file-name names a file connector. These names are classified as either global or local.

A global name can be used to refer to the item with which it is associated either from within the source element in which the global name is declared, or from within any other source element which is contained in the source element which declares the global name.

A local name, however, can be used only to refer to the item with which it is associated from within the source element in which the local name is declared. Some names are always global; other names are always local; some other names are either local or global depending upon specifications in the source element in which the names are declared.

A record-name is global if the GLOBAL clause is specified in the record description entry by which the record-name is declared or, in the case of record description entries in the File Section, if the GLOBAL clause is specified in the file description entry for the file-name associated with the record description entry.

A data-name is global if the GLOBAL clause is specified either in the data description entry by which the data-name is declared or in another entry to which that data description entry is subordinate.

A condition-name declared in a data description entry is global if that entry is subordinate to another entry in which the GLOBAL clause is specified. However, specific rules sometimes prohibit specification of the GLOBAL clause for certain data description, file description, or record description entries.

A file-name is global if the GLOBAL clause is specified in the file description entry for that file-name.

If a data-name, a file-name, or a condition-name declared in a data description entry is not global, the name is local.

Global names are transitive across source elements contained within other source elements.

Parent topic: Data Division


External and Internal Items

Accessible data items usually require that certain representations of data be stored. File connectors require that certain information concerning files be stored. The storage associated with a data item or a file connector can be external or internal.

External and internal items can have either global or local names.

A data record described in the Working-Storage Section is given the external attribute by the presence of the EXTERNAL clause in its data description entry. Any data item described by a data description entry subordinate to an entry describing an external record also attains the external attribute. If a record or data item does not have the external attribute, it is internal.

A file connector is given the external attribute by the presence of the EXTERNAL clause in the associated file description entry. If the file connector does not have the external attribute, it is internal.

The data records described subordinate to a file description entry which does not contain the EXTERNAL clause or a sort-merge file description entry, as well as any data items described subordinate to the data description entries for such records, are always internal. If the EXTERNAL clause is included in the file description entry, the data records and the data items attain the external attribute.

Data records, subordinate data items, and various associated control information described in the Local-Storage, Linkage, Report and Screen Sections are always internal. Special considerations apply to data described in the Linkage Section whereby an association is made between the data records described and other data items accessible to other runtime elements.

If a data item or file connector is external, the storage associated with that item is associated with the run unit rather than with any particular runtime module within the run unit. An external item can be referenced by any runtime module in the run unit that describes it. References to external items from different runtime modules using separate descriptions of the data item or file connector are always to the same item. In a run unit, there is only one representation of an external item.

If a data item or file connector is internal, the storage associated with it is associated only with the runtime module that describes it.

Parent topic: Data Division


Procedure Division

  • Execution
  • Statements and Sentences
Parent topic: Language Fundamentals


Execution

Execution begins with the first statement of the Procedure Division, excluding declaratives. Statements are then executed in the order in which they occur in the source element, except where the rules indicate some other order.

Parent topic: Procedure Division


Statements and Sentences

A statement is a syntactically valid combination of words and symbols beginning with a COBOL verb.

A sentence consists of one or more statements and is terminated by a period followed by a space.

Statements are of the following types:

  1. Conditional statements.
  2. COBOL system-directing statements.
  3. Imperative statements.
  4. ANS85 Delimited scope statements.

There are three types of sentences:

  1. Conditional sentences.
  2. COBOL system-directing sentences.
  3. Imperative sentences.
  • Conditional Statement
  • Conditional Sentence
  • COBOL System-Directing Statement
  • COBOL System-Directing Sentence
  • Compiler Directives
  • Imperative Statement
  • Imperative Sentence
  • Delimited Scope Statements
  • Categories of Statements
Parent topic: Procedure Division


Conditional Statement

A conditional statement specifies that the truth value of a condition is to be determined and that the subsequent flow of control is dependent on this truth value.

A conditional statement is one of the following:

  • An

    ANS85 EVALUATE,

    IF, SEARCH or RETURN statement

  • A READ statement that specifies the AT END or INVALID KEY phrase
  • OSVS An ON statement
  • A WRITE statement that specifies the INVALID KEY or END-OF-PAGE phrase
  • A START, REWRITE or DELETE statement that specifies the INVALID KEY phrase
  • An arithmetic statement (ADD, COMPUTE, DIVIDE, MULTIPLY, SUBTRACT) that specifies the SIZE ERROR phrase
  • A STRING or UNSTRING statement that specifies the ON OVERFLOW phrase
  • A CALL statement that specifies the ON OVERFLOW

    ANS85 or ON EXCEPTION

    phrase

  • MF XOPEN An ACCEPT or DISPLAY statement that specifies the ON EXCEPTION phrase.
Parent topic: Statements and Sentences


Conditional Sentence

A conditional sentence is a conditional statement, optionally preceded by an imperative statement, terminated by a separator period followed by a space.

Parent topic: Statements and Sentences


COBOL System-Directing Statement

A COBOL system-directing statement consists of a directing verb and its operands. The directing verbs are described in the chapter Compiler-directing Statements.

A COBOL system-directing statement causes your COBOL system to take a specified action during creation of the object code.

Parent topic: Statements and Sentences
Related information
Compiler-directing Statements


COBOL System-Directing Sentence

A COBOL system-directing sentence is a single system-directing statement terminated by a period followed by a space.

Parent topic: Statements and Sentences


Compiler Directives

Compiler directives give you options to control the actions of the Compiler. They allow you to enable language features, choose run-time behavior, choose compile-time options, create debugging information, control the format of data files, optimize the object code, and choose SQL options.

ISO2002 The compiler directives provided by the standard are described in the topic Compiler Directives.

MF The syntax of the directives and a description of each directive provided by this implementation are given in your COBOL system documentation.

Parent topic: Statements and Sentences
Related information
Compiler Directives


Imperative Statement

An imperative statement indicates a specific unconditional action to be taken . An imperative statement is any statement that is neither a conditional statement nor a COBOL system-directing statement. An imperative statement can consist of a sequence of imperative statements, each possibly separated from the next by a separator.

The imperative verbs are:

  • ACCEPT (1)
  • ADD (2)
  • ALTER
  • CALL (4)
  • CANCEL
  • CLOSE
  • COMPUTE (2)
  • DELETE (3)
  • DISPLAY (1)
  • DIVIDE (2)
  • EXIT
  • GO TO
  • INSPECT
  • MERGE
  • MOVE
  • MULTIPLY (2)
  • OPEN
  • PERFORM
  • READ (5)
  • RELEASE
  • REWRITE (3)
  • SET
  • SORT
  • START (3)
  • STOP
  • STRING (4)
  • SUBTRACT (2)
  • UNSTRING (4)
  • WRITE (6)

1 | Without the optional ON EXCEPTION phrase.
2 | Without the optional SIZE ERROR phrase.
3 | Without the optional INVALID KEY phrase.
4 | Without the optional ON OVERFLOW or ON EXCEPTION phrase.
5 | Without the optional AT END phrase or INVALID KEY phrase.
6 | Without the optional INVALID KEY phrase or END-OF-PAGE phrase.

ANS85 The additional ANSI'85 imperative verbs are:

  • CONTINUE
  • INITIALIZE

ISO2002 The additional ISO 2002 imperative verb is:

  • ISO2002 MF INVOKE

The additional OS/VS COBOL imperative verbs are:

  • EXAMINE
  • EXHIBIT
  • GOBACK
  • TRANSFORM

VSC2 The additional VS COBOL II imperative verb is:

  • VSC2 GOBACK

MF The additional imperative verbs available to this COBOL system are:

  • CHAIN
  • EXHIBIT
  • GOBACK
  • NEXT SENTENCE

When "imperative-statement" appears in the general format of statements, "imperative-statement" refers to that sequence of consecutive imperative statements that must be ended by a period or by any phrase associated with a statement containing that "imperative-statement".

OSVS Either the connective word "THEN" or the connective word "AND" can optionally be placed between any two imperative statements which appear in a single sequence of imperative statements.

Parent topic: Statements and Sentences


Imperative Sentence

An imperative sentence is an imperative statement terminated by a period followed by a space.

Parent topic: Statements and Sentences


Delimited Scope Statements

A delimited scope statement is a statement (for example, an IF statement) which is terminated by (that is, has its end-point determined by) a matching explicit scope terminator (in this case END-IF). Thus, all the statements between a delimited scope statement and its paired explicit scope terminator are deemed to be contained within that delimited scope statement.

Delimited scope statements can be nested, in which case each explicit scope terminator encountered is considered to pair with the nearest preceding unpaired matching delimited scope statement.

Scope delimited statements can also be implicitly terminated, either at the end of a procedural sentence (where all unterminated statements are terminated by the separator period), or by the termination of any containing delimited scope statement.

Note: Not all statements are scope delimitable in this fashion; those statements that are scope delimitable are termed delimited scope statements only if they are explicitly terminated by an explicit scope delimiter.

See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language for further information.

Parent topic: Statements and Sentences
Related information
Explicit And Implicit Scope Terminators


Categories of Statements

Category Verbs
Arithmetic
  • ADD
  • COMPUTE
  • DIVIDE
  • INSPECT (TALLYING)
  • MULTIPLY
  • SUBTRACT
  • OSVS EXAMINE (TALLYING)
Conditional
  • ADD (SIZE ERROR)
  • CALL (OVERFLOW)
  • COMPUTE (SIZE ERROR)
  • DELETE (INVALID KEY)
  • DIVIDE (SIZE ERROR)
  • GO TO (DEPENDING)
  • IF
  • MULTIPLY (SIZE ERROR)
  • READ (END or INVALID KEY)
  • RETURN (END)
  • REWRITE (INVALID KEY)
  • SEARCH
  • START (INVALID KEY)
  • STRING (OVERFLOW)
  • UNSTRING (OVERFLOW)
  • WRITE (INVALID KEY or END-OF-PAGE)
  • ANS85 EVALUATE
  • OSVS ON
Data movement
  • ACCEPT (DATE, DAY or TIME)
  • INSPECT (REPLACING)
  • MOVE
  • STRING
  • UNSTRING
  • OSVS EXAMINE
  • OSVS TRANSFORM
  • ANS85 INITIALIZE
  • ANS85 INSPECT (CONVERTING)
  • ANS85 SET (TO TRUE)
  • MF SET (TO FALSE)
  • VSC2 MF SET (ADDRESS OF)
  • VSC2 MF SET (POINTER)
  • MF SET (object reference)
Ending
  • MF EXIT METHOD
  • EXIT PROGRAM
  • OSVS VSC2 MF GOBACK
  • STOP
Input/Output
  • ACCEPT (identifier)
  • CLOSE
  • MF COMMIT
  • DELETE
  • DISPLAY
  • OPEN
  • READ
  • RECEIVE
  • REWRITE ]
  • ROLLBACK
  • START
  • STOP (literal)
  • MF UNLOCK
  • WRITE
  • OSVS MF EXHIBIT
  • SET (TO ON or TO OFF)
Inter-program
  • CALL
  • CANCEL
  • MF CHAIN
  • OSVS VSC2 MF ENTRY
  • MF EXEC
  • ISO2002 MF INVOKE
  • OSVS VSC2 SERVICE
Null operation
  • EXIT
  • CONTINUE
Ordering
  • MERGE
  • RELEASE
  • RETURN
  • SORT
Procedure branching
  • ALTER
  • CALL
  • MF EXIT PERFORM/EXIT PARAGRAPH/EXIT SECTION
  • GO TO
  • MF NEXT SENTENCE
  • PERFORM
Scope delimiting
  • MF XOPEN END-ACCEPT
  • END-ADD
  • END-CALL
  • END-DELETE
  • MF XOPEN END-DISPLAY
  • END-DIVIDE
  • END-EVALUATE
  • END-IF
  • MF END-INVOKE
  • END-MULTIPLY
  • END-PERFORM
  • END-READ
  • END-RETURN
  • END-REWRITE
  • END-SEARCH
  • END-START
  • END-STRING
  • END-SUBTRACT
  • END-UNSTRING
  • END-WRITE
COBOL system-directing
  • OSVS VSC2 BASIS
  • OSVS VSC2 DELETE
  • OSVS VSC2 INSERT
  • MF $DISPLAY
  • MF $ELSE
  • MF $END
  • MF $IF
  • COPY
  • ENTER
  • USE
  • ANS85 REPLACE
  • OSVS VSC2 MF ENTRY
  • OSVS VSC2 MF EJECT
  • OSVS VSC2 MF SKIP1
  • OSVS VSC2 MF SKIP2
  • OSVS VSC2 MF SKIP3
  • VSC2 MF TITLE
  • OSVS NOTE
  • OSVS VSC2 ++INCLUDE
  • OSVS VSC2 -INC
Table handling
  • SEARCH
  • SET

IF and ON are verbs in the COBOL sense; it is recognized that they are not verbs in English.

Parent topic: Statements and Sentences


Reference Format

This entire section refers to fixed format only. Your COBOL system also accepts compilation groups written in free format.

The reference format, which provides a standard method for describing COBOL source text, is described in terms of character positions in a line on an input/output medium. Your COBOL system accepts source text written in reference format and produces an output listing using reference format.

The rules for spacing given in the discussion of the reference format take precedence over all other rules for spacing.

  • Reference Format Representation
  • Division, Section and Paragraph Formats
  • Data Division Entries
  • Declaratives
  • Comment Lines
Parent topic: Language Fundamentals
Related information
Free Format
Sample Program


Reference Format Representation

The reference format for a line is represented as shown below:

Reference Format for a COBOL Source Line

  • Margin L is immediately to the left of the leftmost character position of a line.
  • Margin C is between the 6th and 7th character positions of a line.
  • Margin A is between the 7th and 8th character positions of a line.
  • Margin B is between the 11th and 12th character positions of a line.
  • MF Margin R is immediately to the right of the 72nd character position of a line. A line can extend up to the 80th character position, but any characters occupying positions 73 to 80 are ignored by your COBOL system.

The sequence number area occupies six character positions (1-6), and is between margin L and margin C.

The indicator area is the 7th character position of a line.

Area A occupies character positions 8, 9, 10 and 11, and is between margin A and margin B.

Area B occupies character positions 12 through 72 inclusive; it begins immediately to the right of margin B and terminates immediately to the left of margin R.

ISO2002 The program text area consists of both area A and area B. Text-words can begin anywhere in the program text area.

  • Sequence Numbers
  • Continuation of Lines
  • Blank Lines
  • Pseudo-text
Parent topic: Reference Format


Sequence Numbers

A sequence number, normally consisting of six digits, can be placed in the sequence area and can be used to label a source line. This sequence number is usually in ascending numeric order on each successive source line.

OSVS VSC2 This sequence number is the one used by the BASIS mechanism for line editing, in which case it must be both numeric and in ascending order through the program (see the topic The BASIS Mechanism).

The ascending order of sequence numbers can be optionally verified by your COBOL system by using the SEQCHK Compiler directive.

ANS85 There is no requirement for the content of this area to be numeric, or even unique.

MF If the first character position of the sequence number field contains an asterisk, or any non-printing control character (less than the character SPACE in the ASCII collating sequence), then the line is treated as comment, and is not output to the listing file or device. This facility allows an output listing file to be used as a source file to a subsequent compile. This support is sensitive to the MFCOMMENT Compiler directive.

Parent topic: Reference Format Representation
Related information
The BASIS Mechanism


Continuation of Lines

Whenever a sentence, entry, phrase, or clause requires more than one line, it can be continued by starting subsequent line(s) in area B. These subsequent lines are called the continuation line(s). Any word, literal

ANS85 or PICTURE character-string

can be broken in such a way that part of it appears on a continuation line.

A hyphen in the indicator area of a line indicates that the first nonblank character in area B of the current line is the successor of the last nonblank character of the preceding line

ANS85 excluding intervening comment or blank lines

without any intervening space. However, if the continued line contains a nonnumeric literal without closing quotation mark, the first nonblank character in area B on the continuation line must be a quotation mark, and the continuation starts with the character immediately after that quotation mark. All spaces at the end of the continued line are considered part of the literal. Area A of a continuation line must be blank.

If there is no hyphen in the indicator area of a line, it is assumed that the last character in the preceding line is followed by a space. Both characters composing the separator "==" must be on the same line.

VSC2 MF Characters X" and G" must be on the same line.

MF Characters H" must be on the same line.

MF COB370 Characters N" must be on the same line.

MF XOPEN Characters *> must be on the same line.

ISO2002 Characters >> must be on the same line.

Parent topic: Reference Format Representation


Blank Lines

A blank line is one that is blank from margin C to margin R, inclusive. A blank line can appear anywhere in the source text.

Parent topic: Reference Format Representation


Pseudo-text

The text words and the separator space comprising pseudo-text can start in either area A or area B. If, however, there is a hyphen in the indicator area of a line which follows the opening pseudo-text delimiter, area A of the line must be blank; and the normal rules for continuation of lines apply to the formation of text words. (For an explanation of pseudo-text see the section Compiler-directing Statements.)

Parent topic: Reference Format Representation
Related information
Compiler-directing Statements


Division, Section and Paragraph Formats

  • Division Header
  • Section Header
  • Paragraph Header, Paragraph-name and Paragraph
Parent topic: Reference Format


Division Header

The division header must start in area A. (See Figure 1 in the topic Reference Format Representation.)

ISO2002 MF It may start in area B.

Parent topic: Division, Section and Paragraph Formats
Related information
Reference Format Representation


Section Header

The section header must start in area A. (See the figure in the topic Reference Format Representation.)

ISO2002 MF It may start in area B.

A section consists of zero, one, or more paragraphs in the Environment Division or Procedure Division or zero, one or more entries in the Data Division.

Parent topic: Division, Section and Paragraph Formats
Related information
Reference Format Representation


Paragraph Header, Paragraph-name and Paragraph

A paragraph consists of a paragraph-name followed by a period and a space, and by zero, one or more sentences, or a paragraph header followed by one or more entries. Comment entries can be included within a paragraph. The paragraph header or paragraph-name starts in area A of any line following the first line of a division or a section.

ISO2002 MF It may start in area B.

The first sentence or entry in a paragraph begins either on the same line as the paragraph header or paragraph-name, or in area B of the next nonblank line that is not a comment line. Successive sentences or entries begin either in area B of the same line as the preceding sentence or entry, or in area B of the next nonblank line that is not a comment line.

ISO2002 MF Sentences can begin anywhere in area A or area B unless the AREACHECK directive is specified.

When the sentences or entries of a paragraph require more than one line, they can be continued as described in the section Continuation of Lines.

Parent topic: Division, Section and Paragraph Formats
Related information
Continuation of Lines


Data Division Entries

Each Data Division entry begins with a level indicator or a level-number, followed by a space, followed by its associated name

ANS85 if any

, followed by a sequence of independent descriptive clauses. The last clause is always terminated by a period followed by a space.

There are two types of Data Division entry; those which begin with a level indicator and those which begin with a level-number.

A level indicator is any of the following:

  • FD (see the topic File Description Entry Skeleton),
  • SD (see the topic File Description Entry Skeleton),
  • RD (see the section The Report Description Entry.

In those Data Division entries that begin with a level indicator, the level indicator begins in area A followed by a space and followed in area B

ANS85 or area A

with its associated name and appropriate descriptive information.

Those Data Division entries that begin with level-numbers are called data description entries.

A level-number has a value taken from the set of values 1 through 49, 66, 77

MF , 78

and 88. Level-numbers in the range 1 through 9 can be written either as a single digit or as a zero followed by a significant digit. At least one space must separate a level-number from the word following the level-number.

In those data description entries that begin with level-number 01 or 77, the level-number begins in area A followed by a space and followed in area B

ANS85 or area A

by its associated record-name or item-name and appropriate descriptive information.

Successive data description entries can have the same format as the first and are indented according to level-number. Indentation does not affect the magnitude of a level-number.

When level-numbers are to be indented, each new level-number can begin any number of spaces to the right of margin A. The extent of indentation to the right is determined only by the width of the physical medium.

ISO2002 MF Data descriptions and level numbers other than 01 and 77 can also begin in area A.

Parent topic: Reference Format
Related information
File Description Entry Skeleton
The Report Description Entry


Declaratives

The key word DECLARATIVES and the key words END DECLARATIVES that precede and follow, respectively, the declaratives portion of the Procedure Division must each appear on a line by themselves. Each must begin in area A and be followed by a separator period (see the diagram in the topic Reference Format Representation).

Parent topic: Reference Format
Related information
Reference Format Representation


Comment Lines

A comment line is any line with an asterisk (*) in the continuation indicator area of the line. A comment line can appear as any line in a source element after the IDENTIFICATION DIVISION header. Any combination of characters from the computer's character set can be included in area A and area B of that line (see the diagram in the topic Reference Format Representation). The asterisk and the characters in area A and area B will be produced on the listing but serve as documentation only.

OSVS VSC2 MF A comment line can appear before the Identification Division header.

A second form of comment line represented as above but with a slash (/) (instead of an asterisk) in the indicator area of the line causes page ejection prior to printing the comment.

Successive comment lines are allowed. Continuation of comment lines is permitted, except that each continuation line must contain an asterisk in the indicator area.

  • In-line Comments
Parent topic: Reference Format
Related information
Reference Format Representation


In-line Comments

An in-line comment begins with the two contiguous characters "*>" preceded by a separator space, and ends with the last character position of the line. It allows free-form commentary to appear on the same line as character-strings and/or separators. An in-line comment can appear anywhere a separator space can appear in a COBOL compilation group or in a library text of a COBOL library. For the purpose of evaluating library text, pseudo-text and source text, an in-line comment has the value of a single space character. An in-line comment cannot be continued onto another line.

Parent topic: Comment Lines


Part 2. Program Definition

  • Compilation Group
  • Identification Division
  • Environment Division
  • Data Division
  • Procedure Division
  • Compiler-directing Statements
  • Examples
Parent topic: COBOL Language Reference


Compilation Group

  • Compilation Groups
    A compilation group is the entire source file that is submitted to the compiler.
  • End Markers
    End markers indicate the end of a definition
Parent topic: Part 2. Program Definition


Compilation Groups

A compilation group is the entire source file that is submitted to the compiler.

ANS85 A compilation group may contain zero, one, or more source units. A compilation group consists of a series of source units. A source unit may contain other source units and these contained source units may reference some of the resources of the source units within which they are contained.

A source unit begins with an Identification Division.

ANS85 A source unit includes any contained source units.

With the exception of source text manipulation statements

ANS85 and end markers

ISO2002 MF and compiler directives

, the statements, entries, paragraphs, and sections of a source unit are grouped into four divisions that are sequenced in the following order:

  1. Identification Division
  2. Environment Division
  3. Data Division
  4. Procedure Division

The beginning of a division in a source unit is indicated by the appropriate division header.

ISO2002 MF The beginning of the Identification Division may also be indicated by one of the paragraph headers permitted in the Identification Division.

The end of a division in a source unit is indicated by one of the following:

  1. The beginning of a succeeding division in that source unit
  2. ANS85 The end marker for that source unit
  3. That physical position after which no more source lines occur.

The end of a source unit is indicated by the absence of additional source lines in the compilation group.

ANS85 The end of a source unit can also be indicated by an end marker.

ANS85 When a source unit, B, is contained in another source unit, A, it may be directly or indirectly contained. Source unit B is directly contained in source unit A if there is no source unit contained in A that also contains B. Source unit B is indirectly contained in source unit A if there exists a source unit contained in A that also contains B.

A source unit that is directly or indirectly contained within another source unit is considered in these specifications as a separate source unit that may additionally reference certain resources defined in the containing source unit.

The object code resulting from compiling a source unit contained within another source unit is considered in these specifications to be inseparable from the object code resulting from compiling the containing source unit.

ANS85 A compilation unit is a source unit that is not contained within another source unit. It may be preceded or followed by other compilation units in a compilation group.

A source element is a source unit excluding any nested source units.

A runtime element is the result of compiling a source element.

A runtime module is the result of compiling a compilation unit.

ANS85 A compilation group may contain zero, one, or more source units. A compilation group consists of a series of source units. A source unit may contain other source units and these contained source units may reference some of the resources of the source units within which they are contained.

A source unit begins with an Identification Division.

ANS85 A source unit includes any contained source units.

With the exception of source text manipulation statements

ANS85 and end markers

ISO2002 MF and compiler directives

, the statements, entries, paragraphs, and sections of a source unit are grouped into four divisions that are sequenced in the following order:

  1. Identification Division
  2. Environment Division
  3. Data Division
  4. Procedure Division

The beginning of a division in a source unit is indicated by the appropriate division header.

ISO2002 MF The beginning of the Identification Division may also be indicated by one of the paragraph headers permitted in the Identification Division.

The end of a division in a source unit is indicated by one of the following:

  1. The beginning of a succeeding division in that source unit
  2. ANS85 The end marker for that source unit
  3. That physical position after which no more source lines occur.

The end of a source unit is indicated by the absence of additional source lines in the compilation group.

ANS85 The end of a source unit can also be indicated by an end marker.

ANS85 When a source unit, B, is contained in another source unit, A, it may be directly or indirectly contained. Source unit B is directly contained in source unit A if there is no source unit contained in A that also contains B. Source unit B is indirectly contained in source unit A if there exists a source unit contained in A that also contains B.

A source unit that is directly or indirectly contained within another source unit is considered in these specifications as a separate source unit that may additionally reference certain resources defined in the containing source unit.

The object code resulting from compiling a source unit contained within another source unit is considered in these specifications to be inseparable from the object code resulting from compiling the containing source unit.

ANS85 A compilation unit is a source unit that is not contained within another source unit. It may be preceded or followed by other compilation units in a compilation group.

A source element is a source unit excluding any nested source units.

A runtime element is the result of compiling a source element.

A runtime module is the result of compiling a compilation unit.

General Format

Syntax Rules

  1. Within a compilation group,

    MF call-prototypes and

    ISO2002 MF function-prototypes and program-prototypes

    must precede all other types of source units.

  2. ISO2002 MF If a compilation group contains both a function definition and a function prototype definition with the same externalized name, the signatures of these two compilation units must be the same.
  3. ISO2002 MF The Data Division of a method in an interface definition can contain only a Linkage Section.
  4. ISO2002 MF The Procedure Division of a method in an interface definition must contain only a PROCEDURE DIVISION header.
  5. MF In a call prototype, the PROCEDURE DIVISION header must conform to the rules for a format 2 PROCEDURE DIVISION header and any ENTRY statements must conform to the rules for a format 2 ENTRY statement.

General Rules:

  1. MF In a call prototype, all sections of the Data Division are ignored except for the Linkage Section, and the Procedure Division is ignored except for the PROCEDURE DIVISION header and ENTRY statements.
  2. ISO2002 MF In a function prototype and a program prototype, all sections of the Data Division are ignored except for the Linkage Section, and the Procedure Division is ignored except for thePROCEDURE DIVISION header.
Parent topic: Compilation Group


End Markers

End markers indicate the end of a definition

General Format

Note: The Delegate-ID paragraph is not yet supported in COBOL for JVM.

Syntax Rules

  1. An end marker must be present in every source unit that contains, is contained in, or precedes another source unit.
  2. Program-name-1 must be identical to the program-name declared in a preceding Program-ID paragraph.
  3. If a Program-ID paragraph declaring a specific program-name is stated between the Program-ID paragraph and the END PROGRAM marker for program-name-1, then an END PROGRAM marker referencing program-name must precede the END PROGRAM marker referencing program-name-1.
  4. ISO2002 MF Function-prototype-name-1 must be identical to the function-prototype-name declared in the corresponding Function-ID paragraph.
  5. ISO2002 MF User-function-name-1 must be identical to the user-function-name declared in the corresponding Function-ID paragraph.
  6. ISO2002 MF Program-prototype-name-1 must be identical to the program-prototype-name declared in the corresponding Program-ID paragraph.
  7. ISO2002 MF Class-name-1 must be identical to the class-name declared in the corresponding Class-ID paragraph.
  8. ISO2002 MF Method-name-1 must be identical to the method-name declared in the corresponding Method-ID paragraph.

    If the PROPERTY phrase is specified in the Method-ID paragraph, method-name-1 must be omitted.

  9. ISO2002 MF Interface-name-1 must be identical to the interface-name declared in the corresponding Interface-ID paragraph.
  10. If the source unit terminated by the end marker is contained within another source unit, the next statement must be either the first statement of a source unit or another end marker that terminates the containing source unit.
  11. If the source unit terminated by an end marker is not contained within another source unit, the next statement must be the first statement of a compilation unit.

General Rules

  1. An end marker indicates the end of the specified source unit.
Parent topic: Compilation Group


Identification Division

  • Identification Division - General Description
    The Identification Division identifies the program
  • The Program-ID Paragraph
    The Program-ID paragraph gives the name by which a program is identified and assigns selected program attributes to that program.
  • The Class-ID Paragraph
    The Class-ID paragraph indicates that this Identification Division is introducing a class definition and specifies the name that identifies the class and assigns class attributes to the class.
  • The Factory Paragraph
    The Factory paragraph indicates that this Identification Division is introducing a factory definition.
  • The Object Paragraph
    The Object paragraph indicates that this Identification Division is introducing an object definition.
  • The Method-ID Paragraph
    The Method-ID paragraph indicates that this Identification Division introduces a method definition, specifies the name that identifies the method or method prototype, and assigns method attributes to the method.
  • The Interface-ID Paragraph
    The Interface-ID paragraph indicates that this Identification Division is introducing an interface definition, specifies the name that identifies the interface and assigns interface attributes to the interface.
  • The Function-ID Paragraph
    The Function-ID paragraph specifies the name by which a function is identified and assigns selected attributes to that function.
  • The Date-Compiled Paragraph
    The Date-Compiled paragraph provides the date the intermediate code was produced in the Identification Division source program listing.
  • The Delegate-ID Paragraph
    The Delegate-ID paragraph indicates that this Identification Division introduces a delegate definition and specifies the name that identifies the delegate.
  • The Enum-ID Paragraph
    The Enum-ID paragraph indicates that this Identification Division introduces a enumeration definition and specifies the name that identifies the enumeration.
  • The Iterator-ID Paragraph
    The Iterator-ID paragraph indicates that this Identification Division introduces an iterator definition and specifies the name that identifies the iterator. Iterator-id can be specified wherever Method-ID can be specified, and can be used to define either static or instance iterators.
  • The Operator-ID Paragraph
    The Operator-ID paragraph indicates that this Identification Division introduces an operator definition and specifies the symbol or keyword that identifies the operator.
  • The Valuetype-ID Paragraph
    The Valuetype-ID paragraph indicates that this Identification Division introduces a valuetype definition and specifies the name that identifies the valuetype.
Parent topic: Part 2. Program Definition


Identification Division - General Description

The Identification Division identifies the program

ISO2002 MF , class, factory object, object, method,

NET delegate,

NET JVM enum, operator, valuetype,

ISO2002 function or interface.

MF This entire division (including the division header) is optional in a program definition.

MF Another way to identify the first source element defined in a file is with the basename, which is derived from the filename of the file containing the source element.

The Identification Division consists of a number of paragraphs. The paragraph header identifies the type of information contained in the paragraph.

ANS85 The Author, Installation, Date-Written, Date-Compiled, and Security paragraphs are classed as obsolete elements in the ANSI'85 standard and may be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation except ISO2000 fully support these obsolete paragraphs. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although they are a part of the standard COBOL definition, the obsolete paragraphs are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open source program.

General Format

Note: The Delegate-ID paragraph is not yet supported in COBOL for JVM.

Syntax Rules

  1. OSVS VSC2 MF The paragraphs can appear in any order.
  2. OSVS VSC2 The periods following the paragraph-names in the Identification Division are optional as is the period following the program-name.
  3. The comment-entry can be any combination of the characters from the computer's character set. The continuation of the comment-entry by the use of a hyphen in the continuation area is not permitted. If the Compiler directive SOURCEFORMAT is specified as or defaulted to FIXED, the comment-entry can be contained on one or more lines but is restricted to area B of those lines; the next line commencing in area A begins the next non-comment entry.

    MF If the Compiler directive SOURCEFORMAT is specified as FREE, the comment-entry cannot be continued; the next line begins the next non-comment entry.

    VSC2 The comment-entry can contain the SKIP1, SKIP2, SKIP3, EJECT or TITLE statements anywhere on the line. These statements are actioned if they are alone on a line in the comment-entry, and do not terminate the comment-entry.

    OSVS The comment-entry can contain the SKIP1, SKIP2, SKIP3, or EJECT statements anywhere in the B margin. These statements are actioned if they are alone on a line in the comment-entry, and do not terminate the comment-entry.

    OSVS The comment-entry can be contained in either area A or area B of the comment-entry lines. However, the next occurrence in area A of any one of the following COBOL words or phrases terminates the comment-entry and begin the next paragraph or division:

    OSVS
    • OSVS PROGRAM-ID
    • OSVS AUTHOR
    • OSVS INSTALLATION
    • OSVS DATE-WRITTEN
    • OSVS DATE-COMPILED
    • OSVS SECURITY
    • OSVS ENVIRONMENT
    • OSVS DATA
    • OSVS PROCEDURE
Parent topic: Identification Division


The Program-ID Paragraph

The Program-ID paragraph gives the name by which a program is identified and assigns selected program attributes to that program.

ISO2002 MF The Program-ID paragraph specifies the name by which a program prototype is identified.

MF The Program-ID paragraph specifies the name by which a call prototype is identified.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • CASE - determines whether upper-case and lower-case letters are considered equivalent.
    • DEFAULT-BYTE - sets the value for data items defined in Working-Storage Section without a VALUE clause.
    • MAPNAME - impacts the handling of non-alphabetic characters in the program-name.
    • PROGID-COMMENT - causes Format 1 to be assumed rather than Format 2.

Syntax Rules for All Formats

  1. OSVS VSC2 MF Program-name-1 can be a nonnumeric literal specified with or without enclosing quotation marks. The content of the literal must follow the rules for formation of program-names, but may also contain the characters @, #, and $.
  2. Program-name-1 must not be the same as another user-defined word.

    OSVS MF Program-name-1 can be the same as another user-defined word.

Syntax Rules for Formats1 and 2

  3. OSVS VSC2 The first 8 characters of program-name-1 of a program that is not contained in another program should be unique in the system. The first character must be alphabetic; otherwise it is converted as follows:
    • 1 through 9 are changed to A through I respectively.
    • Anything else is changed to J.

    If a hyphen is used in characters 2 through 8 of program-name-1 in a program that is not contained in another program, it is changed to zero (0).

    The MAPNAME Compiler directive controls this behavior.

    VSC2 For programs that are contained in another program, program-name-1 can be any valid user-defined COBOL word, up to 30 characters long. The first eight characters need not be unique, and they will not be converted as described above. Lower-case letters are valid, but such program-names will be handled in a case-insensitive manner.

  4. ANS85 A program contained within another program must not be assigned the same name as that of any other program contained within the compilation unit that contains this program.

Syntax Rules for Format 2

  5. ANS85 The optional COMMON clause can be used only if the program is contained within another program.
  6. ANS85 If the IS PROGRAM phrase is present, at least one of COMMON or INITIAL

    ISO2002 MF OS390 or RECURSIVE

    must be specified.

  7. ISO2002 Literal-1 must be an alphanumeric literal and must not be a figurative constant.
  8. ISO2002 Literal-1 must not be specified in a program that is contained within another program.
  9. ISO2002 MF The RECURSIVE clause must not be specified if any program that directly or indirectly contains this program is an initial program.
  10. OS390 The RECURSIVE clause must not be specified in a program that is contained within another program.
  11. OS390 The RECURSIVE clause must not be specified in a program that contains another program.

Syntax Rules for Format 4

  12. ISO2002 MF Program-prototype-name-1 identifies the program prototoype. However, literal-1, if specified, is the name of the program prototype that is externalized to the operating environment.

General Rules for Formats 1 and 2

  1. Program-name-1 names the program declared by this program definition and is associated with the object code file pertaining to this program. Literal-1, if specified, is the name of the program that is externalized to the operating environment.

General Rules for Format 2

  2. ANS85 The COMMON clause specifies that the program is common. A common program is contained within another program but can be called from programs other than that containing it.
  3. ANS85 The INITIAL clause specifies that the program is initial. When an initial program is called, it and any programs contained within it are placed in their initial state. See the topic Initial State in the chapter Language Fundamentals.
  4. ISO2002 MF OS390 The RECURSIVE clause specifies that the program is recursive.

    ISO2002 MF Any programs contained within a recursive program are recursive.

    ISO2002 MF OS390 A program in which the Local-Storage Section is specified is recursive.

    A recursive program may be called while it is active and may call itself.

  5. ISO2002 MF OS390 If the RECURSIVE clause is not specified in a program or implied for a program, the program must not be called while it is active.
  6. ISO2002 MF OS390 Additional rules concerning common, initial and recursive programs are given in the topic Common, Initial and Recursive Attributes in the chapter Language Fundamentals

General Rules for Format 3

  7. MF Program-name-1 names the call prototype that will be used during syntax checking to determine the validity and nature of CALL literal statements.
Parent topic: Identification Division
Related reference
Program Identification and Data Names
Related information
Initial State
Common, Initial and Recursive Attributes


The Class-ID Paragraph ()

The Class-ID paragraph indicates that this Identification Division is introducing a class definition and specifies the name that identifies the class and assigns class attributes to the class.

General Format

Directives

  1. In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ACTUAL-PARAMS - specifies the parameters to be used in the creation of a class from a parameterized class or interface.
    • ILSOURCE - specifies a file that contains another program to form part of the current .NET assembly. This may include further components of a partial class .

Syntax Rules

  1. Literal-1 must be an alphanumeric literal and must not be a figurative constant.
  2. Type-specifier-1 must not be the name of the class declared by this class definition.
  3. Type-specifier-1 must not inherit from class-name-1 directly or indirectly.
  4. Type-specifier-1 must not be the name of a class defined with the FINAL clause.
  5. Type-specifier-1 cannot be repeated when you compile a program for .NET. In other words, multiple inheritance is not allowed.
  6. Type-specifier-2 must not refer to the interface.
  7. A given class name must not appear more than once in an INHERITS clause.
  8. If two or more different methods with the same name are inherited, none of them may be specified with the FINAL clause. If the same method is inherited from one superclass through two or more intermediate superclasses, it may be specified with the FINAL clause.
  9. If a given method-name is inherited from more than one inherited class, then, if the prototypes for these methods are such that to define a method with the same interface as any one of them in this class would prevent this class from conforming to all the inherited classes, then a method with the same method-name must be declared in this class. This method must satisfy syntax rule 9 in the topic The Method-ID Paragraph.
    Note: If class A inherits method M from two classes, B and C, and the method interface for M is not identical in classes B and C (say M in B returns an object of class X, and M in C returns an object of an unrelated class Y), then the inheritance is invalid, unless a valid method override of M is defined in class A that resolves the method interface conformance problem. It is not always possible to do so (in which case the inheritance is not valid), but there are some cases in which it can be done. For example, if it is possible to define Z as a class that inherits X and Y, then a method override for M could be specified in class A, returning an object of class Z.
  10. Parameter-name-1 must be a name specified in a class-specifier or an interface-specifier in the Repository paragraph of this class definition.
  11. NET JVM Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. Class-name-1 names the class declared by this class definition. However, literal-1, if specified, is the name of the class that is externalized to the operating environment.
  2. The INHERITS clause specifies the name of the class that is inherited by class-name-1 according to Class inheritance.
  3. If the FINAL clause is specified, the class must not be the superclass for any other class.
  4. NET JVM The PARTIAL phrase specifies that this is a partial class that may be combined with one or more other partial classes with the same externalized name to form a single combined class. This may be combined using the ILSOURCE directive.
  5. NET JVM The USING phrase specifies that this is a parameterized class. Parameter-name-1 is the name given to the formal parameter. See the topic Parameterized Classes in the chapter Language Fundamentals for details of the behavior of a parameterized class.

    When USING is specified for a class that is being compiled for .NET, the resulting class is known as a generic class. Constraints for the parameters may be specified in the Constraints paragraph.

  6. Parameter-name-1 must be specified within this class definition only where a class-name or an interface-name is permitted.
  7. If the same class is inherited more than once, then only one copy of the data for that class is added to class-name-1.
    Note: While the same class cannot be directly inherited more than once, a class may be indirectly inherited multiple times. For example, suppose class D inherits from classes B and C, and classes B and C both inherit from class A. In this example, class D indirectly inherits class A twice, once as a superclass of B, and once as a superclass of C.
  8. NET JVM If STATIC is specified, all methods in a class are static.
Parent topic: Identification Division
Related concepts
Classes
Related reference
Simplified Class Layout
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause
Specifying Type Names
Parameterized Classes


The Factory Paragraph

The Factory paragraph indicates that this Identification Division is introducing a factory definition.

General Format

Note: This syntax is no longer required and is not recommended. It is supported for backward compatibility.

Syntax Rules

  1. Interface-name-1 must be the name of an interface specified in the Repository paragraph of the containing class definition.
  2. Each method prototype in each implemented interface must be such that the factory interface of this class conforms to all implemented interfaces.
  3. FACTORY and STATIC are synonymous.

General Rules

  1. The IMPLEMENTS clause specifies the names of the interfaces that are implemented by the factory object of the containing class according to section Interface Implementation in the chapter Language Fundamentals.
  2. A factory object implements an interface int-1 in the following cases:
    1. The factory object is defined with an IMPLEMENTS clause specifying int-1,
    2. The factory object implements an interface that inherits int-1,
    3. The class containing the factory object inherits a class whose factory object implements int-1.
Parent topic: Identification Division
Related information
Interface Implementation


The Object Paragraph

The Object paragraph indicates that this Identification Division is introducing an object definition.

General Format

Note: This syntax is no longer required and is not recommended. It is supported for backward compatibility.

Syntax Rules

  1. Interface-name-1 must be the name of an interface specified in the Repository paragraph of the containing class definition.
  2. Each method prototype in each implemented interface must be such that the object interface of this class conforms to all implemented interfaces.

General Rules

  1. The IMPLEMENTS clause specifies the names of the interfaces that are implemented by the instance object of the containing class according to section Interface Implementation in the chapter Language Fundamentals.
  2. An instance object implements an interface int-1 in the following cases:
    1. The instance object is defined with an IMPLEMENTS clause specifying int-1.
    2. The instance object implements an interface that inherits int-1.
    3. The class containg the instance object inherits a class whose instance object implements int-1.
Parent topic: Identification Division
Related information
Interface Implementation


Method-ID (COBOL Language Reference)

The Method-ID Paragraph

The Method-ID paragraph indicates that this Identification Division introduces a method definition, specifies the name that identifies the method or method prototype, and assigns method attributes to the method.

General Format

Syntax Rules

  1. Literal-1 must be an alphanumeric literal and must not be a figurative constant.
  2. If property-name-1 is specified as a data-name in the Working-Storage Section of the containing object or factory definition, the PROPERTY clause must not be specified in the data description entry of that data-name.
  3. If the GET phrase is specified, then the method must have no USING phrase parameters specified in the PROCEDURE DIVISION header and must have a single RETURNING phrase.
  4. If the SET phrase is specified, then the method must have a single USING parameter specified in the PROCEDURE DIVISION header and no RETURNING phrase.
  5. If STATIC is specified, the method is a static method. In other words, it is accessed through the class rather than an instance of the class.
  6. The OVERRIDE phrase must not be specified in a method prototype.
  7. If the OVERRIDE phrase is specified, there must be a method with the same name as the method declared by this method definition defined in a superclass. The method in the superclass must not be defined with the FINAL clause.
  8. If the OVERRIDE phrase is not specified:
    1. If this method definition is contained in a class definition, no inherited method may have the same name as the method declared by this method definition
    2. If this method definition is contained in an interface definition, no inherited method prototype may have the same name as the method prototype declared by this method definition.
  9. NET JVM If the REDEFINE phrase is specified, there must be a method with the same name as the method declared by this method definition defined in a superclass.
  10. The FINAL clause must not be specified in a method prototype.
  11. If method-name-1 or literal-1 is the same as a method-name inherited by the containing definition, the parameter declarations and returning item in the PROCEDURE DIVISION header must obey the rules of conformance to ensure that the definition that contains this method definition conforms to every inherited definition according to the section Conformance for Parameters and Returning Items in the chapter Procedure Division.
  12. NET JVM If the ABSTRACT phrase is specified, the ABSTRACT phrase must also be specified in the CLASS-ID paragraph of the containing class.
  13. NET JVM If the ABSTRACT phrase is specified, the Procedure Division of this method must be empty.
  14. NET JVM The ABSTRACT phrase must not be specified in a static method.
  15. NET JVM If the PROTECTED phrase is specified, the ABSTRACT phrase must not be specified.
  16. NET JVM The FOR clause may only be specified for instance methods.
  17. NET JVM Interface-name-1 must be the name of an interface, which is implemented by the current class.
  18. NET JVM This interface must include a method with the same signature as the current method.
  19. NET JVM Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. The name of the method declared by this method definition is determined as follows:
    1. If the PROPERTY clause is specified, the name is formed as follows:
      1. If the GET phrase is specified, the characters "GET" are concatenated to property-name-1 folded to upper case.
      2. If the SET phrase is specified, the characters "SET" are concatenated to property-name-1 folded to upper case.
    2. If the PROPERTY clause is not specified, the name is method-name-1. However, literal-1, if specified, is the name of the method that is externalized to the operating environment.
  2. The OVERRIDE phrase indicates that this method overrides the inherited method.
  3. NET JVM The REDEFINE phrase indicates that this method creates a new method with the same name that hides the parent method. Hiding is the same as overriding the inherited method when an object is described as being of an inherited class, however, when an object is described as being of a particular class, but actually contains an instance of a derived class, the method in the class referenced in the description of the object is executed.
  4. The FINAL clause indicates that this method must not be overridden in any subclasses

    NET JVM , but it can be redefined

    .
  5. The name of this method can be referenced in the invocation of a method for an object of the class in which this method is defined.
  6. If a given user-defined word is defined in the Data Division of this method definition and in the Data Division of the containing factory definition or object definition, the use of that word in this method refers to the declaration in this method. The declaration in the containing factory object or object definition is inaccessible to this method.
  7. If the GET phrase is specified, this method is a get property method for property-name-1.
  8. If the SET phrase is specified, this method is a set property method for property-name-1.
  9. NET JVM If the PUBLIC phrase is specified or implied, this method may be invoked from any runtime element.
  10. NET JVM If the PRIVATE phrase is specified, this method may be invoked only from within the containing class.
  11. NET JVM If the PROTECTED phrase is specified without the INTERNAL phrase, this method may be invoked only from within the containing class or a class that inherits from the containing class.
  12. NET JVM If the PROTECTED phrase is specified with the INTERNAL phrase, this method may be invoked only from within the containing class, a class that inherits from the containing class, or from within the current compilation unit.
  13. NET JVM If the INTERNAL phrase is specified without the PROTECTED phrase, this method may be invoked only from within the current compilation unit.
  14. NET JVM If the ABSTRACT phrase is specified, this method must be overridden in every derived class that is not itself ABSTRACT.
  15. NET JVM The CUSTOM-ATTRIBUTE phrase associates the specified custom attributes with this method.
  16. NET JVM If the FOR clause is specified, this method is an Explicit Interface Member Implementation. The method may not be invoked explicitly. It will be invoked implicitly when the corresponding method is invoked on an instance of this class which has been cast to the interface type.
  17. NET JVM The SYNC modifier locks the values of the arguments sent to the method, so that they do not change while the method is processing.

    When an argument is sent to a method and is received as a reference parameter, the value of the parameter and its corresponding sending argument might be updated. Without the SYNC modifier, the value of the sending argument is unknown, while the method is processing.

    The SYNC modifier on a method is equivalent to wrapping the whole method in a SYNC statement.

  18. NET JVM The EXTENSION keyword indicates that the method is an extension method. You declare extension methods as static methods declared in a static class that is not nested or generic.

    If you specify EXTENSION, you can omit the STATIC keyword. This is because EXTENSION implies STATIC.

    In the method, the first parameter in the USING phrase is the class to extend. It is always a value parameter.

Parent topic: Identification Division
Related concepts
Methods
Related information
Conformance for Parameters and Returning Items
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause
Specifying Type Names
The SYNC Statement


The Interface-ID Paragraph

The Interface-ID paragraph indicates that this Identification Division is introducing an interface definition, specifies the name that identifies the interface and assigns interface attributes to the interface.

General Format

Directives

  1. In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ACTUAL-PARAMS - specifies the parameters to be used in the creation of an interface from a parameterized class or interface

Syntax Rules

  1. Literal-1 must be an alphanumeric literal and must not be a figurative constant.
  2. Type-specifier must not inherit directly or indirectly from interface-name-1.
  3. Type-specifier cannot be repeated when you compile a program for .NET. In other words, multiple inheritance is not allowed.
  4. Parameter-name-1 must be a name specified in a class-specifier or an interface-specifier in the Repository paragraph of this interface definition.
  5. If a given method-name is inherited from more than one interface, the method prototype in each inherited interface must be such that this interface conforms to all inherited interfaces.
  6. NET JVM Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. Interface-name-1 names the interface declared by this interface definition. However, literal-1, if specified, is the name of the interface that is externalized to the operating environment.
  2. The INHERITS phrase specifies the name of the interface that is inherited by interface-name-1 as described in the topic Interface Inheritance in the chapter Language Fundamentals.
  3. NET JVM The USING phrase specifies that this is a parameterized interface. Parameter-name-1 is the name given to the formal parameter.
  4. Parameter-name-1 must be specified within this interface definition only where a class-name or an interface-name is permitted.
Parent topic: Identification Division
Related information
Interface Inheritance
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause
Specifying Type Names


The Function-ID Paragraph

The Function-ID paragraph specifies the name by which a function is identified and assigns selected attributes to that function.

General Format for Format 1 (definition):

General Format for Format 2 (prototype):

Syntax Rules

  1. Literal-1 must be an alphanumeric literal and must not be a figurative constant.

General Rules for Format 1

  1. User-function-name-1 names the function declared by this function definition. However, literal-1, if specified, is the name of the function that is externalized to the operating environment.

General Rules for Format 2

  2. Function-prototype-name-1 names the function prototype declared by this definition. However, literal-1, if specified, is the name of the function prototype that is externalized to the operating environment.
Parent topic: Identification Division


The Date-Compiled Paragraph

The Date-Compiled paragraph provides the date the intermediate code was produced in the Identification Division source program listing.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.
    • DATE - impacts the format in which the date is printed in this paragraph.

Syntax Rules

  1. The comment-entry can be any combination of the characters from the computer's character set. The continuation of the comment entry by use of the hyphen is not permitted; however, the comment entry can be contained on one or more lines. The comment-entry lines must be contained in area B. The next line commencing in area A will begin the next non-comment paragraph.

General Rules

  1. The paragraph-name DATE-COMPILED causes your COBOL system to insert a date comment-entry as the executable code is created. If a Date-Compiled paragraph is present (with or without a comment-entry), the paragraph is replaced in the program listing with one of the form:
     DATE-COMPILED. current-date-and-time .

    where the date and time format is DD-MMM-YY hh:mm .

    The DATE Compiler directive can impact the comment-entry replacement string for your COBOL implementation.

    ANS85 The value inserted in the Date-Compiled paragraph is also the value used in the WHEN-COMPILED intrinsic function. However, the format can differ.

Parent topic: Identification Division


The Delegate-ID Paragraph

The Delegate-ID paragraph indicates that this Identification Division introduces a delegate definition and specifies the name that identifies the delegate.

General Format

Syntax Rules

  1. Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. A delegate is the .NET equivalent of a function pointer, however, a delegate has a well-defined signature.
  2. For a discussion of delegates, see the Delegates section in the Managed Code Concepts section of the Language Fundamentals chapter.
Parent topic: Identification Division
Related reference
Managed Code Concepts
Delegates and Events
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


The Enum-ID Paragraph

The Enum-ID paragraph indicates that this Identification Division introduces a enumeration definition and specifies the name that identifies the enumeration.

General Format

Syntax Rules

  1. An enum program consists only of an optional environment division and a data division.
  2. The environment division, if specified, must include only a repository paragraph and a class-attributes paragraph
  3. The data division must include only a working-storage section which has:
    • an optional 01 level item of type, e.g. BINARY-LONG or BINARY-DOUBLE. The type of this item determines the underlying type of the enum. If no such 01 level item is specified, the underlying type is BINARY-LONG.
    • any number of level 78 items, for which the VALUE clause may be omitted. If the VALUE clause is present, it must specify an integer literal. If omitted, the value is assumed to be 1 if this is the first item, and for subsequent items 1 more than the previous value.
  4. The enum definition may be terminated with END ENUM enumeration-name.
  5. Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. The attributes clause is used to assign any attributes to the enum (for instance the Flags attribute, which indicates that the enum is to be regarded as a set of bit settings).
  2. If a 01 level item is specified, the type of this item determines the underlying type of the enum. If no 01 level item is specified, the underlying type is BINARY-LONG.
  3. Each level 78 item specifies an enum member with the same name and value
  4. In .NET, but not JVM, you need to set the attribute System.FlagsAttribute. This attribute applied to an enum means that the distinct values are to be regarded as bit settings, and can therefore be combined.
Parent topic: Identification Division
Related reference
Enumerations and Enum types
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


The Iterator-ID Paragraph

The Iterator-ID paragraph indicates that this Identification Division introduces an iterator definition and specifies the name that identifies the iterator. Iterator-id can be specified wherever Method-ID can be specified, and can be used to define either static or instance iterators.

General Format

Syntax Rules:

  1. The procedure division header of an Iterator must include a Yielding phrase. The type of the item specified in the Yielding phrase determines the type of the iterators.
  2. Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.

General Rules

  1. For an iterators of type T, the system will automatically generate a nested class which implements both IEnumerable[T] and IEnumerator[T].
  2. The system also generates a method with the name specified in the Iterator-ID paragraph. This method returns an item of the nested type defined in GR 1.
  3. Code outside the context of the iterators may invoke this method to return the iteration object, and iterate through it using the PERFORM THROUGH collection class syntax (see PERFORM statement format 5).
  4. The order in which iteration proceeds is determined by the successive RETURNING values when each EXIT ITERATOR statement is executed.
Parent topic: Identification Division
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


The Operator-ID Paragraph

The Operator-ID paragraph indicates that this Identification Division introduces an operator definition and specifies the symbol or keyword that identifies the operator.

General Format

Syntax Rules

  1. The Operator-ID paragraph may be specified only within a factory definition.
  2. An implicit conversion should only be used when the target type is able to represent all possible values of the source type.
  3. An explicit conversion, which is specified using casting syntax (object-name AS type-name), can be used when there is a possibility of failure.
  4. If a comparison operator is specified, a boolean data item must be specified in the RETURNING phrase of the Procedure Division header.
  5. Except for unary +, unary –, IMPLICIT and EXPLICIT, there must be two formal parameters specified in the USING phrase of the Procedure Division header, at least one of which must be of the class in which this operator is defined.
  6. If IMPLICIT or EXPLICIT is specified, there must be one formal parameter specified in the USING phrase of the Procedure Division header and one data item specified in the RETURNING phrase of that header. Either the formal parameter or the return value must be of the class in which this operator is defined.
  7. Use the extension keyword to extend the operator.
  8. The operator to extend must be declared in a static class.

General Rules

  1. The new meaning for the operator can be anything, but it is a good idea if it is consistent with the normal understanding of the operator.
  2. Overloaded arithmetic expressions can be specified anywhere that a normal arithmetic expression can be specified.
  3. Implicit and explicit conversions give a way of assigning an item of one type to another type, even when neither type inherits, directly or indirectly, from the other.
  4. You can tell if an operator is overloaded by using a class browser such as Reflector, look for factory (static) methods whose names begin with the prefix op_.

Example

To extend types in managed COBOL, use the following construct:

       class-id MyOperatorExtension static.

       operator-id + extension.
       procedure division using by value c1 as type MyClass,
                                         c2 as type MyClass,
                      returning ret as type MyClass.
           set ret to null *> or something more complex
           goback
       end operator.

       end class.
Parent topic: Identification Division
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


The Valuetype-ID Paragraph

The Valuetype-ID paragraph indicates that this Identification Division introduces a valuetype definition and specifies the name that identifies the valuetype.

General Format

Syntax Rules

  1. Within a valuetype definition, the object data must consist only of .NET native types.
  2. The valuetype definition must not include a parameter-less constructor.
  3. Attribute-clause is defined in the topic on the Attribute, Custom-Attribute Clause.
Parent topic: Identification Division
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


Environment Division

  • Configuration Section
    The Configuration Section is located in the Environment Division. The Configuration Section specifies aspects of the data processing system that are dependent on the specific system as well as special control techniques and a means of associating a local name with an external resource.
  • Input-Output Section
    The Input-Output Section deals with the information needed to control transmission and handling of data between external media and a runtime element.
Parent topic: Part 2. Program Definition


General Description

The Environment Division specifies a standard method of expressing those aspects of a data processing problem that are dependent upon the physical characteristics of a specific computer. This division allows specification of the configuration of the compiling computer and the object computer. In addition, information relative to input-output control, special hardware characteristics and control techniques may be given.

ANS85 The Environment Division is optional in a COBOL source element.

General Format

    ENVIRONMENT DIVISION. [configuration-section][input-output-section]

Syntax Rules

  1. MF If the program includes an Environment Division, the Environment Division header is optional only if it is the first division in the program.


Configuration Section

The Configuration Section is located in the Environment Division. The Configuration Section specifies aspects of the data processing system that are dependent on the specific system as well as special control techniques and a means of associating a local name with an external resource.

ANS85 OSVS The Configuration Section is optional .

This section is divided into paragraphs: the Source-Computer paragraph, which describes the computer configuration on which the source element is compiled; the Object-Computer paragraph, which describes the computer configuration on which the runtime module produced by the compiler is to be run; the Special-Names paragraph, which provides a means for specifying the currency symbol and the currency string, choosing the decimal point, specifying symbolic-characters, relating implementor-names to user-specified mnemonic-names, relating alphabet-names to character sets or collating sequences, and relating class-names to sets of characters; the Repository paragraph, which provides a means for associating a local name with an external resource and specifying which intrinsic function names become reserved words for this source unit; and the Constraints paragraph, which provides a means for specifying properties of generic parameters, and therefore allows the use of methods or properties on data items whose type is that generic parameter.

General Format

Syntax Rules

  1. MF The CONFIGURATION SECTION header is optional only if it is the first statement in the program.
  2. ANS85 The Configuration Section must not be stated in a program that is contained within another program.
  3. ISO2002 The Configuration Section must not be stated in a method definition.
  4. ISO2002 The Source-Computer, Object-Computer and Repository paragraphs must not be stated in a factory definition or an object definition.
  5. NET JVM The Constraints paragraph must not be stated in a factory defintion or an object definition.

General Rules

  1. ANS85 The entries explicitly or implicitly stated in the Configuration Section of a source unit that contains other source units apply to each directly or indirectly contained source unit.
Parent topic: Environment Division


The Source-Computer Paragraph

The Source-Computer paragraph identifies the computer on which the compilation unit is to be compiled.

General Format

General Rules

  1. The source-computer-name is documentary only.
  2. The WITH DEBUGGING MODE clause is used to enable debugging code, in accordance with the Standard ANSI COBOL Debug Module. (See the topic The WITH DEBUGGING MODE Clause.)
  3. ISO2002 All clauses of the Source-Computer paragraph apply to the source unit in which they are explicitly or implicitly specified and to any source unit contained within that source unit.
Related information
The WITH DEBUGGING MODE Clause


The Object-Computer Paragraph

The Object-Computer paragraph provides a means of describing the computer on which the runtime module created by the compiler is to be executed.

ANS85 OSVS It is optional.

ANS85 The MEMORY SIZE clause and SEGMENT-LIMIT clause are classed as obsolete elements in the ANSI'85 standard and are scheduled to be deleted from the next full revision of the ANSI standard.

MF All dialects within this COBOL implementation support the MEMORY SIZE clause and SEGMENT-LIMIT clause for documentary purposes only. The FLAGSTD Compiler directive can be used to detect occurrences of this syntax.

XOPEN Although they are part of the standard COBOL definition, the MEMORY SIZE clause and SEGMENT-LIMIT clause are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

  1. Object-computer-name must be one user-defined COBOL word.
  2. ANS85 OSVS The Object-Computer paragraph can consist of only the OBJECT-COMPUTER header.

General Rules

  1. The computer-name provides a means for identifying equipment configuration. The configuration definition contains specific information concerning the memory size. The computer-name and the MEMORY SIZE clause are documentary only.
  2. If the PROGRAM COLLATING SEQUENCE clause is not specified, the native collating sequence is used. The appendix Character Sets and Collating Sequences lists both the full ASCII and EBCDIC collating sequences. Either can be chosen as the native collating sequence by use of the NATIVE Compiler directive.
  3. If the PROGRAM COLLATING SEQUENCE clause is specified, the program collating sequence is the collating sequence associated with the alphabet-name specified in that clause.
  4. The program collating sequence established in the Object-Computer paragraph is used to determine the truth value of any nonnumeric comparisons:
    1. Explicitly specified in relation conditions (see the topic Relation Condition in the chapter Procedure Division).
    2. Explicitly specified in condition-name conditions; see the topic Condition-Name Condition (Conditional Variable) in the chapter Procedure Division.
  5. The PROGRAM COLLATING SEQUENCE clause is also applied to any nonnumeric merge or sort keys unless the COLLATING SEQUENCE phrase of the respective SORT or MERGE statement is specified.
  6. The PROGRAM COLLATING SEQUENCE clause has no effect on the ordering of indexed files.
  7. The PROGRAM COLLATING SEQUENCE clause applies only to the source element in which it is specified

    ANS85 and source elements contained within it

  8. The SEGMENT-LIMIT clause is documentary only. (See the topic Segmentation.)
Related information
Character Sets and Collating Sequences
Relation Condition
Condition-Name Condition (Conditional Variable)
Segmentation


The Special-Names Paragraph

The Special-Names paragraph provides a means for specifying the currency string and the currency symbol, choosing the decimal point,

ANS85 specifying symbolic-characters,

relating implementor-names to user-specified mnemonic-names, relating alphabet-names to character sets or collating sequences, and relating class-names to sets of characters.

MF You can select one of several pre-defined parameter passing conventions. Enhancements to the CALL statement and the PROCEDURE DIVISION header allow these parameter passing conventions to be used in inter-program communication.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ALPHASTART - determines whether valid numeric literals used in the ALPHABET clause can begin with 0 or with 1.
    • CHARSET - impacts which alphabet is considered the native character set. This directive is ignored in some environments.
    • NATIVE - impacts which alphabet is considered the native character set.
    • SYMBSTART - determines whether valid numeric literals used in the SYMBOLIC CHARACTERS clause can begin with 0 or with 1.

Syntax Rules

  1. OSVS VSC2 MF The clauses in the Special-Names paragraph may appear in any order.
  2. ISO2002 At the outer level of a source unit that defines a class, the CURSOR and CRT STATUS clauses must not be specified.
  3. ISO2002 In the factory or object of a class definition, the only clauses that can be specified are the CURSOR and CRT STATUS clauses.
  4. ISO2002 If the Special-Names paragraph is specified in an interface definition, the ALPHABET, CURRENCY and DECIMAL-POINT clauses are the only permitted clauses.
  5. Mnemonic-names can be any COBOL user-defined word. At least one constituent character must be alphabetic.
  6. Function-name refers to a system device or function used by your COBOL system.

    OSVS VSC2 MF Function-name refers to an external switch if its name is one of UPSI-0 through UPSI-7.

  7. If function-name references an external switch

    MF XOPEN or the SWITCH-n is used,

    the associated mnemonic-name cannot be specified anywhere

    MF XOPEN except in the SET statement

    . At least one condition-name should be associated with it.

    ANS85 No condition-name is required.

  8. If function-name does not reference an external switch, the associated mnemonic-name can be specified only in the ACCEPT, DISPLAY, SEND or WRITE statements. A condition-name cannot be associated with such an implementor-name.
  9. The literals specified in the literal phrase of the alphabet-name-1 clause:
    1. If numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.

      The lowest valid values for numeric literals in the ALPHABET clause are sensitive to the ALPHASTART Compiler directive.

    2. If nonnumeric and associated with a THROUGH or ALSO phrase, must each be one character in length.
    3. VSC2 MF Cannot be specified as floating-point literals or DBCS literals.
  10. If the literal phrase of the alphabet-name-1 clause is specified, a given character must not be specified more than once in an alphabet-name clause.
  11. The words THRU and THROUGH are equivalent.
  12. MF The words STANDARD-1 and ASCII are equivalent.
  13. ANS85 The reserved word IS is never required in the Special-Names paragraph.
  14. ANS85 The literals specified in the literal-4 phrase:
    1. If numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.
    2. If nonnumeric and associated with a THROUGH phrase, must each be one character in length.
    3. VSC2 MF Cannot be specified as floating-point or DBCS literals.
  15. ANS85 literal-1, ... literal-5 must not specify a symbolic-character figurative constant.
  16. ANS85 The same symbolic-character-1 must appear only once in a SYMBOLIC CHARACTERS clause.
  17. ANS85 The relationship between each symbolic-character-1 and the corresponding integer-1 is by position in the SYMBOLIC CHARACTERS clause. The first symbolic-character-1 is paired with the first integer-1, the second symbolic- character-1 is paired with the second integer-1; and so on throughout the SYMBOLIC CHARACTERS clause; the division into IS or ARE phrases is documentary only.

    The lowest valid value for integer-1 is sensitive to the SYMBSTART Compiler directive.

  18. ANS85 There must be a one-to-one correspondence between occurrences of symbolic-character-1 and occurrences of integer-1, both within each IS or ARE phrase and within the entire SYMBOLIC CHARACTERS clause.
  19. ANS85 The ordinal position specified by integer-1 must exist in the native character set. If the IN phrase is specified, the ordinal position must exist in the character set named by alphabet-name-2; alphabet-name-2 must be described in an ALPHABET clause.
  20. literal-6 must be an alpnanumeric literal

    MF COB370 or national literal.

  21. literal-6 must not be a figurative constant.
  22. If the PICTURE SYMBOL phrase is not specified, literal-6 must consist of a single character that is not one of the following:
    • digits 0 through 9;
    • alphabetic characters A, B, C, D, L, P, R, S, V, X, Z, or their lower-case equivalents; or the space;
      • MF C and R can be used.
      • ANS85 L can be used.
      • OSVS VSC2 MF E cannot be used.
      • MF COB370 N cannot be used.
      • VSC2 MF G cannot be used.
      • ANS85 no lower-case alphabetic characters can be used.
      • MF lower-case alphabetic characters can be used except for those explicitly prohibited by this rule.
    • characters '+' '-' ',' '.' '*' '/' ';' '(' ')' '"' '='.
  23. ISO2002 MF OS390 If the PICTURE SYMBOL phrase is specified, literal-6 cannot be more than 32 bytes in length and:
    1. must contain at least one nonspace character and
    2. may consist of any characters from the computer's coded character set except for the digits 0 through 9 and the characters '+' '-' ',' '.' '*'.
  24. ISO2002 MF OS390 Literal-7 must be an alphanumeric literal consisting of a single character. It must not be a figurative constant. No two occurrences of literal-7 may be the same value.
  25. ISO2002 MF OS390 Literal-7 may be any character from the computer's coded character set except for the following:
    • digits 0 through 9;
    • alphabetic characters A, B, C, D, E, N, P, R, S, V, X, Z, or their lower-case equivalents; or the space;
      • MF C and R can be used.
      • MF G cannot be used.
    • characters '+' '-' ',' '.' '*' '/' ';' '(' ')' '"' '='.
  26. If literal-6 is of class alphanumeric, the associated currency symbol may be used only to define a numeric-edited item with usage display.

    ISO2002 MF OS390 If literal-6 is of class national, the associated currency symbol may be used only to define a numeric-edited item with usage national.

  27. MF Integer-2 must be an unsigned integer in the range 0 to 65535.
  28. MF XOPEN Data-name-1 of the CURSOR IS clause must be declared in the Working-Storage Section .
  29. MF XOPEN The CRT STATUS clause specifies a data item into which a status value is moved after each Format 4

    MF or Format 5

    ACCEPT statement. In some environments, it can be defined only in the first 64K of working storage.

  30. MF XOPEN Data-name-2 must be described in the Working-Storage Section and must be three bytes long.
  31. MF XOPEN The CURSOR IS clause specifies the data item to contain the cursor address as used by the ACCEPT statement.

General Rules

  1. External switches are set at run time by the operator, and the setting can be determined by testing the associated condition-names.
  2. If mnemonic-name is associated with an external switch, the status of that switch can be altered by execution of a Format 1 SET statement (see the topic The SET Statement).
  3. The alphabet-name-1 clause provides a means for relating a name to a specified character code set and/or collating sequence. When alphabet-name-1 is referenced in the PROGRAM COLLATING SEQUENCE clause (see the topic The Object-Computer Paragraph) or the COLLATING SEQUENCE phrase of a SORT or MERGE statement (see the topic The SORT Statement or The MERGE Statement), the alphabet-name-1 clause specifies a collating sequence. When alphabet-name-1 is referenced in a CODE-SET clause in a file description entry (see the topic File Description Entry Skeleton), the alphabet-name clause specifies a character code set.
    1. If the STANDARD-1

      MF or ASCII

      phrase is specified, the character code set or collating sequence identified is the American Standard Code for Information Interchange, as defined in American National Standard X3.4-1968.

      ANS85 If the STANDARD-2 phrase is specified, the character code set identified is the International Reference Version of the ISO 7-bit code, as defined in International Standard 646, 7-bit Coded Character Set for Information Processing Interchange.

      VSC2 MF XOPEN If the EBCDIC phrase is specified, the character code set or collating sequence identified is EBCDIC.

      If the NATIVE phrase is specified, the native character code set or native collating sequence is used. The native collating sequence is either ASCII or EBCDIC, as specified by the NATIVE Compiler directive.)

      See the appendix Character Sets and Collating Sequences for details of the ASCII code set and the ASCII and EBCDIC collating sequences and their correspondence.

    2. If the literal phrase is specified, alphabet-name-1 cannot be referenced in a CODE-SET clause (see the topic The CODE-SET Clause). The character code set and/or collating sequence identified is that defined according to the following rules:
      1. The value of each literal specifies:
        1. The ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.
        2. The actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal, starting with the leftmost character, is assigned successive ascending positions in the collating sequence being specified.
      2. The order in which the literals appear in the ALPHABET clause specifies, in ascending sequence, the ordinal number of the character within the collating sequence being specified.
      3. Any characters within the native collating sequence which are not explicitly specified in the literal phrase, assume a position, in the collating sequence being specified, greater than any of the explicitly specified characters. The relative order within the set of these unspecified characters is unchanged from the native collating sequence.
      4. If a character code set is being specified, for each character within the native character set that is not specified by the literal-1 phrase, the implementor defines the ordinal number within the character code set being specified.
      5. If the THROUGH phrase is specified, the set of contiguous characters in the native character set, beginning with the character specified by the value of literal-1, and ending with the character specified by the value of literal-2, is assigned a successive ascending position in the collating sequence being specified. In addition, the set of contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in either ascending or descending sequence.
      6. If the ALSO phrase is specified, the characters of the native character set specified by the value of literal-1, and literal-3 are assigned to the same position in the collating sequence being specified

        ANS85 , or in the character code set that is used to represent the data

  4. The character that has the highest ordinal position in the program collating sequence is associated with the figurative constant HIGH-VALUE

    ANS85 except when this figurative constant is specified as a literal in the Special-Names paragraph

    .

    If more than one character has the highest position in the program collating sequence, the last character specified is associated with the figurative constant HIGH-VALUE.

  5. The character that has the lowest ordinal position in the program collating sequence is associated with the figurative constant LOW-VALUE

    ANS85 except when this figurative constant is specified as a literal in the Special-Names paragraph

    .

    If more than one character has the lowest position in the program collating sequence, the first character specified is associated with the figurative constant LOW-VALUE.

  6. OSVS VSC2 MF Floating-point literals cannot be used in a user-specified collating sequence.
  7. ANS85 When specified as literals in the Special-Names paragraph, the figurative constants HIGH-VALUE and LOW-VALUE are associated with those characters having the highest and lowest positions, respectively, in the native collating sequence.
  8. ANS85 The SYMBOLIC CHARACTERS clause is used to define user-defined words that can be used like figurative constants. If the IN phrase is not specified, symbolic-character-1 represents the character whose ordinal position in the native character set is specified by integer-1. If the IN phrase is specified, integer-1 specifies the ordinal position of the character that is represented in the character set named by alphabet-name-2.
  9. ANS85 The internal representation of symbolic-character-1 is the internal representation of the character that is represented in the native character set.
  10. The CURRENCY SIGN clause is used to specify a currency string that is placed into numeric-edited data items when they are used as receiving items and de-edited from the data item when it is used as a sending item that has a numeric or numeric-edited receiving item. In addition, it is used to determine which symbol is used in a character-string of a basic format PICTURE clause to specify the presence of this currency string. This symbol is referred to as the currency symbol.

    Literal-6 represents the value of the currency string.

    ISO2002 MF OS390 If the CURRENCY SIGN clause is specified with the PICTURE SYMBOL phrase, literal-7 is used as the currency symbol.

    If the CURRENCY SIGN clause is specified without the PICTURE SYMBOL phrase, literal-6 is used as the currency symbol.

    If the currency symbol is a lower-case letter, it is treated as its upper-case equivalent.

    If this clause is not present, only the currency sign defined in the COBOL character set is used in the PICTURE clause. See the section Character Set in the chapter Concepts of the COBOL Language.

  11. The DECIMAL-POINT IS COMMA clause means that the function of comma and period are exchanged in the character-string of the PICTURE clause and in numeric literals.
  12. MF If the NUMERIC SIGN clause is specified, the default for signed numeric items is for the sign to be stored as described for the corresponding SIGN clause in data description entries. The NUMERIC SIGN clause can be overridden by a SIGN clause in a specific data description entry.
  13. OSVS VSC2 MF Wherever a mnemonic-name is allowed, you can use a function-name.
  14. If function-name does not reference an external switch, it can be selected from the following list:
    TAB | Skip to vertical tabulation position (inserts ASCII X"0B" in the output record as appropriate) | WRITE ADVANCING statement
    PRINTER | Printer | DISPLAY statement
    FORMFEED | Skip to new page (inserts ASCII X"0C" in the output record as appropriate) | WRITE ADVANCING statement
    COMMAND-LINE | Command transfer | ACCEPT and DISPLAY statements
    ARGUMENT-NUMBER | Command-line argument number | ACCEPT and DISPLAY statements
    ARGUMENT-VALUE | Command-line argument value | ACCEPT statement
    ENVIRONMENT-NAME | Environment variable name | DISPLAY statement
    ENVIRONMENT-VALUE | Environment variable value | ACCEPT and DISPLAY statements
    SYSERR | Standard error device | DISPLAY statement

    OSVS VSC2 The following table reflects the support for function names offered by OS/VS COBOL, VS COBOL II and SAA in this COBOL system.

    Table 1. FunctionNames Support
    OSVS | VSC2 Rel (2) | COBOL/370 or VSC2 Rel (3)/(4) | SAA L1
    SYSIN | y | y | y | y
    SYSIPT | U | U | y
    SYSOUT | y | y | y | y
    SYSLIST | y
    SYSLST | U | U | y
    SYSPCH | U | U | y
    SYSPUNCH | U | y | y
    CONSOLE | y | y | y | y
    C01 | y | y | y | y
    C02 | y | y | y
    C03 | y | y | y
    C04 | y | y | y
    C05 | y | y | y
    C06 | y | y | y
    C07 | y | y | y
    C08 | y | y | y
    C09 | y | y | y
    C10 | y | y | y
    C11 | y | y | y
    C12 | y | y | y
    S01 | y | y | y
    S02 | y | y | y
    S03 | U | y
    S04 | U | y
    S05 | U | y
    CSP | y | y | y | y
    1 char rw literal | y
    AFP-5A | y
    Key:
    y
    Documented and accepted by mainframe compilers and the COBOL system.
    U
    Undocumented but accepted by mainframe compiler.
  15. ANS85 The CLASS clause provides a means for relating a name to the specified set of characters listed in that clause. Class-name-1 can be referenced only in a class condition. The characters specified by the values of the literals in this clause define the exclusive set of characters which constitute class-name-1. The value of each literal specifies:
    1. The ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.
    2. The actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal is included in the set of characters identified by class-name-1.

    If the THROUGH phrase is specified, the contiguous characters in the native character set beginning with the character specified by the value of literal-4, and ending with the character specified by the value of literal-5, are included in the set of characters identified by class-name-1. Additionally, the contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in ascending or descending sequence.

  16. All clauses specified in the Special-Names paragraph for a source element also apply to source elements contained within that source element. The condition-names, mnemonic-names, class-names, currency symbols, alphabet-names and symbolic-characters specified in the containing source element's Special-Names paragraph can be referenced from any contained source element.
  17. MF The CALL-CONVENTION clause allows you to select one of several pre-defined parameter-passing conventions which allow you to CALL subprograms written in languages other than COBOL, and which use different parameter passing conventions.
  18. MF The CONSOLE IS CRT clause causes any ACCEPT or DISPLAY statement whose operand is not a screen-name, and that has no phrases specific to a particular format, to be treated as Format 5. If the CONSOLE IS CRT clause is not present, these statements are treated as the standard ANSI ACCEPT or DISPLAY.
  19. MF XOPEN The CURSOR IS clause specifies the data item to contain the cursor address used by the ACCEPT statement.
    1. At the start of an ACCEPT statement, if data-name-1 contains a value that is a valid character position on the screen, that position is used as the initial position for the cursor. Otherwise, data-name-1 is ignored, and the initial position for the cursor is the start of the first input field on the screen. At the end of an ACCEPT statement, if the position in data-name-1 has been used in that statement, data-name-1 is updated to show the position of the cursor at the termination of the ACCEPT statement.
    2. CURSOR IS has no effect on the positioning of fields on the screen.
    3. Data-name-1 must be 4 or 6 characters in length. If data-name-1 is 4 characters in length, the first two characters are interpreted as line number, and the second two as column number. If data-name-1 is 6 characters in length, the first three characters are interpreted as line number, and the second three as column number.
    4. The clause has no effect if data-name-1 contains an illegal position (for example, zeros, a nonnumeric value, or a value that is beyond the bottom of the screen).
    5. If data-name-1 contains a valid position that does not correspond to an input field being accepted by the current ACCEPT statement, the cursor is positioned to the next such field or, if there is none, to the first such field. The ordering of the fields is the order in which their descriptions appear in the Data Division.
  20. MF XOPEN The CRT STATUS clause specifies a 3-byte data item, into which a status value is moved after each Format 4 or Format 5 ACCEPT statement.

    If the CRT STATUS clause is specified in the Special-Names paragraph, every Format 4 or 5 ACCEPT statement (as described later in this chapter) places a value into data-name-2 to indicate the outcome of the ACCEPT operation. Data-name-2 consists of status keys which are set to indicate possible conditions resulting from the completion of the operation. They are described below.

  21. ANS85 MF xml-schema-name-1 specifies a name that can then be used in the VALIDATING phrase of the XML PARSE statement. If the compile option ASSIGN(DYNAMIC) is set then literal-8 or data-name-3 specifies the filename of an XML schema in text format. If ASSIGN(EXTERNAL) is set then use external-file-reference-1 to identify the schema by mapping to an external environment name.

CRT status key CRT Status Keys

CRT Status Key 1: The first byte of data-name-1 is CRT Status Key 1. It should be described as PICTURE 9 USAGE DISPLAY. It indicates the condition that caused the termination of the ACCEPT operation. The possible values are:

"0" | indicates a terminator key or auto-skip out of the final field
"1" | indicates a user-defined function key
"2" | indicates a COBOL system-defined function key
"9" | indicates an error

A terminator key is a key whose purpose is terminating ACCEPT operations (for example, Enter). A particular configuration option causes the field-tab key, when used in the final field of an ACCEPT, to act as a terminator key. Defining function keys is also a configuration option.

A termination that returns a value of "0" is called a normal termination.

If the ACCEPT statement contains an ON EXCEPTION phrase, any value in CRT Status Key 1, except " 0", causes the execution of the imperative statement in that phrase.

CRT Status Key 2: The second byte of data-name-1 is CRT Status Key 2 and contains a code giving further details of the condition that terminated the ACCEPT operation. Its format and possible values depend on the value in CRT Status Key 1, as shown in the following table.

Table 2. Valid Combinationsof CRT Status Keys 1 and 2
Key 1 | Key 2 | Meaning
0 | Format: PIC 9 DISPLAY Value: 0 | The operator pressed a terminator key
0 | Format: PIC 9 DISPLAY Value: 1 | Auto-skip out of the last field
1 | Format: PIC 99 COMP Values: 0-127 | The function key number
2 | Format: PIC 99 COMP Values: 0-26 | The function key number
9 | Format: PIC 99 COMP Value: 0 | No items fall within the screen

See your COBOL system documentation on screen handling and user interfaces for an explanation of function key numbers.

CRT Status Key 3: The third byte of data-name-1 is CRT Status Key 3 and should be described as PICTURE 99 COMP-X or as PICTURE 99 COMP (with the NOIBMCOMP directive specified). If CRT Status Key 1 and CRT Status Key 2 are zero, then CRT Status Key 3 contains the raw keyboard code for the key that terminated the ACCEPT operation. Otherwise, the contents of CRT Status Key 3 are undefined.

Where a sequence of keystrokes rather than a single key has been configured to perform a single function, only the code for the first keystroke is returned.

Examples:

  1. An example of using the CRT status key fields is provided in the topic CRT STATUS Clause of the Special-Names Paragraph.
Related concepts
Character Set


The Repository Paragraph

The Repository paragraph allows specification of program-prototypes-names, function-prototype-names, class-names, delegate-names, enum-names, interface-names and property-names that may be used within the scope of this Environment Division. It also allows declaration of intrinsic-function-names that may be used without specifying the word FUNCTION.

General Format

Note: With the exception of function-specifier, references to the following specifiers can now be made without the need to specify them in the REPOSITORY paragraph, by using the TYPE external-type-name syntax . The specifiers are listed here for backward compatibility.

Directives

  1. In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • REPOSITORY - Creates a repository file or requests that the program being compiled is checked against the repository file.
    • RDFPATH - specifies the location of the library for the repository files.
    • ACTUAL-PARAMS - specifies the parameters to be used in the creation of a class or interface from a parameterized class or interface
    Note: None of these directives are applicable to managed COBOL.

Syntax Rules

  1. If any class-name-1, delegate-name-1, enum-name-1, interface-name-2, function-prototype-name-2, intrinsic-function-name-1, property-name-1 or program-prototype-name-1 is specified more than once in the Repository paragraph, all the specifications for that name must be identical.
  2. Literal-1, literal-2, literal-3, literal-4, literal-5, literal-6 and literal-7 must be nonnumeric literals and must not be figurative constants.
  3. If the CLASS clause is specified, class-name-2, class-name-3, and interface-name-1 must be:
    1. Parameters of a containing class definition or interface definition; or
    2. Defined in the same Repository paragraph where class-name-1 is defined.
  4. If class-name-1 is specified in the USING phrase of the Class-ID paragraph of a class definition containing this Repository paragraph or in the USING phrase of the Interface-ID paragraph of an interface definition containing this Repository paragraph, the EXPANDS phrase must not be specified.
  5. If the INTERFACE clause is specified, class-name-4, interface-name-3 and interface-name-4 must be:
    1. Parameters of a containing class definition or interface definition; or
    2. Defined in the same repository paragraph where interface-name-2 is defined.
  6. If interface-name-2 is specified in the USING phrase of the Class-ID paragraph of a class definition containing this Repository paragraph or in the USING phrase of the Interface-ID paragraph of an interface definition containing this Repository paragraph, the EXPANDS phrase must not be specified.
  7. Either program-prototype-name-1 must be the name of a program prototype or a program definition specified previously in this compilation group or:
    1. If literal-3 is not specified, there must be information in the external repository for the program program-prototype-name-1,
    2. If literal-3 is specified, there must be information in the external repository for the program literal-3.
  8. Either function-prototype-name-1 must be the name of a function prototype or a function definition specified previously in this compilation group or:
    1. If literal-5 is not specified, there must be information in the external repository for the function function-prototype-name-1,
    2. If literal-5 is specified, there must be information in the external repository for the function literal-5.
  9. Intrinsic-function-name-1 must not be specified as a user-defined word within the scope of this Repository paragraph.
  10. If ALL is specified in the intrinsic format of the function-specifier, none of the names of the intrinsic functions can be specified as a user-defined word within the scope of the Repository paragraph.
  11. If the specified class-name-1 is the name of the class definition in which this Repository paragraph is specified, references to class-name-1 are to that class definition and this class-specifier is ignored.
  12. If the specified interface-name-2 is the name of the interface definition in which this Repository paragraph is specified, references to interface-name-2 are to that interface definition and this interface-specifier is ignored.
  13. If the specified program-prototype-name-1 is the name of the program definition in which this Repository paragraph is specified or the name of a containing program, references to program-prototype-name-1 are to the named program definition and this program-specifier is ignored.
  14. If the specified function-prototype-name-1 is the name of the function definition in which this Repository paragraph is specified, references to function-prototype-name-1 are to that function definition and this function-specifier is ignored.
  15. NET If the specified delegate-name-1 is the name of the delegate definition in which this Repository paragraph is specified, references to delegate-name-1 are to that delegate definition and this delegate-specifier is ignored.
  16. NET JVM If the specified enum-name-1 is the name of the enumeration definition in which this Repository paragraph is specified, references to enum-name-1 are to that enumeration definition and this enum-specifier is ignored.
  17. If the CLASS clause is specified:
    1. If literal-1 is specified, there must be information in the external repository for the class literal-1.
    2. If literal-1 is not specified, there must be information in the external repository for the class class-name-1.
  18. If the INTERFACE clause is specified:
    1. If literal-2 is specified, there must be information in the external repository for the interface literal-2.
    2. If literal-2 is not specified, there must be information in the external repository for the interface interface-name-2.
  19. If the PROPERTY clause is specified:
    1. If literal-4 is specified, there must be information in the external repository for the property literal-4 that is part of one of the classes or interfaces that are declared in this Repository paragraph.
    2. If literal-4 is not specified, there must be information in the external repository for the property property-name-1 that is part of one of the classes or interfaces that are declared in this Repository paragraph.
  20. NET If the DELEGATE clause is specified:
    1. If literal-6 is specified, there must be information in the external repository for the delegate definition literal-6.
    2. If literal-6 is not specified, there must be information in the external repository for the delegate definition literal-6.
  21. NET JVM If the ENUM clause is specified:
    1. If literal-7 is specified, there must be information in the external repository for the enumeration definition literal-7.
    2. If literal-7 is not specified, there must be information in the external repository for the enumeration definition literal-7.

General Rules

  1. Class-name-1 is the name of a class that may be used throughout the scope of the containing Environment Division.
  2. If the AS phrase is specified, literal-1, literal-2, literal-3, literal-5 or literal-6 is the name by which the class, interface, program, function or delegate respectively, is known to the operating environment. Literal-4 is the name known to the operating environment for a method that implements the named property. The AS phrase is required when the name of a class, interface, property, function or delegate does not follow the rules for formation of a user-defined word or when the name is case specific.
  3. Class-name-3 and interface-name-1 are actual parameters for the parameterized class referenced by class-name-2.
  4. Class-name-4 and interface-name-4 are actual parameters for the parameterized interface referenced by interface-name-3.
  5. If the EXPANDS phrase is specified in a class-specifier, a class class-name-1 is created from the parameterized class class-name-2. The number of parameters in the USING phrase of the EXPANDS phrase of the class-specifier must be the same as the number of parameters in the USING phrase of the CLASS-ID paragraph of class-name-2. The interface for class-name-1 is the interface specified for class-name-2 with the parameters of class-name-2 replaced by the parameters specified in the class-specifier.

    The class class-name-1 is created from the parameterized class class-name-2 by replacing each specification of the formal parameter by the corresponding actual parameter. This replacement is done after the processing of COPY and REPLACE statements.

  6. The compiler uses the information specified for class-name-1 together with the external repository to determine the details of the class that is to be used. The repository information for the class must be in a file whose name is the externalized name of the class with the extension rdf. If the RDFPATH directive is specified, the file must be in the specified directory; otherwise, the file must be in the local directory where the .int and .idy files will be created.
  7. Interface-name-2 is the name of an interface that may be used throughout the scope of the containing Environment Division.
  8. If the EXPANDS phrase is specified in an interface-specifier, an interface interface-name-2 is created from the parameterized interface interface-name-3. The number of parameters in the USING phrase of the EXPANDS phrase of the interface-specifier must be the same as the number of parameters in the USING phrase of the INTERFACE-ID paragraph of interface-name-3. The interface for interface-name-2 is the interface specified for interface-name-3 with the parameters of interface-name-3 replaced by the parameters specified in the interface-specifier.

    The interface interface-name-2 is created from the parameterized interface interface-name-3 by replacing each specification of the formal parameter by the corresponding actual parameter. This replacement is done after the processing of COPY and REPLACE statements.

  9. The compiler uses the information specified for interface-name-2 together with the external repository to determine the details of the interface that is to be used. The repository information for the interface must be in a file whose name is the externalized name of the interface with the extension rdf. If the RDFPATH directive is specified, the file must be in the specified directory; otherwise, the file must be in the local directory where the .int and .idy files will be created.
  10. Property-name-1 is the name of an object property that may be used throughout the scope of the containing Environment Division.
  11. Program-prototype-name-1 is the name of a program prototype that may be used throughout the scope of the containing Environment Division.
  12. NET Delegate-name-1 is the name of a delegate definition that may be used throughout the scope of the containing Environment Division.
  13. Format 2 of the function-specifier is documentary only.
  14. Intrinsic-function-name-1 may be specified in a function-identifier without being preceded by the word FUNCTION.
  15. If ALL is specified in the intrinsic format of the function-specifier, it is as if each of the intrinsic-function-names defined in the topic Intrinsic Functions were specified.
  16. NET JVM Enum-name-1 is the name of an enumeration definition that may be used throughout the scope of the containing Environment Division.
  17. If a prototype definition or a program definition for program-prototype-name-1 is specified previously in this compilation group, that definition is used to determine the details for activating the program identified by program-prototoype-name-1. Otherwise, the external repository is used to determine the details for activating the program with the externalized name program-prototype-name-1 and that program is activated when program-prototype-name-1 is referenced.
  18. Function-prototype-name-1 is the name of a function prototype that may be used throughout the scope of the containing Environment Division.
  19. If a prototype definition or a function definition for function-prototype-name-1 is specified previously in this compilation group, that definition is used to determine the details for activating the function identified by function-prototoype-name-1. Otherwise, the external repository is used to determine the details for activating the function with the externalized name function-prototype-name-1 and that function is activated when function-prototype-name-1 is referenced.
Related information
Intrinsic Functions


The Constraints Paragraph

The Constraints paragraph allows specification of properties of parameters of a parameterized class, and therefore allows the use of methods or properties on data items whose type is specified as that parameter.

General Format

Syntax Rules

  1. Parameter-name-1 must be a parameter of the class in which this Constraints paragraph is specified.

General Rules

  1. If the IMPLEMENTS phrase is specified, parameter-name-1 must be of a class that implements the interface interface-name-1.
  2. If the INHERITS phrase is specified, parameter-name-1 must inherit directly or indirectly from class-name-1.
  3. If the NEWABLE phrase is specified, the class of parameter-name-1 must include a constructor with no parameters.
  4. If VALUE TYPE or VALUETYPE is specified, the type of parameter-name-1 must be a value type. If REFERENCE TYPE is specified, the type of parameter-name-1 must be a reference type.
  5. Items whose type is specified as parameter-name-1 may be specified where an item of class class-name-1 or interface-name-1 is required.
  6. Items whose type is specified as parameter-name-1 have all the methods and properties of a class-name-1 and interface-name-1


The Class-Attributes Paragraph

The Class-Attributes paragraph allows specification of attributes on a class, delegate, enum, interface or valuetype.

General Format

Note: This syntax is no longer required and is not recommended. It is supported for backward compatibility. Use the attribute clause instead.
    CLASS-ATTRIBUTES. [ Attribute-Clause ] ... .

Syntax Rules

  1. The Attribute-Clause is described in the topic The Attribute Custom-Attribute Clause.

General Rules

  1. The attribute specified becomes part of the metadata describing the source element in which this clause appears and is visible to a reflector.
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


The Assembly-Attributes Paragraph

The Assembly-Attributes paragraph allows specification of custom-attributes for the entire compilation unit.

General Format

    ASSEMBLY-ATTRIBUTES. [ Attribute-Clause ] ... .

Syntax Rules

  1. The Attribute-Clause is described in the topic The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause.

General Rules

  1. The attribute specified becomes part of the metadata describing the compilation unit in which this clause appears and is visible to a reflector.
Related information
The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause


Input-Output Section

The Input-Output Section deals with the information needed to control transmission and handling of data between external media and a runtime element.

General Format

   INPUT-OUTPUT SECTION.[ file-control-paragraph ][ i-o-control-paragraph ]

Syntax Rules

  1. ISO2002 The Input-Output Section can be specified in a program definition or a function definition. Within a class definition, the Input-Output Section can be specified only in a factory definition or an object definition, but not in a method definition. The Input-Output Section must not be specified within an interface definition.
Parent topic: Environment Division


The File-Control Paragraph

The File-Control paragraph names each file and allows specification of other file-related information.

General Format


SELECT statement (COBOL File Control Entry)

The File Control Entry

The file control entry names a file and can specify other file-related information.

XOPEN Although they are a part of the standard COBOL definition, the RECORD DELIMITER and RESERVE phrases and ellipses in the ASSIGN clause are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative Files)

General Formats for Format 4 (Indexed Files)

General Formats for Format 5 (Sort-Merge Files)

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ASSIGN - determines how the literal, data-name, or external-file-reference is evaluated.
    • SEQUENTIAL - determines whether files defined as ORGANIZATION IS SEQUENTIAL are considered LINE SEQUENTIAL or RECORD SEQUENTIAL.

Syntax Rules for All Formats (All Files)

  1. The SELECT clause must be specified first in the file control entry. The clauses which follow the SELECT clause can appear in any order.
  2. Each file described in the Data Division must be named once, and only once, as file-name in the File-Control paragraph. Each file specified in the file control entry must have a file description entry in the Data Division of the same factory, method, object, function or program.
  3. If the ACCESS MODE clause is not specified, the ACCESS MODE IS SEQUENTIAL clause is implied.
  4. MF Data-name-1 can be declared in the Data Division as an alphanumeric or group data item long enough to hold the external name of the file. If it is not explicitly declared within the source element, your COBOL system declares it implicitly as an alphanumeric data item long enough to hold the maximum permissible size of file-name. If data-name-1 occurs in the FROM phrase, the data item must be explicitly declared in the Data Division.
  5. MF The NOT OPTIONAL phrase has effect only when the file is opened input-output.
  6. MF External-file-reference, data-name-1, or literal-1 specifies the external name of the file. If the EXTERNAL or DYNAMIC option is used, literal-1 must not be specified. If the DYNAMIC option is used, the word specified for the external file-name is interpreted as external-file-reference.
  7. Data-name-2 must be defined in the Data Division as a two-character, alphanumeric data item

    OSVS VSC2 MF or a two-character numeric data item with USAGE DISPLAY

    and must not be defined in the File Section

    MF or Local-Storage Section

    of the Data Division.

  8. VSC2 Data-name-3 must be defined as a group item of 6 bytes in the Working-Storage or Linkage Section of the Data Division.
  9. OSVS VSC2 Data-name-4 must be defined in the Working-Storage Section as an alphanumeric data item.
  10. All data-names can be qualified.

Syntax Rules for Format 1 (Record Sequential Files only)

  11. ANS85 Literal-2 must be a one-character nonnumeric literal.
  12. ANS85 Data-name-5 can be qualified. It must be defined in the Data Division as a one-character data item of category alphanumeric. It cannot be defined in the File or Report Sections of the Data Division.

Syntax Rules for Formats 1 and 2 (Record and Line Sequential Files)

  13. When the ORGANIZATION clause is not specified, sequential organization is assumed.
  14. MF KEYBOARD means console input.
  15. MF DISPLAY means console output.
  16. MF PRINTER specifies the system's main printer.
  17. MF PRINTER-1 specifies the system's second printer.
  18. ANS85 Character-string must not be a reserved word, a user-defined word that is defined elsewhere, or a literal.

Syntax Rules for Format 3 (Relative Files)

  19. If a relative file is to be referenced by a START statement, the RELATIVE KEY phrase must be specified for that file.
  20. Data-name-5 must not be defined in a record description entry associated with that file-name.
  21. The data item referenced by data-name-5 must be defined as an unsigned integer.

Syntax Rules for Format 4 (Indexed Files)

  22. ISO2002 MF Split-key-name is a concatenation of one or more data items within a record associated with that file-name. It can be referenced only in START and READ statements.
  23. The data items referenced by data-name-5 and data-name-8

    MF and any data-names referenced by split-key-name-1 and split-key-name-2

    must be defined within a record description entry associated with the file-name.

    OSVS VSC2 MF Any of these data items can be defined as any supported data category. However, the key is still treated as an alphanumeric item for the input and output statements against the file named in the SELECT clause.

  24. Data-name-5 and data-name-8

    MF and any data-names referenced by split-key-name-1 and split-key-name-2

    cannot describe an item whose size is variable. See the topic The OCCURS Clause.

  25. Data-name-8 cannot reference an item whose leftmost character position corresponds to the leftmost character position of the item referenced by data-name-5 or by another data-name-8 specified for the same file.
  26. If the indexed file contains variable-length records, data-name-5 and data-name-8

    and any data-names referenced by split-key-name-1 and split-key-name-2

    shallbe contained within the first x bytes of the record, where x equals the minimum record size specified for the file. See the topic The RECORD Clause.
  27. OSVS VSC2 If the PASSWORD clause is specified, it must immediately follow its associated RECORD KEY or ALTERNATE RECORD KEY clause.
  28. When the DIALECT"RM" or DIALECT"ACU" directives are in effect, the data-names specified in the RECORD KEY or ALTERNATE RECORD KEY clauses are implicitly qualified by the file-name-1 specified in the SELECT clause when file-name-1 is not already specified as the final qualifier of the data-name. For any other dialect, the data-names may need to explicitly specify file-name-1 as the final qualifier to satisfy uniqueness of reference rules.

Syntax Rules for Format 5 (Sort-Merge Files)

  29. Each sort or merge file described in the Data Division must be named once and once only as file-name in the File-Control paragraph. Each sort or merge file specified in the file control entry must have a sort-merge file description entry in the Data Division.
  30. Since file-name represents a sort or merge file, only the ASSIGN clause is permitted to follow file-name in the File-Control paragraph.

General Rules for All Formats (All Files)

  1. The ASSIGN clause specifies the association of the file referenced by file-name-1 to a storage medium. The first assignment takes effect.

    OSVS VSC2 MF Subsequent assignments within any one ASSIGN clause are documentary only.

  2. The RESERVE clause allows you to specify the required number of input-output areas.

    ANS85 The RESERVE clause is documentary only, unless the COBOL system documentation specific to your operating system indicates otherwise.

  3. The ORGANIZATION clause specifies the logical structure of a file. The file organization is established at the time a file is created and cannot subsequently be changed.
  4. When the FILE STATUS clause is specified, a value is moved by the run-time system into the data item specified by data-name-2 after the execution of every statement that references that file either explicitly or implicitly. This value indicates the status of execution of the statement. (See the topic I-O Status in the chapter Procedure Division.)

    MF Data-name-3, if specified, is documentary only.

  5. MF The PASSWORD clause is documentary only.
  6. MF Use of the reserved word DYNAMIC in an ASSIGN clause indicates that the value of literal-1 or data-name-1 in that ASSIGN clause is the specified file's name in the external file-storage environment.
  7. MF Use of the reserved word EXTERNAL in an ASSIGN clause indicates that external-file-reference identifies the specified file to the external environment for possible further mapping to an external file-storage environment-name. (See your COBOL system documentation on file handling for details on setting up external-file-name for your particular operating environment.)

    If external-file-reference contains the character "-", then only that part of the name following the last "-" is used to identify the file to the external environment.

  8. MF The DISK option without external-file-reference, data-name-1 or literal-1 and without the FROM option, specifies a disk file whose name is given in a VALUE OF FILE-ID clause in the file description for the file. If that file description contains no VALUE OF FILE-ID clause, the name of the disk file is assumed to be the same as file-name-1 (known as the internal file-name).
  9. MF If any of the keywords DISK, KEYBOARD, DISPLAY, PRINTER or PRINTER-1 are followed by external-file-reference, data-name-1 or literal-1, that keyword is ignored.
  10. MF The DISK option with the FROM option specifies a disk file whose name on the disk is the value of data-name-1. However, if when an OPEN statement is executed for that file, data-name-1 contains all spaces, the name of the disk file is assumed to be the same as file-name-1 (known as the internal-file-name).
  11. The OPTIONAL phrase applies only to files opened in the INPUT, I-O or EXTEND mode. Its specification is required for files that are not necessarily present each time the runtime element is executed.
  12. ISO2002 MF The SHARING clause specifies the sharing mode to be used for the file unless it is overridden by the SHARING phrase of the OPEN statement. This clause also specifies whether record locks have an effect. Additional details are specified in the topic Sharing Mode in the chapter Language Fundamentals.

General Rules for Formats 1, 3 and 4 (Record Sequential, Relative and Indexed files)

  13. MF The LOCK MODE clause is an optional clause in the file control entry and is used to specify the locking technique used for the file.

    If this clause is omitted, opening the file causes it to become exclusive, with the exception of OPEN INPUT.

    When LOCK MODE IS EXCLUSIVE is specified, the run unit acquires a lock on the whole file when it opens the file.

    When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified, the file that the run unit opens is shareable. Files opened OUTPUT, and indexed and relative files opened EXTEND are, however, always exclusive.

  14. MF The ROLLBACK clause requests transaction logging for a file under those COBOL systems that support that feature. See your COBOL system documentation on file handling for details of how it is implemented in your system.

    If the ROLLBACK clause is specified then WITH LOCK ON MULTIPLE RECORDS is automatically in effect.

  15. MF The WITH LOCK ON RECORD clause specifies single record locking for the file.

    The WITH LOCK ON MULTIPLE RECORDS clause specifies multiple record locking for the file. This clause must be present if multiple record locking is required.

  16. MF If LOCK MODE IS AUTOMATIC WITH LOCK ON RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.

    If LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed, or until an individual lock is released by a DELETE statement.

  17. MF If LOCK MODE IS MANUAL WITH LOCK ON RECORD is specified, a lock is acquired by a READ statement only if it includes the WITH LOCK phrase, and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.

    If LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS is specified, a record lock is acquired by the READ WITH KEPT LOCK statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed.

  18. MF When the lock mode is MANUAL or AUTOMATIC, single record locking is assumed unless the WITH LOCK ON MULTIPLE RECORDS phrase is included.
  19. MF If a file is defined as EXTERNAL and the operating system file-name is assigned by means of a file-name, for example, by use of the ASSIGN directive or keyword, using data-name-1 in the SELECT/ ASSIGN statement, or using Format 2 of the VALUE OF phrase of an FD, then the following rules should be followed:
    1. An identifier with the same name should be used to contain the physical file-name in all source elements which reference the file.
    2. The definition of the identifier which contains the physical file-name should also contain the EXTERNAL attribute.

    No violation of these rules is detected at compile time, but, if any runtime element in the run unit violates these rules, the results at run time are undefined.

    For further details of the effects of record locking, see your COBOL system documentation on file handling.

General Rules for Format 1 (Record Sequential Files)

  20. The MULTIPLE REEL or MULTIPLE UNIT phrase must be specified if it is possible or intended that the file can be closed by use of the CLOSE REEL or CLOSE UNIT statement.
  21. Records in the file are accessed in the sequence specified by predecessor-successor record relationships which are established by the execution of WRITE statements when the file is created or extended.
  22. MF Using the LINE ADVANCING FILE phrase causes a file suitable for a printer to be produced. This file has an initial carriage-return character, and each record is written with AFTER ADVANCING 1 LINE as the default advancing phrase. See your COBOL system documentation on file handling for further details of the format.
  23. ANS85 MF The PADDING CHARACTER clause is documentary only.

    ANS85 If the associated file connector is an external file connector, all PADDING CHARACTER clauses in a run unit which are associated with that file connector must have the same specification. If data-name-5 is external, it must reference an external data item.

  24. ANS85 MF The RECORD DELIMITER clause is documentary only unless character-string is BINARY-SEQUENTIAL, which is an alternative way of specifying the file is record sequential organization.

General Rules for Format 2 (Line Sequential Files)

  25. MF XOPEN When LINE SEQUENTIAL ORGANIZATION is specified either implicitly or explicitly, the file is treated as consisting of fixed-length records, each containing one line of data. The records are stored with trailing spaces removed. The definition of a line of data varies among different operating systems. Some terminate line records with one or both of the carriage-return and line-feed characters, and some pad out as fixed length records. Your COBOL system, therefore, always produces files which are compatible in this respect with the editor software in any operating system.
  26. The RECORD DELIMITER clause is documentary only unless character-string is LINE-SEQUENTIAL, which is an alternative way of specifying the file is line sequential organization.

General Rules for Format 3 (Relative Files)

  27. When access mode is sequential, records in the file are accessed in order of ascending relative record numbers of existing records in the file.
  28. When access mode is random, the value of the RELATIVE KEY data item indicates the record to be accessed.
  29. All records stored in a relative file are uniquely identified by relative record numbers, which also specify the record's logical ordinal position in the file. The first logical record has a relative record number of 1, and subsequent logical records have relative record numbers of 2, 3, 4, ... .
  30. The data item specified by data-name-5 is used to communicate a relative record number between the run-time element and the operating system.

General Rules for Format 4 (Indexed Files)

  31. When access mode is sequential, records in the file are accessed in order of ascending record key values within a given key of reference.
  32. When access mode is random, the value of the record key data item indicates the record to be accessed.
  33. The RECORD KEY clause specifies the record key that is the prime record key for the file. The values of the prime record key must be unique among records of the file. This prime record key provides an access path to records in an indexed file.
  34. If the file has more than one record description entry, data-name-5

    ISO2002 MF and any data-names referenced by split-key-name-1

    need be described only in one of these record description entries. The identical character positions referenced by data-name-5

    ISO2002 MF and any data-names referenced by split-key-name-1

    in any one record description entry are implicitly referenced as keys for all other record description entries of that file.
  35. ANS85 If the associated file connector is an external file connector, all file description entries in the run unit which are associated with that file connector must specify the same data description entry for data-name-1 with the same relative location in the associated record.
  36. The ALTERNATE RECORD KEY clause specifies a record key that is an alternative record key for the file. This alternate record key provides an alternative access path to records in an indexed file.
  37. The data description of data-name-5

    MF or split-key-name-1

    and data-name-8

    MF or split-key-name-2,

    as well as of relative locations within a record, must be the same as that used when the file was created. The number of alternate keys for the file must also be the same as that used when the file was created. This checking is configurable in some environments. (Look up the KEYCHECK parameter in your COBOL system documentation.)

  38. The DUPLICATES phrase specifies that the value of the associated record key can be duplicated within any of the records in the file. If the DUPLICATES phrase is not specified, the value of the associated record key must not be duplicated among any of the records in the file.
  39. For duplicate values, the correct duplicate entry must be located using sequential reads from the first duplicate entry.
  40. MF The SUPPRESS phrase requests the use of a sparse key for an alternate index. Sparse keys are available only through the File Handler and are not available on all systems (see your COBOL system documentation on file handling for details).
  41. ISO2002 MF Split-key-name-1 defines a record key consisting of the concatenation of data-name-6 and all occurrences of data-name-7 in the order specified. Split-key-name-2 defines a record key consisting of the concatenation of data-name-9 and all occurrences of data-name-10 in the order specified.

General Rules for Format 5 (Sort-Merge Files)

  42. The file-control entry names a sort or merge file and specifies the association of the file to a storage medium.
  43. MF When the SORT STATUS clause is specified, a value is placed into the two-character data item specified by data-name-2 after the execution of each sort or merge operation. This value indicates the status at completion of the operation. The following combinations of status keys are possible. Status key 1=0 and status key 2=0 indicates successful completion. Status key 1=3 and status key 2=0 indicates a permanent error. If status key 1=9, status key 2 contains an operating system error message number. For explanations of status keys 1 and 2 and definitions of status, see the topic I-O Status in the chapter Procedure Division. The FILE STATUS clause can be used instead of a SORT STATUS clause, but is treated as a synonym for it, when specified for a sort or merge file.
  44. The ASSIGN clause is documentary only.
Related information
The OCCURS Clause
The RECORD Clause
I-O Status
Sharing Mode


The I-O-Control Paragraph

The I-O-Control paragraph specifies the points at which rerun is to be established, the memory area which is to be shared by different files, and for files with sequential organization the location of files on a multiple file reel.

ANS85 The RERUN and MULTIPLE FILE TAPE clauses of the I-O-Control paragraph are classed as obsolete elements in the ANSI'85 standard and are scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects within this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although they are a part of the standard COBOL definition, the RERUN and MULTIPLE FILE TAPE clauses are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

  1. The I-O-Control paragraph is optional.
  2. When either the integer-1 RECORDS clause or the integer-2 CLOCK-UNITS clause is specified, character-string must be given in the RERUN clause.
  3. In the SAME AREA clause, SORT and SORT-MERGE are equivalent.
  4. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at least one of the file-names must represent a sort or merge file. Files that do not represent sort or merge files can also be named in the clause.
  5. The two forms of the SAME clause (SAME AREA, SAME RECORD AREA) are considered separately in the following:

    More than one SAME clause can be included in a source element, subject to the following restrictions:

    1. A file-name must not appear in more than one SAME AREA clause.
    2. A file-name must not appear in more than one SAME RECORD AREA clause.
    3. If one or more file-names of a SAME AREA clause appear in a SAME RECORD AREA clause, all of the file-names in that SAME AREA clause must appear in the SAME RECORD AREA clause. However, additional file-names not appearing in that SAME AREA clause can also appear in that SAME RECORD AREA clause. The rule that only one of the files mentioned in a SAME AREA clause can be open at any one time takes precedence over the rule that all files mentioned in a SAME RECORD AREA clause can be open at any one time.
    4. A file-name that represents a sort or merge file must not appear in a SAME AREA clause.
    5. A file-name that represents a sort or merge file must not appear in more than one SAME SORT AREA or SAME SORT-MERGE AREA clause.
    6. If a file-name that does not represent a sort or merge file appears in a SAME AREA clause and one or more SAME SORT AREA or SAME SORT-MERGE AREA clauses, all of the files named in that SAME AREA clause must be named in that SAME SORT AREA or SAME SORT-MERGE AREA clause(s).
  6. The files referenced in the SAME AREA, SAME SORT AREA, SAME SORT-MERGE AREA, or SAME RECORD AREA clause need not all have the same organization or access.
  7. MF Character-string must not be a reserved word, a literal or a user-name.
  8. The END OF REEL/UNIT clause can only be used if file-name-2 is a sequential file.
  9. More than one RERUN clause can be specified for a given file-name-2, subject to the following restrictions:
    1. When multiple integer-1 RECORD clauses are specified, no two of them can specify the same file-name-2.
    2. When multiple END OF REEL or END OF UNIT clauses are specified, no two of them can specify the same file-name-2.
  10. Only one RERUN clause containing the CLOCK-UNITS clause can be specified.
  11. OSVS VSC2 Each clause in the I-O-Control paragraph may optionally be followed by a period.

General Rules

  1. ANS85 The RERUN clause is documentary only.
  2. The SAME AREA clause specifies that two or more files that do not represent sort or merge files are to use the same memory area during processing. The area being shared includes all storage areas assigned to the files specified. It is not, therefore, valid to have more than one of the files open at the same time. (See Syntax Rule 5c.)
  3. The SAME RECORD AREA clause specifies that two or more files are to use the same memory area for processing the current logical record. All of the files can be open at the same time. A logical record in the SAME RECORD AREA is considered as a logical record of each opened output file whose file-name appears in this SAME RECORD AREA clause and of the most recently read input file whose file-name appears in this SAME RECORD AREA clause. This is equivalent to an implicit redefinition of the area; that is, records are aligned on the leftmost character position.
  4. MF The APPLY clause is documentary only.
  5. MF The MULTIPLE FILE clause is documentary only.
  6. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at least one of the file-names must represent a sort or merge file. Files that do not represent sort or merge files can also be named in the clause. This clause specifies that storage is shared as follows:
    1. The SAME SORT AREA or SAME SORT-MERGE AREA clause specifies a memory area which is made available for use in sorting or merging each sort or merge file named. Thus any memory area allocated for the sorting or merging of a sort or merge file is available for reuse in sorting or merging any of the other sort or merge files.
    2. In addition, storage areas assigned to files that do not represent sort or merge files can be allocated as needed for sorting or merging the sort or merge files named in the SAME SORT AREA or SAME SORT-MERGE AREA clause.
    3. Files other than sort or merge files do not share a storage area. If you wish these files to share a storage area, you must also include in the source element a SAME AREA or SAME RECORD AREA clause naming these files.
    4. During the execution of a SORT or MERGE statement that refers to a sort or merge file named in this clause, any non-sort-merge files named in this clause must not be open.


Data Division

  • General Description (Data Division)
    The Data Division describes the data that the runtime module is to accept as input, to manipulate, to create, or to produce as output.
  • File Section
    The file description entry (FD) represents the highest level of organization in the File Section. The FILE SECTION header is followed by a file description entry consisting of a level indicator (FD), a file-name and a series of independent clauses. The clauses in the file description entry specify the size of the logical and physical records, the external name of the file, and the names of the data records which comprise the file. The entry itself is terminated by a period.
  • Working-Storage Section
    The Working-Storage Section is composed of the section header, followed by data description entries for noncontiguous data items and/or record description entries. The syntax of data description entries is defined in the topic File Description Entry Skeleton
  • Thread-Local-Storage Section
    The Thread-Local-Storage Section describes data which is unique to each thread, and is persistent across calls. The VALUE clause can be used to provide initial values for this data. The syntax of data description entries is defined in the topic File Description Entry Skeleton.
  • Object-Storage Section
    The Object-Storage Section is an optional section of the Data Division that enables you to declare class object data and instance object data.
  • Local-Storage Section
    A separate copy of the Local-Storage Section is created each time the runtime element is activated and exists only during the lifetime of that activation. The Local-Storage Section is provided specifically for use in functions, methods and recursive calls.
  • Linkage Section
    All references to PROCEDURE DIVISION USING in the following discussion also apply to ENTRY USING.
  • Screen Section
    The Screen Section provides screen handling facilities for use with ACCEPT and DISPLAY statements.
  • File and Data Description
  • Screen Section
Parent topic: Part 2. Program Definition


General Description (Data Division)

The Data Division describes the data that the runtime module is to accept as input, to manipulate, to create, or to produce as output.

The following is the General Format of the sections in the Data Division, and defines the order of presentation in the source element.

General Format

The Report Section is described in the section Report Writer. The other sections are described in individual subtopics within this section.

Parent topic: Data Division
Related information
Report Writer
Input-Output Section
The File-Control Paragraph
The I-O-Control Paragraph
The File Description Entry (Report Writer)
The REPORT Clause
Report Section
The Report Description Entry
PAGE-COUNTER Rules
LINE-COUNTER Rules
The CODE Clause
The CONTROL Clause
The PAGE Clause
The Report Group Description Entry
Presentation Rules Tables
The COLUMN NUMBER Clause (Report Writer)
Data-name (Report Writer)
The GROUP INDICATE Clause
Level-Number (Report Writer)
The LINE NUMBER Clause (Report Writer)
The NEXT GROUP Clause
The SIGN Clause (Report Writer)
The SOURCE Clause (Report Writer)
The SUM Clause (Report Writer)
The TYPE Clause
The USAGE Clause
The VALUE Clause (Report Writer)
General Description
The CLOSE Statement
The GENERATE Statement
The INITIATE Statement
The OPEN Statement (Report Writer)
The SUPPRESS Statement
The TERMINATE Statement
The USE BEFORE REPORTING Statement


File Section

The file description entry (FD) represents the highest level of organization in the File Section. The FILE SECTION header is followed by a file description entry consisting of a level indicator (FD), a file-name and a series of independent clauses. The clauses in the file description entry specify the size of the logical and physical records, the external name of the file, and the names of the data records which comprise the file. The entry itself is terminated by a period.

An SD file description gives information about the size and the names of the data records associated with a file to be sorted or merged. There are no label procedures which the user can control, and the rules for blocking and internal storage are peculiar to the SORT and MERGE statements.

The elements allowed in a file description entry and sort-merge file description entry are defined in the topic File Description Entry Skeleton.

Relationship with Sort-Merge

The sort-merge module provides the capability to sort elements of a table in the Data Division. The files specified in the USING and GIVING phrases of the SORT and MERGE statements must be described implicitly or explicitly in the FILE-CONTROL paragraph as having sequential organization and sequential access mode. No I/O statement can be executed for the file named in the sort-merge file description.

ANS85 The files specified in the USING and GIVING phrases of the SORT and MERGE statements can be described explicitly in the FILE-CONTROL paragraph as having either indexed or relative organization and can have either sequential or dynamic access mode.

Record Description Structure

A record description consists of a set of data description entries which describe the characteristics of a particular record. Each data description entry consists of a level-number, a data-name if required and a series of independent clauses as required. A record description has a hierarchical structure and, therefore, the clauses used with an entry can vary considerably, depending upon whether or not it is followed by subordinate entries. The structure of a record description is defined in the topic Concept Of Levels in the chapter Concepts of the COBOL Language, while the elements allowed in a record description are defined in the topic File Description Entry Skeleton.

Parent topic: Data Division
Related information
File Description Entry Skeleton
Concept Of Levels


Working-Storage Section

The Working-Storage Section is composed of the section header, followed by data description entries for noncontiguous data items and/or record description entries. The syntax of data description entries is defined in the topic File Description Entry Skeleton

Each Working-Storage Section record-name and noncontiguous item-name should be unique since it cannot be qualified. Subordinate data-names need not be unique if they can be made unique by qualification.

ANS85 Provided no reference is made to a given data-name or record-name, it need not be unique by qualification.

General Format

Syntax Rules

  1. The Working-Storage Section may be specified in a function definition or a program definition. Within a class definition, the Working-Storage Section must be specified only in a factory definition or an instance definition, but not in a method definition. The Working-Storage Section must not be specified within an interface definition.

Comments:

Noncontiguous Working-Storage (77-level-description-entry)

Items and constants in the Working-Storage Section which bear no hierarchical relationship to one another need not be grouped into records, provided they do not need to be further subdivided. Instead, they are classified as noncontiguous elementary items and are defined in a separate data description entry which begins with the special level-number, 77. The syntax of data description entries is defined in the chapter File Description Entry Skeleton.

The following data clauses are required in each data description entry:

  • Level-number 77
  • Data-name
  • Either:
    • The PICTURE clause or
    • The USAGE clause specifying USAGE INDEX,

      VSC2 MF USAGE COMPUTATIONAL-1, USAGE COMPUTATIONAL-2, USAGE POINTER, or

      MF COB370 USAGE PROCEDURE-POINTER

      ISO2002 MF USAGE OBJECT-REFERENCE

      MF USAGE EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER or THREAD-POINTER

      .

Other data description clauses are optional and can be used to complete the description of the item if necessary.

Working-Storage Records (record-description-entry)

Data elements in the Working-Storage Section which bear a definite hierarchical relationship to one another must be grouped into records according to the rules for formation of record descriptions. All clauses which are used in record descriptions in the File Section can be used in record descriptions in the Working-Storage Section.

Record Description Structure

A record description consists of a set of data description entries which describe the characteristics of a particular record. Each data description entry consists of a level-number

ANS85 optionally

followed by the data-name or FILLER clause, followed by a series of independent clauses as required. A record description can have a hierarchical structure and therefore the clauses used within an entry can vary considerably, depending upon whether or not it is followed by subordinate entries. The structure of a record description is defined in the topic Concept Of Levels in the chapter Concepts of the COBOL Language, while the elements allowed in a record description are defined in the topic File Description Entry Skeleton.

Parent topic: Data Division
Related information
File Description Entry Skeleton
Concept Of Levels


Thread-Local-Storage Section

The Thread-Local-Storage Section describes data which is unique to each thread, and is persistent across calls. The VALUE clause can be used to provide initial values for this data. The syntax of data description entries is defined in the topic File Description Entry Skeleton.

Thread-local storage can be viewed as thread-specific working storage. This is useful for resolving contention problems in most reentrant programs. In many cases, a non file-handling program can be made completely reentrant by simply changing the WORKING-STORAGE SECTION header to a THREAD-LOCAL-STORAGE SECTION header.

Restriction: THREAD-LOCAL-STORAGE cannot be used in class programs compiled for managed code (but can be used in procedural COBOL programs compiled to managed code).

General Format

Syntax Rules

  1. The EXTERNAL clause is not allowed.
  2. For JVM COBOL applications, data items cannot be object references.

General Rules

  1. A separate copy of each data item in thread-local storage is created and set to its initial state for each new thread of execution that enters the program. The data item is only visible to the thread causing its execution. The data item is destroyed when the creating thread's execution terminates, or when a CANCEL statement on the program is executed; otherwise, on subsequent calls to the program within that thread, the data item is in its last used state.
  2. In a single-threaded environment, thread-local storage behaves exactly as working storage.
Parent topic: Data Division
Related information
File Description Entry Skeleton


Object-Storage Section

The Object-Storage Section is an optional section of the Data Division that enables you to declare class object data and instance object data.

Format

Syntax Rules

  1. Data declared in the Object-Storage Section of the class object may only be accessed in class methods.
  2. Data declared in the Object-Storage Section of an object-program may only be accessed in instance methods.
  3. If DATA IS RESTRICTED or DATA IS PROTECTED is specified in the CLASS-ID paragraph, data declared in the Object-Storage Section may be directly accessed in a subclass. Otherwise, this data may only be accessed by invoking methods.
  4. The syntax rules for data declared in the Object-Storage Section are the same as those for the Linkage Section except you must not specify the DEPENDING ON phrase on an OCCURS clause when the ODOSLIDE Compiler directive is specified.

General Rules

  1. Data declared in the Object-Storage Section can be inherited by subclasses.
  2. Each new instance object is allocated its own unique storage for data items declared in the Object-Storage Section.
  3. When the Compiler directive OOCTRL(+W) is specified, the Working-Storage Section is treated as the Object-Storage Section.
Parent topic: Data Division


Local-Storage Section

A separate copy of the Local-Storage Section is created each time the runtime element is activated and exists only during the lifetime of that activation. The Local-Storage Section is provided specifically for use in functions, methods and recursive calls.

The Local-Storage Section is composed of the section header, followed by data description entries for noncontiguous data items and/or record description entries. Each Local-Storage Section record-name and noncontiguous item-name should be unique since it cannot be qualified. Subordinate data-names need not be unique if they can be made unique by qualification. The syntax of data description entries is defined in the topic File Description Entry Skeleton.

Provided no reference is made to a given data-name or record-name, it need not be unique by qualification.

General Format

Syntax Rules

  1. The EXTERNAL clause is not allowed.
  2. The GLOBAL clause is not allowed.
  3. The syntax CALL ... USING local-data-item is permitted.
  4. The syntax ENTRY ... USING local-data-item is not permitted.
  5. The syntax PROCEDURE DIVISION ... USING local-data-item is not permitted.
  6. The presence of a Local-Storage Section in a program implicitly sets the recursive attribute, even if the section does not have any records. For more information, see the section Common, Initial, and Recursive Attributes in the chapter Language Fundamentals.

General Rules

  1. The DEFAULTBYTE compiler directive does not apply to items declared within the Local-Storage Section.
  2. The VALUE clause initializes data items as described in the topic The VALUE clause.
Parent topic: Data Division
Related information
File Description Entry Skeleton
Common, Initial, and Recursive Attributes
The VALUE clause


Linkage Section

All references to PROCEDURE DIVISION USING in the following discussion also apply to ENTRY USING.

VSC2 MF Except as described in the topic The SET Statement in the chapter Procedure Division - SEARCH - WRITE,

the Linkage Section in a program definition is meaningful if, and only if, the object program is to function under the control of a CALL statement, and the CALL statement in the calling program contains a USING phrase.

ISO2002 MF The Linkage Section is always meaningful in a function or method.

Formal parameters and returning items described in the Linkage Section of a source element are referred to both by that source element, when it is activated, and by the activating source element.

MF Such data can also be described in the File and Working-Storage Sections .

No storage is allocated for data items defined in the Linkage Section. Procedure Division references to these data items are resolved at run time by equating the reference in the activated runtime element to the location used in the activating runtime element. In the case of index-names, no such correspondence is established. Index-names in the activated and activating runtime element always refer to separate indices.

Data items defined in the Linkage Section of a program can be referenced within the Procedure Division of that program only if they are specified as operands of the USING phrase of the PROCEDURE DIVISION header or are subordinate to such operands, and the object program is under the control of a CALL statement which specifies a USING phrase.

The structure of the Linkage Section is the same as that previously described for the Working-Storage Section, beginning with a section header, followed by data description entries for noncontiguous data items and/or record description entries. The syntax of data description entries is defined in the chapter File Description Entry Skeleton.

Each Linkage Section record-name and noncontiguous item-name must be unique within the source element.

ANS85 These names need not be unique if they are not referenced in the Procedure Division.

The description of the parameters and the returning items that appear in a Linkage Section must follow the rules specified in the topic Conformance for Parameters and Returning Items in the chapter Procedure Division.

Comments:

Noncontiguous Linkage Storage

Items in the Linkage Section that bear no hierarchic relationship to one another need not be grouped into records and are classified and defined as noncontiguous elementary items. Each of these data items is defined in a separate data description entry which begins with the special level-number 77.

The following data clauses are required in each data description entry:

  • Level-number 77
  • Data-name
  • Either
    • The PICTURE clause or
    • the USAGE clause specifying USAGE INDEX ,

      VSC2 MF USAGE COMPUTATIONAL-1, USAGE COMPUTATIONAL-2, USAGE POINTER,

      MF COB370 USAGE PROCEDURE-POINTER,

      ISO2002 MF USAGE OBJECT-REFERENCE,

      MF USAGE EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER , THREAD-POINTER

      .

Other data description clauses are optional and can be used to complete the description of the item if necessary.

Linkage Records

Data elements in the Linkage Section which bear a definite hierarchic relationship to one another must be grouped into records according to the rules for formation of record descriptions. Any clause which is used in an input or output record description can be used in a Linkage Section.

Parent topic: Data Division
Related reference
Linkage Section in Main Program
Related information
The SET Statement
File Description Entry Skeleton
Conformance for Parameters and Returning Items


Screen Section

The Screen Section provides screen handling facilities for use with ACCEPT and DISPLAY statements.

The Screen Section provides screen handling facilities for use with ACCEPT and DISPLAY statements. It allows the following:

  • The display of non-scrolling forms consisting of areas of the screen as defined in the Screen Section. A Screen Section entry is called a screen description. It is similar in appearance to a data description but defines a screen item or area of the screen rather than an area in memory.
  • MF The display of data items which constitute non-scrolling forms. The details of the areas of the screen to be used are provided in the associated ACCEPT and DISPLAY operations.

The Screen Section contains a description of each field on the screen which is accessed in a Format 4 ACCEPT or Format 2 DISPLAY operation. Such a field is called a screen item. Many screen items describe only the layout of fields within a field on the screen and are never referenced explicitly.

The Screen Section contains syntax which enables you to:

  • Specify the exact location of fields
  • Accept data typed at specified positions
  • Display literal text at specified positions
  • Define screen attributes
  • Control console features.

This syntax is defined in the topic Screen Section Entry Skeleton.

Data entry is made to numeric and numeric-edited screen fields in two ways; fixed-format mode and free-format mode. Refer to your COBOL system documentation about user interfaces for further details.

Fixed-format mode is the default manner in which data entry is made to numeric and numeric edited screen fields. This mode formats and echoes the entered data and also moves the cursor in accordance with the requirements of the field's picture specification, as each keystroke is received. Characters other than digits, "+", "-" , and the decimal point character, are rejected; insertion characters in edited fields are skipped over as the cursor moves backwards and forwards; any sign indicator is modified in accordance with its normal specification; floating symbols move left and right in the field, and insertion symbols appear and disappear as digits are inserted or deleted. When the cursor reaches the last character position in a field, any further character entered replaces the last character.

Free-format mode is an alternative manner in which data entry can be made to numeric and numeric-edited screen fields. The default mode is fixed-format mode. Free-format mode allows data to be keyed into a PIC X field of appropriate length, and only when the operator leaves the field is the data reformatted to comply with the picture specification. Once the operator moves the cursor from the field, your COBOL system disregards all characters other than digits and the sign and decimal point symbols. It then extracts, stores, or reformats the numeric value in accordance with the normal COBOL rules for a MOVE to an item with the same picture as the screen item or working storage item. The numeric value is then usually echoed to the screen. See your COBOL system documentation about user interfaces for details on configuration options available to you.

The Screen Section provides screen handling facilities for use with Format 4 ACCEPT and Format 2 DISPLAY statements.

General Format

Syntax Rules

  1. The Screen Section must be the last section in the Data Division.
  2. A screen-description-entry contains screen description clauses. Data description clauses allowed in the Screen Section are restricted to those shown in the General Format.

General Rule

  1. The Screen Section contains a description of each field on the screen which is accessed in a Format 4 ACCEPT or Format 2 DISPLAY operation. Such a field is called a screen item. Many screen items describe only the layout of fields within a field on the screen and are never referenced explicitly.
Parent topic: Data Division
Related information
Screen Section Entry Skeleton


File and Data Description

  • File Description Entry Skeleton
    The file description comprises information concerning the physical structure, identification, and record-names pertaining to a given file.
  • Data Description Entry Skeleton
    A data description entry specifies the characteristics of a particular item of data.
Parent topic: Data Division


File Description Entry Skeleton

The file description comprises information concerning the physical structure, identification, and record-names pertaining to a given file.

ANS85 It determines the internal or external attributes of a file connector, of the associated data records, and of the associated data items. The file description entry also determines whether a file-name is a local name or a global name.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative and Indexed Files)

General Formats for Format 4 (Sort-Merge Files)

Syntax Rules for All Formats (All Files)

  1. The clauses which follow file-name-1 may appear in any order.
  2. MF If the VALUE OF FILE-ID clause is specified, literal-1 must be a nonnumeric literal and cannot be a figurative constant.

Syntax Rules for Formats 1, 2 and 3 (RecordSequential, MF Line Sequential, Relative and Indexed Files)

  3. The level indicator FD identifies the beginning of a file description and must precede the file-name.
  4. One or more record description entries must follow the file description entry.
  5. MF The EXTERNAL clause and the THREAD-LOCAL clause must not be specified in the same file description entry.

Syntax Rules for Format 4 (Sort-Merge Files)

  6. The level indicator SD identifies the beginning of the sort-merge file description and must precede the file-name.
  7. The clauses which follow the name of the file are optional and may appear in any order.
  8. One or more record description entries must follow the sort-merge file description entry. However, no input-output statements can be executed for this file.

General Rules for Format 1 (Record Sequential Files)

  1. If the file description entry for a sequential file contains the LINAGE clause and the EXTERNAL clause, the LINAGE-COUNTER data item is an external data item. If the file description entry for a sequential file contains the LINAGE clause and the GLOBAL clause, the special register LINAGE-COUNTER is a global name.
  • The BLOCK CONTAINS Clause
    The BLOCK CONTAINS clause specifies the size of a physical record.
  • The CODE-SET Clause
    The CODE-SET clause specifies the character code set used to represent data on the external media.
  • The DATA RECORDS Clause
    The DATA RECORDS clause serves only as documentation for the names of data records with their associated file.
  • The EXTERNAL Clause
    The EXTERNAL clause specifies that a data item or a file connector is external. The constituent data items and group items of an external data record are available to every runtime element in the run unit that describes that record.
  • The GLOBAL Clause
    The GLOBAL clause specifies that a data-name, a file-name, or a report-name is a global name. A global name is available to every program contained within the program which declares it.
  • The LABEL RECORDS Clause
    The LABEL RECORDS clause specifies whether labels are present.
  • The LINAGE Clause
    The LINAGE clause allows the user to specify the depth of a logical page in terms of number of lines. The user can also specify the size of the top and bottom margins on the logical page, and the line number, within the page body, at which the footing area begins.
  • The RECORD Clause
  • The THREAD-LOCAL Clause
    The THREAD-LOCAL clause specifies that there is a distinct copy of a data item or file connector for each thread entering a program.
  • The VALUE OF Clause
    The VALUE OF clause specifies the description of an item in the label records associated with a file.
  • The RECORDING MODE Clause
    The RECORDING MODE clause specifies the format of the logical records in the file.
Parent topic: File and Data Description


The BLOCK CONTAINS Clause

The BLOCK CONTAINS clause specifies the size of a physical record.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

General Rules

  1. MF This clause is documentary only.
Parent topic: File Description Entry Skeleton


The CODE-SET Clause

The CODE-SET clause specifies the character code set used to represent data on the external media.

It can be specified only for files with record sequential

MF and line sequential

organization.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • CHARSET – determines what is considered the native code set.

Syntax Rules

  1. When the CODE-SET clause is specified for a file, all data in that file must be described as USAGE IS DISPLAY and any signed numeric data must be described with the SIGN IS SEPARATE clause.

    MF These restrictions do not apply.

  2. The alphabet-name clause referenced by the CODE-SET clause must not specify the literal phrase.
  3. MF Identifier-1 can be qualified, but must not be subscripted.
  4. MF Each identifier-1 must be a data item described in the same record description for the file, and must not itself be a record description.
  5. MF If the optional FOR phrase is specified, the CODE-SET clause specifies the character code to be used for the data items named. If the FOR phrase is not specified, the CODE-SET clause specifies the character code to be used for the whole file.
  6. The native character set is used for any file, or data item in a file, to which no CODE-SET clause applies.

General Rules

  1. MF The data in the record area is always in ASCII. If alphabet-name has been equated in the Special-Names paragraph to EBCDIC, then data affected by the CODE-SET clause is translated from ASCII to EBCDIC as it is written to the file; or from EBCDIC to ASCII as it is read from the file. If alphabet-name has been equated in the Special-Names paragraph to STANDARD-1, STANDARD-2, NATIVE, or ASCII, no translation is necessary.
  2. MF For the purposes of this translation, any data item to which a CODE-SET clause applies is treated as alphanumeric. No account is taken of the class and category of the item as described in its data description.
  3. MF If identifier-1 has an OCCURS clause, the CODE-SET clause applies to only the first occurrence of it. If identifier-1 has a subordinate item with an OCCURS clause, the CODE-SET clause applies to the whole of identifier-1.
Parent topic: File Description Entry Skeleton


The DATA RECORDS Clause

The DATA RECORDS clause serves only as documentation for the names of data records with their associated file.

ANS85 The DATA RECORDS clause of the file description entry is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

  1. Data-name-1 and data-name-2 are the names of data records and should have 01 level-number record descriptions, with the same names, associated with them.

    OSVS VSC2 These data-names do not have to be associated with any data description entry in the program.

General Rules

  1. The presence of more than one data-name indicates that the file contains more than one type of data record. These records can be of differing sizes, different formats, and so on. The order in which they are listed is not significant.
    Note: When using multiple 01 level items within an FD, if the SELECT statement contains key definitions, the key sizes must be contained within the minimum record length of that FD.
  2. Conceptually, all data records within a file share the same area. This is in no way altered by the presence of more than one type of data record within the file.
Parent topic: File Description Entry Skeleton


The EXTERNAL Clause

The EXTERNAL clause specifies that a data item or a file connector is external. The constituent data items and group items of an external data record are available to every runtime element in the run unit that describes that record.

General Format

Syntax Rules

  1. The EXTERNAL clause can be specified only in file description entries, or in record description entries in the Working-Storage Section.
  2. In the same source element, the externalized name of the subject of the entry that includes the EXTERNAL clause must not be the same as the externalized name of any other entry that includes the EXTERNAL clause.
  3. The VALUE clause must not be used in any data description entry that includes, or is subordinate to an entry that includes, the EXTERNAL clause. The VALUE clause can be specified for condition-name entries associated with such data description entries.
  4. MF Literal-1 must be a nonnumeric or a national literal and must not be a figurative constant.
  5. ISO2002 The EXTERNAL clause must not be specified for a data item of class object.
  6. MF You can specify EXTERNAL in the data division of a method but not as instance data.

General Rules

  1. The data contained in the record named by the data-name clause is external and can be accessed and processed by any runtime element in the run unit which describes and, optionally, redefines it subject to the following general rules.
  2. Within a run unit, if two or more source elements describe the same external data record, each record-name of the associated record description entries must be the same and the records must define the same number of standard data format characters. However, a source element which describes an external record can contain a data description entry including the REDEFINES clause which redefines the complete external record, and this complete redefinition need not occur identically in other source elements in the run unit, unless the storage area required for the redefinition is larger than the storage area required for the external data record. See the topic The REDEFINES Clause.
  3. Use of the EXTERNAL clause does not imply that the associated file-name or data-name is a global name. See the topic The GLOBAL Clause.
  4. The file connector associated with this description entry is an external file connector.

    MF See your COBOL system documentation on file handling for further information on files with the EXTERNAL attribute.

  5. MF Literal-1 identifies the external name of an external data item or file connector. The same external name must be used by all source elements that reference the same external data item or file connector.
  6. MF When EXTERNAL is specified in the data division of a method, the addressability of the EXTERNAL data is established on each entry to the method.
Parent topic: File Description Entry Skeleton
Related information
The REDEFINES Clause
The GLOBAL Clause


The GLOBAL Clause

The GLOBAL clause specifies that a data-name, a file-name, or a report-name is a global name. A global name is available to every program contained within the program which declares it.

General Format

Syntax Rules

  1. The GLOBAL clause can be specified only in data description entries whose level-number is 01 in the File Section or the Working-Storage Section, file description entries, or report description entries.

    MF COB370 The GLOBAL clause can also be specified in the Linkage Section.

  2. In the same Data Division, the data description entries for any two data items for which the same data-name is specified must not include the GLOBAL clause.
  3. If the SAME RECORD AREA clause is specified for several files, the record description entries or the file description entries for these files must not include the GLOBAL clause.

General Rules

  1. A data-name, file-name or report-name described using a GLOBAL clause is a global name. All data-names subordinate to a global name are global names. All condition-names associated with a global name are global names.
  2. A statement in a program contained directly or indirectly within a program which describes a global name can reference that name without describing it again. See the topic Scope of Names in the chapter Concepts of the COBOL Language.
  3. If the GLOBAL clause is used in a data description entry which contains the REDEFINES clause, it is only the subject of that REDEFINES clause which possesses the global attribute.
Parent topic: File Description Entry Skeleton
Related information
Scope of Names


The LABEL RECORDS Clause

The LABEL RECORDS clause specifies whether labels are present.

ANS85 The LABEL RECORDS clause is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

  1. This clause should be present in every file description entry.

    ANS85 It is not required.

  2. OSVS VSC2 Data-name-1 is the name of a label record and should have a 01 level-number record description, with the same name, associated with it.
  3. OSVS VSC2 Data-name-1 must not appear in the DATA RECORDS clause for the file.
  4. OSVS VSC2 Both LABEL RECORDS IS and LABEL RECORD ARE are accepted as valid syntax.

General Rule

  1. MF This clause is documentary only.
Parent topic: File Description Entry Skeleton


The LINAGE Clause

The LINAGE clause allows the user to specify the depth of a logical page in terms of number of lines. The user can also specify the size of the top and bottom margins on the logical page, and the line number, within the page body, at which the footing area begins.

It can be specified only for files with sequential organization.

General Format

Syntax Rules

  1. Data-name-1, data-name-2, data-name-3 and data-name-4 must reference elementary unsigned integer data items.
  2. The value of integer-1 must be greater than zero.
  3. The value of integer-2 must not be greater than integer-1.
  4. The value of integer-3 and integer-4 can be zero.

General Rules

  1. The LINAGE clause allows the user to specify the size of a logical page in terms of number of lines. The logical page size is the sum of the values referenced by each phrase except the FOOTING phrase. If the FOOTING phrase is not specified, the values for these functions are zero and no end-of-page condition independent of the page overflow condition exists.

    There is not necessarily any relationship between the size of the logical page and the size of a physical page.

  2. The value of integer-1 or the data item referenced by data-name-1 specifies the number of lines that can be written and/or spaced on the logical page. The value must be greater than zero. That part of the logical page in which these lines can be written and/or spaced is called the page body.
  3. The value of integer-2 or the data item referenced by data-name-2 specifies the line number within the page body at which the footing area begins. The value must be greater than zero and not greater than the value of integer-1 or the data item referenced by data-name-1.

    The footing area comprises the area of the logical page between the line represented by the value of integer-2 of the data item referenced by data-name-2, and the line represented by the value of integer-1 or the data item referenced by data-name-1, inclusive.

  4. The value of integer-3 or the data item referenced by data-name-3 specifies the number of lines that comprise the top margin on the logical page. The value can be zero.

    The value of integer-4 or the data item referenced by data-name-4 specifies the number of lines that comprise the bottom margin on the logical page. The value can be zero.

  5. The value of integer-1, integer-3, and integer-4, if specified, will be used at the time the file is opened by the execution of an OPEN statement with the OUTPUT phrase, to specify the number of lines that comprise each of the indicated sections of a logical page. The value of integer-2, if specified, will be used at that time to define the footing area. These values are used for all logical pages written for the file during a given execution of the runtime element.
  6. The values of the data items referenced by data-name-1, data-name-3, and data-name-4, if specified at the time an open statement with the OUTPUT phrase is executed for the file, will be used to specify the number of lines that are to comprise each of the indicated sections for the first logical page.

    The value of the data item referenced by data-name-2, if specified, will be used at the time an OPEN statement with the OUTPUT phrase is executed for the file to define the footing area for the first logical page.

  7. A LINAGE-COUNTER special register is generated by the presence of a LINAGE clause. The value in the LINAGE-COUNTER special register at any one time represents the line number at which the device is positioned within the current page body. The rules governing the LINAGE-COUNTER special register are as follows:
    1. A separate LINAGE-COUNTER special register is supplied for each file described in the File Section whose file description entry contains a LINAGE clause.
    2. The LINAGE-COUNTER special register can be referenced, but cannot be modified, by Procedure Division statements. Since more than one LINAGE-COUNTER special register can exist in a source element, the user must qualify LINAGE-COUNTER by file-name when necessary.
  8. Each logical page is contiguous to the next with no additional spacing provided.
  9. The values of the data items, at the time a WRITE statement with the ADVANCING PAGE phrase is executed or page overflow condition occurs (see the topic The WRITE Statement), will be used to specify the number of lines that are to comprise each of the indicated sections for the next logical page.
  10. The value of the data item referenced by data-name-2, if specified, will be used at the time a WRITE statement with the ADVANCING PAGE phrase is executed or a page overflow condition occurs, to define the footing area for the next logical page.
  11. The LINAGE-COUNTER special register is automatically modified, according to the following rules, during the execution of a WRITE statement to an associated file:
    • When the ADVANCING PAGE phrase of the WRITE statement is specified, the LINAGE-COUNTER special register is automatically reset to one.
    • When the ADVANCING identifier-2 or integer phrase of the WRITE statement is specified, the LINAGE-COUNTER special register is incremented by integer or the value of the data item referenced by identifier-2.
    • When the ADVANCING phrase of the WRITE statement is not specified, the LINAGE-COUNTER special register is incremented by the value one. (See the topic The WRITE Statement.)
    • The value of the LINAGE-COUNTER special register is automatically reset to one when the device is repositioned to the first line that can be written on for each of the succeeding logical pages. (See the topic The WRITE Statement.)
  12. The value of the LINAGE-COUNTER special register is automatically set to one when an OPEN statement is executed for the associated file.
Parent topic: File Description Entry Skeleton
Related information
The WRITE Statement


The RECORD Clause

ANS85 The RECORD clause specifies either the number of character positions in a fixed-length record or the range of character positions in a variable-length record. If the number of character positions varies, the clause specifies the minimum and maximum number of character positions.

MF The concepts of fixed and variable format files used throughout this section do not directly apply to line sequential files. See your COBOL system documentation on file handling for details on the implications of using line sequential files in your COBOL implementation.

XOPEN Although it is a part of the standard COBOL definition, the RECORD CONTAINS clause is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

Syntax Rules for Format 1

  1. No record description entry for the file can specify a number of character positions different from integer-1.

Syntax Rules for Format 2

  2. ANS85 Record descriptions for the file must not describe records which contain fewer character positions than specified by integer-2, nor records which contain a greater number of character positions than that specified by integer-3.
  3. ANS85 Integer-3 must be greater than integer-2.
  4. ANS85 Data-name-1 must describe an elementary unsigned integer in the Working-Storage or Linkage Section.

General Rules for All Formats

  1. If the RECORD clause is not specified, the size of each data record is completely defined in the record description entry.
  2. ANS85 If the associated file connector is an external file connector, all file description entries in the run unit which are associated with that file connector must specify the same values for integer-1 or integer-2 and integer-3. If the RECORD clause is not specified, all record description entries associated with this file connector must be the same length.
  3. MF XOPEN Line sequential files are neither truly fixed nor truly variable format files: the presence or absence of any RECORDING MODE, RECORD CONTAINS or RECORD VARYING IN SIZE clause does not, therefore, impact their performance.

General Rules for Format1

  4. Format 1 is used to specify fixed-length records. Integer-1 specifies the number of character positions contained in each record in the file.

General Rules for Format2

  5. ANS85 Format 2 is used to specify variable-length records. Integer-2 specifies the minimum number of character positions to be contained in any record of the file. Integer-3 specifies the maximum number of character positions in any record of the file.
  6. ANS85 The number of character positions associated with a record description is determined by the sum of the number of character positions in all elementary data items excluding redefinitions and renamings, plus any implicit FILLER items due to synchronization. If a table is specified:
    1. The minimum number of table elements described in the record is used in the summation above to determine the minimum number of character positions associated with the record description.
    2. The maximum number of table elements described in the record is used in the summation above to determine the maximum number of character positions associated with the record description.
  7. ANS85 If integer-2 is not specified, the minimum number of character positions to be contained in any record of the file is equal to the least number of character positions described for a record in that file.
  8. ANS85 If integer-3 is not specified, the maximum number of character positions to be contained in any record of the file is equal to the greatest number of character positions described for a record in that file.
  9. ANS85 If data-name-1 is specified, the number of character positions in the record must be placed into the data item referenced by data-name-1 before any RELEASE, REWRITE, or WRITE statement is executed for the file.
  10. ANS85 If data-name-1 is specified, the execution of a DELETE, RELEASE, REWRITE, START, or WRITE statement or the unsuccessful execution of a READ or RETURN statement does not alter the content of the data item referenced by data-name-1.
  11. ANS85 During the execution of a RELEASE, REWRITE, or WRITE statement, the number of character positions in the record is determined by the following conditions:
    1. If data-name-1 is specified, by the content of the data item referenced by data-name-1.
    2. If data-name-1 is not specified and the record does not contain a variable occurrence data item, by the number of character positions in the record.
    3. If data-name-1 is not specified and the record does contain a variable occurrence data item, by the sum of the fixed portion and that portion of the table described by the number of occurrences at the time of execution of the output statement.

    If the number of character positions in the logical record which is to be written is less than integer-2 or greater than integer-3, the output statement is unsuccessful and, except during execution of a RELEASE statement, the associated I/O status is set to a value indicating the cause of the condition.

  12. ANS85 If data-name-1 is specified, after the successful execution of a READ or RETURN statement for the file, the contents of the data item referenced by data-name-1 indicates the number of character positions in the record just read.
  13. ANS85 If the INTO phrase is specified in the READ or RETURN statement, the number of character positions in the current record that participate as the sending data items in the implicit MOVE statement is determined by the following conditions:
    1. If data-name-1 is specified, by the content of the data item referenced by data-name-1.
    2. If data-name-1 is not specified, by the value that would have been moved into the data item referenced by data-name-1 had data-name-1 been specified.

General Rules for Format 3

  14. When format 3 of the RECORD clause is used, integer-4 and integer-5 refer to the minimum number of characters in the smallest size data record and the maximum number of characters in the largest size data record respectively. However, in this case, the size of each data record is completely defined in the record description entry.
  15. The size of each data record is specified in terms of the number of character positions required to store the logical record, regardless of the types of characters used to represent the items within the logical record. The size of a record is determined by the sum of the number of characters in all fixed-length elementary items plus the sum of the maximum number of characters in any variable-length item subordinate to the record. This sum can be different from the actual size of the record. See the topic Selection Of Character Representation And Radix in the chapter Concepts of the COBOL Language, and the sections The SYNCHRONIZED Clause and The USAGE Clause.
Parent topic: File Description Entry Skeleton
Related information
Selection Of Character Representation And Radix
The SYNCHRONIZED Clause
The USAGE Clause


The THREAD-LOCAL Clause

The THREAD-LOCAL clause specifies that there is a distinct copy of a data item or file connector for each thread entering a program.
Restriction: THREAD-LOCAL cannot be used in class programs compiled for managed code (but can be used in procedural COBOL programs compiled to managed code).

General Format

IS THREAD-LOCAL

Syntax Rules

  1. The THREAD-LOCAL clause can be specified only in file description entries or in record description entries in the Working-Storage Section.
  2. For JVM COBOL applications, data items cannot be object references.

General Rules

  1. If the THREAD-LOCAL clause is specified, a separate copy of the file connector or data item is created and set to its initial state for each new thread of execution that enters the program. The file connector or data item is only visible to the thread causing its creation. The file connector or data item is destroyed when the creating thread's execution terminates or when a CANCEL statement on the program is executed; otherwise, on subsequent calls to the program within that thread, the data item or file connector is in its last used state.
  2. If the THREAD-LOCAL clause is not specified, the file connector or data item is shared by all threads entering the program.
  3. In a single-threaded environment, the clause is ignored and the program behaves exactly as if the THREAD-LOCAL clause had not been specified.
Parent topic: File Description Entry Skeleton


The VALUE OF Clause

The VALUE OF clause specifies the description of an item in the label records associated with a file.

ANS85 The VALUE OF clause of the file description entry is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Formats (All Files)

Syntax Rules (All Files)

  1. implementor-name-1 may be any user-defined word or the words LABEL, or FILE-ID. When implementor-name-1 is LABEL or FILE-ID, only one implementor-name-1 may be specified in a single VALUE OF clause; specify additional VALUE OF clauses within the file-description-entry if you need multiple LABEL or FILE-ID implementor-names.
  2. Data-name-1 must be defined in the Working-Storage Section, except when implementor-name-1 is set to LABEL, in which case, data-name-1 does not have to be defined.
  3. Data-name-1 should be qualified when necessary, but cannot be subscripted or indexed, nor can it be an item described with the USAGE IS INDEX clause.
  4. MF Literal-1 must be a nonnumeric literal and cannot be a figurative constant.
  5. MF The VALUE OF FILE-ID clause should not be used if external-file-reference, data-name-1 or literal-1 has been specified in the ASSIGN clause in the file control entry (see the topic The File Control Entry in the chapter Environment Division). If it is used in one of these cases, the VALUE OF FILE-ID specification overrides the file control entry specification, as indicated by COBCH1658 VALUE OF FILE-ID overriding ASSIGN (1658-E) at compile time.

General Rules (All Files)

  1. MF This clause is documentary only, except when implementor-name-1 is set to FILE-ID.
  2. MF When implementor-name-1 is set to FILE-ID, the character-string specified in literal-1 or data-name-1 is taken as the external file-name.
Parent topic: File Description Entry Skeleton
Related information
The File Control Entry


The RECORDING MODE Clause

The RECORDING MODE clause specifies the format of the logical records in the file.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative and Indexed Files)

Syntax Rules

  1. MF F and FIXED are synonyms.
  2. MF V and VARIABLE are synonyms.

General Rules for All Formats (All Files)

  1. Specifying RECORDING MODE IS F causes all the records in the file to be the same length.

General Rules for Format 1 (Record Sequential Files)

  2. MF The "U" option is documentary only.

General Rules for Formats 1 and 3 (Record Sequential,Relative and Indexed Files)

  3. When RECORDING MODE IS V is specified, the records in the file can be either fixed or variable in length. Each data record includes a record length field. These fields are not part of the record description.

General Rules for Format 2 (Line SequentialFiles)

  4. MF Line sequential files are neither truly fixed nor truly variable format files: the presence or absence of any RECORDING MODE, RECORD CONTAINS or RECORD VARYING IN SIZE clause does not, therefore, impact their performance.
Parent topic: File Description Entry Skeleton


Data Description Entry Skeleton

A data description entry specifies the characteristics of a particular item of data.

MF or the characteristics of a programmer-defined type of data which can then be used to specify the description of one or more particular items of data

.

ANS85 A level 01 data description entry within the Working-Storage Section or File Section determines whether the data record and its subordinate data items have local names or global names.

ANS85 A level 01 data description in the Working-Storage Section determines the internal or external attribute of the data record and its subordinate data items.

General Formats for Format 1

General Formats for 66 level item Format 2

General Formats for 88 level item Format 3

General Formats for 78 level item Format 4

General Formats for 78 level item

Syntax Rules

  1. The level-number in Format 1 can be any number from 01 through 49 or 77.
  2. The clauses can be written in any order with two exceptions: the data-name-1 or FILLER clause

    ANS85 , if specified,

    must immediately follow the level-number; the REDEFINES clause, when used, must immediately follow the data-name-1 or FILLER clause

    ANS85 if either is specified; otherwise it must immediately follow the level number

    .

  3. The PICTURE clause must not be specified for the subject of a RENAMES clause or for an item whose usage is
    • INDEX,
    • ISO2002 MF OBJECT-REFERENCE,
    • PROCEDURE-POINTER,
    • ISO2002 MF PROGRAM-POINTER,
    • POINTER,
    • OSVS VSC2 MF COMPUTATIONAL-1, COMPUTATIONAL-2,
    • ISO2002 MF BINARY-CHAR, BINARY-SHORT, BINARY-LONG, BINARY-DOUBLE,
    • ISO2002 MF FLOAT-SHORT, FLOAT-LONG,
    • MF EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER or THREAD-POINTER.

    For any other entry describing an elementary item, a PICTURE clause must be specified except as indicated in the rule that immediately follows.

  4. The PICTURE clause may be omitted for an elementary item when an alphanumeric or national literal is specified in a format 1 VALUE clause. A PICTURE clause is implied as follows:
    1. if the literal is alphanumeric, 'PICTURE X(length)'
    2. if the literal is national, 'PICTURE N(length)'.

    where length is the length of the literal as specified in the topic Literals in the chapter Concepts of the COBOL Language.

  5. The words THRU and THROUGH are equivalent.
  6. ANS85 The EXTERNAL clause can be specified only in data description entries in the Working-Storage Section whose level-number is 01.
  7. ANS85 The EXTERNAL clause and the REDEFINES clause must not be specified in the same data description entry.
  8. MF The EXTERNAL clause and the THREAD-LOCAL clause must not be specified in the same data description entry.
  9. ANS85 The GLOBAL clause can be specified only in data description entries whose level-number is 01.
  10. ANS85 Data-name-1 must be specified for any entry containing the GLOBAL or EXTERNAL clause, or for record descriptions associated with a file description entry which contains the EXTERNAL or GLOBAL clause.
  11. MF The TYPEDEF clause can only be specified in data description entries whose level-number is 01.
  12. MF The TYPEDEF clause can only be used when data-name-1 is also specified. In other words, it cannot be used in the same data description with either an explicit or implicit FILLER clause.

    Note that if the TYPEDEF clause is specified for a group item, subordinate data descriptions can be defined with either an implicit or explicit FILLER clause.

  13. The clauses SYNCHRONIZED, PICTURE, JUSTIFIED, and BLANK WHEN ZERO must not be specified except for an elementary data item.

    OSVS VSC2 The SYNCHRONIZED clause can be specified for a group item.

  14. MF Literal-6 and integer-1 must not be floating-point values, must not be negative values and must not be more than 18 digits.
  15. If literal-6 is used as part of an expression, it must be an integer.
  16. OSVS VSC2 Data-name-2 and data-name-3 can be implicitly qualified.
  17. ISO2002 The VALUE clause must not be specified for data items of class index, object, or pointer.
  18. ISO2002 MF If the ANY LENGTH clause is specified, the only other clauses permitted are level-number, entry-name, PICTURE, and USAGE.

General Rules

  1. Format 3 is used for each condition-name. Each condition-name requires a separate entry with level-number 88. Format 3 contains the name of the condition and the value, values, or range of values associated with the condition-name. The condition-name entries for a particular conditional variable must immediately follow the entry describing the item with which the condition-name is associated. A condition-name can be associated with any data description entry which contains a level-number except the following:
    1. Another condition-name.
    2. A level 66 item.
    3. A group containing items with descriptions including JUSTIFIED, SYNCHRONIZED or USAGE (other than USAGE IS DISPLAY).
    4. An index

      VSC2 MF or pointer

      data item (see the topic The USAGE Clause).

    5. MF A constant-name.
  2. VSC2 MF Condition-names can be associated with internal floating-point items.

    MF Condition-names can be associated with external floating-point items.

  3. MF Format 4 defines a constant-name, which is a symbolic name representing a constant value assigned to it when the source code is passed through your COBOL system. Your COBOL system replaces each reference to a constant-name by its value.
  4. MF The TYPEDEF clause allows you to declare a group or elementary data description as a type definition, which allows instances of that data description to be declared as data items using data-name-1 as typedef-name-1 in the USAGE clause. The type definition itself is not a data item with allocated storage.
  5. MF If the TYPEDEF clause is specified at a group level, the components of the type definition are implicitly declared for any data item of that type and are referenced using the usual COBOL rules of qualification for the data item.
  6. ENT The VOLATILE clause is documentary only.
  • The ANY LENGTH Clause
    The ANY LENGTH clause specifies that the length of a linkage section item may vary at runtime and is determined by the length of the argument.
  • The BLANK WHEN ZERO Clause
    The BLANK WHEN ZERO clause permits the blanking of an item when its value is zero.
  • The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause
    The ATTRIBUTE or CUSTOM-ATTRIBUTE clause specifies an attribute that provides metadata (information) about a managed code native data item or a property that will be visible using reflection.
  • The Data-name or FILLER Clause
    A data-name specifies the name of the data being described. The word FILLER can be used to specify an elementary item of the logical record that cannot be referred to explicitly.
  • The GROUP-USAGE Clause
    A GROUP-USAGE clause with a BIT phrase specifies that the group item defined by the subject of the entry is to be treated as an elementary item of usage bit and category boolean, unless specified otherwise.
  • The JUSTIFIED Clause
    The JUSTIFIED clause specifies non-standard positioning of data within a receiving data item.
  • Level Number
    The level-number shows the hierarchy of data within a logical record.
  • The OCCURS Clause
    The OCCURS clause eliminates the need for separate entries for repeated data items and supplies information required for the application of subscripts or indices.
  • The PICTURE Clause
    The PICTURE clause describes the general characteristics and editing requirements of an elementary item.
  • The PROPERTY Clause
    The PROPERTY clause indicates that this data item is a property of the object in which this data description is contained and that GET and/or SET methods are to be generated accordingly.
  • The REDEFINES Clause
    The REDEFINES clause allows the same computer storage area to be described by different data description entries.
  • The RENAMES Clause
    The RENAMES clause permits alternative, possibly overlapping, groupings of elementary items.
  • The SIGN Clause
    The SIGN clause specifies the position and the mode of representation of the operational sign when it is necessary to describe these properties explicitly.
  • The SYNCHRONIZED Clause
    The SYNCHRONIZED clause specifies the alignment of an elementary item on the natural boundaries of the computer memory.
  • The TYPEDEF Clause
    The TYPEDEF clause defines a record as a programmer-defined type definition.
  • The USAGE Clause
    The USAGE clause specifies the format of a data item in the computer storage.
  • The VALUE Clause
    The VALUE clause defines the value of constants, the initial value of working storage and local storage items, and the values associated with a condition name.
Parent topic: File and Data Description
Related information
Literals
The USAGE Clause


The ANY LENGTH Clause

The ANY LENGTH clause specifies that the length of a linkage section item may vary at runtime and is determined by the length of the argument.

General Format

  ANY LENGTH

Syntax Rules

  1. The ANY LENGTH clause must be specified only in an elementary level 1 entry in the Linkage Section of a function, of a contained program, or of a method that is not a property method.
  2. If the source element containing the ANY LENGTH clause is a contained program or is a method, the subject of the entry must be referenced in its PROCEDURE DIVISION header as either
    1. A formal parameter with the BY REFERENCE phrase, or
    2. The returning item.
  3. If the source element containing the ANY LENGTH clause is a function, the subject of the entry must be referenced in its PROCEDURE DIVISION header as a formal parameter with the BY REFERENCE phrase.
  4. A PICTURE clause must be specified for the subject of the entry, and the character-string specified in the PICTURE clause must be one instance of the picture symbols 'N' or 'X'.

General Rules

  1. The ANY LENGTH clause specifies that the subject of the entry must be:
    1. A zero-length item when the corresponding argument or returning item of the activating runtime element is a zero-length item, or
    2. Treated as though there were n repetitions of the picture symbol in the character-string in its PICTURE clause, where n is the length of the corresponding argument or returning item of the activating runtime element.
  2. ISO2002 ANY LENGTH can only be used where COBOL calls COBOL in an outer-most program, which can be a sub-program.
Parent topic: Data Description Entry Skeleton


The BLANK WHEN ZERO Clause

The BLANK WHEN ZERO clause permits the blanking of an item when its value is zero.

General Format

Syntax Rules

  1. The BLANK WHEN ZERO clause can be used only for an elementary item whose PICTURE is specified as numeric (with implicit or explicit USAGE IS DISPLAY) or numeric edited. (See the topic The PICTURE Clause.)
  2. The asterisk, when used as the zero suppression symbol, and the clause BLANK WHEN ZERO should not appear in the same entry.

    OSVS This construct is, however, permitted in which case, zero suppression overrides the BLANK WHEN ZERO clause.

General Rules

  1. When the BLANK WHEN ZERO clause is used, the item will contain nothing but spaces if the value of the item is zero.
  2. When the BLANK WHEN ZERO clause is used for an item whose PICTURE is numeric, the category of the item is considered to be numeric edited.
Parent topic: Data Description Entry Skeleton
Related information
The PICTURE Clause


The ATTRIBUTE, CUSTOM-ATTRIBUTE Clause

The ATTRIBUTE or CUSTOM-ATTRIBUTE clause specifies an attribute that provides metadata (information) about a managed code native data item or a property that will be visible using reflection.

Format 1

{ ATTRIBUTE attribute-name(constructor-params, NAME property-name = property-value, ...) } ...

Format 2 (for Backward Compatibility)

{ CUSTOM-ATTRIBUTE IS  class-name-1 [ ( {parameter-1} . . . ) ] }...

Syntax Rules for Format 1

  1. Attribute-name can be specified without quotes and can optionally omit the trailing "Attribute" part of the name.
  2. Constructor-params are the standard parameters to the required attribute constructor. For example:

    attribute Marshal-Attribute(3)

  3. The name/value pairs, preceded by the keyword NAME are used to set any required attribute properties. Property-name can be specified without quotes. For example:

    attribute WebService(NAME Description="My service")

Syntax Rules for Format 2 (for Backward Compatibility)

  4. This list of parameters must match a constructor defined for class-name-1. Each parameter-1 must be one of the following:
    • An ordinary parameter that is the argument to the constructor for that attribute. For example:

      custom-attribute is Marshal-Attribute(3)

    • A named parameter that corresponds to a property defined on the custom attribute class. For example:

      custom-attribute is webservice("Description"="My service")

General Rules

  1. The custom attribute specified becomes part of the metadata describing the subject of the entry and is visible to a reflector.
  2. Languages for JVM support annotations, which are similar broadly to attributes in COBOL.
Parent topic: Data Description Entry Skeleton


The Data-name or FILLER Clause

A data-name specifies the name of the data being described. The word FILLER can be used to specify an elementary item of the logical record that cannot be referred to explicitly.

General Format

Syntax Rules

  1. The data-name or FILLER clause

    ANS85 , if specified,

    must be the first word following the level-number in a data description entry.

General Rules

  1. The key word FILLER can be used to name an elementary item or group in a record. Under no circumstances can a FILLER item be referred to explicitly. However, a data item defined with the key word FILLER can be used as a conditional variable because such use does not require explicit reference to the FILLER item but only to the value contained therein.
  2. ANS85 If this clause is omitted, the data item being described is treated as though FILLER had been specified.
Parent topic: Data Description Entry Skeleton


The GROUP-USAGE Clause

A GROUP-USAGE clause with a BIT phrase specifies that the group item defined by the subject of the entry is to be treated as an elementary item of usage bit and category boolean, unless specified otherwise.

A GROUP-USAGE clause with a NATIONAL phrase specifies that the group item defined by the subject of the entry is to be treated as an elementary item of usage national and category national, unless otherwise specified.

General Format

GROUP-USAGE syntax diagram

Syntax Rules

  1. The GROUP-USAGE clause may be specified only if the subject of the entry is a group item that is not strongly typed.
  2. When the BIT phrase is specified, USAGE BIT is implied for the subject of the entry. A USAGE clause shall not be specified for the subject of the entry. All elementary items subordinate to the subject of the entry shall be explicitly or implicitly described as usage bit, class and category boolean. All subordinate group items shall be explicitly or implicitly described as GROUP-USAGE BIT.

    The maximum number of characters allowed in the group is 64.

  3. When the NATIONAL phrase is specified, USAGE NATIONAL is implied for the subject of the entry. A USAGE clause shall not be specified for the subject of the entry. All elementary items subordinate to the subject of the entry shall be explicitly or implicitly described as usage national. Any signed numeric data items shall be described with the SIGN IS SEPARATE clause. All subordinate group items shall be explicitly or implicitly described as GROUP-USAGE NATIONAL.

General Rules

  1. When the BIT phrase is specified:
    • The subject of the entry is a bit group and also a bit data item; its class and category are boolean.
    • Unless stated otherwise, a bit group is treated as though it were an elementary data item of usage bit and class and category boolean described with PICTURE 1(m), where m is the bit length of the group.
    • Data items contained within a bit group are allocated in storage in accordance with the rules specified in the topic Aligning Bit Data Items.
  2. When the NATIONAL phrase is specified:
    • The subject of the entry is a national group; its class and category are national.
    • Unless stated otherwise, a national group is treated as though it were an elementary data item of usage national and class and category national described with PICTURE N(m), where m is the length of the group.
      Note: The GROUP-USAGE NATIONAL clause is needed so that groups containing only national characters can be properly truncated and padded with national characters and can be correctly processed for operations such as INSPECT. Without the GROUP-USAGE NATIONAL clause, the content of such a group item would be treated as category alphanumeric, possibly leading to corruption or invalid handling of data.
  3. If a GROUP-USAGE clause is not specified or implied for a group item that is not strongly typed, that group item is an alphanumeric group item.
Parent topic: Data Description Entry Skeleton
Related information
The USAGE Clause
The PICTURE Clause


The JUSTIFIED Clause

The JUSTIFIED clause specifies non-standard positioning of data within a receiving data item.

General Format

Syntax Rules

  1. The JUSTIFIED clause can be specified only at the elementary item level.
  2. JUST is an abbreviation for JUSTIFIED.
  3. The JUSTIFIED clause cannot be specified for any data item described as numeric or for which editing is specified.
  4. The JUSTIFIED clause cannot be specified for an index data item (see the section The USAGE Clause)

    VSC2 MF , or for a pointer data item

    .

  5. OSVS VSC2 MF The JUSTIFIED clause cannot be specified for external or internal floating-point data items.

General Rules

  1. When a receiving data item is described with the JUSTIFIED clause and the sending data item is larger than the receiving data item, the leftmost characters are truncated. When the receiving data item is described with the JUSTIFIED clause and it is larger than the sending data item, the data is aligned at the rightmost character position in the data item with space fill for the leftmost character positions.

    The contents of the sending data item are not taken into account, that is, trailing spaces within the sending data item are not suppressed.

    For example, if a data item PIC X(4) whose value is "A   " (that is, A followed by three spaces) is moved into a data item PIC X(6) JUSTIFIED the result is "  A   ". If the same data item is moved to one with PIC X(3) JUSTIFIED the result is "   " that is, the leftmost character is truncated.

  2. When the JUSTIFIED clause is omitted, the standard rules for aligning data within an elementary item apply. (See the topic Standard Alignment Rules in the chapter Concepts of the COBOL Language.)
Parent topic: Data Description Entry Skeleton
Related information
The USAGE Clause
Standard Alignment Rules


Level Number

The level-number shows the hierarchy of data within a logical record.

In addition, it is used to identify entries for working-storage items, linkage items, condition-names

MF , constant-names

and the RENAMES clause.

General Format

Syntax Rules

  1. A level-number is required as the first element in each data description entry.
  2. Data description entries subordinate to an FD or SD entry must have level-numbers with the values 01 through 49, 66

    MF ,78

    or 88. (See the topic File Description Entry Skeleton.)

  3. Data description entries in the Report Section and Screen Section must have level-numbers with the values 01 through 49

    MF , or 78

  4. Data description entries in the Working-Storage Section

    MF , Local-Storage Section

    and Linkage Section must have level-numbers with the values 01 through 49, 66, 77

    MF , 78

    or 88.

  5. A level-number can be a one- or two-digit number.

General Rules

  1. The level-number 01 identifies the first entry in each record description.
  2. Special level numbers have been assigned to certain entries where there is no real concept of level hierarchy:
    1. The level-number 77 is assigned to identify noncontiguous working-storage data items and noncontiguous linkage data items. It can be used only as described by Format 1 of the data description skeleton earlier in this chapter.
    2. Level number 66 is assigned to identify RENAMES entries and can be used only as described in Format 2 of the data description skeleton earlier in this chapter.
    3. Level number 88 is assigned to entries which define condition-names associated with a conditional variable and can be used only as described in Format 3 of the data description skeleton earlier in this chapter.
    4. MF Level number 78 is assigned to entries which define constant-names. It can be used only as described in Format 4 of the data description skeleton earlier in this chapter.
  3. Multiple level 01 entries subordinate to an FD or SD entry represent implicit redefinitions of the same area.
Parent topic: Data Description Entry Skeleton
Related information
File Description Entry Skeleton


The OCCURS Clause

The OCCURS clause eliminates the need for separate entries for repeated data items and supplies information required for the application of subscripts or indices.

General Formats for Format 1

General Formats for Format 2

OCCURS Format 2

General Formats for Format 3

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ODOOSVS – requests OS/VS COBOL compatible processing of the OCCURS DEPENDING ON clause.
    • ODOSLIDE – controls the processing of nested OCCURS DEPENDING ON clauses and fixed data following an OCCURS DEPENDING ON clause.
    • REENTRANT – allows a program to be used in a multi-threaded environment.

Syntax Rules

  1. Where both integer-1 and integer-2 are used, integer-1 must be greater than

    ANS85 OSVS or equal to

    zero and integer-2 must be greater than

    OSVS VSC2 or equal to

    integer-1.

    OSVS VSC2 MF In Format 2, if "integer-1 TO" is omitted, the default value one is assumed.

  2. The data description of data-name-1 must describe an integer.
  3. Data-name-1, data-name-2, data-name-3, ... can be qualified.
  4. Data-name-2 must be either the name of the entry containing the OCCURS clause or the name of an entry subordinate to the entry containing the OCCURS clause.

    OSVS This restriction is removed.

  5. Data-name-3, and so on, must be the name of an entry subordinate to the group item which is the subject of this entry.

    OSVS This restriction is removed.

  6. An INDEXED BY phrase is required if the subject of this entry, or an entry subordinate to this entry, is to be referred to by indexing,

    OSVS VSC2 MF unless it is to be indexed by an index defined for another table (see the section Indexing in the chapter Concepts of the COBOL Language)

    .

    The index-name identified by this clause is not defined elsewhere, and not being data, cannot be associated with any data hierarchy.

  7. A data description entry that contains Format 2 of the OCCURS clause should only be followed, within that record description, by data description entries which are subordinate to it.

    OSVS VSC2 MF A data description entry that contains Format 2 of the OCCURS clause can be followed, within that record description, by data description entries which are not subordinate to it. When the value of the data item referenced by data-name-1 is changed, the position of data items following, but not subordinate to, the table is changed. The data these items contain can be lost.

    MF If the NOODOSLIDE Compiler directive is set, all group items containing the table are considered as always having the maximum number of occurrences, irrespective of the value of data-name-1 and therefore the position of the data items following the table is not changed.

  8. The OCCURS clause cannot be specified in a data description entry that:
    1. Has a 66 or 88 level-number
    2. Describes an item whose size is variable. The size of an item is variable if the data description of any subordinate item contains Format 2 of the OCCURS clause.

      OSVS VSC2 An OCCURS clause can be specified for a data description subordinate to another item with a Format 2 OCCURS clause.

  9. The OCCURS clause should not be specified in a data description entry at the 01 level or as a 77 level-number.

    MF This restriction is removed.

  10. In Format 2, the data item defined by data-name-1 must not occupy a character position within the range of the first character position defined by the data description entry containing the OCCURS clause and the last character position defined by the record description entry containing that OCCURS clause.

    OSVS VSC2 If the ODOSLIDE Compiler directive is set, data-name-1 must have a fixed location.

  11. If data-name-2 is not the subject of this entry, then:
    1. All of the items identified by the data-names in the KEY IS phrase must be within the group item which is the subject of this entry
    2. Items identified by the data-name in the KEY IS phrase must not contain an OCCURS clause
    3. There must not be any entry that contains an OCCURS clause between the items identified by the data-names in the KEY IS phrase and the subject of this entry.
  12. Index-name-1, index-name-2, ... must be unique words within the source element.

    OSVS Index-name-1, index-name-2, ... need not be unique and can be qualified by the data-name which is the subject of this entry

    .

  13. OSVS VSC2 MF The OCCURS clause can be specified for external or internal floating-point data items.
  14. ISO2002 The KEY clause must not be specified for a data item of class object.
  15. NET JVM The Format 3 OCCURS clause must be specified in a data description entry at the 01 level.
  16. NET JVM If the ANY phrase is specified, it must be specified for all dimensions, whether or not OCCURS is repeated.
  17. NET JVM The subject of the entry for a Format 3 OCCURS clause must be a .NET native type as specified in the topic .NET Native Types in the section .NET Concepts in the Language Fundamentals chapter.

General Rules

  1. The OCCURS clause is used in defining tables and other homogenous sets of repeated data items. Whenever the OCCURS clause is used, the data-name which is the subject of this entry must be either subscripted or indexed whenever it is referred to in a statement other than SEARCH

    MF , SORT

    or USE FOR DEBUGGING. Further, if the subject of this entry is the name of a group item, then all data-names belonging to the group must be subscripted or indexed whenever they are used as operands, except as the object of a REDEFINES clause. (See the topics Subscripting, Indexing and Identifier in the chapter Concepts of the COBOL Language.)

  2. Except for the OCCURS clause itself, all data description clauses associated with an item whose description includes an OCCURS clause apply to each occurrence of the item described.
  3. UNBOUNDED can be used to specify an unbounded table (a table with an unbounded maximum number of occurrences), and can be referenced anywhere that a table can be referenced.
  4. An unbounded group is a group that contains at least one unbounded table. It can be specified only in the Linkage Section, and must be of type alphanumeric or national.
  5. You can reference unbounded groups in COBOL syntax anywhere that an alphanumeric or national group can be referenced, with the following exceptions:
    • You cannot specify unbounded groups as a BY CONTENT argument in a CALL statement.
    • You cannot specify unbounded groups as data-name-2 on the Procedure Division RETURNING phrase.
    • You cannot specify unbounded groups as arguments to intrinsic functions, except as an argument to the LENGTH intrinsic function.
  6. Data-name-1 must have a fixed location, and must not follow an item that contains an OCCURS DEPENDING ON clause.
  7. The number of occurrences of the subject entry is defined as follows:
    1. In Format 1, the value of integer-2 represents the exact number of occurrences.
    2. In Format 2, the current value of the data item referenced by data-name-1 represents the number of occurrences.

      This format specifies that the subject of this entry has a variable number of occurrences. The value of integer-2 represents the maximum number of occurrences and the value of integer-1 represents the minimum number of occurrences. This does not imply that the length of the subject of the entry is variable, but that the number of occurrences is variable.

      The value of the data item referenced by data-name-1 must fall within the range of integer-1 through integer-2. Reducing the value of this data item makes the contents of data items, whose occurrence numbers now exceed the value of the data item referenced by data-name-1, unpredictable.

  8. ANS85 When a group item, having subordinate to it an entry that specifies Format 2 of the OCCURS clause, is referenced, the part of the table area used in the operation is determined as follows:
    1. If the data item referenced by data-name-1 is outside the group, only that part of the table area that is specified by the value of the data item referenced by data-name-1 at the start of the operation is used.
    2. If the data item referenced by data-name-1 is included in the same group and the group data item is referenced as a sending item, only that part of the table area that is specified by the value of the data item referenced by data-name-1 at the start of the operation is used in the operation. If the group is a receiving item, the maximum length of the group is used.
  9. The KEY IS phrase is used to indicate that the repeated data is arranged in ascending or descending order according to the values contained in data-name-2, data-name-3, and so on. The ascending or descending order is determined according to the rules for comparison of operands (see the topics Comparison of Numeric Operands and Comparison of Nonnumeric Operands in the topic Relation Condition in the chapter Procedure Division). The data-names are listed in their descending order of significance.
  10. The type of storage allocated for index-name-1, index-name-2... depends on whether or not the program is recursive (that is, has a Local-Storage Section defined) and whether the REENTRANT Complier directive has been specified.

    The first of the tables below specifies how storage is allocated for non-recursive programs. The second table specifies how storage is allocated for recursive programs.

    Table 1. Storage Allocated for Index-name in Non-Recursive Program
    Index-name Defined in | Index-name Allocated in
    NOREENTRANT | REENTRANT (1) | REENTRANT (2)
    working storage | working storage | working storage | thread-local
    thread-local | thread-local | thread-local | thread-local
    linkage | working storage | local storage | local storage
    Table 2. Storage Allocated for Index-name in Recursive Program
    Index-name Defined in | Index-name Allocated in
    NOREENTRANT | REENTRANT (1) | REENTRANT (2)
    working storage | working storage | working storage | thread-local
    thread-local | thread-local | thread-local | thread-local
    local storage | local storage | local storage | local storage
    linkage | local storage | local storage | local storage
  11. NET JVM An entry with a Format 3 OCCURS clause defines an array that is mapped directly to a .NET native array. In COBOL, the first array element has the subscript one.
  12. NET JVM If the ANY phrase is specified, a SET statement with either the SIZE phrase or the CONTENT phrase must be executed on the array before an element of the array can be referenced.
  13. NET JVM A Format 3 OCCURS clause that repeats the option containing ANY and integer-2 defines a rectangular array, one in which all rows and columns have the same size.
  14. NET JVM Repetition of the Format 3 OCCURS clause defines a jagged array, or an array of arrays in which the various sub-arrays can have different lengths.
Parent topic: Data Description Entry Skeleton
Related concepts
Nested OCCURS DEPENDING Clauses
Numeric Fields Containing Illegal Characters When Using a DEPENDING ON Phrase of an OCCURS Clause
Related information
Subscripting
Indexing
Identifier
Relation Condition


The PICTURE Clause

The PICTURE clause describes the general characteristics and editing requirements of an elementary item.

General Format

Syntax Rules

  1. A PICTURE clause can be specified only at the elementary item level.
  2. A character-string consists of certain allowable combinations of characters in the COBOL character set used as symbols. The allowable combinations determine the category of the elementary item.
  3. The maximum number of characters allowed in the character-string is 30.

    ISO2002 MF OS390 The maximum number of characters allowed in the character-string is 50.

  4. The PICTURE clause must not be specified for the subject of a RENAMES clause.
  5. PIC is an abbreviation for PICTURE.
  6. The asterisk when used as the zero suppression symbol and the clause BLANK WHEN ZERO should not appear in the same entry.

    OSVS This construct is, however, permitted, in which case zero suppression overrides the BLANK WHEN ZERO clause.

  7. An integer in parentheses following a character indicates that the character is repeated the number of times shown by the integer.

General Rules

The categories of data that can be described with a PICTURE clause are: alphabetic, numeric, alphanumeric, alphanumeric edited, numeric edited,

OSVS VSC2 MF external floating-point,

ISO2002 MF and boolean.

General rules within these categories are given below:

Alphabetic Data Rules

  1. The PICTURE character-string can contain only the symbols "A" and "B".

    ANS85 The PICTURE character-string can contain only the symbol "A".

  2. The contents when represented in standard data format must be one or more alphabetic characters.

Numeric Data Rules

  3. The PICTURE character-string can contain only the symbols "9", "P", "S", and "V", and can contain up to 18 digit positions; or:

    ISO2002 OS390 The PICTURE character-string can contain up to 31 digit positions; or:

    MF The PICTURE character-string can contain up to 38 digit positions.

  4. If unsigned, the data in standard data format must be a combination of the Arabic numerals "0", "1", "2", " 3", "4", "5", "6", "7", "8", and "9"; if signed, the item can also contain a "+", "-", or other representation of an operational sign. (See the topic The SIGN Clause.)

Alphanumeric Data Rules

  5. The PICTURE character-string is restricted to certain combinations of the symbols " A", "X", "9", and the item is treated as if the character-string contained all X"s. A PICTURE character-string which contains all A"s or all 9"s does not define an alphanumeric item.
  6. The contents when represented in standard data format can consist of any characters in the computer's character set.

Alphanumeric Edited Data Rules

  7. The PICTURE character-string is restricted to certain combinations of the following symbols: "A", "X", " 9", "B", "0", and "/" as follows:
    1. The character-string must contain at least one "B" and at least one "X" or at least one "0" (zero) and at least one "X" or at least one "/" (slash) and at least one "X", or:
    2. The character-string must contain at least one "0" (zero) and at least one "A" or at least one "/" (slash) and at least one "A".
  8. The contents when represented in standard data format can consist of any characters in the computer's character set.

Numeric Edited Data Rules

  9. The PICTURE character-string is restricted to certain combinations of the symbols "B", "/", "P", "V" , "Z", "0", "9", ",", ".", "*", "+", "-", "CR", "DB", and the currency symbol. The allowable combinations are determined from the order of precedence of symbols and the editing rules as follows:
    1. The PICTURE character-string can contain up to 18 digit positions; or:

      ISO2002 OS390 The PICTURE character-string can contain up to 31 digit positions; or:

      MF The PICTURE character-string can contain up to 38 digit positions.

    2. The character-string must contain at least one "0" , "B", "/", "Z", "*", "+", ",", ".", "-", "CR" , "DB", or currency symbol.
  10. The contents of the character positions that represent a digit must be one of the numerals.
  11. If all character positions in the PICTURE character-string are represented by an insertion character, at least one of the insertion characters must be positioned to the left of the decimal point.

External Floating-point Data Items

  12. The PICTURE string must have the following form:

    A sign character must immediately precede both the significand and the exponent.

    A "+" sign indicates that a positive sign will be used in the output to represent positive values and that a negative sign will represent negative values.

    A "-"sign indicates that a blank will be used in the output to represent positive values and that a negative sign will represent negative values.

    Each sign position occupies one byte of storage.

    significand

    The significand can contain the symbols:

    9 . V

    An actual decimal point can be represented with a period while an assumed decimal point is represented by a V. Either an actual or an assumed decimal point must be present in the significand; the decimal point can be leading, embedded or trailing. The significand can contain from 1 to 16 numeric characters.

    E

    Indicates the exponent.

    exponent

    The exponent must be a PIC "99".

  13. The OCCURS, REDEFINES and RENAMES clauses can be associated with external floating-point items.
  14. The SIGN clause is documentary only and has no effect on the representation of the sign.
  15. The SYNCHRONIZED clause is documentary only.
  16. The following clauses are invalid with external floating-point items:

    BLANK WHEN ZERO JUSTIFIED VALUE

Boolean Data Rules

  17. The PICTURE character-string can contain only the symbol "1".
  18. The PICTURE character-string can contain up to 64 digit positions.
  19. Values can be specified in literals with an opening separator B", for example B"1110", where the value is expressed as bits.

Comments:

The size of an elementary item, where size means the number of character positions occupied by the elementary item in standard data format, is determined by the number of allowable symbols that represent character positions. An integer which is enclosed in parentheses following the symbols "A", ",", "X" , "9", "P", "Z", "*", "B", "/", "0", "+", "-", or the currency symbol indicates the number of replications of the symbol. Note that the following symbols can appear only once in a given PICTURE: "S" , "V", ".", "CR", and "DB",

OSVS VSC2 MF "E".

The functions of the symbols used to describe an elementary item are explained as follows:

A | Each "A" in the character-string represents a character position which can contain only a letter of the alphabet or a space.
B | Each "B" in the character-string represents a character position into which the space character will be inserted.
OSVS VSC2 MF E | Marks the start of the exponent in an external floating-point item. The exponent occupies 1 byte of storage at run time.
P Each "P" indicates an assumed decimal scaling position and is used to specify the location of an assumed decimal point when the point is not within the number that appears in the data item. The scaling position character "P" is not counted in the size of the data item. Scaling position characters are counted in determining the maximum number of digit positions in numeric edited items or numeric items. The scaling position character "P" can appear only to the left or right as a continuous string of "P"s within a PICTURE description; since the scaling position character "P" implies an assumed decimal point (to the left of "P" s if "P"s are leftmost PICTURE characters and to the right if "P"s are rightmost PICTURE characters), the assumed decimal point symbol "V" is redundant as either the leftmost or rightmost character within such a PICTURE description.

The character "P" and the insertion character "." (period) cannot both occur in the same PICTURE character-string. If, in any operation involving conversion of data from one form of internal representation to another, the data item being converted is described with the PICTURE character "P", each digit position described by a "P" is considered to contain the value zero, and the size of the data item is considered to include the digit positions so described.

ANS85 In certain operations that reference a data item whose PICTURE character-string contains the symbol "P", the algebraic value of the data item is used rather than the actual character representation of the data item. This algebraic value assumes the decimal point in the prescribed location and zero in place of the digit position specified by the symbol "P". The size of the value is the number of digit positions represented by the PICTURE character-string. These operations are any of the following:

  1. Any operation requiring a numeric sending operand.
  2. An elementary MOVE statement where the sending operand is numeric and its PICTURE character-string contains the symbol "P".
  3. A MOVE statement where the sending operand is numeric edited and its PICTURE character-string contains the symbol "P" and the receiving operand is numeric or numeric edited.
  4. A comparison operation where both operands are numeric.

ANS85 In all other operations the digit positions specified with the symbol "P" are ignored and are not counted in the size of the operand.

S | The letter "S" is used in a character-string to indicate the presence, but neither the representation nor, necessarily, the position of an operational sign; it must be written as the leftmost character in the PICTURE. The "S" is not counted in determining the size (in terms of standard data format characters) of the elementary item unless the entry is subject to a SIGN clause which specifies the optional SEPARATE CHARACTER phrase. (See the topic The SIGN Clause.)
V | The letter "V" is used in a character-string to indicate the location of the assumed decimal point and can only appear once in a character-string. The "V" does not represent a character position and therefore is not counted in the size of the elementary item. When the assumed decimal point is to the right of the rightmost symbol in the string the "V" is redundant.
X | Each "X" in the character-string is used to represent a character position which contains any allowable character from the computer's character set.
Z | Each "Z" in a character-string can only be used to represent the leftmost numeric character positions which will be replaced by a space character when the contents of that character position is zero. Each "Z" is counted in the size of the item.
9 | Each "9" in the character-string represents a character position which contains a numeral and is counted in the size of the item.
0 | Each "0" (zero) in the character-string represents a character position into which the numeral zero will be inserted. The "0" is counted in the size of the item.
/ Each "/" (slash) in the character-string represents a character position into which the slash character will be inserted. The "/" is counted in the size of the item.
, Each "," (comma) in the character-string represents a character position into which the character "," will be inserted. This character position is counted in the size of the item. The insertion character "," must not be the last character in the PICTURE character-string.

ANS85 The insertion character "," can be the last character in the PICTURE character-string.

. When the character "." (period) appears in the character-string it is an editing symbol which represents the decimal point for alignment purposes and, in addition, represents a character position into which the character "." will be inserted. The character "." is counted in the size of the item. For a given source unit the functions of the period and comma are exchanged if the clause DECIMAL-POINT IS COMMA is stated in the Special-Names paragraph. In this exchange the rules for the period apply to the comma and the rules for the comma apply to the period wherever they appear in a PICTURE clause. The insertion character " ." must not be the last character in the PICTURE character-string.

ANS85 The insertion character "." can be the last character in the PICTURE character-string.

+, -, CR, DB | These symbols are used as editing sign control symbols. When used, they represent the character position into which the editing sign control symbol will be placed. The symbols are mutually exclusive in any one character-string and each character used in the symbol is counted in determining the size of the data item.
* Each "*" (asterisk) in the character-string represents a leading numeric character position into which an asterisk will be placed when the contents of that position is zero. Each "*" is counted in the size of the item.
cs A currency symbol represents character positions into which the currency string will be placed during editing. A currency symbol is represented in character-string-1 either by the currency sign or by the currency symbol specified in a CURRENCY SIGN clause in the Special-Names paragraph.

The first occurrence of the currency symbol adds the number of characters in the currency string to the size of the item. Each subsequent occurrence of the currency symbol adds one to the size of the item.

The CURRENCY-SIGN Compiler directive also affects the currency symbol used.

Two general methods of performing editing in the PICTURE clause are available: insertion or suppression and replacement. Four types of insertion editing are available:

  1. Simple insertion
  2. Special insertion
  3. Fixed insertion
  4. Floating insertion

Two types of suppression and replacement editing are available:

  1. Zero suppression and replacement with spaces
  2. Zero suppression and replacement with asterisks

The type of editing which can be performed upon an item is dependent upon the category to which the item belongs. The table below specifies which type of editing can be performed upon a given category.

Table 1. EditingTypes For Data Categories
Category | Type of Editing
Alphabetic | Simple insertion "B" only 1
Numeric | None
Alphanumeric | None
Alphanumeric edited | Simple insertion "0", "B" and "/"
Numeric edited | All 2
DBCS | Simple insertion
External floating-point | Special insertion
Note:
  1. ANS85 In the ANSI'74 standard, PICTURE clauses containing both "A" and "B" are treated as simple insertion in category Alphabetic. As the ANSI'85 standard does not support "B" in the Alphabetic category, the ANSI'85 standard considers this PICTURE as simple insertion in the Alphanumeric Edited category.
  2. Floating insertion editing and editing by zero suppression and replacement are mutually exclusive in a PICTURE clause. Only one type of replacement can be used with zero suppression in a PICTURE clause.

The "," (comma), "B" (space), "0" (zero), and " /" (slash) are used as the insertion characters. The insertion characters are counted in the size of the item and represent the position in the item into which the character will be inserted.

OSVS VSC2 MF This type of editing is valid for either numeric edited items or external floating-point items.

The "." (period) is used as the insertion character. In addition to being an insertion character it represents the decimal point for alignment purposes. The insertion character used for the actual decimal point is counted in the size of the item. The use of the assumed decimal point, represented by the symbol "V" and the actual decimal point, represented by the insertion character, in the same PICTURE character-string is disallowed. The result of special insertion editing is the appearance of the insertion character in the item in the same position as shown in the character-string.

The currency string and the editing sign control symbols "+" , "-", "CR", "DB" are the insertion characters. Only one currency symbol and only one of the editing sign control symbols can be used in a given PICTURE character-string. When the symbols "CR" or "DB" are used, they represent two character positions in determining the size of the item and they must represent the rightmost character positions that are counted in the size of the item. The symbol "+" or "-", when used, must be either the leftmost or rightmost character position to be counted in the size of the item. The currency symbol must be the leftmost character.

Table 2. Editing Symbols in PICTURE Character-Strings
Editing Symbol in Picture Character-string | Result
 | Data Item Positive or Zero | Data Item Negative
+ | + | -
- | space | -
CR | 2 spaces | CR
DB | 2 spaces | DB

The currency symbol and the editing sign control symbols "+" and "-" are the floating insertion symbols and as such are mutually exclusive in a given PICTURE character-string.

Floating insertion editing is indicated in a PICTURE character-string by using a string of at least two of the floating insertion symbols. This string of floating insertion characters can contain any of the simple insertion characters or have simple insertion characters immediately to the right of this string. These simple insertion characters are part of the floating string.

When the floating insertion character is the currency symbol, this string of floating insertion characters can have one of the editing sign control symbols "+", "-", "CR" or " DB" immediately to the right of this string.

The leftmost character of the floating insertion string represents the leftmost limit of the floating symbol in the data item. The rightmost character of the floating string represents the rightmost limit of the floating symbols in the data item.

The second floating character from the left represents the leftmost limit of the numeric data that can be stored in the data item. Non-zero numeric data can replace all the characters at or to the right of this limit.

Floating insertion editing can be represented in a PICTURE character-string in only two ways. One way is to represent any or all of the leading numeric character positions on the left of the decimal point by the insertion character. The other way is to represent all of the numeric character positions in the PICTURE character-string by the insertion character.

If the insertion characters are only to the left of the decimal point in the PICTURE character-string, the result is that a single floating insertion character will be placed into the character position immediately preceding either the decimal point or the first non-zero digit in the data represented by the insertion symbol string, whichever is farther to the left in the PICTURE character-string. The character positions preceding the insertion character are replaced with spaces.

If all numeric character positions in the PICTURE character-string are represented by the insertion character, the result depends upon the value of the data. If the value is zero, the entire data item will contain spaces. If the value is not zero, the result is the same as when the insertion character is only to the left of the decimal point.

ANS85 If all numeric positions in the PICTURE character string are represented by the insertion character, at least one numeric position must be to the left of the assumed or actual decimal point.

To avoid truncation, the minimum size of the PICTURE character-string for the receiving data item must be the number of characters in the sending data item, plus the number of non-floating insertion characters being edited into the receiving data item, plus one for the floating insertion character.

The suppression of leading zeros in numeric character positions is indicated by the use of the alphabetic character "Z" or the character "*" (asterisk) as suppression symbols in a PICTURE character-string. These symbols are mutually exclusive in a given PICTURE character-string. Each suppression symbol is counted in determining the size of the item. If "Z" is used, the replacement character will be the space and if the asterisk is used, the replacement character will be "*".

Zero suppression and replacement is indicated in a PICTURE character-string by using a string of one or more of the allowable symbols to represent leading numeric character positions which are to be replaced when the associated character position in the data contains a zero. Any of the simple insertion characters embedded in the string of symbols or to the immediate right of this string are part of the string.

Zero suppression can be represented in a PICTURE character-string in only two ways. One way is to represent any or all of the leading numeric character positions to the left of the decimal point by suppression symbols. The other way is to represent all of the numeric character positions in the PICTURE character-string by suppression symbols.

If the suppression symbols appear only to the left of the decimal point, any leading zero in the data which corresponds to a symbol in the string is replaced by the replacement character. Suppression terminates at the first non-zero digit in the data represented by the suppression symbol string or at the decimal point, whichever is encountered first.

If all numeric character positions in the PICTURE character-string are represented by suppression symbols and the value of the data is not zero, the result is the same as if the suppression characters were only to the left of the decimal point. If the value is zero and the suppression symbol is "Z", the entire data item will be spaces. If the value is zero and the suppression symbol is "*", the data item will be all "*" except for the actual decimal point.

The symbols "+", "-", "*", " Z" and the currency symbol, when used as floating replacement characters, are mutually exclusive within a given character-string.

The table below shows the order of precedence when using characters as symbols in a character-string. An "X" at an intersection indicates that the symbol(s) at the top of the column can precede, in a given character-string, the symbol(s) at the left of the row. Arguments appearing in braces indicate that the symbols are mutually exclusive. The currency symbol is indicated by the symbol "cs". At least one of the symbols "A " , "X", "Z", " 9" or "*", or at least two of the symbols "+" , "-" or "cs" must be present in a PICTURE string.

In this table, non-floating insertion symbols "+" and "-" , floating insertion symbols "Z", "*", " +", "-", and "cs", and other symbol "P" appear twice in the PICTURE character precedence chart. The leftmost column and uppermost row for each symbol represents its use to the left of the decimal point position. The second appearance of symbol in the row and column represents its use to the right of the decimal point position.

Table 3. PICTURE Character Precedence Chart
First Symbol |  | Non-Floating Insertion Symbols |  |  |  |  |  |  |  |  |  | Floating Insertion Symbols |  |  |  |  |  | Other Symbols
Second Symbol |  | B | 0 | / | , | . | + - | + - | CR DB | C S | E | Z * | Z * | + - | + - | C S | C S | 9 | A X | S | V | P | P | G | 1
Non-Floating Insertion Symbols | B | X | X | X | X | X |  |  |  | X |  | X | X | X | X | X | X | X | X |  | X |  | X | X |
 | 0 | X | X | X | X | X |  |  |  | X |  | X | X | X | X | X | X | X | X |  | X |  | X |  |
 | / | X | X | X | X | X |  |  |  | X |  | X | X | X | X | X | X | X | X |  | X |  | X |  |
 | , | X | X | X | X | X |  |  |  | X |  | X | X | X | X | X | X | X |  |  | X |  | X |  |
 | . | X | X | X | X | X |  |  |  | X |  | X |  | X |  | X |  | X |  |  |  |  |  |  |
 | + - |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 | + - | X | X | X | X | X |  |  |  | X | X | X | X |  |  | X | X | X |  |  | X | X | X |  |
 | CR DB | X | X | X | X | X |  |  |  | X |  | X | X |  |  | X | X | X |  |  | X | X | X |  |
 | CC S |  |  |  |  |  | X |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 | E |  |  |  | X | X |  |  |  |  |  |  |  |  |  |  |  | X |  |  | X |  |  |  |
Floating Insertion Symbols | Z * | X | X | X | X |  | X |  |  | X |  | X |  |  |  |  |  |  |  |  |  |  |  |  |
 | Z * | X | X | X | X | X | X |  |  | X |  | X | X |  |  |  |  |  |  |  | X |  | X |  |
 | + - | X | X | X | X |  |  |  |  | X |  |  |  | X |  |  |  |  |  |  |  |  |  |  |
 | + - | X | X | X | X | X |  |  |  | X |  |  |  | X | X |  |  |  |  |  | X |  |  |  |
 | C S | X | X | X | X |  | X |  |  |  |  |  |  |  |  | X |  |  |  |  |  |  |  |  |
 | C S | X | X | X | X | X | X |  |  |  |  |  |  |  |  | X | X |  |  |  | X |  |  |  |
Other Symbols | 9 | X | X | X | X | X | X |  |  | X | X | X |  | X |  | X |  | X | X | X | X |  | X |  |
 | A X | X | X | X |  |  |  |  |  |  |  |  |  |  |  |  |  | X | X |  |  |  |  |  |
 | S |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
 | V | X | X | X | X |  | X |  |  | X |  | X |  | X |  |  |  | X |  | X |  | X |  |  |
 | P | X | X | X | X |  | X |  |  | X |  | X |  | X |  |  |  | X |  | X |  | X |  |  |
 | P |  |  |  |  |  | X |  |  | X |  |  |  |  |  |  |  |  |  | X | X |  | X |  |
 | G | X |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | X |
 | 1 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | X
Parent topic: Data Description Entry Skeleton
Related information
The SIGN Clause
The USAGE Clause
Selection of Character Representation And Radix


The PROPERTY Clause

The PROPERTY clause indicates that this data item is a property of the object in which this data description is contained and that GET and/or SET methods are to be generated accordingly.

General Format

Syntax Rules

  1. The PROPERTY clause can be specified only in the Working-Storage Section of a factory definition or an object definition.
  2. The PROPERTY clause must not be specified for data items subordinate to an OCCURS clause.
  3. The PROPERTY clause can be specified only for an elementary item whose name does not require qualification for uniqueness of reference.
  4. The data-name for the subject of the entry must not be the same as a property-name defined in a superclass.
    Note: A property-name may be defined in a superclass either by defining a method or a pair of methods with the PROPERTY phrase or by describing a data description entry with the PROPERTY clause.

General Rules

  1. If the GET phrase is not specified, the PROPERTY clause causes a method to be defined for the containing factory or object.

    If the subject of this entry is of class index, object, or pointer, the implicit definition of this method is as follows:

     METHOD-ID. GET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION RETURNING LS-data-name.
 par-name.
     SET LS-data-name TO data-name
     EXIT METHOD.
 END METHOD.

    If the subject of this entry is of category alphanumeric-edited, national-edited, or numeric-edited, the implicit definition of this method is as follows:

     METHOD-ID. GET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION RETURNING LS-data-name.
 par-name.
     MOVE data-name TO LS-data-name (1:).
     EXIT METHOD.
 END METHOD.
    Note: If the subject of the entry is edited, reference modification of the receiving item as the whole of itself prevents the editing rules from being reapplied to the data.

    Otherwise, the implicit definition of this method is as follows:

     METHOD-ID. GET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION RETURNING LS-data-name.
 par-name.
     MOVE data-name TO LS-data-name
     EXIT METHOD.
 END METHOD.

    where LS-data-name has the data description of the subject of the entry, including its subordinate items, with the exception of:

    • INDEXED BY phrases
    • PROPERTY clauses
    • VALUE clauses
    • a REDEFINES clause in the description of the subject of the entry.
  2. If the SET phrase is not specified, the PROPERTY clause causes a method to be defined for the containing factory or object.

    If the subject of this entry is of class index, object, or pointer, the implicit definition of this method is as follows:

     METHOD-ID. SET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION USING LS-data-name.
 par-name.
     SET data-name TO LS-data-name
     EXIT METHOD.
 END METHOD.

    If the subject of this entry is of category alphanumeric-edited, national-edited, or numeric-edited, the implicit definition of this method is as follows:

     METHOD-ID. SET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION USING LS-data-name.
 par-name.
     MOVE LS-data-name TO data-name (1:).
     EXIT METHOD.
 END METHOD.
    Note: If the subject of the entry is edited, reference modification of the receiving item as the whole of itself prevents the editing rules from being reapplied to the data.

    Otherwise, the implicit definition of this method is as follows:

     METHOD-ID. SET PROPERTY data-name.
 DATA DIVISION.
 LINKAGE SECTION.
 01 LS-data-name data-description.
 PROCEDURE DIVISION USING LS-data-name.
 par-name.
     MOVE LS-data-name TO data-name
     EXIT METHOD.
 END METHOD.

    where LS-data-name has the data description of the subject of the entry, including its subordinate items, with the exception of:

    • INDEXED BY phrases
    • PROPERTY clauses
    • VALUE clauses
    • A REDEFINES clause in the description of the subject of the entry.
Parent topic: Data Description Entry Skeleton


The REDEFINES Clause

The REDEFINES clause allows the same computer storage area to be described by different data description entries.

General Format

Note that level-number and data-name-1

ANS85 or FILLER

are shown in the above format to improve clarity. Level-number, and data-name-1

ANS85 and FILLER

are not part of the REDEFINES clause.

Syntax Rules

  1. The REDEFINES clause, when specified, must immediately follow data-name-1

    ANS85 or FILLER,

    MF or it can follow the PICTURE or USAGE clause

    .

  2. The level-numbers of data-name-1 and data-name-2 must be identical but must not be 66,

    MF 78

    or 88.

  3. This clause must not be used in level 01 entries in the File Section, since multiple level 01 entries subordinate to an FD or SD indicator represent implicit redefinitions of the same areas. (See General Rule 2 in the topic The DATA RECORDS Clause.)

    MF This clause can be used on level 01 entries in the File Section.

  4. OSVS VSC2 The data description for data-name-2 can contain a REDEFINES clause and

    data-name-2 can be subordinate to an entry which contains a REDEFINES clause. Its data description cannot contain an OCCURS clause. However, data-name-2 can be subordinate to an item whose data description entry contains an OCCURS clause. In this case, the reference to data-name-2 in the REDEFINES clause cannot be subscripted or indexed. Neither the original definition nor the redefinition can include an item whose size is variable as defined in the OCCURS clause. (See the topic The OCCURS Clause.)

    OSVS MF The data description for data-name-2 can contain an OCCURS clause.

    MF If the level number is 01, either or both of the original definition and the redefinition can include an item whose size is variable as defined in the OCCURS clause.

  5. No entry having a level-number numerically lower than the level-number of data-name-2 and data-name-1 can occur between the data description entries of data-name-2 and data-name-1.
  6. OSVS VSC2 MF An external or internal floating-point data item can be the subject or object of a REDEFINES clause.
  7. ANS85 Data-name-2 must not be qualified even if it is not unique since no ambiguity of reference exists in this case because of the required placement of the REDEFINES clause .

    OSVS Data-name-2 may be qualified but any qualification specified is ignored.

  8. The entries giving the new description of the character positions must not contain any VALUE clauses except in condition-name entries.
  9. ISO2002 The REDEFINES clause must not be specified for a data item of class object.

    MF The REDEFINES clause may be specified for a data item of class object.

  10. ISO2002 Data-name-2 must not be of class object.

    MF Data-name-2 may be of class object.

  11. ISO2002 MF Data-name-2 must not be described with the ANY LENGTH clause.

General Rules

  1. Redefinition starts at data-name-2 and ends when a level-number less than or equal to that of data-name-2 is encountered.
  2. When the level-number of data-name-1 is other than 01, it must specify the same number of character positions that the data item referenced by data-name-2 contains

    ANS85 OSVS except that the data-name-1 area can be either smaller than the data-name-2 area

    MF or be larger than the data-name-2 area. In this case, extra storage is reserved to provide sufficient storage for the number of character positions in the largest of the redefining or redefined items.

    It is important to observe that the REDEFINES clause specifies the redefinition of a storage area, not of the data items occupying the area.

  3. Multiple redefinitions of the same character positions are permitted. The entries giving the new descriptions of the character positions must follow the entries defining the area being redefined, without intervening entries that define new character positions. Multiple redefinitions of the same character positions must all use the data-name of the entry that originally defined the area

    OSVS VSC2 MF or the data-name of any other preceding redefinition of that entry

    .

  4. Multiple level 01 entries subordinate to any given level indicator (FD or SD) represent implicit redefinitions of the same area.
Parent topic: Data Description Entry Skeleton
Related information
The DATA RECORDS Clause
The OCCURS Clause


The RENAMES Clause

The RENAMES clause permits alternative, possibly overlapping, groupings of elementary items.

General Format

Level-number 66 and data-name-1 are shown in the above format to improve clarity. Level-number and data-name-1 are not part of the RENAMES clause.

Syntax Rules

  1. Any number of RENAMES entries can be written for a logical record.
  2. All RENAMES entries referring to data items within a given logical record must immediately follow the last data description entry of the associated record description entry.
  3. Data-name-2 and data-name-3 must be names of elementary items or groups of elementary items in the same logical record, and cannot be the same data-name. A 66 level entry cannot rename another 66 level entry, nor can it rename a 77,

    MF 78,

    88, or 01 entry.

    MF A 66 level entry may rename another 66 level entry or a level 77 or level 01 entry.

  4. Data-name-1 cannot be used as a qualifier, and can be qualified only by the names of the associated level 01, FD or SD entries. Neither data-name-2 nor data-name-3 can have an OCCURS clause in its data description entry, nor be subordinate to an item that has an OCCURS clause in its data description entry. (See the topic The OCCURS Clause.)
  5. The beginning of the area described by data-name-3 must not be to the left of the beginning of the area described by data-name-2. The end of the area described by data-name-3 must be to the right of the end of the area described by data-name-2. Data-name-3, therefore, cannot be subordinate to data-name-2.
  6. Data-name-2 and data-name-3 can be qualified.
  7. The words THRU and THROUGH are equivalent.
  8. None of the items within the range, including data-name-2 and data-name-3, if specified, can be an item whose size is variable as defined in the topic The OCCURS Clause.

General Rules

  1. When data-name-3 is specified, data-name-1 is a group item which includes all elementary items starting with data-name-2 (if data-name-2 is an elementary item) or the first elementary item in data-name-2 (if data-name-2 is a group item), and concluding with data-name-3 (if data-name-3 is an elementary item) or the last elementary item in data-name-3 (if data-name-3 is a group item).
  2. When data-name-3 is not specified, all of the attributes of data-name-2 become the data attributes for data-name-1.
  3. OSVS When data-name-2 and data-name-3 are not explicitly qualified and when no ambiguity of reference exists, implied qualification of the 01 level item is used.
Parent topic: Data Description Entry Skeleton
Related information
The OCCURS Clause


The SIGN Clause

The SIGN clause specifies the position and the mode of representation of the operational sign when it is necessary to describe these properties explicitly.

General Format

Syntax Rules

  1. The SIGN clause can be specified only for a numeric data description entry whose PICTURE contains the character "S" , or a group item containing at least one such numeric data description entry.
  2. The numeric data description entries to which the SIGN clause applies must be described, implicitly or explicitly, as USAGE IS DISPLAY.
  3. At most one SIGN clause can apply to any given numeric data description entry.

    ANS85 This rule is removed.

  4. If the CODE-SET clause is specified, any signed numeric data description entries associated with that file description entry must be described with the SIGN IS SEPARATE clause.

    MF This restriction is not enforced. See the topic The CODE-SET Clause.

General Rules

  1. The optional SIGN clause, if present, specifies the position and the mode of representation of the operational sign for the numeric data description entry to which it applies, or for each numeric data description entry subordinate to the group to which it applies. The SIGN clause applies only to numeric data description entries whose PICTURE contains the character "S"; the "S" indicates the presence of, but neither the representation nor, necessarily, the position of the operational sign.
  2. A numeric data description entry whose PICTURE contains the character "S", but to which no optional SIGN clause applies, has an operational sign, but neither the representation nor, necessarily, the position of the operational sign is specified by the character "S". In this (default) case, General Rules 3 through 5 do not apply to such signed numeric data items. The representation of the default operational sign is defined in the topic Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.
  3. If the optional SEPARATE CHARACTER phrase is not present, then:
    1. The operational sign is presumed to be associated with the leading (or, respectively, trailing) digit position of the elementary numeric data item in a manner defined in the topic Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.
    2. The letter "S" in a PICTURE character-string is not counted in determining the size of the item (in terms of standard data format characters).
  4. If the optional SEPARATE CHARACTER phrase is present, then:
    1. The operational sign is presumed to be the leading (or, respectively, trailing) character position of the elementary numeric data item; this character position is not a digit position.
    2. The letter "S" in a PICTURE character-string is counted in determining the size of the item (in terms of standard data format characters).
    3. The operational signs for positive and negative are the standard data format characters "+" and "-", respectively.
  5. Every numeric data description entry whose PICTURE contains the character "S" is a signed numeric data description entry. If a SIGN clause applies to such an entry and conversion is necessary for purposes of computation or comparisons, conversion takes place automatically.
  6. ANS85 If a SIGN clause is specified for an item (either an elementary numeric data description entry or a group item) which is subordinate to a group item for which a SIGN clause is also specified, then the SIGN clause specified in the subordinate item takes precedence.
  7. OSVS VSC2 MF The SIGN clause is treated as documentary for external floating-point items. For internal floating-point items, the SIGN clause is invalid and will result in a diagnostic message.
Parent topic: Data Description Entry Skeleton
Related information
The CODE-SET Clause
Selection of Character Representation and Radix


The SYNCHRONIZED Clause

The SYNCHRONIZED clause specifies the alignment of an elementary item on the natural boundaries of the computer memory.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • IBMCOMP - When NOIBMCOMP is specified, the SYNCHRONIZED clause is treated as documentary only.

Syntax Rules

  1. This clause should appear only with an elementary item.

    OSVS VSC2 The SYNCHRONIZED clause can appear with a non-elementary item.

  2. SYNC is an abbreviation for SYNCHRONIZED.

General Rules

  1. SYNCHRONIZED RIGHT specifies that the elementary item is to be positioned so that it terminates on the right character position of the natural boundary in which the elementary item is placed.

    It takes effect only if the IBMCOMP Compiler directive is set.

  2. Specification of the LEFT phrase in the SYNCHRONIZED clause has no effect.
  3. The effect of the SYNCHRONIZED clause is, by definition, implementation-dependent.
  4. This clause specifies that the subject data item is to be aligned in the computer so that no other data item occupies any of the character positions between the leftmost and rightmost natural boundaries of the computer memory which delimits this data item.

    If the number of character positions required to store this data item is less than the number of character positions between those natural boundaries, the unused character positions (or portions thereof) must not be used for any other data item. Such unused character positions are, however, included in:

    1. The size of any group item(s) to which the elementary item belongs, and:
    2. The character positions redefined when this data item is the object of a REDEFINES clause.

    Thus the size of an elementary item is unchanged by the SYNCHRONIZED clause, but extra character positions are assigned by the use of the clause.

  5. SYNCHRONIZED not followed by either RIGHT or LEFT specifies that the elementary item is to be positioned between natural boundaries so that it uses the elementary data item efficiently.
  6. Whenever a SYNCHRONIZED item is referenced , the original size of the item, as shown in the PICTURE clause, is used in determining any action that depends on size, such as justification, truncation or overflow.
  7. If the data description of an item contains the SYNCHRONIZED clause and an operational sign, the sign of the item appears in the normal operational sign position, regardless of whether the item is SYNCHRONIZED LEFT or SYNCHRONIZED RIGHT.
  8. When the SYNCHRONIZED clause is specified in a data description entry of a data item that also contains an OCCURS clause, or in a data description entry of a data item subordinate to a data description entry that contains an OCCURS clause, then:
    1. Each occurrence of the data item is SYNCHRONIZED.
    2. Any implicit FILLER generated for other data items within that same table is generated for each occurrence of those data items.
  9. OSVS VSC2 If the SYNCHRONIZED clause is specified with a non-elementary item, then the clause applies to all the items subordinate to that non-elementary item.
  10. The effect of using the SYNCHRONIZED clause is discussed in the topic Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.
Parent topic: Data Description Entry Skeleton
Related information
Selection of Character Representation and Radix


The TYPEDEF Clause

The TYPEDEF clause defines a record as a programmer-defined type definition.

General Format

Syntax Rules

  1. The TYPEDEF clause can be specified only in data description entries whose level-number is 01.
  2. If TYPEDEF is specified, the following clauses cannot be specified:
    • EXTERNAL
    • GLOBAL
    • OCCURS
    • REDEFINES
    • VALUE

    If the TYPEDEF clause is specified for a group item, then subordinate items can be specified with OCCURS or REDEFINES clauses.

    The VALUE clause cannot be specified either in the data descriptions specifying the TYPEDEF clause or in any subordinate item except for condition-names (88 level entries) within the TYPEDEF structure.

  3. If the TYPEDEF clause is specified for a data description, then that same data description must include a data-name, that is, it must not be specified with either an implicit or explicit FILLER clause.
  4. If a TYPEDEF clause is specified in a call prototype (a program with the EXTERNAL clause in its Program-ID paragraph) then that TYPEDEF can be referenced in any subsequent source line of the compilation group.

General Rules

  1. The purpose of using the TYPEDEF clause is to create a programmer-defined usage or structure that can subsequently be referenced in the USAGE clause.
  2. A record declared with the TYPEDEF clause does not allocate any storage, but declares that data-name-1 can be specified in a subsequent data description entry as typedef-name-1.
Parent topic: Data Description Entry Skeleton
Related concepts
SAME AS Clause Not Available When Defining Data Structures


The USAGE Clause

The USAGE clause specifies the format of a data item in the computer storage.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • COBOL370 – controls whether four or eight bytes of storage are allocated to USAGE PROCEDURE-POINTER data items.
    • COMP-5 – controls the handling of the operational sign when storing into a USAGE COMP-5 data item.
    • IBMCOMP – controls the storage allocated for USAGE COMP and USAGE COMP-5 data items.

Syntax Rules

  1. The USAGE clause may be written in any data description entry with a level number other than 66 or 88.
  2. If the USAGE clause is written in the data description entry for a group item, it may also be written in the data description entry for any subordinate elementary item or group item, but the same usage must be specified in both entries.
  3. An elementary data item whose declaration contains, or an elementary data item subordinate to a group item whose declaration contains, a USAGE clause specifying COMPUTATIONAL

    ANS85 , BINARY, PACKED-DECIMAL

    OSVS VSC2 MF XOPEN , COMPUTATIONAL-3

    OSVS VSC2 MF , COMPUTATIONAL-4

    MF XOPEN OS390 , or COMPUTATIONAL-5

    must be declared with a PICTURE character-string that describes a numeric item (i.e. a PICTURE character-string that contains only the symbols "P", "S", "V", and "9"). See the topic The PICTURE Clause.

    MF An elementary data item whose declaration contains no USAGE clause and that is subordinate to a group item whose declaration contains a USAGE clause specifying a format from the list may be declared with a PICTURE character-string that describes an alphabetic, alphanumeric, alphanumeric-edited or numeric-edited data item.

  4. MF XOPEN OS390 An elementary data item whose declaration contains, or an elementary data item subordinate to a group item whose declaration contains, a USAGE clause specifying COMPUTATIONAL-5

    MF or COMPUTATIONAL-X

    must be declared with a picture character-string that describes a numeric item

    MF or describes an alphanumeric item with a size of between one and sixteen bytes inclusive. If it describes an alphanumeric item of size 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, or 16 bytes, then this is equivalent to specifying an integer item with 2, 4, 7, 9, 12, 14, 16, 18, 19, 21, 24, 26, 28, 31, 33, 36 or 38 decimal digit positions respectively

    .

    MF The PICTURE character-string can contain up to 38 digit positions.

    MF When COMPUTATIONAL-X is specified and the PICTURE character-string describes a numeric item, then that item must be unsigned.

  5. The BLANK WHEN ZERO, JUSTIFIED and SIGN clauses must not be specified for data items whose usage is not explicitly or implicitly DISPLAY.
  6. The SYNCHRONIZED and VALUE clauses must not be specified for data items whose usage is INDEX.

    OSVS VSC2 MF The SYNCHRONIZED clause can be specified for data items whose usage is INDEX.

  7. COMP is an abbreviation for COMPUTATIONAL.

    OSVS VSC2 MF COMP-1 is an abbreviation for COMPUTATIONAL-1.

    OSVS VSC2 MF COMP-2 is an abbreviation for COMPUTATIONAL-2.

    OSVS VSC2 MF XOPEN COMP-3 is an abbreviation for COMPUTATIONAL-3.

    OSVS VSC2 MF COMP-4 is an abbreviation for COMPUTATIONAL-4.

    MF XOPEN OS390 COMP-5 is an abbreviation for COMPUTATIONAL-5.

    MF COMP-X is an abbreviation for COMPUTATIONAL-X.

  8. An index item can be referenced explicitly only in a SEARCH or SET statement, a relation condition, the USING phrase of a Procedure Division,

    OSVS VSC2 MF the USING statement of an ENTRY statement,

    ANS85 an intrinsic function argument

    ISO2002 MF the USING phrase of an INVOKE statement, an inline method invocation argument

    ANS85 an INITIALIZE statement

    or the USING phrase of a CALL statement.

  9. ISO2002 VSC2 MF COB370 ISO2002 VSC2 MF A pointer

    MF COB370 or procedure-pointer

    VSC2 MF item can be referenced explicitly only in a SET statement, a relation condition, a CALL statement, the USING phrase of a Procedure Division, the USING statement of an ENTRY statement

    ISO2002 an INVOKE statement, the argument list of an inline invocation of a method, the argument list of a function,

  10. An elementary data item described with usage INDEX,

    ISO2002 OBJECT,

    VSC2 MF POINTER,

    MF COB370 or PROCEDURE-POINTER

    MF EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, PROCEDURE-POINTER, SEMAPHORE-POINTER or THREAD-POINTER

    clause must not be a conditional variable.

  11. MF Typedef-name-1 must be previously defined in the same source file as a record with the TYPEDEF clause.
  12. MF If USAGE typedef-name-1 is specified, the following clauses cannot also be specified:
    • BLANK
    • JUSTIFIED
    • PICTURE
    • SIGN
    • SYNCHRONIZED
    • VALUE
  13. MF It is an error to specify USAGE typedef-name-1 if there is an explicit USAGE clause at a higher level in the same hierarchy.
  14. MF It is an error to specify any subordinate items (items with a higher level number other than 78) immediately following an item defined with USAGE typedef-name-1.
  15. ISO2002 The USAGE OBJECT REFERENCE clause must not be specified in the data description entry for a group item, but may be specified on subordinate elementary data items.
  16. ISO2002 The USAGE OBJECT REFERENCE clause must not be specified in the File Section.

    MF The USAGE OBJECT REFERENCE clause can be specified in the File Section.

    Note: Whether the object reference still references an active object depends on the application logic.
  17. ISO2002 The ACTIVE-CLASS phrase can be specified only in a factory definition, object definition, or method definition.
  18. MF A data item whose usage is EVENT-POINTER can be referenced explicitly only in a CLOSE statement, an OPEN statement, a SET statement, a WAIT statement or a USING phrase.
  19. MF A data item whose usage is MONITOR-POINTER, MUTEX-POINTER, or SEMAPHORE-POINTER can be referenced explicitly only in a CLOSE statement, an OPEN statement, a SET statement or a USING phrase.
  20. MF A data item whose usage is THREAD-POINTER can be referenced explicitly only in a START statement, a WAIT statement or a USING phrase.

  21. When a directive setting of NATIONAL"1" is in effect, an elementary data item whose description contains a USAGE NATIONAL clause, or an elementary data item subordinate to a group item whose description contains a USAGE NATIONAL clause, must be declared with a picture character-string that describes a national item.

    When a directive setting of NATIONAL"2" is in effect, an elementary data item whose description contains a USAGE NATIONAL clause, or an elementary data item subordinate to a group item whose description contains a USAGE NATIONAL clause, must be declared with a picture character-string that describes a national, national edited, numeric, numeric edited, or external floating point item.

  22. National numeric edited items cannot contain currency symbols if either the NLS-CURRENCY-LENGTH directive is in effect, or the CURRENCY SIGN IS clause is specified in the SPECIAL-NAMES paragraph.
  23. MF When a USAGE clause is not specified for an elementary data item or for any group to which the data item belongs:
    1. if the explicit or implicit picture character-string contains the symbol 'N', a USAGE NATIONAL clause is implied;
    2. otherwise, a USAGE DISPLAY clause is implied.
  24. MF A USAGE clause with the OBJECT REFERENCE, POINTER, or PROGRAM-POINTER phrase must be specified only for an elementary data item with level 1.

    This restriction is not enforced.

  25. MF If program-prototype-name-1 is specified, the TYPEDEF clause must be specified for the subject of the entry.

    This restriction is not enforced.

  26. When a directive setting of NATIONAL"1" is in effect, the NATIONAL phrase can only be specified in a USAGE clause associated with an elementary data item whose explicit or implicit picture character-string contains the symbol 'N'.

    When a directive setting of NATIONAL"2" is in effect, the NATIONAL phrase can also be specified for picture character strings containing the symbol '9', although a signed numeric data item must be described with the SIGN IS SEPARATE clause.

  27. NET JVM A USAGE clause with the CONDITION-VALUE phrase must be specified only for an elementary data item with level 1.
  28. NET JVM If the EVENT phrase is specified, then class-name-1 shall reference a delegate definition and the FACTORY phrase shall not be specified.
  29. integer-1 must have a value between 1 and 16.

General Rules

  1. If the USAGE clause is written at the group level, it applies to each elementary item in the group

    MF except when there is a PICTURE clause and the data item described is non-numeric

  2. The USAGE clause specifies the manner in which a data item is represented in the storage of the computer. It does not affect the use of the data item, although the specifications for some statements in the Procedure Division may restrict the USAGE clause of the operands referred to. The USAGE clause may affect the radix or type of character representation of the item. See the section Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language for more details of the format of each usage.
  3. The USAGE IS BINARY clause specifies that a radix of 2 is used to represent a numeric item in the storage of the computer. This clause is equivalent to specifying USAGE IS COMPUTATIONAL.
  4. The USAGE IS PACKED-DECIMAL clause specifies that a radix of 10 is used to represent a numeric item in the storage of the computer. Furthermore, this clause specifies that each digit position must occupy the minimum possible configuration in computer storage.

    OSVS VSC2 MF XOPEN This clause is equivalent to specifying USAGE IS COMPUTATIONAL-3.

  5. The USAGE IS DISPLAY clause (whether specified explicitly or implicitly) specifies that a standard data format is used to represent a data item in the storage of the computer, and that the data item is aligned on a character boundary.
  6. OSVS VSC2 MF The USAGE IS DISPLAY clause is valid for the following types of items:
    • Alphabetic
    • Alphanumeric
    • Alphanumeric edited
    • Numeric edited
    • External floating-point
    • External decimal (numeric)
  7. The USAGE IS INDEX clause specifies that a data item is an index data item and contains a value which must correspond to an occurrence number of a table element.
  8. When a MOVE statement or an input-output statement that references a group item that contains an index,

    VSC2 MF or pointer,

    MF COB370 or procedure-pointer

    data item is executed, no conversion of the index,

    VSC2 MF or pointer

    MF COB370 or procedure-pointer

    data item takes place.

  9. OSVS VSC2 MF The USAGE IS COMPUTATIONAL-4 clause is equivalent to specifying USAGE IS COMPUTATIONAL.
  10. VSC2 MF The USAGE IS POINTER clause identifies a data item in which you can store the address of a data item (see the topic The SET Statement).
  11. MF COB370 The USAGE IS PROCEDURE-POINTER clause specifies that a data item is a procedure pointer data item in which you can store the address of a procedure. (See the topic The SET Statement.) The procedure can be written in any language: if COBOL, it represents the Procedure Division of a program that is not nested and identified by either:
    • The program-name of the Program-ID paragraph; or
    • The entry-name of an ENTRY statement.
  12. MF If typedef-name-1 was specified as an elementary item, then the USAGE typedef-name-1 clause specifies an elementary item with the same attributes as the programmer-defined usage referenced by typedef-name-1.
  13. MF If typedef-name-1 was specified as a group item, then the USAGE typedef-name-1 clause specifies a group item with an identical structure. The effect is as if the data declarations subordinate to the data description entry identified by typedef-name-1 had been specified identically, subordinate to the item declared with the USAGE typedef-name-1 clause. Data-names of the subordinate data items are identical to those declared within the programmer-defined structure referenced by typedef-name-1 and can be uniquely referenced using qualification.
  14. ISO2002 MF A data item described with a USAGE OBJECT REFERENCE clause is called an object reference. An object reference is a data item of class object and category object-reference. It must contain either null or a reference to an object, subject to the following rules:
    1. The amount of storage allocated for an object reference data item is four bytes.
    2. If none of the optional phrases is specified, this data item is called a universal object reference. Its content may be a reference to any object.
    3. If interface-name-1 is specified, the object referenced by this data item must implement interface-name-1.
    4. If class-name-1 is specified, the object referenced by this data item must be an object of class-name-1 or of a subclass of class-name-1, subject to the following rules:
      1. If the ONLY phrase is not specified:
        1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of the specified class or of a subclass of the specified class.
        2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of the specified class or of a subclass of the specified class.
      2. If the ONLY phrase is specified:
        1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of the specified class.
        2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of the specified class.
    5. If ACTIVE-CLASS is specified, the object referenced by this data item must be an object of the class of the object that was used to invoke the method in which the object referenced is specified, subject to the following rules:
      1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of that class.
      2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of that class.
  15. MF The USAGE IS EVENT-POINTER clause identifies an synchronization data item that flags an occurrence of a software event. An event data item has a value of either TRUE or FALSE.
  16. MF The USAGE IS MONITOR-POINTER clause identifies a synchronization data item, known as a monitor, on which one can request read locks, browse locks, and write locks.
    Note: A monitor is typically used to protect a data structure that different threads might want to read from or read from and write to.
  17. MF The USAGE IS MUTEX-POINTER clause identifies a synchronization data item, known as a mutex, that can be used to protect critical sections in a multi-threaded application. A mutex data item has a value of either ON or OFF. Only one thread can have a mutex data item in the ON state at a time.
  18. MF The USAGE IS SEMAPHORE-POINTER clause identifies a counting synchronization data item that cannot go below zero.
  19. MF The USAGE IS THREAD-POINTER clause identifies a data item in which you can store the handle for a thread.
  20. ISO2002 MF The implicit or explicit USAGE IS NATIONAL clause identifies a data item that is stored in the computer in national-coded characters and aligned on a character boundary. National characters are represented in the storage of the computer as characters of a uniform size. See your COBOL system documentation on national data (UNICODE) for further information.
  21. ISO2002 MF The USAGE IS BINARY-CHAR, USAGE IS BINARY-SHORT, USAGE IS BINARY-LONG and USAGE IS BINARY-DOUBLE clauses identify a numeric data item that has a radix of 2 in the storage of the computer. These usages are equivalent to specifying USAGE IS COMP-5 with the picture character-strings as shown below. An S is included in the equivalent picture character-string unless the UNSIGNED phrase is specified in the USAGE clause.
    USAGE | Equivalent PICTURE character-string
    BINARY-CHAR | [S]9(2)
    BINARY-SHORT | [S]9(4)
    BINARY-LONG | [S]9(9)
    BINARY-DOUBLE | [S] 9(18)
  22. ISO2002 MF The USAGE IS FLOAT-SHORT clause is equivalent to specifying USAGE IS COMPUTATIONAL-1.
  23. ISO2002 MF The USAGE IS FLOAT-LONG clause is equivalent to specifying USAGE IS COMPUTATIONAL-2.
  24. ISO2002 MF A data description entry that specifies the USAGE PROGRAM-POINTER clause specifies a procedure-pointer data item, also called a program-pointer and a procedure-pointer, that may contain the address of a program. (See the topic The SET Statement.) The procedure can be written in any language: if COBOL, it represents the Procedure Division of a program that is not nested and identified by one of :
    • The program-name of the Program-ID paragraph
    • The entry-name of an ENTRY statement.
  25. ISO2002 MF If program-prototype-name-1 is specified, this data item is a restricted program-pointer. A restricted program pointer must contain only the predefined address NULL or the address of a program with the same signature as that identified by the specified program-prototype-name.
  26. NET JVM The USAGE IS CONDITION-VALUE clause specifies a boolean data item that can have the value TRUE or FALSE. A CONDITION-VALUE boolean data item maps onto the .NET framework System.Boolean type, so data items with this usage can be passed to methods that accept System.Boolean parameters.
  27. NET JVM If the class-name specified in the USAGE IS OBJECT REFERENCE class-name clause is a value type, a compiler warning is produced. The item will be treated as a value type, i.e. no reference is produced.
  28. NET JVM The USAGE IS class-name clause phrase specifies:
    • If class-name references a reference type, this is exactly equivalent to USAGE OBJECT REFERENCE class-name-1. The data item represents a reference to an object allocated on the heap, or the value NULL.
    • If class-name references a value type, this clause specifies a data item that is a value type.
  29. NET JVM If the EVENT phrase is specified, the two methods add_ChangeEvent and remove_ChangeEvent are automatically created. These methods can be used, respectively, to hook a new method into the delegate, and subsequently to remove it.
  30. ISO2002 MF The USAGE BIT clause specifies that bits are used to represent a boolean data item. A data item described with USAGE BIT is a bit data item. See the topic Aligning Bit Data Items for information on how boolean data items are aligned.
  31. Integer-1 specifies the number of bytes allocated for a binary (radix-2) data item. If the IBMCOMP directive is specified, the value is adjusted, if necessary, to the next word storage number of bytes that is equal or greater to the number of bytes specified. The length specification can specify a value less than, equal to or greater than the number of bytes that would otherwise be allocated for the binary data item based on the number of 9 symbols in the PICTURE character-string.
  32. If the integer-1 length specification is specified in a USAGE clause at a group level, the length specification applies to each binary data item subordinate to that group except when a data item is subordinate to another group that specifies a different length specification or the elementary data item itself is described with a length specification. That is, the nearest containing group that has a length specification is applied for binary data items in a group that do not have their own length specification.
Parent topic: Data Description Entry Skeleton
Related concepts
SAME AS Clause Not Available When Defining Data Structures
Related information
The PICTURE Clause
Selection of Character Representation and Radix
The SET Statement
Aligning Bit Data Items


The VALUE Clause

The VALUE clause defines the value of constants, the initial value of working storage and local storage items, and the values associated with a condition name.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

General Formats for Format 5

Syntax Rules for All Formats

  1. If a signed numeric literal is specified, the subject of the entry must be a signed numeric data item.
  2. If the category of the subject of the entry is numeric, all literals in the VALUE clause must be numeric and have a value that is within the range of values indicated by the PICTURE clause or the USAGE clause. If the usage is other than float-short or float-long this value must not require truncation of non-zero digits. This value must have the digit zero in each position that corresponds to a picture character symbol 'P'.
  3. If the item is of class alphabetic or alphanumeric, literals in the VALUE clause must be alphanumeric literals. Alphanumeric literals in the VALUE clause of an elementary item must not exceed the size indicated by an explicit PICTURE clause. Alphanumeric literals in the VALUE clause of an alphanumeric group item must not exceed the size of the group item.
  4. If the item is of class national, literals in the VALUE clause must be national literals. National literals in the VALUE clause of an elementary item must not exceed the size indicated by an explicit PICTURE clause. National literals in the VALUE clause of a national group item must not exceed the size of the group item.

Syntax Rules for Formats 1 and 4

  5. The VALUE clause must not be specified in a data description entry that contains a REDEFINES clause or in an entry that is subordinate to an entry containing a REDEFINES clause.
  6. If the VALUE clause is specified at the group level, the literal must be of the same category as the group item or must be a figurative constant that is permitted in a MOVE statement to a receiving item of that category. The VALUE clause cannot be specified at subordinate levels within this group.
  7. If a VALUE clause is specified at the group level, subordinate items within that group must not be described with a JUSTIFIED or SYNCHRONIZED clause, and all data items subordinate to an alphanumeric group item must be explicitly or implicitly described with USAGE DISPLAY.

Syntax Rules for Format 1

  8. OSVS VALUES ARE can be used with Format 1.
  9. OSVS VSC2 MF The VALUE clause may not be used with external floating-point data items.

    MF The VALUE clause may be used with external floating-point data items.

  10. OSVS VSC2 MF The VALUE clause may be used for an internal floating-point data item, that is an item defined with USAGE COMP-1 or USAGE COMP-2. In this case literal-1 must either be a floating-point literal, the figurative constant ZERO, or a numeric literal representing the value zero.

Syntax Rules for Format 2

  11. The words THRU and THROUGH are equivalent.
  12. Any number of Format 2 entries can be written for a data item.
  13. Format 2 must be used only in connection with a condition-name.
  14. In a condition-name entry, the VALUE clause is required. The VALUE clause and the condition-name itself are the only two clauses permitted in the entry.
  15. Literal-2 must be less than literal-3.
  16. OSVS VSC2 MF Format 2 may be used to define a conditional-variable associated with an internal floating-point data item, but not an external floating-point data item. In this case, literal-2 and literal-3 must be floating-point literals, the figurative constant ZERO, or numeric literals representing the value zero.

    MF Format 2 may be used to define a condition-variable associated with an external floating-point data item.

  17. ISO2002 MF Literal-4 must not be equal to any literal-2, and in any literal-2 THROUGH literal-3 pair, literal-4 cannot be greater than or equal to literal-2 and less than or equal to literal-3.

Syntax Rules for Format 3

  18. MF All identifiers must have been defined before the declaration of the level 78 item. If either identifier-1 or identifier-3 (LENGTH parameters) is a group item, the definition of that group must have been completed before the level 78 declaration, by the appearance of another data item at the same or lower level number.

Syntax Rules for Format 4

  19. ISO2002 MF In Format 4 (level 78) the VALUE clause may be omitted if the item is specified in an ENUM definition.
  20. ISO2002 MF A data description entry that contains the VALUE clause must contain an OCCURS clause or be subordinate to a data description entry that contains an OCCURS clause.
  21. ISO2002 MF Subscript-1 and subscript-2 must be integer numeric literals.
  22. ISO2002 MF In one FROM phrase, there must be one subscript-1 specified for each OCCURS clause for the subject of the entry or superordinate to that entry, specified in the same order as a subscripted reference to the subject of the entry would be specified. Each instance of subscript-1 must not exceed the maximum number of occurrences specified in the OCCURS clause associated with that instance.
  23. ISO2002 MF If the TO phrase is specified, there must be one subscript-2 specified for each OCCURS clause for the subject of the entry or superordinate to that entry, specified in the same order as a subscripted reference to the subject of the entry would be specified. Each instance of subscript-2 must not exceed the maximum number of occurrences specified in the OCCURS clause associated with that instance. The specification of subscript-2 in one TO phrase must be such that the table element associated with subscript-2 is the same occurrence or a successive occurrence of the table element associated with the corresponding subscript-1.

Syntax Rules for Format 5

  24. NET JVM Format 5 must be used only in conjunction with USAGE CONDITION-VALUE.

General Rules for Formats 1, 2 and 4

  1. The VALUE clause must not conflict with other clauses in the data description of the item or in the data description within the hierarchy of the item. The following rules apply:
    1. If the literal defines the value of a data item, the literal is aligned in the data item according to the standard alignment rules. (See the topic Standard Alignment Rules in the chapter Concepts of the COBOL Language.)
    2. If the category of the item is alphabetic, alphanumeric, alphanumeric edited or numeric edited all literals in the VALUE clause must be nonnumeric. The literal is aligned in the data item as if the data item had been described as alphanumeric. (See the topic Standard Alignment Rules in the chapter Concepts of the COBOL Language.) Editing characters in the PICTURE clause are included in determining the size of the data item (see the topic The PICTURE Clause) but have no effect on initialization of the data item. Therefore, the programmer is responsible for specifying the value of a literal associated with an edited data item in edited form.

      MF If the item is numeric edited, the value can be a numeric literal or a nonnumeric literal. If the value is a numeric literal, the value contained in the item will be the same as if the numeric literal were moved to the numeric edited item.

    3. Initialization takes place independent of any BLANK WHEN ZERO or JUSTIFIED clause that can be specified.

General Rules for Data-Item (Format 1)

  2. Rules governing the use of the VALUE clause in data item entries differ with the respective sections of the Data Division:
    1. In the Working-Storage Section

      ISO2002 MF and Local-Storage Section,

      the VALUE clause can be used to specify the initial value of a data item, in which case the clause causes the item to assume the specified value at the time the runtime element is placed into its initial state. If the VALUE clause is not used in an item's description, the initial value of that data item is undefined.

    2. In the File Section and the Linkage Section,

      OS390 and Local-Storage Section,

      the VALUE clause can be used in data item entries, but it takes effect only when an INITIALIZE statement that applies to the entries is executed.

  4. If the VALUE clause is specified in an entry at the group level the group area is initialized without consideration for the individual elementary or group items contained within this group.
  5. VSC2 MF The figurative constant NULL can be specified in the VALUE clause only if the data item is defined with USAGE POINTER or USAGE PROCEDURE-POINTER. This is the only value you can specify in the VALUE clause for such an item. The effect is to set the pointer in such a way that it is guaranteed not to point to any data item.
  6. ANS85 A VALUE clause specified in a data description entry that contains an OCCURS clause, or in an entry that is subordinate to an OCCURS clause, causes every occurrence of the associated data item to be assigned the specified value.
  7. ANS85 If a VALUE clause is specified in a data description entry of a data item which is associated with a variable occurrence data item, the initialization of the data item behaves as if the value of the data item referenced by the DEPENDING ON phrase in the OCCURS clause specified for the variable occurrence data item is set to the maximum number of occurrences as specified by that OCCURS clause. A data item is associated with a variable occurrence data item in any of the following cases:
    1. It is a group data item which contains a variable occurrence data item.
    2. It is a variable occurrence data item.
    3. It is a data item that is subordinate to a variable occurrence data item.

    If a VALUE clause is associated with the data item referenced by a DEPENDING ON phrase, that value is considered to be placed in the data item after the variable occurrence data item is initialized.

  8. ISO2002 A data item of class object is initialized to null. The initial value takes effect when VALUE clauses take effect and when storage for the data item is allocated.
  9. ISO2002 A data item of class pointer is initialized to null. The initial value takes effect when VALUE clauses take effect and when storage for the data item is allocated.

Condition-name Rules (Format 2)

  10. In a condition-name entry, the VALUE clause is required. The VALUE clause and the condition-name itself are the only two clauses permitted in the entry. The characteristics of a condition-name are implicitly those of its conditional variable.
  11. Format 2 can be used only in connection with condition-names. Wherever the THRU phrase is used, literal-2 must be less than literal-3.
  12. The FALSE phrase is meaningful only if the associated condition-name is referenced in a SET condition-name TO FALSE statement. (See the topic The SET Statement.)

Constant-Name Rules (Format 3)

  13. MF Constant-expression-1 has the following format:

  14. MF Format 3 can be used only in a constant-name entry.
  15. MF If literal-5 is specified and not followed by an operator, the characteristic of the constant-name is that of literal-5. Otherwise, the characteristic of the constant-name is that of an integer.
  16. MF Any number of arithmetic or logical operators can be used. The result is evaluated using integer arithmetic in strict left to right order unless parentheses are used. A parenthesized expression is evaluated in strict left to right order before its use in the overall expression. That is, all operators other than parentheses have the same precedence in a constant-expression. The expression result is computed in 64-bits. (When the DIALECT"RM" directive is in effect, the expression result is computed in 32-bits.) If any intermediate result is less than zero, the final value is undefined. A constant-name may be used in place of integer-1.
  17. MF The logical operations AND, OR, EXCLUSIVE OR and NOT act on the binary representation in a bit-wise manner.
  18. MF LENGTH of identifier-1 or identifier-3 is the size of the storage allocated for identifier-1 or identifier-3, respectively. If the identifier is a group item, the length includes all subordinate data items. SIZE can also be used as a synonym of LENGTH in a constant-expression.
  19. MF If literal-1 or literal-2 is a figurative constant, LENGTH OF is calculated as 1.
  20. MF If literal-1 or literal-2 is a numeric literal other than a floating point literal, LENGTH OF is the result of the number of digits in the numeric literal, including leading zeroes; the sign and decimal point are not counted, if specified. If literal-1 or literal-2 is a floating point numeric literal, LENGTH OF is the result of a sign character (whether specified or not), the digits of the mantissa and exponent (excluding leading zeroes), the decimal point, the "E" or "e" character, and the exponent sign (whether specified or not).
  21. MF The value returned by NEXT is the offset at which the next byte of storage occurs after the previous data declaration. (It is not the offset of the start of the next data declaration.) If that data declaration was of a table defined with an OCCURS clause, the value returned by NEXT is the offset at which the next byte of storage occurs after the first element of the table.
  22. MF START of identifier-2 or identifier-4 is the offset at which identifier-2 or identifier-4, respectively, begins.
  23. MF For rules 21 and 22, the offset is defined as follows:
    • If the identifier is part of an EXTERNAL record or a LINKAGE record, the offset is calculated from the start of the associated 01-level;
    • If the identifier is defined in the Local-Storage Section, the offset is calculated from the start of the Local-Storage Section;
    • Otherwise the offset is calculated from the start of the Data Division.
  24. MF Offsets are not portable across different COBOL implementations and no reliance should be placed on particular values outside this compilation unit.
  25. DATE-COMPILED gives the integer value representing the date the compilation started as YYYYMMDD, where YYYY is the year, MM is the month of the year, and DD is the day of the month.

Table Rules (Format 4)

  26. ISO2002 MF A format 2 VALUE clause initializes a table element to the value of literal-6. The table element initialized is identified by subscript-1. Consecutive table elements are initialized, in turn, to the value of successive occurrences of literal-6. Consecutive table elements are referenced by incrementing by 1 the subscript that represents the least inclusive dimension of the table. When any reference to a subscript, prior to incrementing it, is equal to the maximum number of occurrences specified by its corresponding OCCURS clause, that subscript is set to 1 and the subscript for the next most inclusive dimension of the table is incremented by 1.
  27. ISO2002 MF If the TO phrase is specified, all occurrences of literal-6 are reused, in the order specified, as a source during the initialization described in the immediately preceding rule. This repetition is done until the table element identified by subscript-2 is initialized.
  28. ISO2002 MF If the TO phrase is not specified, it is as if the TO phrase were specified with each subscript-2 as the maximum number of occurrences of the table associated with each corresponding subscript-1.
  29. ISO2002 MF If multiple specifications of the FROM phrase reference the same table element, the value defined by the last specified FROM phrase in the VALUE clause is assigned to the table element.

Format 5

  30. NET JVM If the TRUE phrase is specified, the associated condition-value data item is set to true. If the FALSE phrase is specified, the associated condition-value data item is set to false.

Examples

  1. An example of using the NEXT phrase of the VALUE clause is provided in the section NEXT Phrase of CONSTANT-NAMES.
Parent topic: Data Description Entry Skeleton
Related reference
Initialization of Working Storage
Related information
Standard Alignment Rules
The SET Statement
The PICTURE Clause
NEXT Phrase of CONSTANT-NAMES


Screen Section

  • Screen Section Entry Skeleton
    A Screen Description entry specifies the attributes, behavior, size and location for a referenced screen item which is accepted or displayed at run time.
  • The AUTO Clause
    The AUTO clause automatically terminates an ACCEPT operation of the screen item when the last character position is keyed. No explicit terminator key is necessary.
  • The BACKGROUND-COLOR Clause
    The BACKGROUND-COLOR clause specifies the background color of the screen item.
  • The BELL Clause
    The BELL clause causes an audible alarm to occur each time the item containing the clause is displayed.
  • The BLANK Clause
    The BLANK clause clears a line of a screen or the whole screen before a screen item is displayed.
  • The BLANK WHEN ZERO Clause in the Screen Section
    The BLANK WHEN ZERO clause causes the blanking of a screen item when its value is zero.
  • The BLINK Clause
    The BLINK clause causes the screen item to blink when it appears on the screen.
  • The COLUMN Clause
    The COLUMN clause specifies the column at which the screen item starts on the screen.
  • The CONTROL Clause
    The CONTROL clause allows attributes associated with a Screen Section item to be defined at run time.
  • The ERASE Clause
    The ERASE clause clears part of the line or the screen starting at the cursor position.
  • The FOREGROUND-COLOR Clause
    The FOREGROUND-COLOR clause specifies the foreground color of the screen item.
  • The FROM Clause
    The FROM clause identifies the source of data for display.
  • The FULL Clause
    The FULL clause specifies that the operator must either leave the screen item completely empty or fill it entirely with data.
  • The GRID Clause
    The GRID clause causes each character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. Each line is within the character-position.
  • The HIGHLIGHT Clause
    The HIGHLIGHT clause causes the screen item to appear in high intensity mode when it appears on the screen.
  • The JUSTIFIED Clause in the Screen Section
    The JUSTIFIED clause specifies non-standard positioning of data within a screen item when data is either moved to it or entered into it.
  • The LEFTLINE Clause
    The LEFTLINE clause causes the leftmost character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. The line is within the character-position.
  • The LINE Clause
    The LINE clause specifies the line at which the screen item starts on the screen.
  • The LOWLIGHT Clause
    The LOWLIGHT clause specifies that the field is to appear on the screen with the lowest intensity.
  • The OCCURS Clause in the Screen Section
    The OCCURS clause eliminates the need for separate entries for repeated screen items and supplies information required for the application of subscripts or indices.
  • The OVERLINE Clause
    The OVERLINE clause causes every character of the screen item to have a horizontal line above it when the item appears on the screen. The line is within the character-position.
  • The PICTURE Clause in the Screen Section
    The PICTURE clause describes the length, general characteristics and editing requirements of a screen item.
  • The PROMPT Clause
    The PROMPT clause causes the empty character positions in the screen item to be marked on the screen during an ACCEPT operation while the system is ready to accept operator-keyed data into that item.
  • The REQUIRED Clause
    The REQUIRED clause specifies that the operator must not leave the screen item empty.
  • The REVERSE-VIDEO Clause
    The REVERSE-VIDEO clause causes the screen item to be displayed in reverse-video.
  • The SECURE Clause
    The SECURE clause prevents operator-keyed data from appearing on the screen.
  • The SIGN Clause in the Screen Section
    The SIGN clause specifies the position and representation of the operational sign.
  • The SIZE Clause
    The SIZE clause specifies the current size of the screen item.
  • The TO Clause
    The TO clause identifies the destination of data accepted.
  • The UNDERLINE Clause
    The UNDERLINE clause causes the screen item to be underlined when it appears on the screen.
  • The USAGE Clause in the Screen Section
    The USAGE clause specifies the format of a data item in the computer storage.
  • The USING Clause
    The USING clause identifies the source of data for display.
  • The VALUE Clause in the Screen Section
    The VALUE clause specifies literal information for display on the screen.
  • The ZERO-FILL Clause
    The ZERO-FILL clause causes trailing prompt characters to be replaced by zeros instead of spaces.
Parent topic: Data Division


Screen Section Entry Skeleton

A Screen Description entry specifies the attributes, behavior, size and location for a referenced screen item which is accepted or displayed at run time.

The availability of screen attributes is dependent on your terminal hardware and operating system and COBOL run-time support.

MF The following are not a part of X/Open screen handling:

  • ACCEPT (Formats 3 and 5)
  • AUTO-SKIP (synonym for AUTO)
  • BEEP (synonym for BELL)
  • COL (synonym for COLUMN)
  • CONTROL
  • DISPLAY (Format 3)
  • EMPTY-CHECK (synonym for REQUIRED)
  • GRID
  • LEFTLINE
  • LENGTH-CHECK (synonym for FULL)
  • NO-ECHO (synonym for SECURE)
  • OCCURS
  • OVERLINE
  • PROMPT
  • SIZE
  • ZERO-FILL

General Format

Syntax Rules

  1. Each Screen Description entry must start with a level number from 01 through 49.
  2. Each level 01 item must have a screen-name.
  3. Screen-name must immediately follow level number and conform to the rules for user-defined names.
  4. A screen item can be referenced only in a Format 4 ACCEPT or Format 2 DISPLAY statement.
  5. Each elementary screen item must contain at least one of the following clauses: BELL, BLANK LINE, BLANK SCREEN, COLUMN, LINE, PICTURE, VALUE.
  6. The data items in the FROM, TO and USING phrases are associated with the screen item. The USING phrase is equivalent to the combination of a FROM and TO phrase, each specifying the same field.
  7. An ACCEPT can be executed on a group screen item containing screen items with FROM or VALUE phrases only if that group also contains screen items with TO or USING phrases.
  8. The clauses following screen-name can be specified in any order.
  9. A clause that appears in the description of a group screen item applies to all the elementary subordinate items in that group in whose descriptions it would be allowed.
  10. Any non-01 level screen item can have a data name, FILLER, or no name. If no name is used, then FILLER is assumed (and the item can never be explicitly referenced).
  11. If the same clause is specified more than once for the same screen item, the clause which appears at the lowest level within the hierarchy is the one which takes effect.

  12. Table 1 summarizes the screen description entry clauses available in the Screen Section for use with different types of screen fields

    MF and the WITH phrase options for use with the ACCEPT and DISPLAY statements.

    Table 1. Permitted Use of Options
    Screen Description Entry Clauses/ WITH Phrases | Screen Section | MF WITH Phrase
    Input Field | Output Field | Update Field | Literal Field | ACCEPT | DISPLAY
    AUTO | X | X | X
    BACKGROUND-COLOR | X | X | X | X | X | X
    BELL | X | X | X | X | X | X
    BLANK | X | X | X | X | X
    BLANK WHEN ZERO | X | X | X
    BLINK | X | X | X | X | X | X
    COLUMN | X | X | X | X
    ERASE | X | X | X | X | X
    FOREGROUND-COLOR | X | X | X | X | X | X
    FULL | X | X | X
    GRID | X | X | X | X | X | X
    HIGHLIGHT | X | X | X | X | X | X
    JUSTIFIED | X | X | X
    LEFT-JUSTIFY | X
    LEFTLINE | X | X | X | X | X | X
    LINE | X | X | X | X
    LOWLIGHT | X | X | X | X | X | X
    OCCURS | X | X | X
    OVERLINE | X | X | X | X | X | X
    PROMPT | X | X | X
    REQUIRED | X | X | X
    REVERSE-VIDEO | X | X | X | X | X | X
    RIGHT-JUSTIFY | X
    SECURE | X | X | X
    SIGN | X | X | X
    SIZE | X | X | X | X | X | X
    SPACE-FILL | X
    TRAILING-SIGN | X
    UNDERLINE | X | X | X | X | X | X
    UPDATE | X

    Key:

    X | Clause or option allowed
    Input field | Screen item whose description contains a TO phrase
    Output field | Screen item whose description contains a FROM phrase
    Update field | Screen item whose description contains a USING phrase
    Literal field | Elementary screen item whose description contains no PICTURE clause.

General Rules

  1. Screen-name assigns a name to the screen item described in the screen description.
  2. Screen descriptions define areas on the screen. Each entry consists of a level number, an optional screen-name, and various optional clauses relating to the positioning of fields as well as to console functions.
  3. When the screen item is displayed, data is taken from the literal or data item named in the associated FROM or USING phrase. Items with the TO phrase only are treated as though FROM SPACE or FROM ZERO were specified, depending on the type of screen item.
  4. When the screen item is accepted, the data entered is moved from the screen to the data item named in the TO or USING phrase. Depending on the category of the item, conversion and de-editing are done if necessary.
  5. An input field is a screen item whose description contains a TO phrase.
  6. An output field is a screen item whose description contains a FROM phrase.
  7. An update field is a screen item whose description contains a USING phrase.
  8. A literal field is an elementary screen item whose description contains no PICTURE clause.
  9. An ACCEPT of a group screen item consists of accepting those elementary subordinate items that are input or update fields. They are accepted in the order their descriptions appear in the Screen Section at the screen positions indicated by the screen descriptions. Unless otherwise specified in the CURSOR IS clause (see the topic The Special-Names Paragraph in the chapter Environment Division), the cursor is initially positioned at the start of the first item. As the ACCEPT operation into each item is terminated, the cursor moves to the start of the next item.
  10. A DISPLAY of a group screen item consists of displaying those elementary subordinate items that are output, update or literal fields. They are displayed simultaneously at the screen positions indicated by the screen descriptions.
  11. If the length of an ACCEPT or DISPLAY screen item exceeds the length of the current line, wraparound is to the next line.
  12. If a screen item is too large to fit within the physical screen, truncation occurs at the first character that is off-screen for output fields and alphanumeric input and update fields, and at the first field that is off-screen for numeric and numeric edited input and update fields.
Parent topic: Screen Section
Related information
The Special-Names Paragraph


The AUTO Clause

The AUTO clause automatically terminates an ACCEPT operation of the screen item when the last character position is keyed. No explicit terminator key is necessary.

General Format

Syntax Rules

  1. The AUTO clause is allowed only with input and update fields.
  2. If this clause is specified at group level, it applies to all elementary subordinate items.
  3. MF AUTO and AUTO-SKIP are equivalent.

General Rules

  1. Provided any REQUIRED or FULL clause is satisfied, the cursor is positioned to the next screen item. Alternatively, if the screen item is the last one in the ACCEPT operation, the entire ACCEPT is terminated.
  2. This clause overrides any existing configuration options for automatic skipping and for the automatic termination of an ACCEPT statement. (See your COBOL system documentation about user interfaces for details of configuration options.)
  3. In a fixed-format numeric-edited screen item, the AUTO clause causes the decimal point position to be skipped automatically once all of the integer places have been filled. Selection of fixed format mode is a configuration option. (See your COBOL system documentation about user interfaces for details of configuration options.)
Parent topic: Screen Section


The BACKGROUND-COLOR Clause

The BACKGROUND-COLOR clause specifies the background color of the screen item.

General Format

Syntax Rules

  1. MF BACKGROUND-COLOR and BACKGROUND-COLOUR are equivalent.
  2. This clause is allowed with any screen item.
  3. If this clause is specified at group level, it applies to all elementary subordinate items.
  4. Integer-1 must be a value from 0 to 15.

General Rules

  1. This clause is available for use only with a color screen.
  2. Integer-1 or identifier-1 specifies the background color of the screen item. The colors and their corresponding values are:
    0 | black | 8 | grey
    1 | blue | 9 | light blue
    2 | green | 10 | light green
    3 | cyan | 11 | light cyan
    4 | red | 12 | light red
    5 | magenta | 13 | light magenta
    6 | brown or yellow | 14 | yellow
    7 | white | 15 | high intensity white

    On a color screen, if the value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the BLINK clause. On a monochrome screen, this is equivalent to simply specifying the BLINK clause.

  3. If this clause is not specified, the background color defaults to black.
  4. If a screen description contains a BLANK SCREEN clause, and either contains a BACKGROUND-COLOR clause or is subordinate to one that does, when the screen item is displayed by a DISPLAY statement the specified color becomes the default background color. It remains the default background color until either another screen item with this combination of options is displayed (whether in the same DISPLAY statement or another), or a Format 3 DISPLAY statement with both options is executed.
  5. Identifier-1 must be an unsigned numeric integer and should contain a value between 0 and 7. Any value higher than 7 is divided by 8 and the remainder used as the color value.
  6. Identifier-1 must not be subject to OCCURS clauses.
  7. Whether a value of 6 in integer-1 or identifier-1 produces brown or yellow color depends on the terminal hardware.
Parent topic: Screen Section


The BELL Clause

The BELL clause causes an audible alarm to occur each time the item containing the clause is displayed.

General Format

Syntax Rules

  1. This clause is allowed only with elementary items.
  2. MF BELL and BEEP are equivalent.

General Rules

  1. The BELL clause causes an alarm to occur each time the item containing the clause is accepted or displayed.
  2. In order to cause the audible alarm to sound when the subject of this entry is accepted, you must specify the BELL clause in General Format 5 of the ACCEPT statement: the alarm does not sound if you specify the BELL clause in the Screen Description Entry and then use General Format 4 of the ACCEPT statement.
Parent topic: Screen Section


The BLANK Clause

The BLANK clause clears a line of a screen or the whole screen before a screen item is displayed.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or semantics described in this section.
    • OLDBLANKLINE - specifies that the BLANK LINE clause has the same effect as ERASE EOL; that is, all characters to the right of the cursor are deleted.

Syntax Rules

  1. The BLANK SCREEN clause can be specified in any screen description entry.
  2. The BLANK LINE clause can be specified only for elementary items.

General Rules

  1. The BLANK SCREEN clause is executed before DISPLAY of a screen data item, no matter where it appears. If the clause is specified, all the screen is cleared and the cursor is placed at line 1, column 1.
  2. When BLANK LINE is specified, blanking begins at column 1 of the line specified for the screen data element in whose description it is included and continues through the end of the line. The cursor remains in the same position as before the BLANK LINE was actioned.
  3. If neither the BLANK nor the ERASE clause is specified, only the particular character positions corresponding to the screen data element are modified when the element is displayed. The rest of the screen content remains the same.
  4. The BLANK SCREEN clause causes the screen to return to its default foreground and background colors. For additional effects, if the screen item is subject to a FOREGROUND-COLOR or BACKGROUND-COLOR clause, see the topics on those clauses.
  5. The BLANK clause is ignored in an ACCEPT statement.
  6. When the BLANK SCREEN clause is used, only color options (foreground-color and background-color) should be used on the same screen. Other attributes are accepted but ignored.
Parent topic: Screen Section


The BLANK WHEN ZERO Clause in the Screen Section

The BLANK WHEN ZERO clause causes the blanking of a screen item when its value is zero.

General Format

Syntax Rules

  1. This clause is allowed only with input, output and update fields that are numeric or numeric-edited.

General Rules

  1. The BLANK WHEN ZERO clause causes the blanking of a screen item when its value is zero.
  2. This clause has no effect when the cursor is in the field. That is, the contents of the field are always displayed, even if zero, if this is the current input field.
Parent topic: Screen Section


The BLINK Clause

The BLINK clause causes the screen item to blink when it appears on the screen.

General Format

Syntax Rules

  1. The BLINK clause is allowed with any screen item.
  2. If the BLINK clause is specified at group level, it applies to all suitable subordinate elementary items.

General Rules

  1. The BLINK clause causes the screen item to blink when it appears on the screen.
Parent topic: Screen Section


The COLUMN Clause

The COLUMN clause specifies the column at which the screen item starts on the screen.

General Format

Syntax Rules

  1. Identifier-1 must be an unsigned numeric integer and must contain a value greater than zero and less than 256.
  2. Integer-1 must be unsigned, greater than zero and less than 256.
  3. MF PLUS and "+" are equivalent.
  4. Omitting the NUMBER phrase results in a default value of +1.
  5. COLUMN 1 is assumed for screen descriptions which specify the LINE clause but omit the COLUMN clause.
  6. The COLUMN clause can be specified with any elementary item.
  7. MF COL is an abbreviation for COLUMN.
  8. MF When the COLUMN clause is specified anywhere within the hierarchy of a Screen Section group item, then at least one of the following clauses must also be specified within the same group definition:

    BEEP, BELL, BLANK LINE, BLANK SCREEN, ERASE EOL, ERASE EOS, FROM, TO, USING, or VALUE.

General Rules

  1. The value of identifier-1 or integer-1 is restricted by the physical limits of the screen; for example, the Windows limit is 132.
  2. The COLUMN clause specifies the column in which the screen item is to appear on the screen in an ACCEPT or DISPLAY operation.
  3. If the COLUMN clause has an identifier or an integer but does not specify PLUS,

    MF "+" or "-",

    the clause gives an absolute column number within the screen record. Each 01 level represents a screen record. The AT phrase of the ACCEPT and DISPLAY statements specifies the positioning of the screen record relative to the start of the display screen. If the AT phrase is not specified, then column 1 is the first column on the screen.

  4. If PLUS,

    MF "+" or "-"

    is specified in the COLUMN clause, then the column number within the screen record is relative to that at which the preceding screen item ends, regardless of whether or not the statement displays the preceding item on the screen. This depends on the current effective length of that item at run time, derived from its PICTURE, VALUE and SIZE clauses. The counting of column numbers restarts at a level 01 item at column 1.

  5. If a screen description contains neither a LINE or COLUMN clause, and the item is not a level 01 item, COLUMN+1 is assumed. The item then starts immediately following the preceding item in the Screen Section.
  6. If a COLUMN position that is specified is off the screen, wraparound is to the next (or previous) line.
Parent topic: Screen Section


The CONTROL Clause

The CONTROL clause allows attributes associated with a Screen Section item to be defined at run time.

General Format

Syntax Rules

  1. This clause is allowed with any screen item.
  2. If this clause is specified at group level, it applies to all elementary subordinate items.
  3. Identifier-1 must be an alphanumeric data item. The maximum permitted size of the item is PIC X(65535).
  4. Attributes specified in identifier-1 override any statically defined attributes.
  5. CONTROL statements must not be nested.
  6. The PROTECT attribute may be specified only for an elementary screen description entry.
  7. integer-1 must be a value between 0-15, as noted in The FOREGROUND-COLOR Clause or The BACKGROUND-COLOR Clause.
  8. identifier-2 must be one of BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, or WHITE.

General Rules

  1. When an ACCEPT or DISPLAY statement is executed that implicitly or explicitly references the subject of this entry, the contents of the data item referenced by identifier-1 must conform to the following subset of the screen attributes which can be specified elsewhere:

  2. If identifier-1 contains spaces, the statically defined attributes are used for any accept or display of the item.
  3. The meaning of each of the attributes that can be specified within the CONTROL identifier-1 is defined in the following parts of this reference:
    1. Within the Data Division as an individual Screen Section clause
      • AUTO-SKIP/AUTO
      • BACKGROUND-COLOR/BACKGROUND-COLOUR/BCOLOR
      • BELL/BEEP
      • BLANK LINE/SCREEN
      • BLINK
      • ECHO
      • ERASE EOS/EOL
      • FOREGROUND-COLOR/FOREGROUND-COLOUR/FCOLOR
      • FULL/LENGTH-CHECK
      • GRID
      • HIGHLIGHT/HIGH
      • JUSTIFY/JUST
      • LEFTLINE
      • LOWLIGHT/LOW
      • OVERLINE
      • PROMPT
      • REQUIRED/EMPTY-CHECK
      • REVERSE-VIDEO/REVERSE
      • SECURE/NO-ECH0/OFF
      • TAB
      • UNDERLINE
      • UPDATE
      • ZERO-FILL
    2. Within the Procedure Division in the ACCEPT statement General Rules:
      • RIGHT-JUSTIFY
      • TRAILING-SIGN
      • TRAILING
    3. Within this CONTROL clause discussion:
      • PROTECT
  4. The PROTECT attribute specifies that input to an ACCEPT item is to be prevented.
  5. The = sign is synonymous with a space; for example, BCOLOR=3 is the same as BCOLOR 3.
  6. The color name can be specified as an equivalent to the integer values integer-3 and integer-4; for example, BCOLOR IS BLUE.
Parent topic: Screen Section


The ERASE Clause

The ERASE clause clears part of the line or the screen starting at the cursor position.

General Format

Syntax Rules

  1. The ERASE clause can be specified only for elementary items.

General Rules

  1. When ERASE EOL is specified, blanking begins at the line and column coordinates specified for the screen data element in whose description it is included and continues through the end of the line.
  2. When ERASE EOS is specified, blanking begins at the line and column coordinates specified for the screen data element in whose description it is included and continues through the end of the screen.
  3. If neither the BLANK nor the ERASE clause is specified, only the particular character positions corresponding to the screen data element are modified when the element is displayed.
  4. The clause is ignored in an ACCEPT operation.
Parent topic: Screen Section


The FOREGROUND-COLOR Clause

The FOREGROUND-COLOR clause specifies the foreground color of the screen item.

General Format

Syntax Rules

  1. FOREGROUND-COLOR and FOREGROUND-COLOUR are equivalent.
  2. This clause is allowed with any screen item.
  3. If this clause is specified at group level, it applies to all elementary subordinate items.
  4. Integer-1 must be a value from 0 to 15.

General Rules

  1. This clause is available for use only with a color screen.
  2. Integer-1 or identifier-1 specifies the foreground color of the screen item. The colors and their corresponding values are:
    0 | black | 8 | grey
    1 | blue | 9 | light blue
    2 | green | 10 | light green
    3 | cyan | 11 | light cyan
    4 | red | 12 | light red
    5 | magenta | 13 | light magenta
    6 | brown or yellow | 14 | yellow
    7 | white | 15 | high intensity white

    On a color screen, if the value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the HIGHLIGHT clause. On a monochrome screen, this is equivalent to simply specifying the HIGHLIGHT clause.

  3. If this clause is not specified, the foreground color defaults to white.
  4. If a screen description contains a BLANK SCREEN clause, and either contains a FOREGROUND-COLOR clause or is subordinate to one that does, then when the screen item is displayed by a DISPLAY statement the specified color becomes the default foreground color. It remains the default foreground color until either another screen item with this combination of options is displayed (whether in the same DISPLAY statement or another), or a Format 3 DISPLAY statement with both options is executed.
  5. If the HIGHLIGHT clause is also specified, foreground colors are brightened and lightened; for example on some hardware, black can become grey and brown can become yellow. However, this does not apply to the BLANK SCREEN clause.
  6. Identifier-1 must be an unsigned numeric integer and should contain a value between 0 and 7. Any value higher than 7 is divided by 8 and the remainder used as the color value.
  7. Identifier-1 must not be subject to OCCURS clauses.
  8. Whether a value of 6 in integer-1 or identifier-1 produces brown or yellow depends on the terminal hardware.
Parent topic: Screen Section


The FROM Clause

The FROM clause identifies the source of data for display.

General Format

Syntax Rules

  1. The FROM clause, when used with the TO clause, is equivalent to the USING clause, both specifying the same identifier. It must not be used with the USING clause.
  2. The identifier in the FROM clause can be qualified. If no OCCURS clause applies to the screen item, this identifier can be subscripted or indexed. It must be defined in the File, Working-Storage,

    MF Local-Storage,

    or Linkage Section of the program.

General Rules

  1. Executing a DISPLAY statement on a screen item whose description includes a FROM clause moves data from the associated data item to the screen item, and then displays the screen item on the screen.
Parent topic: Screen Section


The FULL Clause

The FULL clause specifies that the operator must either leave the screen item completely empty or fill it entirely with data.

General Format

Syntax Rules

  1. The FULL clause is valid only in input and update fields and group items.
  2. If this clause is specified at group level, it applies to all suitable subordinate elementary items.
  3. MF FULL and LENGTH-CHECK are equivalent.

General Rules

  1. The FULL clause is effective during the execution of any ACCEPT statement that causes the screen item to be accepted provided the cursor enters the screen item at some time during the ACCEPT operation. Until this clause is satisfied, terminator keystrokes are rejected. If the item is fixed format numeric edited, the cursor is repositioned to the decimal point position.
  2. If the screen item is alphanumeric, in order to satisfy this clause either the entire item must contain only spaces or prompt characters, or both the first and last character positions must contain non-space, non-prompt characters.
  3. If the screen item is free-format numeric or free-format numeric-edited, then to satisfy the clause, either the resultant value must be zero, or both the first and last character positions must contain non-space, non-prompt characters.
  4. If the screen item is fixed-format numeric-edited, then to satisfy the clause either the value must be zero or there must be no digit positions in which zero-suppression has taken effect.
  5. The FULL clause has no effect on fixed-format numeric or on numeric-edited screen items that have no zero-suppression positions.
  6. For update fields, the FULL clause can be satisfied by initial data as well as operator-keyed data.
  7. The FULL clause cannot be effective if a function key is used to terminate the ACCEPT operation. (See your COBOL system documentation about user interfaces for details of configuration options.)
  8. An error message can be configured for display on the screen if the FULL clause is not satisfied. (See your COBOL system documentation about user interfaces for details of configuration options.)
Parent topic: Screen Section


The GRID Clause

The GRID clause causes each character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. Each line is within the character-position.

General Format

Syntax Rules

  1. The GRID clause can be used with any screen item.
  2. If the GRID clause is specified at group level, it applies to all suitable subordinate elementary items.
  3. If this clause is used on a system that does not support characters with vertical left-hand lines it has no effect.

General Rules

  1. The GRID clause causes each character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. Each line is within the character-position.
Parent topic: Screen Section


The HIGHLIGHT Clause

The HIGHLIGHT clause causes the screen item to appear in high intensity mode when it appears on the screen.

General Format

Syntax Rules

  1. This clause is valid for input, output, update and literal fields.
  2. If the HIGHLIGHT clause is specified at group level, it applies to all suitable subordinate elementary items.

General Rules

  1. If the FOREGROUND-COLOR clause is also specified, the HIGHLIGHT clause causes the foreground colors to become brighter and lighter; for example on some hardware, black can become grey and brown can become yellow. However, this does not apply to the BLANK SCREEN clause.
Parent topic: Screen Section


The JUSTIFIED Clause in the Screen Section

The JUSTIFIED clause specifies non-standard positioning of data within a screen item when data is either moved to it or entered into it.

General Format

Syntax Rules

  1. JUST is an abbreviation for JUSTIFIED.
  2. The JUSTIFIED clause is allowed only with input, output and update fields.

General Rules

  1. If the screen item is an output or update field, when data is moved to it from the sending item, the JUSTIFIED clause is applied according to the normal rules for MOVE.
  2. If the screen item is an input or update field, when the accepting of data into it has terminated, the JUSTIFIED clause causes the data entered to be moved right by the number of character positions occupied by prompt characters, and the left of the field to be padded with spaces. This is done before the data is moved to the receiving item. This does not occur if data is not entered.
  3. If the screen item has a SECURE clause, the effect on the data is the same as it would be without the SECURE clause, but this effect does not appear on the screen.
Parent topic: Screen Section


The LEFTLINE Clause

The LEFTLINE clause causes the leftmost character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. The line is within the character-position.

General Format

Syntax Rules

  1. The LEFTLINE clause can be used with any screen item.
  2. If the LEFTLINE clause is specified at group level, it applies to all suitable subordinate elementary items.
  3. If this clause is used on a system that does not support characters with vertical left-hand lines it has no effect.

General Rules

  1. The LEFTLINE clause causes the leftmost character of the screen item to have a vertical line on its left-hand side when the item appears on the screen. The line is within the character-position.
Parent topic: Screen Section


The LINE Clause

The LINE clause specifies the line at which the screen item starts on the screen.

General Format

Syntax Rules

  1. Identifier-1 must be an unsigned numeric integer and must contain a value greater than zero and less than 256.
  2. Integer-1 must be unsigned, greater than zero and less than 256.
  3. MF PLUS and "+" are equivalent.
  4. Omitting the NUMBER phrase results in a default value of PLUS 1.
  5. The current line is assumed for screen descriptions which omit the LINE clause.
  6. The LINE clause can be specified with any elementary item.
  7. MF When the LINE clause is specified anywhere within the hierarchy of a Screen Section group item, then at least one of the following clauses must also be specified within the same group definition: BEEP, BELL, BLANK LINE, BLANK SCREEN, ERASE EOL, ERASE EOS, FROM, TO, USING, or VALUE.

General Rules

  1. The value of identifier-1 or integer-1 is restricted by the physical limits of the screen; for example, the Windows limit is 60.
  2. The LINE clause specifies the line on which the screen item is to appear on the screen in an ACCEPT or DISPLAY operation.
  3. If the LINE clause has identifier-1 or integer-1 but does not specify PLUS,

    MF "+" or "-",

    the clause gives an absolute line number within the screen record. Each 01 level represents a screen record. The AT phrase of the ACCEPT and DISPLAY statements specifies the positioning of the start of the screen record relative to the start of the display screen. If the AT phrase is not specified, then line 1 is the first line on the screen.

  4. If PLUS,

    MF "+" or "-",

    is specified in the LINE clause, then the line number is relative to that at which the preceding screen item ends, regardless of whether or not the statement displays the preceding item on the screen. This depends on the current effective length of that item at run time, derived from its PICTURE, VALUE and SIZE clauses. The counting of line numbers restarts at a level 01 item at line 1.

  5. If a Screen Description contains neither a LINE or COLUMN clause, and the item is not a level 01 item, COLUMN PLUS 1 is assumed. The item then starts immediately following the preceding item in the Screen Section.
  6. If a LINE position that is specified is off the screen, the ACCEPT or DISPLAY is truncated.
  7. If PLUS

    MF "+" or "-",

    is specified in the LINE clause, and an ACCEPT or DISPLAY statement referencing the Screen Section item includes the AT LINE NUMBER phrase, the line number at which this item is presented is the sum or difference of the two numbers.

Parent topic: Screen Section


The LOWLIGHT Clause

The LOWLIGHT clause specifies that the field is to appear on the screen with the lowest intensity.

General Format

Syntax Rules

  1. If the LOWLIGHT clause is specified at group level, it applies to all suitable subordinate elementary items.

General Rules

  1. The LOWLIGHT clause specifies that the field is to appear on the screen with the lowest intensity.
Parent topic: Screen Section


The OCCURS Clause in the Screen Section

The OCCURS clause eliminates the need for separate entries for repeated screen items and supplies information required for the application of subscripts or indices.

General Format

Syntax Rules

  1. The OCCURS clause is not allowed at 01 level.
  2. If USING or TO clauses apply to the item, or to any item subsidiary to the item, then the same number of OCCURS clauses, specifying the same number of occurrences, must apply to the receiving item. These OCCURS clauses must not include the DEPENDING phrase.
  3. If a FROM clause applies to the item, or to any item subsidiary to the item, either the same number of OCCURS clauses, specifying the same number of occurrences, or no OCCURS clauses at all, must apply to the sending item. These OCCURS clauses must not include the DEPENDING phrase.

General Rules

  1. In a screen description which is subject to an OCCURS clause, the LINE and COLUMN clauses apply to each individual table entry. Thus either the LINE or the COLUMN clause should specify relative positioning, because if they both specify an absolute position every entry will appear in the same place.
  2. If the screen item is an output field, and no OCCURS clauses apply to the sending item, in a DISPLAY operation the contents of the sending item are moved to every occurrence of the screen item. An elementary item that is fully subscripted is deemed to have no OCCURS clauses applying to it.
  3. If the screen item is an update field, or it is an output field with OCCURS clauses applying to the sending item, then in a DISPLAY operation the contents of each occurrence of the sending item are moved to the corresponding occurrence of the screen item.
  4. If the screen item is an update or input field, then in an ACCEPT operation the data entered into each occurrence of the screen item is moved to the corresponding occurrence of the receiving item.
Parent topic: Screen Section


The OVERLINE Clause

The OVERLINE clause causes every character of the screen item to have a horizontal line above it when the item appears on the screen. The line is within the character-position.

General Format

Syntax Rules

  1. The OVERLINE clause can be used with a screen item.
  2. If the OVERLINE clause is specified at group level, it applies to all suitable subordinate elementary items.
  3. If this clause is used on a system that does not support overlining it has no effect.

General Rules

  1. The OVERLINE clause causes every character of the screen item to have a horizontal line above it when the item appears on the screen.
Parent topic: Screen Section


The PICTURE Clause in the Screen Section

The PICTURE clause describes the length, general characteristics and editing requirements of a screen item.

General Format

Syntax Rules

  1. The PICTURE clause can include any standard editing characters.
  2. The PICTURE clause must be used in conjunction with one or more of the FROM, TO or USING clauses. The USING clause must not be used with either the FROM or TO clause.
  3. PIC is an abbreviation for PICTURE.
  4. The PICTURE clause is allowed only with elementary items.
  5. The PICTURE clause need not be the same as the PICTURE clause of the data item referenced in the FROM, TO or USING clause but it must be such that the implied MOVE is legal.

General Rules

  1. The character-string describes the length and category of the screen item. It is used in the same way as the character-string in the PICTURE clause for a data item.
  2. We recommend that every numeric screen item either be a numeric edited item or contain only 9's in its PICTURE clause. Editing and de-editing are applied as necessary when data is moved to or from the associated data item.
Parent topic: Screen Section


The PROMPT Clause

The PROMPT clause causes the empty character positions in the screen item to be marked on the screen during an ACCEPT operation while the system is ready to accept operator-keyed data into that item.

General Format

Syntax Rules

  1. This clause is allowed only with input and update fields and with group items.
  2. If this clause is specified at group level, it applies to all subordinate elementary items.
  3. Identifier-1 must be a single-character alphabetic or alphanumeric data item.
  4. Identifier-1 must not be subject to an OCCURS clause.
  5. Literal-1 must be a one-character nonnumeric literal or a figurative constant.

General Rules

  1. For items in the Screen Section :
    1. PROMPT is always on.
    2. If the PROMPT clause is not specified, or is specified without the CHARACTER phrase, the default prompt character is used.
  2. For other data items referenced in an ACCEPT statement,
    1. PROMPT is on if and only if the PROMPT clause is specified on the ACCEPT statement.
    2. If the PROMPT clause is specified without the CHARACTER phrase, the default prompt character is used.
  3. The CHARACTER phrase specifies a prompt character to be used for marking empty character positions. The prompt character overrides the configured option. (See your COBOL system documentation about user interfaces for details on configuration options.)
  4. The PROMPT clause causes the prompt character to replace trailing spaces in alphanumeric or free format numeric screen items. It also causes the prompt character to replace leading suppressed digit positions in fixed format numeric edited screen items.
  5. The PROMPT clause has no effect on fixed format, nonedited numeric screen items or numeric edited screen items that have no zero-suppression positions.
  6. If PROMPT is on for a field, you cannot move the cursor past the end of the field, which is marked by prompt characters. An attempt to do so moves the cursor to the next field .
  7. If PROMPT is not on for a field, the cursor can be moved to the spaces following the end of the field.
  8. This clause has no effect if the SECURE clause is specified.
  9. The prompt characters appearing in the screen item are changed to spaces upon termination of the ACCEPT operation.
Parent topic: Screen Section


The REQUIRED Clause

The REQUIRED clause specifies that the operator must not leave the screen item empty.

General Format

Syntax Rules

  1. The REQUIRED clause is allowed only with input and update fields and with group items.
  2. This clause can be specified on a group screen item, in which case it applies to all suitable elementary items which are subordinate to that item.
  3. MF REQUIRED and EMPTY-CHECK are equivalent.

General Rules

  1. The REQUIRED clause takes effect during the execution of any ACCEPT statement that causes the screen item to be accepted provided the cursor enters the screen item at some time during the ACCEPT. Unless this clause is satisfied, terminator keystrokes are rejected and the cursor is repositioned to the beginning of the item.
  2. To satisfy this clause, alphanumeric screen items must contain at least one non-space, non-prompt character; numeric screen items must have a non-zero value.
  3. For update fields, the REQUIRED clause can be satisfied by initial data as well as by operator-keyed data.
  4. The REQUIRED clause cannot be effective if a function key is used to terminate an ACCEPT operation. (See your COBOL system documentation about user interfaces for details on configuration options.)
  5. An error message can be configured for display on the screen if the REQUIRED clause is not satisfied. (See your COBOL system documentation about user interfaces for details on configuration options.)
Parent topic: Screen Section


The REVERSE-VIDEO Clause

The REVERSE-VIDEO clause causes the screen item to be displayed in reverse-video.

General Format

Syntax Rules

  1. The REVERSE-VIDEO clause is allowed with any screen item.
  2. If the REVERSE-VIDEO clause is specified at group level, it applies to all suitable subordinate elementary items.

General Rules

  1. The REVERSE-VIDEO clause causes the screen item to be displayed in reverse-video.
Parent topic: Screen Section


The SECURE Clause

The SECURE clause prevents operator-keyed data from appearing on the screen.

General Format

Syntax Rules

  1. The SECURE clause is allowed only with input and update fields.
  2. This clause can be specified on a group screen item, in which case it applies to all suitable elementary items which are subordinate to that item.

    MF SECURE and NO-ECHO are equivalent.

General Rules

  1. When the SECURE clause is specified for input fields, only spaces and the cursor appear in the screen item. For update fields, the original contents of the field are displayed, but cannot be altered.
Parent topic: Screen Section


The SIGN Clause in the Screen Section

The SIGN clause specifies the position and representation of the operational sign.

General Format

Syntax Rules

  1. The SIGN clause is allowed only with input, output and update fields whose pictures contain the character "S".
  2. This clause is allowed only with elementary items.

General Rules

  1. It is recommended that the SEPARATE option be used when the SIGN clause is specified in a screen description. If the SEPARATE option is not specified, a sign denoted by "S" in a PICTURE clause appears as an overpunch.
Parent topic: Screen Section


The SIZE Clause

The SIZE clause specifies the current size of the screen item.

General Format

Syntax Rules

  1. The SIZE clause is allowed only with elementary screen items.
  2. Identifier-1 must be an unsigned numeric integer and must not be subject to an OCCURS clause.
  3. Integer-1 must be unsigned.

General Rules

  1. The SIZE clause has no effect if the size specified is zero.
  2. If the SIZE clause is specified for a numeric or numeric edited screen item and the size specified is not zero, the screen item is treated as though it were free format. This overrides the setting of the configuration option.
  3. If the size specified in the SIZE clause is less than that implied by the associated PICTURE or VALUE clause, only the left-hand portion of the screen item appears on the screen. If the JUSTIFIED clause is present in an ACCEPT statement, only the right-hand portion of the screen item appears. The remainder of the screen item can be considered to contain spaces or zeros, as appropriate.
  4. If the size specified in the SIZE clause is greater than that implied by the PICTURE or VALUE clause for output or literal fields, the screen item is padded on the right with spaces.
  5. Changing the value in identifier-1 alters the effective size of the screen item at run time. This can alter the screen positions of items whose descriptions follow it in the Screen Section. (See the topics The LINE Clause and The COLUMN Clause.)
Parent topic: Screen Section
Related information
The LINE Clause
The COLUMN Clause


The TO Clause

The TO clause identifies the destination of data accepted.

General Format

Syntax Rules

  1. The TO clause, when used with the FROM clause, is equivalent to the USING clause, both specifying the same identifier. It must not be used with the USING clause.
  2. The identifier in the TO clause can be qualified. If no OCCURS clause applies to the screen item, this identifier can be subscripted or indexed. It must be defined in the File, Working-Storage,

    MF Local-Storage,

    or Linkage Section of the program.

General Rules

  1. Executing an ACCEPT statement on a screen item whose description includes a TO clause accepts operator-keyed data into the screen item, and then moves that data to the associated data item.
Parent topic: Screen Section


The UNDERLINE Clause

The UNDERLINE clause causes the screen item to be underlined when it appears on the screen.

General Format

Syntax Rules

  1. The UNDERLINE clause is allowed with any screen item.
  2. If the UNDERLINE clause is specified at group level, it applies to all suitable subordinate elementary items.

General Rules

  1. The UNDERLINE clause causes the screen item to be underlined when it appears on the screen.
  2. This clause has no effect if your screen hardware does not support underline.
Parent topic: Screen Section


The USAGE Clause in the Screen Section

The USAGE clause specifies the format of a data item in the computer storage.

General Format

Syntax Rules

  1. The USAGE of a Screen Section data item must be either explicitly or implicitly defined as USAGE DISPLAY or USAGE DISPLAY-1.
Parent topic: Screen Section


The USING Clause

The USING clause identifies the source of data for display.

General Format

Syntax Rules

  1. The USING clause is equivalent to the TO and FROM clauses, both specifying the same identifier. It must not be used with either the TO or FROM clause.
  2. The identifier in the USING clause can be qualified. If no OCCURS clause applies to the screen item, this identifier can be subscripted or indexed. It must be defined in the File, Working-Storage, Local-Storage, or Linkage Section of the program.

General Rules

  1. Executing a DISPLAY statement on a screen item whose description includes a USING clause moves data from the associated data item to the screen item, and then displays the screen item on the screen.
  2. Executing an ACCEPT statement on a screen item whose description includes a USING clause accepts operator-keyed data into the screen item, and then moves that data to the associated data item.
Parent topic: Screen Section


The VALUE Clause in the Screen Section

The VALUE clause specifies literal information for display on the screen.

General Format

Syntax Rules

  1. The literal associated with the VALUE clause must be nonnumeric. It cannot be a figurative constant.
  2. The VALUE clause is allowed only with elementary items that have no PICTURE clauses.

General Rules

  1. The VALUE clause specifies literal information for display on the screen.
Parent topic: Screen Section


The ZERO-FILL Clause

The ZERO-FILL clause causes trailing prompt characters to be replaced by zeros instead of spaces.

General Format

Syntax Rules

  1. This clause is allowed only with input and update fields that are alphabetic or alphanumeric.

General Rules

  1. The ZERO-FILL clause causes trailing prompt characters to be replaced by zeros instead of spaces when data is moved from the screen item to the receiving item. This occurs only if the operator enters data into the screen item.
  2. If the receiving item has a JUSTIFIED clause, the ZERO-FILL clause causes leading positions left vacant by justification to be zero-filled.
Parent topic: Screen Section


Procedure Division

  • Procedure Division General Description
  • The PROCEDURE DIVISION Header
    The Procedure Division is identified by and must begin with a header in one of the following formats:
  • Arithmetic Expressions
  • Conditional Expressions
  • Common Phrases
  • File I/O Concepts
  • Conformance for Parameters and Returning Items
  • Intrinsic Functions
  • Statements
Parent topic: Part 2. Program Definition


Procedure Division General Description

ANS85 The Procedure Division is optional.

The Procedure Division in a program definition

ISO2002 MF , function definition

or method definition contains procedures to be executed. These procedures can be declarative and/or nondeclarative.

ISO2002 MF The Procedure Division for an object definition and a factory definition contains the methods that may be invoked on the object or factory object.

MF The Procedure Division in a call prototype contains no procedures, except that it may contain the ENTRY statement.

ISO2002 MF The Procedure Division in a function prototype, method prototype or program prototype specifies the parameters and returning item, if any.

General Formats for Format 1 (with-sections)

General Formats for Format 2 (without-sections)

General Formats for Format 3 (interface-object-or-factory)

Comments:

The generic term procedure-division-header is described in the topic The PROCEDURE DIVISION Header.

Formats 1 and 2 can be used only in a program definition,

ISO2002 MF a program prototype definition, a function definition, a function prototype definition

ISO2002 MF a method definition, or a

MF call prototype.

ISO2002 MF Format 3 can be used only in a factory definition or an interface definition

ISO2002 MF or an object definition.

The declarative sentence shown above is a USE statement (see the topics The USE Statement, The USE FOR DEBUGGING Statement, and The USE BEFORE REPORTING Statement ). It specifies when the section is to be executed.

A procedure is composed of a paragraph or group of paragraphs, or a section or group of sections in the Procedure Division. A procedure-name is a word used to refer to a paragraph or section in the source element in which it occurs. It consists of a paragraph-name (that may be qualified) or a section-name.

If one paragraph is in a section, all must be.

OSVS VSC2 MF This rule is not enforced.

A paragraph comprises a paragraph-name followed by a period and a space, and any number of sentences or, if the paragraph-name is omitted, one or more successive sentences following the PROCEDURE DIVISION header or a section header. It is terminated either immediately before the next paragraph-name or section-name or at the end of the Procedure Division, or, in the declaratives portion, with END DECLARATIVES.

A section comprises a section header followed by any number of paragraphs. It is terminated either immediately before the next section or at the end of the Procedure Division, or, in the declaratives portion, with END DECLARATIVES.

VSC2 MF However, a section in the declaratives need not have a declarative-sentence; it can be invoked by a PERFORM statement. (See the topic The PERFORM Statement for details of the PERFORM statement.)

VSC2 MF Sentences that are not explicitly contained within a named paragraph as described above are considered to be contained within an unnamed implicit paragraph. Paragraphs that are not explicitly contained within a section are considered to be contained within an implicit, unnamed section.

In a program definition

ISO2002 MF or method definition,

execution begins with the first statement in the Procedure Division, excluding declaratives. Statements are then executed in the order in which they are written, except where the rules indicate some other order.

MF In a call prototype the Procedure Division is never executed.

ISO2002 MF In an object definition, declaratives behave in the same way as if they had been specified in every contained method definition

ISO2002 In a factory definition, declaratives behave in the same way as if they had been specified in every contained method definition.

This segment of the chapter deals with arithmetic and conditional expressions, common and input/output phrases, intrinsic functions and COBOL verbs.

MF The procedure-division-header is optional in Format 2 of the Procedure Division. However, it is only optional if there are no divisions coded before this and if the Procedure Division begins with a COBOL sentence (not a section header, paragraph header, or Declarative Section).

Parent topic: Procedure Division
Related information
The PROCEDURE DIVISION Header
The USE Statement
The USE FOR DEBUGGING Statement
The USE BEFORE REPORTING Statement
The PERFORM Statement


The PROCEDURE DIVISION Header

The Procedure Division is identified by and must begin with a header in one of the following formats:

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • DEFAULTCALLS - sets the default calling convention if none is explicitly coded in the Procedure Division header.
    • STICKY-LINKAGE - controls whether addressability to Linkage Section items is maintained between calls to different entry points in the same program.

Syntax Rules for All Formats

  1. MF Mnemonic-name is necessary only if the runtime element is being invoked by another runtime element and that runtime element is using a calling convention other than that used as default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant implementation of a non-COBOL language for the run-time environment.

    Mnemonic-name must be defined in the Special-Names paragraph. See the topic The Special-Names Paragraph in the chapter Environment Division for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run time environment.

  2. MF CHAINING and USING are equivalent.
  3. ISO2002 MF If data-name-1 or data-name-2 is defined with the USAGE OBJECT REFERENCE clause, the ACTIVE-CLASS phrase must not be specified.
  4. ISO2002 MF Data-name-3 must be defined as a level 01 or level 77 entry in the Linkage Section. The data description entry for data-name-3 must not contain a REDEFINES clause. A data item elsewhere in the Linkage Section may specify REDEFINES data-name-3.
  5. ISO2002 MF Data-name-3 must not be the same as data-name-1 or data-name-2.

Syntax Rules for Format 1

  6. Data-name-1 must be defined as a level 01 or a level 77 entry in the Linkage Section

    MF , File Section or Working-Storage Section

    . A particular user-defined word must not appear more than once as data-name-1.

    OSVS VSC2 MF It may appear more than once.

    The data description entry for data-name-1 must not contain a REDEFINES clause.

    OSVS VSC2 MF It may contain a REDEFINES clause.

    Data-name-1 may, however, be the object of a REDEFINES clause elsewhere in the Linkage Section.

  7. ISO2002 MF Data-name-2 must be defined as a level 01 or a level 77 entry in the Linkage Section

    MF , File Section or Working-Storage Section , unless the source unit is a method definition or method prototype definition

    . Data-name-2 must be defined as a data item of class numeric, object or pointer.

    MF Data-name-2 can be of any class, but the length must be no greater than 8 bytes.

Syntax Rules for Formats 1 and 3

  8. ISO2002 MF NET JVM The RETURNING phrase must be specified in a function definition and in a function prototype definition.
  9. ISO2002 MF NET JVM The RETURNING phrase may be specified in a method definition, a program definition or a program prototype.

Syntax Rules for Format 2

  10. MF Format 2 can only be used in a program in which the EXTERNAL clause is specified in the Program-ID paragraph, that is a call prototype.
  11. MF Data-name-1 and data-name-2 must be defined as 01 level records in the Linkage Section.
  12. MF Typedef-name-1, typedef-name-2, and typedef-name-3 must be previously defined in the same source file as a programmer-defined usage by means of a TYPEDEF clause.

Syntax Rules for Format 3

  13. Data-name-1, data-name-2, data-name-4 and data-name-5 must either be defined as 01 level records in the Linkage Section or be followed by the AS phrase.
  14. Type-name-1 must be a .NET native type.
  15. Custom-attribute-clause is as described in the section The CUSTOM-ATTRIBUTE clause in the Data Division chapter.
  16. YIELDING may be specified only in the context of an Iterator. See Iterator-ID.
  17. The type of the item specified in the YIELDING phrase determines the type of the iterator.
  18. A parameter including the syntax '= default-expression' is an optional parameter, and default-expression must evaluate to a constant, whose type is compatible with that of the parameter. All such optional parameters must follow any non-optional parameters.

General Rules for All Formats

  1. Up to five data-names are permitted in the USING phrase.

    ISO2002 MF XOPEN Up to sixty-two data-names are permitted in the USING phrase.

  2. The BY REFERENCE, the BY VALUE and the BY OUTPUT phrases are transitive across the parameters that follow them until another BY REFERENCE, BY VALUE or BY OUTPUT phrase is encountered. If neither the BY REFERENCE, the BY VALUE nor the BY OUTPUT phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

General Rules for Format 1

  3. MF Mnemonic-name identifies the calling convention that this program assumes has been adopted by the calling program that invokes it. This calling convention is also used for subsequent entry points unless those entry points specify a calling convention explicitly. If the calling convention actually used is different to that implied by mnemonic-name, then the COBOL system may become corrupt.
  4. MF If data-name-1 is defined as a level 01 or a level 77 entry in the File Section or Working-Storage Section then the activated runtime element operates as if a data item had been declared in the Linkage Section with the same data declaration as data-name-1 and the contents of that data item were moved to data-name-1 prior to executing the first statement in the activated runtime element. In an initial program, these values are overwritten by the initialization of the program's working storage data and are therefore not available to the called program.
  5. ENT OSVS OS390 If the activating runtime element is COBOL the following rules apply. If the activating runtime element is not COBOL, see your COBOL system documentation on interfacing for details of when you need to use the BY REFERENCE or BY VALUE clauses.
  6. ENT OSVS OS390 At all times in the activated element, references to data-name-1

    ISO2002 MF , data-name-2 and data-name-3

    are resolved in accordance with their description in the Linkage Section. If this description defines a greater number of character positions than the corresponding data item in the activating element, unpredictable results can occur. Failure to comply with this rule or exceeding the maximum allowed size of the system area for a particular run time environment may result in the system becoming catastrophically corrupt.

  7. MF When a program is called and a BY REFERENCE operand in the USING phrase corresponds to a parameter in the calling program, a referential connection is established and endures until control is returned to the calling program. If the program is called a second time, without any intervening cancel of the program, and that same BY REFERENCE operand does not correspond to a parameter in the calling program, then you must not reference that operand unless the STICKY-LINKAGE Compiler directive is specified.
  8. ENT OSVS OS390 data-name 4 must be defined in the Linkage Section.

General Rules for Formats 1 and 3

  9. The USING phrase identifies the names of the formal parameters used by the program,

    ISO2002 , function

    ISO2002 MF or method for any arguments passed to it

    . The arguments passed to it are identified in the activating source element by one of the following:

    • The USING phrase of a CALL statement
    • ISO2002 The arguments in a function-identifier
    • ISO2002 MF The USING phrase of an INVOKE statement
    • ISO2002 MF The arguments specified in an inline invocation of a method
    • ISO2002 MF The arguments defined by the rules of an object-property for invocation of an implicit SET property method.

    The correspondence between the two lists of names is established on a positional basis

  10. If the argument is passed by content, the activated runtime element operates as if the record in the Linkage Section were allocated by the activating runtime element during the process of initiating the activation and as if this record does not occupy the same storage area as the argument in the activating runtime element.

    ISO2002 MF If the activated runtime element is a program for which there is no program-specifier in the Repository paragraph of the activating runtime element, the allocated record is handled as follows.

    The allocated record is of the same length as the argument, where the maximum length is used if the argument is described as a variable-occurrence data item. That argument is moved to this allocated record without conversion. This record is then treated by the activated runtime element as if it were the argument and as if it were passed by reference.

    ISO2002 MF If the activated runtime element is one of the following:

    ISO2002 MF
    • ISO2002 MF A program for which there is a program-specifier in the Repository paragraph of the activating runtime element
    • ISO2002 MF A method
    • ISO2002 MF A function

    ISO2002 MF then this allocated record is one of:

    ISO2002 MF
    • ISO2002 MF A data item of the same category, usage, and length as the argument, if the formal parameter is described with the ANY LENGTH clause
    • ISO2002 MF A data item with the same description and the same number of bytes as the formal parameter, where the maximum length is used if the formal parameter is described as a variable-occurrence data item.

    ISO2002 MF The argument is used as the sending operand and the allocated record as the receiving operand in one of the following:

    ISO2002 MF
    • ISO2002 MF If the formal parameter is numeric, a COMPUTE statement without the ROUNDED phrase
    • ISO2002 MF If the formal parameter is of class index, object, or pointer, a SET statement
    • ISO2002 MF A MOVE statement.

    ISO2002 MF The allocated record is then treated as if it were the argument and it were passed by reference.

  11. If the argument is passed by reference, the activated runtime element operates as if the formal parameter occupies the same storage area as the argument.
  12. ISO2002 MF If the argument is passed by value, the activated runtime element operates as if the record in the Linkage Section were allocated by the activating runtime element during the process of initiating the activation and as if this record does not occupy the same storage area as the argument in the activating runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the activated runtime element as if it were the argument and as if it were passed by reference.
  13. If the OPTIONAL phrase is specified for data-name-1, you can either specify a valid corresponding argument, or replace the corresponding argument with the OMITTED phrase; if data-name-1 is not specified as OPTIONAL, you cannot use the OMITTED phrase as the corresponding argument.

    Note that, in COBOL, the storage for the returning item is allocated in the activating source unit. The activated element contains only a formal description in its linkage section.

    This form of optional parameter is distinct from the optional parameter that can be used in Managed COBOL, and which applies to VALUE parameters. Such parameters are specified by use of the '= default-expression' syntax; see General Rule 18.

General Rules for Format 2

  14. MF If a call prototype (program with the EXTERNAL clause in the Program-ID paragraph) contains a format 2 PROCEDURE DIVISION header and another program in the same source file includes a CALL literal statement referencing the program-name of this call prototype, then the following rules apply:
    1. If a call convention is specified in the CALL statement, it must match that specified (implicitly or explicitly) in the prototype. If no call convention is specified in the CALL statement, the call convention specified (implicitly or explicitly) in the prototype is used.
    2. The number of parameters specified in the CALL statement must equal the number of parameters specified in the prototype, except as allowed by the REPEATED phrase.
    3. For each parameter specified in the CALL statement, the following rules apply:
      1. If there is a BY REFERENCE or a BY CONTENT phrase associated with the parameter, the corresponding parameter in the prototype must be specified BY REFERENCE.
      2. If there is a BY VALUE phrase associated with the parameter, the corresponding parameter in the prototype must be specified BY VALUE.
      3. If the parameter in the CALL statement has no BY REFERENCE, BY CONTENT or BY VALUE phrase, the phrase specified (implicitly or explicitly) in the prototype is used.
      4. This rule overrides the rules that apply when no matching call prototype is found. In other words, when no call prototype is used, all parameters up to the first BY phrase are treated as if BY REFERENCE were specified and all parameters after any BY phrase, that do not themselves have an explicit BY phrase, use the last one in effect. However, when a matching call prototype is found, its definitions for the BY phrases take precedence.
      5. If the parameter in the prototype is of class numeric, or it is a pointer or index data-item, then the parameter in the CALL must have the same data definition.
      6. If the parameter in the prototype is of class alphanumeric, the parameter in the CALL must also be of class alphanumeric and be at least as long as the parameter in the prototype.
      7. If ANY is specified in the prototype, the parameter in the CALL statement can be of any class.
    4. If the CALL statement includes the GIVING or RETURNING clause, the prototype must also include the clause, and vice versa. The data definition of the data item specified in the CALL must be the same as that of the data item specified in the prototype.
    5. The DELIMITED BY SIZE phrase in the prototype can be used only for alphanumeric parameters. In this case, the corresponding parameter in the CALL statement is moved to an implicitly allocated data area, and a binary 0 (x"00") character is placed immediately following this copy of the data. If the BY SIZE phrase is omitted, the corresponding parameter in the CALL statement is moved to an implicitly allocated data area, and a binary 0 (x"00") character is placed immediately following the last non-space character in the copy data. The intention is to help in interfacing to languages such as C, which use null terminated text strings.
    6. The REPEATED phrase indicates that there must be at least integer-1 and no more than integer-2 repetitions of the final parameter. If integer-1 TO integer-2 is not specified, integer-1 is taken as 0 and integer-2 as infinite.

General Rules for Format 3

  15. The data item referenced by data-name-5 has no value when the runtime element is activated. An attempt to access the value of the data item referenced by data-name-5 prior to that item being a receiving item will result in a runtime exception..
  16. At all times in the activated element, references to data-name-1, data-name-2, data-name-4 and data-name-5 are resolved in accordance with their description in the Linkage Section or the AS phrase. If this description defines a greater number of character positions than the corresponding data item in the activating element, unpredictable results can occur. Failure to comply with this rule or exceeding the maximum allowed size of the system area for a particular run time environment may result in the system becoming catastrophically corrupt.
  17. If the CUSTOM-ATTRIBUTE clause is specified, the custom attribute information is included in the generated code.
  18. When the method is called, any optional parameters may be omitted by the invoking code; in which case, the default value specified in default-expression is passed. If an optional parameter is omitted, all following parameters must also be omitted.
Parent topic: Procedure Division
Related information
The Iterator-ID Paragraph
The Special-Names Paragraph


Arithmetic Expressions

An arithmetic expression can be an identifier of a numeric elementary item, a numeric literal, such identifiers and literals separated by arithmetic operators or bitwise operators (or both), two arithmetic expressions separated by an arithmetic or bitwise operator, or an arithmetic expression enclosed in parentheses. Any arithmetic expression can be preceded by a unary arithemetic or bitwise operator.

OSVS VSC2 MF In the following discussion:

  • OSVS VSC2 MF The term "numeric data item" encompasses floating-point data items in addition to fixed-point data items
  • OSVS VSC2 MF The term "numeric literal" encompasses floating-point literals in addition to fixed-point literals

Those identifiers and literals appearing in an arithmetic expression must represent either numeric elementary items or numeric literals on which arithmetic can be performed.

  • Arithmetic Operators
  • Bitwise Operators
  • Permissible Combinations of Symbols
  • Formation and Evaluation Rules
  • Intermediate Results
Parent topic: Procedure Division


Arithmetic Operators

Five binary arithmetic operators and two unary arithmetic operators can be used in arithmetic expressions. They are represented by specific characters that must be preceded by a space and followed by a space.

Binary Arithmetic Operators | Meaning
+ | Addition
- | Subtraction
* | Multiplication
/ | Division
** | Exponentiation
Unary Arithmetic Operators | Meaning
+ | The effect of multiplication by numeric literal +1
- | The effect of multiplication by numeric literal -1
Parent topic: Arithmetic Expressions
Related reference
Undefined Results of MOVE and Arithmetic Operations


Bitwise Operators

Four binary bitwise operators and one unary bitwise operator can be used in arithmetic expressions. They are represented by reserved words that must be preceded by a space and followed by a space.

Binary Bitwise Operators | Meaning
B-AND | The effect of performing a logical AND between the two data items
B-OR | The effect of performing a logical OR between the two data items
B-XOR | The effect of performing a logical XOR (exclusive OR) between the two data items
B-EXOR | The effect of performing a logical XOR (exclusive OR) between the two data items
Unary Bitwise Operator | Meaning
B-NOT | The effect of performing a logical NOT on the data item

B-XOR and B-EXOR are equivalent.

These operators can only be used in any arithmetic expressions with COMP-5, COMP-X or numeric literal operands. B-NOT takes one operand. The rest take two operands. The result is as if the equivalent logical operator library routine were used on the operands and the result returned in a temporary data item the size of the largest item used. If the items differ in size then the smaller item is moved to a temporary data item of the same size as the larger item. If the operands are of mixed type (COMP-5, COMP-X) then the smaller operand is moved to a temporary item of the same type as the larger. For best performance use consistent data types.

Here is an example program:

data division.
working-storage section.
01 n1 pic 9(9).
 01 n2 pic xx comp-5.
 01 n3 pic xxxx comp-5.
 procedure division.
     move 2 to n2
     move 4 to n3
     compute n1 = n2 b-or n1        *> n1 = 6
     if n2 b-and n1 = n2
         display 'true'
     end-if
     compute n1 = b-not n2          *> n1 = 65533
     compute n1 = n2 b-xor n3 + 1   *> n1 = 7
     compute n1 = n2 b-and 2        *> n1 = 2
Parent topic: Arithmetic Expressions


Permissible Combinations of Symbols

The permissible combinations of variables, numeric literals, arithmetic operator and parentheses are given in Table 1.

Table 1. Combination Of Symbols In Arithmetic Expressions
First Symbol | Second Symbol
 | Variable | * / ** + - B-AND B-OR B-XOR B-EXOR | Unary + - B-NOT | ( | )
Variable | - | P | - | - | P
* / ** + - B-AND B-OR B-XOR B-EXOR | P | - | P | P | -
Unary + - B-NOT | P | - | - | P | -
( | P | - | P | P | -
) | - | P | - | - | P
P | indicates a permissible pair of symbols
- | indicates an invalid pair
Variable | indicates an identifier or literal
Parent topic: Arithmetic Expressions


Formation and Evaluation Rules

The following formation and evaluation rules aplly to arithmetic expressions:

  1. Parentheses can be used in arithmetic expressions to specify the order in which elements are to be evaluated. Expressions within parentheses are evaluated first, and within nested parentheses, evaluation proceeds from the least inclusive set to the most inclusive set. When parentheses are not used, or parenthesized expressions are at the same level of inclusiveness, the following hierarchical order of execution is implied:
    1st | Unary plus and minus, B-NOT
    2nd | Exponentiation
    3rd | Multiplication and division
    4th | Addition and subtraction
    5th | B-AND
    6th | B-XOR and B-EXOR
    7th | B-OR

    Thus, in the expression:

     1 + 2 * 3

    the order of evaluation is:

    1. 2 * 3

      yielding an intermediate result of 6

    2. 1 + 6

      giving a result of 7.

  2. Parentheses are used either to eliminate ambiguities in logic where consecutive operations of the same hierarchical level appear or to modify the normal hierarchical sequence of execution in expressions where it is necessary to have some deviation from the normal precedence. When the sequence of execution is not specified by parentheses, the order of execution of consecutive operations of the same hierarchical level is from left to right.
  3. An arithmetic expression can only begin with the symbol "(", "+", "-", the bitwise operator B-NOT, or a variable, and can only end with a ")" or a variable. There must be a one-to-one correspondence between left and right parenthesis of an arithmetic expression such that each left parenthesis is to the left of its corresponding right parenthesis.
  4. Arithmetic expressions allow you to combine arithmetic operations without the restrictions on composite of operands and/or receiving data items. See, for example, Syntax Rule 3 of The ADD Statement in this chapter.
Parent topic: Arithmetic Expressions


Intermediate Results

As the expression is evaluated, one or more intermediate results is derived. Conceptually, each intermediate result is stored in a temporary data item, the value of which is determined by the parameter you select in the ARITHMETIC Compiler directive.

If you select the ARITHMETIC"MF" Compiler directive, the Micro Focus COBOL system evaluates each intermediate result using an internal floating-point register of 40 decimal digits. The most significant nonzero digit of each nonzero intermediate result is stored in the first digit of the register. The decimal point location depends on the value. Intermediate results are truncated to 40 digits.

If you select the ARITHMETIC"TRUNC20" Compiler directive, the Micro Focus COBOL system evaluates each intermediate result in the same manner as when ARITHMETIC"MF" is selected, except that the number of digits to the right of the decimal point is truncated to 20 at each step in the evaluation of the expression. You should use this directive only when you require truncation similar to that provided in COBOL WorkBench. If you use this directive, be aware that the system limit is 38 digits, but this limit can be affected by the ARITH and DIALECT directives.

The OS/VS COBOL, VS COBOL II, DOS/VS COBOL, COBOL/370 and OS/390 systems compute intermediate results to an accuracy determined by the pictures of the operands in the expressions. The rules, which are slightly different for each version of COBOL, are documented in appendices of the IBM VS COBOL for OS/VS manual, the VS COBOL II Application Programming Guide, and the COBOL for OS/390 & VM V2R2 Programming Guide. Each intermediate result has a picture of 9(n)V9(m). The maximum value of n+m is either 30 or 31 depending on the system and the chosen arithmetic option.

If you specify the OSVS or VSC2 options for intermediate results, this COBOL system emulates the selected mainframe behavior by truncating its results accordingly, with the following limitations:

  • The maximum number of integer and decimal places allowed by this COBOL system is 18 for each. Truncation of intermediate results ceases at the point in the expression where this limit is reached. A warning message is issued at compile time if this occurs.
  • The rules apply to fixed-point numerical expressions only. If the expression contains any floating-point operands or any operation which causes it to be evaluated in floating point (see the topic Intrinsic Functions), all truncation of intermediate results ceases.
  • Floating-point results are, by their nature, inexact and may vary across platforms by a small degree.
Parent topic: Arithmetic Expressions
Related information
Intrinsic Functions


Conditional Expressions

Conditional expressions identify conditions that are tested to enable selection between alternate paths of control depending upon the truth value of the condition. Conditional expressions are specified in the

ANS85 EVALUATE,

IF, PERFORM and SEARCH statements. Two categories of conditions are associated with conditional expressions: simple conditions and complex conditions. Each can be enclosed within any number of paired parentheses, in which case its category is not changed.

OSVS If the OSVS Compiler directive is set, reference modification cannot be used within a conditional expression.

  • Simple Conditions
  • Complex Condition
  • Abbreviated Combined Relation Conditions
Parent topic: Procedure Division


Simple Conditions

The simple conditions are the relation, class, condition-name, switch-status, sign and omitted-argument conditions. A simple condition has a truth value of "true" or "false". The inclusion in parentheses of simple conditions does not change the simple truth value.

See also Complex Condition.

  • Relation Condition
  • Class Condition
    The class condition determines whether the operand is numeric, or alphabetic
  • Condition-name Condition (Conditional Variable)
    In a condition-name condition, a conditional variable is tested to determine whether or not its value is equal to one of the values associated with a condition-name.
  • Switch-Status Condition
    A switch-status condition determines the "on" or "off" status of one of the
  • Sign Condition
    The sign condition determines whether or not the algebraic value of an arithmetic expression is less than, greater than, or equal to zero. The general format for a sign condition is as follows:
  • Omitted-argument Condition
    The omitted-argument condition determines whether an argument was provided to a function, method, or program.
  • Instance-of Condition
    The instance-of condition determines whether an object reference is an instance of a particular class or interface.
Parent topic: Conditional Expressions
Related information
Complex Condition


Relation Condition

A relation condition causes a comparison of two operands, each of which can be the data item referenced by an identifier, a literal or the value resulting from an arithmetic expression. A relation condition has a truth value of "true" if the relation exists between the operands. Comparison of two numeric operands is permitted regardless of the formats specified in their respective USAGE clauses. However, for all other comparisons the operands must have the same usage. If either of the operands is a group item, the nonnumeric comparison rules apply.

OSVS VSC2 A nonnumeric literal can be enclosed in parentheses.

OSVS Note that " = TO", "> THAN" and "< THAN" are accepted.

OSVS MF THEN may be used instead of THAN.

The first operand (identifier-1, literal-1 or arithmetic-expression-1) is called the subject of the condition; the second operand (identifier-2 or literal-2 or arithmetic-expression-2) is called the object of the condition. The relation condition must contain at least one reference to a variable.

The relational operator specifies the type of comparison to be made in a relation condition. A space must precede and follow each reserved word comprising the relational operator. When used, "NOT" and the next key word or relation character are one relational operator that defines the comparison to be executed for truth value; for example, "NOT EQUAL" is a truth test for an "unequal" comparison; " NOT GREATER" is a truth test for an "equal" or "less" comparison. The meaning of the relational operators is shown in the Relational Operators table below.

The following relational operators are equivalent:

IS EQUAL TO | and | EQUALS;
IS NOT EQUAL TO | and | IS UNEQUAL TO;
IS GREATER THAN | and | EXCEEDS;
IS NOT GREATER THAN | and | IS LESS THAN OR EQUAL TO;
IS NOT LESS THAN | and | IS GREATER THAN OR EQUAL TO.
Table 1. Relational Operators
Meaning | Relational Operator
Greater than or not greater than | {short description of image}
Less than or not less than | {short description of image}
Equal or not equal to | {short description of image}
Greater than or equal to | {short description of image}
Less than or equal to | {short description of image}
Equal to | {short description of image}
Not equal to | {short description of image}
Greater than | {short description of image}

The required relational characters '<', '>', and '=' are not underlined to avoid confusion with other symbols such as '>' (greater than or equal to).

  • Comparison of Numeric Operands (Relation Condition)
  • Comparison of Nonnumeric Operands (Relation Condition)
  • Comparisons Involving Index-Names and/or Index Data Items (Relation Condition)
  • Comparisons Involving Data Items with USAGE POINTER (Relation Condition)
    Two items whose USAGE is either implicitly or explicitly POINTER can be compared. Only the relational operators which test for exact equality or inequality are permitted in pointer comparisons.
  • Comparisons Involving Data Items with USAGE PROCEDURE-POINTER (Relation Condition)
    Two items whose USAGE is PROCEDURE-POINTER can be compared.
  • Comparisons Involving Data Items with USAGE OBJECT (Relation Condition)
    You can compare two object references to see if they refer to the same object.
Parent topic: Simple Conditions


Comparison of Numeric Operands (Relation Condition)

General Format:

Comparison of Numeric Operands

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as '>' (greater than or equal to).

General Rules:

  1. For operands whose class is numeric a comparison is made with respect to the algebraic value of the operands. The length of the literal or arithmetic expression operands in terms of number of digits represented, is not significant. Zero is considered a unique value regardless of the sign.
  2. Comparison of these operands is permitted regardless of the manner in which their usage is described. Unsigned numeric operands are considered positive for purposes of comparison.
  3. Numeric-edited items are of class alphanumeric, and comparisons involving them follow the rules for comparison of nonnumeric operands, as below.
Parent topic: Relation Condition


Comparison of Nonnumeric Operands (Relation Condition)

General Format:

Comparison of Nonnumeric Operands

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as '>' (greater than or equal to).

General Rules:

  1. For nonnumeric operands, or one numeric and one nonnumeric operand, a comparison is made with respect to a specified collating sequence of characters (see the topic The Object-Computer Paragraph). If one of the operands is specified as numeric, it must be an integer data item or an integer literal and:
    1. If the nonnumeric operand is an elementary data item or a nonnumeric literal, the numeric operand is treated as though it were moved to an elementary alphanumeric data item of the same size as the numeric data item (in terms of standard data format characters), and the contents of this alphanumeric data item were then compared to the nonnumeric operand. (See the topic The MOVE Statement.)
    2. If the nonnumeric operand is a group item, the numeric operand is treated as though it were moved to a group item of the same size as the numeric data item (in terms of standard data format characters), and the contents of this group item were then compared to the nonnumeric operand. (See the topic The MOVE Statement.)
    3. A non-integer numeric operand cannot be compared to a nonnumeric operand.

    The size of an operand is the total number of standard data format characters in the operand.

  2. OSVS Comparison of a numeric-edited data item with figurative constants is allowed and is treated as an alphanumeric comparison.
  3. MF Numeric and nonnumeric operands can be compared when their usage is not the same. The numeric operand is treated as if it were moved to a USAGE DISPLAY item of the same size (in terms of standard data format characters), and the contents of this were then compared to the nonnumeric operand.

    There are two cases to consider:

    1. Operands of equal size - if the operands are of equal size, comparison effectively proceeds by comparing characters in corresponding character positions starting from the high order end and continuing until either a pair of unequal characters is encountered or the low order end of the operand is reached, whichever comes first. The operands are determined to be equal if all pairs of characters compare equally through the last pair, when the low order end is reached.

      The first encountered pair of unequal characters is compared to determine their relative position in the collating sequence. The operand that contains the character that is positioned higher in the collating sequence is considered to be the greater operand.

    2. Operands of unequal size - if the operands are of unequal size, comparison proceeds as though the shorter operand were extended on the right by sufficient spaces to make the operands of equal size.
Parent topic: Relation Condition
Related information
The Object-Computer Paragraph
The MOVE Statement


Comparisons Involving Index-Names and/or Index Data Items (Relation Condition)

General Format:

Index-Names and Index Data Items

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as '>' (greater or equal to).

General Rules:

  1. Relation tests can be made only between:

    1. Two index-names. The result is the same as if the corresponding occurrence numbers were compared.
    2. An index-name and a numeric data item or numeric literal. The occurrence number that corresponds to the value of the index-name is compared to the data item or literal.
    3. An index data item and an index-name or another index data item. The actual values are compared without conversion.
    4. OSVS VSC2 An index-name can be compared with an arithmetic expression. The occurrence number that corresponds to the value of the index-name is compared to the computed value of the expression.
    5. The result of the comparison of an index data item with any data item or literal not specified above is undefined.
Parent topic: Relation Condition


Comparisons Involving Data Items with USAGE POINTER (Relation Condition)

Two items whose USAGE is either implicitly or explicitly POINTER can be compared. Only the relational operators which test for exact equality or inequality are permitted in pointer comparisons.

General Format

Syntax Rules

  1. Identifier-1 and identifier-3 refer to an 01 or 77 level items in the Linkage Section.
  2. MF Identifier-1 and identifier-3 can refer to any data items defined in the Data Division.
  3. Identifier-2 and identifier-4 refer to items with USAGE IS POINTER.
  4. Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if the two addresses are the same, otherwise they are unequal.
  2. This type of relation condition is allowed in IF, PERFORM, EVALUATE and SEARCH (Format 1) statements. It is not allowed in SEARCH (Format 2) statements (SEARCH ALL) because no meaningful ordering can be applied to pointer data items.
Parent topic: Relation Condition


Comparisons Involving Data Items with USAGE PROCEDURE-POINTER (Relation Condition)

Two items whose USAGE is PROCEDURE-POINTER can be compared.

General Format

Syntax Rules

  1. Identifier-1 and identifier-2 refer to items with USAGE IS PROCEDURE-POINTER.
  2. Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if the two addresses are the same, otherwise they are unequal.
  2. This type of relation condition is allowed in IF, PERFORM, EVALUATE and SEARCH (Format 1) statements. It is not allowed in SEARCH (Format 2) statements (SEARCH ALL) because no meaningful ordering can be applied to pointer data items.
Parent topic: Relation Condition


Comparisons Involving Data Items with USAGE OBJECT (Relation Condition)

You can compare two object references to see if they refer to the same object.

General Format

Syntax Rules

  1. Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if they identify the same object, otherwise they are unequal.
Parent topic: Relation Condition


Class Condition

The class condition determines whether the operand is numeric, or alphabetic

ANS85 or alphabetic-lower, or alphabetic-upper, or contains only the characters in the set of characters specified by the CLASS clause as defined in the Special-Names paragraph of the Environment Division.

General Format

Syntax Rules

  1. The class of an operand is determined as follows:
    1. An operand is numeric if it consists entirely of the characters 0,1, 2, 3, ... , 9, with or without an operational sign.
    2. An operand is alphabetic if it consists entirely of the upper-case letters A, B, C, ... , Z, space,

      ANS85 or the lower-case letters a, b, c, ... , z, space,

      or any combination of the upper-case

      ANS85 and lower-case

      letters and spaces.

    3. ANS85 An operand is alphabetic-lower if it consists entirely of the lower-case letters a, b, c, ... , z, and space.
    4. ANS85 An operand is alphabetic-upper if it consists entirely of the upper-case letters A, B, C, ... , Z, and space.
    5. ANS85 An operand conforms to class-name-1 if it consists entirely of the characters listed in the definition of class-name-1 in the Special-Names paragraph.
  2. Identifier-1 must reference a data item whose usage is explicitly or implicitly DISPLAY, or in the case of the NUMERIC test, is one of: DISPLAY,

    MF COMPUTATIONAL, COMPUTATIONAL-X,

    OSVS VSC2 MF XOPEN COMPUTATIONAL-3

    MF XOPEN COMPUTATIONAL-5

    ANS85 or PACKED-DECIMAL.

  3. ANS85 If identifier-1 is a function-identifier, it must reference an alphanumeric

    MF or national

    function.

General Rules

  1. When the class condition does not include the word NOT and identifier-1 is a zero-length group item, the result of the class test is always false.

    When used, NOT and the next key word specify one class condition that defines the class test to be executed for truth value; e.g. NOT NUMERIC is a truth test for determining that an operand is nonnumeric. When the class condition includes the word NOT and identifier-1 is a zero-length group item, the result of the class test is always true.

    MF The truth value of a class test involving a zero-length group item is reversed by the ZEROLENGTHFALSE Compiler directive.

  2. The NUMERIC test cannot be used with an item whose data description describes the item as alphabetic or as a group item composed of elementary items whose data description indicates the presence of operational sign(s). If the data description of the item being tested does not indicate the presence of an operational sign, the item being tested is determined to be numeric only if the contents are numeric and an operational sign is not present. If the data description of an elementary item being tested does indicate the presence of an operational sign, the item being tested is determined to be numeric only if the contents are numeric and a valid operational sign is present. Valid operational signs for data items described with the SIGN IS SEPARATE clause are the standard data format characters, "+" and "-"; valid operational signs for data items not described with the SIGN IS SEPARATE clause are described in the section Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.

    OSVS MF The NUMERIC test can be used with an item defined as a group item composed of elementary items whose data description indicates the presence of operational sign(s).

  3. The ALPHABETIC test cannot be used with an item whose data description describes the item as numeric. The item being tested is determined to be alphabetic only if the contents consist of any combination of the upper-case alphabetic characters "A" through "Z" and the space

    ANS85 and any combination of the lower-case alphabetic characters "a" through "z"

    and the space.

    OSVS VSC2 MF The class condition cannot be used for external floating-point (USAGE DISPLAY) or internal floating-point (USAGE COMP-1 and USAGE COMP-2) items.

  4. ANS85 The ALPHABETIC-LOWER test cannot be used with an item whose data description describes the item as numeric. The result of the test is true if the content of the data item referenced by identifier-1 consists entirely of the lower-case alphabetic characters "a" through "z" and space.
  5. ANS85 The ALPHABETIC-UPPER test cannot be used with an item whose data description describes the item as numeric. The result of the test is true if the content of the data item referenced by identifier-1 consists entirely of the upper-case alphabetic characters "A" through "Z" and space.
  6. MF The class-name-1 test must not be used with an item whose data description describes the item as numeric.
Parent topic: Simple Conditions
Related information
Selection of Character Representation and Radix


Condition-name Condition (Conditional Variable)

In a condition-name condition, a conditional variable is tested to determine whether or not its value is equal to one of the values associated with a condition-name.

General Format

Syntax Rules

  1. OSVS VSC2 MF Condition-names with DBCS and internal floating-point items are allowed.
  2. MF Condition-names with external floating-point items are allowed.

General Rules

  1. If the condition-name is associated with a value or range of values, then the conditional variable is tested to determine whether or not its value falls in this range, including the end values.
  2. The rules for comparing a conditional variable with a condition-name value are the same as those specified for relation conditions.
  3. The result of the test is true if one of the values corresponding to the condition-name equals the value of its associated conditional variable.
Parent topic: Simple Conditions


Switch-Status Condition

A switch-status condition determines the "on" or "off" status of one of the

MF nine

COBOL switches

MF named respectively SWITCH-0 through SWITCH-8.

The value of each of these switches ("on" or "off" ) is set by the operator at the start of execution of the COBOL run unit. (See the discussion of RTS switches in your COBOL system documentation for details.) The switch and the "on" or "off" value associated with the condition must be named in the Special-Names paragraph of the Environment Division described earlier in this chapter; see the topic The Special-Names Paragraph.

General Format

Comments:

The result of the test is true if the switch is set to the specified position corresponding to the condition-name.

If the compiler directive SWITCH-TYPE is set to 1, which is the default, it is only possible to use the Switch-Status Condition to test if a COBOL switch is set from within the runtime element that set the switch.

If the compiler directive SWITCH-TYPE is set to 2, which is set by the compiler when the compiler directive DIALECT is set to ISO2000, it is possible to use the Switch-Status Condition to test if a COBOL switch is set from within any runtime element of the run unit.

Parent topic: Simple Conditions
Related information
The Special-Names Paragraph


Sign Condition

The sign condition determines whether or not the algebraic value of an arithmetic expression is less than, greater than, or equal to zero. The general format for a sign condition is as follows:

General Format:

General Rules:

  1. When used, "NOT" and the next keyword specify one sign condition that defines that algebraic test to be executed for truth value; for example, "NOT ZERO" is a truth test for a nonzero (positive or negative) value. An operand is positive if its value is greater than zero, negative if its value is less than zero, and zero if its value is equal to zero. The arithmetic expression must contain at least one reference to a variable.
  2. OSVS ZEROS or ZEROES can be used instead of ZERO in a sign test.
Parent topic: Simple Conditions


Omitted-argument Condition

The omitted-argument condition determines whether an argument was provided to a function, method, or program.

General Format

data-name-1 IS [ NOT ] OMITTED

Syntax Rules

  1. Data-name-1 must be a formal parameter defined in the source element in which this condition is specified.

General Rules

  1. The result of the OMITTED test is true if one of the following conditions applies:
    1. If the OMITTED phrase, rather than an identifier or literal, is specified as the argument corresponding to data-name-1 in the statement that activated this program, function, or method
    2. The argument corresponding to data-name-1 was a trailing argument that was omitted from the activating statement
    3. If the argument corresponding to data-name-1 is itself a formal parameter for which the omitted-argument condition is true.
  2. When used, NOT and the keyword OMITTED specify one condition to be executed for truth values.
Parent topic: Simple Conditions


Instance-of Condition

The instance-of condition determines whether an object reference is an instance of a particular class or interface.

General Format

Syntax Rules

  1. Object-identifier-1 must be an object reference.
  2. Class-name-1 must be the name of a class specified in the Repository paragraph or the Class-Control paragraph of this source element.
  3. Interface-name-1 must be the name of an interface specified in the Repository paragraph or the Class-Control paragraph of this source element.

General Rules

  1. If none of the optional phrases is specified, the result of the instance-of test is true if the object named by object-identifier-1 is an instance of the class named by class-name-1 or one of its subclasses, or the interface named by interface-name-1 or one of its subinterfaces.
  2. If the FACTORY phrase is specified and the ONLY phrase is not specified, the result of the instance-of test is true if the object named by object-identifier-1 is the factory of the class named by class-name-1.
  3. If the ONLY phrase is specified and the FACTORY phrase is not specified, the result of the instance-of test is true if the object named by object-identifier-1 is an instance of the class named by class-name-1, and not one of its subclasses.
  4. If both the FACTORY phrase and the ONLY phrase are specified, the result of the instance-of test is true if the object named by object-identifier-1 is the factory of the class named by class-name-1, and not one of its subclasses
Parent topic: Simple Conditions


Complex Condition

A complex condition is formed by combining simple conditions, combined conditions and/or complex conditions with logical connectors (logical operators "AND" and "OR" ) or negating these conditions with logical negation (the logical operator "NOT"). The truth value of a complex condition, whether parenthesized or not, is that truth value which results from the interaction of all the stated logical operators on the individual truth values of simple conditions, or the intermediate truth values of conditions logically connected or logically negated.

The logical operators and their meanings are:

Operator | Meaning
AND | Logical conjunction; the truth value is "true" if both of the conjoined conditions are true; "false" if one or both of the conjoined conditions is false.
OR | Logical inclusive OR; the truth value is "true" if one or both of the included conditions is true; "false" if both included conditions are false.
NOT | Logical negation or reversal of truth value; the truth value is "true" if the condition is false; "false" if the condition is true.

The logical operators must be preceded by a space and followed by a space.

  • Negated Simple Condition
    A simple condition is negated through the use of the logical operator "NOT". The negated simple condition effects the opposite truth value for a simple condition. Thus the truth value of a negated simple condition is "true" if and only if the truth value of the simple condition is "false" ; the truth value of a negated simple condition is "false" if and only if the truth value of the simple condition is "true". The inclusion in parentheses of a negated simple condition does not change the truth value.
  • Combined and Negated Combined Condition
    A combined condition results from connecting conditions with one of the logical operators "AND" or "OR".
Parent topic: Conditional Expressions
Related information
Simple Conditions


Negated Simple Condition

A simple condition is negated through the use of the logical operator "NOT". The negated simple condition effects the opposite truth value for a simple condition. Thus the truth value of a negated simple condition is "true" if and only if the truth value of the simple condition is "false" ; the truth value of a negated simple condition is "false" if and only if the truth value of the simple condition is "true". The inclusion in parentheses of a negated simple condition does not change the truth value.

General Format

Parent topic: Complex Condition


Combined and Negated Combined Condition

A combined condition results from connecting conditions with one of the logical operators "AND" or "OR".

General Format

Syntax Rules

  1. Condition may be:
    • A simple condition
    • A negated simple condition
    • A combined condition
    • A negated combined condition; that is, the "NOT" logical operator followed by a combined condition enclosed within parentheses
    • Combinations of the above, specified according to the rules summarized in the table in the Comments section below.
  2. Although parentheses need never be used when either "AND" or "OR" (but not both) is used exclusively in a combined condition, parentheses can be used to effect a final truth value when a mixture of "AND", "OR" and "NOT" is used.

General Rules

  1. In the absence of the relevant parentheses in a complex condition, the precedence (that is, binding power) of the logical operators determines the conditions to which the specified logical operators apply and implies the equivalent parentheses. The order of precedence is "NOT", "AND" , "OR". Thus, specifying "condition-1 OR NOT condition-2 AND condition-3" implies and is equivalent to specifying "condition-1 OR ((NOT condition-2) AND condition-3)".
  2. Where parentheses are used in a complex condition, precedence is used to determine the binding of conditions to logical operator. Parentheses can, therefore, be used to depart from the normal precedence of logical operators as specified above. Thus, the example complex condition above can be given a different meaning by specifying it as a "(condition-1 OR (NOT condition-2)) AND condition-3". (See the topic Condition Evaluation Rules.)

Comments:

The table below indicates the ways in which conditions and logical operators can be combined and parenthesized. There must be a one-to-one correspondence between left and right parentheses such that each left parenthesis is to the left of its corresponding right parenthesis.

Table 1. Combinations of Conditions, Logical Operators, and Parentheses
Element | Permitted location in conditional expression | Element can be preceded by only: | Element can be followed by only:
simple-condition | Any | OR, NOT, AND, ( | OR, AND, )
OR or AND | Not first or last | simple-condition, ) | simple-condition, NOT, (
NOT | Not last | OR, AND, ( | simple-condition, (
( | Not last | OR, NOT, AND, ( | simple-condition, NOT, (
) | Not first | simple-condition, ) | OR, AND, )

Thus, the element pair "OR NOT" is permissible while the pair "NOT OR" is not permissible; "NOT ( " is permissible while "NOT NOT" is not permissible.

Parent topic: Complex Condition
Related information
Condition Evaluation Rules


Abbreviated Combined Relation Conditions

When simple or negated simple relation conditions are combined with logical connectives in a consecutive sequence such that a succeeding relation condition contains a subject or subject and relational operator that is common with the preceding relation condition, and no parentheses are used within such a consecutive sequence, any relation condition except the first can be abbreviated by either of the following means:

  • The omission of the subject of the relation condition
  • The omission of the subject and relational operator of the relation condition.

General Format

Comments:

Within a sequence of relation conditions both of the above forms of abbreviation can be used. The effect of using such abbreviations is as if the last preceding stated subject were inserted in place of the omitted subject, and the last stated relational operator were inserted in place of the omitted relational operator. The result of such implied insertion must comply with the rules of the table Relational Operators. This insertion of an omitted subject and/or relational operator terminates once a complete simple condition is encountered within a complex condition.

OSVS The order of evaluation of the conditions can be prioritized by the use of parentheses (see example below).

The interpretation applied to the use of the word "NOT" in an abbreviated combined relation condition is as follows:

  1. ANS85 If NOT is immediately followed by the word GREATER, >, LESS, <, EQUAL, or =, excluding the relational operators GREATER THAN OR EQUAL TO, >=, LESS THAN OR EQUAL TO, and <=, then the word NOT is interpreted as part of the relational operator, otherwise:
  2. The "NOT" is interpreted as a logical operator and, therefore, the implied insertion of subject or relational operator results in a negated relation condition.

Some examples of abbreviated combined and negated combined relation conditions and expanded equivalents follow.

Abbreviated Combined Relation Condition | Expanded Equivalent
a > b AND NOT < c OR d | ((a > b) AND (a NOT < c)) OR (a NOT < d)
a NOT EQUAL b OR c | (a NOT EQUAL b) OR (a NOT EQUAL c)
NOT a = b OR c | (NOT (a = b)) OR (a = c)
NOT (a GREATER b OR < c) | NOT ((a GREATER b) OR (a < c))
NOT (a NOT > b AND c AND NOT d | NOT ((((a NOT > b) AND (a NOT > c)) AND (NOT (a NOT > d))))
x > a OR y AND z | x > a OR (x > y AND x > z)
x > a OR (y AND z) | x > a OR (x > y AND x > z)
x > (a OR y) AND z | (x > a OR x > y) AND x > z
x ( = a OR > b) | x = a OR x > b
x = a AND ( > b OR < z ) | x = a AND ( x > b OR x < z )
a EQUAL b OR NOT GREATER OR EQUAL c OR d | (a EQUAL b) OR (NOT (a GREATER OR EQUAL c)) OR (a GREATER OR EQUAL d)
a EQUAL b OR NOT >=c OR d | (a EQUAL b) OR (NOT (a >= c)) OR (a >= d)
  • Condition Evaluation Rules
Parent topic: Conditional Expressions
Related information
Relational Operators


Condition Evaluation Rules

Parentheses can be used to specify the order in which individual conditions of complex conditions are to be evaluated when it is necessary to depart from the implied evaluation precedence.

Conditions within parentheses are evaluated first, and, within nested parentheses, evaluation proceeds from the least inclusive condition to the most inclusive condition. When parentheses are not used, or parenthesized conditions are at the same level of inclusiveness, the following hierarchical order of logical evaluation is implied until the final truth value is determined:

  1. ANS85 Values are established for arithmetic expressions and functions if and when the conditions containing them are evaluated. Similarly, negated conditions are evaluated if and when it is necessary to evaluate the complex condition that they represent. (See the section Formation and Evaluation Rules.)
  2. Truth values for simple conditions are established in the following order:

    relation (following the expansion of any abbreviated relation condition) class condition-name switch-status sign

  3. Truth values for negated conditions are established.
  4. Truth values for combined conditions are established: "AND" logical operators, followed by "OR" logical operators.
  5. Truth values for negated combined conditions are established.
  6. When the sequence of evaluation is not completely specified by parentheses, the order of evaluation of consecutive operations of the same hierarchical level is from left to right.
Parent topic: Abbreviated Combined Relation Conditions
Related information
Formation and Evaluation Rules


Common Phrases

In the statement descriptions several phrases appear frequently.

In these phrases, the term "resultant-identifier" refers to that identifier associated with the result of an arithmetic operation.

  • Arithmetic Statements
  • Overlapping Operands
  • Multiple Results in Arithmetic Statements
  • Incompatible Data
  • Signed Receiving Items
  • The ROUNDED Phrase
  • The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase
  • The CORRESPONDING Phrase
Parent topic: Procedure Division


Arithmetic Statements

The arithmetic statements are the ADD, COMPUTE, DIVIDE, MULTIPLY and SUBTRACT statements. Common features are as follows:

  1. The data descriptions of the operands need not be the same; any necessary conversion and decimal point alignment are supplied throughout the calculation.

  2. The composite of operands is a hypothetical data item resulting from the superimposition of specified operands in a statement aligned on their decimal points.

    ANS85 The composite of operands for ADD, DIVIDE, MULTIPLY and SUBTRACT statements must not contain more than 18 decimal digits.

    MF There is no limit on the composite of operands.

Parent topic: Common Phrases


Overlapping Operands

When a sending and a receiving item in a statement share a part of their storage areas,

ANS85 yet are not defined by the same data description entry,

the result of the execution of such a statement is undefined.

MF Overlapping moves are detected at compile time only when the MOVE verb is used and neither operand uses reference modification or subscripting. Forward overlapping moves result in a warning message, if you set the Compiler directive WARNING"3". Any other types result in flagging messages, if you set the Compiler directive FLAG"dialect", where "dialect" is anything but OSVS. Other operations resulting in sending and receiving items sharing the same memory are not detected.

MF Although portability of COBOL source code is only guaranteed when there are no overlapping MOVE statements, this COBOL system does allow such statements. The behavior of such statements is sensitive to the BYTE-MODE-MOVE Compiler directive.

Parent topic: Common Phrases


Multiple Results in Arithmetic Statements

The ADD, COMPUTE, DIVIDE, MULTIPLY and SUBTRACT statements can have multiple results. Such statements behave as though they had been written in the following way:

  1. A statement which accesses all data items that are part of the initial evaluation of the statement, performs all arithmetic necessary to arrive at the result to be stored in the receiving items, and stores that result in a temporary storage location.
  2. A sequence of statements transferring or combining the value of this temporary location with each single resultant data item. These statements are considered to be written in the same left-to-right sequence in which the multiple results are listed.

    The result of the statement:

    ADD a, b, c TO c, d (c), e

    is equivalent to:

    ADD a, b,
c GIVING temp ADD temp TO c ADD temp TO d (c) ADD temp TO e

    and the result of the statement:

    MULTIPLY a(i) BY i, a(i)

    is equivalent to:

    MOVE a(i) to temp MULTIPLY temp by i MULTIPLY temp BY
a(i)

    where temp is an intermediate result item provided by your COBOL system.

Parent topic: Common Phrases


Incompatible Data

Except for the class condition (see the topic Class Condition), when the contents of a data item are referenced in the Procedure Division and the contents of that data item are not compatible with the class specified for that data item by its PICTURE clause

ANS85 or function definition

then the result of such a reference is undefined.

MF The results of referencing a numeric field that contains nonnumeric, or otherwise invalid data, are undefined. Such conditions may be detected, and give an error at run-time. This behavior is affected by the F RTS switch.

MF When an alphabetic field which contains non-alphabetic data is referenced, execution continues, but results may be undefined.

Parent topic: Common Phrases
Related information
Class Condition


Signed Receiving Items

When the receiving item in an arithmetic statement or a MOVE statement is a signed numeric or a signed numeric-edited item, the sign is moved into the receiving item independently of any truncation of the absolute numeric data. It is possible, therefore, for the numeric value to be zero but for the sign to be negative.

Parent topic: Common Phrases


The ROUNDED Phrase

If, after decimal point alignment, the number of places in the fraction of the result of an arithmetic operation is greater than the number of places provided for the fraction of the resultant-identifier, truncation is relative to the size provided for the resultant-identifier. When rounding is requested, the absolute value of the resultant-identifier is increased by one whenever the most significant digit of the excess is greater than or equal to five.

When the low-order integer positions in a resultant-identifier are represented by the character "P" in the PICTURE for the resultant-identifier, rounding or truncation occurs relative to the rightmost integer position for which storage is allocated.

OSVS VSC2 MF In a floating-point arithmetic operation, the ROUNDED phrase is treated as documentary; the result of a floating-point operation is always rounded.

Parent topic: Common Phrases


The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase

If, after decimal point alignment, the absolute value of a result of an arithmetic operation exceeds the largest value that can be contained in the associated resultant-identifier, a size error condition exists. Division by zero always causes a size error condition. Note that the results of division by zero when no ON SIZE ERROR phrase is specified are unpredictable. The size error condition applies only to the final results, except in MULTIPLY and DIVIDE statements, in which case the size error condition applies to the intermediate results as well.

ANS85 Violation of the rules for the evaluation of exponentiation always terminates the arithmetic operation and always causes a size error condition.

If the ROUNDED phrase is specified, rounding takes place before checking for size error. When such a size error condition occurs, the subsequent action depends on whether or not the SIZE ERROR phrase is specified, as follows:

  • ON SIZE ERROR Phrase Not Specified
  • ON SIZE ERROR Phrase Specified
  • The NOT ON SIZE ERROR Phrase
Parent topic: Common Phrases
Related reference
ON SIZE ERROR Phrase


ON SIZE ERROR Phrase Not Specified

When a size error condition occurs, the value of those resultant- identifier(s) affected is undefined. Any subsequent use of the resultant-identifier(s) affected is also unpredictable in effect. Values of resultant-identifier(s) for which no size error condition occurs are unaffected by size errors that occur for other resultant-identifier(s) during execution of this operation.

ANS85 After completion of the arithmetic operation, control is transferred to the end of the arithmetic statement and the NOT ON SIZE phrase, if specified, is ignored.

Results of division by zero, when no ON SIZE ERROR is specified, are unpredictable. You can avoid this by using the CHECKDIV Compiler directive and O RTS switch.

Parent topic: The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase


ON SIZE ERROR Phrase Specified

When a size error condition occurs, then the values of resultant- identifier(s) affected by the size errors are not altered. Values of resultant-identifier(s) for which no size error condition occurs are unaffected by size errors that occur for other resultant-identifier(s) during execution of this operation. After completion of the execution of this operation, the imperative statement in the SIZE ERROR phrase is executed.

For the ADD statement with the CORRESPONDING phrase and the SUBTRACT statement with the CORRESPONDING phrase, if any of the individual operations produces a size error condition, the imperative statement in the ON SIZE ERROR phrase is not executed until all of the individual additions or subtractions are completed.

ANS85 If a size error condition occurs, any NOT ON SIZE ERROR phrase is ignored whether or not an ON SIZE ERROR phrase is specified.

ANS85 When both ON SIZE ERROR and NOT ON SIZE ERROR phrases are specified, and the statement in the phrase that is executed does not contain any explicit transfer of control, then, if necessary, an implicit transfer of control is made after execution of the phrase to the end of the arithmetic statement.

Parent topic: The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase


The NOT ON SIZE ERROR Phrase

If the NOT ON SIZE ERROR phrase is specified for an arithmetic operation statement, and after execution of that statement a size error condition (as defined above) does not exist, then the NOT ON SIZE ERROR phrase is executed. The ON SIZE ERROR phrase, if specified, is ignored, and the imperative statement associated with it is not executed.

Parent topic: The ON SIZE ERROR Phrase and NOT ON SIZE ERROR Phrase


The CORRESPONDING Phrase

In the text that follows, d1 and d2 must each be identifiers that refer to group items. A pair of data items, one from d1 and one from d2 correspond if the following conditions exist:

  1. A data item in d1 and a data item in d2 are not designated by the key word FILLER and have the same data-name and the same qualifiers up to, but not including, d1 and d2.
  2. At least one of the data items is an elementary data item and the resulting move is legal according to the move rules in the case of a MOVE statement with the CORRESPONDING phrase, and both of the data items are elementary numeric data items in the case of the ADD statement with the CORRESPONDING phrase or the SUBTRACT statement with the CORRESPONDING phrase.
  3. The description of d1 and d2 must not contain level-number 66, 77,

    MF 78

    or 88, the USAGE IS INDEX clause

    MF or the USAGE IS OBJECT clause

  4. A data item that is subordinate to d1 or d2 and contains a REDEFINES, RENAMES, OCCURS, USAGE IS INDEX

    MF , USAGE IS PROCEDURE-POINTER

    VSC2 MF , USAGE IS POINTER

    MF , or USAGE IS OBJECT

    clause is ignored, as well as those data items subordinate to the data item that contains the REDEFINES, RENAMES, OCCURS, USAGE IS INDEX

    MF , USAGE IS PROCEDURE-POINTER

    VSC2 MF , USAGE IS POINTER

    MF , or USAGE IS OBJECT

    clause. However, d1 and d2 can have REDEFINES or OCCURS clauses or be subordinate to data items with REDEFINES or OCCURS clauses.

    ANS85 Neither d1 or d2 can be reference modified.

  5. The name of each data item which satisfies the above conditions must be unique after application of the implied qualifiers.
Parent topic: Common Phrases


File I/O Concepts

  • File Position Indicator
  • I-O Status
  • The AT END Condition
  • The INVALID KEY Condition
  • Sharing Files on Multi-user Systems
Parent topic: Procedure Division


File Position Indicator

The file position indicator identifies the next record to be accessed within a given file during certain input-output sequences. The setting of the file position indicator is affected only by CLOSE, OPEN, START and READ statements. The file position indicator has no effect on files opened in the output or extend mode.

Parent topic: File I/O Concepts


I-O Status

If the FILE STATUS clause is specified in a file control entry, a value is placed into the specified two-character data item during the execution of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, UNLOCK or START statement before any applicable USE procedure is executed, to indicate the status of that input-output operation.

The file status keys described in the following pages are for those files which conform fully to the ANSI standard and which use none of the extensions available with this COBOL system.

MF Use of extensions, for example, specifying a file as LINE SEQUENTIAL, affects the status keys returned. Additional information is provided under the relevant verbs.

  • Status Key 1
  • Successful Completion
  • Valid Combinations of Status Keys 1 And 2
Parent topic: File I/O Concepts


Status Key 1

The leftmost character position of the FILE STATUS data item is known as status key 1 and is set to indicate one of the following conditions upon completion of the input-output operation on a file of any organization.

"0" | - Successful completion
"1" | - At end
"2" | - Invalid key
"3" | - Permanent error
"4" | - Logic error
"9" | - Run-time system error message

The meaning of the above conditions is as follows:

"0" | Successful completion. The input-output statement was successfully executed.
"1" | At end. The sequential READ statement was unsuccessfully executed either because of an attempt to read a record when no next logical record exists in the file or because the first READ statement was executed for a file described with the OPTIONAL clause when that file was not available at the time its associated OPEN statement was executed.
"2" | Invalid key. The input-output statement on a non-sequential file was unsuccessfully executed because of one of the following: Sequence error Duplicate key No record found Boundary violation
"3" | Permanent error. The input-output statement was unsuccessfully executed because of a boundary violation for a sequential file or because of an input-output error, such as a data check parity error or transmission error.
"4" | Logic error. The input-output statement was unsuccessfully executed, either because an improper sequence of input-output operations was performed on the file, or because a limit you defined was violated.
"9" | Run-time system error message. The input-output statement was unsuccessfully executed because of a condition that is specified by the run-time system error message number. This value is used only to indicate a condition not indicated by other defined values of status key 1, or by specified combinations of the values of status key 1 and status key 2.
Parent topic: I-O Status


Successful Completion

If status key 1 contains "0" to indicate the successful completion of the input-output operation, status key 2 can contain one of the following values:

"0" | (all files) No further information is available
"2" (indexed files only) Indicates one of two possibilities:
  • For a READ statement, the key value for the current key of reference is equal to the value of the same key in the next record within 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.
"4" | (all files) Indicates that the length of the record being processed does not conform to the fixed file attributes for that file.
"5" | (all files) Indicates that the referenced optional file was not present at the time the OPEN statement was executed.
"7" | (record sequential files only) Indicates that for a CLOSE statement with the NO REWIND, REEL/UNIT or FOR REWIND phrase, or an OPEN statement with the NO REWIND phrase, the referenced file is a non-reel/unit medium.
  • Successful Completion
  • AT END Condition with Unsuccessful Completion
  • INVALID KEY Condition with Unsuccessful Completion
  • Permanent Error Condition with Unsuccessful Completion
  • Logic Error Condition with Unsuccessful Completion
  • Run-Time System Error Message
Parent topic: I-O Status


Successful Completion

If status key 1 contains "0" to indicate the successful completion of the input-output operation, status key 2 can contain one of the following values:

"0" | (all files) No further information is available
"2" (indexed files only) Indicates one of two possibilities:
  • For a READ statement, the key value for the current key of reference is equal to the value of the same key in the next record within 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.
"4" | (all files) Indicates that the length of the record being processed does not conform to the fixed file attributes for that file.
"5" | (all files) Indicates that the referenced optional file was not present at the time the OPEN statement was executed.
"7" | (record sequential files only) Indicates that for a CLOSE statement with the NO REWIND, REEL/UNIT or FOR REWIND phrase, or an OPEN statement with the NO REWIND phrase, the referenced file is a non-reel/unit medium.
Parent topic: Successful Completion


AT END Condition with Unsuccessful Completion

If status key 1 contains "1" to indicate the AT END condition, status key 2 can contain one of the following values:

"0" (all files) Indicates that there is no next logical record. This can be caused by two conditions:
  • The end of the file has been reached.
  • A sequential READ statement has been attempted for the first time on an optional input file that is not present.
"4" (relative files only) Indicates that 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.
Parent topic: Successful Completion


INVALID KEY Condition with Unsuccessful Completion

If status key 1 contains "2" to indicate INVALID KEY condition, status key 2 indicates the cause of the condition by one of the values:

"1" | (sequentially accessed indexed files) Indicates a sequence error. The ascending sequence requirements of successive record key values have been violated (see the topic The WRITE Statement), or the prime record key value has been changed by the COBOL runtime element between the successful execution of a READ statement and the execution of the next REWRITE statement for that file.
"2" | (relative and indexed files only) Indicates a duplicate key value. An attempt has been made either to write a record that would create a duplicate prime record key or to write or rewrite a record that would create a duplicate alternate record key when the DUPLICATES phrase is not specified for that alternate record key.
"3" | (relative and indexed files only) 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, or a START or READ statement has been attempted on an optional input file that is not present.
"4" (relative and indexed files only) Indicates a boundary violation arising from one of the following conditions:
  • An attempt has been made to write beyond the externally defined boundaries of a file.
  • A sequential WRITE statement has been attempted for 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.
Parent topic: Successful Completion
Related information
The WRITE Statement


Permanent Error Condition with Unsuccessful Completion

If status key 1 contains "3" to indicate a permanent error condition, status key 2 can contain one of the following values to indicate the cause of that error:

"0" | (all files) Indicates that no further information is available concerning the cause of the error.
"4" | (sequential files only) Indicates a boundary violation. An attempt has been made to write beyond the externally defined boundaries of a file.
"5" | (all files) Indicates that an OPEN statement with the INPUT, I-O, or EXTEND phrase has been attempted on a non-optional file that is not present.
"7" (all files) Indicates that an OPEN statement has been attempted on a file which does not support the open mode specified in the OPEN statement. The possible violations are:
  • The EXTEND or OUTPUT phrase has been specified but the file does not support write operations.
  • The I-O phrase has been specified but the file doesl not support the input and output operations that are permitted for a relative file when opened in the I-O mode.
  • The INPUT phrase has been specified but the file does not support read operations.
"8" | (all files) Indicates that an OPEN statement has been attempted on a file previously closed with lock.
"9" | (record sequential, relative and indexed files) Indicates that a conflict has been detected between the fixed file attributes and the attributes specified for that file in the source element.
Parent topic: Successful Completion


Logic Error Condition with Unsuccessful Completion

If status key 1 contains "4" to indicate a logic error condition, status key 2 can contain one of the following values to indicate the cause of that error:

"1" | (all files) Indicates that an OPEN statement has been attempted for a file already in open mode.
"2" | (all files) Indicates that a CLOSE statement has been attempted for a file not in open mode.
"3" | (all files, sequential access mode only) Indicates that the last input-output statement executed for the associated file, prior to the execution of a DELETE or REWRITE statement, was not a successfully executed READ statement.
"4" | (record sequential files only) Indicates that a boundary violation exists. A possible violation is that 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.
"5" (all files ) 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.

MF For line sequential files this refers to the physical size of the record, that is after space removal, tab compression and null insertion. In this case, the physical size of the new record is allowed to be smaller than that of the record being replaced.
"6" (all files) Indicates that a sequential READ statement has been attempted on a file open in input or I-O mode, but no valid next record has been established. This can be caused by the following conditions:
  • The preceding START statement was unsuccessful.
  • The preceding READ statement was unsuccessful but did not cause an at end condition.
  • The preceding READ statement caused an at end condition.
"7" | (all files) Indicates that the execution of a READ or START statement has been attempted on a file not open in input or I-O mode.
"8" | (all files) Indicates that the execution of a WRITE statement has been attempted on a file not open in I-O, output or extend mode, or on a file open I-O in sequential access mode.
"9" | (all files) Indicates that the execution of a DELETE or REWRITE statement has been attempted on a file not open in I-O mode.
Parent topic: Successful Completion


Run-Time System Error Message

If status key 1 contains " 9" to indicate a run-time system error message, status key 2 contains the run-time system error message number in binary. These are described in full in your COBOL system documentation.

Parent topic: Successful Completion


Valid Combinations of Status Keys 1 And 2

In the following table: "S" indicates a Record Sequential file,

MF "L " indicates a Line Sequential file,

"R" indicates a Relative file and "I" indicates an Indexed file.

A particular combination of status key 1 and status key 2 is valid for a given file organization if the letter for that organization is found at the corresponding intersection in the table below.

Table 1. Valid Combinations of Status Keys 1 and 2
Status Key 1 |  | Status Key 2
 |  | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
Successful Completion | 0 | SRIL |  | I |  | SRIL | SRIL |  | S |  |
At End | 1 | SRIL |  |  |  | R |  |  |  |  |
Invalid Key | 2 |  | I | RI | RI | RI |  |  |  |  |
Permanent Error | 3 | SRIL |  |  |  | SL | SRIL |  | SRIL | SRIL | SRIL
Logic Error | 4 |  | SRIL | SRIL | SRIL | SRIL |  | SRIL | SRIL | SRIL | SRIL
Implementor Defined | 9 | Run-Time System Error Message (SRIL)
Parent topic: I-O Status


The AT END Condition

The AT END condition can occur as a result of the execution of a READ statement. For details of the causes of the condition, see the topic The READ Statement.

Parent topic: File I/O Concepts
Related information
The READ Statement


The INVALID KEY Condition

The INVALID KEY condition can occur as a result of the execution of a START, READ, WRITE, REWRITE or DELETE statement. For details of the causes of the condition, see the topics The READ Statement and The REWRITE Statement and the sections The START Statement and The WRITE Statement.

If the INVALID KEY condition exists after the execution of the input-output operation specified in an input-output statement, the following actions occur in the order shown:

  1. A value is placed in the FILE STATUS data item, if specified for this file, to indicate an INVALID KEY condition. (See the section earlier in this chapter.)
  2. If the INVALID KEY phrase is specified in the statement causing the condition, control is passed to the INVALID KEY imperative statement. Any USE procedure specified for this file is not executed.
  3. If the INVALID KEY phrase is not specified, but a USE procedure is specified, either explicitly or implicitly, for this file, that procedure is executed.

When the INVALID KEY condition occurs, execution of the input-output statement which recognized the condition is unsuccessful, and the file is not affected.

Note that INVALID KEY does not trap errors when status key 1 is set to "9". Such errors must be trapped either by explicitly testing the status key or by using declaratives instead of the INVALID KEY clause.

Parent topic: File I/O Concepts
Related information
The READ Statement
The REWRITE Statement
The START Statement
The WRITE Statement


Sharing Files on Multi-user Systems

The run-time system supports this COBOL system's multi-user facilities which allow files to be shared between users in a multi-user environment, and allow runtime elements accessing those files to lock records or entire files in order to prevent access to them while data is being updated.

In single-user environments the multi-user syntax has no effect at run time, but runtime elements can be developed for use in both single- and multi-user environments.

Files are either active or inactive. An active file is open to one or more run units. An inactive file is one that is not open to any run unit.

Active files can be open in one of two modes: exclusive or shareable:

  • MF XOPEN Exclusive

    A file which is in exclusive mode is open to one run unit only; any other run unit which attempts to access it receives a "File locked" error and is denied access. Exclusive mode implies that a file lock is held by the one run unit which is able to access the file; the file lock is released by that run unit closing the file.

  • Shareable

    A file which is in shareable mode is available to any number of run units, each of which can protect data while using the file by locking one or more records at a time in the file. This prevents other run units from acquiring a lock on the individual records that are locked, but does not prevent access to the file otherwise. The organization of the file affects the way the file can be shared.

The organization of the file affects the way the file can be shared:

  • Record sequential

    Record sequential files opened for INPUT can be shared between run units but records cannot be locked in the file. Files opened for I-O or EXTEND can also be made shareable and each run unit can maintain a record lock for the file. Files opened for OUTPUT always have an exclusive file lock.

  • MF Line sequential

    Line sequential files that are opened INPUT or EXTEND can be made shareable but records cannot be locked in the file. Files that are opened OUTPUT always have an exclusive file lock.

  • Relative and indexed

    Files that are opened in INPUT mode are shareable, but records cannot be locked in the file. Files that are opened I-O can be shareable but files that are opened OUTPUT or EXTEND are exclusive.

Each run unit that is sharing access to a file can be locking either a single record or multiple records in that file. A run unit cannot select single record locking and multiple record locking for the same file.

  • Single Record Locking
  • Multiple Record Locking
  • Default Record Locking
Parent topic: File I/O Concepts


Single Record Locking

A run unit that has specified single record locking for a file (either explicitly or implicitly) can hold only one record lock in that file at any one time. A run unit can acquire a record lock in two ways: manually or automatically:

  • Manual record lock

    The run unit acquires a lock only if it accesses a record with a READ WITH LOCK statement.

  • Automatic record lock

    The run unit acquires a lock whenever it reads a record in the file, unless you specify the READ WITH NO LOCK statement.

The lock is released by the same run unit doing any of the following:

  • Accessing any record in the file with any file operation (except START for relative and indexed files)
  • Executing an UNLOCK statement on that file
  • Executing a COMMIT statement
  • Executing a ROLLBACK statement
  • Closing the file.
Parent topic: Sharing Files on Multi-user Systems


Multiple Record Locking

Locking of multiple records in a file is available only when the organization of that file is relative, indexed or record sequential.

A run unit that has specified multiple record locking for a file can hold a number of record locks in one file simultaneously. This prevents other run units from updating or acquiring a lock on those locked records, but does not deny them access to any records that are not locked. Record locks can be acquired in two ways: manually or automatically:

  • Manual record lock

    The run unit acquires a lock only if it accesses a record with a READ WITH LOCK or READ WITH KEPT LOCK statement.

  • Automatic record lock

    The run unit acquires a lock whenever it reads a record in the file unless you explicitly specify that it should not. If the WRITELOCK Compiler directive has been specified at the time the compilation group was submitted to your COBOL system, then a lock is acquired if the run unit accesses the file with a WRITE or REWRITE statement.

The locks are released by the same run unit doing any of the following:

  • Executing a DELETE statement referencing a record for which a lock is held. In this case, only the lock on that record is released
  • Executing an UNLOCK statement for that file
  • Executing a COMMIT statement
  • Executing a ROLLBACK statement
  • Closing the file.
Parent topic: Sharing Files on Multi-user Systems


Default Record Locking

Tables 2, 3 and 4 show the default type of locking which is used when files are opened in a particular open mode. The default locking can be modified if the AUTOLOCK Compiler directive was specified at the time the compilation group was submitted to your COBOL system. The tables also indicate whether the default type of locking can be overridden for individual files. This is done by inserting a suitable clause in the SELECT clause for the file. (See the topic The File Control Entry.)

XOPEN X/Open restricts those X/Open conforming source programs that use locking to either single record locks with automatic locking, or multiple record locks with manual locking.

Table 1. Default Locking For Record Sequential Files
OPEN Mode | No Directive | AUTOLOCK Compiler Directive | Override in SELECT Statement
INPUT | No lock | No lock | Yes, but only to Exclusive
I-O | Exclusive | Lock on single record | Yes
OUTPUT | Exclusive | Exclusive | No
EXTEND | Exclusive | No lock | Yes, the file can be made shareable but no records are locked
Table 2. Default Locking For Line Sequential Files
OPEN Mode | No Directive | AUTOLOCK Compiler Directive | Override in SELECT Statement
INPUT | No lock | No lock | No
I-O | Exclusive | No lock | No
OUTPUT | Exclusive | Exclusive | No
EXTEND | Exclusive | No lock | No
Table 3. Default Locking For Relative And Indexed Files
OPEN Mode | No Directive | AUTOLOCK Compiler Directive | Override in SELECT Statement
INPUT | No lock | No lock | Yes, but only to Exclusive
I-O | Exclusive | Automatic lock on single record | Yes
OUTPUT | Exclusive | Exclusive | No
EXTEND | Exclusive | Exclusive | No
Note:
  1. A file opened for OUTPUT causes the file to become exclusive, regardless of the specified lock mode.
  2. You can select the type of locking for individual files by accepting the default locking (see Tables 1, 2 and 3) or by including a LOCK MODE clause in the file control entry (see the section The File Control Entry).
Parent topic: Sharing Files on Multi-user Systems
Related information
The File Control Entry


Conformance for Parameters and Returning Items

The conformance rules for parameters and returning items apply at compile time when an explicit reference is made to them from a syntax rule.

Note: Conformance rules for parameters and returning items are checked at compile time for:
  • An INVOKE statement on an object reference that is not a universal object reference,
  • A reference to a user-defined function,
  • A program-prototype format of the CALL statement.
  • Parameters
  • Returning Items
Parent topic: Procedure Division


Parameters

The number of arguments in the activating element must be equal to the number of formal parameters in the activated element,

ISO2002 MF with the exception of trailing formal parameters that are specified with an OPTIONAL phrase in the PROCEDURE DIVISION header of the activated element and are omitted from the list of arguments of the activating element.

MF If the numbers of operands are different, then if there are more operands in the activating statement, they are ignored and if there are more operands in the PROCEDURE DIVISION header, they must not be referenced within the activated runtime element. The positional correspondence may vary depending on the non-COBOL calling conventions implied by mnemonic-name. Any mismatch in the number of the operands will only be apparent at run time and so the directive FLAG does not cause this extension to be flagged.

The rules for conformance between arguments and formal parameters depend on whether either the formal parameter or its corresponding argument is a group item or both are elementary items.

  • Group Items
  • Elementary Items
Parent topic: Conformance for Parameters and Returning Items


Group Items

If either the formal parameter or the argument is a group item, the corresponding argument or formal parameter must be a group item or an elementary item of category alphanumeric, and the formal parameter must be described with the same number or a smaller number of character positions as the corresponding argument.

Parent topic: Parameters


Elementary Items

The conformance rules for elementary items depend on whether the argument is passed by reference, by content, or by value.

  • Elementary Items Passed by Reference
  • Elementary Items Passed by Content or by Value
Parent topic: Parameters


Elementary Items Passed by Reference

If either the formal parameter or the corresponding argument is an object reference, the corresponding argument or formal parameter must be an object reference following these rules:

  1. If either the argument or the formal parameter is a universal object reference, the corresponding formal parameter or argument must be a universal object reference.
  2. If either the argument or the formal parameter is described with an interface-name, the corresponding formal parameter or argument must be described with the same interface-name.
  3. If either the argument or the formal parameter is described with a class-name, the corresponding formal parameter or argument must be described with the same class-name, and the FACTORY and ONLY phrases must be the same.
  4. If the formal parameter is described with the ACTIVE-CLASS phrase, one of the following conditions must be true:
    1. The argument must be an object reference described with the ACTIVE-CLASS phrase, where the presence or absence of the FACTORY phrase is the same as in the formal parameter, and the method to be activated must be invoked with the predefined object references SELF or SUPER, or with an object reference described with the ACTIVE-CLASS phrase.
    2. The argument must be an object reference described with a class-name and the ONLY phrase, where the presence or absence of the FACTORY phrase is the same as in the formal parameter, and the method to be activated must be invoked with that class-name or with an object reference described with that classname and the ONLY phrase.

If either the argument or the formal parameter is of class pointer, the corresponding formal parameter or argument must be of class pointer and the corresponding items must be of the same category. If either is a restricted pointer, both must be restricted and of the same type. The ADDRESS special register is considered to be of class pointer and category data-pointer.

If neither the formal parameter nor the argument is of class object or pointer, the conformance rules are the following:

  1. If the activated element is a program for which there is no program-specifier in the Repository paragraph of the activating element and there is no NESTED phrase specified on the CALL statement, the formal parameter must be of the same length as the corresponding argument.
  2. If the activated element is one of the following:
    • A program for which there is a program-specifier in the Repository paragraph of the activating element
    • A program that was called with a CALL statement in which the NESTED phrase is specified
    • A method
    • A function

    then the definition of the formal parameter and the definition of the argument must have the same PICTURE, USAGE, SIGN, JUSTIFIED, and BLANK clauses, with the following exceptions:

    1. Currency symbols match if and only if the corresponding currency strings are the same.
    2. Period picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both the activating and the activated runtime elements or for neither of them. Comma picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both the activating and the activated runtime elements or for neither of them.

    Additionally:

    1. If the formal parameter is described with the ANY LENGTH clause, its length is considered to match the length of the corresponding argument.
    2. If the argument is described with the ANY LENGTH clause, the corresponding formal parameter shall be described with the ANY LENGTH clause.
Parent topic: Elementary Items


Elementary Items Passed by Content or by Value

If the formal parameter is an object reference described with the ACTIVE-CLASS phrase, one of the following conditions must be true:

  1. The method to be activated must be invoked with the predefined object references SELF or SUPER, or with an object reference described with the ACTIVE-CLASS phrase, and a SET statement must be valid in the activating unit with the argument as the sending operand and an object reference described with the ACTIVE-CLASS phrase as the receiving operand, where the presence or absence of the FACTORY phrase is the same as in the formal parameter.
  2. The method to be activated must be invoked with a class-name or with an object reference described with a class-name and the ONLY phrase, and a SET statement must be valid in the activating unit with the argument as the sending operand and an object reference described with that class-name and the ONLY phrase as the receiving operand, where the presence or absence of the FACTORY phrase is the same as in the formal parameter.

If the formal parameter is of class pointer or an object reference descrited without the ACTIVE-CLASS phrase, the conformance rules are the same as if a SET statement were performed in the activating runtime element with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

If the formal parameter is not of class object or pointer, the conformance rules are the following:

  1. If the activated element is a program for which there is no program-specifier in the Repository paragraph of the activating element and there is no NESTED phrase specified on the CALL statement, the formal parameter must be described with the same number of character positions as the corresponding argument.
  2. If the activated unit is one of the following:
    • A program for which there is a program-specifier in the Repository paragraph of the activating element
    • A program that was called with a CALL statement in which the NESTED phrase is specified
    • A method
    • A function

    then the conformance rules depend on the type of the formal parameter as specified in the following rules:

    1. If the formal parameter is numeric, the conformance rules are the same as for a COMPUTE statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.
    2. If the formal parameter is an index or pointer data item, the conformance rules are the same as for a SET statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.
    3. If the formal parameter is described with the ANY LENGTH clause, its length is considered to match the length of the corresponding argument.
    4. Otherwise, the conformance rules are the same as for a MOVE statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.
Parent topic: Elementary Items


Returning Items

A returning item must be specified in the activating statement, if and only if a returning item is specified in the PROCEDURE DIVISION header

MF or ENTRY statement

of the activated source element. A returning item is implicitly specified in the activating element when a function or inline method invocation is referenced.

The returning item in the activated source element is the sending operand, the corresponding returning item in the activating source element is the receiving operand.

The rules for conformance between the sending operand and the receiving operand depend on whether at least one of the operands is an alphanumeric group item or both operands are elementary items.

  • Group Items
  • Elementary Items
Parent topic: Conformance for Parameters and Returning Items


Group Items

If either the sending or the receiving operand is a group item, the corresponding returning item must be a group item or an elementary item of category alphanumeric, and the receiving operand must be described with the same number of character positions as the sending operand.

Note: If a returning item in an activating element is a group with a level number other than 1 and its subordinate items are described such that the implementation inserts slack bits or bytes, the alignment of the subordinate elementary items might not correspond between the returning item in the activating runtime element and the returning item in the activated runtime element.

For an operand that is described as a variable-occurrence data item, the maximum length is used.

Parent topic: Returning Items


Elementary Items

If either of the operands is an object reference, the corresponding item must be an object reference, and the following rules apply:

  1. If the returning item in the activated source element is not described with an ACTIVE-CLASS phrase, the conformance rules are be the same as if a SET statement were performed in the activated runtime element with the returning item in the activated source element as the sending operand and the corresponding returning item in the activating source element as the receiving operand.
  2. If the returning item in the activated source element is described with an ACTIVE-CLASS phrase, the conformance rules are the same as if a SET statement were performed in the activating runtime element with the returning item in the activating source element as the receiving operand, and a sending operand described with USAGE OBJECT REFERENCE as determined by the following rules:
    1. If the activated method is invoked with a class-name, the sending operand is described with the same class-name and an ONLY phrase.
    2. If the activated method is invoked with the predefined object references SELF or SUPER

      MF or SELFCLASS

      , the sending operand is described with an ACTIVE-CLASS phrase.

    3. If the activated method is invoked with an object reference described with an interface-name, the sending operand is a universal object reference.
    4. If the activated method is invoked with any other object reference, this identifier is used as the sending operand, including the ONLY phrase if specified.
    5. If the sending operand selected by applying the above rules is described with a class-name or an ACTIVE-CLASS phrase, the presence or absence of the FACTORY phrase is the same as in the returning item of the activated source element.

If the sending operand is not an object reference, the receiving operand must have the same PICTURE, USAGE, SIGN, SYNCHRONIZED, JUSTIFIED, and BLANK clauses, with the following exceptions:

  1. Currency symbols match if and only if the corresponding currency strings are the same.
  2. Period picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both the activating and the activated runtime elements or for neither of them.
  3. Comma picture symbols match if and only if the DECIMAL-POINT IS COMMA clause is in effect for both the activating and the activated runtime elements or for neither of them.

Additionally:

  1. If the receiving operand is described with the ANY LENGTH clause, the sending operand must also be described with the ANY LENGTH clause.
  2. If the sending operand is described with the ANY LENGTH clause, the length of the sending operand is considered to match the length of the receiving operand.
Parent topic: Returning Items


Intrinsic Functions

General Description

An intrinsic function is a temporary data item whose value is determined at the time the function is referenced during the execution of a statement. An intrinsic-function-name is a COBOL word that is one of a specified list of COBOL words which can be used in COBOL source programs. (For a list of all the available functions, see the topic Definitions of Functions .)

Function Definition and Returned Value

The definition of each function specifies:

  • For alphanumeric

    MF and national

    functions, the size of the returned value

  • For numeric and integer functions, the sign of the returned value and whether the function is integer
  • For some other cases, the value returned.

Function Identifier

A function identifier is used to reference a function in the Procedure Division of a COBOL source program.

The value returned by a function is considered to be a data value. A mechanism is provided at run time to assign a data value to a function when it is referenced. In order to determine the function's value, the evaluation mechanism requires access to data values provided by the referencing program. These data values are provided by specifying parameters, known as arguments, when referencing the function. Specific functions can place constraints on these arguments, such as range, and so on. If, at the time a function is referenced, the arguments specified for that reference do not have values that comply with the specified constraints, then the returned value for the function is undefined.

  • Arguments
  • Function Types
  • Definitions of Functions
Parent topic: Procedure Division


Arguments

Arguments specify values used in the evaluation of a function. Arguments are specified in the function-identifier. These arguments can be specified as identifiers, as arithmetic expressions, or as literals. The definition of a function specifies the number of arguments required, which can be zero, one, or more. For some functions, the number of arguments which can be specified is variable. The order in which arguments are specified in a function-identifier determines the interpretation given to each value in arriving at the function value. Arguments may be required to have a certain class or a subset of a certain class. The types of argument are:

  1. Numeric. An arithmetic expression must be specified. The value of the arithmetic expression, including operational sign, is used in determining the value of the function.
  2. Alphabetic. An elementary data item of the class alphabetic or a nonnumeric literal containing only alphabetic characters must be specified. The size associated with the argument can be used in determining the value of the function.
  3. Alphanumeric. A data item of the class alphabetic or alphanumeric or a nonnumeric literal must be specified. The size associated with the argument can be used in determining the value of the function.
  4. MF National. An elementary data item of class national or a national literal must be specified. The size associated with the argument can be used in determining the value of the function.
  5. Integer. An arithmetic expression which will always result in an integer value must be specified. The value of the arithmetic expression, including operational sign, is used in determining the value of the function.

The rules for a function can place constraints on the permissible values for arguments, in order to accurately determine the function's value. If, at the time a function is referenced, the arguments specified for that reference do not have values within the permissible range, the returned value for the function is undefined.

When the definition of a function permits an argument to be repeated a variable number of times, a table can be referenced by specifying the data-name and any qualifiers that identify the table, followed immediately by subscripting where one or more of the subscripts is the word ALL.

When ALL is specified as a subscript, the effect is as if each table element associated with that subscript position were specified. The order of the implicit specification of each occurrence is from left to right, with the first (or leftmost) specification being the identifier with each subscript specified by the word ALL replaced by one, the next specification being the same identifier with the rightmost subscript specified by the word ALL incremented by one.

This process continues with the rightmost ALL subscript being incremented by one for each implicit specification until the rightmost ALL subscript has been incremented through its range of values. If any additional ALL subscripts exist, the subscript immediately to the left of the rightmost ALL subscript is incremented by one, the rightmost ALL subscript is reset to one and the process of varying the rightmost ALL subscript is repeated. The ALL subscript to the left of the rightmost ALL subscript is incremented through its range of values. For each additional ALL subscript this process is repeated in turn until the leftmost ALL subscript has been incremented by one through its range of values.

If the ALL subscript is associated with an OCCURS DEPENDING ON clause, the range of values is determined by the object of the OCCURS DEPENDING ON clause. The evaluation of an ALL subscript must result in at least one argument, otherwise the result of the reference to the function-identifier is undefined.

Example

 01 Test-Fields.
     10 OT-Elem                  PIC 9(02).
     10 Arr.
         15 Ind occurs 5 times        PIC 9(02).
     compute OT-Elem = function sum (IND(ALL)).

is equivalent to specifying

     compute OT-Elem = function sum (IND(1), IND(2), IND(3),
                                            IND(4), IND(5)).

The ALL subscript can also be used with a table that has a variable number of elements as in the following example:

 01 Test-Group.
     03 OT-Elem               pic 9(15) binary.
     03 table-length          pic s9(9) binary.
     03 array.
         05 Ind pic 9(2) occurs 1 to 200 times depending on
                              table length
      ...
     move 100 to table-length.
     compute OT-Elem = function sum (Ind(ALL))

These statements will sum the first 100 elements of the table. At the time the function is referenced, the number of elements specified by table-length determines that number of elements that are added.

Parent topic: Intrinsic Functions
Related information
Intrinsic Functions
Data Item Functions
Date Conversion Functions
Trigonometric Functions
Definitions of Functions


Function Types

  • Data Item Functions
  • Date Conversion Functions
  • Trigonometric Functions
Parent topic: Intrinsic Functions


Data Item Functions

Data item functions are elementary data items and return alphanumeric,

MF national,

numeric or integer values. Data item functions are treated as elementary data items and cannot be receiving operands. The types of data item functions are:

  1. Alphanumeric functions. These are of the class and category alphanumeric. The number of character positions in this data item is specified in the function definition. Alphanumeric functions have an implicit usage of DISPLAY.
  2. Numeric functions. These are of the class and category numeric. A numeric function is always considered to have an operational sign.
    • A numeric function can be used only in an arithmetic expression

      MF or as the source of a MOVE statement

    • A numeric function cannot be referenced where an integer operand is required, even though a particular reference can yield an integer value.
  3. Integer functions. These are of the class and category numeric. An integer function is always considered to have an operational sign.
    • An integer function can be used only in an arithmetic expression

      MF or as the source of a MOVE statement

      ISO2002 or anywhere an integer data item is not used as a receiving data item.

    • An integer function can be referenced where an integer operand is required and where a signed operand is allowed.
  4. MF National functions. These are of the class and category national. The number of character positions in this data item is specified in the function definition. National functions have an implicit usage of NATIONAL.
Parent topic: Function Types
Related information
Intrinsic Functions
Arguments
Date Conversion Functions
Trigonometric Functions
Definitions of Functions


Date Conversion Functions

Date conversion functions are of type integer. The Gregorian calendar is used in the date conversion functions. The starting date of Monday, January 1, 1601, was chosen to establish a simple relationship between the date and DAY-OF-WEEK; that is, the integer date 1 was a Monday, DAY-OF-WEEK 1.

For example, the statement:

compute DoW =
     function rem (function integer-of-date (date-field) , 7)

returns the day of week for a given date, where 0 is Sunday, 1 is Monday, and so on.

Parent topic: Function Types
Related information
Intrinsic Functions
Arguments
Data Item Functions
Trigonometric Functions
Definitions of Functions


Trigonometric Functions

Trigonometric functions are of type numeric. Trigonometry deals with the relationships among the sides of a triangle and its angles. An angle can be measured in degrees, radians or Gon (grad). Since a computer usually generates trigonometric values by series approximation, the angle is specified in radians when used as the argument to the SIN, COS, and TAN functions or as the returned value from the ASIN, ACOS, and ATAN functions.

A radian is an arc of a circle whose length is equal to the circle's radius. Since the relationship between a circle's radius and circumference is C = 2 * P * r, and there are 360 degrees in a circle, we can derive from 360 = 2 * P * r, that the values for conversion are:

1 radian = 180/P = 57.295780 degrees 1 degree = P/180 = 0.01745329 radians.

Another scale that is sometimes used to measure angles is Gon, also known as grad. The values for conversion are:

1 radian = 200/P = 63.661977 Gon (grad) 1 Gon (grad) = P/200 = 0.01570796 radians.

Parent topic: Function Types
Related information
Intrinsic Functions
Arguments
Data Item Functions
Date Conversion Functions
Definitions of Functions


Definitions of Functions

The table below summarizes the intrinsic functions that are available.

The "arguments" column defines argument type and the "type" column defines the type of the function, as follows:

Alph | means alphabetic
Anum | means alphanumeric
Int | means integer
Nat | means national
Num | means numeric
Table 1. Summary of Functions
Function-Name | Arguments | Type | Value Returned
The ABS Function | Int1 or Num1 | Depends upon arguments | The absolute value of argument
The ACOS Function | Num1 | Num | Arccosine of Num1
The ANNUITY Function | Num1, Int2 | Num | Ratio of annuity paid for Int2 periods at interest of Num1 to initial investment of one
The ASIN Function | Num1 | Num | Arcsine of Num1
The ATAN Function | Num1 | Num | Arctangent of Num1
The CHAR Function | Int1 | Anum | Character in position Int1 of the alphanumeric program collating sequence
The CHAR-NATIONAL Function | Int1 | Nat | Character in position Int1 of the national program collating sequence
The COS Function | Num1 | Num | Cosine of Num1
The CURRENT-DATE Function | None | Anum | Current date and time and difference from Greenwich Mean Time
The DATE-OF-INTEGER Function | Int1 | Int | Standard date equivalent (YYYYMMDD) of integer date
The DATE-TO-YYYYMMDD Function | Int1, Int2 | Int | Argument-1 converted from YYMMDD to YYYYMMDD based on the value of argument-2
The DAY-OF-INTEGER Function | Int1 | Int | Julian date equivalent (YYYYDDD) of integer date
The DAY-TO-YYYYDDD Function | Int1, Int2 | Int | Argument-1 converted from YYDDD to YYYYDDD based on the value of argument-2
The DISPLAY-OF Function | Nat1, ENT MF Anum1 ENT Num1 | Anum | Usage display representation of argument Nat1
The E Function | None | Num | The value of e, the natural base
The EXP Function | Num1 | Num | e raised to the power Num1
The EXP10 Function | Num1 | Num | 10 raised to the power Num1
The FACTORIAL Function | Int1 | Int | Factorial of Int1
The FRACTION-PART Function | Num1 | Num | Fraction part of Num1
The INTEGER Function | Num1 | Int | The greatest integer not greater than Num1
The INTEGER-OF-DATE Function | Int1 | Int | The integer date equivalent of standard date (YYYYMMDD)
The INTEGER-OF-DAY Function | Int1 | Int | The integer date equivalent of Julian date (YYYYDDD)
The INTEGER-PART Function | Num1 | Int | Integer part of Num1
The LENGTH Function | Alph1 or Anum1 MF or Nat1 or Num1 | Int | Length of argument in number of character positions
The LENGTH-AN Function | Alph1 or Anum1 or Int1 or Nat1 or Num1 | Int | Length of argument in number of alphanumeric character positions
The LOG Function | Num1 | Num | Natural logarithm of Num1
The LOG10 Function | Num1 | Num | Logarithm to base 10 of Num1
The LOWER-CASE Function | Alph1 or Anum1 MF or Nat1 | Depends upon argument* | All letters in the argument are set to lowercase
The MAX Function | Alph1 ... or Anum1 ... or Int1 ... or MF Nat1 ... or Num1 ... | Depends upon arguments* | Value of maximum argument
The MEAN Function | Num1 ... | Num | Arithmetic mean of arguments
The MEDIAN Function | Num1 ... | Num | Median of arguments
The MIDRANGE Function | Num1 ... | Num | Mean of minimum and maximum arguments
The MIN Function | Alph1 ... or Anum1 ... or Int1 ... or MF Nat1 ... or Num1 ... | Depends upon arguments* | Value of minimum argument
The MOD Function | Int1, Int2 | Int | Int1 modulo Int2
The NATIONAL-OF Function | Anum1 MF or Nat1 Num1 | Nat | Usage national representation of argument Anum1
The NUMVAL Function | Anum1 or MF or Nat1 | Num | Numeric value of simple numeric string
The NUMVAL-C Function | Anum1 or Anum2 MF or Nat1 or Nat2 | Num | Numeric value of numeric string with optional commas and currency string
The ORD Function | Alph1 or Anum1 MF or Nat1 | Int | Ordinal position of the argument in collating sequence
The ORD-MAX Function | Alph1 ... or Anum1 ... or MF Nat1 ... or Num1 | Int | Ordinal position of maximum argument
The ORD-MIN Function | Alph1 ... or Anum1 ... or MF Nat1 ... or Num1 | Int | Ordinal position of minimum argument
The PI Function | None | Num | Value of
The PRESENT-VALUE Function | Num1, Num2 ... | Num | Present value of a series of future period-end amounts, Num2, at a discount rate of Num1
The RANDOM Function | Int1 | Num | Random number
The RANGE Function | Int1 ... or Num1 | Depends upon arguments* | Value of maximum argument minus value of minimum arguments
The REM Function | Num1, Num2 | Num | Remainder of Num1/Num2
The REVERSE Function | Alph1 or Anum1 MF or Nat1 | Depends upon argument* | Reverse order of the characters of the argument
The SIGN Function | Num1 | Int | The sign of Num1
The SIN Function | Num1 | Num | Sine of Num1
The SQRT Function | Num1 | Num | Square root of Num1
The STANDARD-DEVIATION Function | Num1 ... | Num | Standard deviation of arguments
The SUM Function | Int1 ... or Num1 ... | Depends upon arguments | Sum of arguments
The TAN Function | Num1 | Num | Tangent of Num1
The ULENGTH Function | Alph1 or Anum1 | Int | Number of characters in Alph1 or Anum1
The UPOS Function | Alph1 or Anum1, Int1 | Int | Position of nth UTF-8 char in Alph1 or Anum1
The UPPER-CASE Function | Alph1 or Anum1 MF or Nat1 | Depends upon argument* | All letters in the argument are set to uppercase
The USUBSTR Function | Alph1 or Anum1, Num1, Num2 | Anum | Substring of a character string argument that is encoded in UTF-8
The USUPPLEMENTARY Function | Alph1 or Anum1 MF or Nat1 | Int | Integer value that is equal to the index of the first Unicode supplementary character in a character string argument that is encoded in UTF-8 or UTF-16
The UVALID Function | Alph1 or Anum1 MF or Nat1 | Int | Zero if character string consists of valid Unicode UTF-8 or UTF-16 data; non-zero if not.
The UWIDTH Function | Alph1 or Anum1, Int1 | Int | integer value that is equal to the width in bytes of the nth UTF-8 character in a character string
The VARIANCE Function | Num1 ... | Num | Variance of argument
The WHEN-COMPILED Function | None | Anum | Date and time program was compiled
The YEAR-TO-YYYY Function | Int1, Int2 | Int | Argument-1 converted from YY to YYYY based on the value of argument-2

* A function that has only alphabetic arguments is type alphanumeric.

  • The ABS Function
    The ABS function returns the absolute value of the argument.
  • The ACOS Function
    The ACOS function returns a numeric value in radians that approximates the arccosine of argument-1. The type of this function is numeric.
  • The ANNUITY Function
    The ANNUITY function (annuity immediate) returns a numeric value that approximates the ratio of an annuity paid at the end of each period for the number of periods specified by argument-2 to an initial investment of one. Interest is earned at the rate specified by argument-1 and is applied at the end of the period, before the payment. The type of this function is numeric.
  • The ASIN Function
    The ASIN function returns a numeric value in radians that approximates the arcsine of argument-1. The type of this function is numeric.
  • The ATAN Function
    The ATAN function returns a numeric value in radians that approximates the arctangent of argument-1. The type of this function is numeric.
  • The BOOLEAN-OF-INTEGER Statement
    The BOOLEAN-OF-INTEGER function returns a boolean item of usage bit representing the binary value of argument-1. Argument-2 specifies the length of the boolean data item that is returned.
  • The CHAR Function
    The CHAR function returns a one-character alphanumeric value that is a character in the program collating sequence having the ordinal position equal to the value of argument-1. The type of this function is alphanumeric.
  • The CHAR-NATIONAL Function
    The CHAR-NATIONAL (national character) function returns a one-character value that is a character in the national program collating sequence having the ordinal position equal to the value of the argument.
  • The COS Function
    The COS function returns a numeric value that approximates the cosine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.
  • The CURRENT-DATE Function
    The CURRENT-DATE function returns a 21-character alphanumeric value that represents the calendar date, time of day, and local time differential factor provided by the system on which the function is evaluated. The type of this function is alphanumeric.
  • The DATE-OF-INTEGER Function
    The DATE-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to standard date form (YYYYMMDD). The type of this function is integer.
  • The DATE-TO-YYYYMMDD Function
    The DATE-TO-YYYYMMDD function converts argument-1 from the form YYmmdd to the form YYYYmmdd. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.
  • The DAY-OF-INTEGER Function
    The DAY-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to Julian date form (YYYYDDD). The type of this function is integer.
  • The DAY-TO-YYYYDDD Function
    The DAY-TO-YYYYDDD function converts argument-1 from the form YYnnn to the form YYYYnnn. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.
  • The DISPLAY-OF Function
    The DISPLAY-OF function returns a character string containing the alphanumeric character representation - the external format representation - of the national characters in the argument.
  • The E Function
    The E function returns an approximation of e, the base of natural logarithms.
  • The EXP Function
    The EXP function returns an approximation of the value of e raised to the power of the argument.
  • The EXP10 Function
    The EXP10 function returns an approximation of the value of 10 raised to the power of the argument.
  • The FACTORIAL Function
    The FACTORIAL function returns an integer that is the factorial of argument-1. The type of this function is integer.
  • The FRACTION-PART Function
    The FRACTION-PART function returns a numeric value that is the fraction portion of the argument.
  • The INTEGER Function
    The INTEGER function returns the greatest integer value that is less than or equal to the argument. The type of this function is integer.
  • The INTEGER-OF-BOOLEAN Statement
    The INTEGER-OF-BOOLEAN function returns the numeric value of the boolean string in argument-1.
  • The INTEGER-OF-DATE Function
    The INTEGER-OF-DATE function converts a date in the Gregorian calendar from standard date form (YYYYMMDD) to integer date form. The type of this function is integer.
  • The INTEGER-OF-DAY Function
    The INTEGER-OF-DAY function converts a date in the Gregorian calendar from Julian date form (YYYYDDD) to integer date form. The type of this function is integer.
  • The INTEGER-PART Function
    The INTEGER-PART function returns an integer that is the integer portion of argument-1. The type of this function is integer.
  • The LENGTH Function
    The LENGTH function returns an integer equal to the length of the argument in alphanumeric character positions
  • The LENGTH-AN Function
    The LENGTH-AN function returns an integer equal to the length of the argument in number of alphanumeric character positions.
  • The LOG Function
    The LOG function returns a numeric value that approximates the logarithm to the base e (natural log) of argument-1. The type of this function is numeric.
  • The LOG10 Function
    The LOG10 function returns a numeric value that approximates the logarithm to the base 10 of argument-1. The type of this function is numeric.
  • The LOWER-CASE Function
    The LOWER-CASE function returns a character string that is the same length as argument-1 with each upper-case letter replaced by the corresponding lower-case letter. The type of this function depends on the argument as follows:
  • The MAX Function
    The MAX function returns the content of the argument-1 that contains the maximum value. The type of this function depends upon the argument types as follows:
  • The MEAN Function
    The MEAN function returns a numeric value that is the arithmetic mean (average) of its arguments. The type of this function is numeric.
  • The MEDIAN Function
    The MEDIAN function returns the content of the argument whose value is the middle value in the list formed by arranging the arguments in sorted order. The type of this function is numeric.
  • The MIDRANGE Function
    The MIDRANGE (middle range) function returns a numeric value that is the arithmetic mean (average) of the values of the minimum argument and the maximum argument. The type of this function is numeric.
  • The MIN Function
    The MIN function returns the content of the argument-1 that contains the minimum value. The type of this function depends upon the argument types as follows:
  • The MOD Function
    The MOD function returns an integer value that is argument-1 modulo argument-2. The type of this function is integer.
  • The NATIONAL-OF Function
    The NATIONAL-OF function returns a character string containing the national character internal representation of the characters in the argument.
  • The NUMVAL Function
    The NUMVAL function returns the numeric value represented by the character string specified by argument-1. Leading and trailing spaces are ignored. The type of this function is numeric.
  • The NUMVAL-C Function
    The NUMVAL-C function returns the numeric value represented by the character string specified by argument-1. Any optional currency string specified by argument-2 and any optional commas preceding the decimal point are ignored. The type of this function is numeric.
  • The ORD Function
    The ORD function returns an integer value that is the ordinal position of argument-1 in the collating sequence for the program. The lowest ordinal position is 1. The type of this function is integer.
  • The ORD-MAX Function
    The ORD-MAX function returns a value that is the ordinal number of the argument-1 that contains the maximum value. The type of this function is integer.
  • The ORD-MIN Function
    The ORD-MIN function returns a value that is the ordinal number of the argument-1 that contains the minimum value. The type of this function is integer.
  • The PI Function
    The PI function returns a value that is an approximation of the ratio of the circumference of a circle to its diameter.
  • The PRESENT-VALUE Function
    The PRESENT-VALUE function returns a value that approximates the present value of a series of future period-end amounts specified by argument-2 at a discount rate specified by argument-1. The type of this function is numeric.
  • The RANDOM Function
    The RANDOM function returns a numeric value that is a pseudo-random number from a rectangular distribution. The type of this function is numeric.
  • The RANGE Function
    The RANGE function returns a value that is equal to the value of the maximum argument minus the value of the minimum argument. The type of this function depends upon the argument types as follows:
  • The REM Function
    The REM function returns a numeric value that is the remainder of argument-1 divided by argument-2. The type of this function is numeric.
  • The REVERSE Function
    The REVERSE function returns a character string whose length and characters are exactly the same as argument-1, except that the characters are in reverse order. The type of this function depends on the argument type as follows:
  • The SIGN Function
    The SIGN function returns +1, 0, or -1 depending on the sign of the argument.
  • The SIN Function
    The SIN function returns a numeric value that approximates the sine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.
  • The SQRT Function
    The SQRT function returns a numeric value that approximates the square root of argument-1. The type of this function is numeric.
  • The STANDARD-DEVIATION Function
    The STANDARD-DEVIATION function returns a numeric value that approximates the standard deviation of its arguments. The type of this function is numeric.
  • The SUM Function
    The SUM function returns a value that is the sum of the arguments. The type of this function depends upon the argument types as follows:
  • The TAN Function
    The TAN function returns a value that approximates the tangent of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.
  • The ULENGTH Function
    The ULENGTH function returns an integer value that is equal to the number of UTF-8 characters in a character string argument that is encoded in UTF-8.
  • The UPOS Function
    The UPOS function returns an integer value that is equal to the index of the nth UTF-8 character in a character string argument that is encoded in UTF-8.
  • The USUBSTR Function
    The USUBSTR function returns a substring of a character string argument that is encoded in UTF-8.
  • The USUPPLEMENTARY Function
    The USUPPLEMENTARY function returns an integer value that is equal to the index of the first Unicode supplementary character in a character string argument that is encoded in UTF-8 or UTF-16.
  • The UVALID Function
    If a character string consists of valid Unicode UTF-8 or UTF-16 data, the UVALID function returns the value zero. If a character string contains invalid Unicode data, the UVALID function returns the index of the first invalid element.
  • The UWIDTH Function
    The UWIDTH function returns an integer value that is equal to the width in bytes of the nth UTF-8 character in a character string argument that is encoded in UTF-8.
  • The UPPER-CASE Function
    The UPPER-CASE function returns a character string that is the same length as argument-1 with each lower-case letter replaced by the corresponding upper-case letter. The type of this function depends on the argument as follows:
  • The VARIANCE Function
    The VARIANCE function returns a numeric value that approximates the variance of its arguments. The type of this function is numeric.
  • The WHEN-COMPILED Function
    The WHEN-COMPILED function returns the date and time the program was compiled. The type of this function is alphanumeric.
  • The YEAR-TO-YYYY Function
    The YEAR-TO-YYYY function converts argument-1, the two low-order digits of a year, to a four-digit year. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.
Parent topic: Intrinsic Functions
Related information
Date Conversion Functions
Intrinsic Functions
Data Item Functions
Arguments
Trigonometric Functions


The ABS Function

The ABS function returns the absolute value of the argument.

The type of this function is according to the argument type as follows:

Argument Type | Function Type
Integer | Integer
Numeric | Numeric

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is as follows:
    1. When the value of argument-1 is zero or positive, (argument-1)
    2. When the value of argument-1 is negative, (-argument-1)
Parent topic: Definitions of Functions


The ACOS Function

The ACOS function returns a numeric value in radians that approximates the arccosine of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be greater than or equal to -1 and less than or equal to +1.

Returned Values

  1. The returned value is the approximation of the arccosine of argument-1 and is greater than or equal to zero and less than or equal to pi.
    Note: Conversion factors from radians to degrees and Gon (grad) are specified in the section Trigonometric Functions.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The ANNUITY Function

The ANNUITY function (annuity immediate) returns a numeric value that approximates the ratio of an annuity paid at the end of each period for the number of periods specified by argument-2 to an initial investment of one. Interest is earned at the rate specified by argument-1 and is applied at the end of the period, before the payment. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be greater than or equal to zero.
  3. Argument-2 must be a positive integer.

Returned Values

  1. When the value of argument-1 is zero, the value of the function is the approximation of:

    1 / argument-2

  2. When the value of argument-1 is not zero, the value of the function is the approximation of:

    argument-1 / (1 - (1 + argument-1) ** (- argument-2))

  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The ASIN Function

The ASIN function returns a numeric value in radians that approximates the arcsine of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be greater than or equal to -1 and less than or equal to +1.

Returned Values

  1. The returned value is the approximation of the arcsine of argument-1 and is greater than or equal to -pi/2 and less than or equal to +pi/2.
    Note: Conversion factors from radians to degrees and Gon (grad) are specified in the section Trigonometric Functions.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The ATAN Function

The ATAN function returns a numeric value in radians that approximates the arctangent of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the approximation of the arctangent of argument-1 and is greater than -pi/2 and less than +pi/2.
    Note: Conversion factors from radians to degrees and Gon (grad) are specified in the section Trigonometric Functions.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The BOOLEAN-OF-INTEGER Statement

The BOOLEAN-OF-INTEGER function returns a boolean item of usage bit representing the binary value of argument-1. Argument-2 specifies the length of the boolean data item that is returned.

The function type is boolean.

The returned value is a boolean item of usage bit that has the same bit configuration as the binary representation of the value of argument-1, where the rightmost boolean position is the low-order binary digit. The boolean value is zero-filled or truncated on the left, if necessary, in order to return a boolean item whose length is specified by argument-2 in terms of boolean positions.

General Format

FUNCTION BOOLEAN-OF-INTEGER (argument-1 argument-2)

Syntax Rules

  1. Argument-1 must be a positive integer.
  2. Argument-2 must be a positive nonzero integer.
  3. Argument-2 must be a numeric constant when the function is used
    • in an expression with B-NOT
    • as part of a boolean expression which is used as an argument in INTEGER-OF-BOOLEAN
Parent topic: Definitions of Functions


The CHAR Function

The CHAR function returns a one-character alphanumeric value that is a character in the program collating sequence having the ordinal position equal to the value of argument-1. The type of this function is alphanumeric.

General Format

Arguments

  1. Argument-1 must be an integer.
  2. The value of argument-1 must be greater than zero and less than or equal to the number of positions in the collating sequence.

Returned Values

  1. If more than one character has the same position in the program collating sequence, the character returned as the function value is that of the first literal specified for that character position in the ALPHABET clause.
  2. If the current program collating sequence was not specified by an ALPHABET clause, the native collating sequence is used.
Parent topic: Definitions of Functions


The CHAR-NATIONAL Function

The CHAR-NATIONAL (national character) function returns a one-character value that is a character in the national program collating sequence having the ordinal position equal to the value of the argument.

The type of the function is national.

General Format

Arguments

  1. Argument-1 must be an integer.
  2. The value of argument-1 must be greater than zero and less than or equal to the number of positions in the national program collating sequence.

Returned Values

  1. The returned value is the character in the national program collating sequence having the ordinal position specifed by argument-1.
  2. If more than one character has the same ordinal positon in the current national program collating sequence, the returned value is the first character defined for that position.
Parent topic: Definitions of Functions


The COS Function

The COS function returns a numeric value that approximates the cosine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
    Note: Conversion factors from degrees and Gon (grad) to radians are specified in the section Trigonometric Functions.

Returned Values

  1. The returned value is the approximation of the cosine of argument-1 and is greater than or equal to -1 and less than or equal to +1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The CURRENT-DATE Function

The CURRENT-DATE function returns a 21-character alphanumeric value that represents the calendar date, time of day, and local time differential factor provided by the system on which the function is evaluated. The type of this function is alphanumeric.

General Format

Returned Values

  1. The character positions returned, numbered from left to right, are:
    Character Positions | Contents
    1-4 | Four numeric digits of the year in the Gregorian calendar.
    5-6 | Two numeric digits of the month of the year, in the range 01 through 12.
    7-8 | Two numeric digits of the day of the month, in the range 01 through 31.
    9-10 | Two numeric digits of the hours past midnight, in the range 00 through 23.
    11-12 | Two numeric digits of the minutes past the hour, in the range 00 through 59.
    13-14 | Two numeric digits of the seconds past the minute, in the range 00 through 59.
    15-16 Two numeric digits of the hundredths of a second past the second, in the range 00 through 99.

    If the system does not have the facility to provide fractional parts of a second, the value 00 is returned.

    17 Either the character "-", the character " +", or the character "0". The character "-" is returned if the local time indicated in the previous character positions is behind Greenwich Mean Time. The character "+" is returned if the local time indicated is the same or ahead of Greenwich Mean Time. The character "0" is returned if the system on which this function is evaluated does not have the facility to provide the local time differential factor.

    If the system does not have the facility to provide the local time differential factor, the value 00000 is returned in character positions 17 through 21.

    18-19 | If character position 17 is "-", two numeric digits are returned in the range 00 through 12 indicating the number of hours that the reported time is behind Greenwich Mean Time. If character position 17 is "+", two numeric digits are returned in the range 00 through 13 indicating the number of hours that the reported time is ahead of Greenwich Mean Time. If character position 17 is "0", the value 00 is returned.
    20-21 | Two numeric digits are returned in the range 00 through 59 indicating the number of additional minutes that the reported time is ahead of or behind Greenwich Mean Time, depending on whether character position 17 is "+" or "-" , respectively. If character position 17 is "0", the value 00 is returned.
Parent topic: Definitions of Functions


The DATE-OF-INTEGER Function

The DATE-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to standard date form (YYYYMMDD). The type of this function is integer.

General Format

Arguments

  1. Argument-1 is a positive integer that represents a number of days succeeding December 31, 1600, in the Gregorian calendar.

Returned Values

  1. The returned value represents the ISO Standard date equivalent of the integer specified in argument-1.
  2. The returned value is in the form (YYYYMMDD) where YYYY represents a year in the Gregorian calendar; MM represents the month of that year; and DD represents the day of that month.
Parent topic: Definitions of Functions


The DATE-TO-YYYYMMDD Function

The DATE-TO-YYYYMMDD function converts argument-1 from the form YYmmdd to the form YYYYmmdd. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.

General Format

    FUNCTION DATE-TO-YYYYMMDD ( argument-1 [argument-2] )

Arguments

  1. Argument-1 must be a positive integer less than 1,000,000.
  2. Argument-2 must be an integer.
  3. If argument-2 is omitted, the function is evaluated as though 50 were specified.
  4. The sum of the year at the time of execution and the value of argument-2 must be less than 10,000 and greater than 1699.

Returned Values

  1. The equivalent arithmetic expression is:

    (FUNCTION YEAR-TO-YYYY (YY, argument-2) * 10000 + nnnn) where:

    YY = FUNCTION INTEGER (argument-1/10000) nnnn = FUNCTION MOD (argument-1, 10000)

    and where argument-1 of the INTEGER and MOD functions and argument-2 of the YEAR-TO-YYYY function are the same as argument-1 and argument-2 of the DATE-TO-YYYYMMDD function itself.

Notes

  1. In the year 2002 the returned value for FUNCTION DATE-TO-YYYYMMDD (851003, 10) is 19851003. In the year 1994 the returned value for FUNCTION DATE-TO-YYYYMMDD (981002, (-10)) is 18981002.
  2. This function supports a sliding window algorithm. See the notes for the YEAR-TO-YYYY function for a discussion of how to specify a fixed window.
Parent topic: Definitions of Functions


The DAY-OF-INTEGER Function

The DAY-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to Julian date form (YYYYDDD). The type of this function is integer.

General Format

Arguments

  1. Argument-1 is a positive integer that represents a number of days succeeding December 31, 1600, in the Gregorian calendar.

Returned Values

  1. The returned value represents the Julian equivalent of the integer specified in argument-1.
  2. The returned value is an integer of the form (YYYYDDD) where YYYY represents a year in the Gregorian calendar and DDD represents the day of that year.
Parent topic: Definitions of Functions


The DAY-TO-YYYYDDD Function

The DAY-TO-YYYYDDD function converts argument-1 from the form YYnnn to the form YYYYnnn. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.

General Format

    FUNCTION DAY-TO-YYYYDDD ( argument-1 [argument-2] )

Arguments

  1. Argument-1 must be a positive integer less than 100,000.
  2. Argument-2 must be an integer.
  3. If argument-2 is omitted, the function is evaluated as though 50 were specified.
  4. The sum of the year at the time of execution and the value of argument-2 must be less than 10,000 and greater than 1699.

Returned Values

  1. The equivalent arithmetic expression is:

    (FUNCTION YEAR-TO-YYYY (YY, argument-2) * 1000 + nnn)

    where:

    YY = FUNCTION INTEGER (argument-1/1000) nnn = FUNCTION MOD (argument-1, 1000)

    and where argument-1 of the INTEGER and MOD functions and argument-2 of the YEAR-TO-YYYY functions are the same as argument-1 and argument-2 of the DAY-TO-YYYYDDD function itself.

Notes

  1. In the year 2002 the returned value for FUNCTION DAY-TO-YYYYDDD (10004,20) is 2010004. In the year 1994 the returned value for FUNCTION DAY-TO-YYYYDDD (95005, (-10)) is 1895005.
  2. This function supports a sliding window algorithm. See the notes for the YEAR-TO-YYYY function for a discussion of how to specify a fixed window.
Parent topic: Definitions of Functions


The DISPLAY-OF Function

The DISPLAY-OF function returns a character string containing the alphanumeric character representation - the external format representation - of the national characters in the argument.

The type of the function is alphanumeric.

General Format

Arguments

  1. Argument-1 must be of class national.
  2. ISO2002 MF Argument-2 must be of class alphabetic or alphanumeric and must be one character position in length. Argument-2 specifies an alphanumeric substitution character for use in conversion of national characters for which there is no corresponding alphanumeric character.

    ENT Must be an integer. Argument-2 identifies the source code page for the conversion. Full support for a CCSID value other than 1208 (UTF-8) requires the installation of the appropriate IBM CCSID conversion table; see Installing CCSID Tables for more information. The table name required for a CCSID of nnn is IBM-nnn. For example, to support a CCSID value of 37, you should install table IBM-37. If the required table is not installed, the conversion is carried out using the default EBCDIC or ASCII code page (according to whether the given CCSID is EBCDIC or not).

Returned Values

  1. A character string is returned with each national character of argument-1 converted to its corresponding alphanumeric character representation, if any. The correspondence of characters between the alphanumeric character set and the national character set depends on the native environment.
  2. ISO2002 MF If argument-2 is specified, the alphanumeric substitution character is returned for each national character in argument-1 that has no corresponding alphanumeric character representation.
  3. ISO2002 MF If argument-2 is unspecified, each national character in argument-1 that has no corresponding alphanumeric character representation is returned in national external format, with the minimum of control functions necessary for interpretation of the external format characters.
  4. The length of the returned value is the number of character positions of usage display required to hold the returned value; it is dependent on the characters in the argument and on the attributes of the national character set.
Parent topic: Definitions of Functions


The E Function

The E function returns an approximation of e, the base of natural logarithms.

The type of the function is numeric.

General Format

Returned Values

  1. The returned value is:

    2.718281828459045235

Parent topic: Definitions of Functions


The EXP Function

The EXP function returns an approximation of the value of e raised to the power of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:

    FUNCTION E ** argument-1

Parent topic: Definitions of Functions


The EXP10 Function

The EXP10 function returns an approximation of the value of 10 raised to the power of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:

    10 ** argument-1

Parent topic: Definitions of Functions


The FACTORIAL Function

The FACTORIAL function returns an integer that is the factorial of argument-1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer greater than or equal to zero.

Returned Values

  1. If the value of argument-1 is zero, the value 1 is returned.
  2. If the value of argument-1 is positive, its factorial is returned.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The FRACTION-PART Function

The FRACTION-PART function returns a numeric value that is the fraction portion of the argument.

The type of the function is numeric.

General Format

Arguments

  1. Argument-1 must be of the class numeric.

Returned Values

  1. The returned value is:

    (argument-1 - FUNCTION INTEGER-PART (argument-1))

    where the argument for the INTEGER-PART function is the same as for the FRACTION-PART function itself.

    Note: If the value of argument-1 is +1.5, +0.5 is returned. If the value of argument-1 is -1.5, -0.5 is returned.
Parent topic: Definitions of Functions


The INTEGER Function

The INTEGER function returns the greatest integer value that is less than or equal to the argument. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, -2 is returned. If the value of argument-1 is +1.5, +1 is returned.
Parent topic: Definitions of Functions


The INTEGER-OF-BOOLEAN Statement

The INTEGER-OF-BOOLEAN function returns the numeric value of the boolean string in argument-1.

The function type is integer.

General Format

FUNCTION INTEGER-OF-BOOLEAN (argument-1)

Syntax Rules

  1. Argument-1 must be a boolean data item.
Parent topic: Definitions of Functions


The INTEGER-OF-DATE Function

The INTEGER-OF-DATE function converts a date in the Gregorian calendar from standard date form (YYYYMMDD) to integer date form. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer of the form YYYYMMDD, whose value is obtained from the calculation:

    (YYYY * 10,000) + (MM * 100) + DD.

    1. YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
    2. MM represents a month and must be a positive integer less than 13.
    3. DD represents a day and must be a positive integer less than 32 provided that it is valid for the specified month and year combination.

Returned Values

  1. The returned value is an integer that is the number of days by which the date represented by argument-1 succeeds December 31, 1600, in the Gregorian calendar.
Parent topic: Definitions of Functions


The INTEGER-OF-DAY Function

The INTEGER-OF-DAY function converts a date in the Gregorian calendar from Julian date form (YYYYDDD) to integer date form. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be an integer of the form YYYYDDD, whose value is obtained from the calculation:

    (YYYY * 1000) + DDD.

    1. YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
    2. DDD represents the day of the year. It must be a positive integer less than 367 provided that it is valid for the year specified.

Returned Values

  1. The returned value is an integer that is the number of days by which the date represented by argument-1 succeeds December 31, 1600, in the Gregorian calendar.
Parent topic: Definitions of Functions


The INTEGER-PART Function

The INTEGER-PART function returns an integer that is the integer portion of argument-1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. If the value of argument-1 is zero, the returned value is zero.
  2. If the value of argument-1 is positive, the returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is +1.5, +1 is returned.
  3. If the value of argument-1 is negative, the returned value is the least integer greater than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, -1 is returned.
Parent topic: Definitions of Functions


The LENGTH Function

The LENGTH function returns an integer equal to the length of the argument in alphanumeric character positions

MF or national character positions, depending on the class of the argument.

The type of this function is integer.

General Format

Arguments

  1. Argument-1 can be a nonnumeric literal or a data item of any class or category.
  2. If argument-1 or any data item subordinate to argument-1 is described with the DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by the data-name specified in the DEPENDING phrase are used at the time the LENGTH function is evaluated.

Returned Values

  1. If argument-1 is an alphanumeric literal or is an elementary data item of class other than national or is a group data item that does not contain a variable occurrence data item, the value returned is an integer equal to the length of argument-1 in alphanumeric character positions.

    MF If argument-1 is an elementary data item of the class national or is a national literal, the returned value is an integer equal to the length of argument-1 in national character positions.

  2. If argument-1 is a group data item containing a variable occurrence data item, the returned value is an integer determined by evaluation of the data item specified in the DEPENDING phrase of the OCCURS clause for that variable occurrence data item. This evaluation is accomplished according to the rules in the OCCURS clause dealing with the data item as a sending data item. See the section The OCCURS Clause in the chapter Data Division - File and Data Description.
  3. The returned value includes implicit FILLER characters, if any.
Parent topic: Definitions of Functions
Related information
The OCCURS Clause


The LENGTH-AN Function

The LENGTH-AN function returns an integer equal to the length of the argument in number of alphanumeric character positions.

The type of the function is integer.

General Format

Arguments

  1. Argument-1 may be a literal or data item of any class or category.
  2. If argument-1 or any data item subordinate to argument-1 is described with the DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by the data-name specified in the DEPENDING phrase is used at the time the LENGTH-AN function is evaluated.

Returned Values

  1. If argument-1 is an elementary data item, the returned value is an integer equal to the length of argument-1 in alphanumeric character positions.
  2. If argument-1 is a group data item:
    1. If argument-1 or any data item subordinate to argument-1 is described with the DEPENDING phrase of the OCCURS clause, the returned value is an integer equal to the length of argument-1 in alphanumeric character positions, as a sending data item, determined by evaluation of the data item specified in the DEPENDING phrase in accordance with the rules of the OCCURS clause; otherwise the value returned is an integer equal to the length of argument-1 in alphanumeric character positions.
    2. The returned length includes the number of implicit FILLER positions, if any, in argument-1.
Parent topic: Definitions of Functions


The LOG Function

The LOG function returns a numeric value that approximates the logarithm to the base e (natural log) of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be greater than zero.

Returned Values

  1. The returned value is the approximation of the logarithm to the base e of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The LOG10 Function

The LOG10 function returns a numeric value that approximates the logarithm to the base 10 of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be greater than zero.

Returned Values

  1. The returned value is the approximation of the logarithm to the base 10 of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The LOWER-CASE Function

The LOWER-CASE function returns a character string that is the same length as argument-1 with each upper-case letter replaced by the corresponding lower-case letter. The type of this function depends on the argument as follows:
Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National

General Format

Arguments

  1. Argument-1 must be class alphabetic or alphanumeric

    MF or national

    and must be at least one character in length.

Returned Values

  1. The same character string as argument-1 is returned, except that each upper-case letter is replaced by the corresponding lower-case letter.
  2. The character string returned has the same length as argument-1.
  3. If the computer character set does not include lower-case letters, no changes take place in the character string.
Parent topic: Definitions of Functions


The MAX Function

The MAX function returns the content of the argument-1 that contains the maximum value. The type of this function depends upon the argument types as follows:
Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National
All arguments integer | Integer
Numeric | Numeric
(some arguments can be integer) |

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class except alphabetic and alphanumeric arguments which can be mixed.

Returned Values

  1. The returned value is the content of the argument-1 having the greatest value. The comparisons used to determine the greatest value are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  2. If more than one argument-1 has the same greatest value, the content of the argument-1 returned is the leftmost argument-1 having that value.
  3. If the type of the function is alphanumeric

    MF or national

    the size of the returned value is the same as the size of the selected argument-1.

  4. If the value of argument-1 is numeric non-integer, results are returned in floating-point format.
Parent topic: Definitions of Functions
Related information
Relation Condition


The MEAN Function

The MEAN function returns a numeric value that is the arithmetic mean (average) of its arguments. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the arithmetic mean of the argument-1 series.
  2. The returned value is defined as the sum of the argument-1 series divided by the number of occurrences referenced by argument-1.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The MEDIAN Function

The MEDIAN function returns the content of the argument whose value is the middle value in the list formed by arranging the arguments in sorted order. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the content of the argument-1 having the middle value in the list formed by arranging all the argument-1 values in sorted order.
  2. If the number of occurrences referenced by argument-1 is odd, the returned value is such that at least half of the occurrences referenced by argument-1 are greater than or equal to the returned value and at least half are less than or equal. If the number of occurrences referenced by argument-1 is even, the returned value is the arithmetic mean of the values referenced by the two middle occurrences.
  3. The comparisons used to arrange the argument-1 values in sorted order are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Relation Condition


The MIDRANGE Function

The MIDRANGE (middle range) function returns a numeric value that is the arithmetic mean (average) of the values of the minimum argument and the maximum argument. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the arithmetic mean of the greatest argument-1 value and the least argument-1 value.
  2. The comparisons used to determine the greatest and least values are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Relation Condition


The MIN Function

The MIN function returns the content of the argument-1 that contains the minimum value. The type of this function depends upon the argument types as follows:
Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National
All arguments integer | Integer
Numeric | Numeric
(some arguments can be integer) |

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class except alphabetic and alphanumeric arguments which can be mixed.

Returned Values

  1. The returned value is the content of the argument-1 having the least value. The comparisons used to determine the least value are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  2. If more than one argument-1 has the same least value, the content of the argument-1 returned is the leftmost argument-1 having that value.
  3. If the type of the function is alphanumeric

    MF or national,

    the size of the returned value is the same as the size of the selected argument-1.

  4. If the value of argument-1 is numeric non-integer, results are returned in floating-point format.
Parent topic: Definitions of Functions
Related information
Relation Condition


The MOD Function

The MOD function returns an integer value that is argument-1 modulo argument-2. The type of this function is integer.

General Format

Arguments

  1. Argument-1 and argument-2 must be integers.
  2. The value of argument-2 must not be zero.

Returned Values

  1. The returned value is argument-1 modulo argument-2. The returned value is defined as:

    argument-1 - (argument-2 * FUNCTION INTEGER (argument-1 / argument-2))

  2. The expected results for some values of argument-1 and argument-2 are as follows:
    Argument-1 | Argument-2 | Return
    11 | 5 | 1
    -11 | 5 | 4
    11 | -5 | -4
    -11 | -5 | -1
Parent topic: Definitions of Functions


The NATIONAL-OF Function

The NATIONAL-OF function returns a character string containing the national character internal representation of the characters in the argument.

The type of the function is national.

General Format

Arguments

  1. Argument-1 must be of class alphabetic or class alphnumeric. If alphanumeric, it may contain alphanumeric characters or national characters in external format, or both.
  2. ISO2002 MF Argument-2 must be of category national and must be one character in length. Argument-2 specifies a national substitution character for use in conversion of alphanumeric characters for which there is no corresponding national character.

    ENT Must be an integer. Argument-2 identifies the source code page for the conversion. Full support for a CCSID value other than 1208 (UTF-8) requires the installation of the appropriate IBM CCSID conversion table; see Installing CCSID Tables for more information. The table name required for a CCSID of nnn is IBM-nnn. For example, to support a CCSID value of 37, you should install table IBM-37. If the required table is not installed, the conversion is carried out using the default EBCDIC or ASCII code page (according to whether the given CCSID is EBCDIC or not).

Returned Values

  1. A character string is returned with each alphanumeric character and each national character in argument-1 converted to its corresponding national internal format. Any control functions used for external format representation in argument-1 are recognised only for purposes of distinguishing characters, and are not be considered as separate characters of argument-1.
  2. ISO2002 MF If argument-2 is specified, each character in argument-1 that has no corresponding internal national representation is converted to the substitution character specified by argument-2.

  3. ISO2002 MF If argument-2 is unspecified, each character that has no corresponding internal national representation is converted to a national space.

    .
  4. The length of the returned value is the number of character positions of usage national required to hold the converted argument and depends on the number of characters contained in argument-1.
Parent topic: Definitions of Functions


The NUMVAL Function

The NUMVAL function returns the numeric value represented by the character string specified by argument-1. Leading and trailing spaces are ignored. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be an alphanumeric

    MF or national

    literal or an alphanumeric

    MF or national

    data item whose content has one of the following two formats:

    or

    where space is a string of zero or more spaces and digit is a string of one to 18 digits.

  2. The total number of digits in argument-1 must not exceed 18.
  3. If the DECIMAL POINT IS COMMA clause is specified in the Special-Names paragraph, a comma must be used in argument-1 rather than a decimal point.

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. The number of digits returned is 18.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The NUMVAL-C Function

The NUMVAL-C function returns the numeric value represented by the character string specified by argument-1. Any optional currency string specified by argument-2 and any optional commas preceding the decimal point are ignored. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be an alphanumeric

    MF or national

    literal or an alphanumeric

    MF or national

    data item whose content has one of the following two formats:

    or

    where space is a string of zero or more spaces, cs is the string of one or more characters specified by argument-2 and digit is a string of one or more digits.

  2. If the DECIMAL POINT IS COMMA clause is specified in the Special-Names paragraph, the functions of the comma and decimal point in argument-1 are reversed.
  3. The total number of digits in argument-1 must not exceed 18.
  4. Argument-2, if specified, must be of the same class as argument-1.

    It cannot be a digit, comma, space, plus sign(+), minus sign (-) or decimal point.

  5. If argument-2 is not specified, the character used for cs is the currency string specified for the program when argument-1 is of class alphanumeric

    MF ; or if argument-1 is of class national, the national representation of the currency string specified for the program. The national representation of cs is the value returned from FUNCTION NATIONAL-OF (cs).

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. The number of digits returned is 18.
  3. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The ORD Function

The ORD function returns an integer value that is the ordinal position of argument-1 in the collating sequence for the program. The lowest ordinal position is 1. The type of this function is integer.

General Format

Arguments

  1. Argument-1 must be one character in length and must be class alphabetic, alphanumeric

    MF or national.

Returned Values

  1. If the class of argument-1 is alphabetic or alphanumeric, the returned value is the ordinal position of argument-1 in the current alphanumeric collating sequence for the program.
  2. MF If the class of argument-1 is national, the returned value is the ordinal position of argument-1 in the current national program collating sequence.
Parent topic: Definitions of Functions


The ORD-MAX Function

The ORD-MAX function returns a value that is the ordinal number of the argument-1 that contains the maximum value. The type of this function is integer.

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class, except alphabetic and alphanumeric arguments which can be mixed.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the greatest value in the argument-1 series.
  2. The comparisons used to determine the greatest valued argument are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If more than one argument-1 has the same greatest value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Definitions of Functions
Related information
Relation Condition


The ORD-MIN Function

The ORD-MIN function returns a value that is the ordinal number of the argument-1 that contains the minimum value. The type of this function is integer.

General Format

Arguments

  1. If more than one argument-1 is specified, all arguments must be of the same class, except alphabetic and alphanumeric arguments which may be mixed.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the lowest value in the argument-1 series.
  2. The comparisons used to determine the lowest valued argument are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If more than one argument-1 has the same lowest value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Definitions of Functions
Related information
Relation Condition


The PI Function

The PI function returns a value that is an approximation of the ratio of the circumference of a circle to its diameter.

The type of the function is numeric.

General Format

Returned Values

  1. The returned value is:

    3.141592653589793238

Parent topic: Definitions of Functions


The PRESENT-VALUE Function

The PRESENT-VALUE function returns a value that approximates the present value of a series of future period-end amounts specified by argument-2 at a discount rate specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 and argument-2 must be of the class numeric.
  2. The value of argument-1 must be greater than -1.

Returned Values

  1. The returned value is an approximation of the summation of a series of calculations with each term in the following form:

    argument-2 / (1+argument-1) ** n

    There is one term for each occurrence of argument-2. The exponent, n, is incremented from one by one for each term in the series.

  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The RANDOM Function

The RANDOM function returns a numeric value that is a pseudo-random number from a rectangular distribution. The type of this function is numeric.

General Format

Arguments

  1. If argument-1 is specified, it must be zero or a positive integer. It is used as the seed value to generate a sequence of pseudo-random numbers.
  2. If a subsequent reference specifies argument-1, a new sequence of pseudo-random numbers is started.
  3. MF If the first reference to this function in the run unit does not specify argument-1, the seed value of zero is used.
  4. In each case, subsequent references without specifying argument-1 return the next number in the current sequence.

Returned Values

  1. The returned value is greater than or equal to zero and less than one.
  2. For a given seed value on a given implementation, the sequence of pseudo-random numbers will always be the same.
  3. The domain of argument-1 values will yield distinct sequences of pseudo-random numbers. This subset includes the values from 0 through at least 32767.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The RANGE Function

The RANGE function returns a value that is equal to the value of the maximum argument minus the value of the minimum argument. The type of this function depends upon the argument types as follows:
Argument Type | Function Type
All arguments integer | Integer
Numeric | Numeric
(some arguments can be integer) |

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is equal to the greatest value of argument-1 minus the least value of argument-1.
  2. The comparisons used to determine the greatest and least values are made according to the rules for relation conditions. See the topic Relation Condition in the chapter Procedure Division.
  3. If the value of argument-1 is numeric non-integer, results are returned in floating-point format.
Parent topic: Definitions of Functions
Related information
Relation Condition


The REM Function

The REM function returns a numeric value that is the remainder of argument-1 divided by argument-2. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 and argument-2 must be class numeric.
  2. The value of argument-2 must not be zero.

Returned Values

  1. The returned value is the remainder of argument-1 / argument-2. It is defined as the expression:

    argument-1 - (argument-2 * FUNCTION INTEGER-PART (argument-1 / argument-2))

  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The REVERSE Function

The REVERSE function returns a character string whose length and characters are exactly the same as argument-1, except that the characters are in reverse order. The type of this function depends on the argument type as follows:
Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National

General Format

Arguments

  1. Argument-1 must be class alphabetic, alphanumeric

    MF or national

    and must be at least one character in length.

Returned Values

  1. If argument-1 is a character string of length n, the returned value is a character string of length n such that for 1 <j < n, the character in position j of the returned value is the character from position n-j+1 of argument-1.
Parent topic: Definitions of Functions


The SIGN Function

The SIGN function returns +1, 0, or -1 depending on the sign of the argument.

The type of the function is integer.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is:
    1. When the value of argument-1 is positive, 1
    2. When the value of argument-1 is zero, 0
    3. When the value of argument-1 is negative, -1
Parent topic: Definitions of Functions


The SIN Function

The SIN function returns a numeric value that approximates the sine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
    Note: Conversion factors from degrees and Gon (grad) to radians are specified in the section Trigonometric Functions.

Returned Values

  1. The returned value is the approximation of the sine of argument-1 and is greater than or equal to -1 and less than or equal to +1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The SQRT Function

The SQRT function returns a numeric value that approximates the square root of argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
  2. The value of argument-1 must be zero or positive.

Returned Values

  1. The returned value is the absolute value of the approximation of the square root of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The STANDARD-DEVIATION Function

The STANDARD-DEVIATION function returns a numeric value that approximates the standard deviation of its arguments. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the approximation of the standard deviation of the argument-1 series.
  2. The returned value is calculated as follows:
    1. The difference between each argument-1 value and the arithmetic mean of the argument-1 series is calculated and squared.
    2. The values obtained are added. This quantity is divided by the number of values in the argument-1 series.
    3. The square root of the quotient obtained is calculated. The returned value is the absolute value of this square root.
  3. If the argument-1 series consists of only one value, or if the argument-1 series consists of all variable occurrence data items and the total number of occurrences for all of them is one, the returned value is zero.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions


The SUM Function

The SUM function returns a value that is the sum of the arguments. The type of this function depends upon the argument types as follows:
Argument Type | Function Type
All arguments integer | Integer
Numeric | Numeric
(some arguments may be integer) |

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the sum of the arguments.
  2. If the argument-1 series are all integers, the value returned is an integer.
  3. If the argument-1 series are not all integers, a numeric value is returned in floating-point format.
Parent topic: Definitions of Functions


The TAN Function

The TAN function returns a value that approximates the tangent of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.
    Note: Conversion factors from degrees and Gon (grad) to radians are specified in the section Trigonometric Functions.

Returned Values

  1. The returned value is the approximation of the tangent of argument-1.
  2. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
Trigonometric Functions


The ULENGTH Function

The ULENGTH function returns an integer value that is equal to the number of UTF-8 characters in a character string argument that is encoded in UTF-8.

The function type is integer.

General Format

Arguments

argument-1
must be alphabetic or alphanumeric, and must contain valid UTF-8 encoded characters.

Returned Values

The returned value is the number of UTF-8 characters in argument-1.

Notes

If the UTF-8 argument contains composed characters (for example, ä, ê, and ü), the combining characters are counted individually in determining the length. See the following example where the returned value may vary for a composed character:

Character | Unicode encoding | UTF-8 encoding | Returned value
ä | U+00E4 (precomposed form, latin small letter a with diaeresis) | x'C3A4' | 1
 | U+0061 + U+0308 (canonical decomposition, latin small letter a + combining diaeresis) | x'61CC88' | 2
Parent topic: Definitions of Functions
Related reference
The UPOS Function
The USUBSTR Function
The USUPPLEMENTARY Function
The UVALID Function
The UWIDTH Function


The UPOS Function

The UPOS function returns an integer value that is equal to the index of the nth UTF-8 character in a character string argument that is encoded in UTF-8.

The function type is integer.

General Format

Arguments

argument-1
Must be alphabetic or alphanumeric, and must contain valid UTF-8 encoded characters.
argument-2
The nth UTF-8 character to locate in argument-1. argument-2 must be a positive integer and not exceed ULENGTH(argument-1), otherwise zero is returned.

Returned Value

The returned value is an integer that is equal to the index of the nth UTF-8 character (as specified by argument-2) in argument-1.

Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The USUBSTR Function
The USUPPLEMENTARY Function
The UVALID Function
The UWIDTH Function


The USUBSTR Function

The USUBSTR function returns a substring of a character string argument that is encoded in UTF-8.

The function type is alphanumeric.

General Format

Arguments

argument-1
Must be of class alphabetic or alphanumeric. argument-1 must contain valid UTF-8 encoded characters.
argument-2
Must be an integer that is greater than zero. It represents the starting position of a substring in argument-1.
argument-3
Must be an integer that is greater than or equal to zero. It represents the length of a substring in argument-1.
Note: The sum of argument-2 and argument-3 minus one must be less than or equal to ULENGTH(argument-1).

If argument-2 = 3 and argument-3 = 2, the returned value is an alphanumeric character string that contains two UTF-8 characters in argument-1, starting with the third character.

Return Value

The returned value is an alphanumeric string that is a substring of argument-1.

Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The UPOS Function
The USUPPLEMENTARY Function
The UVALID Function
The UWIDTH Function


The USUPPLEMENTARY Function

The USUPPLEMENTARY function returns an integer value that is equal to the index of the first Unicode supplementary character in a character string argument that is encoded in UTF-8 or UTF-16.

A Unicode supplementary character is a character above U+FFFF, that is, a character outside of the Basic Multilingual Plane (BMP). These characters are encoded in UTF-16 with a surrogate pair (two 16-bit code units), or are encoded in UTF-8 with a 4-byte representation.

The function type is integer.

General Format

Arguments

argument-1
Must be alphabetic, alphanumeric, or national. argument-1 must contain valid UTF-8 or UTF-16 data based on its class:
  • If argument-1 is of class alphabetic or alphanumeric, it must contain valid UTF-8 data.
  • If argument-1 is of class national, it must contain valid UTF-16 data.

Returned Value

The returned value is an integer, which differs based on the argument-1 value:

  • If the contents of argument-1 are not valid Unicode (UTF-8 or UTF-16, depending on class), the returned result is unpredictable.
  • If argument-1 contains no supplementary characters, the returned value is zero.
  • If argument-1 is of class alphabetic or alphanumeric, the returned value is the byte position of the first UTF-8 supplementary character in argument-1.
  • If argument-1 is of class national, the returned value is the index, in UTF-16 encoding units, of the first UTF-16 supplementary character in argument-1.
Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The UPOS Function
The USUBSTR Function
The UVALID Function
The UWIDTH Function


The UVALID Function

If a character string consists of valid Unicode UTF-8 or UTF-16 data, the UVALID function returns the value zero. If a character string contains invalid Unicode data, the UVALID function returns the index of the first invalid element.

The function type is integer.

General Format

Arguments

argument-1
Must be alphabetic, alphanumeric, or national.

Returned Values

The returned value is an integer, which differs based on argument-1:
  • If argument-1 is of class alphabetic or alphanumeric, and it consists of valid UTF-8 encoded Unicode data, the returned value is zero.
  • If argument-1 is of class alphabetic or alphanumeric, and it contains invalid UTF-8 encoded Unicode data, the returned value is the position of the first byte where the invalid UTF-8 data starts.
  • If argument-1 is of class national, and it consists of valid UTF-16 encoded Unicode data, the returned value is zero.
  • If argument-1 is of class national, and it contains invalid UTF-16 encoded Unicode data, the returned value is the position of the first UTF-16 encoding unit where the invalid UTF-16 data starts. This position is one plus the number of well-formed UTF-16 encoding units that precede the invalid data.
Note: The UVALID function indicates whether the character string contains well-formed Unicode UTF-8 or UTF-16 data. It does not indicate whether any or all of the Unicode code points represented by the character string are assigned to characters.
Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The UPOS Function
The USUBSTR Function
The USUPPLEMENTARY Function
The UWIDTH Function


The UWIDTH Function

The UWIDTH function returns an integer value that is equal to the width in bytes of the nth UTF-8 character in a character string argument that is encoded in UTF-8.

The function type is integer.

General Format

Arguments

argument-1
Must be alphabetic or alphanumeric, and must contain valid UTF-8 encoded characters.
argument-2
The nth UTF-8 character to locate in argument-1. argument-2 must be a positive integer and not exceed ULENGTH(argument-1), otherwise zero is returned.

Returned Value

The returned value is an integer representing the width in bytes of the nth character in argument-1.

Parent topic: Definitions of Functions
Related reference
The ULENGTH Function
The UPOS Function
The USUBSTR Function
The USUPPLEMENTARY Function
The UVALID Function


The UPPER-CASE Function

The UPPER-CASE function returns a character string that is the same length as argument-1 with each lower-case letter replaced by the corresponding upper-case letter. The type of this function depends on the argument as follows:
Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
National | National

General Format

Arguments

  1. Argument-1 must be class alphabetic, alphanumeric

    MF or national

    and must be at least one character in length.

Returned Values

  1. The same character string as argument-1 is returned, except that each lower-case letter is replaced by the corresponding upper-case letter.
  2. The character string returned has the same length as argument-1.
Parent topic: Definitions of Functions


The VARIANCE Function

The VARIANCE function returns a numeric value that approximates the variance of its arguments. The type of this function is numeric.

General Format

Arguments

  1. Argument-1 must be class numeric.

Returned Values

  1. The returned value is the approximation of the variance of the argument-1 series.
  2. The returned value is defined as the square of the standard deviation of the argument-1 series. (See the topic The STANDARD-DEVIATION Function.)
  3. If the argument-1 series consists of only one value, or if the argument-1 series consists of all variable occurrence data items and the total number of occurrences for all of them is one, the returned value is zero.
  4. Floating-point format is used for numeric non-integer results.
Parent topic: Definitions of Functions
Related information
The STANDARD-DEVIATION Function


The WHEN-COMPILED Function

The WHEN-COMPILED function returns the date and time the program was compiled. The type of this function is alphanumeric.

General Format

Returned Values

  1. The character positions returned, numbered from left to right, are:
    Character Positions | Contents
    1-4 | Four numeric digits of the year in the Gregorian calendar.
    5-6 | Two numeric digits of the month of the year, in the range 01 through 12.
    7-8 | Two numeric digits of the day of the month, in the range 01 through 31.
    9-10 | Two numeric digits of the hours past midnight, in the range 00 through 23.
    11-12 | Two numeric digits of the minutes past the hour, in the range 00 through 59.
    13-14 | Two numeric digits of the seconds past the minute, in the range 00 through 59.
    15-16 Two numeric digits of the hundredths of a second past the second, in the range 00 through 99.

    If the system does not have the facility to provide fractional parts of a second, the value 00 is returned.

    17 Either the character "-", the character " +", or the character "0". The character "-" is returned if the local time indicated in the previous character positions is behind Greenwich Mean Time. The character "+" is returned if the local time indicated is the same or ahead of Greenwich Mean Time. The character "0" is returned if the system on which this function is evaluated does not have the facility to provide the local time differential factor.

    If the system does not have the facility to provide the local time differential factor, the value 00000 is returned in character positions 17 through 21.

    18-19 | If character position 17 is "-", two numeric digits are returned in the range 00 through 12, indicating the number of hours that the reported time is behind Greenwich Mean Time. If character position 17 is "+", two numeric digits are returned in the range 00 through 13 indicating the number of hours that the reported time is ahead of Greenwich Mean Time. If character position 17 is "0", the value 00 is returned.
    20-21 Two numeric digits are returned in the range 00 through 59 indicating the number of additional minutes that the reported time is ahead of or behind Greenwich Mean Time, depending on whether character position 17 is "+" or "-" , respectively.

    If character position 17 is "0", the value 00 is returned.

  2. The returned value is the date and time of compilation of the source program that contains this function. If the program is a contained program, the returned value is the compilation date and time associated with the separately compiled program in which it is contained.
  3. The returned value denotes the same time as the compilation date and time if provided in the listing of the source program and in the generated object code for the source program, although their representations and precisions may differ.
Parent topic: Definitions of Functions


The YEAR-TO-YYYY Function

The YEAR-TO-YYYY function converts argument-1, the two low-order digits of a year, to a four-digit year. Argument-2, when added to the year at the time of execution, defines the ending year of a 100-year interval, or sliding window, into which the year of argument-1 falls. The type of this function is integer.

General Format

    FUNCTION YEAR-TO-YYYY ( argument-1 [argument-2] )

Arguments

  1. Argument-1 must be a nonnegative integer less than 100.
  2. Argument-2 must be an integer.
  3. If argument-2 is omitted, the function is evaluated as though 50 were specified.
  4. The sum of the year at the time of execution and the value of argument-2 must be less than 10,000 and greater than 1699.

Returned Values

  1. Maximum-year is calculated as follows:

    (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4)) + argument-2)

    where argument-2 of the NUMVAL function is the same as argument-2 of the YEAR-TO-YYYY function itself.

  2. The equivalent arithmetic expression is:
    1. When the following condition is true:

      FUNCTION MOD (maximum-year, 100) > = argument-1

      The equivalent arithmetic expression is:

      (argument-1 + 100 * (FUNCTION INTEGER (maximum-year/100)))

    2. Otherwise, the equivalent arithmetic expression is:

      (argument-1 + 100 * (FUNCTION INTEGER (maximum-year/100) - 1))

Notes

  1. In the year 1995, the returned value for FUNCTION YEAR-TO-YYYY (4, 23) is 2004. In the year 2008 the returned value for FUNCTION YEAR-TO-YYYY (98, (-15)) is 1898.
  2. The YEAR-TO-YYYY function implements a sliding window algorithm. To use it for a fixed window, argument-2 can be specified as follows, where fixed-maximum-year is the maximum year in the fixed 100-year interval:

    (fixed-maximum-year - FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4)))

    If the fixed window is 1973 through 2072, then in 2009 argument-2 has the value 63 and in 2019, the value 53.

Parent topic: Definitions of Functions


Statements

  • The ACCEPT Statement
    The ACCEPT statement causes data keyed at the console or supplied by the operating system to be made available to the program in a specified data item.
  • The ADD Statement
    The ADD statement causes two or more numeric operands to be summed and the result to be stored.
  • The ALLOCATE Statement
    The ALLOCATE statement allocates dynamic storage.
  • The ALTER Statement
    The ALTER statement modifies a predetermined sequence of operations.
  • The ATTACH Statement
    Attaches a delegate, a method group or an anonymous method to an event.
  • The CALL Statement
    The CALL statement causes control to be transferred to a specific program within the run unit.
  • The CANCEL Statement
    The CANCEL statement ensures that the next time the referenced program is called it is in its initial state.
  • The CHAIN Statement
    The CHAIN statement transfers control from one object program to another in the run unit with no subsequent return of control. The effect is as though the chained program is the main program in the new run unit.
  • The CLOSE Statement
    The CLOSE statement terminates the processing of reels/units and files, with optional rewind, lock or removal where applicable.
  • The COMMIT Statement
    The COMMIT statement releases all record locks in all files held by this run unit. For COBOL systems that support the WITH...ROLLBACK clause of the SELECT statement as other than documentary, COMMIT indicates the end of the current transaction and makes the effects of that transaction permanent.
  • The COMPUTE Statement
    The COMPUTE statement assigns to one or more data items the value of an arithmetic expression.
  • The CONTINUE Statement
    The CONTINUE statement is a no operation statement, indicating that no executable statement is present.
  • The CREATE Collection Statement
    Creates or constructs an instance of a list or dictionary.
  • The DECLARE Statement
    Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.
  • The DELETE Statement
    The DELETE statement logically removes a record from a mass storage file. It can be specified only for files with relative or indexed organization.
  • The DELETE FILE Statement
    The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.
  • The DETACH Statement
    Detaches a delegate or a method group from an event.
  • The DISPLAY Statement
    The DISPLAY statement causes data to be transferred from specified data items to the appropriate hardware device, such as the CRT screen.
  • The DIVIDE Statement
    The DIVIDE statement divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.
  • The ENTER Statement
    The ENTER statement provides a means of allowing the use of more than one language in the same program.
  • The ENTRY Statement
    The ENTRY statement establishes an alternate entry point into a called COBOL program.
  • The EVALUATE Statement
    The EVALUATE statement describes a multi-branch, multi-join structure. It can cause multiple conditions to be evaluated. The subsequent action of the runtime element depends on the results of these evaluations.
  • The EXAMINE Statement
    The EXAMINE statement replaces or counts the number of occurrences of a given character in a data item.
  • The EXEC(UTE) Statement
    The EXEC(UTE) statement is provided as a linkage mechanism to allow control to be passed to non-COBOL subsystems.
  • The EXHIBIT Statement
    The EXHIBIT statement causes an (optionally conditional) display of the literals, and/or identifiers (optionally preceded by the identifier name) specified in the statement.
  • The EXIT Statement
    The EXIT statement provides a common end point for a series of procedures.
  • The FREE Statement
    The FREE statement frees up dynamic storage that was previously allocated by an ALLOCATE statement.
  • The GOBACK Statement
    The GOBACK statement marks the logical end of a called program.
  • The GO TO Statement
    The GO TO statement causes control to be transferred from one part of the Procedure Division to another.
  • The IF Statement
    The IF statement causes a condition to be evaluated (see the topic Conditional Expressions in the chapter Procedure Division). The subsequent action of the runtime element depends on whether the value of the condition is true or false.
  • The INITIALIZE Statement
    The INITIALIZE statement provides the ability to set selected data items to specified values.
  • The INSPECT Statement
    The INSPECT statement provides the ability to tally (Format 1), replace (Format 2), tally and replace (Format 3) , convert (Format 4) and tally trailing (Format 5).
  • The INVOKE Statement
    The INVOKE statement causes a method to be invoked.
  • The JSON GENERATE Statement
    The JSON GENERATE statement converts data to JSON format.
  • The JSON PARSE Statement
    The JSON PARSE statement converts JSON text to COBOL data formats. It matches the JSON name/value pairs to COBOL identifiers, and then populates them.
  • The MERGE Statement
    The MERGE statement combines two or more identically sequenced files on a set of specified keys, and during the process makes records available, in merged order, to an output procedure or to an output file.
  • The MOVE Statement
    The MOVE statement transfers data, in accordance with the rules of editing, to one or more data areas.
  • The MULTIPLY Statement
    The MULTIPLY statement causes numeric data items to be multiplied and sets the values of data items equal to the results.
  • The NEXT SENTENCE Statement
    The NEXT SENTENCE statement transfers control to the next COBOL sentence, that is, following the next period. It does not transfer control to the logically next COBOL verb as occurs with the CONTINUE verb.
  • The NOTE Statement
    The NOTE statement introduces a sentence or paragraph that will be treated as comments.
  • The ON Statement
    The ON statement allows selective execution of procedural statements on a periodic basis.
  • The OPEN Statement
    The OPEN statement initiates the processing of files. It also performs checking and/or writing of labels and other input-output operations.
  • The PERFORM Statement
    The PERFORM statement is used to transfer control explicitly to one or more procedures and to return control implicitly whenever execution of the specified procedure is complete.
  • The RAISE Statement
    The RAISE statement raises an exception.
  • The READ Statement
  • The RELEASE Statement
    The RELEASE statement transfers records to the initial phase of a SORT operation.
  • The RESET Collection Statement
    Deletes all the elements from the list or dictionary.
  • The RETURN Statement
    The RETURN statement obtains either sorted records from the final phase of a SORT operation or merged records during a MERGE operation.
  • The REWRITE Statement
    The REWRITE statement logically replaces a record existing in a disk file.
  • The ROLLBACK Statement
    The ROLLBACK statement releases all record locks in all files held by this run unit.
  • The SEARCH Statement
    The SEARCH statement is used to search a table for a table element that satisfies the specified condition and to adjust the associated index-name to indicate that table element.
  • The SERVICE Statement
    The SERVICE statement is used to establish addressability to Linkage Section items.
  • The SET Statement
    The SET statement is used to alter the status of external switches.
  • The SORT Statement
    The SORT statement creates a sort file by executing input procedures or by transferring records from another file, sorts the records in the sort file on a set of specified keys, and in the final phase of the sort operation, makes available each record from the sort file, in sorted order to some output procedures or to an output file.
  • The START Statement
    The START statement provides a basis for logical positioning within a relative or indexed file for subsequent retrieval of records. This statement is not available for files with sequential organization.
  • The STOP Statement
    The STOP statement causes a permanent or temporary suspension of the execution of the run unit.
  • The STRING Statement
    The STRING statement provides concatenation of the partial or complete contents of two or more data items into a single data item.
  • The SUBTRACT Statement
    The SUBTRACT statement is used to subtract one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.
  • The SYNC Statement
    The SYNC statement marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.
  • The TRANSFORM Statement
    The TRANSFORM statement is used to alter characters according to a transformation rule.
  • The TRY Statement
    The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling. The TRY block allows you to test a section of code for exceptions that may occur during its execution. The CATCH block must specify the type of exception you wish to handle if one should occur during the execution of the TRY block. The FINALLY block allows you to execute a section of code following the TRY block, whether or not an exception occurred.
  • The UNLOCK Statement
    The UNLOCK statement releases all record locks held by the run unit on a named file.
  • The UNSTRING Statement
    The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.
  • The USE Statement
    The USE statement specifies procedures for input-output error handling, that are in addition to the standard procedures provided by the input-output control system.
  • The WAIT Statement
    The WAIT statement suspends the current thread's execution until the targeted thread's execution terminates and optionally retrieves the value returned from the targeted thread's execution.
  • The WRITE Statement
    The WRITE statement releases a logical record for an output or input-output file. For sequential files it can also be used for vertical positioning of lines within a logical page.
  • The XML GENERATE Statement
    The XML GENERATE statement converts data to XML format.
  • The XML PARSE Statement
    The XML PARSE statement is used to interface with an XML parser that is part of the COBOL run-time system. The XML PARSE statement parses an XML document into its individual pieces and passes each piece, one at a time, to a user-written processing procedure.
Parent topic: Procedure Division


ACCEPT Statement (COBOL)

The ACCEPT Statement

The ACCEPT statement causes data keyed at the console or supplied by the operating system to be made available to the program in a specified data item.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

General Formats for Format 5

General Formats for Format 6

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ACCEPTREFRESH - specifies whether the data areas associated with Screen Section data are updated from their corresponding Working-Storage Section items before an ACCEPT statement.
    • XOPEN - specifies whether the data areas associated with the Screen Section data are updated from their corresponding Working-Storage Section items before an ACCEPT statement.

Syntax Rules for Format 1

  1. The mnemonic-name in Format 1 must be associated with a function-name in the Special-Names paragraph in the Environment Division. See General Rule 14 in the topic The Special-Names Paragraph for a list of valid function-names.
  2. OSVS VSC2 MF Alternatively, function-name can itself be used instead of an associated mnemonic-name.
  3. MF XOPEN When mnemonic-name is associated with ARGUMENT-NUMBER in the Special-Names paragraph, then identifier must be an unsigned integer.
  4. MF XOPEN When mnemonic-name is associated with ARGUMENT-VALUE or ENVIRONMENT-VALUE in the Special-Names paragraph, then identifier must be an alphanumeric data item or an object of type string.
  5. VSC2 MF Identifier can be a USAGE DISPLAY-1 (DBCS) item or an external floating-point data item.

    ISO2002 MF Identifier can be an internal floating-point data item.

  6. MF XOPEN The EXCEPTION phrase may be specified only if FROM is specified with either ENVIRONMENT-NAME or ARGUMENT-VALUE, or with the mnemonic-names associated with them.

Syntax Rules for Format 2

  7. OSVS VSC2 MF Identifier can be of any class, category or usage, including an internal floating-point or external floating-point item.

Syntax Rules for Format 3

  8. MF No restrictions apply to the class, category or usage of the identifier. However, the actual value placed into the identifier and the validity of moving such values to the identifier are dependent on the FROM clause. See the Format 3 General Rules for more information.

Syntax Rules for Format 4

  9. MF Screen-name cannot be an item with an OCCURS clause.

Syntax Rules for Formats 4 and 5

  10. MF The LINE and COLUMN phrases can appear in any order.
  11. MF EXCEPTION and ESCAPE are equivalent.
  12. MF Identifier-4 must be a PIC 9(4) or a PIC 9(6) data item.

Syntax Rules for Format 5

  13. MF Identifier-8 must be an integer. It can be signed.
  14. MF Integer-7 can be signed.
  15. MF An ACCEPT statement whose operand is not a screen-name is treated as a Format 5 ACCEPT statement if it has an AT phrase, a FROM phrase with the CRT option, a WITH phrase, a MODE IS BLOCK phrase, or an EXCEPTION phrase; or if it has no FROM phrase but the CONSOLE option clause is specified in the Special-Names paragraph. If it has the FROM phrase with the CONSOLE option, or if it has no FROM phrase and the CONSOLE IS CRT clause is not specified in the Special-Names paragraph, it is treated as a Format 1 ACCEPT statement.
  16. MF The phrases following the identifier can be in any order.
  17. MF The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY, PROMPT and TRAILING-SIGN options are allowed only if the operand is an elementary item.
  18. MF Elementary data items in identifier-1 must be of USAGE DISPLAY.
  19. MF No elementary item in identifier-1 may be longer than 8191 bytes. If the MODE IS BLOCK phrase is used, the whole of identifier-1 must be no longer than 8191 bytes.

Syntax Rules for Format 6

  20. MF Identifier and env-name must be alphanumeric data items or objects of type string.

General Rules for All Formats

  1. The END-ACCEPT phrase delimits the scope of the ACCEPT statement. (See the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.) END-ACCEPT is treated as a reserved word only if the MF(4) Compiler directive is set.
  2. This phrase is not necessary unless the ACCEPT statement is specified in the conditional phrase of another statement. Even in that case, the phrase is not necessary unless this statement specifies a conditional phrase or that other statement is also an ACCEPT statement. The END-ACCEPT phrase is allowed even when not necessary.

General Rules for Format 1

  3. The ACCEPT statement causes the transfer of data from the logical or physical device. This data replaces the content of the data item referenced by identifier. If the data item referenced by identifier has an explicit or implicit usage of DISPLAY then replacement is direct and without conversion, otherwise conversion into the correct format takes place.

    The size of a data transfer is determined by the device and the run-time environment (see the topic The Special-Names Paragraph for a list of function-names that can be used and your COBOL system documentation for details of devices and the limits of data transfer sizes).

    If the device is capable of transferring data of the same size as the receiving data item, the transferred data is stored in the receiving data item. If otherwise, then:

    1. If the size of the receiving data item (or the portion not yet currently occupied by transferred data) exceeds the size of the transferred data, the transferred data is stored aligned to the left in the receiving data item (or the portion not yet occupied) and additional data is requested.
    2. If the size of the transferred data exceeds the size of the receiving data item (or portion not yet occupied by transferred data), only the leftmost characters of the transferred data are stored in the receiving data item (or in the portion remaining). The remaining characters of the transferred data which do not fit into the receiving data item are ignored.

    If the FROM option is not given, it is equivalent to specifying FROM CONSOLE.

  4. MF XOPEN If the function-name COMMAND-LINE, or a mnemonic-name associated with the function-name COMMAND-LINE, is specified, the contents of a system-dependent command-line buffer are transferred to the receiving data item.
  5. MF XOPEN If the mnemonic-name associated with the function-name ARGUMENT-NUMBER is used, identifier receives the number of arguments contained in the command line. (This includes all arguments, those before the program-name, the program-name itself, and any arguments following the program-name. Hence no portability from types of program invocation is expected.)
  6. MF XOPEN When mnemonic-name is associated with ARGUMENT-VALUE, the current command-line argument is placed into identifier. The determination of which command-line argument is current is as follows:
    1. Initially, the first command-line argument is current.
    2. A DISPLAY upon a mnemonic-name associated with ARGUMENT-NUMBER sets the current command-line argument number to the value of the identifier or literal specified in the DISPLAY statement.
    3. When an ACCEPT statement from a mnemonic-name associated with ARGUMENT-NUMBER has been executed since the last execution of a DISPLAY statement upon a mnemonic-name associated with ARGUMENT-NUMBER, the current command-line argument number is incremented prior to its use in this ACCEPT statement.

    If the current command-line argument number is 0, it is intended that the program-name of the main program of the run unit will be returned. However, the effects of variations on program invocation can impact these results so that a utility or calling program can be returned instead.

    If the current command-line argument number

    XOPEN is not in the range 0 to 99 inclusive or

    exceeds the number of arguments on the command line when this ACCEPT statement is executed, imperative-statement-1, if specified, is executed.

  7. MF XOPEN If the mnemonic-name associated with the function-name ENVIRONMENT-NAME is used then,
    1. The value returned or set in ENVIRONMENT-NAME must not exceed 255 bytes.
    2. If a previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, the value of the designated environment variable is placed into identifier.
    3. If no previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, or if the specified environment variable does not exist, the imperative statement associated with an ON EXCEPTION phrase is executed. The value in identifier is undefined in this case.
  8. MF XOPEN The effect of retrieving command-line arguments and the number of arguments in a program that is called by another program is defined as the same as if they were retrieved by the first program in the run unit.

General Rules for Format 2

  9. The ACCEPT statement causes the information requested to be transferred to the data item specified by identifier according to the rules of the MOVE statement. DATE, DAY,

    ANS85 DAY-OF-WEEK,

    and TIME are conceptual data items and, therefore, are not described in the COBOL program.

  10. DATE, without the phrase YYYYMMDD, is composed of the data elements year of the current century, month of the year, and day of the month. DATE, without the phrase YYYYMMDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display six digits in length, the character positions of which, numbered from left to right, are:
    Char | Contents
    1-2 | The two right-most numeric characters of the year in the Gregorian calendar.
    3-4 | Two numeric characters of the month of the year in the range 01 through 12.
    5-6 | Two numeric characters of the day of the month in the range 01 through 31.
  11. DATE, with the phrase YYYYMMDD, is composed of the data elements year in the Gregorian calendar, month of the year, and day of the month. DATE, with the phrase YYYYMMDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display eight digits in length, the character positions of which, numbered from left to right, are:
    Char | Contents
    1-4 | Four numeric characters of the year in the Gregorian calendar.
    5-6 | Two numeric characters of the month of the year in the range 01 through 12.
    7-8 | Two numeric characters of the day of the month in the range 01 through 31.
  12. DAY, without the phrase YYYYDDD, is composed of the data elements year of the current century and day of the year. DAY, without the phrase YYYYDDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display five digits in length, the character positions of which, numbered from left to right, are:
    Char | Contents
    1-2 | The two right-most numeric characters of the year in the Gregorian calendar.
    3-5 | Three numeric characters of the day of the year in the range 01 through 366.
  13. DAY, with the phrase YYYYDDD, is composed of the data elements year in the Gregorian calendar and day of the year. DAY, with the phrase YYYYDDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display seven digits in length, the character positions of which, numbered from left to right, are:
    Char | Contents
    1-4 | Four numeric characters of the year in the Gregorian calendar.
    5-7 | Three numeric characters of the day of the year in the range 01 through 366.
  14. ANS85 DAY-OF-WEEK is composed of a single data element whose content represents the day of the week. DAY-OF-WEEK, when accessed by a COBOL program, behaves as if it had been described in a COBOL program as an unsigned elementary numeric integer data item one digit in length. In DAY-OF-WEEK, the value 1 represents Monday, 2 represents Tuesday, ... , 7 represents Sunday.

  15. DATE-AND-TIME is made up of the data elements year, month, day, hours, minutes, seconds, and hundredths of seconds. The sequence is YYYYMMDDHHMMSShh; thus, a current date and time of July 1, 2013 at 2:41 p.m. would be expressed as 2013070114410000.

    DATE-AND-TIME, when accessed by a program, behaves as if it had been described as an unsigned elementary numeric integer data item sixteen digits in length.

  16. DAY-AND-TIME is made up of the data elements year, day, hours, minutes, seconds, and hundredths of seconds. The sequence is YYYYDDDHHMMSShh; thus, a current date and time of July 1, 2013 at 2:41 p.m. would be expressed as 201318214410000. DAY-AND-TIME, when accessed by a program, behaves as if it had been described as an unsigned elementary numeric integer data item fifteen digits in length.

  17. TIME is composed of the data elements: hours, minutes, seconds and hundredths of a second. TIME is based on elapsed time after midnight on a 24-hour clock basis - thus, 2:41 P.M. would be expressed as 14410000. TIME, when accessed by a COBOL program behaves as if it had been described in a COBOL program as an unsigned elementary numeric integer data item eight digits in length. The minimum value of TIME is 00000000; the maximum value of TIME is 23595999. If the hardware does not have the facility to provide fractional parts of TIME, the value is converted to the closest decimal approximation.

General Rules for Format 3

  18. MF The value returned from the ACCEPT FROM LINE NUMBER phrase is always numeric. The value is implementation-dependent.
  19. MF The FROM USER NAME option returns a user-id number on UNIX systems, or spaces on systems where such a concept is meaningless.
  20. MF The FROM ESCAPE KEY option returns the two-digit code generated by a termination key.

  21. The EXCEPTION STATUS item contains a three-digit numeric value that identifies the type of exception condition that has occurred during the execution of a CALL statement.

    If EXCEPTION STATUS is to be examined this should be done immediately following the CALL statement. There must be nothing between the CALL and ACCEPT FROM EXCEPTION STATUS. File I/O operations will alter the exception status value making it unpredictable.

    The possible EXCEPTION STATUS values are:
    • 000 - no exception
    • 001 - out of memory
    • 002 - program not found
    • 128 - any other failure

General Rules for Format 4

  22. MF This format of the ACCEPT statement accepts screen items, which are defined in the Screen Section of the program, and allows full access to the enhanced screen handling facilities.

General Rules for Formats 4 and 5

  23. MF The order of execution of an ACCEPT statement is always:
    1. The AT phrase
    2. The BLANK phrase
    3. If either of the Compiler directives ACCEPTREFRESH or XOPEN are specified, the current contents of screen items with the USING phrase are displayed
    4. The BELL phrase
    5. The ACCEPT operation.
  24. MF The AT phrase gives the absolute address on the screen where the ACCEPT operation is to start.
  25. MF If integer-3 or identifier-4 is 4 digits long, the first two digits specify the line, the second two the column. If 6 digits long, the first three digits specify the line, while the second three specify the column.
  26. MF Certain combinations of line and column numbers have special meanings, as follows:
    1. Until the column comes within range, out of range column values are reduced by the line length and the line value is incremented.
    2. Out of range line values cause the screen to scroll up one line. The effect is the same as if the line number of the bottom line had been specified.
    3. If the line and column numbers given are both zero, the ACCEPT starts at the position following that where the preceding Format 4 or Format 5 ACCEPT operation finished. Column 1 of each line is considered to follow the last column of the previous line.
    4. If the line number is zero, but a non-zero column number is specified, the ACCEPT starts at the specified column, on the line following that where the preceding Format 4 or Format 5 ACCEPT operation finished.
    5. If the column number is zero, but a non-zero line number is specified, the ACCEPT starts on the specified line, at the column following that where the preceding Format 4 or Format 5 ACCEPT operation finished.
  27. MF Prior to the execution of this ACCEPT statement, a DISPLAY statement which specifies the same screen-name or identifier-1 as is specified in this ACCEPT statement must have been executed. There must not have been any ACCEPT or DISPLAY statement executed since then.
  28. MF If the ON EXCEPTION phrase is specified, imperative-statement-1 is executed if the ACCEPT operation finishes with anything other than a normal termination. If the NOT ON EXCEPTION phrase is specified, imperative-statement-2 is executed if the ACCEPT operation terminates normally. (See the rules for the CRT STATUS clause in the topic The Special-Names Paragraph for possible types of termination.)

General Rules for Format 5

  29. MF The ACCEPT operation starts at line 1, column 1 if no AT phrase is specified.
  30. MF If identifier is a group item and no MODE IS BLOCK phrase exists, then those elementary subordinate items which have names other than FILLER are accepted. They are positioned on the screen in the order their descriptions appear in the Data Division and are separated by the lengths of the FILLER items in the group. For this purpose, the first position on a line is regarded as immediately following the last position on the previous line. The items are accepted in the same order.

    Unless otherwise specified in the CURSOR IS clause (see the rules for the CURSOR IS clause in the topic The Special-Names Paragraph), the cursor is initially positioned at the start of the first item. As the ACCEPT operation into each item is terminated, the cursor moves to the start of the next item.

  31. MF If identifier-1 is a group item that has a variable-occurrence data item subordinate to it, the ACCEPT statement acts as if the MODE IS BLOCK clause were specified.
  32. MF If identifier-1 is a group item that has a variable-occurrence data item subordinate to it, the ACCEPT statement acts as if the MODE IS BLOCK clause were specified.
  33. MF The MODE IS BLOCK phrase indicates that the identifier is to be treated as an elementary item. Thus, even if it is a group item it is displayed as one item.
  34. MF The effect of specifying the PROMPT option is as described in the topic The PROMPT Clause.
  35. MF If the PROMPT option is not specified, no character is output to the screen to mark empty character-positions; those character-positions into which the operator does not enter data produce spaces in the data item.
  36. MF The WITH phrase allows you to specify certain options available during the operation. (See the topic Screen Section Entry Skeleton for descriptions of these options.)

    In addition to the options available as screen description clauses, the following options can be used in the WITH phrase; SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY TRAILING-SIGN and UPDATE. ZERO-FILL appears in this list and as a screen description clause because it has two different uses. Its second use is documented later in this chapter.

    A configuration option is available which allows the entry of data into numeric and numeric edited screen fields in free format mode. In COBOL, nonedited numeric data items are intended for holding data in an internal form; however, this format enables such data items to appear on the screen. See your COBOL system documentation on user interfaces for more details. If free format mode is in effect, the data appears automatically reformatted as follows:

    • With the virtual decimal point represented by a period
    • With the sign represented by a sign character ("-" for minus; space for plus) which appears immediately before the leftmost digit
    • With zero suppression in all integer character positions, except the least significant
    • With left justification.

    The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN options amend this format.

  37. MF The SPACE-FILL option causes data in free format nonedited numeric data items to appear on the screen with zero-suppression in all integer character positions. This option affects only free format, nonedited numeric data items. This takes effect when initial data in the data item is displayed and again when the ACCEPT operation into the data item is terminated. Any leading sign is displayed in the rightmost space.
  38. MF The ZERO-FILL option causes data in free format nonedited numeric data items to appear on the screen with no zero-suppression. This takes effect when initial data in the data item is displayed and again when the ACCEPT operation into the data item is terminated. (See the topic The ZERO-FILL Clause for this option's effect when used with alphabetic or alphanumeric data items.)
  39. MF The LEFT-JUSTIFY option is documentary only.
  40. MF The RIGHT-JUSTIFY option causes operator-keyed characters to be moved on the screen to the rightmost character positions of the field. This option affects only free format nonedited numeric data items. This takes effect upon display of the initial data (the current contents displayed) in the data item and also upon termination of the ACCEPT operation.
  41. MF The TRAILING-SIGN option causes the operational sign to appear in the rightmost character position of the field. This takes effect upon display of initial data in the data item and also upon termination of the ACCEPT operation. This option affects only signed, nonedited numeric data items which are in free format mode.
  42. MF The UPDATE option causes the current contents (initial data) of the data item to be displayed before the operator is prompted to key in new input. If the operator does not key in any new data, the initial data is then treated as though it were operator-keyed. If the UPDATE option is not specified, the display of initial data is a configuration option. (See your COBOL system documentation on user interfaces for details of configuration options.)
  43. MF The UPPER option forces input into upper case.
  44. MF The LOWER option forces input into lower case.
  45. MF If REDEFINES is used with identifier-1, the first description of the redefined data area is used and subsequent descriptions are ignored. If OCCURS or nested OCCURS are used the repeated data item is expanded into the full number of times it occurs, so that one definition is repeated for many fields.
  46. MF If identifier-8 or integer-7 has a negative value, this represents a request that no time-out "exception" should occur no matter how long there is between/before key-strokes.
  47. MF If identifier-8 or integer-7 is zero, no timeout occurs if characters are waiting (when the ACCEPT is processed). However, if no characters are waiting, then a timeout occurs immediately.
  48. MF The ON EXCEPTION clause, if present, will be executed when a timeout occurs and a TIMEOUT clause is specified. The NOT ON EXCEPTION clause, if present, will be executed when a TIMEOUT clause is specified but no timeout (or other exception) occurs.
  49. MF If a timeout exception occurs, then the contents of any ACCEPT resultant-field are defined as follows:
    1. Any field which has been partially modified contains any information which has already been received.
    2. Fields which have "FULL" or "REQUIRED" attributes or any other attribute which would normally impact partial field input, are not required to meet those attributes when a partial field entry has occurred when a timeout exception occurs.
    3. The rules listed above apply whether or not the timeout clock is reset upon each keystroke.
  50. MF If at run time a positive timeout interval greater than 2,147,483,647 hundredths of a second is detected the timeout value is reset to 2,147,483,647 hundredths of a second (which is approximately eight months).
  51. MF The TIMEOUT value specifies the number of seconds (or tenths of a second) after the ACCEPT statement begins processing until a timeout exception occurs. An ADISCF configuration option controls whether or not the timeout clock is reset each time a new keyboard action is detected. An application which wants some ACCEPT statements to be handled with a RESET and some without, can make specific calls to the ADIS run-time interface before or after the ACCEPT statements that need changes from the default. For example when ADIS was configured not to do resets, if a program had:
     ACCEPT INPUT-FIELD TIME-OUT AFTER +10

    a timeout would occur after 10 seconds had elapsed from the beginning of the ACCEPT, even if some characters were entered after 5 seconds into the ACCEPT processing.

    If, on the other hand, ADIS were configured to do resets, if a program had the same code given above, then each time a new character were entered, the TIMEOUT clock would be reset to zero.

  52. MF If a timeout exception occurs and no ON EXCEPTION phrase is specified, the CRT Status keys (if specified) are updated, the application continues to the next logical phrase, and the contents of the ACCEPT receiving field are as defined above. (The above is true whether or not a NOT ON EXCEPTION phrase is specified.)
  53. MF All references to (NOT) ON EXCEPTION phrases also apply to (NOT) ON ESCAPE phrases.

General Rules for Formats 1 and 5

  54. MF For alphanumeric data items, the size of the field that is accepted from the screen during an ACCEPT statement is exactly the same size as the target field. Therefore, if you want data to appear at the right hand side of a field, you must enter it there.

General Rules for Format 6

  55. MF If the environment variable designated by env-name exists, its value is placed into the identifier, and statement-2 is executed, if specified. Otherwise the value in identifier is undefined, and statement-1 is executed, if specified.
Parent topic: Statements
Related concepts
ACCEPT FROM CENTURY-DATE and FROM CENTURY-DAY
Related reference
ACCEPT Fields at the Edge of the Screen
Display of Input Data in Concealed ACCEPT Fields
ACCEPT Statement
Related information
The Special-Names Paragraph
Explicit and Implicit Scope Terminators
The PROMPT Clause
Screen Section Entry Skeleton
The ZERO-FILL Clause


ADD Statement (COBOL)

The ADD Statement

The ADD statement causes two or more numeric operands to be summed and the result to be stored.

General Formats for Format 1

ADD - FORMAT 1

General Formats for Format 2

ADD - FORMAT 2

General Formats for Format 3

ADD - FORMAT 3

Syntax Rules for All Formats

  1. In Formats 1 and 2, each identifier must refer to an elementary numeric item, except that in Format 2 each identifier following the word GIVING must refer to either an elementary numeric item or an elementary numeric edited item. In Format 3, each identifier must refer to a group item.
  2. Each literal must be a numeric literal.
  3. The composite of operands is determined as follows (see the topic Arithmetic Statements in the chapter Procedure Division):
    1. In Format 1, by using all of the operands in a given statement.
    2. In Format 2, by using all of the operands in a given statement excluding the data items that follow the word GIVING.
    3. In Format 3, separately for each corresponding pair of data items.
  4. In Format 3, CORR is an abbreviation for CORRESPONDING.
  5. OSVS VSC2 MF Floating-point literals and floating-point data items can be used anywhere a numeric data item or literal can be specified.

General Rules for All Formats

  1. See the topics The ROUNDED Phrase, The ON SIZE ERROR Phrase, The CORRESPONDING Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results in Arithmetic Statements in the chapter Procedure Division; the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language, and the section Delimited Scope Statements in the chapter Language Fundamentals.
  2. If Format 1 is used, the values of the operands preceding the word TO are added together, then this sum is added to the current value of identifier-2 storing the result immediately into identifier-2, and repeating this process respectively for each successive operand following the word TO in left-to-right order.
  3. If Format 2 is used, the value of the operands preceding the word GIVING are added together, then the sum is stored as the new value of each data item referenced by identifier-3, the resultant identifier.
  4. If Format 3 is used, data items in identifier-1 are added to and stored in corresponding data items in identifier-2.
  5. MF Your COBOL system ensures that enough places are carried so as not to lose any significant digits during execution.
Parent topic: Statements
Related information
Arithmetic Statements
The ON SIZE ERROR Phrase
The CORRESPONDING Phrase
The ROUNDED Phrase
Overlapping Operands
Multiple Results in Arithmetic Statements
Explicit and Implicit Scope Terminators
Delimited Scope Statements


ALLOCATE Statement (COBOL)

The ALLOCATE Statement

The ALLOCATE statement allocates dynamic storage.

General Format

General Rules

  1. If data-name-1 is specified:
    • the amount of storage to be allocated is the number of bytes required to hold data-name-1. If the data description entry for data-name-1 contains a sub-ordinate item containing an OCCURS DEPENDING ON clause, the maximum length of the record is allocated.
    • the address of the data item is set to the address of the obtained storage, to the same effect as SET ADDRESS OF data-name-1 TO address.
    • the RETURNING phrase can be omitted, but if specified, data-name-2 will contain that address.
  2. If arithmetic-expression-1 CHARACTERS is specified:
    • arithmetic-expression-1 specifies the number of bytes of storage to allocate.
    • the RETURNING data-item-2 must be specified, and will be set to the address of the obtained storage.
  3. If the INITIALIZED phrase is specified, the allocated storage is initialized; If it is omitted, the contents of the allocated storage is undefined.
  4. If arithmetic-expression-1 and the INITIALIZED phrase are both specified, all storage bytes are initialized to binary zeroes.
  5. If data-name-1 and the INITIALIZED phrase are both specified, the storage is initialized to the same effect as: INITIALIZE data-name-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT.
  6. If the specified amount of storage is available for allocation:
    • If the RETURNING phrase is specified, the data item referenced by data-name-2 is set to the address of that storage.
    • If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data item referenced by data-name-1 is set to the address of that storage, to the same effect as: SET ADDRESS OF data-name-1 TO address-of-obtained-storage.
  7. If the specified amount of storage is not available for allocation:
    • If the RETURNING phrase is specified, the data item referenced by data-name-2 is set to the predefined address NULL.
    • If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data item referenced by data-name-1 is set to the predefined address NULL.
  8. The allocated storage persists until explicitly released using the FREE statement or the run unit is terminated, whichever occurs first.

Syntax Rules

  1. data-name-1 must be a level-01 or level-77 item defined in the Linkage Section.
  2. data-name-1 must not be:
    • reference modified.
    • a group item that contains an unbounded table.
  3. data-name-2 must be defined as USAGE IS POINTER.
  4. data-name-2 can be qualified or subscripted.
  5. If arithmetic-expression-1 does not equate to an integer, the result is rounded up to the next whole number.
  6. If arithmetic-expression-1 equates to zero or a negative value, data-name-2 is set to the predefined address NULL.
Parent topic: Statements
Related reference
The FREE Statement


ALTER Statement (COBOL)

The ALTER Statement

The ALTER statement modifies a predetermined sequence of operations.

ANS85 The ALTER statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this verb is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

ALTER Statement (COBOL)

Syntax Rules

  1. Each procedure-name-1, procedure-name-3, ..., is the name of a paragraph that contains a single sentence consisting of a GO TO statement without the DEPENDING phrase.
  2. Each procedure-name-2, procedure-name-4, ..., is the name of a paragraph or section in the Procedure Division.
  3. The ALTER statement is not supported in class programs when compiling to managed code.

General Rules

  1. Execution of the ALTER statement modifies the GO TO statement in the paragraph named procedure-name-1, procedure-name-3, ..., so that subsequent executions of the modified GO TO statements cause transfer of control to procedure-name-2, procedure-name-4, ..., respectively. Modified GO TO statements in independent segments can, under some circumstances, be returned to their initial states (see the section Independent Segments in the topic Segmentation.
  2. A GO TO statement in a section whose segment-number is greater than or equal to 50 must not be referred to by an ALTER statement in a section with a different segment-number.

    All other uses of the ALTER statement are valid and are performed even if procedure-name-1, procedure-name-3 is in an overlayable fixed segment.

Parent topic: Statements
Related information
Independent Segments


ATTACH Statement (COBOL)

The ATTACH Statement

Attaches a delegate, a method group or an anonymous method to an event.

General Formats

Syntax Rules

  1. some rule

General Rules

  1. some rule
Parent topic: Statements


CALL Statement (COBOL)

The CALL Statement

The CALL statement causes control to be transferred to a specific program within the run unit.

ISO2002 MF You can call the program indirectly, by address. Data, pointers to data, and pointers to procedures can be passed as parameters to the called program, and returned by it. Parameter passing conventions can be controlled in order to allow the called program to be written in languages other than COBOL, using different conventions.

ISO2002 MF OS390 A called COBOL program can recursively call itself when it has the recursive attribute.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • ALIGN - specifies the memory boundaries on which data items of 01-level or 77-level are aligned.
    • CASE - determines whether upper-case and lower-case letters are considered equivalent.
    • DEFAULTCALLS - controls which calling convention is the default.
    • FOLD-CALL-NAME - determines whether you are guaranteed to find a called subprogram when the calling and called programs do not use the same upper-case and lower-case letters for the program-name.
    • IBMCOMP - turns on word-storage mode.
    • MAPNAME - impacts the handling of non-alphabetic characters in the program-name.

Syntax Rules

  1. * Identifier-1 must be defined as an alphanumeric

    ISO2002 MF or national

    data item.

  2. * Literal-1

    cannot be a figurative constant and must be an alphanumeric literal

    ISO2002 MF or a national literal.

  3. MF * Literal-3

    VSC2 MF , literal-4

    VSC2 MF , and literal-5

    cannot be a figurative constant.

  4. * Identifier-2, identifier-3, identifier-4 and identifier-6 must be defined as data items in the File Section, Working-Storage Section,

    ISO2002 MF Local-Storage Section

    or Linkage Section, and must be a level 01 data item, or a level 77 data item

    ANS85 , or an elementary item

    ISO2002 MF , or any group item.

    MF Identifier-2, identifier-3, identifier-4 must not be defined in the Working-Storage or File Section of a factory or an instance object.

  5. MF * Neither identifier-7, identifier-8, identifier-9, nor identifier-10 can be a function-identifier.
  6. MF * GIVING and RETURNING are equivalent.
  7. MF Identifier-11 must be defined as a data item in the Linkage Section with a level number of 01 or 77.
  8. MF *Identifier-2, identifier-3, identifier-4, identifier-6, identifier-8 and identifier-10 must not be described with the ANY LENGTH clause.
  9. Arithmetic-expression-2, Literal-5, or Identifier-8 must not be defined as or contain COMP-1 or COMP-2 items; in native COBOL, you cannot pass a floating point item by VALUE.
  10. MF USING and GIVING/RETURNING can be used in either order.
  11. For native COBOL, alphanumeric and national literals must be less than eight characters in length in the BY VALUE phrase. Numeric literals are passed as the 32-bit comp-x value; the sign bit can be interpreted as such if the called program describes a signed item; otherwise, a negative literal causes a large positive value to be generated in the comp-x item. The decimal point in the literal, if any, is ignored when the value of the comp-x item is created.
  12. MF Mnemonic-name is necessary only if the object program that is to be invoked expects a calling convention other than that used as the default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant implementation of a non-COBOL language for the run-time environment.

    Mnemonic-name must be defined in the Special-Names paragraph. See the topic The Special-Names Paragraph for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run-time environment.

  13. VSC2 MF * Identifier-2, identifier-3, identifier-5 must be defined as a data item in the Linkage Section

    MF , Local-Storage Section or Working-Storage Section,

    and must be a level 01 data item, a level 77 data item

    MF , or other level data item.

  14. MF If the CALL statement specifies literal-1 (but not if it specifies identifier-1 or procedure-pointer-1), and if a call prototype (a program with the EXTERNAL clause in its Program-ID paragraph) has been included in the current compilation unit with a name that matches literal-1, then the following items are validated during syntax checking:
    • The number of parameters required
    • The type of parameters
    • The call convention
  15. ISO2002 * Identifier-2, identifier-3, identifier-4 must not be a data item of class object or pointer.

General Rules

General rules marked with an asterisk (*) are common to the CALL statement and to the CHAIN statement. In these rules, where "CALL or CHAIN statement" are specified, you should read "CALL statement" or "CHAIN statement" when applying the rules to the CALL statement or the CHAIN statement respectively.

  1. Literal-1 or the content of the data item referenced by identifier-1 is the name of the called program

    MF or called procedure.

    The program in which the CALL statement appears is the calling program. If the program being called is a COBOL program, literal-1 or the content of the data item referenced by identifier-1 must contain the program-name contained in the Program-ID paragraph of the called program (see the topic The Program-ID Paragraph, particularly in regard to case sensitivity),

    MF or the entry-name contained in the ENTRY statement of a called program that must have been called previously and not canceled since. Alternatively, the name of the called program may be a name which identifies a file that contains executable program code for the called program. The result of specifying different names that identify the same file in two CALL statements or a CALL and a CANCEL statement are operating-system specific. See your COBOL system documentation for details of how your system matches the given name to previously called programs, program filenames or programs held in library files.

    MF If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in the COBOL system documentation on interfacing.

  2. MF The content of the data item referenced by procedure-pointer-1 is the address of the called program that must be already resident in memory. If the program being called is a COBOL program, the address of the called program must originally have been derived from a SET statement with an ENTRY phrase and no CANCEL statement for that program must have been subsequently executed. If the program being called is not a COBOL program then the address of the called program must originally have been derived from a CALL to a non-COBOL program or procedure. It is an error to attempt to CALL a program with an address that is equal to NULL.
  3. If, when a CALL statement is executed, the program specified by the CALL statement is made available for execution, control is transferred to the called program. After control is returned from the called program, the ON OVERFLOW

    ANS85 or ON EXCEPTION

    phrase is ignored and control is passed to the end of the CALL statement

    ANS85 or, if the NOT ON EXCEPTION phrase is specified control is passed to imperative-statement-2. If control is passed to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the CALL statement.

  4. When a CALL statement is executed, the program specified by the CALL statement is made available if it is already resident in memory. If it is not already resident in memory then an attempt may be made to dynamically load the program (see your COBOL system documentation on interfacing). If a program with the specified name can be dynamically located and a sufficient, contiguous area of free memory is available, then the program is dynamically loaded and made available for execution.

    If the program specified by the CALL is not resident in memory, is not available for dynamic loading or is available but is too large for the available memory, then the program cannot be made available at that time and one of the following two actions occurs:

    1. If the ON OVERFLOW

      ANS85 or ON EXCEPTION

      phrase is specified in the CALL statement, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of execution of imperative-statement-1, control is transferred to the end of the CALL statement

      ANS85 and the NOT ON EXCEPTION phrase, if specified, is ignored.

    2. ANS85 If the ON OVERFLOW or ON EXCEPTION phrase is not specified in the CALL statement, the NOT ON EXCEPTION phrase, if specified, is ignored.

      MF Program execution stops, without an implicit CLOSE statement for any file that is in open mode in the run unit, and a run time error is displayed.

  5. ANS85 Two or more COBOL programs in the run unit can have the same program-name, and the reference in a CALL statement to such a program-name is resolved by using the scope-of-names conventions for program-names. See the topic Conventions for Program-names in the chapter Concepts of the COBOL Language. For example, when two programs in the run unit have the same name as that specified in a CALL statement:
    1. One of those two programs must also be contained directly or indirectly either within the separate program which includes the CALL statement or within the separate program which itself directly or indirectly contains the program which includes that CALL statement, and
    2. The other one of those two programs must be a different separate program.

    The mechanism used in this example is as follows:

    1. If one of the two programs having the same name as that specified in the CALL statement is directly contained within the program which includes that CALL statement, that program is called.
    2. If one of the two programs having the same name as that specified in the CALL statement possesses the common attribute and is directly contained within another program which directly or indirectly contains the program which includes the CALL statement, that common program is called unless the calling program is contained in that common program.
    3. Otherwise, the separate program is called.
  6. If the called program is a COBOL program and does not possess the initial attribute, it and each COBOL program directly or indirectly contained within it, is in its initial state the first time it is called within a run unit and the first time it is called after a CANCEL of the called program.

    If the called program is not COBOL, it is only in its initial state the first time it is called within a run unit. A CANCEL of such a program has no effect.

    On all other entries into the called program, the state of the program and each program directly or indirectly contained within it remains unchanged from its state when last exited. Some implementations of languages other than COBOL may provide alternative semantics and, if available, these are detailed in your COBOL system documentation on interfacing.

  7. ANS85 If the called program possesses the intial attribute, it and each program directly or indirectly contained within it, is placed into its initial state every time the called program is called in a run unit. Whether a called program is in the initial state or last-used state is sensitive to the DYNAM Compiler directive.
  8. ANS85 Files associated with a called program's internal file connectors are not in the open mode when the program is in an initial state. See the topicIntial State Of A Program earlier in this chapter. On all other entries into the called program, the states and positioning of all such files are the same as when the called program was last exited.
  9. ANS85 The process of calling a program or exiting from a called program does not alter the status or positioning of a file associated with any external file connector.
  10. If the program being called is a COBOL program, the USING phrase is included in the CALL statement only if there is a USING phrase in the PROCEDURE DIVISION header

    OSVS VSC2 MF or ENTRY statement

    of the called program, in which case the number of operands in each USING phrase must be identical.

    MF The number of operands need not be identical.

  11. MF If the program being called is not a COBOL program, the USING phrase is included in the CALL statement only if one or more parameters are declared for the called program, in which case the number of operands in the USING phrase must be identical to the number of parameters in the called program. (Some implementations of languages other than COBOL may allow the number of operands to be other than identical.) The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:
    • Modifying group items to include additional filler items
    • Ensuring operands in the USING phrase are level 01 or level 77 data items in conjunction with the ALIGN Compiler directive or
    • Use of the SYNCHRONIZED clause in conjunction with the IBMCOMP Compiler directive.
  12. * The sequence of appearance of the operands in the USING phrase of the CALL

    MF or CHAIN

    statement and in the corresponding USING phrase in the called program's PROCEDURE DIVISION header

    MF or ENTRY statement or parameter list if the called program is not COBOL

    determines the correspondence between the data names used by the calling and called programs. This correspondence is positional and not by name equivalence; the first operand in the CALL

    MF or CHAIN

    statement's USING phrase corresponds to the first operand in the called program's USING phrase or parameter list, the second to the second, etc.

    MF If the correspondence cannot be completed because the numbers of operands are different, then if the remaining unmatched operands are in the CALL or CHAIN statement they are ignored and if they are in the PROCEDURE DIVISION header or ENTRY statement or parameter list then they must not be referenced within the called program. The positional correspondence may vary depending on the calling conventions implied by mnemonic-name.

    In the case of index-name, no such correspondence is established. Index-names in the called and calling programs always refer to separate indices.

  13. ANS85 * The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called program at the time the CALL statement is executed.
  14. * If the BY REFERENCE identifier-4 phrase is

    ANS85 either specified or

    implied for a parameter, the program operates as if the corresponding data item in the called program occupies the same storage area as the data item in the calling program. The description of the data item in the called program must describe the same number of character positions as described by the description of the corresponding data item in the calling program.

    VSC2 MF If the BY REFERENCE ADDRESS OF phrase is specified or implied then the program operates as if an additional data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-3 and identifier-5 statement.

    VSC2 MF If identifier-3 and identifier-5 are in the Linkage Section and have a level number other than 01 or 77 or is in the Working-Storage Section, this is equivalent to passing the item BY CONTENT; the address of identifier-3 or identifier-5 cannot be modified by the called subprogram.

    MF If the BY REFERENCE literal-3 phrase is specified or implied then the object program processes literal-3 as described for literal-4.

  15. MF XOPEN * If the BY CONTENT phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase, though the called program can change the value of the data item referenced by the corresponding data-name in the called program's PROCEDURE DIVISION header. The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the PROCEDURE DIVISION header.

    MF If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-6 is specified, then both the implied data description of the additional data item and its contents are identical to that of identifier-6. If literal-4 is specified, then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-4 and with its contents set to the value of literal-4. If LENGTH OF identifier-7 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE BINARY, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-7.

  16. MF COB370 *If the BY VALUE phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase, though the called program can change the value of the data item referenced by the corresponding data-name in the called program's PROCEDURE DIVISION header. The object program operates, conceptually, as if an additional data item had been declared in a system area (typically the stack), available to non-COBOL languages for passing parameters and that this additional data item occupies the same storage area as the data item in the called program.

    If identifier-8 is specified and is BINARY, COMP-4, COMP-5 or COMP-X, then the data description of the additional data item is identical to that of identifier-8, except its usage is COMP-5. The contents of the additional data item are identical to the COMP-5 representation of the contents of identifier-8. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-8 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-8.

    If literal-5 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE BINARY that occupies the number of bytes of storage indicated by the value of integer-1, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).

    If LENGTH OF identifier-9 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-9.

    If the program being called is a COBOL program, each parameter in the BY VALUE phrase of the CALL statement must have a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    The additional data item generated as a result of the CALL statement, described above, is related to this corresponding parameter in the called program, as follows.

    If the additional data item was subject to conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the corresponding parameter in the called program must be identical to that of the data description of the additional data item with the exception that the corresponding parameter's USAGE can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the called COBOL program, a conversion from the USAGE COMP-5 of the additional data item to the USAGE of the corresponding parameter in the called program is performed.

    If the additional data item was not subject to conversion to COMP-5, the data description of each parameter in the called program must be the same as the corresponding additional data item. This means there is no conversion or extension or truncation, of the additional data item to match the corresponding parameter in the called program.

    If the program being called is not COBOL, the size of the additional data item should not exceed the maximum size of the system area (typically the size of a POINTER on the system); otherwise the system might become catastrophically corrupt.

  17. MF A called program can pass data to the calling program either by using a parameter declared in the USING phrase of the calling program or by means of a returned value. A called program returns a value by means of an EXIT GIVING or GOBACK GIVING statement. As control is returned from the called program to the calling program, the returned value is held in a system area generally available for non-COBOL programs to return a value.

    The size of the system area (typically the size of a POINTER on the system) is determined outside the COBOL system and limits the maximum value the return value can take, but the return value might not utilize the full size of the system area. The returned value is available to the calling program after control is returned, either implicitly in the special register RETURN-CODE or explicitly in the data item specified in the GIVING phrase.

  18. MF If the GIVING phrase is not specified and the calling convention specifies updating the RETURN-CODE special register (see the topic The Special-Names Paragraph) then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and the same size as the system area and as if a MOVE statement had been executed with the system area as the sending item and the RETURN-CODE special register as the receiving item.
  19. MF If the GIVING INTO phrase is specified in the calling program, identifier-10 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is implied for the returned value by the manner in which the value was returned from the called program. When control returns to the calling program, identifier-10 contains the return value.
  20. MF If the GIVING ADDRESS OF phrase is specified in the calling program, the called program must return a value with explicit or implicit USAGE POINTER. The object program operates as if the system area were declared as a COBOL data item with USAGE POINTER and as if a SET statement had been executed with the system area as the first operand and TO ADDRESS OF identifier-11 as the second operand.
  21. MF It is an error to specify the GIVING phrase for a called program that does not return a value.
  22. Called programs can contain CALL statements. However, a called program may not execute a CALL that directly or indirectly calls the calling program,

    ISO2002 MF OS390 unless that calling program has the recursive attribute.

  23. If a CALL statement is executed within the range of a declarative, that CALL statement cannot directly or indirectly reference any called program to which control has been transferred and which has not completed execution.
  24. ANS85 The END-CALL phrase delimits the scope of the CALL statement.
  25. VSC2 MF Any values with implicit or explicit USAGE POINTER

    MF or USAGE PROCEDURE-POINTER

    that were originally derived from the address of a data item

    MF or procedure

    that is contained within a called program become invalid and must not be used after a CANCEL statement that references that called program is executed.

  26. MF The OMITTED phrase is used to pass unused parameters to a subprogram without having to declare a dummy data item.
  27. MF The OMITTED parameter is a BY REFERENCE parameter, equivalent to passing a null address to the calling subprogram. It is identical to BY VALUE 0 but is subject to the type checking of call prototypes as a BY REFERENCE parameter.
  28. MF If BY REFERENCE does not immediately precede OMITTED, subsequent parameters are passed by the convention previously in force and the omitted parameter is treated as if the program had specified BY VALUE 0.
  29. A numeric literal-3 or literal- is passed as an integer 32-bit comp-x item if it is not negative or as an integer 32-bit comp (binary) item if it is negative, even if the literal is not an integer. A decimal point in the numeric literal is ignored.
  30. MF Mnemonic-name identifies the calling convention that this program uses when invoking the called program. If the calling convention assumed by the called program is different to that implied by mnemonic-name, then the COBOL system may become corrupt.
  31. MF The run unit remains unaware of whether a called program is a COBOL program or a non-COBOL program or procedure until the called program has been located, prior to being made available for execution. The form of the program-name cannot be used, in general, to determine whether the program is a COBOL program or not. It is an error for a COBOL program and a non-COBOL program or for two non-COBOL programs to have the same program-name.
  32. ANS85 * The BY CONTENT, BY REFERENCE

    MF COB370 and BY VALUE

    phrases are transitive across the parameters which follow them until another BY CONTENT, BY REFERENCE

    MF COB370 or BY VALUE

    phrase is encountered.

    If no BY CONTENT, BY REFERENCE

    MF COB370 or BY VALUE

    phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

Example

  1. An example of using procedure-pointer in a CALL statement is provided in section Calling and Setting a Procedure-Pointer.
Parent topic: Statements
Related concepts
C$DARG
C$NARG
Related information
The Special-Names Paragraph
Conventions for Program-names
Conformance for Parameters and Returning Items
The Program-ID Paragraph
The Repository Paragraph
The Omitted-argument Condition
Calling and Setting a Procedure-Pointer


CANCEL Statement (COBOL)

The CANCEL Statement

The CANCEL statement ensures that the next time the referenced program is called it is in its initial state.

General Format

Directives:

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • DYNAM - NODYNAM causes CANCEL statements to be ignored.

Syntax Rules

  1. Literal-1 must be a nonnumeric literal.
  2. Identifier-1 must reference an alphanumeric data item.

General Rules

  1. Literal-1 or the content of the data item referenced by identifier-1 identifies the name of the program to be canceled. The name must contain the program-name contained in the Program-ID paragraph of the program to be canceled (see the section The Program-ID Paragraph in the chapter Identification Division, particularly in regard to case sensitivity). Alternatively, the name may identify a file that contains executable program code for the program to be canceled. The results of specifying different names that identify the same file in a CANCEL statement are operating-system specific. See your COBOL system documentation for details of how your system matches the given name to previously called programs, program filenames or programs held in library files.

    If the name contains the entry-name contained in an ENTRY statement, the results are undefined.

  2. Subsequent to the execution of an explicit or implicit CANCEL statement, the program referred to therein ceases to have any logical relationship to the run unit in which the CANCEL statement appears. If the program referenced by a successfully executed explicit or implicit CANCEL statement in a run unit is subsequently called in that run unit, that program is in its initial state. See the topic State of a Function, Method or Program in the chapter Language Fundamentals.
  3. A program named in a CANCEL statement in another program must be callable by that other program. See the topic Scope of Names in the chapter Concepts of the COBOL Language and the section The CALL Statement.
  4. ANS85 When an explicit or implicit CANCEL statement is executed, all programs contained in the program referenced by the CANCEL statement are also canceled. The result is the same as if a valid CANCEL statement were executed for each contained program in the reverse order in which the programs appear in the separate program.
  5. A program named in the CANCEL statement must not refer directly or indirectly to any program that has been called and has not yet executed an EXIT PROGRAM

    OSVS VSC2 MF or GOBACK

    statement.

  6. A logical relationship to a canceled program is established only by execution of a subsequent CALL statement naming that program.
  7. A called program is canceled either by being referred to as the operand of a CANCEL statement, by the termination of the run unit of which the program is a member,

    ANS85 or by execution of an EXIT PROGRAM statement in a called program that possesses the initial attribute.

  8. No action is taken when an explicit or implicit CANCEL statement is executed naming a program that has not been called in this run unit, has been called and is at present canceled or is a non-COBOL program. Control is transferred to the next executable statement following the CANCEL statement.
  9. ANS85 The contents of data items in external data records described by a program are not changed when that program is canceled.
  10. ANS85 During execution of an explicit or implicit CANCEL statement, an implicit CLOSE statement without any optional phrases is executed for each file in the open mode that is associated with an internal file connector in the program named in the CANCEL statement. Any USE procedures associated with any of these files are not executed.
  11. The CANCEL statement determines whether or not a subprogram is re-entered in initial or last-used state. It does not necessarily free any memory used by the subprogram. However, in many operating systems, if the subprogram has been dynamically loaded, this statement also frees the memory originally used by the subprogram. EXTERNAL files and data areas of the subprogram are never freed by a CANCEL statement.
Parent topic: Statements
Related information
The Program-ID Paragraph
State of a Function, Method or Program
Scope of Names
The CALL Statement


CHAIN Statement (COBOL)

The CHAIN Statement

The CHAIN statement transfers control from one object program to another in the run unit with no subsequent return of control. The effect is as though the chained program is the main program in the new run unit.

General Format

Syntax Rules

  1. The syntax of the CHAIN statement is similar to the syntax of the CALL statement and the two are subject to common syntax rules as indicated in the topic The CALL Statement. All the identifiers, literals and integers in the general format of the CHAIN statement correspond to the identifiers, literals and integers of the CALL statement.

General Rules

  1. Literal-1 or the content of the data item referenced by identifier-1 is the name of the chained program. The program in which the CHAIN statement appears is the chaining program.

    The chained program must be a COBOL program that is not a nested program. The name of the chained program must contain the name contained in the Program-ID paragraph of the chained program (seethe section The Program-ID Paragraph, particularly in regard to case sensitivity). Alternatively, the name of the chained program may contain a name which identifies a file that contains executable program code for the chained program. See your COBOL system documentation for details of how your system matches the given name to previously chained programs, program filenames or programs held in library files.

  2. If, when a CHAIN statement is executed, the program specified by the CHAIN statement is made available for execution, control is transferred to the chained program, and the chaining program, and any COBOL programs called by the chaining program, are canceled. The chained program is not under the control of a chaining program and so any EXIT PROGRAM executed within the chained program has no effect.
  3. If, when a CHAIN statement is executed, the program specified by the CHAIN statement is not made available for execution, one of the following actions occur:
    • If either of the ON EXCEPTION or ON OVERFLOW phrases are specified, control is transferred to imperative-statement-1 or imperative-statement-2. Execution then continues according to the rules of the statement. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of execution of the imperative statement, control is transferred to the end of the CHAIN statement.
    • If the ON EXCEPTION or ON OVERFLOW phrase is not specified, a fatal runtime error is given.
  4. Chained programs can contain CHAIN statements. A CHAIN statement within a chained program may reference any program except itself.
  5. The form of the CHAIN statement is similar to the form of the CALL statement and the two are subject to common general rules as indicated in the topic The CALL Statement. All the identifiers, literals and integers in the general format of the CHAIN statement correspond to the identifiers, literals and integers of the CALL statement. Also, where the expressions calling program and called program are used, these can be considered equivalent to the expressions chaining program and chained program.
  6. The chain operation moves the value from each data item referenced in the USING phrase of the CHAIN statement to the data item referenced by the corresponding data-name in the USING phrase of the PROCEDURE DIVISION header of the chained program.
  7. The value of any data item with USAGE POINTER or USAGE PROCEDURE-POINTER that is passed as an operand in the USING phrase must not represent the address that was originally derived from a COBOL data item.
  8. The END-CHAIN phrase delimits the scope of the CHAIN statement.
Parent topic: Statements
Related information
The CALL Statement
The Program-ID Paragraph


CLOSE Statement (COBOL)

The CLOSE Statement

The CLOSE statement terminates the processing of reels/units and files, with optional rewind, lock or removal where applicable.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 ( MF Line Sequential, Relative and Indexed Files)

Syntax Rules for All Formats (All Files)

  1. The files referenced in the CLOSE statement need not all have the same organization or access.

Syntax Rules for Format 1 (Record Sequential Files)

  2. MF The REEL and UNIT phrases should be specified only for files which have had MULTIPLE REEL or MULTIPLE UNIT specified in their SELECT clause. If your run-time system does not recognize multi-unit files, the statements CLOSE REEL and CLOSE UNIT are "null" statements; that is, they are documentary only. It is important that no other files are open on the device(s) closed by a CLOSE REEL or CLOSE UNIT statement.

    OSVS The statements CLOSE REEL WITH LOCK and CLOSE UNIT WITH LOCK are treated as equivalent to CLOSE REEL FOR REMOVAL.

  3. OSVS The DISP option is applicable only to tape files.

    It is documentary only.

General Rules for All Formats (All Files)

  1. A CLOSE statement can be executed only for a file in an open mode.
  2. Following the successful execution of a CLOSE statement the record area associated with file-name-1 is no longer available. The unsuccessful execution of such a CLOSE statement leaves the availability of the record area undefined.
  3. ANS85 If a file is in the open mode when a STOP RUN statement is executed, the fileis closed. If a file has been opened in a called program and not closed in that program prior to the execution of a CANCEL statement for the program, that file is closed.
  4. MF Following the successful execution of a CLOSE statement, all record or file locks held by the run unit on the closed file are released.
  5. The execution of the CLOSE statement causes the value of the I/O status associated with file-name-1 to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  6. The results of executing each type of CLOSE statement for each category of file are summarized in the table below.
    Table 1. Relationship of Categories of Files and the Formats of the CLOSE Statement
    CLOSE Statement Format | File Category
    Non-Reel/Unit | Record Sequential Single-Reel/Unit | Record Sequential Multi-Reel/Unit | Non-record Sequential Single/ Multi-Reel/Unit
    CLOSE | C | C, G | A, C, G | C
    CLOSE WITH LOCK | C, E | C, E, G | A, C, E, G | C, E
    CLOSE WITH NO REWIND record sequential only | ANS85 C, H | B, C | A, B, C | X
    CLOSE REEL/UNIT record sequential only | ANS85 F | ANS85 F, G | F, G | X
    CLOSE REEL/UNIT FOR REMOVAL record sequential only | ANS85 F | ANS85 D, F, G | D, F , G | X
    CLOSE REEL/UNIT WITH NO REWIND record sequential only | X | X | F, B | X

    The definitions of the symbols in the table are given below. Where the definition depends on whether the file is an input, output or input-output file, alternate definitions are given; otherwise, a definition applies to input, output, and input-output files.

    A. Previous Reels/Units Unaffected
    • Input Files and Input-output Files:

      All reels/units in the file prior to the current reel/unit are processed except those reels/units controlled by a prior CLOSE REEL/UNIT statement. If the current reel/unit is not the last in the file, the reels/units in the file following the current one are not processed.

    • Output Files:

      All reels/units in the file prior to the current reel/unit are processed except those reels/units controlled by a prior CLOSE REEL/UNIT statement.

    B. No Rewind of Current Reel

    The current reel/unit is left in its current position.

    C. Close File
    • Input Files and Input-output Files (Sequential Access Mode):

      If the file is at the end and label records are specified for the file, the labels are processed according to the operating system label convention. The behavior of the CLOSE statement when label records are specified but not present, or when label records are not specified but are present, is undefined. If the file is at the end and label records are not specified for the file, label processing does not take place, but other closing operations dependent on the run-time system are executed. If the file is not at the end, the closing operations dependent on the run-time system are executed, but there is no ending label processing.

    • Input Files and Input-output Files (Random or Dynamic Access Mode); Output Files (Random, Dynamic or Sequential Access Mode):

      If label records are specified for the file, the labels are processed according to the operating system standard label convention. The behavior of the CLOSE statement when label records are specified but not present, or when label records are not specified but are present, is undefined. If label records are not specified for the file, label processing does not take place, but other closing operations dependent on the run-time system are executed.

    D. Reel/Unit Removal

    The reel or unit can be accessed again, in the proper order of reels or units in the file, if a CLOSE statement without the REEL or UNIT phrase has previously been executed for this file followed by the execution of an OPEN statement for the file.

    E. File Lock

    This file cannot be opened again during this execution of this run unit.

    F. Close Reel/Unit
    • Input Files and Input-output Files (Reel/Unit Media):
      1. ANS85 If the current reel/unit is the last or only reel/unit for the file, no reel/unit swap takes place; the current volume pointer remains unchanged, and the file position indicator is set to indicate that no next reel/unit exists.
      2. If another reel/unit exists for the file, a reel/unit swap occurs, the current volume pointer is updated to point to the next reel/unit existing in the file, the standard beginning reel/unit label procedure is executed, and the file position indicator is set to one less than the number of the first record existing on the new current volume. If no data records exist for the current volume, another reel/unit swap occurs.
    • Output Files (Reel/Unit Media):

      The following operations take place:

      1. Execution of the standard ending reel/unit label procedure.
      2. A reel/unit swap.
      3. Execution of the standard beginning reel/unit label procedure.
      4. The next executed WRITE statement that references that file directs the next logical data record to the next reel/unit of the file.
    • Input Files, Input-output Files, and Output Files (Non-Reel/Unit Media):

      ANS85 Execution of this statement is considered successful. The file remains in the open mode, the file position indicator remains unchanged, and no action takes place except as specified in General Rule 4.

    G. Rewind

    The current reel or analogous device is positioned at its physical beginning.

    H. Optional Phrases Ignored

    ANS85 The CLOSE statement is executed as if none of the optional phrases is present.

    X. Illegal

    This is an illegal combination of a CLOSE option and a file category. The results at object time are undefined.

General Rules for Format 1 (Record SequentialFiles)

Note: Except where otherwise stated in the general rules below, the terms "reel" and "unit" are equivalent and completely interchangeable in the CLOSE statement. Treatment of sequential mass storage files is logically equivalent to the treatment of a file on tape or analogous sequential media.

General Rules for All Formats (All Files)

  7. In order to show the effect of various types of CLOSE statements as applied to various storage media, all files are divided into the following categories:
    1. Non-reel/unit. A file whose input or output medium is such that the concepts of rewind and reels/units have no meaning.
    2. Sequential single-reel/unit. A sequential file that is entirely contained on one reel/unit.
    3. Sequential multi-reel/unit. A sequential file that is contained on more than one reel/unit.
  8. If the OPTIONAL phrase has been specified for the file in the File-Control paragraph of the Environment Division and the file is not present, the standard end-of-file processing is not performed for that file.
  9. If a CLOSE statement without the REEL or UNIT phrase has been executed for a file, no other statement (except the SORT or MERGE statements with the USING or GIVING phrases) can be executed that references that file, either explicitly or implicitly, unless an intervening OPEN statement for that file is executed.
  10. The WITH NO REWIND and FOR REMOVAL phrases have no effect at object time if they do not apply to the storage media on which the file resides.
  11. If WITH LOCK is specified, the file cannot be reopened during the current execution of the run unit. Otherwise a normal CLOSE takes effect.

    MF (This option has no connection with the record or file locking used when sharing files.)

General Rules for All Formats (All Files)

  12. If a CLOSE statement has been executed for a file, no statement

    MF other than a DELETE FILE statement

    can be executed that references that file, either explicitly or implicitly, unless an intervening OPEN statement for that file is executed.

  13. If WITH LOCK is specified, the file cannot be reopened during the current execution of the run unit.
Parent topic: Statements
Related information
I-O Status


COMMIT Statement (COBOL)

The COMMIT Statement

The COMMIT statement releases all record locks in all files held by this run unit. For COBOL systems that support the WITH...ROLLBACK clause of the SELECT statement as other than documentary, COMMIT indicates the end of the current transaction and makes the effects of that transaction permanent.

General Format

General Rules

  1. Execution of the COMMIT statement causes all record locks in all files held by the run unit to be released.
  2. The file lock on an exclusive file is not affected by the COMMIT statement.
  3. If your COBOL system supports the WITH ... ROLLBACK clause of the SELECT statement as other than documentary, then the COMMIT verb:
    1. Indicates completion of the current transaction
    2. Makes all changes applied during the transaction permanent.
Parent topic: Statements


COMPUTE Statement (COBOL)

The COMPUTE Statement

The COMPUTE statement assigns to one or more data items the value of an arithmetic expression.

General Format for Format 1 (arithmetic compute)

Format 2 (boolean compute)

Syntax Rules for Format 1

  1. Identifiers that appear only to the left of "=" must refer to either an elementary numeric item or an elementary numeric edited item

    OSVS VSC2 MF or a floating-point item.

  2. OSVS VSC2 MF "Equal", "Equals" and "=" are synonymous.

Syntax Rules for Format 2

  3. Identifier-2 must reference an elementary boolean data item.
  4. Boolean-expression must not consist solely of the figurative constant ALL literal.
  5. "Equal", "Equals" and "=" are synonymous.

General Rules

  1. See the topics Arithmetic Expressions, The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results in Arithmetic Statements in the chapter Procedure Division; the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language, and the section Delimited Scope Statements in the chapter Language Fundamentals.
  2. An arithmetic expression consisting of a single identifier or literal provides a method of setting the values of identifier-1 equal to the value of the single identifier or literal.
  3. The COMPUTE statement allows you to combine arithmetic operations without the need to explicitly store intermediate results in temporary data items, as would be necessary using the arithmetic statements ADD, SUBTRACT, MULTIPLY and DIVIDE. The expression is evaluated to as many digits as possible, and truncated or rounded to fit into identifier-1.

    OSVS VSC2 The intermediate results obtained during the expression evaluation are truncated as if they were moved to data items whose PICTURE is determined by the COBOL system. This behavior is selected using the ARITHMETIC Compiler directive.

    ISO2002 MF The number of boolean positions in the value resulting from the evaluation of boolean-expression is the number of boolean positions in the largest boolean item referenced in the expression. The resulting value is moved to the data item referenced by identifier-2 according to the rules of the MOVE statement.

  4. If more than one identifier is specified for the result of the operation, that is preceding "=", the value of the arithmetic expression is computed, and then this value is stored as the new value of each occurrence of identifier-1 in turn.
Parent topic: Statements
Related information
Arithmetic Expressions
The ON SIZE ERROR Phrase
The ROUNDED Phrase
Arithmetic Statements
Overlapping Operands
Multiple Results in Arithmetic Statements
Explicit and Implicit Scope Terminators
Delimited Scope Statements


CONTINUE Statement (COBOL)

The CONTINUE Statement

The CONTINUE statement is a no operation statement, indicating that no executable statement is present.

General Format

Syntax Rules

  1. The CONTINUE statement can be used anywhere a conditional statement or an imperative-statement can be used.

General Rules

  1. The CONTINUE statement has no effect on the execution of the program.
Parent topic: Statements


CREATE Collection Statement (COBOL)

The CREATE Collection Statement

Creates or constructs an instance of a list or dictionary.

General Formats

CREATE Collection Statement

Where: identifier is the name of the list or dictionary collection type.

Example

The following declares and creates a list collection: and then writes an element to the list:

       declare stringList as list[string]
       create stringList
       write stringList from "item 0"

See also the Collections sample, which is available from $COBDIR/demo.

Parent topic: Statements


DECLARE Statement (COBOL)

The DECLARE Statement

Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.

General Formats for Format 1

General Formats for Format 2

Example

       declare i1 as binary-long
       display i1

       *>   Optionally, the variables can be initialised inline
        declare c2 as condition-value = true
        display c2

        declare string-list2 as string occurs 3 = table of string("Bill", "Ben", "LittleWeed")

See also the Local Variables sample, which is available from $COBDIR/demo.

Parent topic: Statements


DELETE Statement (COBOL)

The DELETE Statement

The DELETE statement logically removes a record from a mass storage file. It can be specified only for files with relative or indexed organization.

General Format

Syntax Rules

  1. The INVALID KEY phrase must not be specified for a DELETE statement which references a file in sequential access mode.
  2. The INVALID KEY phrase must be specified for a DELETE statement which references any file not in sequential access mode for which an applicable USE AFTER STANDARD EXCEPTION PROCEDURE is not specified.

    OSVS VSC2 MF This rule is not enforced.

General Rules

  1. The associated file must be open in the I-O mode at the time of execution of this statement. (See the topic The OPEN Statement.)
  2. For files in sequential access mode, the last input-output statement executed for file-name-1 prior to the execution of the DELETE statement must have been a successfully executed READ statement. The operating system logically removes from the file the record that was accessed by that READ statement.
  3. For a file in random or dynamic access mode, the operating system logically removes from the file that record identified by the contents of a key data item associated with file-name. For a relative file, this key data item is the relative key and for an indexed file, it is the prime record key. If the file does not contain the record specified by the key, an INVALID KEY condition exists. (See the section The INVALID KEY Condition in the chapter Procedure Division.)
  4. After the successful execution of a DELETE statement, the identified record is logically removed from the file and can no longer be accessed.
  5. The execution of a DELETE statement does not affect the contents of the record area associated with file-name-1.
  6. The file position indicator is not affected by the execution of a DELETE statement.
  7. Execution of the DELETE statement causes the value of the specified FILE STATUS data item, if any, associated with the file-name to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  8. Transfer of control following the successful or unsuccessful execution of the DELETE operation depends on the presence or absence of the optional INVALID KEY phrase

    ANS85 and NOT INVALID KEY phrase

    in the DELETE statement. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)

  9. ANS85 The END-DELETE phrase delimits the scope of the DELETE statement. (See the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)
  10. MF When using DELETE, the record to be deleted must not be locked by another run unit.
  11. MF Following the successful execution of a DELETE statement, any record lock held by the run unit on the deleted record is released.
Parent topic: Statements
Related information
The OPEN Statement
The INVALID KEY Condition
I-O Status
Explicit and Implicit Scope Terminators


DELETE FILE Statement (COBOL)

The DELETE FILE Statement

The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.

General Format

DELETE FILE Statement

General Rules

  1. The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.
  2. The specified files must be closed when the statement is executed, but not CLOSED WITH LOCK.
Parent topic: Statements


DETACH Statement (COBOL)

The DETACH Statement

Detaches a delegate or a method group from an event.

General Formats

Syntax Rules

  1. some text

General Rules

  1. some text
Parent topic: Statements


DISPLAY Statement (COBOL)

The DISPLAY Statement

The DISPLAY statement causes data to be transferred from specified data items to the appropriate hardware device, such as the CRT screen.

MF The DISPLAY statement also transfers data from your program to the CRT or video terminal screen: non-scrolling forms, into which you can enter data, are displayed.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

Syntax Rules for Format 1

  1. The mnemonic-name must be associated with a function-name in the Special-Names paragraph in the Environment Division. See General Rule 9 in the topic The Special-Names Paragraph for a list of valid function-names.
  2. OSVS VSC2 MF Alternatively, function-name can itself be used instead of an associated mnemonic-name.
  3. Each literal can be any figurative constant, except ALL.
  4. If the literal is numeric, it must be an unsigned integer.

    OSVS VSC2 MF This restriction can be ignored.

  5. MF XOPEN When mnemonic-name is associated with ARGUMENT-NUMBER, then identifier-1 or literal-1 must each, if used, reference a data item defined as an unsigned integer or an unsigned integer literal respectively. Only a single identifier-1 or literal-1 can be used and the WITH NO ADVANCING phrase cannot be used.
  6. MF XOPEN When mnemonic-name is associated with ENVIRONMENT-NAME or ENVIRONMENT-VALUE, then identifier-1, if used, must reference an alphanumeric data item or an object of type string. Literal-1, if used, must reference a nonnumeric literal. Only a single identifier-1 or literal-1 can be used and the WITH NO ADVANCING phrase cannot be used.
  7. The ON EXCEPTION and NOT ON EXCEPTION phrases can only be specified when mnemonic-name is associated with ENVIRONMENT-NAME or ENVIRONMENT-VALUE.

Syntax Rules for Format 2

  8. MF XOPEN Screen-name cannot be an item with an OCCURS clause.

Syntax Rules for Format 2 and 3

  9. MF The LINE and COLUMN phrases can appear in any order.
  10. MF Integer-3 and identifier-4 must be 4 or 6 digits long.

Syntax Rules for Format 3

  11. MF A DISPLAY statement with an operand that is not a screen-name is treated as a Format 3 DISPLAY statement if it has an AT phrase, an UPON phrase with the CRT or CRT-UNDER option, a WITH phrase, or a MODE IS BLOCK phrase; or if it has no UPON phrase but the CONSOLE IS CRT clause is specified in the Special-Names paragraph. If it has the UPON phrase with the CONSOLE option, or if it has no UPON phrase and the CONSOLE IS CRT clause is not specified in the Special-Names paragraph, it is treated as a Format 1 DISPLAY statement.
  12. MF The phrases following the identifier can be in any order.
  13. MF Elementary data items in identifier-1 must be of USAGE DISPLAY.
  14. MF No elementary item in identifier-1 may be longer than 8191 bytes. If the MODE IS BLOCK phrase is used, the whole of identifier-1 must be no longer than 8191 bytes.
  15. MF If a DISPLAY verb is followed by more than one identifier-1, any WITH clause applies only to the operand immediately preceding it.

General Rules for Format 1

  1. When operands in a DISPLAY statement have USAGE other than DISPLAY, or have included signs, they are converted to USAGE DISPLAY with separate sign. The size of the operand is taken as the size after conversion.
  2. If a figurative constant is specified as one of the operands, only a single occurrence of the figurative constant is displayed.
  3. MF If the function-name COMMAND-LINE, or a mnemonic-name associated with the function-name COMMAND LINE, is specified, data overwrites the contents of a system-dependent command-line buffer from where it can be retrieved by subsequent use of ACCEPT FROM COMMAND-LINE. Only one operand is allowed in this case.

    All permissible function-names other than those specifically mentioned in the general rules for Format 1 of the DISPLAY statement are treated as equivalent to CONSOLE and each operand is transferred to the console device in the order listed. The total size of data displayed is equal to the sum of the sizes of each operand. The display starts from the current cursor position, overflowing onto the following line(s) if necessary.

    On earlier releases, trailing spaces after the last operand were not displayed.

  4. ANS85 If the NO ADVANCING phrase is specified, the cursor is then left at the space following the last character displayed; otherwise it is positioned at the start of the next line. Scrolling can take place whenever the cursor is moved to a new line.
  5. MF XOPEN If the mnemonic-name associated with the function-name ARGUMENT-NUMBER is used, then the position for any subsequent ACCEPT with a mnemonic associated with ARGUMENT-VALUE is set to retrieve the designated command-line argument. If the value associated with identifier-1 or literal-1 is less than 0, greater than 99, or greater than the total number of arguments on the command-line, then results are explicitly undefined.
  6. MF XOPEN If the mnemonic-name associated with the function-name ENVIRONMENT-NAME is used then the variable to be read or set in any subsequent ACCEPT or DISPLAY with a mnemonic associated with ENVIRONMENT-VALUE is set to the designated variable-name specified in literal-1 or as the contents of identifier-1. The ON EXCEPTION phrase is ignored. If any problem occurs while trying to set an ENVIRONMENT-NAME for a subsequent ACCEPT or DISPLAY associated with ENVIRONMENT-VALUE, then it is only the subsequent ACCEPT or DISPLAY that must detect the ON EXCEPTION condition.
  7. MF XOPEN If the mnemonic-name associated with the function-name ENVIRONMENT-NAME is used then
    1. The value returned or set in ENVIRONMENT-NAME must not exceed 255 bytes.
    2. If a previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been done, then the value of the identifier is placed into the designated environment variable.
    3. If no previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, or, for ACCEPT, if the specified environment variable does not exist, or, for DISPLAY, not enough space can be allocated to store the environment variable, the imperative statement associated with an ON EXCEPTION phrase is executed. The value in identifier is undefined in this case.
  8. MF XOPEN If the mnemonic-name associated with the function-name SYSERR is used, then a DISPLAY is performed as if to the CONSOLE except that all output is directed to the system's standard Error Device.
  9. MF XOPEN When using DISPLAY UPON ENVIRONMENT-VALUE, trailing spaces are included in the value. You should use INSPECT REPLACING ALL SPACE BY LOW-VALUES to avoid this.
  10. OSVS VSC2 MF Within identifier-1, internal floating-point numbers are converted to external floating-point numbers for display, so that:
    1. A COMP-1 item is displayed as if it has an external floating-point PICTURE clause of -.9(8)E-99.
    2. A COMP-2 item is displayed as if it has an external floating-point PICTURE clause of -.9(18)E-99 (even though this picture string is illegal if explicitly specified).
  11. OSVS VSC2 MF Literal-1 may be a floating-point literal.

General Rules for Format 2

  12. MF XOPEN This format of the DISPLAY statement displays screen items, which are defined in the Screen Section of the program, and allows full access to the enhanced screen handling facilities.

General Rules for Format 2 and 3

  13. MF The AT phrase gives the absolute address on the screen where the DISPLAY operation is to start.
  14. MF The order of execution of a DISPLAY statement is always:
    1. The AT phrase
    2. The BLANK phrase
    3. The BELL phrase
    4. The DISPLAY operation
  15. MF If integer-3 or identifier-4 is 4 digits long, the first two digits specify the line, the second two the column. If 6 digits long, the first three digits specify the line, while the second three specify the column.
  16. MF Certain combinations of line and column numbers have special meanings, as follows:
    1. Until the column comes within range, out of range column values are reduced by the line length and the line value is incremented.
    2. Out of range line values cause the screen to scroll up one line. The effect is the same as if the line number of the bottom line had been specified.
    3. If the line and column numbers given are both zero, the DISPLAY starts at the position following that where the preceding Format 2 or Format 3 DISPLAY operation finished. Column 1 of each line is considered to follow the last column of the previous line.
    4. If the line number is zero, but a non-zero column number is specified, the DISPLAY starts at the specified column, on the line following that where the preceding Format 2 or 3 DISPLAY operation finished.
    5. If the column number is zero, but a non-zero line number is specified, the DISPLAY starts on the specified line, at the column following that where the preceding Format 2 or 3 DISPLAY operation finished.

General Rules for Format 3

  17. MF Part of this statement can be repeated to allow the display of several data items. If the first item has no AT phrase, it begins at line 1, column 1. Each subsequent item begins at the current cursor position as left after the previous item.
  18. MF If identifier-1 is a group item and no MODE IS BLOCK phrase exists, those elementary subordinate items which have names other than FILLER are displayed. They are displayed simultaneously, positioned on the screen in the order their descriptions appear in the Data Division, and separated by the lengths of the FILLER items in the group. For this purpose, the first position on a line is regarded as immediately following the last position on the previous line.
  19. MF The MODE IS BLOCK phrase indicates that the identifier is to be treated as an elementary item. Thus, even if it is a group item it is displayed as one item.
  20. MF The WITH phrase allows you to specify certain options available during the operation. (See Screen Section Entry Skeleton for descriptions of these options.)

    In addition to the options available as screen description clauses, the following options can be used in the WITH phrase; SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY, TRAILING-SIGN and UPDATE. ZERO-FILL appears in this list and as a screen description clause because it has two different uses. Its second use is documented later in this chapter.

    A configuration option is available which allows the entry of data into numeric and numeric edited screen fields in free format mode. In COBOL, nonedited numeric data items are intended for holding data in an internal form; however, this format enables such data items to appear on the screen. See your COBOL system documentation on user interfaces for more details. If free format mode is in effect, the data appears automatically reformatted as follows:

    • With the virtual decimal point represented by a period
    • With the sign represented by a sign character ("-" for minus; space for plus) which appears immediately before the leftmost digit
    • With zero suppression in all integer character positions, except the least significant
    • With left justification

    The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN options amend this format.

  21. MF If the literal-1 is one of the following figurative constants it has a special effect as follows: SPACE clears from the specified cursor position to the end of the screen; LOW-VALUE moves the cursor to the specified position; ALL X"01" clears from the specified cursor position to the end of the line; ALL X"02" clears the whole screen; ALL X"07" sounds the bell. If the literal is a figurative constant that is not listed above and the SIZE option is not specified, one occurrence of its value is displayed.
  22. MF If the SIZE option is specified for a figurative constant that has no special effect, then that figurative constant is displayed as many times as necessary to reach the length specified in the SIZE option. However, if the display wraps around to a new line, it starts again at the beginning of the figurative constant.
  23. MF When displaying to the screen, any previous foreground or background colors used at a particular screen position are inherited, unless you specify the FOREGROUND-COLOR and BACKGROUND-COLOR clauses again or use the BLANK SCREEN clause. The BLANK SCREEN clause clears the display, and any previous color settings are no longer inherited.
  24. MF If REDEFINES is used within identifier-1, the first description of the redefined data area is used and subsequent descriptions are ignored. If OCCURS or nested OCCURS are used the repeated data item is expanded into the full number of times it occurs, so that one definition is repeated for many fields.
Parent topic: Statements
Related reference
DISPLAY Statement
Related information
The Special-Names Paragraph
Screen Section Entry Skeleton


DIVIDE Statement (COBOL)

The DIVIDE Statement

The DIVIDE statement divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.

General Formats for Format 1

DIVIDE - FORMAT 1

General Formats for Format 2

DIVIDE - FORMAT 2

General Formats for Format 3

DIVIDE - FORMAT 3

General Formats for Format 4

DIVIDE - FORMAT 4

General Formats for Format 5

DIVIDE - FORMAT 5

Syntax Rules for All Formats

  1. Each identifier must refer to an elementary numeric item, except that any identifier associated with the GIVING or REMAINDER phrase must refer to either an elementary numeric item or an elementary numeric edited item.
  2. Each literal must be a numeric literal.
  3. The composite of operands is determined by using all receiving data items except the REMAINDER data item. See the topic Arithmetic Statements in the chapter Procedure Division.
  4. OSVS VSC2 MF When Format 1, 2, or 3 is used, floating-point data items and literals can be used anywhere a numeric data item or literal can be specified. When Format 4 or 5 is used, no floating-point data items or literals may be specified.

General Rules for All Formats

  1. See the topics The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results in Arithmetic Statements in the chapter Procedure Division; the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language, and the section Delimited Scope Statements in the chapter Language Fundamentals. .

General Rules for Format 1

  2. When Format 1 is used, literal-1 or the value of the data item referenced by identifier-1 is stored in a temporary data item. The value in this temporary data item is then divided into the value of identifier-2. The value of the dividend (the value of the data item referenced by identifier-2) is replaced by this quotient; similarly, the temporary data item is divided into each successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is specified.

General Rules for Format 2

  3. When Format 2 is used, the value of identifier-1 or literal-1 is divided into identifier-2 or literal-2 and the result is stored in each data item referenced by identifier-3.

General Rules for Format 3

  4. When Format 3 is used, the value of identifier-1 or literal-1 is divided by the value of identifier-2 or literal-2 and the result is stored in each data item referenced by identifier-3.

General Rules for Formats 4 and 5

  5. Formats 4 and 5 are used when a remainder from the division operation is desired, namely identifier-4. The remainder in COBOL is defined as the result of subtracting the product of the quotient (identifier-3) and the divisor from the dividend. If identifier-3 is defined as a numeric edited item, the quotient used to calculate the remainder is an intermediate field which contains the unedited quotient. If ROUNDED is used, the quotient used to calculate the remainder is an intermediate field which contains the quotient of the DIVIDE statement, truncated rather than rounded.
  6. In Formats 4 and 5, the accuracy of the REMAINDER data item (identifier-4) is defined by the calculation described above. Appropriate decimal alignment truncation (not rounding) is performed for the content of the data item referenced by identifier-4, as needed.
  7. When the ON SIZE ERROR phrase is used in Formats 4 and 5, the following rules pertain:
    1. If the size error condition occurs on the quotient, no remainder calculation is meaningful. Thus, the contents of the data items referenced by both identifier-3 and identifier-4 ill remain unchanged.
    2. If the size error condition occurs on the remainder, the contents of the data item referenced by identifier-4 remains unchanged.

    However, as with other instances of multiple results of arithmetic statements, you will have to do your own analysis to recognize which situation has actually occurred.

Parent topic: Statements
Related information
Arithmetic Expressions
The ON SIZE ERROR Phrase
The ROUNDED Phrase
Arithmetic Statements
Overlapping Operands
Multiple Results in Arithmetic Statements
Explicit and Implicit Scope Terminators
Delimited Scope Statements


ENTER Statement (COBOL)

The ENTER Statement

The ENTER statement provides a means of allowing the use of more than one language in the same program.

ANS85 The ENTER statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation support this syntax for documentation purposes only. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Format

Syntax Rules

  1. Language-name and routine-name can be any user-defined word or alphanumeric literal.

General Rules

  1. This statement is treated as for documentation purposes only. Access to other languages can be achieved by means of the CALL statement.
Parent topic: Statements


ENTRY Statement (COBOL)

The ENTRY Statement

The ENTRY statement establishes an alternate entry point into a called COBOL program.

General Formats for Format 1

General Formats for Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the STICKY-LINKAGE directive controls whether addressability to Linkage Section items is maintained between calls to different entry points in the same program.

Syntax Rules for All Formats

  1. The ENTRY statement cannot be used in a program that is nested within another program.
  2. Literal-1 must be non-numeric and must not be a figurative constant. In some environments, only the first 8 characters are significant.
  3. Mnemonic-name is necessary only if the object program that is to be invoked expects a calling convention other than that used as the default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant implementation of a non-COBOL language for the run-time environment.

    Mnemonic-name must be defined in the Special-Names paragraph. See the topic The Special-Names Paragraph for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run-time environment.

Syntax Rules for Format 1

  4. Format 1 must be specified only within program definitions.
  5. Data-name-1 must be defined as a level 01 or a level 77 entry in the Linkage Section

    MF , File Section or Working-Storage Section.

  6. MF Data-name-2 must be defined as a level 01 or a level 77 entry in the Linkage Section, File Section or Working-Storage Section. Data-name-2 can be of any class, but the length must be no greater than 8 bytes.

Syntax Rules for Format 2

  7. MF Format 2 can only be used in a program in which the EXTERNAL clause is specified in the Program-ID paragraph, that is a call prototype.
  8. MF Data-name-1 and data-name-2 must be defined as 01 level records in the Linkage Section.
  9. MF Typedef-name-1, typedef-name-2, and typedef-name-3 must be previously defined in the same source file as a programmer-defined usage by means of a TYPEDEF clause.

General Rules for All Formats

  1. The content of literal-1 gives the entry-name, a name which identifies an entry point into the program that is an alternative to the default COBOL entry point at the start of the Procedure Division that is identified by the program-name given in the Program-ID paragraph.

    Note that program files containing executable COBOL code typically have names that are essentially the same as the program-name. When a CALL is made and the program-name or entry-name is not already loaded into memory, program files are located by filename but can appear to be located by program-name. In such circumstances, a CALL that references a program-name may succeed but a CALL that references an entry-name may fail.

    The entry-name is largely equivalent to a program-name and the two are subject to common rules for formation of the name as indicated in the topic The Program-ID Paragraph. Literal-1 corresponds to literal-1 of the general format for the Program-ID paragraph.

  2. When the calling program invokes the called program by a CALL statement naming the entry-name given by literal-1, control is transferred to the next executable statement following the ENTRY statement.
  3. Data items that are declared in the Linkage Section but are not declared in the USING phrase of the ENTRY statement can only be referenced if they have been linked to a data item by executing a SET statement or if the STICKY-LINKAGE Compiler directive is used.
  4. Up to sixty-two data-names are permitted in the USING phrase.
  5. Both the BY REFERENCE and the BY VALUE phrases are transitive across the parameters that follow them until another BY REFERENCE or BY VALUE phrase is encountered. If neither the BY REFERENCE nor the BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

General Rules for Format 1

  6. MF If data-name-1 is defined as a level 01 or a level 77 entry in the File Section or Working-Storage Section then the object program operates as if a data item had been declared in the Linkage Section with the same data declaration as data-name-1 and the contents of that data item were moved to data-name-1 prior to executing the first statement in the called program. In an initial program, these values are overwritten by the initialization of the program's Working-Storage data and are therefore not available to the called program.
  7. If the activating runtime element is COBOL the following rules apply. If the activating runtime element is not COBOL, see your COBOL system documentation on interfacing for details of when you need to use the BY REFERENCE or BY VALUE clauses.
  8. The USING phrase identifies the names of the formal parameters used by the program or for any arguments passed to it. The arguments passed to it are identified in the activating source element by the USING phrase of a CALL statement. The correspondence between the two lists of names is established on a positional basis.
  9. If the argument is passed by content, the called program operates as if the record in the Linkage Section were allocated by the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage area as the argument in the calling runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the called program as if it were the argument and as if it were passed by reference.
  10. If the argument is passed by reference, the called program operates as if the formal parameter occupies the same storage area as the argument.
  11. MF If the argument is passed by value, the called program operates as if the record in the Linkage Section were allocated by the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage area as the argument in the calling runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the called program as if it were the argument and as if it were passed by reference.
  12. At all times in the activated element, references to data-name-1

    MF , data-name-2 and data-name-3

    are resolved in accordance with their description in the Linkage Section. If this description defines a greater number of character positions than the corresponding data item in the activating element, unpredictable results can occur. Failure to comply with this rule or exceeding the maximum allowed size of the system area for a particular run time environment may result in the system becoming catastrophically corrupt.

  13. MF When a program is called and a BY REFERENCE operand in the USING phrase corresponds to a parameter in the calling program, a referential connection is established and endures until control is returned to the calling program. If the program is called a second time, without any intervening cancel of the program, and that same BY REFERENCE operand does not correspond to a parameter in the calling program, then you must not reference that operand unless the STICKY-LINKAGE Compiler directive is specified.

General Rules for Format 2

  23. When the BY REFERENCE phrase passes data-name-1 using the DELIMITED keyword, it is a copy of the original parameter, with any trailing spaces replaced with a null terminator, that is passed. No changes to this parameter are passed back to the calling program.
Parent topic: Statements
Related information
The Special-Names Paragraph
The Program-ID Paragraph


EVALUATE Statement (COBOL)

The EVALUATE Statement

The EVALUATE statement describes a multi-branch, multi-join structure. It can cause multiple conditions to be evaluated. The subsequent action of the runtime element depends on the results of these evaluations.

General Format

Syntax Rules

  1. The operands or the words TRUE and FALSE which appear before the first WHEN phrase of the EVALUATE statement are referred to individually as selection subjects and collectively, for all those specified, as the set of selection subjects.
  2. The operands or the words TRUE, FALSE, and ANY which appear in a WHEN phrase of an EVALUATE statement are referred to individually as selection objects and collectively, for all those specified in a single WHEN phrase, as the set of selection objects.
  3. The words THROUGH and THRU are equivalent.
  4. Two operands connected by a THROUGH phrase must be of the same class. The two operands thus connected constitute a single selection object.
  5. The number of selection objects in each set of selection objects must be equal to the number of selection subjects.
  6. Each selection object in a set of selection objects must correspond to the selection subject having the same ordinal position in the set of selection subjects according to the following rules:
    1. Identifiers, literals, or arithmetic expressions appearing in a selection object must be valid operands for comparison to the corresponding operand in the set of selection subjects. (See the topic Relation Condition in the chapter Procedure Division.)
    2. Condition-1, condition-2, or the words TRUE or FALSE appearing as a selection object must correspond to a conditional expression or the words TRUE or FALSE in the set of selection subjects.
    3. The word ANY can correspond to a selection subject of any type.
    4. VSC2 MF Where identifiers are permitted, they can reference floating-point data items.
    5. VSC2 MF Where numeric literals are permitted, floating-point literals are permitted.
    6. VSC2 MF Where identifiers are permitted, they can reference pointer data items.
  7. A selection object is a partial-expression if the leftmost portion of the selection object is a relational operator, a class condition without the identifier, a sign condition without the identifier, or a sign condition without the arithmetic expression.
  8. ISO2002 MF If partial-expression-1 or partial-expression-2 is specified as a selection object, it must correspond to a selection subject that is an identifier, a literal or an arithmetic expression. Partial-expression-1 and partial-expression-2 must be a sequence of COBOL words which, when following the corresponding selection subject, make the resultant text a valid conditional expression.

General Rules

  1. The execution of the EVALUATE statement operates as if each selection subject and selection object were evaluated and assigned a numeric or nonnumeric value, a range of numeric or nonnumeric values, or a truth value. These values are determined as follows:
    1. Any selection subject specified by identifier-1, identifier-2, and any selection object specified by identifier-3, identifier-5, without either the NOT or the THROUGH phrases, are assigned the value and class of the data item referenced by the identifier.
    2. Any selection subject specified by literal-1, literal-2, and any selection object specified by literal-3, literal-5, without either the NOT or the THROUGH phrases, are assigned the value and class of the specified literal. If literal-3, literal-5, is the figurative constant ZERO, it is assigned the class of the corresponding selection subject.
    3. Any selection subject in which expression-1, expression-2, is specified as an arithmetic expression and any selection object, without either the NOT or the THROUGH phrases, in which arithmetic-expression-1, arithmetic-expression-3, is specified are assigned a numeric value according to the rules for evaluating an arithmetic expression. (See the topic Arithmetic Expressions in the chapter Procedure Division.)
    4. Any selection subject in which expression-1, expression-2 is specified as a conditional expression and any selection object in which condition-1, condition-2, is specified are assigned a truth value according to the rules for evaluating conditional expressions. (See the topic Conditional Expressions in the chapter Procedure Division.)
    5. Any selection subject or any selection object specified by the words TRUE or FALSE is assigned a truth value. The truth value "true" is assigned to those items specified with the word TRUE, and the truth value "false" is assigned to those items specified with the word FALSE.
    6. Any selection object specified by the word ANY is not further evaluated.
    7. If the THROUGH phrase is specified for a selection object, without the NOT phrase, the range of values is all values which, when compared to the selection subject, are greater than or equal to the first operand and less than or equal to the second operand according to the rules for comparison. (See the topic Relation Condition in the chapter Procedure Division.
    8. If the NOT phrase is specified for a selection object, the values assigned to that item are all values not equal to the value, or range of values, which would have been assigned to the item had the NOT phrase not been specified.
  2. The execution of the EVALUATE statement then proceeds as if the values assigned to the selection subjects and selection objects were compared to determine if any WHEN phrase satisfies the set of selection subjects. This comparison proceeds as follows:
    1. Each selection object in the set of selection objects for the first WHEN phrase is compared to the selection subject having the same ordinal position in the set of selection subjects.
      1. If the items being compared are assigned numeric or nonnumeric values, or a range of numeric or nonnumeric values, the comparison is satisfied if the value, or one of the range of values, assigned to the selection object is equal to the value assigned to the selection subject according to the rules for comparison. (See the topic Relation Condition in the chapter Procedure Division.)
      2. If the items being compared are assigned truth values, the comparison is satisfied if the items are assigned the identical truth value.
      3. If the selection object being compared is specified by the word ANY, the comparison is always satisfied regardless of the value of the selection subject.
    2. If the above comparison is satisfied for every selection object in the set of selection objects being compared, the WHEN phrase containing that set of selection objects is selected as the one satisfying the set of selection subjects.
    3. If the above comparison is not satisfied for one or more selection objects in the set of selection objects being compared, that set of selection objects does not satisfy the set of selection subjects.
    4. This procedure is repeated for subsequent sets of selection objects, in the order of their appearance in the source element, until either a WHEN phrase satisfying the set of selection subjects is selected or until all sets of selection objects are exhausted.
  3. After the comparison operation is completed, execution of the EVALUATE statement proceeds as follows:
    1. If a WHEN phrase is selected, execution continues with the first imperative-statement-1 following the selected WHEN phrase.
    2. If no WHEN phrase is selected and a WHEN OTHER phrase is specified, execution continues with imperative-statement-2.
    3. The scope of execution of the EVALUATE statement is terminated when execution reaches the end of the scope of the selected WHEN phrase or WHEN OTHER phrase or when no WHEN phrase is selected and no WHEN OTHER phrase is specified.
  4. ISO2002 MF If the selection object is specified by partial-expression-1 or partial-expression-2, the corresponding selection subject is considered to be the word TRUE. The selection object is considered to be condition-1 or condition-2 respectively, where condition-1 or condition-2 is the conditional expression resulting from partial expression-1 or partial-expression-2 following the original corresponding selection-subject-1 or selection-subject-2 respectively.
Parent topic: Statements
Related concepts
Explicit and Implicit Scope Terminators


EXAMINE Statement (COBOL)

The EXAMINE Statement

The EXAMINE statement replaces or counts the number of occurrences of a given character in a data item.

General Formats for Format 1

General Formats for Format 2

Syntax Rules for All Formats

  1. The identifier must be described, explicitly or implicitly, as USAGE IS DISPLAY.
  2. Each literal must consist of a single character. If identifier is a numeric item, the literals must be numeric literals, nonnumeric literals whose value is a single numeric digit, or the figurative constant ZERO. If identifier belongs to any other class, then the literals can be numeric or nonnumeric, or any figurative constant without the word ALL.

General Rules for All Formats

  1. Examination proceeds as follows:
    1. For nonnumeric data items, examination starts at the leftmost character and proceeds to the right. Each character in the data item specified by the identifier is examined in turn.
    2. If a data item referred to by the EXAMINE statement is numeric, it must consist of numeric characters and can possess an operational sign. Examination starts at the leftmost character (excluding the sign) and proceeds to the right. Each character except the sign is examined in turn. Regardless of where the sign is physically located, it is completely ignored by the EXAMINE statement.
  2. The TALLYING option creates an integral count which replaces the value of a spe cial register called TALLY. The count represents the number of:
    1. Characters not equal to literal-1 encountered before the first occurrence of literal-1 when the UNTIL FIRST option is used.
    2. Occurrences of literal-1 when the ALL option is used.
    3. Occurrences of literal-1 prior to encountering a character other than literal-1 when the LEADING option is used.
  3. When either of the REPLACING options is used, the replacement rules are as follows:
    1. When the ALL option is used, then literal-2 is substituted for each occurrence of literal-1.
    2. When the LEADING option is used, the substitution of literal-2 terminates as soon as a character other than literal-1 or when the right-hand boundary of the data item is encountered.
    3. When the FIRST option is used, the first occurrence of literal-1 is replaced by literal-2.
    4. When the UNTIL FIRST option is used, the substitution of literal-2 terminates as soon as literal-1 or the right-hand boundary of the data item is encountered.
Parent topic: Statements


EXEC(UTE) Statement (COBOL)

The EXEC(UTE) Statement

The EXEC(UTE) statement is provided as a linkage mechanism to allow control to be passed to non-COBOL subsystems.

General Formats for Format 1

General Formats for Format 2

Syntax Rules

  1. Text-data can be any textual data not containing the string END-EXEC.

General Rules for Format 1

  1. The formats EXEC(UTE) CICS, EXEC(UTE) SQL, and EXEC(UTE) DLI cause the appropriate system component (variously known as preprocessors, co-processors and external compiler modules) to be called to process text-data if the corresponding Compiler directive is specified that invokes that system component. If the corresponding Compiler directive has not been specified, the EXEC(UTE) statement is treated as a format 1 EXEC(UTE) statement For further information on the use of these formats see the information on using CICS and accessing databases in your COBOL system documentation.

General Rules for Format 2

  2. The statement is compiled as a CALL "text-name" USING text-data-buffer statement (see the topic The CALL Statement), where text-data-buffer contains all the text-data from the EXEC statement (space compressed) for further parsing by the called program text-name.

    This means that the called subprogram (text-name) is passed a text string which includes the entire COBOL statement beginning with the EXEC(UTE) verb and ending with the END-EXEC phrase. The called program must parse and then process all of the included information.

    If an identifier-name is included in text-data, then it is the name of the identifier, not the value of the data in the identifier, that is passed to the subprogram.

Parent topic: Statements
Related information
The CALL Statement


EXHIBIT Statement (COBOL)

The EXHIBIT Statement

The EXHIBIT statement causes an (optionally conditional) display of the literals, and/or identifiers (optionally preceded by the identifier name) specified in the statement.

General Format

Syntax Rules

  1. Each identifier specified in the EXHIBIT statement can be any class of data. TALLY and RETURN-CODE are the only special registers that can be used as identifiers.
  2. The EXHIBIT CHANGED statement is not supported in class programs when compiling to managed code.

General Rules

  1. Literals and identifiers displayed by the EXHIBIT statement are separated by a space on the displayed line.
  2. Each literal can be any figurative constant other than ALL.
  3. If the literal is numeric, it must be an unsigned integer.
  4. Each execution of an EXHIBIT NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by an "=" (equal sign) and its current value. They all appear on a single line in the order in which they appear in the statement.
  5. Each execution of an EXHIBIT CHANGED NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by an "=" (equal sign) and its current value. They all appear on a single line in the order in which they appear in the statement. However, the display for each identifier (name and value) is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, neither the name nor the value is printed for those identifiers. If none of the identifier values has changed, and no literals are specified, no display takes place (display of a blank line is suppressed).
  6. Each execution of an EXHIBIT CHANGED statement displays the current value of each identifier or literal specified. They all appear on a single line in the order in which they appear in the statement. However, the value display for each identifier is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, the value for those identifiers is not printed; spaces are inserted instead. If none of the identifier values has changed, and no literals are specified, a blank line is displayed (display of a blank line is not suppressed).
  7. Each execution of an EXHIBIT statement with neither the CHANGED nor the NAMED option displays each identifier or literal specified. They all appear on a single line in the order in which they appear in the statement.
Parent topic: Statements


EXIT Statement (COBOL)

The EXIT Statement

The EXIT statement provides a common end point for a series of procedures.

MF The EXIT statement can also exit an inline PERFORM, a paragraph or a section.

The EXIT PROGRAM statement marks the logical end of a called program.

MF You can also return values to activating runtime elements written in any language.

ISO2002 MF The EXIT METHOD statement marks the logical end of an invoked method.

ISO2002 The EXIT FUNCTION statement marks the logical end of the execution of a function.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

General Formats for Format 5

General Formats for Format 6

General Formats for Format 7

Syntax Rules for Format 1

  1. The EXIT statement should appear in a sentence by itself.

    VSC2 MF This rule is not enforced.

  2. The EXIT sentence should be the only sentence in the paragraph.

    VSC2 MF This rule is not enforced.

Syntax Rules for Format 2

  3. MF A Format 2 EXIT statement can be used only within an inline PERFORM.

Syntax Rules for Format4

  4. If an EXIT PROGRAM statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    VSC2 MF This rule is not enforced.

  5. There must be no sentence other than the EXIT PROGRAM sentence in the paragraph.

    ANS85 This rule is not enforced.

  6. MF Integer-1 may be signed.
  7. MF GIVING and RETURNING are equivalent.
  8. MF Identifier-1 must be no larger than 8 bytes in size.

Syntax Rules for Format 5

  9. ISO2002 MF An EXIT METHOD statement may be specified only in a method Procedure Division.

Syntax Rules for Format 6

  10. ISO2002 An EXIT FUNCTION statement must be specified only in a function Procedure Division.

Syntax Rules for Formats 4, 5 and 6

  11. The EXIT statement must not be specified in a declarative procedure for which the GLOBAL phrase is specified in the associated USE statement.

Syntax Rules for Format 7

  12. NET JVM EXIT ITERATOR may only be specified in the context of an Iterator. See Iterator-ID.

General Rules for Format 1

  1. An EXIT statement serves only to enable you to assign a procedure-name to a given point in a Procedure Division. Such an EXIT statement has no other effect on the compilation or execution .

General Rules for Format 2

  2. MF The execution of an EXIT PERFORM statement without a CYCLE phrase causes control to be passed to an implicit CONTINUE statement, immediately following the END-PERFORM associated with the nearest inline PERFORM statement.
  3. MF The execution of an EXIT PERFORM statement with a CYCLE phrase causes control to be passed to an implicit CONTINUE statement, immediately preceding the END-PERFORM associated with the nearest inline PERFORM statement.

General Rules for Format3

  4. MF The execution of a Format 3 EXIT statement with the PARAGRAPH phrase causes control to pass to an implicit CONTINUE statement immediately following the last statement in the paragraph.
  5. MF The execution of an EXIT SECTION statement causes control to be passed to an unnamed empty paragraph immediately following the last paragraph of the current section, preceding any return mechanisms for that section.

General Rules for Format 4

  6. ANS85 If the EXIT PROGRAM statement is executed in a program which is not under the control of a calling runtime element, the EXIT PROGRAM statement causes execution of the program to continue with the next executable statement.
  7. ANS85 The execution of an EXIT PROGRAM statement in a called program which does not possess the initial attribute causes execution to continue with the next executable statement following the CALL statement in the calling runtime element. The state of the calling runtime element is not altered and is identical to that which existed at the time it executed the CALL statement except that the contents of data items and the contents of data files shared between the calling and called runtime elements may have been changed. The program state of the called program is not altered except that the ends of the ranges of all PERFORM statements executed by that called program are considered to have been reached.
  8. ANS85 Besides the actions specified in General Rule 7, the execution of an EXIT PROGRAM statement in a called program which possesses the initial attribute is equivalent to also executing a CANCEL statement referencing that program except that the statement does not free any memory. See the topic The CANCEL Statement in the chapter Procedure Division - ACCEPT - DIVIDE.
  9. ANS85 An EXIT PROGRAM statement must not be executed while executing a declarative procedure in which the GLOBAL phrase is specified except in a program called while executing that declarative procedure.
  10. MF Execution of an EXIT PROGRAM statement in a program that is under the control of a calling runtime element, causes a return value to be set in the system area generally available for non-COBOL programs to return a value. This system area is never smaller than 4 bytes in size but may be larger in some environments.

    If the GIVING phrase is not specified and the calling convention specifies updating the RETURN-CODE special-register (see the rules for the CALL-CONVENTION clause in the topic The Special-Names Paragraph) then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with the RETURN-CODE as the sending item and the system area as the receiving item. (See the topic Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

    If the GIVING ADDRESS OF phrase is specified, the object program operates as if the system area were declared as a COBOL data item with USAGE POINTER and as if a SET statement had been executed with TO ADDRESS OF identifier-2 as the first operand and the system area as the second operand. The ADDRESS OF phrase may be used to indirectly pass a value that is larger than the system area.

    If the GIVING identifier-1 phrase is specified, identifier-1 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is expected by the calling runtime element. The object program operates as if a MOVE statement had been executed with identifier-1 as the sending item and the system area as the receiving item.

    If the GIVING integer-1 phrase is specified, integer-1 must not be larger than the value that can be held in the system area. The object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with integer-1 as the sending item and the system area as the receiving item.

    When compiling procedural COBOL code to managed COBOL, if there is no RETURNING phrase on the PROCEDURE DIVISION header, the Compiler generates a method that returns a 32 or 64-bit integer depending on the setting of the RTNCODE-SIZE directive. Statements of the form EXIT PROGRAM RETURNING identifier-1 attempt to convert identier-1 into the correct integer type, according to the rules of the MOVE statement, before returning the value to the calling program.

General Rules for Format 5

  11. ISO2002 MF The execution of an EXIT METHOD statement causes the executing method to terminate, and control to return to the invoking statement. If a RETURNING phrase is present in the containing method definition, the value in the data item referenced by the RETURNING phrase becomes the result of the method invocation.

General Rules for Format 6

  12. ISO2002 The execution of an EXIT FUNCTION causes the executing function to terminate, and control to return to the activating statement. The value in the data item referenced by the RETURNING phrase in the containing function definition becomes the result of the function activation.
Parent topic: Statements
Related reference
EXIT Statement
Related information
The Iterator-ID Paragraph
The CANCEL Statement
The Special-Names Paragraph
Special Registers


FREE Statement (COBOL)

The FREE Statement

The FREE statement frees up dynamic storage that was previously allocated by an ALLOCATE statement.

General Format

General Rules

  1. If data-name-1 identifies the start of storage currently allocated by an ALLOCATE statement, the storage is released and data-name-1 set to NULL.
  2. The length of the released storage is the same as the length allocated using the ALLOCATE statement, and so the contents of any data items within the storage become undefined.
  3. If data-name-1 contains a predefined address of NULL or an address of storage not allocated via the ALLOCATE statement, no storage is freed. The pointer data-name-1 will be kept unchanged, and behavior is undefined.
  4. If more than one data-name-1 is specified in a single statement, the effect is as if individual FREE statements were entered, in the order in which the data-name-1 pointers are specified.

Syntax Rules

  1. data-name-1 must be defined as USAGE IS POINTER.
  2. data-name-1 can be qualified or subscripted.
Parent topic: Statements
Related reference
The ALLOCATE Statement


GOBACK Statement (COBOL)

The GOBACK Statement

The GOBACK statement marks the logical end of a called program.

MF You can also return values to calling runtime elements written in any language or to the operating system environment.

General Format

The GOBACK Statement

Syntax Rules

  1. If a GOBACK statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    This rule is not enforced, although any statements in the sentence that follow the GOBACK statement are not executed.

  2. MF GIVING and RETURNING are equivalent.
  3. MF The data item referenced by identifier-1 must be no larger than 8 bytes in size.
  4. Integer-1 may be signed.

General Rules

  1. If a GOBACK statement is executed in a program which is under the control of a calling runtime element, the object program operates as if executing an EXIT PROGRAM statement that has the same clauses as the GOBACK statement. See the topic The EXIT Statement.
  2. If a GOBACK statement without the ADDRESS OF clause is executed in a program which is not under the control of a calling runtime element, the object program operates as if executing a STOP RUN statement that has the same clauses as the GOBACK statement.
  3. If a GOBACK statement with the ADDRESS OF clause is executed in a program which is not under the control of a calling runtime element, the object program operates as if executing a STOP RUN statement except that an arbitrary returned value is set in the system area. The GOBACK statement may result in more compact code than the equivalent EXIT PROGRAM and STOP RUN statement.
  4. A GOBACK statement must not be executed while executing a declarative procedure in which the GLOBAL phrase is specified except in a program called while executing that declarative procedure.
  5. ISO2002 If a GOBACK statement is executed in a function, the function operates as if executing an EXIT FUNCTION statement.
  6. ISO2002 MF If a GOBACK statement is executed in a method, the method operates as if executing an EXIT METHOD statement.
  7. NET JVM If a GOBACK statement is executed in an iterator, the iterator operates as if executing an EXIT ITERATOR statement.
Parent topic: Statements
Related reference
GOBACK Statement
Related information
The EXIT Statement


GO TO Statement (COBOL)

The GO TO Statement

The GO TO statement causes control to be transferred from one part of the Procedure Division to another.

ANS85 The option of omitting procedure-name-1 in a Format 1 GO TO statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, omitting the procedure-name in Format 1 is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Formats for Format 1

GO TO - Format 1

General Formats for Format 2

GO TO - Format 2

Syntax Rules for All Formats

  1. Identifier is the name of a numeric elementary item which is an integer.
  2. When a paragraph is referenced by an ALTER statement, that paragraph can consist only of a paragraph header followed by a Format 1 GO TO statement.

Syntax Rules for Format 1

  3. A Format 1 GO TO statement, without procedure-name-1, can only appear in a single statement paragraph.

    MF This restriction is not enforced.

  4. If a Format 1 GO TO statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

Syntax Rules for Format 2

  5. In Format 2, at least two procedure-names should be specified.

    ANS85 A Format 2 statement can be written with only one procedure name.

General Rules for All Formats

  1. If procedure-name-1 is not specified in Format 1, an ALTER statement, referring to this GO TO statement, must be executed prior to the execution of this GO TO statement.

    VSC2 MF If an ALTER statement referring to the paragraph containing this GO TO statement has not been executed before this GO TO statement is executed, this GO TO statement is treated like a CONTINUE statement.

General Rules for Format 1

  2. When a GO TO statement represented by Format 1 is executed, control is transferred to procedure-name-1 or to another procedure-name if the GO TO statement has been modified by an ALTER statement.

General Rules for Format 2

  3. When a GO TO statement represented by Format 2 is executed, control is transferred to procedure-name-1, procedure-name-2, and so on, depending on the value of the identifier being 1, 2, ..., n. If the value of the identifier is anything other than the positive or unsigned integers 1, 2, ..., n, then no transfer occurs and control passes to the next statement in the normal sequence for execution.
Parent topic: Statements


IF Statement (COBOL)

The IF Statement

The IF statement causes a condition to be evaluated (see the topic Conditional Expressions in the chapter Procedure Division). The subsequent action of the runtime element depends on whether the value of the condition is true or false.

General Format

Syntax Rules

  1. Statement-1 and statement-2 represent either an imperative statement or a conditional statement optionally preceded by an imperative statement.
  2. ANS85 If the END-IF phrase is specified, the NEXT SENTENCE phrase must not be specified.

    VSC2 MF NEXT SENTENCE can be specified with END-IF.

    If the NEXT SENTENCE phrase is executed, control does not pass to the next statement following the END-IF, but instead passes to the statement after the closest following period.

General Rules

  1. The scope of an IF statement can be terminated by any of the following:
    1. ANS85 An END-IF phrase at the same level of nesting.
    2. A separator period.
    3. If nested, by an ELSE phrase associated with an IF statement at a higher level of nesting.
  2. When an IF statement is executed, the following transfers of control occur:
    1. If the condition is true, statement-1 is executed if specified. If statement-1 contains a procedure branching or conditional statement, control is explicitly transferred in accordance with the rules of that statement. If statement-1 does not contain a procedure branching or conditional statement, the ELSE phrase, if specified, is ignored and control passes to the end of the IF statement.
    2. If the condition is true and the NEXT SENTENCE phrase is specified instead of statement-1, the ELSE phrase, if specified, is ignored and control passes to the next executable sentence.
    3. If the condition is false, statement-1 or its surrogate NEXT SENTENCE is ignored, and statement-2, if specified, is executed. If statement-2 contains a procedure branching or conditional statement, control is explicitly transferred in accordance with the rules of that statement. If statement-2 does not contain a procedure branching or conditional statement, control passes to the end of the IF statement. If the ELSE statement-2 phrase is not specified, statement-1 is ignored and control passes to the end of the IF statement.
    4. If the condition is false, and the ELSE NEXT SENTENCE phrase is specified, statement-1 is ignored, if specified, and control passes to the next executable sentence.
  3. Statement-1 and/or statement-2 can contain an IF statement. In this case the IF statement is said to be nested.

    ANS85 IF statements within IF statements are considered matched IF, ELSE, and END-IF ordered combinations, proceeding from left to right. Thus, any ELSE encountered is matched with the nearest preceding IF that has not been already matched with an ELSE or has not been implicitly or explicitly terminated. Any END-IF encountered is matched with the nearest preceding IF that has not been implicitly or explicitly terminated.

Parent topic: Statements
Related information
Conditional Expressions


INITIALIZE Statement (COBOL)

The INITIALIZE Statement

The INITIALIZE statement provides the ability to set selected data items to specified values.

General Format

Syntax Rules

  1. Identifier-1 must be of class alphabetic or alphanumeric or numeric

    ISO2002 MF or object or pointer

    ISO2002 ENT MF or national

    .

  2. ISO2002 MF For each DATA-POINTER, OBJECT-REFERENCE or PROGRAM-POINTER phrase specified as the category-name in the REPLACING phrase, identifier-2 must be specified.
  3. ISO2002 MF For each of the categories data-pointer, object-reference and program-pointer specified in the REPLACING phrase, a SET statement with identifer-2 as the sending operand and an item of the specified category as the receiving operand must be valid. (See the topic The SET Statement.)

    ISO2002 MF For each of the categories other than data-pointer, object-reference or program-pointer stated in the REPLACING phrase, a MOVE statement with identifier-2 or literal-1 as the sending item and an item of the specified category as the receiving operand must be valid. (See the topic The MOVE Statement.)

    ENT For each of the categories, a MOVE statement with identifier-2 or literal-1 as the sending item and an item of the specified category as the receiving operand must be valid.

  4. If the REPLACING phrase is specified, literal-1 or the data item referenced by identifier-2 is the sending operand.

    ISO2002 ENT MF If the REPLACING phrase is not specified, the sending operand is determined according to the general rules of the INITIALIZE statement.

  5. The data item referenced by identifier-1 is the receiving area.
  6. The same category cannot be repeated in a REPLACING phrase.
  7. The description of the data item referenced by identifier-1 or any items subordinate to identifier-1 cannot contain the DEPENDING phrase of the OCCURS clause.

    VSC2 The data item referenced by identifier-1 cannot be variably located, that is, it cannot follow in the same record description an item containing the DEPENDING phrase of the OCCURS clause unless identifier-1 is subordinate to that item with the OCCURS clause.

    MF The data item referenced by identifier-1 can be variably located.

  8. The data description entry for the data item referenced by identifier-1 must not contain a RENAMES clause.
  9. VSC2 MF A floating-point data item or literal can be used anywhere a numeric identifier or literal can be specified.
  10. category-list can be one of:
    • ALPHABETIC
    • ALPHANUMERIC
    • ALPHANUMERIC-EDITED
    • BOOLEAN
    • ISO2002 MF DATA-POINTER
    • ENT VSC2 MF DBCS
    • ISO2002 ENT MF NATIONAL
    • ISO2002 ENT MF NATIONAL-EDITED
    • NUMERIC
    • NUMERIC-EDITED
    • ISO2002 MF OBJECT-REFERENCE
    • ISO2002 MF PROGRAM-POINTER

General Rules

  1. The key words in category-name correspond to a category of data as defined elsewhere in this document. (See the topic Class and Category of Data in the chapter Concepts of the COBOL Language.)

    ISO2002 ENT MF If ALL is specified in the VALUE phrase it is as if all of the categories listed in category-name were specified.

  2. Whether identifier-1 references an elementary item or a group item, the effect of the execution of the INITIALIZE statement is as though a series of implicit MOVE or SET statements, each of which has an elementary data item as its receiving operand, were executed. The sending-operands of these implicit statements are defined in general rule 4 and the receiving-operands are defined in general rule 3.

    If the category of a receiving-operand is data-pointer, object-reference, or program-pointer, the implicit statement is: SET receiving-operand TO sending-operand

    Otherwise, the implicit statement is: MOVE sending-operand TO receiving-operand.

  3. The receiving operand in each implicit MOVE or SET statement is determined by applying the following steps in order:
    1. First, the following data items are excluded as receiving operands:
      1. ISO2002 ENT MF Any identifiers that are not valid receiving operands of a MOVE statement

        ISO2002 MF - except data items of category data-pointer, object-reference or program-pointer when dialect specified is MF15 or ISO2002

        .
      2. If the FILLER phrase is not specified, elementary data items with an explicit or implicit FILLER clause.
      3. Any elementary data item subordinate to identifier-1 whose data description entry contains a REDEFINES or RENAMES clause or is subordinate to a data item whose data description entry contains a REDEFINES clause. However, identifier-1 may itself have a REDEFINES clause or be subordinate to a data item with a REDEFINES clause.
      4. For group table items, when the FASTINIT directive is in effect, the existing contents of filler items, data-pointers, object-references or program-pointers from the 1st table element will be propagated to the rest of the table.
    2. Second, an elementary data item is a possible receiving item if either of the following apply:
      1. It is explicitly referenced by identifier-1
      2. It is contained within the group data item referenced by identifier-1. If the elementary data items is a table element, each occurrence of the elementary data items is a possible receiving operand
    3. Finally, each possible receiving operand is a receiving operand if at least one of the following is true:
      1. The VALUE phrase is specified, the category of the elementary data item is one of the categories specified or implied in the VALUE phrase, and one of the following is true:
        1. Either the category of the elementary data item is data-pointer, object-reference, or program-pointer.
        2. A data-item format or table format VALUE clause is specified in the data description entry of the elementary data item.
      2. The REPLACING phrase is specified and the category of the elementary data item is one of the categories specified in the REPLACING phrase.
      3. The DEFAULT phrase is specified.
      4. Neither the REPLACING phrase nor the VALUE phrase is specified.
  4. The sending-operand in each implicit MOVE and SET statement is determined as follows:
    1. If the data item qualifies as a receiving-operand because of the VALUE phrase:
      1. ISO2002 MF If the category of the receiving-operand is data-pointer or program-pointer, the sending-operand is the predefined address NULL. This requires the INITPTR compiler directive to be set.
      2. ISO2002 MF If the category of the receiving-operand is object-reference, the sending-operand is the predefined object reference NULL. This requires the INITPTR compiler directive to be set.
      3. Otherwise, the sending-operand is determined by the literal in the VALUE clause specified in the data description entry of the data item. If the data item is a table element, the literal in the VALUE clause that corresponds to the occurrence being initialized determines the sending-operand. The actual sending-operand is a literal that, when moved to the receiving-operand with a MOVE statement, produces the same result as the initial value of the data item as produced by the application of the VALUE clause.
    2. If the data item does not qualify as a receiving-operand because of the VALUE phrase, but does qualify because of the REPLACING phrase, the sending-operand is the literal-1 or identifier-2 associated with the category specified in the REPLACING phrase.
    3. If the data item does not qualify in accordance with general rules 4a and 4b, the sending-operand used depends on the category of the receiving-operand as follows:
      Receiving operand | Figurative constant
      Alphabetic | Figurative constant alphanumeric SPACES
      Alphanumeric | Figurative constant alphanumeric SPACES
      Alphanumeric-edited | Figurative constant alphanumeric SPACES
      Data-pointer | Predefined address NULL
      National | Figurative constant national SPACES
      National-edited | Figurative constant national SPACES
      Numeric | Figurative constant ZEROES
      Numeric-edited | Figurative constant ZEROES
      Object-reference | Predefined object reference NULL
      Program-pointer | Predefined address NULL
  5. In all cases, the content of the data item referenced by identifier-1 is set to the indicated value in the order (left to right) of the appearance of identifier-1 in the INITIALIZE statement. Within this sequence, where identifier-1 references a group item, affected elementary items are initialized in the sequence of their definition in the group. For a variable-occurrence data item, the number of occurrences initialized is determined by the rules of the OCCURS clause for a receiving data item.
  6. If identifier-1 occupies the same storage area as identifier-2, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the topic Overlapping Operands in the chapter Procedure Division.)
Parent topic: Statements
Related information
The SET Statement
The MOVE Statement
Class and Category of Data
Overlapping Operands


INSPECT Statement (COBOL)

The INSPECT Statement

The INSPECT statement provides the ability to tally (Format 1), replace (Format 2), tally and replace (Format 3) , convert (Format 4) and tally trailing (Format 5).

General Formats for Format 1

INSPECT - Format 1

General Formats for Format 2

INSPECT - Format 2

General Formats for Format 3

INSPECT - Format 3

General Formats for Format 4

INSPECT - Format 4

General Formats for Format 5

INSPECT - Format 5

Syntax Rules for All Formats

  1. Identifier-1 must reference either a group item or any category of elementary item, described (either implicitly or explicitly) as USAGE IS DISPLAY.
  2. Identifier-3 ... identifier-n must reference

    MF either a group item or

    an elementary alphabetic, alphanumeric,

    ANS85 alphanumeric edited, numeric edited

    or numeric item described (either implicitly or explicitly) as USAGE IS DISPLAY.

  3. Each literal must be nonnumeric and can be any figurative constant, except ALL. If literal-1, literal-2 or literal-4 is a figurative constant, it refers to an implicit one-character data item.
  4. No more than one BEFORE phrase

    ANS85 and /;

    or one AFTER phrase can be specified for any one ALL, LEADING, CHARACTERS, FIRST

    ANS85 or CONVERTING

    phrase.

  5. Literal-1, literal-2, literal-3, literal-4, and literal-5, and the data items referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7 can be any number of characters in length up to the limit allowed for literals or data items.
  6. MF All identifiers, except identifier-2 (the TALLYING field), can be external floating-point items. External floating-point items are treated as if redefined as alphanumeric with the INSPECT statement referring to the alphanumeric item.

Syntax Rules for Formats 1 and 3

  7. Identifier-2 must reference an elementary numeric data item.

Syntax Rules for Formats 2 and 3

  8. The size of the data referenced by literal-3 or identifier-5 must be equal to the size of the data referenced by literal-1 or identifier-3. When a figurative constant is used as literal-3, the size of the figurative constant is equal to the size of literal-1 or the size of the data item referenced by identifier-3.
  9. When the CHARACTERS phrase is used, literal-3 or the size of the data item referenced by identifier-5 must be one character in length.

    ANS85 This restriction does not apply to literal-2 or identifier-4.

Syntax Rules for Format 4

  10. ANS85 The size of literal-5 or the data item referenced by identifier-7 must be equal to the size of literal-4 or the data item referenced by identifier-6. When a figurative constant is used as literal-5, the size of the figurative constant is equal to the size of literal-4 or the size of the data item referenced by identifier-6.
  11. ANS85 The same character must not appear more than once either in literal-4 or in the data item referenced by identifier-6.

General Rules for All Formats

  1. ANS85 For the purpose of determining its length, identifier-1 is treated as if it were a sending data item. (See the topic The OCCURS Clause.)
  2. Inspection (which includes the comparison cycle, the establishment of boundaries for the BEFORE or AFTER phrase, and the mechanism for tallying and/or replacing) begins at the leftmost character position of the data item referenced by identifier-1, regardless of its class, and proceeds from left to right to the rightmost character position as described in General Rules 11, 12 and 13.
  3. For use in the INSPECT statement, the contents of the data item referenced by identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is treated as follows:
    1. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric, the INSPECT statement treats the contents of each such identifier as a character-string.
    2. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric edited, numeric edited or unsigned numeric, the data item is inspected as though it had been redefined as alphanumeric (see General Rule 3a.) and the INSPECT statement had been written to reference the redefined data item.
    3. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as signed numeric, the data item is inspected as though it had been moved to an unsigned numeric data item with length equal to the length of the signed item excluding any separate sign position and then the rules in General Rule 3b had been applied. (See the topic The MOVE Statement.)
  4. In General Rules 6 through 19, all references to literal-1, literal-2, literal-3, literal-4, and literal-5 apply equally to the contents of the data item referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7, respectively.
  5. If any identifier is subscripted

    ANS85 or is a function-identifier

    , the subscript

    ANS85 or function-identifier

    is evaluated only once as the first operation in the execution of the INSPECT statement.

General Rules for Format 1

  6. ANS85 Identifier-1 is a sending data item.
  7. The required words ALL and LEADING are adjectives that apply to each succeeding literal-1 until the next adjective appears.
  8. The contents of the data item referenced by identifier-2 are not initialized by the execution of the INSPECT statement.
  9. The rules for tallying are as follows:
    1. If the ALL phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1.
    2. If the LEADING phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1, provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.
    3. If the CHARACTERS phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each character matched, in the sense of Format 1 and 2, General Rule 12e, in the contents of the data item referenced by identifier-1.
  10. If identifier-1, identifier-3 or identifier-4 occupies the same storage area as identifier-2, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the topic Overlapping Operands.)

General Rules for Formats 1 and 2

  11. During inspection of the contents of the data item referenced by identifier-1, each properly matched occurrence of literal-1 is tallied (Format 1) or replaced by literal-3 (Format 2).
  12. The comparison operation to determine the occurrences of literal-1 to be tallied or to be replaced, occurs as follows:
    1. The operands of the TALLYING or REPLACING phrases are considered in the order they are specified in the INSPECT statement from left to right. The first literal-1 is compared to an equal number of contiguous characters, starting with the leftmost character position in the data item referenced by identifier-1. Literal-1 matches that portion of the contents of the data item referenced by identifier-1 if, and only if, they are equal, character for character, and if one of the following is true:
      1. If neither LEADING nor FIRST is specified:
      2. If the LEADING adjective applies to literal-1 and literal-1 is a leading occurrence as defined in General Rules 9 and 15:
      3. If the FIRST adjective applies to literal-1 and literal-1 is the first occurrence as defined in General Rule 9.
    2. If no match occurs in the comparison of the first literal-1, the comparison is repeated with each successive literal-1, if any, until either a match is found or there is no next successive literal-1. When there is no next successive literal-1, the character position in the data item referenced by identifier-1 immediately to the right of the leftmost character position considered in the last comparison cycle is considered as the leftmost character position, and the comparison cycle begins again with the first literal-1.
    3. Whenever a match occurs, tallying and/or replacing takes place as described in General Rules 9 and 15. The character position in the data item referenced by identifier-1 immediately to the right of the rightmost character position that participated in the match is now considered to be the leftmost character position of the data item referenced by identifier-1, and the comparison cycle starts again with the first literal-1.
    4. The comparison operation continues until the rightmost character position of the data item referenced by identifier-1 has participated in a match or has been considered as the leftmost character position. When this occurs, inspection is terminated.
    5. If the CHARACTERS phrase is specified, an implied one-character operand participates in the cycle described in paragraphs 12a through 12d above, except that no comparison to the contents of the data item referenced by identifier-1 takes place. This implied character is considered always to match the leftmost character of the contents of the data item referenced by identifier-1 participating in the current comparison cycle.
  13. The comparison operation defined in General Rule 12 is affected by the BEFORE and AFTER phrases as follows:
    1. If neither the BEFORE nor the AFTER phrase is specified, literal-1 or the implied operand of the CHARACTERS phrase is first eligible to participate in matching at the leftmost character position of identifier-1.
    2. If the BEFORE phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase participates only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from its leftmost character position up to, but not including, the first occurrence of literal-2, in the contents of the data item referenced by identifier-1.

      The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase participates in the comparison operation as though the BEFORE phrase had not been specified.

    3. If the AFTER phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase can participate only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from the character position immediately to the right of the rightmost character position of the first occurrence of literal-2, in the contents of the data item referenced by identifier-1 to the rightmost character position of the data item referenced by identifier-1.

      The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase is never eligible to participate in the comparison operation.

General Rules for Format 2

  14. The required words ALL, LEADING and FIRST are adjectives that apply to each succeeding BY phrase until the next adjective appears.
  15. The rules for replacement are as follows:
    1. When the CHARACTERS phrase is specified, each character matched in the sense of Format 1 and 2, General Rule 12e in the contents of the data item referenced by identifier-1, is replaced by literal-3.
    2. When the adjective ALL is specified, each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.
    3. When the adjective LEADING is specified, the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3, provided that the leftmost occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.
    4. When the adjective FIRST is specified, the leftmost occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.
  16. If identifier-3, identifier-4 or identifier-5 occupies the same storage area as identifier-1, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the topic Overlapping Operands.)

General Rules for Format 3

  17. A Format 3 INSPECT statement is interpreted and executed as though two successive INSPECT statements specifying the same identifier-1 had been written with one statement being a Format 1 statement with TALLYING phrases identical to those specified in the Format 3 statement, and the other statement being a Format 2 statement with REPLACING phrases identical to those specified in the Format 3 statement. The General Rules given for matching and counting apply to the Format 1 statement and the General Rules given for matching and replacing apply to the Format 2 statement.

General Rules for Format 4

  18. ANS85 A Format 4 INSPECT statement is interpreted and executed as though a Format 2 INSPECT statement specifying the same identifier-1 had been written with a series of ALL phrases, one for each character of literal-4. The effect is as if each of these ALL phrases referenced, as literal-1, a single character of literal-4 and referenced, as literal-3, the corresponding single character of literal-5. Correspondence between the characters of literal-4 and the characters of literal-5 is by ordinal position within the data item.
  19. ANS85 If identifier-4, identifier-6 or identifier-7 occupies the same storage area as identifier-1, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.

General Rules for Format 5

  1. TRAILING is an MF extension, used to find the rightmost occurrence or set of contiguous occurrences in a source data item.

  2. If a TRAILING occurrence is found, a right to left scan of the source data item is made to find contiguous occurrences.

  3. The REPLACING option enables you to replace all contiguous occurrences.

  4. The following items must be single-character items: identifier-3, identifier-4, identifier-5, literal-1, literal-2 and literal-3.

Examples

  1. Examples of using INSPECT TALLYING, REPLACING, and CONVERTING are provided in the topic INSPECT Statement (Tallying, Replacing, and Converting).
Parent topic: Statements
Related information
The OCCURS Clause
The MOVE Statement
INSPECT Statement (Tallying, Replacing, and Converting)
Overlapping Operands


INVOKE Statement (COBOL)

The INVOKE Statement

The INVOKE statement causes a method to be invoked.

General Format

Syntax Rules

  1. Object-identifier-1 must be an object reference or a class-name.
  2. MF Identifier-1 must be a four-byte data item.
  3. Literal-1 must be an alphanumeric literal.
  4. Neither literal-1 nor literal-2 may be a figurative constant.
  5. ISO2002 If object-identifier-1 references a universal object reference, neither the BY CONTENT nor BY VALUE phrase can be specified and the BY REFERENCE phrase, if not specified explicitly, is assumed implicitly.

    MF The BY CONTENT and BY VALUE phrases can be specified.

  6. Identifier-2 must be defined as an alphanumeric data item.
  7. ISO2002 If identifier-2 is specified, object-identifier-1 must be a universal object reference.

    MF Object-identifier-1 is not required to be a universal object reference.

  8. If the data item referenced by identifier-1 is not a universal object reference, the rules for conformance as specified in the topic Conformance for Parameters and Returning Items in the chapter Procedure Division apply.
  9. If the data item referenced by identifier-1 is not a universal object reference and a BY CONTENT or BY REFERENCE phrase is specified for an argument, a BY REFERENCE phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.
  10. Identifier-3 must reference a data item defined in the File, Working-Storage,

    MF Object-Storage,

    Local-Storage, or Linkage Section.

  11. MF Neither identifier-4, identifier-5, identifier-6, identifier-7, nor identifier-8 can be a function-identifier.
  12. If a BY VALUE phrase is specified for an argument, a BY VALUE phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.
  13. MF Integer-1 may be signed or zero.
  14. MF GIVING and RETURNING are equivalent.
  15. MF Identifier-10 must be defined as a data item in the Linkage Section with a level number of 01 or 77.
  16. Identifier-3 is both a sending and receiving operand.
  17. Identifier-1, identifier-2, identifier-4, identifier-5, identifier-6, identifier-7, identifier-8 and any identifier specified in arithmetic-expression-1 are sending operands.
  18. Identifier-9 and identifier-10 are receiving operands.
  19. If an OMITTED phrase is specified, an OPTIONAL phrase must be specified for the corresponding formal parameter in the PROCEDURE DIVISION header.

General Rules

  1. The instance of the program, function or method that executes the INVOKE statement is the activating runtime element.
  2. Object-identifier-1

    MF or identifier-1

    identifies an object instance. If object-identifier-1 is specified as a class-name, object-identifier-1 identifies the factory object of that class-name. Literal-1 or the content of the data item referenced by identifier-2 identifies a method of that object that will act upon that object instance:

    1. If the method to be invoked is a COBOL method, literal-1 or the content of the data item referenced by identifier-2 is the name of the method to be invoked as specified in its Method-ID paragraph.

      If the object instance is identified by a universal object reference, neither a formal parameter nor the returning item in the invoked method may be described with the ANY LENGTH clause

    2. If the method to be invoked is not a COBOL method, the rules for the formation of the method-name are dependent upon the domain involved.
  3. MF The AS phrase enables you to invoke methods on a COBOL data item. If template-1 is specified, it is used as a class template. Creation of templates is a function provided by objects in the supplied Class Library. (See your COBOL system documentation for details.)
  4. When an INVOKE statement is executed, the method specified is made available for execution and control is transferred to the invoked method. If the invoked method is a COBOL method, its execution is as described in the topic General Rules in the topic The PROCEDURE DIVISION Header; otherwise, the execution is defined by the implementor of the language in which the method is written. After control is returned from the method, control is transferred to the end of the INVOKE statement.
  5. The run unit is not aware of whether an invoked method is a COBOL method or a non-COBOL method until the invoked method has been located, prior to being made available for execution. The form of the method-name cannot be used to determine whether the method is a COBOL method or not.
  6. The process of invoking a method or exiting from an invoked method does not alter the status or positioning of a file associated with any external file connector.
  7. This implementation does not maintain any synchronization between the arguments and the Linkage Section data items. That is your responsibility.
    Note: The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:
    • Modifying group items to include additional filler items
    • Ensuring operands in the USING phrase are level 01 or level 77 data items in conjunction with the ALIGN Compiler directive or
    • Use of the SYNCHRONIZED clause in conjunction with the IBMCOMP Compiler directive

    If a RETURNING phrase is specified on the INVOKE statement, a non-COBOL method must return a result in the appropriate format.

  8. The sequence of arguments in the USING phrase of the INVOKE statement and the corresponding formal parameters in the USING phrase of the invoked method's PROCEDURE DIVISION header determines the correspondence between arguments and formal parameters. This correspondence is positional and not by name equivalence; the first argument corresponds to the first formal parameter, the second to the second, etc.

    If a parameter is an index-name, no such correspondence is established. Index-names in the invoked method and the invoking runtime element always refer to separate indices.

    The effect of the USING phrase on the activated runtime element is described in as described in the topic General Rules in the topic The PROCEDURE DIVISION Header

  9. An argument that consists merely of a single identifier or literal is regarded as an identifier or literal rather than an arithmetic expression.
  10. The values of the parameters referenced in the USING phrase of the INVOKE statement are made available to the invoked method at the time the INVOKE statement is executed.
  11. The BY CONTENT, BY REFERENCE and BY VALUE phrases are transitive across the parameters that follow them until another BY CONTENT, BY REFERENCE or BY VALUE phrase is encountered.

    If no BY CONTENT, BY REFERENCE or BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

  12. If the BY REFERENCE ADDRESS OF phrase is specified or implied then the method operates as if a data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-4 statement.
  13. If the BY CONTENT phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, although the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's PROCEDURE DIVISION header. The data description of each parameter in the BY CONTENT phrase of the INVOKE statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the PROCEDURE DIVISION header.

    If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-5 is specified then both the implied data description of the additional data item and its contents are identical to that of identifier-5. If literal-3 is specified then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-3 and with its contents set to the value of literal-3. If LENGTH OF identifier-6 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-6.

  14. If the BY VALUE phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, though the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's PROCEDURE DIVISION header. The method operates, conceptually, as if an additional data item had been declared in a system area (typically the stack), available to non-COBOL languages for passing parameters and this additional data item occupies the same storage area as the data item in the invoked method.

    If identifier-7 is specified and is BINARY, COMP-4, COMP-5 or COMP-X, then the data description of the additional data item is identical to that of identifier-7, except its usage is COMP-5. The contents of the additional data item are identical to the COMP-5 representation of the contents of identifier-7. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-7 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-7.

    If integer-1 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage indicated by the value of integer-2, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).

    If LENGTH OF identifier-8 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-8.

    If the method being invoked is a COBOL method, each parameter in the BY VALUE phrase of the INVOKE statement must have a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    The additional data item generated as a result of the INVOKE statement, described above, is related to this corresponding parameter in the invoked method, as follows.

    • If the additional data item was subject to conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the corresponding parameter in the invoked method must be identical to that of the data description of the additional data item with the exception that the corresponding parameter's usage can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the invoked COBOL method, a conversion from the USAGE COMP-5 of the additional data item to the USAGE of the corresponding parameter in the invoked method is performed.
    • If the additional data item was not subject to conversion to COMP-5, the data description of each parameter in the invoked method must be the same as the corresponding additional data item. This means there is no conversion or extension or truncation, of the additional data item to match the corresponding parameter in the invoked method.

    If the method being invoked is non-COBOL, the details of when you need to use the BY VALUE phrase are dependent on the domain involved.

  15. MF If identifier-4 is in the Linkage Section and has a level number other than 01 or 77 or is in the Working-Storage Section, the item is passed as if BY CONTENT had been specified and the address of identifier-4 cannot be modified by the invoked method.
  16. MF If the BY REFERENCE literal-2 phrase is specified or implied then the method processes literal-2 as described for literal-3.
  17. MF If LENGTH OF identifier-6 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-6.
  18. MF If integer-1 is specified then the implied data description of the argument is a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage specified by the value of integer-2, if specified, or 4 bytes otherwise.
  19. MF If LENGTH OF identifier-8 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-8.
  20. MF If identifier-10 is specified, the invoked method must return a value with explicit or implicit USAGE POINTER. The result of the method is assigned to identifier-10 using the rules for the SET statement.
  21. Invoked methods may contain INVOKE statements. An invoked method may execute an INVOKE statement that directly or indirectly invokes the invoking method.
  22. If an OMITTED phrase is specified or a trailing argument is omitted, the omitted-argument condition for that parameter is true in the invoked method.
  23. If a parameter for which the omitted-argument condition is true is referenced in an invoked method, except as an argument or in the omitted-argument condition, you will get RTS error message 203.
Parent topic: Statements
Related information
Conformance for Parameters and Returning Items
The PROCEDURE DIVISION Header


JSON GENERATE Statement (COBOL)

The JSON GENERATE Statement

The JSON GENERATE statement converts data to JSON format.

General Format

JSON GENERATE Statement

Syntax Rules

  1. Identifier-1 must be either: an elementary data item of category alphanumeric; an alphanumeric group item; an elementary data item of category national; or a national group item
  2. When identifier-1 is a national group item, identifier-1 is processed as an elementary data item of category national.
  3. When identifier-1 is an alphanumeric group item, identifier-1 is treated as though it were an elementary data item of category alphanumeric.
  4. Identifier-1 must not be defined with the JUSTIFIED clause.
  5. Identifier-1, identifier-2, identifier-4, or identifier-5 cannot be a function identifier.
  6. Identifier-1 can be subscripted or reference modified.
  7. Identifier-1 must not overlap identifier-2 or identifier-3.
  8. The generated JSON text is encoded in UTF-16 big-Endian (codepage 1200) if identifier-1 is of category national; otherwise, it is encoded in UTF-8 (codepage 1208).
  9. Identifier-1 must be large enough to contain the generated JSON text. Typically, it should be from 2 to 3 times the size of identifier-2, depending on the lengths of the data-names within identifier-2. If identifier-1 is not large enough, an exception condition exists at the end of the JSON GENERATE statement. If the COUNT phrase is specified, identifier-3 contains the number of character encoding units that were actually generated.
  10. If the SUPPRESS phrase is in effect, identifier-1 must still be large enough to contain the generated JSON text before suppression.
  11. Identifier-2 cannot be reference modified, but it can be subscripted.
  12. Identifier-2 must not overlap identifier-1 or identifier-3, or must not specify the RENAMES clause.
  13. If identifier-2 is set to any of the following, they are ignored by the JSON GENERATE statement: any subordinate unnamed elementary data items or elementary FILLER data items; any slack bytes inserted for SYNCHRONIZED items; any data item subordinate to identifier-2 that is defined with the REDEFINES clause or that is subordinate to such a redefining item; any data item subordinate to identifier-2 that is defined with the RENAMES clause; and any group data item whose subordinate data items are all ignored.
  14. All data items specified by identifier-2 that are not ignored according to the previous rules must satisfy the following conditions: each elementary data item must have a USAGE other than POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE; there must be at least one such elementary data item; and each non-FILLER data-name must be unique within any immediately superordinate group data item.
  15. Identifier-3 must be an integer data item defined without the symbol P in its picture string.
  16. Identifier-3 must not overlap identifier-1, identifier-2, identifier-4, or identifier-5.
  17. Identifier-4 must reference identifier-2 or one of its subordinate data items.
  18. Identifier-4 or identifier-5 cannot be reference modified or subscripted.
  19. Identifier-4 cannot specify any data item which is ignored by the JSON GENERATE statement.
  20. Literal-1 must be an alphanumeric or national literal containing the name to be generated in the JSON text corresponding to identifier-4.
  21. Identifier-5 must reference a data item that is subordinate to identifier-2 and that is not otherwise ignored by the operation of the JSON GENERATE statement.

General Rules

  1. Identifier-1 is the receiving area for the generated JSON text.
  2. Identifier-2 is the group or elementary data item to be converted to JSON format.
  3. If the COUNT phrase is specified, identifier-3 contains (after successful execution of the JSON GENERATE statement) the count of generated JSON character encoding units. If identifier-1 (the receiver) is of category national, the count is in double-bytes. Otherwise, the count is in bytes.
  4. The NAME phrase enables you to override the default JSON names derived from identifier-2 or its subordinate data items.
  5. If the NAME phrase specifies identifier-4 more than once, the last specification is used.
  6. The SUPPRESS phrase enables you to selectively generate output for the JSON GENERATE statement by allowing you to identify and unconditionally exclude items that are subordinate to identifier-2.
  7. If identifier-5 specifies a group data item, that group data item and all subordinate data items are excluded.
  8. Duplicate specifications of identifier-5 are permitted.
  9. When the SUPPRESS phrase is specified, a group item subordinate to identifier-2 is excluded from the generated JSON text if all eligible items subordinate to the group item are excluded. The outermost object that corresponds to identifier-2 itself is always generated, even if all subordinate items to identifier-2 are excluded. In this case, the value generated for identifier-2 is an empty object, as follows :
    {“identifier-2”:{}}

    Unless explicitly suppressed, an ODO table with no elements is always retained in the JSON text as follows:

    {“table-name”:[]}
  10. If the ON EXCEPTION phrase is specified, control transfers to imperative-statement-1 when an error occurs during generation of the JSON document.
  11. If the ON EXCEPTION phrase is not specified, the NOT ON EXCEPTION phrase, if any, is ignored, and control is transferred to the end of the JSON GENERATE statement in the event of an error.
  12. In the event of an error, the JSON-CODE special register contains the exception code; see JSON-CODE Exception Codes for more information.
  13. If an exception condition does not occur during generation of the JSON document, control is passed to imperative-statement-2, if specified; otherwise, control is passed to the end of the JSON GENERATE statement. The ON EXCEPTION phrase, if specified, is ignored, and special register JSON-CODE contains zero after execution of the JSON GENERATE statement.
  14. The END-JSON phrase is the scope terminator that delimits the scope of the statement.
  15. Use of END-JSON allows a conditional JSON GENERATE statement (that is, a JSON GENERATE statement that specifies the ON EXCEPTION or NOT ON EXCEPTION phrase) to be nested in another conditional statement.
  16. The scope of a conditional JSON GENERATE statement can be terminated by either an END-JSON phrase or a separator period.
  17. END-JSON can also be used with a JSON GENERATE statement that does not specify either the ON EXCEPTION or the NOT ON EXCEPTION phrase.
  18. JSON GENERATE statements that appear in imperative-statement-1 or imperative-statement-2 of another JSON GENERATE statement are nested JSON GENERATE statements. Nested JSON GENERATE statements are considered to be matched JSON GENERATE and END-JSON combinations, proceeding from left to right. Thus, any END-JSON phrase that is encountered is matched with the nearest preceding JSON GENERATE statement that has not been implicitly or explicitly terminated.
  • Appendix A - JSON GENERATE Source Items
  • Appendix B - JSON Output Text
  • Appendix C - Elementary Data Format Conversions
  • Appendix D - Trimming of Generated JSON Data
  • Appendix E - JSON Name Formation
Parent topic: Statements


Appendix A - JSON GENERATE Source Items

The following data declaration is specified as the source intended to be converted to JSON format.

01 JSON-SRC-GRP.
  03 SRC-STAT PIC X(4).
  03 SRC-AREA PIC X(100).
  03 VAL-AREA REDEFINES SRC-AREA.
     05 FLAGS PIC X.
     05 PIC X(3).
     05 COUNTER USAGE COMP-5 PIC S9(9).
     05 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
     05 UNREFERENCED PIC X(92).
  03 INVAL-AREA1 REDEFINES SRC-AREA.
     05 FLAGS PIC X.
     05 PIC X(3).
     05 PTR USAGE POINTER.
     05 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9).
     05 PIC X(92).
  03 INVAL-AREA2 REDEFINES SRC-AREA.
     05 FN-CODE PIC X.
     05 UNREFERENCED PIC X(3).
     05 QTYONHAND USAGE BINARY PIC 9(5).
     05 DESC USAGE NATIONAL PIC N(40).
     05 UNREFERENCED PIC X(12).

In line with the syntax rules, the following data items, when specified as identifier-2, would be converted in a JSON GENERATE statement:

  • JSON-SRC-GRP, of which subordinate data items SRC-STAT and SRC-AREA would be converted to JSON format. VAL-AREA, INVAL-AREA1, and INVAL-AREA2 are ignored because they specify the REDEFINES clause.
  • VAL-AREA, of which subordinate data items FLAGS, COUNTER, and UNREFERENCED would be converted. The item whose data description entry specifies 05 PIC X(3) is ignored because it is an elementary FILLER data item. ASFNPTR is ignored because it specifies the REDEFINES clause.
  • Any of the elementary data items that are subordinate to JSON-SRC-GRP, except:
    • ASFNPTR or PTR (disallowed usage)
    • UNREFERENCED OF INVAL-AREA2 (non-unique names for data items that are otherwise eligible)
    • Any FILLER data items
The following data items cannot be specified as identifier-2:
  • INVAL-AREA1, because subordinate data item PTR specifies USAGE POINTER but does not specify the REDEFINES clause. (PTR would be ignored if it is defined with the REDEFINES clause.)
  • INVAL-AREA2, because subordinate elementary data items have the non-unique name UNREFERENCED.
Parent topic: The JSON GENERATE Statement


Appendix B - JSON Output Text

The JSON generation process converts each eligible elementary data item within identifier-2, unless it has been suppressed, to character format. Only the first definition of each storage area is processed.

The following elementary data items are not eligible:

  • Redefined data items
  • Date items defined by RENAMES clause
  • Table items that have zero occurrences
    Note: If one or more zero occurrence tables are the only subordinate data items in their containing (immediately superordinate) group, the containing group item is included in the JSON text with the special value null.

For information about the format conversion of elementary data, see Appendix D - Format Conversion of Elementary Data and Appendix E - Trimming of Generated JSON Data. The JSON names are obtained from the NAME phrase if specified; otherwise by default they are derived from the data-names within identifier-2 as described in Appendix F - JSON Name Formation.

The names of group items that contain the selected elementary items are retained as the names of parent JSON objects.

No extra white space (new lines, indentation, and so forth) is inserted to make the generated JSON text more readable.

If identifier-1 (the target area) is not large enough to contain the JSON text after generation, an exception condition exists. Use the ON EXCEPTION phrase to control processing in the event of an exception; see The JSON GENERATE Statement for more details.

If identifier-1 is larger than the JSON text, any existing data beyond the size of the JSON text will remain in identifier-1 after the JSON GENERATE statement. To avoid referring to that data, either initialize identifier-1 to spaces before the JSON GENERATE statement or specify the COUNT phrase.

If you use the COUNT phrase, after successful execution of the JSON GENERATE statement, identifier-3 contains the total number of character positions (UTF-16 encoding units or bytes) that were generated. Use this value as a reference modification length field to refer to the part of identifier-2 that contains the generated JSON text.

After execution of the JSON GENERATE statement, special register JSON-CODE contains either zero, which indicates successful completion, or a nonzero exception code. For details, see JSON-CODE Exception Codes.

A byte order mark is not generated for JSON texts.

Parent topic: The JSON GENERATE Statement
Related reference
Appendix C - Elementary Data Format Conversions
Appendix D - Trimming of Generated JSON Data
Appendix E - JSON Name Formation
JSON-CODE Exception Codes


Appendix C - Elementary Data Format Conversions

Elementary data items within identifier-2 are converted in the sequence of the following steps. Some of these steps are optional.

Conversion to character format:

Elementary data items are converted to character format depending on the type of the data item:

  • The following data items are not converted to character format, except when Unicode encoding is required:
    • alphabetic
    • alphanumeric
    • alphanumeric-edited
    • DBCS
    • external floating-point
    • national
    • national-edit
    • numeric-edited
  • The following data items are converted to character format:
    • fixed-point numeric
      • Fixed-point numerics other than COMPUTATIONAL-5 (COMP-5) binary data items or binary data items compiled with the TRUNC(BIN) Compiler directive are converted as if they were moved to a numeric-edited item that has:
        • As many integer positions as the numeric item has, but with at least one integer position (possibly zero), and the same number of decimal positions as the numeric item
        • An explicit decimal point, if the numeric item has at least one decimal position; the DECIMAL-POINT IS COMMA clause in the SPECIAL-NAMES paragraph, if specified, is ignored.
        • A leading '-' picture symbol if the data item is signed (that is, has an S in its PICTURE clause)
      • Fixed-point numerics that are COMPUTATIONAL-5 (COMP-5) binary data items or binary data items compiled with the TRUNC(BIN) compiler option are converted as those above except that the number of decimal positions is dependent on the number of '9' symbols in the picture character string:
        • 5 minus the number of decimal places, if the data item has 1 to 4 '9' picture symbols
        • 10 minus the number of decimal places, if the data item has 5 to 9 '9' picture symbols
        • 20 minus the number of decimal places, if the data item has 10 to 18 '9' picture symbols
    • internal floating-point
      • Internal floating-point data items are converted as if they were moved to a data item as follows:
        • For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
        • For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99 (illegal because of the number of digit positions)
    • external floating-point
      • External floating-point data items are converted as if they were moved to another external floating-point data item with the same precision and scale, and with:
        • A - sign for the mantissa.
        • An actual decimal point, indicated by a . PICTURE symbol.
        • A + sign for the exponent.

        For example, an external floating-point item defined with PICTURE -9(4)V9(2)E-99 would be converted as if it were moved to an external floating-point item defined with PICTURE -9(4).9(2)E+99.

    • index data items
      • Index data items are converted as if they were declared USAGE COMP-5 PICTURE S9(9).

Trimming

Trimming occurs after any conversion to character format; see Appendix E - Trimming of Generated JSON Data for more information.

Conversion to the target encoding

All values are represented in UTF-8 format unless identifier-1 is a national data item; in which case, any non-national values are converted to national format.

Escaping characters

The following table shows the conversion of common characters to their two-character escape sequences:

Note: The characters NX'0022' (") and NX'005C' (\) are escaped as \" and \\, respectively.
Coded value | Escape sequence | Description
NX'0008' | \b | backspace
NX'0009' | \t | tab
NX'000A' | \n | line feed
NX'000C' | \f | form feed
NX'000D' | \r | carriage return
NX'0085' | \x | next line

The remaining characters in the range NX'0000' through NX'001F' are escaped as \uhhhh, where h represents a hexadecimal digit 0 through F.

Parent topic: The JSON GENERATE Statement
Related reference
Appendix D - Trimming of Generated JSON Data


Appendix D - Trimming of Generated JSON Data

Data values are trimmed once they have been converted to character format.

For more information about the conversion process, see Appendix D - Elementary Data Format Conversions.

The leading space, if positive, is removed for values converted from signed numeric data items. The leading zeroes (after any initial minus sign) up to but not including the digit immediately before the actual or implied decimal point are eliminated for values converted from numeric items. The trailing zeroes after a decimal point are retained. For example:

  • -0063.435 becomes -63.435
  • 0000.022 becomes 0.022
  • 0044 becomes 44
  • 0000 becomes 0

Trailing or leading spaces are removed from character values for data items of class alphabetic, alphanumeric, DBCS, and national, depending on whether the corresponding data items have left (default) or right justification, respectively. That is, trailing spaces are removed from values whose corresponding data items do not specify the JUSTIFIED clause. Leading spaces are removed from values whose data items do specify the JUSTIFIED clause. If a character value consists solely of spaces, one space remains as the value after trimming is finished.

Parent topic: The JSON GENERATE Statement
Related reference
Appendix C - Elementary Data Format Conversions


Appendix E - JSON Name Formation

The names used in the JSON output text are taken from the NAME phrase if specified; otherwise they are derived from the name of the data item specified by identifier-2 and from any eligible data-names that are subordinate to identifier-2. The exact mixed-case spelling of data-names from the data description entry is retained. The spellings from any references to data items (for example, in an OCCURS DEPENDING ON clause) are not used.

Parent topic: The JSON GENERATE Statement


JSON PARSE Statement (COBOL)

The JSON PARSE Statement

The JSON PARSE statement converts JSON text to COBOL data formats. It matches the JSON name/value pairs to COBOL identifiers, and then populates them.

General Format

JSON PARSE Statement

General Rules

  1. Identifier-1 is the data item that contains the JSON text.
  2. The JSON text identified by identifier-1 is assumed to be encoded in UTF-8.
  3. If identifier-1 contains invalid JSON syntax, the statement terminates with an exception condition, and identifier-2 may be partially modified.
  4. Identifier-2 is the group or elementary item populated with the JSON text.
  5. When the WITH DETAIL phrase is specified, JSON PARSE generates run-time error messages when it encounters both non-exception and exception conditions.
  6. The NAME OF phrase enables you to use a different data name than the one required by the matching algorithm when matching the name of a JSON name/value pair to a COBOL data item. See Appendix C - Matching Algorithm Examples for more information.
  7. The NAME OF phrase must not result in an ambiguous name specification, and is in effect during the execution of the JSON PARSE statement.
  8. The SUPPRESS phrase enables you to exclude items that are subordinate to identifier-2 from being parsed.
  9. When an exception occurs, if the ON EXCEPTION phrase is specified, control is passed to imperative-statement-1, and the NOT ON EXCEPTION phrase, if specified, is ignored. If the ON EXCEPTION phrase is not specified, control is transferred to the end of the statement. Such conditions can occur when the JSON text is ill-formed or there are problems populating identifier-2 with the JSON text.
  10. When an exception occurs, the parsing operation is halted, but identifier-2 may be partially modified.
  11. On exception, special register JSON-CODE contains the exception code; see JSON-CODE Exception Codes.
  12. The special register JSON-STATUS may also contain a non-zero value, indicating one or more non-exception conditions that occurred before the exception occurred. See JSON-STATUS Non-Exception Codes.
  13. If an exception does not occur, and the NOT ON EXCEPTION phrase is specified, control is passed to imperative-statement-2; otherwise control is transferred to the end of the statement, and special register JSON-CODE contains zero after statement execution.
  14. Non-exception conditions during statement execution can result in special register JSON-STATUS being set to a nonzero value, and identifier-2 may be partially modified.
  15. During parsing, whitespace characters (SP, HT, LF, and CR) are ignored, except within strings, and are illegal within numbers.

Syntax Rules

  1. Identifier-1 must reference one of the following: an elementary data item of category alphanumeric; an alphanumeric group item.
  2. When identifier-1 references an alphanumeric group item, it is treated as though it is an elementary data item of category alphanumeric.
  3. Identifier-1 must not be defined with the JUSTIFIED clause.
  4. Identifier-1 cannot be a function identifier.
  5. Identifier-1 can be subscripted or reference modified.
  6. Identifier-1 must not overlap identifier-2.
  7. Identifier-2 must be an alphanumeric group item, or elementary data item of category alphanumeric
  8. Identifier-2, the group or elementary item destined to hold the JSON text, cannot be reference modified, but it can be subscripted.
  9. Identifier-2 cannot be a function identifier.
  10. Identifier-2 must not overlap identifier-1.
  11. Identifier-2 must not specify the UNBOUNDED or RENAMES clause. Subordinate data must also not specify the UNBOUNDED clause.
  12. The following data items specified by identifier-2 are ignored by the JSON PARSE statement:
    • Subordinate unnamed elementary data items.
    • Elementary FILLER data items.
    • Slack bytes inserted for SYNCHRONIZED data items.
    • Subordinate items defined with the REDEFINES clause, or items subordinate to such a redefining item.
    • Subordinate items defined with the RENAMES clause.
    • Any group item whose subordinate data items are all ignored.
  13. Data items specified by identifier-2 that are not ignored according to the previous rules must adhere to the following:
    • There must be at least one elementary data item.
    • Elementary data items must have a USAGE other than DISPLAY-1, FUNCTION-POINTER, INDEX, OBJECT REFERENCE, POINTER, or PROCEDURE-POINTER.
    • Each non-FILLER data name must be unique within identifier-2.
    • If the data declaration of identifier-2, or any of its subordinate items, contains the OCCURS DEPENDING ON clause, then the target of that clause must not be subordinate to identifier-2. Thus, any objects of OCCURS DEPENDING ON clauses are not updated by the JSON PARSE statement.
  14. Identifier-3 must reference identifier-2 or one of its subordinates.
  15. Identifier-3 cannot be a function identifier, reference modified or subscripted.
  16. Identifier-3 cannot specify any data item that is ignored according to the above restrictions.
  17. Identifier-3 may be specified more than once, but only the last specification is used.
  18. Literal-1 must be alphanumeric or a national literal containing the JSON name to be associated with identifier-3.
  19. Identifier-4 must reference an item that is subordinate to identifier-2 and that is not otherwise ignored according to the above restrictions.
  20. Identifier-4 cannot be a function identifier, subscripted or reference modified.
  21. Identifier-4 can reference an entire table.
  22. If identifier-4 specifies a group item, that group item and all of its subordinates are excluded.
  23. Duplicate specifications of identifier-4 are permitted.
  24. If a data item is specified in both the NAME phrase and the SUPPRESS phrase, it is excluded.
  • Appendix A - JSON PARSE Example
  • Appendix B - Parsing JSON Arrays
  • Appendix C - JSON PARSE Matching Algorithm
  • Appendix D - Size and Precision Handling
  • Appendix E - Suppressing Population of COBOL Items During Parsing
Parent topic: Statements


Appendix A - JSON PARSE Example

The following example demonstrates how you can parse a JSON text string into a COBOL group item.

Consider the following JSON text string:

{"msg":{"SND":9,"pid":1289,"txt":"Hello World!"}}

If you pass the string into the following COBOL program, you can see how it can be parsed, at which point you can query and manipulate the results:

       Identification division.
       Program-id. jparse1.
       Data division.
       Working-storage section.
       01 msg.
         03 snd usage comp-1.
         03 pid pic 9999 usage display.
         03 txt pic x(12).
       Linkage section.
       01 json-str pic x(53).
       Procedure division using json-str.
       display "Parsing....".
       JSON PARSE json-str into msg with DETAIL
       END-JSON.
       if snd equal to 9 then
          display "PID is " pid
          display "Message text is '" txt "'"
       end-if.
       goback.
       End program jparse1.

As a result of executing the JSON PARSE statement, the group msg is populated with the three values from the JSON text name/value pairs. At this point, you can manipulate the text in any way that you wish.

Parent topic: The JSON PARSE Statement
Related information
Appendix B - Parsing JSON Arrays
Appendix C - JSON PARSE Matching Algorithm
Appendix D - Size and Precision Handling
Appendix E - Suppressing Population of COBOL Items During Parsing


Appendix B - Parsing JSON Arrays

If the JSON text string contains an array, it can be parsed into COBOL data items containing the OCCURS or OCCURS DEPENDING ON clauses.

Each JSON array should have the same number of elements as the associated table data item. If the JSON array has fewer elements, additional COBOL table elements are not modified, but if the JSON array has more values than the matching table item, the additional values are ignored. Both of these scenarios results in a nonzero JSON-STATUS setting.

Consider the following JSON text string:

{"mem-file":{"rec":[{"SND":9,"pid":1289,"txt":"Hello"},{"SND":9,"pid":1478,"txt":"World"},
{"SND":9,"pid":8746,"txt":"!"}]}}

If you pass the string into the following COBOL program, you can see how it can be parsed, at which point you can query and manipulate the results:

       Identification division.
       Program-id. jparse1.
       Data division.
       Working-storage section.
       01 mem-file.
           03 rec occurs 3.
               05 snd usage comp-1.
               05 pid pic 9999 usage display.
               05 txt pic x(12).
       01 cnt pic 9 value zeroes.
       Linkage section.
       01 json-str pic x(128).
       Procedure division using json-str.
       display "Parsing....".
       JSON PARSE json-str into mem-file with DETAIL
       END-JSON.
       perform 3 times
           add 1 to cnt
           if snd(cnt) equal to 9 then
               display "PID is " pid(cnt)
               display "Message text is '" txt(cnt) "'"
           end-if
       end-perform.
       display "Status is: " JSON-STATUS.
       display "Code is: " JSON-CODE.
       goback.
       End program jparse1.

As a result of executing the JSON PARSE statement, the group rec is populated with the three elements from the JSON array. At this point, you can manipulate the text in any way that you wish by using the matched COBOL data item and table indices.

The special value null can be used to skip assignment of the corresponding data item or occurrence. For example, parsing the JSON text would result in setting only the third and fifth occurrences of the myTable data item:

Consider the following JSON text:

{"mt":{"myTable":[null, null, 21, null,66]}}

When the text is parsed into a COBOL table, only the third and fifth table indices are populated. A non-exception code (64) is produced for the other indices.

Parent topic: The JSON PARSE Statement
Related information
Appendix A - JSON PARSE Example
Appendix C - JSON PARSE Matching Algorithm
Appendix D - Size and Precision Handling
Appendix E - Suppressing Population of COBOL Items During Parsing


Appendix C - JSON PARSE Matching Algorithm

A name-matching algorithm controls the parsing operation, where the COBOL data structure must match the JSON text string exactly, except that omissions of complete elementary or group levels are tolerated in the JSON text.

The name matching between JSON names and COBOL data names is case insensitive. That is, for both the JSON name and the COBOL data name, each lowercase single-byte alphabetic letter (a-z) is considered to be equivalent to its corresponding single-byte uppercase alphabetic letter (A-Z). However, when the NAME phrase is specified, after the NAME phrase literal has been converted by the Compiler to Unicode UTF-8, the literal must match the JSON name exactly in a case sensitive match.

The JSON PARSE statement terminates without an exception, and with special registers JSON-STATUS and JSON-CODE containing zero if, for each elementary data item subordinate to identifier-2, there is exactly one matching appropriately qualified JSON name/value pair, regardless of the order in the JSON text.

There are a number of other conditions during execution that might result in a nonzero JSON-STATUS value, or an exception and a nonzero JSON-CODE value. For example, if any combination of JSON value and COBOL data type is invalid, the statement terminates with an exception condition.

If there are JSON name/value pairs that do not match any data item names in the COBOL group/elementary item, they are allowed, but result in setting the special register JSON-STATUS to a condition code, and can result in one or more runtime messages, under control of the WITH DETAIL phrase.

If there are no matching COBOL data items, the statement terminates with an exception condition, and the COBOL group/elementary item is unmodified.

The following examples show what is considered a match and what is considered a mismatch when the name-matching algorithm is executed.

The special values true and false are not supported, and result in an exception condition if present as the value of a JSON name that matches a data item in the receiver.

The following two examples are considered an exact match:

The COBOL data definition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "8_": 8, "a-A": "VOID"}}}

If you were to use the JSON GENERATE statement, specifying the COBOL data definition, it would produce the following JSON text, which is also considered an exact match for the JSON text above:

{"Grp-1": {"a": {"grk": "ERK*VML", "8_": 8, "A-a": "Void"}}}

The COBOL data definition and JSON text can also match even if the JSON text omits certain elements of the structure, as long as the level matches. For example, the following examples are considered a match even though the JSON text has omitted the elementary item 8_ and group item AddTxt - a JSON PARSE operation would not modify those two items in the structure, and would generate a JSON-STATUS of 1 (a run-time message may also be produced if the WITH DETAIL phrase is specified):

The COBOL data definition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).
    03 AddTxt.
       05 dt pic 9(6).
       05 not pic x(50).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "a-A": "VOID"}}}

Conversely, additional items in the JSON text are tolerated, but generate non-zero JSON-STATUS codes and run-time messages. The following examples are compatible, and a JSON PARSE operation would completely populate Grp-1, but leave the JSON name/value pair "X-X": "Y" untouched. The statement would terminate without an exception code, but the special register JSON-STATUS is set to a reason code of 2:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "8_": 8, "X-X": "Y", "a-A": "VOID"}}}

These two examples are also considered fully compatible, even though the order of the items is mismatched:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"a-A": "VOID", "GrK": "ERK*VML", "8_": 8}}}

Whereas, these two examples are not considered compatible, because the JSON text is missing a matching name equivalent to group item a. This operation would result in an exception condition, because no data item would be changed:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"a-A": "VOID", "GrK": "ERK*VML", "8_": 8}}

These two examples are also not considered compatible, because the JSON text values and their COBOL data definition values are incompatible. This operation would result in an exception condition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": 33, "8_": "eight", "a-A": 657}}}

When JSON names contain characters that are not permitted to be used in COBOL data names, use the NAME phrase to supply a compliant alias for use as a COBOL data name. For example, the following JSON name is not permitted as a COBOL data name:

{"x>z":250}

Therefore, by specifying the NAME phrase in the JSON PARSE statement, you can continue to handle its JSON value with a valid COBOL name (my-sub):

JSON PARSE j-text into j-data
           NAME OF my-sub is "x>z"
END-JSON.

When using the NAME phrase, you must specify the JSON name exactly how it appears in the JSON string. Unlike the other matching algorithms, it is not case insensitive. Also, the NAME phrase must not result in an ambiguous name specification.

Parent topic: The JSON PARSE Statement
Related information
Appendix A - JSON PARSE Example
Appendix B - Parsing JSON Arrays
Appendix D - Size and Precision Handling
Appendix E - Suppressing Population of COBOL Items During Parsing


Appendix D - Size and Precision Handling

During JSON PARSE processing, the JSON value may exceed the size, length or precision of the matching COBOL data item. When this occurs, the operation continues with a loss of significance, and reason code 128 or 256 may be set in the JSON-STATUS special register. If the WITH DETAIL phrase is specified, a run-time message may also be produced.

JSON-STATUS special register value 128 and 256

The JSON-STATUS special register is set to the following values in the following circumstances:

128
Signifies a loss of precision when matching a fixed-point integer, fixed-point non-integer, or floating-point JSON value to the COBOL item. This occurs after decimal point alignment, when the JSON value exceeds the value that the COBOL item is capable of holding. JSON string values containing only digits can also cause this value to be set.
256
Signifies a loss of information from a JSON string value.
Parent topic: The JSON PARSE Statement
Related information
Appendix A - JSON PARSE Example
Appendix B - Parsing JSON Arrays
Appendix C - JSON PARSE Matching Algorithm
Appendix E - Suppressing Population of COBOL Items During Parsing


Appendix E - Suppressing Population of COBOL Items During Parsing

Consider the following JSON text string:

{"msg":{"SND":9,"pid":1289,"txt":"Hello World!"}}

If you pass the string into the following COBOL program, you can suppress any of the sub-ordinate items (of msg) from being matched when the JSON PARSE statement is executed:

       Identification division.
       Program-id. jparse1.
       Data division.
       Working-storage section.
       01 msg.
         03 snd usage comp-1.
         03 pid pic 9999 usage display.
         03 txt pic x(12).
       Linkage section.
       01 json-str pic x(53).
       Procedure division using json-str.
       move 1300 to pid.
       display "Parsing....".
       JSON PARSE json-str into msg with DETAIL
                  SUPPRESS pid
       END-JSON.
       if snd equal to 9 then
          DISPLAY "PID is " pid
          DISPLAY "Message text is '" txt "'"
       end-if.
       display "JSON-STATUS is " JSON-STATUS.
       goback.
       End program jparse1.

As a result of executing the JSON PARSE statement, the matching of pid is suppressed, and its previous value (1300) is retained. Suppressing a data item produces a non-exception code of 2.

Parent topic: The JSON PARSE Statement
Related information
Appendix A - JSON PARSE Example
Appendix B - Parsing JSON Arrays
Appendix C - JSON PARSE Matching Algorithm
Appendix D - Size and Precision Handling


MERGE Statement (COBOL)

The MERGE Statement

The MERGE statement combines two or more identically sequenced files on a set of specified keys, and during the process makes records available, in merged order, to an output procedure or to an output file.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • CALLSORT"EXTSM" - enables you to specify up to 128 files in the USING or GIVING clause. Without this directive the limit is 10 file-names.

Syntax Rules

  1. File-name-1 must be described in a sort-merge file description entry in the Data Division.
  2. Procedure-name-1 represents the name of an output procedure.
  3. Procedure-name-1 and procedure-name-2 must be section-names.

    ANS85 OSVS This restriction is removed.

  4. ANS85 If the file referenced by file-name-1 contains variable length records, the size of the records contained in the files referenced by file-name-2 and file-name-3 must not be less than the smallest record, nor greater than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed length records, the size of the records contained in the files referenced by file-name-2 and file-name-3 must not be greater than the largest record described for file-name-1.
  5. File-name-2, file-name-3, and file-name-4 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
  6. The words THRU and THROUGH are equivalent.
  7. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. The data items identified by KEY data-names must be described in records associated with file-name-1.
    2. KEY data-names can be qualified.
    3. The data items identified by KEY data-names must not be variable length items.
    4. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions. The same character positions referenced by a key data-name in one record description entry are taken as the key in all records of the file.
    5. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.
    6. OSVS VSC2 MF KEY data items can be floating-point items.
    7. OSVS VSC2 MF If the KEY is an external floating-point item, the key is treated as alphanumeric. The sequence in which the records are merged depends on the collating sequence used.
    8. OSVS VSC2 MF If the KEY is an internal floating-point item, the records are merged in numeric order.
  8. No more than one file-name from a multiple file reel can appear in the MERGE statement.
  9. File-names must not be repeated in the MERGE statement.
  10. MERGE statements can appear anywhere except in the declaratives portion of the Procedure Division.
  11. ANS85 If file-name-4 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase, and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.
  12. ANS85 If the GIVING phrase is specified and the file referenced by file-name-4 contains variable length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor greater than the largest record described for file-name-4. If the file referenced by file-name-4 contains fixed length records, the size of the records contained in the file referenced by file-name-1 must not be greater than the largest record described for file-name-4.

General Rules

  1. The MERGE statement merges all records contained on the files referenced by file-name-2 and file-name-3.
  2. If the file referenced by file-name-1 contains only fixed length records, any record in the file referenced by file-name-2 or file-name-3 containing fewer character positions than that fixed length is space filled on the right, beginning with the first character position after the last character in the record, when that record is released to the file referenced by file-name-1.
  3. The data-names following the word KEY are listed from left to right in the MERGE statement in order of decreasing significance without regard to how they are divided into KEY phrases. The leftmost data-name is the major key, the next data-name is the next most significant key, and so on.
    1. When the ASCENDING phrase is specified, the merged sequence is from the lowest value of the contents of the data items identified by the key data-names to the highest value, according to the rules for comparison of operands in a relation condition.
    2. When the DESCENDING phrase is specified, the merged sequence is from the highest value of the contents of the data items identified by the key data-names to the lowest value, according to the rules for comparison of operands in a relation condition.
  4. When, according to the rules for comparison of operands in relation condition, the contents of all the key data items of one data record are equal to the corresponding key data items of one or more other data records, the order of return of these records:
    1. Follows the order of the associated input files as specified in the MERGE statement
    2. Is such that all records associated with one input file are returned prior to the return of records from another input file.
  5. The collating sequence that applies to the comparison of the nonnumeric key data items specified is determined at the beginning of the execution of the MERGE statement in the following order of precedence:
    1. First, the collating sequence established by the COLLATING SEQUENCE phrase, if specified, in that MERGE statement.
    2. Second, the collating sequence established as the program collating sequence.
  6. The results of the merge operation are undefined unless the records in the files referenced by file-name-2 and file-name-3 are ordered as described in the ASCENDING or DESCENDING KEY phrases associated with the MERGE statement.
  7. All the records in the files referenced by file-name-2 and file-name-3 are transferred to the file referenced by file-name-1. At the start of execution of the MERGE statement, the files referenced by file-name-2 and file-name-3 must not be in the open mode. For each of the files referenced by file-name-2 and file-name-3 the execution of the MERGE statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the INPUT phrase had been executed. If an output procedure is specified, this initiation is performed before control passes to the output procedure.
    2. The logical records are obtained and released to the merge operation. Each record is obtained as if a READ statement with the NEXT and the AT END phrases had been executed.

      If the file referenced by file-name-1 is described with variable length records, the size of any record written to file-name-1 is the size of that record when it was read from file-name-2 or file-name-3, regardless of the content of the data item referenced in the DEPENDING ON phrase of either a RECORD IS VARYING clause or an OCCURS clause specified in the sort-merge file description entry for file-name-1.

      For a relative file, the content of the relative data key item is undefined after the execution of the MERGE statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. If an output procedure is specified, this termination is not performed until after control passes the last statement in the output procedure.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION/ERROR procedures are executed.

      The value of the data item referenced by the DEPENDING ON phrase of a RECORD IS VARYING clause specified in the file description entry for file-name-2 or file-name-3 is undefined upon completion of the MERGE statement.

  8. The output procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RETURN statement in merged order from the file referenced by file-name-1. The range includes all statements that are executed as the result of a transfer of control by CALL, EXIT, GO TO, and PERFORM statements in the range of the output procedure, as well as all statements in declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the output procedure must not cause the execution of any MERGE, RELEASE, or SORT statement. (See the topic Explicit and Implicit Transfers of Control in the chapter Concepts of the COBOL Language.)
  9. If an output procedure is specified, control passes to it during execution of the MERGE statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure. When control passes the last statement in the output procedure, the return statement provides for termination of the merge, and then passes control to the next executable statement after the MERGE statement. Before entering the output procedure, the merge procedure reaches a point at which it can select the next record in merged order when requested. The RETURN statements in the output procedure are the requests for the next record.
  10. During the execution of the output procedure, no statement can be executed manipulating the file referenced by, or accessing the record area associated with, file-name-2, file-name-3, or file-name-4.
  11. If the GIVING phrase is specified, all the merged records are written on the file referenced by file-name-4 as the implied output procedure for the MERGE statement. At the start of execution of the MERGE statement, the file referenced by file-name-4 must not be in the open mode. For each of the files referenced by file-name-4, the execution of the MERGE statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the OUTPUT phrase had been executed.
    2. The merged logical records are returned and written onto the file. Each record is written as if a WRITE statement without any optional phrases had been executed.

      If the file referenced by file-name-4 is described with variable length records, the size of any record written to file-name-4 is the size of that record when it was read from file-name-1, regardless of the content of the data item referenced in the DEPENDING ON phrase of either a RECORD IS VARYING clause or an OCCURS clause specified in the file description entry for file-name-4.

      For a relative file, the relative key data item for the first record returned has the value 1; for the second record returned, the value 2, and so on. The content of the relative key data item is undefined after execution of the MERGE statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed.

    These implicit functions are performed such that any associated USE AFTER EXCEPTION/ERROR procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by, or accessing the record area associated with, file-name-4. On the first attempt to write beyond the externally defined boundaries of the file, any USE AFTER EXCEPTION/ERROR procedure specified for the file is executed; if control is returned from the USE procedure or if no such USE procedure is specified, the processing of the file is terminated as in paragraph 11c above.

    The value of the data item referenced by the DEPENDING ON phrase of a RECORD IS VARYING clause specified in the file description entry for file-name-1 is undefined upon completion of the MERGE statement for which the GIVING phrase is specified.

  12. If the file referenced by file-name-4 contains only fixed length records, any record in the file referenced by file-name-1 containing fewer character positions than that fixed length is space filled on the right, beginning with the first character position after the last character in the record, when that record is returned to the file referenced by file-name-4.
  13. Segmentation, as defined in the topic Segmentation, can be applied to programs containing the MERGE statement. However, the following restrictions apply:
    1. If the MERGE statement appears in a section that is not in an independent segment, then any output procedure referenced by that MERGE statement must appear:
      1. Totally within non-independent segments, or
      2. Wholly contained in a single independent segment.
    2. If a MERGE statement appears in an independent segment, then any output procedure referenced by that MERGE statement must be contained:
      1. Totally within non-independent segments, or
      2. Wholly within the same independent segment as that MERGE statement.
  14. OSVS VSC2 MF The SORT-RETURN special register is available to source elements with a MERGE statement. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of the merge operation. You can set the special register to 16 in the output procedure to terminate a merge operation before all records are processed. The operation is terminated on the next RETURN statement.
Parent topic: Statements
Related information
Segmentation
Explicit and Implicit Transfers of Control


MOVE Statement (COBOL)

The MOVE Statement

The MOVE statement transfers data, in accordance with the rules of editing, to one or more data areas.

General Formats for Format 1

General Formats for Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • BYTE-MODE-MOVE - impacts the behavior of MOVE statements in which the sending and receiving items share a part of their storage (that is, overlapping moves).
    • DBCS (DBSPACE) - impacts what characters are used for space-filling DBCS receiving items.
    • DE-EDIT - controls whether the value of numeric-edited sending fields is determined by their PICTURE clause or not.
    • TRUNC - determines whether truncation occurs based on the storage available or the PICTURE clause, when the sending item includes a value larger than a binary receiving value's size.

Syntax Rules for All Formats

  1. Identifier-1 and literal represent the sending area; identifier-2 represents the receiving area.
  2. An index-name or an index data item may not be specified as an operand of a MOVE statement.
  3. MF If the sending or receiving item is a pointer data item or an ADDRESS OF operand, then the other operands of the MOVE statement must also be pointer data items or ADDRESS OF operands or, in the case of the sending item, NULL.
  4. MF If the sending or receiving item is an object reference, a program-pointer, an entry-pointer, a monitor-pointer, a mutex-pointer, a semaphore-pointer or a thread-pointer, then all other operands of the MOVE statement must be of the same type or, in the case of the sending item, NULL.
  5. VSC2 MF If either the sending or receiving item is a DBCS (USAGE DISPLAY-1) item, then both must be DBCS items. The figurative constant SPACE can be the DBCS sending item.

Syntax Rules for Format 1

  6. OSVS VSC2 MF When Format 1 is specified, all identifiers can be either group or elementary items. The data in the sending area is moved into the data item referenced by each identifier-2 in the order in which it is specified.
  7. MF Identifier-1 may be a numeric function-identifier.
  8. If identifier-1 is a data item described with USAGE BINARY-CHAR, USAGE BINARY-SHORT, USAGE BINARY-LONG or USAGE BINARY-DOUBLE, identifier-2 must be a numeric or numeric-edited item; otherwise, see Table 1, MOVE Statement Data Categories, below which specifies the validity of the move.

Syntax Rules for Format 2

  9. CORR is an abbreviation for CORRESPONDING.
  10. When the CORRESPONDING phrase is used, all identifiers must be group items.
  11. The following items can be part of a group that is referenced in a MOVE CORRESPONDING statement; however, no movement of this item takes place:
    • VSC2 MF POINTER, PROCEDURE-POINTER
    • ISO2002 MF OBJECT-REFERENCE, PROGRAM-POINTER
    • MF EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER, THREAD-POINTER.

General Rules for All Formats

  1. MF If identifier-1 is a numeric function-identifier, then identifier-2 must be either a numeric or numeric-edited item.
  2. The data designated by the literal or identifier-1 is moved to the data item referenced by each identifier-2, in the order in which it is specified. The rules referring to identifier-2 also apply to the other receiving areas. Any subscripting or indexing associated with identifier-2, is evaluated immediately before the data is moved to the respective data item.

    ANS85 If identifier-1 is reference modified, subscripted, or is a function-identifier, the reference modifier, subscript, or function-identifier is evaluated only once, immediately before data is moved to the first of the receiving operands.

    ANS85 The result of the statement:

    ANS85
     MOVE a(b) TO b, c(b)

    ANS85 is equivalent to:

    ANS85
     MOVE a(b) TO temp MOVE temp TO b MOVE temp TO c(b)

    ANS85 where temp is an intermediate result item provided by your COBOL system.

  3. Any MOVE in which the sending and receiving items are both elementary items is an elementary move. Every elementary item belongs to one of the following categories: numeric, alphabetic, alphanumeric, numeric-edited, alphanumeric-edited

    ISO2002 MF national, national-edited, boolean

    OSVS VSC2 MF or floating-point.

    These categories are described in the PICTURE clause. Numeric literals belong to the category numeric, and nonnumeric literals belong to the category alphanumeric. The figurative constant ZERO belongs to the category numeric when moved to a numeric or numeric-edited item. The figurative constant ZERO belongs to the category alphanumeric in all other cases. The figurative constant SPACE belongs to the category alphabetic. All other figurative constants belong to the category alphanumeric.

    The following rules apply to an elementary move between these categories:

    1. The figurative constant SPACE, or an alphanumeric-edited, or alphabetic data item must not be moved to a numeric or numeric-edited data item.
    2. A numeric-edited data item must not be moved to a numeric or numeric-edited data item

      ISO2002 MF , or boolean

      .

      ANS85 This restriction is removed.

    3. A numeric literal, the figurative constant ZERO, a numeric data item or a numeric-edited data item

      ISO2002 MF , or a boolean data item

      must not be moved to an alphabetic data item.
    4. A non-integer numeric literal or a non-integer numeric data item must not be moved to an alphanumeric or alphanumeric-edited data item

      ISO2002 MF , or boolean data item

      .
    5. ISO2002 MF If identifier-2 is a boolean data item, it can only receive figurative constants whose associated characters are boolean characters.
    6. ISO2002 MF An alphabetic, alphanumeric-edited, numeric, or national data item must not be moved to a boolean data item.
    7. ISO2002 MF A boolean data item must not be moved to a national data item.
    8. All other elementary moves are legal and are performed according to the rules given in General Rule 5.
  4. Any necessary conversion of data from one form of internal representation to another takes place during legal elementary moves, along with any editing specified for

    ANS85 , or de-editing implied by,

    the receiving data item:
    1. When an alphanumeric-edited or alphanumeric item is a receiving item, alignment and any necessary space-filling takes place as defined in the topic Standard Alignment Rules in the chapter Concepts of the COBOL Language. If the size of the sending item is greater than the size of the receiving item, the excess characters are truncated on the right after the receiving item is filled. If the sending item is described as being signed numeric, the operational sign is not moved; if the operational sign occupies a separate character position (see the topic The SIGN Clause), that character is not moved and the size of the sending item is considered to be one less than its actual size (in terms of standard data format characters).
    2. When a numeric or numeric-edited item is the receiving item, alignment by decimal point and any necessary zero-filling takes place as defined in the section Standard Alignment Rules in the chapter Concepts of the COBOL Language, except where zeros are replaced because of editing requirements.

      ANS85 When the sending operand is numeric-edited, de-editing is implied to establish the operand's unedited numeric value, which can be signed; then the unedited numeric value is moved to the receiving field. The effect of de-editing depends on the setting of the DE-EDIT Compiler directive

      When a signed numeric item is the receiving item, the sign of the sending item is placed in the receiving item. (See the topic The SIGN Clause.) Conversion of the representation of the sign takes place as necessary. If the sending item is unsigned, a positive sign is generated for the receiving item.

      When an unsigned numeric item is the receiving item, the absolute value of the sending item is moved and no operational sign is generated for the receiving item.

      When a data item described as alphanumeric is the sending item, data is moved as if the sending item were described as an unsigned numeric integer.

      When the receiving item is numeric or numeric-edited and the sending item is defined as alphanumeric, if the content of the sending item is not an integer, the results of the move are undefined. If the alphanumeric sending item is a literal whose contents do not represent an integer, an error is reported, and zero moved to the target. (See the topic Incompatible Data in the chapter Procedure Division.)

      ANS85 When the numeric data item is the sending item the action of the move is such that a reverse of the move would cause the same value to appear in the numeric-edited field (except for truncation). If the data item contains data which does not conform to the edited picture, zero is moved to the target.

    3. When a receiving field is described as alphabetic, justification and any necessary space-filling takes place as defined in the topic Standard Alignment Rules in the chapter Concepts of the COBOL Language. If the size of the sending item is greater than the size of the receiving item, the excess characters are truncated on the right after the receiving item is filled.
    4. OSVS VSC2 MF When the receiving field is floating-point, the sending item is converted first to internal floating-point and then moved. When data is moved to or from an external floating-point item, the data is converted first to or from its equivalent internal floating-point value.
    5. VSC2 MF When the receiving field is non-NCHAR DBCS, the sending item must be DBCS or national; no conversion takes place. If the sending and receiving items are not the same size the data item is either truncated or padded with DBCS spaces on the right.
  5. Any move that is not an elementary move is treated exactly as if it were an alphanumeric to alphanumeric elementary move, except that no conversion of data from one form of internal representation to another takes place. In such a move, the receiving area is filled without consideration for the individual elementary or group items contained in either the sending or receiving area, except as noted in the General Rules of the OCCURS clause.
  6. Table 1 below summarizes the legality of the various types of MOVE statements. The general rule reference indicates the rule that prohibits the move or the behavior of a legal move.
  7. ISO2002 MF When the receiving field is boolean, the boolean value of the sending item is moved, with conversion of data representation if necessary, and any necessary alignment and zero filling as defined in the topic Standard Alignment Rules in the sectionConcepts of the COBOL Language. If the sending field is not boolean, it is treated as if it were a boolean data item with the same usage and number of character positions as the sending field. If the content of the sending field would result in a false value in a boolean class condition, an error is reported (see the topic Incompatible Data in the section Procedure Division.)

General Rules for Format 2

  8. If the CORRESPONDING phrase is used, selected items in identifier-1 are moved to selected items in identifier-2, according to the rules given in The CORRESPONDING Phrase in the chapter Procedure Division. The results are the same as if you had referred to each pair of corresponding identifiers in separate MOVE statements.

    OSVS VSC2 The process is repeated for each destination group.

    Table 1. MOVE Statement Data Categories
    Category of Sending Item | Category of Receiving Data Items (the relevant rule number is quoted in these columns)
    Alphabetic | Alphanumeric-Edited/ Alpha-numeric | Numeric Integer/Non-Integer | Numeric-Edited External/Internal Floating Point | National | Non-NCHAR DBCS | NCHAR DBCS | Boolean
    Alphabetic | Yes/4c | Yes/4a | No/3a | No/3a | Yes | No/4e | Yes | No/3f
    Alphanumeric | Yes/4c | Yes/4a | Yes/4b2 | Yes/4b | Yes | No/4e | Yes | Yes/3e
    Alphanumeric-Edited | Yes/4c | Yes/4a | No/3a | No/3a | Yes | No/4e | Yes | No/3f
    Numeric Integer | No/3c | Yes/4a | Yes/4b | Yes/4b | Yes | No/4e | Yes | No/3f
    Numeric Non-Integer | No/3c | No/3c | Yes/4b | Yes/4b | No | No/4e | No | No/3f
    Numeric-Edited | No/3c | Yes/4a | Yes/4b | Yes/4b | Yes | No/4e | Yes | No/3f
    National | No | No | Yes | Yes | Yes | Yes | Yes | No
    Non-NCHAR DBCS | No/4e | No/4e | No/4e | No/4e | Yes | Yes/4e | Yes | No/3f
    NCHAR DBCS | Yes | Yes | No | No | Yes | Yes/4e | Yes | No
    Boolean | No/3c | Yes/4a | No/3b | No/3b | No | No/3g | No | Yes/4f
    Note: An error is reported if a non-integer alphanumeric literal sending item is used

    For more information on NCHAR DBCS support, refer to Micro Focus Extensions for Double-byte Character Set Support, and for more information on non-NCHAR DBCS support, refer to Double-byte Character Set Support.

Parent topic: Statements
Related reference
Undefined Results of MOVE and Arithmetic Operations
MOVE Statement
Related information
Micro Focus Extensions for Double-byte Character Set Support
Double-byte Character Set Support
Standard Alignment Rules
The SIGN Clause
Incompatible Data
The CORRESPONDING Phrase


MULTIPLY Statement (COBOL)

The MULTIPLY Statement

The MULTIPLY statement causes numeric data items to be multiplied and sets the values of data items equal to the results.

General Formats for Format 1

MULTIPLY - FORMAT 1

General Formats for Format 2

MULTIPLY - FORMAT 2

Syntax Rules for All Formats

  1. Each identifier must refer to a numeric elementary item, except that in Format 2 each identifier following the word GIVING must refer to either an elementary numeric item or an elementary numeric-edited item.
  2. Each literal must be a numeric literal.
  3. The composite of operands is determined by using all receiving data items. See the topic Arithmetic Statements in the chapter Procedure Division.
  4. OSVS VSC2 MF Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified.

General Rules for All Formats

  1. See the topics The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in the chapter Procedure Division.

General Rules for Format 1

  2. When Format 1 is used, the value of identifier-1 or literal-1 is multiplied by the value of identifier-2. The value of the multiplier (identifier-2) is replaced by this product; similarly for each successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is specified.

General Rules for Format 2

  3. When Format 2 is used, the value of identifier-1 or literal-1 is multiplied by identifier-2 or literal-2 and the result is stored in the data item referenced by each identifier-3.
Parent topic: Statements
Related information
Arithmetic Statements
The ON SIZE ERROR Phrase
The ROUNDED Phrase
Overlapping Operands
Multiple Results in Arithmetic Statements


NEXT SENTENCE Statement (COBOL)

The NEXT SENTENCE Statement

The NEXT SENTENCE statement transfers control to the next COBOL sentence, that is, following the next period. It does not transfer control to the logically next COBOL verb as occurs with the CONTINUE verb.

General Format

NEXT SENTENCE Statement

Syntax Rules

  1. The NEXT SENTENCE statement can be used anywhere a conditional statement or an imperative-statement can be used.

General Rules

  1. The NEXT SENTENCE statement redirects the flow of execution to the logically next COBOL verb following the next period.
Parent topic: Statements


NOTE Statement (COBOL)

The NOTE Statement

The NOTE statement introduces a sentence or paragraph that will be treated as comments.

General Format

Syntax Rules

  1. The character-string can be any combination of characters from the computer character set.

General Rules

  1. If a NOTE statement is the first sentence of a paragraph, the entire paragraph is treated as comment.
  2. If a NOTE statement appears as other than the first sentence of a paragraph, text up to the next separator period is treated as comment.
Parent topic: Statements


ON Statement (COBOL)

The ON Statement

The ON statement allows selective execution of procedural statements on a periodic basis.

General Format

Syntax Rules

  1. Identifier-1, identifier-2 and identifier-3 must describe unsigned integer numeric elementary items.
  2. Literal-1, literal-2 and literal-3 must be unsigned numeric literals.
  3. The ON statement is not supported in class programs when compiling to managed code.

General Rules

  1. Prior to the first execution of each ON statement , a counter, implicitly defined for that ON statement (the implicit-ON-counter), is initialized to be zero.
  2. Identifier-1, identifier-2 and identifier-3 should, if specified, contain positive integer values at the time of execution of the ON statement. Varying these values between executions of the ON statement will affect subsequent executions of the ON statements.
  3. The implicit ON counter cannot be affected in any way other than by transfer of execution flow to that ON statement. (The ON counter of a called program can only be reset by the canceling of that program; execution of the EXIT PROGRAM statement and subsequent CALL of the program without intervening CANCEL has no effect upon the implicit ON counter value.)
  4. The following value-list is then evaluated:
    1. The current value of identifier-1 or literal-1,
    2. A sequence of values being the results of repeatedly adding the current value of identifier-2 or literal-2 to the current value of identifier-1 or literal-1 until the value of identifier-3 or literal-3 is reached.

    The implicit-ON-counter is then compared with each of this list of values. If an equality is found, then imperative-statement-1 is executed. If no equality is found, then imperative-statement-2, if specified, is executed.

Parent topic: Statements


OPEN Statement (COBOL)

The OPEN Statement

The OPEN statement initiates the processing of files. It also performs checking and/or writing of labels and other input-output operations.

ANS85 The REVERSED phrase of the OPEN statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, the REVERSED phrase of the OPEN statement is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

MF The OPEN statement allocates system resources for a synchronization data item and initializes the data item.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 ( MF Line Sequential, Relative and Indexed Files)

General Formats for Format 3 (Synchronization Data Items)

Syntax Rules for All Formats (All Files)

  1. The files referenced in the OPEN statement need not all have the same organization or access.
  2. ISO2002 MF If SHARING ALL is specified and the INPUT phrase is not specified, the LOCK MODE clause must be specified in the file control entry for file-name-1.

Syntax Rules for Format 1 (Record Sequential Files)

  3. MF NO REWIND is documentary only.
  4. The I-O phrase can be used only for disk files.
  5. ANS85 The EXTEND phrase can only be used for files on which the LINAGE clause has not been specified.
  6. The EXTEND phrase must not be specified with multiple file reels.
  7. The REVERSED phrase can be used only for fixed-length record sequential files.

Syntax Rules for Format 2 ( MF Line Sequential, Relative and Indexed Files)

  8. ANS85 The EXTEND phrase can be used for files in sequential access mode.
  9. ISO2002 MF The SHARING phrase must not be specified for files with line sequential organization.

Syntax Rules for Format 3 (Synchronization Data Items)

  10. MF Identifier-1 must reference an elementary data item with a USAGE of EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER or SEMAPHORE-POINTER.

General Rules for Formats 1 and 2 (All Files)

  1. Prior to the successful execution of an OPEN statement for a given file, no statement (except for a SORT or MERGE statement with the USING or GIVING phrases) can be executed that references that file, either explicitly or implicitly.
  2. ISO2002 MF The successful execution of an OPEN statement determines the availability of the file and results in the file connector referenced by the file-name being in an open mode. The successful execution of an OPEN statement associates the file with the file-name through a file connector.

    The key words INPUT, OUTPUT, I-O, and EXTEND specify the type of input-output operations intended for the file through the file connector and establish the open mode. (See table 14-4, Permissible Combinations of Statements and OPEN Modes.)

    A file is available if it is physically present and is recognized by the file handling system. Table 1, Opening Available and Unavailable Files (file not currently open), shows the results of opening available and unavailable files that are not currently open. Table 2, Opening Available Shared Files that are Currently Open by Another File Connector, shows the results of opening available and unavailable files that are currently open by another file connector.

    Table 1. Opening Available and Unavailable Files (File not Currently Open)
    Open Mode | File is Available | File is Unavailable
    INPUT | Normal open | Open is unsuccessful
    INPUT (optional file) | Normal open | Normal open; the first read causes the at end condition or invalid key condition
    I-O | Normal open | Open is unsuccessful
    I-O (optional file) | Normal open | Open causes the file to be created
    OUTPUT | Normal open; the file contains no records | Open causes the file to be created
    EXTEND | Normal open | Open is unsuccessful
    EXTEND (optional file) | Normal open | Open causes the file to be created
    Table 2. Opening Available SharedFiles that are Currently Open by Another File Connector
    Open request | Most Restrictive Existing Sharing Mode and Open Mode
    Sharing with no Other | Sharing with Read Only | Sharing with All Other
    extend/ I-O/ input/ output | extend/ I-O/ output | input | extend/ I-O/ output | input
    SHARING WITH NO OTHER | EXTEND/ I-O/ INPUT/ OUTPUT/ | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open
    SHARING WITH READ ONLY | EXTEND/ I-O | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open | Normal open
    INPUT | Unsuccessful open | Unsuccessful open | Normal open | Unsuccessful open | Normal open
    OUTPUT | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open
    SHARING WITH ALL OTHER | EXTEND/ I-O | Unsuccessful open | Unsuccessful open | Unsuccessful open | Normal open | Normal open
    INPUT | Unsuccessful open | Normal open | Normal open | Normal open | Normal open
    OUTPUT | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open | Unsuccessful open
  3. The successful execution of an OPEN statement makes the associated record area available .
  4. In Table 3, "X" at an intersection indicates that the specified statement, used in the access mode given for that row, can be used with the open mode given at the top of the column.
    File Access Mode | OPEN Mode
    Statement | Input | Output | Input-Output | Extend
    Sequential | READ | X | X
    WRITE | X | X
    REWRITE | X
    Random (Non-Sequential Files) | READ | X | X
    WRITE | X | X
    REWRITE | X
    START
    DELETE | X
    Dynamic (Non-Sequential Files) | READ | X | X
    WRITE | X | X
    REWRITE | X
    START | X | X
    DELETE | X
    Note: The START and DELETE statements cannot be used with record

    MF or line

    sequential files.
  5. MF If the WITH LOCK phrase is specified, the OPEN statement acquires a lock on the whole file. (This is equivalent to specifying LOCK MODE IS EXCLUSIVE in the SELECT statement for the file. See the topic The File Control Entry in the chapter Environment Division.)
  6. ANS85 If, during the execution of an OPEN statement, a file attribute conflict occurs, the execution of the OPEN statement is unsuccessful. Your COBOL system defines which of the fixed file attributes are validated during the execution of the OPEN statement. See your file handling documentation for more details. The validation of fixed file attributes can vary depending on the organization and/or storage medium of the file.
  7. ANS85 A file can be opened with the INPUT, OUTPUT, EXTEND and I-O phrases in the same run unit. Following the initial execution of an OPEN statement for a file connector, each subsequent OPEN statement execution for that same file connector must be preceded by the execution of a CLOSE statement for that file connector, even if the file is optional.
  8. Execution of the OPEN statement does not obtain or release the first data record.
  9. The external name of the file specified in the SELECT clause for a file is processed as follows:
    1. When the INPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for input.
    2. When the OUTPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for output.
  10. The file description entry for file-name-1, file-name-2, file-name-3, and file-name-4 must be equivalent to that used when this file was created.
  11. For files being opened with the INPUT or I-O phrase, the OPEN statement sets the file position indicator to the first record currently existing in the file for indexed and sequential files, and record position one for relative files. If no records exist in the file, the file position indicator is set such that the next executed READ statement for an indexed or sequential file will result in an AT END condition. If the file does not exist, OPEN INPUT causes an error status, unless the file is optional.
  12. When the I-O phrase is specified and the LABEL RECORDS clause indicates label records are present, the execution of the OPEN statement includes the following steps:
    1. The labels are checked in accordance with the operating system-specified conventions for input-output label checking.
    2. The new labels are written in accordance with the operating system-specified conventions for input-output label writing.
  13. Upon successful execution of an OPEN statement with the OUTPUT phrase specified, a file is created. At that time the associated file contains no data records. If a file of the same name exists it is deleted. If the file is write-protected an error occurs.
  14. ANS85 When the EXTEND phrase is specified, the OPEN statement positions the file immediately after the last logical record for that file. The last logical record for a sequential file is the last record written in the file. In a relative file it is the currently existing record with the highest relative record number, and in an indexed file it is the currently existing record with the highest prime key value.
  15. Execution of the OPEN statement causes the value of the FILE STATUS data item to be updated (see the topic I-O Status in the chapter Procedure Division).
  16. MF When LOCK MODE IS EXCLUSIVE is specified in the SELECT/ ASSIGN statement of a file, successful execution of an OPEN statement of that file locks the file exclusively to that run unit.
  17. MF When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified in the SELECT/ASSIGN statement of a file, the file that is referred to is shareable. More than one run unit can successfully open such a file.
  18. MF A file opened for OUTPUT, and relative and indexed files opened EXTEND, are implicitly defined as files with an exclusive lock, that is, they are not shareable.
  19. MF Only shareable files opened for I-O can acquire record locks.
  20. If execution of the OPEN statement is unsuccessful, the physical file is not affected and the following actions take place in this order:
    1. A value is placed in the I-O status associated with file-name to indicate the condition that caused the OPEN statement to be unsuccessful.
    2. Any applicable USE AFTER EXCEPTION procedure is executed. (See the topic The USE Statement.)
  21. The I-O phrase permits the opening of a file for both input and output operations. If the file does not exist, the following rules apply:
    1. If the OPTIONAL phrase is specified in the SELECT clause for the file, the file is created
    2. If the NOT OPTIONAL phrase is specified in the SELECT clause for the file, an error occurs
    3. If neither phrase is specified, and the directive OPTIONAL-FILE was specified when the source element was compiled, the file is created.
    4. If neither phrase is specified, and the directive NOOPTIONAL-FILE was specified when the source element was compiled, an error occurs.
  22. If an input file is designated with the OPTIONAL phrase in its SELECT clause, when the file is opened there is an interrogation for the presence or absence of this file. If the file is not present, the first READ statement for this file causes the AT END condition to occur.
  23. When the EXTEND phrase is specified, the OPEN statement positions the file immediately following the last logical record of that file. Subsequent WRITE statements referencing the file will add records to the file as though the file had been opened with the OUTPUT phrase. If the file does not exist it is created.
  24. ANS85 When the EXTEND phrase is specified and the LABEL RECORDS clause in this file's FD indicates label records are present, the execution of the OPEN statement includes the following steps:
    1. The beginning file labels are processed only in the case of a single reel/unit file.
    2. The beginning reel/unit labels on the last existing reel/unit are processed as though the file was being opened with the INPUT phrase.
    3. The existing ending file labels are processed as though the file is being opened with the INPUT phrase. These labels are then deleted.
    4. Processing then proceeds as though the file had been opened with the OUTPUT phrase.
  25. The I-O phrase permits the opening of a file for both input and output operations,

    MF except files with ORGANIZATION LINE SEQUENTIAL.

    If the file does not exist, it is created and used as an empty file for input

    MF unless NOT OPTIONAL was specified in the SELECT statement.

    An attempt to READ from the newly created file causes an error.

  26. ISO2002 MF The SHARING phrase can be specified only for shared files. (See the topic Sharing Mode in the chapter Language Fundamentals.)
  27. ISO2002 MF The SHARING phrase specifies what operations may be performed on the file through other file connectors sharing the file. (See the topic Sharing Mode in the chapter Language Fundamentals.)
  28. ISO2002 MF The SHARING phrase overrides any SHARING clause in the file control entry of the file connector associated with the file-name. If there is no SHARING phrase on the OPEN statement, then file sharing is completely specified in the file control entry. If neither a SHARING phrase on the OPEN statement nor a SHARING clause in the file control entry is specified, the sharing mode is established for the file connector in accordance with the rules specified in the topic Language Fundamentals in the chapter Language Fundamentals.

General Rules for Format1 (Record Sequential Files)

  29. If the storage medium for the file permits rewinding, the following rules apply:
    1. Execution of the OPEN statement causes the file to be positioned at its beginning.
    2. When the REVERSED phrase is specified, the file is positioned at its end by execution of the OPEN statement.
  30. When the REVERSED phrase is specified, the subsequent READ statements for the file make the data available in reversed order; that is, starting with the last record.

General Rules for Format 2 ( Line Sequential Files)

  31. MF I-O mode is not allowed for line sequential files unless the REWRITE-LS Compiler directive is set.

General Rules for Format 3 (Synchronization Data Items)

  32. MF Prior to the successful execution of an OPEN statement for a given synchronization data item, no statement can be executed that references that data item.
  33. MF The successful execution of an OPEN statement determines the availability of the synchronization data item.
  34. MF Execution of the OPEN statement causes the RETURN-CODE special register to be updated with one of the values specified for the synchronization item library routines.
  35. MF Following the initial execution of an OPEN statement for a synchronization data item, each subsequent OPEN statement execution for that same data item must be preceded by the execution of a CLOSE statement for that data item.
  36. MF If identifier-1 references an event data item, the execution of the OPEN statement initializes the data item to FALSE.
  37. MF If identifier-1 references a monitor data item, the execution of the OPEN statement initializes the monitor to NOT BROWSING, NOT READING, and NOT WRITING.
  38. MF If identifier-1 references a mutex data item, the execution of the OPEN statement initializes the data item to OFF.
  39. MF If identifier-1 references a semaphore data item, the execution of the OPEN statement initializes the data item to zero.
Parent topic: Statements
Related reference
File and Record Locking
Related information
The File Control Entry
I-O Status
The USE Statement
Sharing Mode


PERFORM Statement (COBOL)

The PERFORM Statement

The PERFORM statement is used to transfer control explicitly to one or more procedures and to return control implicitly whenever execution of the specified procedure is complete.

ANS85 The PERFORM statement is used to control execution of one or more imperative statements which are in the scope of that PERFORM statement.

NET JVM The PERFORM statement is used to process each element of an array.

See also the section The EXIT Statement.

General Formats for Format 1 (Out-of-Line PERFORM)

General Formats for Format 2 (Inline PERFORM)

General Formats for Format 3

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • PERFORM-TYPE - controls the handling of overlapping PERFORM ranges.

Syntax Rules for All Formats

  1. Each identifier represents a numeric elementary item described in the Data Division. identifier-1 must be described as a numeric integer.
  2. OSVS VSC2 MF Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified. They cannot be used where an integer is required.
  3. If the TEST phrase is specified, the EXIT phrase must not be specified.
  4. ANS85 If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is assumed.
  5. condition-1, condition-2, ... , can be any conditional expression. (See the section Conditional Expressions in the chapter Procedure Division)
  6. Each literal represents a numeric literal.
  7. If an index-name is specified in the VARYING or AFTER phrase, then:
    1. The identifier in the associated FROM and BY phrases must reference an integer data item.
    2. The literal in the associated FROM phrase must be a positive integer.
    3. The literal in the associated BY phrase must be a nonzero integer.
  8. If an index-name is specified in the FROM phrase, then:
    1. The identifier in the associated VARYING or AFTER phrase must reference an integer data item.
    2. The identifier in the associated BY phrase must reference an integer data item.
    3. The literal in the associated BY phrase must be an integer.
  9. The literal in the BY phrase must not be zero.
  10. Two AFTER phrases are permitted in the PERFORM statement.

    ANS85 Six AFTER phrases are permitted in the PERFORM statement.

    MF This limit is raised to fifteen.

Syntax Rules for Format 1

  11. The words THROUGH and THRU are equivalent.
  12. Where procedure-name-1 and procedure-name-2 are both specified and either is the name of a procedure in the declaratives portion of the Procedure Division, both must be procedure-names in the same declarative section.

Syntax Rules for Format 3

  13. NET JVM Identifier-9 must either be a managed array or an instance of a collection class, i.e. a class that implements the System.IEnumerable interface (.NET) or the java.lang.Iterable interface (JVM). Examples of such collection classes are the List and Dictionary classes.
  14. NET JVM It must be possible to perform a casting operation from the element type of identifier-9 to the type of identifier-8.

General Rules for Format 1

  1. The statements contained within the range of procedure-name-1 (through procedure-name-2 if specified) are referred to as the specified set of statements.
  2. When the PERFORM statement is executed, control is transferred to the first statement of the specified set of statements (except as indicated in General Rules 8b, 8c, 8d and 8e). This transfer of control occurs only once for each execution of a PERFORM statement. For those cases where a transfer of control to the specified set of statements does take place, an implicit transfer of control to the end of the PERFORM statement is established as follows:
    1. If procedure-name-1 is a paragraph-name and procedure-name-2 is not specified, the return is after the last statement of procedure-name-1.
    2. If procedure-name-1 is a section-name and procedure-name-2 is not specified, the return is after the last statement of the last paragraph in procedure-name-1.
    3. If procedure-name-2 is specified and it is a paragraph-name, the return is after the last statement of the paragraph.
    4. If procedure-name-2 is specified and it is a section-name, the return is after the last statement of the last paragraph in the topic.
  3. There is no necessary relationship between procedure-name-1 and procedure-name-2 except that a consecutive sequence of operations is to be executed beginning at the procedure named procedure-name-1 and ending with the execution of the procedure named procedure-name-2. In particular, GO and PERFORM statements can occur between procedure-name-1 and the end of procedure-name-2. If there are two or more logical paths to the return point, then procedure-name-2 can be the name of a paragraph consisting of the EXIT statement, to which all of these paths must lead.
  4. If the range of a PERFORM statement includes another PERFORM statement, the sequence of procedures associated with the included PERFORM should itself either be totally included in, or totally excluded from, the logical sequence referred to by the first PERFORM. Thus, an active PERFORM statement, whose execution point begins within the range of another active PERFORM statement should not allow control to pass to the exit of the other active PERFORM statement; furthermore, two or more such active PERFORM statements should not have a common exit.

    MF These restrictions are not enforced. PERFORM statements can be freely nested, and recursion (a PERFORM statement performing a procedure containing it) is allowed. Only the exit point of the innermost PERFORM statement currently being executed is recognized. These rules can be changed by use of the PERFORM-TYPE Compiler directive.

    See the following illustrations for examples of legal PERFORM constructs.

General Rules for Format 2

  5. ANS85 The statements contained in the PERFORM statement itself are referred to as the specified set of statements.
  6. ANS85 The END-PERFORM phrase delimits the scope of the in-line PERFORM statement. (See the topic Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)
  7. ANS85 An in-line PERFORM statement functions according to the following general rules for an otherwise identical out-of-line PERFORM statement, with the exception that the statements contained within the in-line PERFORM statement are executed in place of the statements contained within the range of procedure-name-1 (through procedure-name-2 if specified). Unless specifically qualified by the word in-line or out-of-line, all the general rules which apply to the out-of-line PERFORM statement also apply to the in-line PERFORM statement.
  8. When the PERFORM statement is executed, control is transferred to the first statement of the specified set of statements (except as indicated in the General Rules 2b, 2c, 2d and 2e). This transfer of control occurs only once for each execution of a PERFORM statement. For those cases where a transfer of control to the specified set of statements does take place, an implicit transfer of control to the end of the PERFORM statement is established as follows:
    1. MF An EXIT PERFORM statement can be used to exit an in-line perform before executing all statements within the in-line perform.

General Rules for Formats 1 and 2

  9. If control passes to the specified set of statements by means other than a PERFORM statement, control passes through the last statement of the set to the next executable statement as if no PERFORM statement referenced the set.
  10. The PERFORM statements operate as follows:
    1. In the basic PERFORM statement, the specified set of statements referenced by this type of PERFORM statement is executed once and then control passes to the end of the PERFORM statement.
    2. If you use the PERFORM ... TIMES form, the specified set of statements is performed the number of times specified by integer-1 or by the initial value of the data item referenced by identifier-1 for that execution. If at the time of the execution of a PERFORM statement, the value of the data item referenced by identifier-1 is equal to zero or is negative, control passes to the end of the PERFORM statement. Following the execution of the specified set of statements the specified number of times, control is transferred to the end of the PERFORM statement.

      During execution of the PERFORM statement, reference to identifier-1 cannot alter the number of times the specified set of statements is to be executed from that which was indicated by the initial value of the data item referenced by identifier-1.

      Integer-1 must be zero or positive, but it may be signed.

    3. If you use the PERFORM ... UNTIL form, the specified set of statements is performed until the condition specified by the UNTIL phrase is true. When the condition is true, control is transferred to the end of the PERFORM statement. If the condition is true when the PERFORM statement is entered,

      ANS85 and the TEST BEFORE phrase is specified or implied,

      no transfer to procedure-name-1 takes place, and control is passed to the end of the PERFORM statement.

      ANS85 If the TEST AFTER phrase is specified, the PERFORM statement functions as if the TEST BEFORE phrase were specified except that the condition is tested after the specified set of statements has been executed. Any subscripting or reference modification associated with the operands specified in condition-1 is evaluated each time the condition is tested.

      MF When UNTIL EXIT is specified, the specified set of statements is performed repeatedly until some statement in the set causes this repetition to end. In the case of an out-of-line PERFORM, the only statements that will cause this termination are statements such as EXIT PROGRAM and STOP RUN. In the case of an in-line PERFORM, the repetition can also be terminated by the EXIT PERFORM statement and the GO TO statement.

    4. If you use the PERFORM ... VARYING form, the PERFORM statement is used to augment the values referenced by one or more identifiers or index-names in an orderly fashion during the execution of a PERFORM statement. In the following discussion, every reference to identifier as the object of the VARYING, AFTER, and FROM (current value) phrases also refers to index-names.

      If index-name-1 is specified, the value of identifier-3, index-name-2, or literal-1 at the beginning of the execution of the PERFORM statement must correspond to an occurrence number of an element in the table associated with index-name-1. If index-name-3 is specified, the value of identifier-6, index-name-4, or literal-3 at the beginning of the execution of the PERFORM statement must correspond to an occurrence number of an element in the table associated with index-name-3.

      Subsequent augmentation, as described below, of index-name-1 or index-name-3 must not result in the associated index being set to a value outside the range of the table associated with index-name-1 or index-name-3; except that, at the completion of the PERFORM statement, the index associated with index-name-1 can contain a value that is outside the range of the associated table by one increment or decrement value.

      If identifier-2 or identifier-5 is subscripted, the subscripts are evaluated each time the content of the data item referenced by the identifier is set or augmented. If identifier-3, identifier-4, identifier-6, or identifier-7 is subscripted, the subscripts are evaluated each time the content of the data item referenced by the identifier is used in a setting or augmenting operation. Any subscripting or reference modification associated with the operands specified in condition-1 or condition-2 is evaluated each time the condition is tested.

      Representations of the actions of several types of PERFORM statements are given on the following pages.

      1. If the TEST BEFORE phrase is specified or implied:

        When the data item referenced by one identifier is varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 at the point of initial execution of the PERFORM statement; then, if the condition of the UNTIL phrase is false, the specified set of statements is executed once. The value of the data item referenced by identifier-2 is augmented by the specified increment or decrement value (literal-2 or the value of the data item referenced by identifier-4) and condition-1 is evaluated again. The cycle continues until this condition is true, at which point control is transferred to the end of the PERFORM statement. If condition-1 is true at the beginning of execution of the PERFORM statement, control is transferred to the end of the PERFORM statement. See the diagram below.

        The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having One Condition

        When the data items referenced by two identifiers are varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 and then the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6. See the diagram of The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having Two Conditions below.

        After the contents of the data items referenced by the identifiers have been set, condition-1 is evaluated; if true, control is transferred to the end of the PERFORM statement; if false, condition-2 is evaluated. If condition-2 is false, the specified set of statements is executed once, then the content of the data item referenced by identifier-5 is augmented by literal-4 or the content of the data item referenced by identifier-7 and condition-2 is evaluated again.

        This cycle of evaluation and augmentation continues until this condition is true. When condition-2 is true, the content of the data item referenced by identifier-2 is augmented by literal-2 or the content of the data item referenced by identifier-4, the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6, and condition-1 is reevaluated. The PERFORM statement is completed if condition-1 is true; if not, the cycle continues until condition-1 is true.

        At the termination of the PERFORM statement, the data item referenced by identifier-5 contains literal-3 or the current value of the data item referenced by identifier-6. The data item referenced by identifier-2 contains a value that exceeds the last used setting by one increment or decrement value, unless condition-1 was true when the PERFORM statement was entered, in which case the data item referenced by identifier-2 contains literal-1 or the current value of the data item referenced by identifier-3.

        Figure 1. The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having Two Conditions
        The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having Two Conditions
      2. ANS85 If the TEST AFTER phrase is specified:

        When the data item referenced by one identifier is varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 at the point of execution of the PERFORM statement; then the specified set of statements is executed once and condition-1 of the UNTIL phrase is tested. If the condition is false, the value of the data item referenced by identifier-2 is augmented by the specified increment or decrement value (literal-2 or the value of the data item referenced by identifier-4) and the specified set of statements is executed again. The cycle continues until condition-1 is tested and found to be true, at which point control is transferred to the end of the PERFORM statement. See the diagram below.

        The VARYING Option of a PERFORM Statement with the TEST AFTER Phrase Having One Condition

        When the data items referenced by two identifiers are varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3; then the current value of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6; and the specified set of statements is then executed. Condition-2 is then evaluated; if false, the content of the data item referenced by identifier-5 is augmented by literal-4 or the content of the data item referenced by identifier-7 and the specified set of statements is again executed. The cycle continues until condition-2 is again evaluated and found to be true, at which time condition-1 is evaluated. If false, the content of the data item referenced by identifier-2 is augmented by literal-2 or the content of data item referenced by identifier-4, the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6 and the specified set of statements is again executed. This cycle continues until condition-1 is again evaluated and found to be true, at which time control is transferred to the end of the PERFORM statement. See the diagram The VARYING Option of a PERFORM Statement with a TEST AFTER Phrase Having Two Conditions below.

        After completion of the PERFORM statement, each data item varied by an AFTER or VARYING phrase contains the same value it contained at the end of the most recent execution of the specified set of statements.

        Figure 2. The VARYING Option of a PERFORM Statement with a TEST AFTER Phrase Having Two Conditions
        The VARYING Option of a PERFORM Statement with a TEST AFTER Phrase Having Two Conditions

        During the execution of the specified set of statements associated with the PERFORM statement, any change to the VARYING variable (the data item referenced by identifier-2 and index-name-1), the BY variable (the data item referenced by identifier-4), the AFTER variable (the data item referenced by identifier-5 and index-name-3), or the FROM variable (the data item referenced by identifier-3 and index-name-2) is taken into consideration and affects the operation of the PERFORM statement.

        When the data items referenced by two identifiers are varied, the data item referenced by identifier-5 goes through a complete cycle (FROM, BY, UNTIL) each time the content of the data item referenced by identifier-2 is varied. When the contents of three or more data items referenced by identifiers are varied, the mechanism is the same as for two identifiers except that the data item being varied by each AFTER phrase goes through a complete cycle each time the data item being varied by the preceding AFTER phrase is augmented.

  11. The range of a PERFORM statement consists logically of all those statements that are executed as a result of executing the PERFORM statement through execution of the explicit transfer of control to the end of the PERFORM statement. The range includes all statements that are executed as the result of a transfer of control by CALL, EXIT, GO TO and PERFORM statements in the range of the PERFORM statement, as well as all statements in declarative procedures that are executed as a result of the execution of statements in the range of the PERFORM statement. The statements in the range of a PERFORM statement need not appear consecutively in the source element.
  12. Statements executed as the result of a transfer of control caused by executing an EXIT PROGRAM statement are not considered to be part of the range of the PERFORM statement when both of the following conditions apply:
    1. The EXIT PROGRAM statement is specified in the same program in which the PERFORM statement is specified
    2. The EXIT PROGRAM statement is within the range of the PERFORM statement.
  13. The data items referenced by identifier-4 and identifier-7 must not have a zero value.
  14. If an index-name is specified in the VARYING or AFTER phrase, and an identifier is specified in the associated FROM phrase, the data item referenced by the identifier must have a positive value.
Parent topic: Statements
Related reference
PERFORM Statement
Related information
The EXIT Statement
Conditional Expressions
Explicit and Implicit Scope Terminators


RAISE Statement (COBOL)

The RAISE Statement

The RAISE statement raises an exception.

General Formats

Syntax Rules

  1. Identifier-1 must be an object reference of class System.Exception or a subclass of System.Exception.

General Rules

  1. If identifier-1 is specified, it is raised as an exception.
  2. If identifier-1 is not specified, the current exception is re-raised.
Parent topic: Statements


READ Statement (COBOL)

The READ Statement

For sequential access, the READ statement makes available the next

MF or previous

logical record from a file. For random access, the READ statement makes available a specified record from a mass storage file.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative and Indexed Files)

General Formats for Format 4 (Relative Files)

General Formats for Format 5 (Indexed Files)

Directives and RTS switches

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • RETRYLOCK - causes the COBOL system to retry to read a locked record.
  2. The following RTS switches may impact the semantics described in this section.
    • B, B1 - causes the record pointer to be updated past any locked record encountered when executing a READ NEXT statement.
    • N - controls the interpretation of null characters before control characters when reading line sequential records.
    • T - controls the interpretation of tab characters when writing line sequential records.

Syntax Rules for All Formats (All Files)

  1. The INTO phrase must not be used when the input file contains logical records of various sizes as indicated by their record descriptions.

    ANS85 This restriction is removed.

    The storage area associated with identifier and the storage area which is the record area associated with file-name must not be the same storage area.

  2. OSVS VSC2 MF Identifier can be a floating-point data item.
  3. The INVALID KEY phrase or the AT END phrase must be specified if no applicable USE procedure is specified for file-name.

    OSVS VSC2 MF This rule is not enforced.

Syntax Rules for Formats 1, 3, 4 and 5 (Record Sequential, Relative and Indexed Files)

  4. MF The WITH LOCK phrase can be included only when single records are being locked manually in a shareable file.
  5. MF The WITH NO LOCK phrase is only allowed when records are being locked manually or automatically in a shareable file.

Syntax Rules for Format 3 (Relative and Indexed Files)

  6. The NEXT

    MF or PREVIOUS

    phrases must be specified for files in dynamic access mode when records are to be retrieved sequentially.

Syntax Rules for Formats 3, 4 and 5 (Relative and Indexed Files)

  7. MF The WITH KEPT LOCK phrase can be included only when multiple records are being locked manually in a shareable file.

Syntax Rules for Formats 4 and 5 (Relative and Indexed Files)

  8. Format 4 or 5 is used for files in random access mode or for files in dynamic access mode when records are to be retrieved randomly.

Syntax Rules for Format 5 (Indexed Files)

  9. Data-name

    ISO2002 MF or split-key-name

    must be the name of a data item specified as a record key associated with file-name.

    OSVS MF Data-name may also be a redefinition of a data-item specified as a record key associated with a file-name, provided the data-name has the same length as that data-item.

    OSVS The redefinition may have a different length from the record key.

  10. Data-name

    ISO2002 MF or split-key-name

    can be qualified.
  11. MF Split-key-name is a concatenation of one or more data items specified as a record key associated with file-name.
  12. When the DIALECT"RM" or DIALECT"ACU" directives are in effect, the data-name or split-key-name specified in the KEY phrase is implicitly qualified by the file-name specified in the READ statement when the file-name is not already explicitly specified as the final qualifier of the data-name or split-key-name. For any other dialect, the data-name or split-key-name may need to explicitly specify file-name as the final qualifier to satisfy uniqueness of reference rules.

General Rules for All Formats (All Files)

  1. The associated file must be open in the INPUT or I-O mode at the time the statement is executed. (See the topic The OPEN Statement.)
  2. The execution of the READ statement causes the value of the FILE STATUS data item, if any, associated with file-name to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  3. When the logical records of a file are described by more than one record description, these records automatically share the same storage area; this is equivalent to an implicit redefinition of the area. The contents of any data items which lie beyond the range of the current data record are undefined at the completion of the execution of the READ statement.
  4. If the INTO phrase is specified, the record being read is moved from the record area to the area specified by identifier according to the rules specified for the MOVE statement without the CORRESPONDING phrase. The implied MOVE does not occur if execution of the READ statement was unsuccessful. Any subscripting or indexing associated with identifier is evaluated after the record has been read and immediately before it is moved to the data item.
  5. When the INTO phrase is used, the record being read is available in both the input record area and data area associated with identifier.
  6. If the file position indicator indicates that no next logical record exists, or that an optional input file is not present, the following occurs in the order specified:
    1. A value, derived from the setting of the file position indicator, is placed into the FILE STATUS data item associated with file-name-1 to indicate the at end condition. (See the topic I-O Status in the chapter Procedure Division.)
    2. If the AT END phrase is specified in the statement causing the condition, control is transferred to AT END imperative-statement-1. Any USE AFTER EXCEPTION procedure associated with the file connector referenced by file-name-1 is not executed. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the READ statement and the NOT AT END phrase, if specified, is ignored.
    3. If the AT END phrase is not specified, a USE AFTER STANDARD EXCEPTION procedure must be associated with this file-name-1, and that procedure is executed. Return from that procedure is to the next executable statement following the end of the READ statement.

      ANS85 When the AT END condition occurs, the execution of the READ statement is unsuccessful.

  7. Following the unsuccessful execution of any READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no next record has been established.
  8. When running non-transactional file handling on a UNIX platform, when using FCD3, a record locked status returns the process-id of the locking process to the fcd-session-id of the FCD; this operation does not apply when using Fileshare.

General Rules for Format 1 (Record Sequential Files)

  9. The record to be made available by the READ statement is determined as follows:
    1. ANS85 If the file position indicator was positioned by the execution of the OPEN statement, the record pointed to by the file position indicator is made available.
    2. ANS85 If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next existing record in the file, and that record is made available.

      MF However if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available.

  10. If the end of a reel or unit is recognized during the execution of a READ statement, and end-of-file has not been reached, the following procedures are executed:
    1. The standard ending reel/unit label procedure.
    2. A reel/unit swap.
    3. The standard beginning reel/unit label procedure.
    4. The first data record of the new reel/unit is made available.
  11. If a file described with the OPTIONAL clause is not present at the time the file is opened, then at the time of execution of the first READ statement for the file, the AT END condition occurs and execution of the READ statement is unsuccessful. The standard end of file procedures are not performed. (See the topic The File-Control Paragraph, the topic The OPEN Statement and the topic The USE Statement.) Execution then proceeds as in General Rule 13.
  12. MF For files opened for INPUT, the READ, READ WITH LOCK or READ WITH KEPT LOCK statements do not acquire a record lock.
  13. MF Two or more run units can share a sequential output file by opening it EXTEND with AUTOMATIC or MANUAL record locking. Records that are appended to the file are in unspecified order.
  14. MF For files opened for I/O:
    1. With LOCK MODE AUTOMATIC, unless the WITH NO LOCK phrase is specified, each record is locked as it is read.
    2. With LOCK MODE MANUAL, a simple READ statement does not acquire a lock on the record - the READ WITH LOCK statement must be used to acquire a record lock. The WITH NO LOCK phrase, if specified, is documentary.
    3. The use of multiple or single record locking determines when the record lock is released. (See the topic The File Control Entry.)
  15. MF If an end-of-file status occurs on a READ statement in a file opened for I/O or INPUT by one run unit and opened EXTEND by another run unit, the run unit that attempted the READ must close the file. This run unit has no access to the appended records because the status remains end-of-file.

General Rules for Formats 1, 2 and 3 (Sequential, Relative and Indexed Files)

  16. If an AT END condition does not occur during the execution of a READ statement, the AT END phrase, if specified, is ignored and the following actions occur:
    1. The file position indicator is set and the I/O status associated with file-name-1 is updated.
    2. If an exception condition which is not an AT END condition exists, control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to file-name-1. (See the topic The USE Statement.)
    3. If no exception condition exists, the record is made available in the record area and any implicit move resulting from the presence of an INTO phrase is executed. Control is transferred to the end of the READ statement or to imperative-statement-2, if specified. In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2. If a control branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the READ statement.
  17. If when a READ statement with the NEXT option is executed, no next logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful. See the topic I-O Status in the chapter Procedure Division.
  18. For

    ANS85 sequential files or

    files in sequential access mode, the NEXT phrase is optional and has no effect on the execution of the READ statement.

General Rules for Format 3 (Relative and Indexed Files)

  19. MF Following a READ which encounters a locked record status, the file position indicator points at the locked record. A subsequent READ NEXT or READ PREVIOUS will retrieve the same record again.

    The NOT AT END phrase is only executed following successful completion of the operation.

  20. MF If when a READ statement with the PREVIOUS option is executed no previous logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful.
  21. When the AT END condition has been recognized,

    MF the next Format 3 READ statement, if any, executed for that file must be a READ NEXT statement, if AT END occurred because no previous logical record existed. Otherwise

    the AT END condition must be followed by:

    1. A successful CLOSE statement followed by the execution of a successful OPEN statement for that file.
    2. A successful START statement for that file.
    3. A successful Format 4 (or Format 5 for indexed files) READ statement for that file.
  22. For a file for which dynamic access mode is specified, a READ statement with the NEXT phrase specified causes the next logical record to be retrieved from the file

    MF as described in General Rule 8.

  23. The record to be made available by the READ statement is determined as follows:
    1. MF If the file position indicator was positioned by the execution of an OPEN statement, and the PREVIOUS option is specified, the AT END condition occurs. Otherwise

      if the file position indicator was positioned by the execution of the START or OPEN statement and the record is still accessible through the path indicated by the file position indicator, the record pointed to by the file position indicator is made available. If the record is no longer accessible, which can have been caused for a relative file by deletion of the record, or for an indexed file by a change in an alternate key, the file position indicator is updated to point to the next

      MF or, if the PREVIOUS option is specified, the previous

      existing record within the established key of reference, and that record is then made available.

    2. If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next

      MF or, if the PREVIOUS option is specified, the previous

      existing record in the file.

      MF However, if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available.

General Rules for Formats 1, 3, 4 and 5 (Sequential, Relative and Indexed Files)

  24. MF If the lock mode is MANUAL with single record locking and the referenced file is opened I/O, the run unit acquires a record lock on the record only if the WITH LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates.
  25. MF If the lock mode is MANUAL with multiple record locking and the referenced file is opened I/O, the run unit acquires a lock on the record only if the WITH KEPT LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates.
  26. MF The WITH WAIT phrase ensures that a lock is acquired on the record, waiting if necessary.

General Rules for Format 3 (Relative Files)

  27. If the RELATIVE KEY phrase is specified for the file, the execution of a READ statement updates the contents of the RELATIVE KEY data item so that it contains the relative record number of the record made available.

General Rules for Format 4 (Relative Files)

  28. The execution of a READ statement sets the file position indicator to, and makes available, the record whose relative record number is contained in the data item named in the RELATIVE KEY phrase for the file. If the file does not contain such a record, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)

General Rules for Formats 3 and 5 (Relative and Indexed Files)

  29. MF The IGNORE LOCK phrase causes the READ to proceed as if the record were not locked.

General Rules for Format 3 (Indexed Files)

  30. For an indexed file being sequentially accessed, records having the same duplicate value in an alternate record key which is the key of reference are made available in the same order in which they are released by execution of WRITE statements, or by execution of REWRITE statements which create such duplicate values.

General Rules for Format 5 (Indexed Files)

  31. If the KEY phrase is not specified the prime record key is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used for retrievals by any subsequent executions of Format 3 READ statements for the file.
  32. If the KEY phrase is specified, data-name-1

    ISO2002 MF or split-key-name

    is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used for retrievals by any subsequent executions of Format 3 READ statements for the file until a different key of reference is established for the file.

  33. Execution of a Format 5 READ statement causes the value of the key of reference to be compared with the value contained in the corresponding data item of the stored records in the file, until the first record having an equal value is found. The file position indicator is positioned to this record which is then made available. If no record can be so identified, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)
Parent topic: Statements
Related reference
End of File Notification
Related information
The OPEN Statement
I-O Status
The File-Control Paragraph
The USE Statement
The File Control Entry
The INVALID KEY Condition


RELEASE Statement (COBOL)

The RELEASE Statement

The RELEASE statement transfers records to the initial phase of a SORT operation.

General Format

Syntax Rules

  1. A RELEASE statement can only be used within the range of an input procedure associated with a SORT statement for a file whose sort-merge file description entry contains record-name. (See the topic The SORT Statement.)
  2. Record-name must be the name of a logical record in the associated sort-merge file description entry and can be qualified.
  3. ANS85 If identifier is a function-identifier, it must reference an alphanumeric function. When identifier is not a function-identifier,

    record-name and identifier must not reference the same storage area.

  4. OSVS VSC2 MF Record-name can be defined as a floating-point item.
  5. OSVS VSC2 MF Identifier can be a floating-point item.

General Rules

  1. The execution of a RELEASE statement causes the record named by record-name to be released to the initial phase of a sort operation.
  2. If the FROM phrase is used, the contents of the identifier data area are moved to record-name, then the contents of record-name are released to the sort file. Moving records takes place according to the rules specified for the MOVE statement without the CORRESPONDING phrase. The information in the record area is no longer available, but the information in the data area associated with identifier is available.
  3. After the execution of the RELEASE statement, the logical record is no longer available in the record area unless the associated sort-merge file is named in a SAME RECORD AREA clause. The logical record is also available as a record of other files referenced in the same SAME RECORD AREA clause as the associated sort-merge file, as well as the file associated with record-name. When control passes from the input procedure, the file consists of all those records which were placed in it by the execution of RELEASE statements.
Parent topic: Statements
Related information
The SORT Statement


RESET Collection Statement (COBOL)

The RESET Collection Statement

Deletes all the elements from the list or dictionary.

General Formats

Where: identifier is the name of the list or dictionary collection type.

Parent topic: Statements


RETURN Statement (COBOL)

The RETURN Statement

The RETURN statement obtains either sorted records from the final phase of a SORT operation or merged records during a MERGE operation.

General Format

Syntax Rules

  1. File-name must be described by a sort-merge file description entry in the Data Division.
  2. A RETURN statement can only be used within the range of an output procedure associated with a SORT or MERGE statement for file-name.
  3. The INTO phrase must not be used when the input file contains logical records of various sizes as indicated by their record descriptions. The storage area associated with identifier and the record area associated with file-name must not be the same storage area.
  4. OSVS VSC2 MF Identifier-1 can be a floating-point item.

General Rules

  1. When the logical records of a file are described with more than one record description, these records automatically share the same storage area; this is equivalent to an implicit redefinition of the area. The contents of any data items which lie beyond the range of the current data record are undefined at the completion of the execution of the RETURN statement.
  2. The execution of the RETURN statement causes the next existing record in the file referenced by file-name, as determined by the keys listed in the SORT or MERGE statement, to be made available in the record area associated with file-name. If no next logical record exists in the file referenced by file-name, the AT END condition exists and control is transferred to imperative-statement-1 of the AT END phrase. Execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred according to the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the RETURN statement

    ANS85 and the NOT AT END phrase if specified is ignored.

    When the AT END condition occurs, execution of the RETURN statement is unsuccessful and the contents of the record area associated with file-name are undefined. After the execution of imperative-statement-1 in the AT END phrase, no RETURN statement can be executed as part of the current output procedure.

  3. ANS85 If an AT END condition does not occur during the execution of a RETURN statement, then after the record is made available and after executing any implicit move resulting from the presence of an INTO phrase, control is transferred to imperative-statement-2, if specified. Otherwise, control is transferred to the end of the RETURN statement.
  4. ANS85 The END-RETURN phrase delimits the scope of the RETURN statement.
  5. The INTO phrase can be specified in a RETURN statement if one of the following conditions apply:
    • If only one record description is subordinate to the sort-merge file description entry:
    • If all record-names associated with file-name and the data item referenced by identifier describe groups item or elementary alphanumeric items.
  6. The result of the execution of a RETURN statement with the INTO phrase is equivalent to the application of the following rules in the order specified:
    1. The same RETURN statement without the INTO phrase is executed.
    2. The current record is moved from the record area to the area specified by identifier according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified for the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the RETURN statement was unsuccessful. Any subscripting associated with identifier-1 is evaluated after the record has been read and immediately before it is moved to the data item. The record is available in both the record area and the data item referenced by identifier-1.
Parent topic: Statements


REWRITE Statement (COBOL)

The REWRITE Statement

The REWRITE statement logically replaces a record existing in a disk file.

General Formats for Format 1 (Line Sequential Files)

REWRITE - FORMAT 1

General Formats for Format 2 (Record Sequential Files)

REWRITE - FORMAT 2

General Formats for Format 2 (Relative and Indexed Files)

REWRITE - FORMAT 3

Directives and RTS switches

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • WRITE-LOCK - acquires a record lock for a REWRITE statement when multiple recording locking is used.
  2. The following RTS switches may impact the semantics described in this section.
    • N - controls the insertion of null characters before control characters when writing line sequential records.
    • T - controls the insertion of tab characters when writing line sequential records.

Syntax Rules for All Formats (All Files)

  1. ANS85 If identifier is a function-identifier, it must reference an alphanumeric function. When identifier is not a function-identifier,

    record-name and identifier must not reference the same storage area.

  2. Record-name is the name of a logical record in the File Section of the Data Division and can be qualified.
  3. OSVS VSC2 MF Record-name can define a floating point or DBCS item.
  4. OSVS VSC2 MF Identifier can be a USAGE DISPLAY-1 (DBCS) item or a floating- point item.

Syntax Rules for Format 3 (Relative and Indexed Files)

  5. The INVALID KEY phrase must not be specified for a REWRITE statement which references a file in sequential access mode.

    OSVS VSC2 However, it can be specified for an indexed file in sequential access mode.

  6. The INVALID KEY phrase must be specified in the REWRITE statement for files in the random or dynamic access mode for which an appropriate USE procedure is not specified.

General Rules for All Formats (All Files)

  1. The file associated with record-name must be a disk file and must be open in the I-O mode at the time of execution of this statement. (See the section The OPEN Statement.)
  2. For files in the sequential access mode the last input-output statement executed for the associated file prior to the execution of the REWRITE statement must have been a successfully executed READ statement. The operating system logically replaces the record that was accessed by the READ statement.
  3. The execution of a REWRITE statement with the FROM phrase is equivalent to the execution of:
     MOVE identifier TO record-name

    followed by the execution of the same REWRITE statement without the FROM phrase. The contents of the record area prior to the execution of the implicit MOVE statement have no effect on the execution of the REWRITE statement.

  4. The file position indicator is not affected by the execution of a REWRITE statement.
  5. The execution of the REWRITE statement causes the value of the FILE STATUS data item, if any, associated with the file to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  6. ANS85 The END-REWRITE phrase delimits the scope of the REWRITE statement.
  7. MF A REWRITE is unsuccessful if any other run unit holds a lock on the record to be rewritten.

General Rules for Formats 1 and 2 (Sequential Files)

  8. The number of character positions in the record referenced by record-name must be equal to the number of character positions in the record being replaced.
    Note: We recommend that you do not use the REWRITE statement on compressed sequential files because a REWRITE operation will only succeed if the length of the compressed new record is the same as the length of the compressed old record.
  9. The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause. In this case, the record is still available in the record area, not only as a record of this file, but also as a record of other files named in the SAME RECORD AREA clause.

General Rules for Format 1 (Line SequentialFiles)

  10. MF The REWRITE statement can be used and is considered successful whenever the record being written (after compacting by removing trailing spaces, tab compression and null insertion) is less than or equal to the length of the original compacted record. When a record is read, nulls and tab characters in the record can be expanded and this makes the record longer.

General Rules for Format 3 (Relative and IndexedFiles)

  11. The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause, in which case the logical record is available both as a record of other files appearing in the same SAME RECORD AREA clause as the associated I/O file, as well as the file associated with record-name.

General Rules for Format 3 (Relative Files)

  12. For a file accessed in either random or dynamic access mode, the operating system logically replaces the record specified by the contents of the RELATIVE KEY data item associated with the file. If the file does not contain the record specified by the key, the INVALID KEY condition exists (see the topic The INVALID KEY Condition in the chapter Procedure Division), the updating operation does not take place and the data in the record area is unaffected.

General Rules for Format 3 (Indexed Files)

  13. For a file in sequential access mode, the record to be replaced is specified by the value contained in the prime record key. When the REWRITE statement is executed, the value contained in the prime record data item of the record to be replaced must be equal to the value of the prime record key of the last record read from this file.
  14. For a file in random or dynamic access mode, the record to be replaced is specified by the prime record key data item.
  15. The contents of alternate record key data items of the record being rewritten can differ from those in the record being replaced. The operating system uses the contents of the record key data items during execution of the REWRITE statement so that the record can subsequently be accessed via any of those specified record keys.
  16. The INVALID KEY condition exists when any of the following is true:
    1. Access mode is sequential and the value contained in the prime record key data item of the record to be replaced is not equal to the value of the prime record key of the last record read from this file:
    2. The value contained in the prime record key data item does not equal that of any record stored in the file:
    3. The value contained in an alternate record key data item for which a DUPLICATES clause has not been specified is equal to that of a record already stored in the file.

    The updating operation does not take place and the data in the record area is unaffected. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)

Parent topic: Statements
Related information
The OPEN Statement
I-O Status
The INVALID KEY Condition


ROLLBACK Statement (COBOL)

The ROLLBACK Statement

The ROLLBACK statement releases all record locks in all files held by this run unit.

General Format

General Rules

  1. Execution of the ROLLBACK statement causes all record locks in all files held by the run unit to be released.
  2. The file lock on an exclusive file is not affected by the ROLLBACK statement.
  3. If your COBOL system supports the WITH ROLLBACK clause of the SELECT statement as other than documentary, then the ROLLBACK verb:
    1. Indicates completion of the current transaction
    2. Ensures all changes applied during the transaction are canceled.
Parent topic: Statements


SEARCH Statement (COBOL)

The SEARCH Statement

The SEARCH statement is used to search a table for a table element that satisfies the specified condition and to adjust the associated index-name to indicate that table element.

General Format for Format 1

General Format for Format 2

SEARCH - Format 2

Syntax Rules for All Formats (All Files)

  1. Identifier-1 must not be subscripted or indexed, but its description must contain an OCCURS clause and an INDEXED BY clause. The description of identifier-1 in Format 2 must also contain the KEY IS phrase in its OCCURS clause.
  2. Identifier-2, when specified, must be described as USAGE IS INDEX or as a numeric elementary item without any positions to the right of the assumed decimal point.
  3. ANS85 If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not be specified.

    VSC2 MF END-SEARCH can be specified with NEXT SENTENCE. If the NEXT SENTENCE phrase is executed, control does not pass to the next statement following the END-SEARCH, but instead passes to the statement after the closest following period.

  4. MF Both imperative-statement-1 and imperative-statement-2 can be replaced by a conditional statement.

Syntax Rules for Format 1

  5. Condition-1, condition-2, and so on, can be any condition as described in the section Conditional Expressions in the chapter Procedure Division.
  6. OSVS VSC2 MF Identifier-1, the table element being searched, can be an internal or external floating-point item.

Syntax Rules for Format 2

  7. All referenced condition-names must be defined as having only a single value. The data-name associated with a condition-name must appear in the KEY clause of identifier-1. Each data-name-1, data-name-2 can be qualified. Each data-name-1, data-name-2 must be indexed by the first index-name associated with identifier-1 along with other indices or literals as required, and must be referenced in the KEY clause of identifier-1. Identifier-3, identifier-4, or identifiers specified in arithmetic-expression-1, arithmetic-expression-2 must not be referenced in the KEY clause of identifier-1 or be indexed by the first index-name associated with identifier-1.

    When a data-name in the KEY clause of identifier-1 is referenced, or when a condition-name associated with a data-name in the KEY clause of identifier-1 is referenced, all preceding data-names in the KEY clause of identifier-1 or their associated condition-names must also be referenced.

  8. OSVS VSC2 MF Identifier-1, the table element being searched, cannot be a floating-point item.
  9. OSVS VSC2 MF Neither data-name-1 nor data-name-2, the key data items, can be floating-point items. However, identifier-3, identifier-4, literal-1, or literal-2, the items against which the key is compared, can be floating-point items.

General Rules for All Formats

  1. The scope of a SEARCH statement can be terminated by any of the following:
    • ANS85 An END-SEARCH phrase at the same level of nesting.
    • Separator period.
    • An ELSE

      ANS85 or END-IF

      associated with a previous IF statement.

  2. After execution of imperative-statement-1 or imperative-statement-2 that does not terminate with a GO TO statement, control passes to the next executable sentence.
  3. If identifier-1 is a data item subordinate to a data item that contains an OCCURS clause (providing for a two- or three-dimensional table), an index-name must be associated with each dimension of the table through the INDEXED BY phrase of the OCCURS clause. Only the setting of the index-name associated with identifier-1 (and the data item identifier-2 or index-name-1, if present) is modified by the execution of the SEARCH statement. To search an entire two- or three-dimensional table it is necessary to execute a SEARCH statement several times. Prior to each execution of a SEARCH statement, SET statements must be executed whenever index-names must be adjusted to appropriate settings.

General Rules for Serial search Format 1

  4. If Format 1 of the SEARCH statement is used, a serial type of search operation takes place, starting with the current index setting.
    1. If, at the start of execution of the SEARCH statement, the index-name associated with identifier-1 contains a value that corresponds to an occurrence number that is greater than the highest permissible occurrence number for identifier-1, the SEARCH is terminated immediately. The number of occurrences of identifier-1, the last of which is the highest permissible, is discussed in the topic The OCCURS Clause in the chapter Data Division - File and Data Description.) Then, if the AT END phrase is specified, imperative-statement-1 is executed; if the AT END phrase is not specified, control passes to the next executable sentence.
    2. If, at the start of execution of the SEARCH statement, the index-name associated with identifier-1 contains a value that corresponds to an occurrence number that is not greater than the highest permissible occurrence number for identifier-1 (the number of occurrences of identifier-1, the last of which is the highest permissible is discussed in the topic The OCCURS Clause), the SEARCH statement operates by evaluating the conditions in the order that they are written, making use of the index settings, wherever specified, to determine the occurrence of those items to be tested. If none of the conditions is satisfied, the index name for identifier-1 is incremented to obtain reference to the next occurrence. The process is then repeated using the new index-name settings unless the new value of the index-name settings for identifier-1 corresponds to a table element outside the permissible range of occurrence values, in which case the search terminates as indicated in General Rule 4a above. If one of the conditions is satisfied upon its evaluation, the search terminates immediately and the imperative statement associated with that condition is executed; the index-name remains set at the occurrence which caused the condition to be satisfied.
  5. If the VARYING phrase is not used, the index-name that is used for the search operation is the first (or only) index-name that appears in the INDEXED BY phrase of identifier-1. Any other index-names for identifier-1 remain unchanged.
  6. If the VARYING index-name-1 phrase is specified, and if index-name-1 appears in the INDEXED BY phrase of identifier-1, that index-name is used for this search. If this is not the case, or if the VARYING identifier-2 phrase is specified, the first (or only) index-name given in the INDEXED BY phrase of identifier-1 is used for the search. In addition, the following operations occur:
    1. If the VARYING index-name-1 phrase is used, and if index-name-1 appears in the INDEXED BY phrase of another table entry, the occurrence number represented by index-name-1 is incremented by the same amount as the index-name associated with identifier-1, and at the same time.
    2. If the VARYING identifier-2 phrase is specified, and identifier-2 is an index data item, then the data item referenced by identifier-2 is incremented by the same amount as the index-name associated with identifier-1, and at the same time. If identifier-2 is not an index data item, the data item referenced by identifier-2 is incremented by the value (1) at the same time as the index referenced by the index-name associated with identifier-1 is incremented.

General Rules for Non-serial search Format 2

  7. The results of the SEARCH ALL operation are predictable only when:
    1. The data in the table is ordered in the same manner as described in the ASCENDING/DESCENDING KEY clause associated with the description of identifier-1, and:
    2. The contents of the key(s) referenced in the WHEN clause are sufficient to identify a unique table element.
  8. If Format 2 of the SEARCH statement is used, a non-serial type of search operation can take place; the initial setting of the index-name for identifier-1 is ignored and its setting is varied during the search operation with the restriction that at no time is it set to a value that exceeds the value which corresponds to the last element of the table, or that is less than the value that corresponds to the first element of the table. The length of the table is discussed in the topic The OCCURS Clause). If any of the conditions specified in the WHEN clause cannot be satisfied for any setting of the index within the permitted range, control is passed to imperative-statement-1 of the AT END phrase, when specified, or to the next executable sentence when this phrase is not specified; in either case the final setting of the index is not predictable. If all conditions can be satisfied, the index indicates an occurrence that allows the conditions to be satisfied, and control passes to imperative-statement-2.
  9. The index-name that is used for the search operation is the first (or only) index-name that appears in the INDEXED BY phrase of identifier-1. Any other index-names for identifier-1 remain unchanged.
  10. OSVS VSC2 MF Neither imperative-statement-2 nor NEXT SENTENCE is required. Without them, the SEARCH statement sets the index to the value in the table that matched the condition.

Comments:

Figure 1 shows a flowchart of a Format 1 SEARCH operation containing two WHEN phrases.

Figure 1. Flowchart of SEARCH Operation Showing Two WHEN Phrases
Flowchart of SEARCH Operation Showing Two WHEN Phrases
1 | These operations are options included only when specified in the SEARCH statement
2 | Each of these control transfers is to the next executable sentence unless the imperative-statement ends with a GO TO statement.
Parent topic: Statements
Related information
Conditional Expressions
The OCCURS Clause


SERVICE Statement (COBOL)

The SERVICE Statement

The SERVICE statement is used to establish addressability to Linkage Section items.

General Format

The SERVICE Statement

Syntax Rules

  1. SERVICE LABEL is not intended for general use.
  2. Identifier should be the first 01-level item representing the BLL-cell block in the Linkage Section.

General Rules

  1. The SERVICE RELOAD statement is documentary only in a program compiled with the VSC2 Compiler directive.
Parent topic: Statements


SET Statement (COBOL)

The SET Statement

The SET statement is used to alter the status of external switches.

ANS85 The SET statement is used to alter the value of conditional variables.

VSC2 MF The SET statement is used to assign the address of a data item to a pointer data item. It is also used to adjust the contents of a pointer data item.

The SET statement establishes reference points for table handling operations by setting indices associated with table elements.

MF The SET statement is used to assign the address of a program or an entry-point in a program to a procedure-pointer data item.

ISO2002 MF The SET statement is used to assign the address of a pointer to a program-pointer data item.

ISO2002 MF The SET statement is used to assign object references.

MF The SET statement is used to alter the value of a synchronization data item.

MF The SET statement is used to assign the address of a synchronization data item to another synchronization data item.

NET JVM The SET statement is used to alter the size of a native array.

NET JVM The SET statement is used to initialize the contents of a native array and to set the array size based on those contents.

NET JVM The SET statement is used to alter the value of a boolean data item with usage CONDITION-VALUE.

NET JVM The SET statement is used to alter the value of a data item with a native type.

General Formats for Format 1 (Switch-setting)

General Formats for Format 2 (Condition-setting)

General Formats for Format 3 (Data-pointer-assignment)

General Formats for Format 4 (Data-pointer-assignment)

General Formats for Format 5 (Data-pointer-arithmetic)

General Formats for Format 6 (Index-assignment)

General Formats for Format 7 (Index-arithmetic)

General Formats for Format 8 (Procedure-pointer-assignment)

General Formats for Format 9 (Object-reference-assignment)

General Formats for Format 10 (Value-of-Event-pointer)

General Formats for Format 11 (Address-of-Event-pointer)

General Formats for Format 12 (Value-of-Monitor-pointer)

General Formats for Format 13 (Address-of-Monitor-pointer)

General Formats for Format 14 (Value-of-Mutex-pointer)

General Formats for Format 15 (Address-of-Mutex-pointer)

General Formats for Format 16 (Value-of-Semaphore-pointer)

General Formats for Format 17 (Address-of-Semaphore-pointer)

General Formats for Format 18 (Size-of-array)

General Formats for Format 19 (Content-of-array)

General Formats for Format 20 (CONDITION-VALUE setting)

General Formats for Format 21 (data-setting)

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • STICKY-LINKAGE - determines whether addresses of data items placed in pointer data items by the SET statement are retained between invocations of a subprogram.

Syntax Rules for All Formats

  1. The figurative constant NULL or NULLS or the data item referenced by pointer-name-2 or procedure-pointer-name-2 represents the sending area. ADDRESS OF identifier-2, ENTRY identifier-8, ENTRY literal-1 or the value held in the sending area, represents the sending value.

    The data item referenced by pointer-name-1, pointer-name-3 or procedure-pointer-name-1 or the COBOL system area implied by ADDRESS OF identifier-1 represents the receiving area.

    Identifier-3, integer-1 or LENGTH OF identifier-4 represents the increment value.

Syntax Rules for Format 1

  2. ANS85 Mnemonic-name-1 must be associated with an external switch, the status of which can be altered.

    MF See the topic The Special-Names Paragraph for details of which external switches can be referenced in the SET statement.

Syntax Rules for Format 2

  3. ANS85 Condition-name-1 and condition-name-2 must be associated with a conditional variable.
  4. MF If the FALSE phrase is specified, the FALSE phrase must be specified in the VALUE clause of the Data Description entry for condition-name-1 or condition-name-2.
  5. MF Each FALSE or TRUE phrase applies to the occurrences of condition-name-1 or condition-name-2 that precede that phrase and follow a previous FALSE or TRUE phrase, if any.

Syntax Rules for Format 3 and 4

  6. VSC2 MF Identifier-1 must reference a level 01 or level 77 data item that is declared in the Linkage Section.

    OS390 Identifier-1 must be declared in the Linkage Section, the Local-Storage Section or the Working-Storage Section

  7. ISO2002 VSC2 MF OS390 Identifier-2 must reference a data item with a level of 77 or between 01 and 49 inclusive.

    ISO2002 VSC2 Identifier-2 must be declared in the Linkage Section.

  8. VSC2 MF Pointer-name-1, pointer-name-2 must each be an identifier that references an elementary data item with USAGE IS POINTER.

Syntax Rules for Format 5

  9. MF Pointer-name-3 must be an identifier that references an elementary data item with USAGE IS POINTER.
  10. MF Identifier-3 must be an elementary numeric integer.
  11. MF Integer-1 may be signed.

Syntax Rules for Format 6

  12. Identifier-5 and identifier-6 must each reference an index data item or an elementary item described as an integer. If both are specified, they must not both reference an elementary item.

Syntax Rules for Formats 6 and 7

  13. Integer-2 and integer-3 may be signed. Integer-2 must be positive.

Syntax Rules for Format 7

  14. Identifier-7 must reference an elementary numeric integer.

Syntax Rules for Format 8

  15. MF Procedure-pointer-name-1 and procedure-pointer-name-2 must each be an identifier that references an elementary data item with USAGE IS PROCEDURE-POINTER.
  16. MF Identifier-8 must be defined as an alphanumeric data item such that its value can be a COBOL or a non-COBOL program name.
  17. MF Literal-1 must be a nonnumeric literal.

Syntax Rules for Format 9

  18. ISO2002 MF Identifier-9 must be any item of class object that is permitted as a receiving item.
  19. ISO2002 MF Identifier-10 must be a class-name or an object reference; the predefined object reference SUPER must not be specified.
  20. ISO2002 MF If the data item referenced by identifier-9 is a universal object reference, the only predefined object references that may be specified for identifier-10 are SELF and NULL.
  21. ISO2002 MF If the data item referenced by identifier-9 is described with an interface-name that identifies the interface int-1, the data item referenced by identifier-10 must be one of the following:
    1. An object reference described with an interface-name that identifies int-1 or an interface inheriting from int-1.
    2. An object reference described with a class-name, subject to the following rules:
      1. If described with a FACTORY phrase, the factory object of the specified class must implement int-1
      2. If described without a FACTORY phrase, the instance objects of the specified class must implement int-1.
    3. An object reference described with an ACTIVE-CLASS phrase, subject to the following rules:
      1. If described with a FACTORY phrase, the factory object of the class containing the data item referenced by identifier-10 must implement int-1.
      2. If described without a FACTORY phrase, the instance objects of the class containing the data item referenced by identifier-10 must implement int-1.
    4. A class-name whose factory object implements int-1.
    5. The predefined object reference SELF, subject to the following rules:
      1. If the SET statement is contained in a method within the factory definition of the class, that factory definition must be described with an IMPLEMENTS clause that references int-1.
      2. If the SET statement is contained in a method within the instance definition of the class, that instance definition must be described with an IMPLEMENTS clause that references int-1.
    6. The predefined object reference NULL
  22. ISO2002 MF If the data item referenced by identifier-9 is described with a class-name, the data item referenced by identifier-10 must be one of the following:
    1. An object reference described with a class-name, subject to the following rules:
      1. If the data item referenced by identifier-9 is described with an ONLY phrase, the data item referenced by identifier-10 must be described with the ONLY phrase, and the class-name specified in the description of the data item referenced by identifier-10 must be the same as the class-name specified in the description of the data item referenced by identifier-9
      2. If the data item referenced by identifier-9 is described without an ONLY phrase, the class-name specified in the description of the data item referenced by identifier-10 must reference the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
      3. The presence or absence of the FACTORY phrase must be the same as in the description of the data item referenced by identifier-9
    2. An object reference described with an ACTIVE-CLASS phrase, subject to the following rules:
      1. The data item referenced by identifier-9 must not be described with the ONLY phrase
      2. The class containing the data item referenced by identifier-10 must be the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
      3. The presence or absence of the FACTORY phrase must be the same as in the description of the data item referenced by identifier-9
    3. The predefined object reference SELF, subject to the following rules:
      1. The data item referenced by identifier-9 must not be described with the ONLY phrase
      2. The class of the object containing the SET statement must be the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
      3. If the data item referenced by identifier-9 is described without a FACTORY phrase, the object containing the SET statement must be an instance object
      4. If the data item referenced by identifier-9 is described with a FACTORY phrase, the object containing the SET statement must be a factory object
    4. A class-name, provided the data item referenced by identifier-9 is described with the FACTORY phrase, and class-name references the same class or a subclass of the class specified in the description of the data item referenced by identifier-9
    5. The predefined object reference NULL
  23. ISO2002 MF If the data item referenced by identifier-9 is described with an ACTIVE-CLASS phrase, the data item referenced by identifier-10 must be one of the following:
    1. An object reference described with the ACTIVE-CLASS phrase, where the presence or absence of the FACTORY phrase is the same as in the data item referenced by identifier-9
    2. The predefined object reference SELF, subject to the following rules:
      1. If the data item referenced by identifier-9 is described without a FACTORY phrase, the object containing the SET statement must be an instance object
      2. If the data item referenced by identifier-9 is described with a FACTORY phrase, the object containing the SET statement must be a factory object
    3. The predefined object reference NULL
  24. ISO2002 MF If identifier-9 is of type String, then identifier-10 may be of any type.

Syntax Rules for Format 10 (Value of Event-pointer)

  25. MF Event-pointer-1 must be defined as a data item with USAGE EVENT-POINTER.

Syntax Rules for Format 11 (Address of Event-pointer)

  26. MF Event-pointer-1 and event-pointer-2 must be defined as data items with USAGE EVENT-POINTER.

Syntax Rules for Format 12 (Value of Monitor-pointer)

  27. MF Monitor-pointer-1 must be defined as a data item with USAGE MONITOR-POINTER.
  28. MF If the NOT phrase is specified, then the CONVERTING phrase must not be specified.

Syntax Rules for Format 13 (Address of Monitor-pointer)

  29. MF Monitor-pointer-1 and monitor-pointer-2 must be defined as data items with USAGE MONITOR-POINTER.

Syntax Rules for Format 14 (Value of Mutex-pointer)

  30. MF Mutex-pointer-1 must be defined as a data item with USAGE MUTEX-POINTER.

Syntax Rules for Format 15 (Address of Mutex-pointer)

  31. MF Mutex-pointer-1 and mutex-pointer-2 must be defined as data items with USAGE MUTEX-POINTER.

Syntax Rules for Format 16 (Value of Semaphore-pointer)

  32. MF Semaphore-pointer-1 must be defined as a data item with USAGE SEMAPHORE-POINTER.
  33. MF Identifier-11 must reference an integer.

Syntax Rules for Format 17 (Address of Semaphore-pointer)

  34. MF Semaphore-pointer-1 and semaphore-pointer-2 must be defined as data items with USAGE SEMAPHORE-POINTER.

Syntax Rules for Format 18 (Size-of-Array)

  35. NET JVM Identifier-12 must be described with a format 3 OCCURS clause.
  36. NET JVM Identifier-13 must describe an integer.
  37. NET JVM The number of operands after the TO phrase must not exceed the number of dimensions specified for identifier-12.

Syntax Rules for Format 19 (Content-of-Array)

  38. NET JVM Identifier-14 must be described with a format 3 OCCURS clause as either a one-dimensional array or a rectangular array.
  39. NET JVM Literal-2 must be a valid literal for a VALUE clause describing the subject of the entry.
  40. NET JVM Parentheses may be used within the repetitions of literal-2 or identifier-15 to separate the values into subarrays.

Syntax Rules for Format 20 (CONDITION-VALUE setting)

  41. NET JVM Identifier-16 and identifier-17 must have usage CONDITION-VALUE.
  42. NET JVM Condition-name-3 must be associated with a conditional variable.

Syntax Rules for Format 21 (.NET-data-setting)

  43. NET JVM Identifier-18 and Identifier-19 are the receiving items.
  44. NET JVM Identifier-20, literal-3 or arithmetic-expression-1 is the sending item.
  45. NET JVM The SET statement is legal if any of the following are true:
    • Both the sending item and the receiving item are numeric
    • Identifier-18, identifier-19 and identifier-20 are objects of the same class.
    • The class of identifier-20 inherits directly or indirectly from the class of identifier-18 and identifier-19.
    • Identifier-18 and identifier-19 conform are of an interface type and identifier-20 implements that interface.
    • There is an implicit conversion operator for an item with the class of identifier-20 to the class of identifier-18 and identifier-19.
    • Identifier-18 and identifier-19 are alphanumeric or national.

General Rules for Format 1

  1. ANS85 The status of each external switch associated with the specified mnemonic-name-1 is modified such that the truth value resulting from evaluation of a condition-name associated with that switch reflects an on status if the ON phrase is specified, or an off status if the OFF phrase is specified. (See the topic Switch-Status Condition in the chapter Procedure Division.)

General Rules for Format 2

  2. ANS85 The literal in the VALUE clause associated with condition-name-1 or condition-name-2 is placed in the conditional variable according to the rules of the VALUE clause (see the section The VALUE Clause.) If more than one literal is specified in the VALUE clause, the conditional variable is set to the value of the first literal that appears in the VALUE clause.
  3. ANS85 If multiple condition-names are specified, the results are the same as if a separate SET statement had been written for each condition-name-1 or condition-name-2 in the same order as specified in the SET statement.
  4. MF If the FALSE phrase is specified, the literal in the FALSE phrase of the VALUE clause associated with condition-name-1 or condition-name-2 is placed in the conditional variable according to the rules for the VALUE clause. (See the topic The VALUE Clause.)

General Rules for Format 3 and 4

  5. VSC2 MF The sending value represents the address of a data item. If pointer-name-2 is specified, the sending value is the value contained with the data item referenced by pointer-name-2. If ADDRESS OF identifier-2 is specified, the sending value represents the address of identifier-2.
  6. VSC2 MF If pointer-name-1 is specified, the sending value is moved to the data name referenced by pointer-name-1.
  7. VSC2 MF If ADDRESS OF identifier-1 is specified, the sending value is moved to a COBOL system area and the runtime element subsequently operates such that the area of storage referenced by identifier-1 is located at the address represented by the sending value.

    MF Whether or not the link is retained between invocations of a subprogram is dependent on the STICKY-LINKAGE Compiler directive.

General Rules for Format 5

  8. MF Before execution of the SET statement, the value of the data item referenced by pointer-name-3 must represent the address of a data item within a logical record, the original address. After execution of the SET statement, the value of the data item referenced by pointer-name-3 represents the new address. If the original address and the new address do not both lie within the same logical record, (or, for environments in which address space is segmented, within the same segment) then the results of using the value of the data item referenced by pointer-name-3 are undefined.
  9. MF If the UP clause is specified, the new address is formed by adding the number of bytes given by the increment value to the original address.
  10. MF If the DOWN clause is specified, the new address is formed by subtracting the number of bytes given by the increment value from the original address.

General Rules for Format 5

  11. The following steps are repeated for each recurrence of index-name-1 or identifier-5. Each time, the value of index-name-2 or identifier-6 is used as it was at the beginning of the execution of the statement. Any subscripting or indexing associated with identifier-5 is evaluated immediately before the value of that data item is changed.
    1. If index-name-1 is specified, index-name-1 is set to a value causing it to refer to the table element that corresponds in occurrence number to the table element referenced by index-name-2, identifier-6, or integer-2. If identifier-6 references an index data item, or if index-name-2 is related to the same table as index-name-1, no conversion takes place.
    2. If identifier-5 references an index data item, it can be set equal to either the contents of index-name-2 or identifier-6 where identifier-6 also references an index item; no conversion takes place in either case.
    3. If identifier-5 does not reference an index data item, it can be set only to an occurrence number that corresponds to the value of index-name-2. Neither identifier-6 nor integer-2 can be used in this case.
  12. The following table represents the validity of various operand combinations in the SET statement. The general rule reference indicates the applicable general rule.
    Table 1. SET Index Statement Valid Operand Combinations
    Sending Item | Receiving Item
    Integer Data Item | Index-Name | Index Data Item
    Integer Literal | No/11c | Valid/11a | No/11b
    Integer Data Item | No/11c | Valid/11a | No/11b
    Index-Name | Valid/11c | Valid/11a | Valid/11b1
    Index Data Item | No/11c | Valid/11a1 | Valid/11b1

    1 = No conversion takes place.

General Rules for Formats 6 and 7

  13. Index-names are associated with a given table by being specified in the INDEXED BY phrase of the OCCURS clause for that table.
  14. If index-name-1 is specified, the value of the index after the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-1. The value of the index associated with an index-name after the execution of a PERFORM or SEARCH statement may be set to an occurrence number that is outside the range of its associated table. (See the topic The PERFORM Statement and the topic The SEARCH Statement.)

    If index-name-2 is specified, the value of the index before the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-1.

    If index-name-3 is specified, the value of the index both before and after the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-3.

General Rules for Format 7

  15. The contents of index-name-3 are incremented (UP BY) or decremented (DOWN BY) by a value that corresponds to the number of occurrences represented by the value of integer-3 or the data item referenced by identifier-7; thereafter, the process is repeated for each recurrence of index-name-3. For each repetition, the value of the data item referenced by identifier-7 is used as it was at the beginning of the execution of the statement.

General Rules for Format 8

  16. MF The sending value represents the address of the start of a procedure within a COBOL or non-COBOL program.
  17. MF The sending value is moved to the data item referenced by procedure-pointer-name-1.
  18. MF If procedure-pointer-name-2 is specified, the sending value is the value contained within the data item referenced by procedure-pointer-name-2.
  19. MF Literal-1 or the content of the data item referenced by identifier-8 is the name of the referenced procedure. If the referenced procedure is a COBOL procedure, the name of the referenced procedure must contain the program-name contained in the Program-ID paragraph of the referenced program or the entry-name contained in the ENTRY statement of the referenced procedure.

    If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in your COBOL system documentation on interfacing.

    If the referenced procedure has been previously made available and remains available at the time of execution of the SET statement, then the sending value represents the address of the referenced procedure.

    If the referenced procedure is not available at the time of execution of the SET statement, then the sending value represents the address of a COBOL system error procedure.

General Rules for Format 9

  20. ISO2002 MF If identifier-10 is an object reference, a reference to the object identified by identifier-10 is placed into each data item referenced by identifier-9 in the order specified.
  21. ISO2002 MF If identifier-10 is a class-name, a reference to the factory object of the class identified by identifier-10 is placed into each data item referenced by identifier-9 in the order specified.
  22. ISO2002 MF If identifier-9 is of type String, and identifier-10 is of any type, and no implicit conversion exists between the type of identifier-10 and String, then the ToString method is applied to identifier-10 to convert it to a string, and the result is placed in identifier-9.

General Rules for Formats 10 and 11

  23. MF If more than one event-pointer-1 is specified, the results are the same as if a separate SET statement had been written for each event-pointer-1 in the same order as specified in the SET statement.

General Rules for Format 10 (Value of Event-pointer)

  24. MF The execution of the SET statement sets the value of the event referenced by event-pointer-1 to TRUE or FALSE.
    Note: When an event is set to FALSE, the execution of any thread which executes a WAIT statement which references that event suspends until the event is set to TRUE in another thread.

General Rules for Format 11 (Address of Event-pointer)

  25. MF Event-pointer-1 is set to reference the same event data item that event-pointer-2 references.

General Rules for Formats 12 and 13

  26. MF If more than one monitor-pointer-1 is specified, the results are the same as if a separate SET statement had been written for each monitor-pointer-1 in the same order as specified in the SET statement.

General Rules for Format 12 (Value of Monitor-pointer)

  27. MF If the NOT phrase is not specified, the value of the monitor referenced by monitor-pointer-1 is set to one of BROWSING, READING, or WRITING, thus establishing the corresponding form of lock. This specific lock type for this specific monitor must be eventually released by a SET statement either with a matching NOT phrase or a matching CONVERTING FROM phrase.

    For example, the lock established by

     SET mon-1 TO READING

    can be cleared by

     SET mon-1 TO NOT READING
  28. MF The CONVERTING phrase is used to change the current type of lock established on a monitor. The lock type specified in the FROM phrase must be currently established by that thread and upon successful execution of the statement, that lock will have been changed, in one atomic operation, to the lock type specified in the TO phrase.
  29. MF Nested locks can be obtained by the execution of successive SET monitor statements with no intervening SET statement that releases the lock. Once a READING lock is established, no BROWSING or WRITING lock is allowed to nest within that thread. Once a BROWSING lock or a WRITING lock is established, any other level of lock is allowed to nest within that thread.

General Rules for Format 13 (Address of Monitor-pointer)

  30. MF Monitor-pointer-1 is set to reference the same monitor data item that monitor-pointer-2 references.

General Rules for Formats 14 and 15

  31. MF If more than one mutex-pointer-1 is specified, the results are the same as if a separate SET statement had been written for each mutex-pointer-1 in the same order as specified in the SET statement.

General Rules for Format 14 (Value of Mutex-pointer)

  32. MF The execution of the SET statement sets the value of the mutex referenced by mutex-pointer-1 to ON or OFF.
  33. MF When a mutex is set to ON, the execution of any thread that attempts to set that mutex to ON suspends until the mutex is set to OFF in the thread that set it ON.

General Rules for Format 15 (Address of Mutex-pointer)

  34. MF Mutex-pointer-1 is set to reference the same mutex data item that mutex-pointer-2 references.

General Rules for Formats 16 and 17

  35. MF If more than one semaphore-pointer-1 is specified, the results are the same as if a separate SET statement had been written for each semaphore-pointer-1 in the same order as specified in the SET statement.

General Rules for Format 16 (Value of Semaphore-pointer)

  36. MF The contents of the semaphore data item referenced by semaphore-pointer-1 are incremented (UP BY) or decremented (DOWN BY) by a value that corresponds to the value of integer-4 or the data item referenced by identifier-11; thereafter, the process is repeated for each recurrence of semaphore-pointer-1. For each repetition, the value of the data item referenced by identifier-11 is used as it was at the beginning of the execution of the statement.
  37. MF If a semaphore is set DOWN BY n and the semaphore is less than n, the thread is suspended until another thread raises the semaphore to above n.

General Rules for Format 17 (Address of Semaphore-pointer)

  38. MF Semaphore-pointer-1 is set to reference the same semaphore data item that semaphore-pointer-2 references.

General Rules for Format 18 (Size-of-Array)

  39. NET JVM The SET statement sets the size of the .NET array described by identifier-12 to the contents of the data item referenced by identifier-13 or the value of integer-5.

General Rules for Format 19 (Content-of-Array)

  40. NET JVM The SET statement creates an a .NET array of the size required to contain the values specified by the repetitions of literal-2 and initializes the array to the specified values.

General Rules for Format 20 (CONDITION-VALUE setting)

  41. NET JVM The data-item referenced by identifier-16 is set to the value of the data item referenced by identifier-17 or to condition-name-3, a conditional expression or to TRUE or FALSE.

General Rules for Format 21 (.NET-data-setting)

  42. NET JVM If identifier-18 and identifier-19 are alphanumeric or national, the ToString method is automatically invoked on the sending item and the resulting string moved to the data item referenced by identifier-18 and identifier-19. Note that the ToString method exists for any class since it is implemented in System.Object.
  43. NET JVM The sending item is moved to the receiving item.
Parent topic: Statements
Related reference
SET Statement
Related information
The Special-Names Paragraph
Switch-Status Condition
The VALUE Clause
The PERFORM Statement
The SEARCH Statement


SORT Statement (COBOL)

The SORT Statement

The SORT statement creates a sort file by executing input procedures or by transferring records from another file, sorts the records in the sort file on a set of specified keys, and in the final phase of the sort operation, makes available each record from the sort file, in sorted order to some output procedures or to an output file.

MF The SORT statement can also be used to sort the elements of a table.

General Formats for Format 1

SORT - Format 1

General Formats for Format 2

SORT - Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • CALLSORT - specifies the program to be used to handle SORT and MERGE operations.

Syntax Rules for All Formats

  1. A Format 1 SORT statement cannot appear in the declaratives portion of the Procedure Division, or in an input or output procedure associated with a SORT or MERGE statement.

    MF A Format 2 SORT can appear in the declaratives portion.

  2. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. KEY data-names can be qualified.
    2. The data items identified by KEY data-names must not be variable length items.
    3. KEY data items can be floating-point items.
    4. OSVS VSC2 MF If the KEY is an external floating-point item, the Compiler treats the data item as character data, rather than numeric data. The sequence in which the records are sorted depends on the collating sequence used.
    5. OSVS VSC2 MF If the KEY data item is internal floating-point, the records are sorted in numeric order of key values.

Syntax Rules for Format 1

  3. File-name-1 must be described in a Sort-Merge File Description entry in the Data Division.
  4. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. The data items identified by KEY data-names must be described in records associated with file-name-1.
    2. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions.
    3. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.
    4. If the file referenced by file-name-1 contains variable-length records, all the data items identified by key data-names must be contained within the first x character positions of the record, where x equals the minimum record size specified for the file referenced by file-name-1.
  5. The words THRU and THROUGH are equivalent.
  6. File-name-2 and file-name-3 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
  7. ANS85 The files referenced by file-name-2 and file-name-3 can reside on the same multiple file reel.
  8. ANS85 If file-name-3 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.
  9. No pair of file-names in the same SORT statement can be specified in the SAME SORT AREA or SAME SORT-MERGE AREA clause. File-names associated with the GIVING phrase cannot be specified in the same SAME clause.
  10. ANS85 If the GIVING phrase is specified and the file referenced by file-name-3 contains variable-length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor larger than the largest record described for file-name-3. If the file referenced by file-name-3 contains fixed-length records, the size of the records contained in the file referenced by file-name-1 must not be larger than the largest record described for the file referenced by file-name-3.

    If the data descriptions of the elementary items that make up these records are not identical, it is the programmer's responsibility to describe the corresponding records in such a manner as to cause equal amounts of character positions to be allocated for the corresponding records.

  11. ANS85 If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
  12. Procedure-name-1 represents the name of an input procedure. Procedure-name-3 represents the name of an output procedure.
  13. Procedure-name-1, procedure-name-2, procedure-name-3 and procedure-name-4 must be section-names.

    ANS85 OSVS This restriction is removed.

  14. If you want to specify more than 10 file-names in the USING or GIVING clause, you must use the Compiler directive CALLSORT"EXTSM"; this allows you to specify up to 255 files.

Syntax Rules for Format 2

  15. MF Data-name-2 can be qualified and must have an OCCURS clause in the data description entry.
  16. MF The data item referenced by data-name-1 must be the same as the data item referenced by data-name-2, or an entry subordinate to the data item referenced by data-name-2.
  17. MF Unless data-name-1 and data-name-2 are the same, the data item referenced by data-name-1 must not be described by an entry containing an OCCURS clause. The data item referenced by data-name-1 must not be subordinate to an entry containing an OCCURS clause that is also subordinate to data-name-2.
  18. MF The KEY phrase can be omitted only if the description of the table referenced by data-name-2 contains a KEY phrase.
  19. MF If data-name-2 references a data item subordinate to a data item that contains an OCCURS clause, an index-name must be associated with each data item containing an OCCURS clause to which the data item referenced by data-name-2 is subordinate.

General Rules for All Formats

  1. The words ASCENDING and DESCENDING are transitive across all occurrences of data-name-1 until another word ASCENDING or DESCENDING is encountered.
  2. The data items referenced by the specifications of data-name-1 are the key data items which determine the order in which records are returned from the file referenced by file-name-1 or the order in which the table elements are stored after sorting takes place. The order of significance of the keys is the order in which they are specified in the SORT statement, without regard to their association with ASCENDING or DESCENDING phrases.
  3. If the DUPLICATES phrase is specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records is:
    1. The order of the associated input files as specified in the SORT statement, or by means of an RTS switch. Within a given input file the order is that in which the records are accessed from that file.
    2. The order in which these records are released by an input procedure, when an input procedure is specified.
    3. The relative order of the contents of these table elements before sorting takes place.
  4. If the DUPLICATES phrase is not specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records or the relative order of the contents of these table elements is undefined.
  5. The collating sequence that applies to the comparison of the nonnumeric key data items specified is determined at the beginning of the execution of the SORT statement in the following order of precedence:
    1. First, the collating sequence established by the COLLATING SEQUENCE phrase, if specified, in the SORT statement.
    2. Second, the collating sequence established as the program collating sequence.

General Rules for Format 1

  6. The SORT statement releases all the records in the file referenced by file-name-2 or released by an input procedure to the file referenced by file-name-1, and returns them to an output procedure, or to the file referenced by file-name-3, in an order determined by the ASCENDING and DESCENDING phrases and the values of the data items referenced by the specifications of data-name-1.
  7. To determine the relative order in which two records are returned from the file referenced by file-name-1, the contents of corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item:
    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the record containing the key data item with the lower value is returned first.
    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the record containing the key data item with the higher value is returned first.
    3. If the contents of the corresponding key data items are equal, the determination is made on the contents of the next most significant key data item.
  8. The execution of the SORT statement consists of three distinct phases as follows:
    1. Records are made available to the file referenced by file-name-1. This is achieved either by the execution of RELEASE statements in the input procedure or by the implicit execution of READ statements for file-name-2. When this phase commences, the file referenced by file-name-2 must not be in the open mode. When this phase terminates, the file referenced by file-name-2 is not in the open mode.
    2. The file referenced by file-name-1 is sequenced. No processing of the files referenced by file-name-2 and file-name-3 takes place during this phase.
    3. The records of the file referenced by file-name-1 are made available in sorted order. The sorted records are either written to the file referenced by file-name-3, or, by the execution of a RETURN statement, are made available for processing by the output procedure. When this phase commences, the file referenced by file-name-3 must not be in the open mode. When this phase terminates, the file referenced by file-name-3 is not in the open mode.
  9. The input procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RELEASE statement to the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the input procedure. The range of the input procedure must not cause the execution of any MERGE, RETURN or SORT statement.
  10. If an input procedure is specified, control is passed to the input procedure before the file referenced by file-name-1 is sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the input procedure and when control passes the last statement in the input procedure, the records that have been released to the file referenced by file-name-1 are sorted.
  11. If the USING phrase is specified, all the records in the file(s) referenced by file-name-2 are transferred to the file referenced by file-name-1. For each of the files referenced by file-name-2 the execution of the SORT statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the INPUT and the WITH LOCK phrases had been executed .
    2. The logical records are obtained and released to the sort operation. Each record is obtained as if a READ statement with the NEXT and AT END phrases had been executed. If the file referenced by file-name-1 contains fixed-length records, any record in the file referenced by file-name-2 containing fewer character positions than that specified for file-name-1 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is released to the file referenced by file-name-1. If the file referenced by file-name-1 is described with variable-length records, the size of any record written to file-name-1 is the size of that record when it was read from file-name-2 or file-name-3, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-1.
    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. This termination is performed before the file referenced by file-name-1 is sequenced by the SORT statement.

      For a relative file, the content of the relative key data item is undefined after the execution of a SORT statement if file-name-2 is not referenced in the GIVING phrase.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-2 or accessing the record area associated with file-name-2.

      The value of the data item referenced by a RECORD VARYING DEPENDING ON clause specified in the File Description entry for file-name-2 is undefined upon completion of the SORT statement.

  12. The output procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RETURN statement in sorted order from the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the output procedure, as well as all statements in the declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the output procedure must not cause the execution of any MERGE, RELEASE or SORT statement.
  13. If an output procedure is specified, control passes to it after the file referenced by file-name-1 has been sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure and when control passes the last statement in the output procedure, the return mechanism provides for termination of the sort and then passes control to the next executable statement after the SORT statement. Before entering the output procedure, the sort procedure reaches a point at which it can select the next record in sorted order when requested. The RETURN statements in the output procedure are the requests for the next record.
  14. If the GIVING phrase is specified, all the sorted records are written to the file referenced by file-name-3 as the implied output procedure for the SORT statement. For each of the files referenced by file-name-3, the execution of the SORT statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the OUTPUT phrase had been executed. This initiation is performed after the execution of any input procedure.
    2. The logical records are returned and written to the file. The records are written as if a WRITE statement without any optional phrases had been executed. If the file referenced by file-name-3 is described with fixed-length records, any record in the file referenced by file-name-1 containing fewer character positions than that specified for file-name-3 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is returned to the file referenced by file-name-3. If the file referenced by file-name-3 is described with variable-length records, the size of any record written to file-name-3 is the size of that record when it was read from file-name-1, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-3.

      For a relative file, the relative key data item for the first record returned has the value 1; for the second record returned, the value 2, and so on. The content of the relative key data item is undefined after execution of a SORT statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-3 or accessing the record area associated with file-name-3. On the first attempt to write beyond the externally-defined boundaries of a file, the USE AFTER EXCEPTION procedure, if any, associated with the file is executed; if control is returned as specified by the rules of the USE statement, no additional implicit write operations are executed for that file and the processing of the file is terminated as specified in this part.

    The value of the data item referenced by a RECORDING VARYING DEPENDING ON clause specified in the File Description entry for file-name-1 is undefined upon completion of the SORT statement for which the GIVING phrase is specified.

  15. Segmentation, as defined in the topic Segmentation, can be applied to programs containing the SORT statement. However, the following restrictions apply:
    1. If a SORT statement appears in a section that is not in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
      • Totally within non-independent segments
      • Wholly contained in a single independent segment.
    2. If a SORT statement appears in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
      • Totally within non-independent segments
      • Wholly within the same independent segment as that SORT statement.
  16. OSVS VSC2 MF The SORT-RETURN special register is available to SORT runtime elements. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of a sort operation. You can set the SORT-RETURN special register to 16 in an error declarative or input/output procedure to terminate a sort operation before all records are processed. The operation is terminated on the next RETURN or RELEASE statement.

General Rules for Format 2

  17. MF The SORT statement sorts the table referenced by data-name-2 and presents the sorted table in data-name-2 either in the order determined by the ASCENDING or DESCENDING phrases, if specified, or in the order determined by the KEY phrase associated with data-name-2.
  18. MF To determine the relative order in which the table elements are stored after sorting, the contents of the corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item.
    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the table element containing the key data item with the lower value has the lowest occurrence number.
    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the table element containing the key data item with the higher value has the lowest occurrence number.
    3. If the contents of the corresponding key data items are equal, the determination is based on the contents of the next most significant key data item.
  19. MF The number of occurrences of table elements referenced by data-name-2 is determined by the rules in the OCCURS clause.
  20. MF If data-name-2 references a data item which is subordinate to a data item which contains an OCCURS clause, the first or only index-name associated with each such superordinate table must be set to the desired occurrence number before the SORT statement is executed.
  21. MF If the KEY phrase is not specified, the sequence is determined by the KEY phrase in the Data Description entry of the table referenced by data-name-2.
  22. MF If the KEY phrase is specified, it overrides any KEY phrase specified in the Data Description entry of the table referenced by data-name-2.
  23. MF If the key phrase is specified but data-name-1 is omitted, the data item referenced by data-name-2 is the KEY data item.
  24. MF The sorted table elements of the table referenced by data-name-2 are placed in the table referenced by data-name-2.
  25. SORT procedures should not be invoked by multiple threads simultaneously.

Examples

Examples of using the SORT verb are provided in the topics SORT a File Using Input and Output Procedures and SORT Table Entries.

Parent topic: Statements
Related reference
SORT Statement
Related information
Segmentation
SORT a File Using Input and Output Procedures
SORT Table Entries


START Statement (COBOL)

The START Statement

The START statement provides a basis for logical positioning within a relative or indexed file for subsequent retrieval of records. This statement is not available for files with sequential organization.

MF The START statement initiates execution of a thread, either synchronously or asynchronously.

General Formats for Format 1 (Relative Files)

START - FORMAT 1

General Formats for Format 2 (Indexed Files)

START - FORMAT 2

General Formats for Format 3 (Threads)

START - FORMAT 3

Syntax Rules for All Formats (Relative and Indexed Files)

  1. File-name-1 must be the name of a relative or indexed file.
  2. File-name-1 must be the name of a file with sequential or dynamic access.
  3. Data-name-1 can be qualified.
  4. The INVALID KEY phrase must be specified if no applicable USE procedure is specified for file-name-1.

    OSVS VSC2 MF This rule is not enforced.

  5. MF THEN may be used instead of THAN.

Syntax Rules for Format 1 (Relative Files)

  6. If the KEY phrase is specified, data-name-1 must be the data item specified in the RELATIVE KEY phrase of the associated file control entry.

Syntax Rules for Format 2 (Indexed Files)

  7. If the KEY phrase is specified, data-name-1 can reference a data item specified as a record key associated with file-name-1. It can also reference any data item of category alphanumeric, subordinate to the data item specified as a record key associated with file-name-1, whose leftmost character position corresponds to the leftmost character position of that record key data item.
  8. MF Split-key-name-1 can reference one or more data items, and is specified as a record key associated with file-name-1.
  9. MF WITH SIZE specifies the number of characters in the key to be used in the positioning process.
  10. MF Identifier-1 must be the name of an elementary integer data item when used with the WITH SIZE phrase.
  11. When the DIALECT"RM" or DIALECT"ACU" directives are in effect, the data-name-1 or split-key-name-1 specified in the KEY phrase is implicitly qualified by the file-name-1 specified in the START statement when file-name-1 is not already explicitly specified as the final qualifier of data-name-1 or split-key-name-1. For any other dialect, data-name-1 or split-key-name-1 may need to explicitly specify file-name-1 as the final qualifier to satisfy uniqueness of reference rules.

Syntax Rules for Format 3 (Threads)

  12. MF Literal-1 must be a nonnumeric literal and cannot be a figurative constant.
  13. MF Identifier-1 must be defined as an alphanumeric data item such that its value can be a COBOL or non-COBOL program-name.
  14. MF Identifier-3 must be defined as either USAGE POINTER or a data item that is four bytes in size. The definition depends on the definition of the GIVING/RETURNING item within the EXIT PROGRAM / STOP RUN statement for the new thread. If identifier-3 is defined as a USAGE POINTER item, it must not be a function-identifier.
  15. MF Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
  16. MF Identifier-4 must be defined as an integer data item that has a length of at least four digits.

General Rules for All Formats (All Files)

  1. File-name-1 must be open in the INPUT or I/O mode at the time that the START statement is executed. (See the topic The OPEN Statement.)
  2. If the KEY phrase is not specified, the relational operation IS EQUAL TO is implied.
  3. Execution of the START statement causes the value of the FILE STATUS data item, if any, associated with file-name-1 to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  4. MF The START statement never acquires, detects or releases record locks.

General Rules for Format 1 (Relative Files)

  5. The type of comparison specified by the relational operator in the KEY phrase occurs between a key associated with a record in the file referenced by file-name-1 and a data item as specified in General Rule 6.
    1. ANS85 If the relational operator specifies that the key must be equal to, greater than, or greater than or equal to the data item, then

      the file position indicator is positioned to the first logical record currently existing in the file whose key satisfies the comparison.

    2. MF If the relational operator specifies that the key must be less than, or less than or equal to the data item, then the file position indicator is positioned to the last logical record currently existing in the file whose key satisfies the comparison.
    3. If the comparison is not satisfied by any record in the file, an INVALID KEY condition exists. The execution of the START statement is unsuccessful, and the position of the file position indicator is undefined. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)
  6. The comparison described in General Rule 5 uses the data item referenced by the RELATIVE KEY clause associated with file-name-1. A RELATIVE KEY clause must be associated with file-name-1.

General Rules for Format 2 (Indexed Files)

  7. The type of comparison specified by the relational operator in the KEY phrase occurs between a key associated with a record in the file referenced by file-name-1 and a data item as specified in General Rule 8. If file-name-1 references an indexed file and the operands are of unequal size, the comparison proceeds as though the longer one were truncated on the right so that its length is equal to that of the shorter. All other nonnumeric comparison rules apply except that the presence of the PROGRAM COLLATING SEQUENCE clause has no effect on the comparison. (See the topic Comparison of Nonnumeric Operands in the section Relation Condition in the chapter Procedure Division.)
    1. ANS85 If the relational operator specifies that the key must be equal to, greater than, or greater than or equal to the data item, then

      the file position indicator is positioned to the first logical record currently existing in the file whose key satisfies the comparison.

    2. MF If the relational operator specifies that the key must be less than, or less than or equal to the data item, then the file position indicator is positioned to the last logical record currently existing in the file whose key satisfies the comparison. If this key has duplicate entries, the file position indicator is positioned to the last of these entries.
    3. If the comparison is not satisfied by any record in the file, an INVALID KEY condition exists, the execution of the START statement is unsuccessful, and the position of the file position indicator is undefined. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)
  8. If the KEY phrase is specified, the comparison described in General Rule 7 uses the data item referenced by data-name.
  9. If the KEY phrase is not specified, the comparison described in General Rule 7 uses the data item referenced in the RECORD KEY clause associated with file-name-1.
  10. After successful execution of the START statement, a key of reference is established and used in subsequent Format 3 READ statements as follows (see the topic The READ Statement):
    1. If the KEY phrase is not specified, the prime record key specified for file-name-1 becomes the key of reference.
    2. If the KEY phrase is specified, and data-name-1

      MF or split-key-name-1

      is specified as a record key for file-name-1, that record key becomes the key of reference.

    3. If the KEY phrase is specified, and data-name-1

      MF or split-key-name-1

      is not specified as a record key for file-name-1, the record key whose leftmost character position corresponds to the leftmost character position of the data item specified by data-name-1

      MF or split-key-name-1

      becomes the key of reference.

  11. If execution of the START statement is not successful, the key of reference is undefined.

General Rules for Format 3 (Threads)

  12. MF Literal-1, identifier-1, or procedure-pointer-1 must reference a program-id which is either the outermost program-id in a compilation unit, an ENTRY point in a program or a label in another language. This is the starting point of the newly created thread's execution.
  13. MF If identifier-2 is specified, the starting point of the newly created thread must be defined in such a way that it accepts a single parameter that is passed by reference.
  14. MF If the BY CONTENT phrase is specified, the contents of identifier-2 are copied to a system-allocated, thread-safe work area and a reference to this work area is passed to the starting point of the newly created thread. This work area remains valid during the entire execution of the created thread, irrespective of the lifetime of the creating program's data areas.
  15. MF If the BY CONTENT phrase is not specified, a direct reference to identifier-2 is passed to the starting point of the newly created thread. It is left to you to ensure that this data area remains valid while the newly created thread references it.
  16. MF If the RETURNING phrase is specified, the newly created thread executes to completion, returns a value in identifier-3 and returns control to the START statement.
  17. MF If the IDENTIFIED BY phrase is specified, execution of the newly created thread is initiated, a handle to reference the newly created thread is placed into thread-pointer-1 and control is returned to the START statement. The handle can be used in a WAIT statement to retrieve a returned value, synchronize execution and free the thread's resources. This handle is a valid thread handle as used by the CBL_THREAD_ library routines.
  18. MF If neither the RETURNING phrase nor the IDENTIFIED phrase is specified, the newly created thread is initiated and control is returned to the START statement. All resources of the thread are automatically freed when the thread terminates.
  19. MF If the STATUS phrase is specified, the execution of the START statement places into identifier-4 one of the return codes specified for the CBL_THREAD_ library routines.
  20. MF If the START statement fails, one of the return codes specified for the CBL_THREAD_ library routines is placed into identifier-4, if specified, and then one of the following occurs:
    1. If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure-branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the START statement and the NOT ON EXCEPTION phrase, if specified, is ignored.
    2. Otherwise, if the NOT ON EXCEPTION phrase or the STATUS phrase is specified, control is transferred to the end of the START statement and the NOT ON EXCEPTION phrase, if specified, is ignored.
    3. Otherwise, the run-unit terminates with a run-time system error.
  21. MF If the START statement is successful, the following occurs in the order specified:
    1. If the STATUS phrase is specified, ZERO is moved to identifier-4.
    2. If the NOT ON EXCEPTION phrase is specified, control is transferred to imperative-statement-2. Execution then continues according to the rules for each statement specified in imperative-statement-2. If a procedure-branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the START statement and the ON EXCEPTION phrase, if specified, is ignored.
Parent topic: Statements
Related information
The OPEN Statement
I-O Status
The INVALID KEY Condition
Relation Condition
The READ Statement


STOP Statement (COBOL)

The STOP Statement

The STOP statement causes a permanent or temporary suspension of the execution of the run unit.

ANS85 The STOP literal statement is classed as an obsolete element in the ANSI'85 Standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects within this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, the Stop literal format is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Format for Format 1

General Format for Format 2

General Format for Format 3

Syntax Rules

  1. Literal-1 must not be a figurative constant that begins with the word ALL.
  2. If literal-1 is numeric, then it must be an unsigned integer.

    OSVS VSC2 A signed integer is allowed.

  3. MF Integer-1 may be signed.
  4. If a STOP RUN statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    OSVS VSC2 MF This rule is not enforced, although any statements in the sentence that follow the STOP RUN statement will not be executed.

  5. MF GIVING and RETURNING are equivalent.
  6. MF Identifier-1 must be no larger than 8 bytes in size.
  7. MF If a STOP RUN GIVING statement is executed within a thread created with the START statement (format 3 threads) and if the ADDRESS OF clause is not specified, identifier-1 must be defined as either USAGE POINTER or a data item that is four bytes in size. The definition depends on the definition of the RETURNING item within the START statement. If identifier-1 is defined as a USAGE POINTER item, it must not be a function-identifier.
  8. NET JVM STOP ITERATOR may only be specified in the context of an Iterator. See Iterator-ID.

General Rules

  1. If the RUN phrase is specified, execution of the run unit ceases and control is transferred to the operating system.
  2. During the execution of a STOP RUN statement, an implicit CLOSE statement without any optional phrases is executed for each file that is in the open mode in the run unit. Any USE procedures associated with any of these files are not executed.
  3. MF Execution of a STOP RUN statement causes a return value to be set in the system area generally available for non-COBOL runtime elements to return a value. If the operating system supports the facility of returning a value from a program that is run to the operating system environment then it returns the value from the system area.

    If the GIVING phrase is not specified then the run unit operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with the RETURN-CODE as the sending item and the system area as the receiving item. (See the topic Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

    If the GIVING identifier-1 phrase is specified, identifier-1 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is expected by the operating system. Typically, identifier-1 needs to be declared explicitly or implicitly as PIC S9 (9) USAGE COMP-5; this declaration depends on the value of the RTNCODE-SIZE Compiler directive. The run unit operates as if a MOVE statement had been executed with identifier-1 as the sending item and the system area as the receiving item.

    If the GIVING integer-1 phrase is specified, integer-1 must not be larger than the value that can be held in the system area. The run unit operates as if a MOVE statement had been executed with integer-1 as the sending item and the system area as the receiving item.

  4. If STOP literal-1 is specified, the execution of the run unit is suspended and literal-1 is communicated to the operator. Continuation of the execution of the run unit begins with the next executable statement when the operator presses the ENTER key or its equivalent.
    Note: This behavior is not supported when initiated from a JCL batch job; processing will continue without operator intervention. Instead, use ACCEPT FROM CONSOLE syntax to achieve a similar effect when running via JCL.
  5. When executed within a thread created with a START statement or the CBL_THREAD_CREATE library routine, a STOP RUN GIVING statement does not end the run-unit; it simply provides a return value and terminates the thread. It is equivalent to:
    CALL 'CBL_THREAD_EXIT' USING BY VALUE ADDRESS OF thread-parm
  6. MF STOP RUN in threads not created by the START statement or CBL_THREAD_CREATE library routine (that is, the main thread, or a thread created by a program written in another programming language) waits for all active CBL_THREAD_CREATE threads to finish and then terminates the run unit.
  7. NET JVM The STOP ITERATOR statement has the effect of terminating the iterator.
Parent topic: Statements
Related reference
RTNCODE-SIZE
Related information
The Iterator-ID Paragraph
Special Registers


STRING Statement (COBOL)

The STRING Statement

The STRING statement provides concatenation of the partial or complete contents of two or more data items into a single data item.

General Format

Syntax Rules

  1. Each literal can be any figurative constant without the optional word ALL.
  2. All literals must be described as nonnumeric literals, and all identifiers, except identifier-4, must be described implicitly or explicitly as USAGE IS DISPLAY.
  3. Identifier-3 must represent an elementary alphanumeric data item without editing symbols or the JUSTIFIED clause.
  4. Identifier-4 must represent an elementary numeric integer data item of sufficient size to contain a value equal to the size plus 1 of the area referenced by identifier-3. The symbol "P" cannot be used in the PICTURE character-string of identifier-4.
  5. Where identifier-1 or identifier-2 is an elementary numeric data item, it must be described as an integer without the symbol "P" in its PICTURE character-string.
  6. ANS85 Identifier-3 must not be reference modified.
  7. MF OS390 Identifier-3 can be reference modified.

General Rules

  1. Identifier-1, or literal-1, represents the sending item. Identifier-3 represents the receiving item.
  2. Literal-2, identifier-2, indicate the character(s) delimiting the move. If the SIZE phrase is used, the complete data item defined by identifier-1, or literal-1, is moved. When a figurative constant is used as the delimiter, it stands for a single-character nonnumeric literal.
  3. When a figurative constant is specified as literal-1, or literal-2, it refers to an implicit one-character data item whose usage is DISPLAY.
  4. When the STRING statement is executed, the transfer of data is governed by the following rules:
    1. Those characters from literal-1, or from the contents of the data item referenced by identifier-1, are transferred to the contents of identifier-3 in accordance with the rules for alphanumeric to alphanumeric moves, except that no space filling is provided. (See the topic The MOVE Statement.)
    2. If the DELIMITED phrase is specified without the SIZE phrase, the contents of the data item referenced by identifier-1, or the value of literal-1, is transferred to the receiving data item in the sequence specified in the STRING statement beginning with the leftmost character and continuing from left to right until the end of the data item is reached, or until the character(s) specified by literal-2, or by the contents of identifier-2 are encountered. The character(s) specified by literal-2, or by the data item referenced by identifier-2, are not transferred.
    3. If the DELIMITED phrase is specified with the SIZE phrase, the entire contents of literal-1, or the contents of the data item referenced by identifier-1, are transferred, in the sequence specified in the STRING statement, to the data item referenced by identifier-3 until all data has been transferred or the end of the data item referenced by identifier-3 has been reached.
  5. If the POINTER phrase is specified, identifier-4 is explicitly available to you, and you are then responsible for setting its initial value. The initial value must not be less than one.
  6. If the POINTER phrase is not specified, the following General Rules apply as if you had specified identifier-4 with an initial value of 1.
  7. When characters are transferred to the data item referenced by identifier-3, the moves behave as though the characters were moved one at a time from the source into the character position of the data item referenced by identifier-3 designated by the value associated with identifier-4, and then identifier-4 was increased by one prior to the move of the next character. The value associated with identifier-4 is changed during execution of the STRING statement only by the behavior specified above.
  8. At the end of execution of the STRING statement, only the portion of the data item referenced by identifier-3 that was referenced during the execution of the STRING statement is changed. All other portions of the data item referenced by identifier-3 contains data that was present before this execution of the STRING statement.
  9. Before each move of a character to the data item referenced by identifier-3, if the value associated with the data item referenced by identifier-4 is either less than one or exceeds the number of character positions in the data item referenced by identifier-3, no (further) data is transferred to the data item referenced by identifier-3,

    ANS85 the NOT ON OVERFLOW phrase, if specified, is ignored

    and control is transferred to the end of the STRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1. If control is transferred to imperative-statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the STRING statement.

  10. ANS85 If, at the time of execution of a STRING statement with the NOT ON OVERFLOW phrase, the conditions described in General Rule 9 are not encountered, after completion of the transfer of data according to the other general rules, the ON OVERFLOW phrase, if specified, is ignored and control is transferred to the end of the STRING statement or, if the NOT ON OVERFLOW phrase is specified, to imperative- statement-2. If control is transferred to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure-branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the STRING statement.
  11. ANS85 The END-STRING phrase delimits the scope of the STRING statement. (
Parent topic: Statements
Related concepts
Explicit and Implicit Scope Terminators


SUBTRACT Statement (COBOL)

The SUBTRACT Statement

The SUBTRACT statement is used to subtract one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.

General Formats for Format 1

SUBTRACT - FORMAT 1

General Formats for Format 2

SUBTRACT - FORMAT 2

General Formats for Format 3

SUBTRACT - FORMAT 3

Syntax Rules for All Formats

  1. Each identifier must refer to a numeric elementary item, except that in Format 2 each identifier following the word GIVING must refer to either an elementary numeric item or an elementary numeric edited item, and in Format 3 each identifier must refer to a group item.
  2. The composite of operands is determined as follows (see the topic Arithmetic Statements in the chapter Procedure Division):
    1. In Format 1, by using all of the operands in a given statement.
    2. In Format 2, by using all of the operands in a given statement excluding the data items that follow the word GIVING.
    3. In Format 3, separately for each pair of corresponding data items.

Syntax Rules for Formats1 and 2

  3. Each literal must be a numeric literal.
  4. OSVS VSC2 MF Floating-point data items and literals can be used anywhere numeric data items and literals can be specified.

Syntax Rules for Format 3

  5. CORR is an abbreviation for CORRESPONDING.

General Rules for All Formats

  1. See the topics The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in the chapter Procedure Division.
  2. VSC2 MF The COBOL system ensures enough places are carried so as not to lose significant digits during execution.

General Rules for Format 1

  3. All literals or identifiers preceding the word FROM are added together and this total is subtracted from the current value of identifier-2 storing the result immediately into identifier-2, and repeating this process respectively for each operand following the word FROM.

General Rules for Format 2

  4. In Format 2, all literals or identifiers preceding the word FROM are added together, the sum is subtracted from literal-2 or identifier-2 and the result of the subtraction is stored as the new value of each data item referenced by identifier-3.

General Rules for Format 3

  5. If Format 3 is used, data items in identifier-1 are subtracted from and stored into corresponding data items in identifier-2.
Parent topic: Statements
Related information
Arithmetic Statements
The ON SIZE ERROR Phrase
The ROUNDED Phrase
Overlapping Operands
Multiple Results In Arithmetic Statements


SYNC Statement (COBOL)

The SYNC Statement

The SYNC statement marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.

General Format

Syntax Rules

  1. identifier-1 must be a reference type.

General Rules

  1. identifier-1 specifies the object that you want to lock on. Typically, identifier-1 is the SELF keyword if you want to protect an instance variable, or a type if you want to protect a static variable (or if the critical section occurs in a static method in the given class).
  2. statement- block-1 represents the statements of the critical section.
  3. When the object is locked, code executing in the same execution thread can also obtain and release the lock. However, code executing in other threads cannot. It is blocked until the lock is released.

Example

In the following example, the SYNC statement locks a set of critical statements.

method-id Withdraw.
procedure division using by value amount as binary-long
                   returning ret as binary-long.
           sync on self
               if balance >= amount
                   display "In critical section"
                   compute balance = balance - amount
                   set ret to amount
               else
                   display "In critical section"
                   set ret to 0
               end-if
           end-sync
end method.
Parent topic: Statements


TRANSFORM Statement (COBOL)

The TRANSFORM Statement

The TRANSFORM statement is used to alter characters according to a transformation rule.

General Format

The TRANSFORM Statement

Syntax Rules

  1. Identifier-3 can be any elementary item except a numeric item with USAGE other than DISPLAY, or a group item.
  2. Identifier-1 and identifier-2 must be elementary alphabetic or alphanumeric items.
  3. Nonnumeric-literal-2 or identifier-2 must be either one character long or the same length as nonnumeric-literal-1 or identifier-1.

General Rules

  1. The use of figurative-constant-1 and/or figurative-constant-2 is equivalent to the use of a single-character nonnumeric literal with the same value.
  2. If either identifier-1 or identifier-2 references the same computer storage area as identifier-3, the result of the TRANSFORM is undefined. (See the topic The REDEFINES Clause .)
  3. If characters are repeated in nonnumeric-literal-1 or identifier-1, then the result of the TRANSFORM operation is undefined.
  4. The TRANSFORM statement scans identifier-3 for occurrences of individual characters from identifier-1 or nonnumeric-literal-1. When a match is found, the corresponding character (or the single character of a one-character field) from identifier-2 or nonnumeric-literal-2 is substituted into that character position in identifier-3. The correspondence between identifier-1 or nonnumeric- literal-1 and identifier-2 or nonnumeric-literal-2 is by occurrence number of the character within the data item (starting from the left).
Parent topic: Statements
Related information
The REDEFINES Clause


TRY Statement (COBOL)

The TRY Statement

The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling. The TRY block allows you to test a section of code for exceptions that may occur during its execution. The CATCH block must specify the type of exception you wish to handle if one should occur during the execution of the TRY block. The FINALLY block allows you to execute a section of code following the TRY block, whether or not an exception occurred.

General Formats

Syntax Rules

  1. Identifier-1 must be an object reference of class (or a subclass of) System.Exception (.NET COBOL) or java.lang.Throwable (JVM COBOL).

General Rules

  1. If identifier-1 is omitted, it is equivalent to specifying the special register EXCEPTION-OBJECT as identifier-1. EXCEPTION-OBJECT has class System.Exception (.NET COBOL) or java.lang.Throwable (JVM COBOL).
  2. If an exception is raised during the execution of imperative-statement-1, each CATCH phrase is examined in the order specified until one is found for which the class of the exception that was thrown is equal to, or derives from, the class of identifier-1. If such an identifier-1 is found, identifier-1 is set to contain the value of the thrown exception, and the associated imperative-statement-2 is executed. Execution continues according to the rules for each statement specified in imperative-statement-2. If a control branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to imperative-statement 3, if specified, or to the end of the TRY statement.
  3. If no exception is raised during the execution of imperative-statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a control branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to imperative-statement 3, if specified, or to the end of the TRY statement.
  4. Execution of imperative-statement-3 continues according to the rules for each statement specified in imperative-statement-3. If a control branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-3, control is transferred to the end of the TRY statement

Example

The following is an example of specifying the EXCEPTION-OBJECT register:

           try
               set str to "some string"
           catch
               display exception-object::ToString()
           finally
           end-try
Parent topic: Statements


UNLOCK Statement (COBOL)

The UNLOCK Statement

The UNLOCK statement releases all record locks held by the run unit on a named file.

General Format

Syntax Rule

  1. File-name must occur in the SELECT statement of the file control entry.

General Rules

  1. The file referenced by file-name must already be opened with the OPEN statement.
  2. The UNLOCK statement releases all record locks held by the run unit on a named file.
Parent topic: Statements


UNSTRING Statement (COBOL)

The UNSTRING Statement

The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.

General Format

Syntax Rules

  1. Each literal must be a nonnumeric literal. In addition, each literal can be any figurative constant without the optional word ALL.
  2. Identifier-1, identifier-2, identifier-3, and identifier-5 must be described, implicitly or explicitly, as alphanumeric data items.
  3. Identifier-4 can be described as either alphabetic (except that the symbol "B" cannot be used in the PICTURE character-string), alphanumeric, or numeric (except that the symbol "P" cannot be used in the PICTURE character-string), and must be described as USAGE IS DISPLAY.
  4. MF Syntax Rules 2 and 3 do not apply. Instead, the following rules apply:
    1. Identifier-1 must be alphanumeric
    2. Identifier-2 and identifier-3 must be USAGE DISPLAY and must not be edited
    3. Identifier-5 must be USAGE DISPLAY
    4. Identifier-4 can be USAGE DISPLAY
    5. Identifier-4 can have any USAGE that defines a numeric data item as long as the data results in a valid MOVE operation.
  5. OSVS VSC2 MF Identifier-4 must not be defined as a floating-point item.
  6. Identifier-6 and identifier-8 must reference integer data items (except that the symbol " P" cannot be used in the PICTURE character-string).
  7. Identifier-7 must be described as an elementary numeric integer data item of sufficient size to contain a value equal to 1 plus the size of the data item referenced by identifier-1. The symbol "P" cannot be used in the PICTURE character string of identifier-7.
  8. No identifier can name a level 88 entry.
  9. The DELIMITER IN phrase and the COUNT IN phrase can be specified only if the DELIMITED BY phrase is specified.
  10. ANS85 Identifier-1 must not be reference modified.
  11. ISO2002 MF OS390 Identifier-1 can be reference modified.

General Rules

  1. All references to identifier-2, literal-1, apply equally to identifier-3, literal-2, respectively and all recursions thereof.
  2. Identifier-1 represents the sending area.
  3. Identifier-4 represents the data receiving area. Identifier-5 represents the receiving area for delimiters.
  4. Literal-1 or the data item referenced by identifier-2 specifies a delimiter.
  5. The data item referenced by identifier-6 represents the count of the number of characters within the data item referenced by identifier-1 isolated by the delimiters for the move to the data item referenced by identifier-4. This value does not include a count of the delimiter character(s).
  6. The data item referenced by identifier-7 contains a value that indicates a relative character position within the area defined by identifier-1.
  7. The data item referenced by identifier-8 is a counter that records the number of data items acted upon during the execution of an UNSTRING statement.
  8. When a figurative constant is used as the delimiter, it stands for a single character nonnumeric literal.

    When the ALL phrase is specified, one occurrence or two or more contiguous occurrences of literal-1 (figurative constant or not) or the contents of the data item referenced by identifier-2 are treated as if it were only one occurrence, and this occurrence is moved to the receiving data item according to the rules in General Rule 13d.

  9. When any examination encounters two contiguous delimiters, the current receiving area is either space- or zero-filled according to the description of the receiving area.
  10. Literal-1 or the contents of the data item referenced by identifier-2 can contain any character in the computer's character set.
  11. Each literal-1 or the data item referenced by identifier-2 represents one delimiter. When a delimiter contains two or more characters, all of the characters must be present in contiguous positions of the sending item and in the order given, to be recognized as a delimiter.
  12. When two or more delimiters are specified in the DELIMITED BY phrase, an "OR" condition exists between them. Each delimiter is compared to the sending field. If a match occurs, the character(s) in the sending field is considered to be a single delimiter. No character(s) in the sending field can be considered a part of more than one delimiter.

    Each delimiter is applied to the sending field in the sequence specified in the UNSTRING statement.

  13. When the UNSTRING statement is initiated, the current receiving area is the data item referenced by identifier-4. Data is transferred from the data item referenced by identifier-1 to the data item referenced by identifier-4 according to the following rules:
    1. If the POINTER phrase is specified, the string of characters referenced by identifier-1 is examined beginning with the relative character position indicated by the contents of the data item referenced by identifier-7. If the POINTER phrase is not specified, the string of characters is examined beginning with the leftmost character position.
    2. If the DELIMITED BY phrase is specified, the examination proceeds left to right until either a delimiter specified by the value of literal-1 or the data item referenced by identifier-2 is encountered. (See General Rule 11.) If the DELIMITED BY phrase is not specified, the number of characters examined is equal to the size of the current receiving area. However, if the sign of the receiving item is defined as occupying a separate character position, the number of characters examined is one less than the size of the current receiving area.

      If the end of the data item referenced by identifier-1 is encountered before the delimiting condition is met, the examination terminates with the last character examined.

    3. The characters thus examined (excluding the delimiting character(s), if any) are treated as an elementary alphanumeric data item, and are moved into the current receiving area according to the rules for the MOVE statement. (See the section The MOVE Statement.)
    4. If the DELIMITER IN phrase is specified, the delimiting character(s) are treated as an elementary alphanumeric data item and are moved into the data item referenced by identifier-5 according to the rules for the MOVE statement. (See the topic The MOVE Statement.) If the delimiting condition is the end of the data item referenced by identifier-1, then the data item referenced by identifier-5 is space-filled.
    5. If the COUNT IN phrase is specified, a value equal to the number of characters thus examined (excluding the delimiter character(s) if any) is moved into the area referenced by identifier-6 according to the rules for an elementary move.
    6. If the DELIMITED BY phrase is specified, the string of characters is further examined beginning with the first character to the right of the delimiter. If the DELIMITED BY phrase is not specified, the string of characters is further examined beginning with the character to the right of the last character transferred.
    7. After data is transferred to the data item referenced by identifier-4, the current receiving area is the data item referenced by the next recurrence of identifier-4. The behavior described in paragraphs 13b through 13f is repeated until either all the characters are exhausted in the data item referenced by identifier-1, or until there are no more receiving areas.
  14. The initialization of the contents of the data items associated with the POINTER phrase or the TALLYING phrase is your responsibility.
  15. The contents of the data item referenced by identifier-7 is incremented by one for each character examined in the data item referenced by identifier-1. When the execution of an UNSTRING statement with a POINTER phrase is complete, the data item referenced by identifier-7 contains a value equal to the initial value plus the number of characters examined in the data item referenced by identifier-1.
  16. When the execution of an UNSTRING statement with a TALLYING phrase is completed, the contents of the data item referenced by identifier-8 contains a value equal to its initial value plus the number of data receiving items acted upon.
  17. Either of the following situations causes an overflow condition:
    1. An UNSTRING is initiated, and the value in the data item referenced by identifier-7 is less than 1 or greater than the size of the data item referenced by identifier-1.
    2. During execution of an UNSTRING statement, all data receiving areas have been acted upon, and the data item referenced by identifier-1 contains characters that have not been examined.
  18. When an overflow condition exists, the UNSTRING operation is terminated,

    ANS85 the NOT ON OVERFLOW phrase, if specified, is ignored,

    and control is transferred to the end of the UNSTRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1. If control is transferred to imperative-statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the UNSTRING statement.

  19. ANS85 The END-UNSTRING phrase delimits the scope of the UNSTRING statement. (See the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)
  20. If, at the time of execution of an UNSTRING statement, the conditions described in General Rule 17 are not encountered, after completion of the transfer of data according to the other general rules, the ON OVERFLOW phrase, if specified, is ignored and control is transferred to the end of the UNSTRING statement

    ANS85 or, if the NOT ON OVERFLOW phrase is specified, to imperative-statement-2. If control is transferred to imperative- statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the UNSTRING statement.

  21. The evaluation of subscripting and indexing for the identifiers is as follows:
    1. Any subscripting or indexing associated with identifier-1, identifier-7, or identifier-8 is evaluated only once, immediately before any data is transferred as the result of the execution of the UNSTRING statement.
    2. Any subscripting or indexing associated with identifier-2, -3, -4, -5, or -6 is evaluated immediately before the transfer of data into the respective data item.
    3. ANS85 22..Any subscripting associated with the DELIMITED BY identifier, the INTO identifier, the DELIMITER IN identifier, or the COUNT IN identifier is evaluated once, immediately before the examination of the sending fields for the delimiter.
  22. If identifier-1, -2 or -3 occupies the same storage area as identifier-4, -5, -6, -7 or -8, or if identifier-4, -5 or -6 occupies the same storage area as identifier-7 or -8, or if identifier-7 and identifier-8 occupy the same storage area, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.

Example

        01  WS-INPUT-BUFFER.
           05 FILLER     PIC  X(050) VALUE
           'AAAAAAAAAAAAAAAAAAAAAAAA:BBBBBBBBBBBBBBBBBBBBBBBBB'.
        01 WS-OUTPUT-UNSTR-1  PIC  X(50) VALUE SPACES.
        01 WS-OUTPUT-UNSTR-2  PIC  X(50) VALUE SPACES.
        01 WS-DELIMITER1      PIC  X(10) VALUE SPACES.
        01 WS-DELIMITER2      PIC  X(10) VALUE SPACES.

        UNSTRING WS-INPUT-BUFFER DELIMITED BY ':'
                    INTO WS-OUTPUT-UNSTR-1
                    DELIMITER IN WS-DELIMITER1
                    WS-OUTPUT-UNSTR-2
                    DELIMITER IN WS-DELIMITER2
        display WS-OUTPUT-UNSTR-1
        display WS-OUTPUT-UNSTR-2
        display WS-DELIMITER1
        display WS-DELIMITER2.
Parent topic: Statements
Related information
The MOVE Statement
Explicit and Implicit Scope Terminators


USE Statement (COBOL)

The USE Statement

The USE statement specifies procedures for input-output error handling, that are in addition to the standard procedures provided by the input-output control system.

General Formats for Format 1 (Sequential, Relative and Indexed Files)

USE - FORMAT 1

General Formats for Format 2 (Record Sequential Files)

USE - FORMAT 2

General Formats for Format 3 (Relative and Indexed Files)

USE - FORMAT 3

Syntax Rules for All Formats (All Files)

  1. Format 1 is the ERROR declarative.

    OSVS VSC2 Formats 2 and 3 are the LABEL declarative.

  2. A USE statement, when present, must immediately follow a section header in the Declaratives Section and must be followed by a period followed by a space.
  3. The USE statement itself is never executed; it merely defines the conditions calling for the execution of the USE procedures.
  4. The files implicitly or explicitly referenced in a USE statement need not all have the same organization or access.

Syntax Rules for Format 1 (Sequential, Relative and Indexed Files)

  5. The same file-name can appear in a different specific arrangement of the format. Appearance of a file-name in a USE statement must not cause the simultaneous request for execution of more than one USE procedure.

    ANS85 The same file-name must not appear in more than one USE AFTER EXCEPTION statement within the same Procedure Division.

  6. The words ERROR and EXCEPTION are equivalent and can be used interchangeably.

Syntax Rules for Formats 2 and 3 (Record Sequential, Relative and Indexed Files)

  7. OSVS VSC2 If both BEGINNING and ENDING are omitted, the effect is as though both BEGINNING and ENDING had been specified.

Syntax Rules for Format 2 (Record Sequential Files)

  8. OSVS VSC2 REEL and UNIT are treated as equivalent.
  9. OSVS VSC2 If both FILE and REEL/UNIT are omitted, the effect is as though both REEL or UNIT and FILE had been specified.
  10. OSVS VSC2 Any one file-name and any one OPEN mode can appear in only one declarative for each of the possible combinations of BEGINNING/ENDING and FILE/REEL as shown below:
    • BEGINNING FILE
    • BEGINNING REEL/UNIT
    • ENDING FILE
    • ENDING REEL/UNIT

General Rules for All Formats (All Files)

  1. After execution of a USE procedure, control is returned to the invoking routine. Note that control is not returned if an exception is trapped.
  2. Within a USE procedure, there must not be any reference to any non-declarative procedures. Conversely, in the non-declarative portion there must be no reference to procedure-names that appear in the declarative portion, except that PERFORM statements can refer to a USE statement.

    OSVS VSC2 MF This restriction can be ignored.

  3. Within a USE procedure, there must be no execution of any statement that would cause the execution of a USE procedure that has previously been invoked and has not yet returned control to the invoking routine.

General Rules for Format 1 (Sequential, Relative and Indexed Files)

  4. The designated procedures are executed by the input-output system after completing the standard input-output error routine, or upon recognition of the AT END condition, when the AT END phrase has not been specified in the input-output statement.
  5. ANS85 When file-name-1 is specified explicitly, no other USE statement applies to file-name-1.
  6. The GIVING phrase is documentary only.

General Rules for Formats 2 and 3 (Record Sequential, Relative and Indexed Files)

  7. OSVS VSC2 If the BEGINNING phrase is specified explicitly or implicitly, the following actions are taken during the execution of an applicable OPEN statement:
    Open Mode Action
    INPUT
    1. Read header labels
    2. Execute beginning declarative
    OUTPUT
    1. Execute beginning declarative
    2. Write header labels
    I/O
    1. Read header labels
    2. Execute beginning declarative
    3. Write header labels
    EXTEND
    1. Read header labels
    2. Execute beginning declaratives (trailer labels treated as header)
    3. Write header labels
  8. OSVS VSC2 If the ENDING phrase is specified explicitly or implicitly, the following actions are taken during the execution of an applicable CLOSE statement:
    Open Mode Action
    INPUT
    1. Read trailer labels
    2. Execute ending declarative
    OUTPUT
    1. Execute ending declarative
    2. Write trailer labels
    I/O
    1. Read trailer labels
    2. Execute ending declarative
    3. Write trailer labels
    EXTEND
    1. Execute ending declaratives
    2. Write trailer labels
  9. OSVS VSC2 The statement GO TO MORE-LABELS appearing in a declarative procedure is treated as a simple jump to the start of the declarative procedure in which it appears.
Parent topic: Statements


WAIT Statement (COBOL)

The WAIT Statement

The WAIT statement suspends the current thread's execution until the targeted thread's execution terminates and optionally retrieves the value returned from the targeted thread's execution.

The WAIT statement suspends execution until an event is TRUE.

General Formats for Format 1 (Thread)

General Formats for Format 2 (Event)

Syntax Rules for Format 1 (Thread)

  1. Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
  2. Identifier-1 must be defined either as USAGE POINTER or must be four bytes in size. It must not be a function-identifier.
  3. Identifier-2 must be defined as an integer data item that has a length of at least four digits.

Syntax Rules for Format 2 (Event)

  4. Event-pointer-1 must be defined as USAGE EVENT-POINTER.

General Rules for Format 1 (Thread)

  1. Thread-pointer-1 must contain a thread handle as returned from the START statement with the IDENTIFIED BY phrase or from a CBL_THREAD_ library routine.
  2. A successful WAIT statement suspends the current thread's execution until the termination of the thread referenced by the thread handle contained in thread-pointer-1.
  3. If the RETURNING phrase is specified, a successful WAIT statement returns a value in identifier-1.
  4. After the successful execution of a WAIT statement, the thread handle contained in thread-pointer-1 is invalid.
  5. If the STATUS phrase is specified, the execution of the WAIT statement places into identifier-4 one of the return codes specified for the CBL_THREAD_ library routines.
  6. If the WAIT statement fails, one of the return codes specified for the CBL_THREAD_ library routines is placed into identifier-2, if specified, and then one of the following occurs:
    1. If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure-branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the WAIT statement and the NOT ON EXCEPTION phrase, if specified, is ignored.
    2. Otherwise, if the NOT ON EXCEPTION phrase or the STATUS phrase is specified, control is transferred to the end of the WAIT statement and the NOT ON EXCEPTION phrase, if specified, is ignored.
    3. Otherwise, the run unit terminates with a run-time system error.
  7. If the WAIT verb is successful, the following occurs in the order specified:
    1. If the STATUS phrase, is specified, ZERO is moved to identifier-2.
    2. If the NOT ON EXCEPTION phrase is specified, control is transferred to imperative-statement-2. Execution then continues according to the rules for each statement specified in imperative-statement-2. If a procedure-branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the WAIT statement and the ON EXCEPTION phrase, if specified, is ignored.

General Rules for Format 2 (Event)

  8. A successful WAIT statement suspends execution until the event referenced by event-pointer-1 is TRUE.
    Note: Execution resumes immediately if the event referenced by event-pointer-1 is TRUE when the statement is executed.
  9. If the WAIT statement fails, the run unit terminates with a run-time system error.
Parent topic: Statements


WRITE Statement (COBOL)

The WRITE Statement

The WRITE statement releases a logical record for an output or input-output file. For sequential files it can also be used for vertical positioning of lines within a logical page.

XOPEN Although they are a part of the standard COBOL definition, mnemonic names in the ADVANCING phrase are explicitly excluded from the X/Open COBOL language definitions and should not be used in X/Open COBOL source programs.

General Formats for Format 1 (Record MF and Line Sequential Files)

General Formats for Format 2 (Record Sequential Files)

General Formats for Format 3 (Record Sequential Files)

General Formats for Format 4 (Relative and Indexed Files)

Directives and RTS switches

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • WRITE-LOCK - causes a WRITE statement to acquire a record lock when multiple recording locking is used.
    • FDCLEAR - causes the contents of the record area to be predictable after a WRITE statement.
  2. The following RTS switches may impact the semantics described in this section.
    • N - controls the insertion of null characters before control characters when writing line sequential records.
    • T - controls the insertion of tab characters when writing line sequential records.

Syntax Rules for All Formats (All Files)

  1. ANS85 If identifier-1 is a function-identifier, it must reference an alphanumeric function. When identifier-1 is not a function-identifier, record-name and identifier-1 must not reference the same storage area.
  2. Record-name is the name of a logical record in the File Section of the Data Division and can be qualified.
  3. OSVS VSC2 MF Record-name can define a floating-point item.
  4. OSVS VSC2 MF Identifier-1 can be defined as a floating-point item.

Syntax Rules for Format 1 (RecordSequential Files)

  5. MF A user-defined mnemonic-name can be used instead of TAB if they are associated in the Special-Names paragraph. (See the topic The Special-Names Paragraph.)
  6. When identifier-2 is used in the ADVANCING phrase, it must be the name of an elementary integer data item.
  7. Integer, or the value of the data item referenced by identifier-2, can be zero.
  8. VSC2 Integer can be signed.
  9. If the END-OF-PAGE phrase is specified, the LINAGE clause must be specified in the file description entry for the associated file.
  10. The words END-OF-PAGE and EOP are equivalent.
  11. The ADVANCING mnemonic-name phrase cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause.
  12. ANS85 The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement.

    MF This restriction can be ignored.

    OSVS VSC2 MF Alternatively, function-name can itself be used instead of an associated mnemonic-name.

Syntax Rules for Format 2 (Record Sequential Files)

  13. OSVS This format cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause.
  14. OSVS If this format of the WRITE statement is used for writing to a given file, then every WRITE statement used for that file should be in this format.
  15. OSVS In the AFTER POSITIONING phrase, identifier-2 must be defined as a single-character alphanumeric item. See General Rule 18 for its possible values.

Syntax Rules for Format4 (Relative and Indexed Files)

  16. The INVALID KEY phrase must be specified if an applicable USE procedure is not specified for the associated file.

    OSVS VSC2 MF This rule is not enforced.

General Rules for All Formats (All Files)

  1. The results of the execution of the WRITE statement with the FROM phrase is equivalent to the execution of:
    1. The statement:
       MOVE identifier-1 TO record-name

      according to the rules specified for the MOVE statement:

    2. The same WRITE statement without the FROM phrase.

    The contents of the record area prior to the execution of the implicit MOVE statement have no effect on the execution of this WRITE statement.

    After execution of the WRITE statement is complete, the information in the area referenced by identifier-1 is available, even though the information in the area referenced by record-name is not. (See General Rule 13.)

  2. The file position indicator is unaffected by the execution of a WRITE statement.
  3. The execution of the WRITE statement causes the value of the FILE STATUS data item, if any, associated with the file to be updated. (See the topic I-O Status in the chapter Procedure Division.)
  4. The maximum record size for a file is established at the time the file is created and must not subsequently be changed.
  5. The number of character positions on a mass storage device to store a logical record in a file may or may not be equal to the number of character positions defined by the logical description of that record .
  6. The execution of the WRITE statement releases a logical record to the operating system.
  7. ANS85 If the execution of the WRITE statement is unsuccessful, the I/O status of the file-name associated with record-name is updated and control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to the file-name associated with record-name. (See the topic The USE Statement.)

General Rules for Format 1 (Record SequentialFiles)

  8. MF When the mnemonic-name associated with TAB is specified the result is to cause the paper to throw to the standard vertical tabulation position.
  9. If the logical end of the representation of the printed page is reached during the execution of a WRITE statement with the END-OF-PAGE phrase, the imperative-statement specified in the END-OF-PAGE phrase is executed. The logical end is specified in the LINAGE clause associated with record-name.
  10. An end-of-page condition is reached whenever the execution of a given WRITE statement with the END-OF-PAGE phrase occurs, when the execution of such a WRITE statement causes the LINAGE-COUNTER to equal or exceed the value specified by integer-2 or the data item referenced by data-name-2 of the LINAGE clause, if specified. In this case, the WRITE statement is executed and then the imperative statement in the END-OF-PAGE phrase is executed.

    An automatic page overflow condition is reached whenever the execution of a given WRITE statement (with or without an END-OF-PAGE phrase) cannot be fully accommodated within the current page body.

    This occurs when a WRITE statement, if executed, would cause the LINAGE-COUNTER to exceed the value specified by integer-1 or the data item referenced by data-name-1 of the LINAGE clause. In this case, the record is presented on the logical page before or after (depending on the phrase used) the device is repositioned to the first line that can be written on the next logical page as specified in the LINAGE clause. The imperative statement in the END-OF-PAGE clause, if specified, is executed after the record is written and the device has been repositioned.

    If integer-2 or data-name-2 of the LINAGE clause is not specified, no end-of-page condition distinct from the page overflow condition is detected. In this case, the end-of-page condition and page overflow condition occur simultaneously.

    If integer-2 or data-name-2 of the LINAGE clause is specified, but the execution of a given WRITE statement would cause LINAGE-COUNTER to simultaneously exceed the value of both integer-2 or the data item referenced by data-name-2 and integer-1 or the data item referenced by data-name-1, then the operation proceeds as if integer-2 or data-name-2 had not been specified.

General Rules for Format 1 (LineSequential Files)

  11. MF If the ADVANCING phrase is not used, automatic advancing of one line is provided to act in accordance with the convention of your operating system text editor (usually as if you had specified BEFORE ADVANCING 1 LINE).
  12. MF MF When an attempt is made to write beyond the externally defined boundaries of a sequential file, an exception condition exists and the contents of the record area are unaffected. The following actions take place:
    1. The value of the FILE STATUS data item, if any, of the associated file is set to a value indicating a boundary violation. (See the topic I-O Status in the chapter Procedure Division.)
    2. If a USE AFTER STANDARD EXCEPTION declarative is explicitly or implicitly specified for the file, that declarative procedure is executed.
    3. If a USE AFTER STANDARD EXCEPTION declarative is not explicitly or implicitly specified for the file, the result is undefined.
  13. MF MF After the recognition of an end-of-unit of an output file that is contained on more than one physical reel/unit, the WRITE statement performs the following operations:
    1. The standard ending reel/unit procedure.
    2. The reel/unit swap.
    3. The standard beginning of reel/unit label procedure.
  14. XOPEN When the file contains fixed-length records, the entire record area is written to the file. If the record area is redefined with records of varying sizes, records that are shorter than the maximum size may need to be spaced-filled so that they do not contain meaningless data.
  15. ANS85 If, during the successful execution of a WRITE statement with the NOT END-OF-PAGE phrase, the end-of-page condition does not occur, control is transferred to imperative-statement-2 after execution of the input-ouput operation.

General Rules for Format1 (Record and Line Sequential Files)

  16. Both the ADVANCING phrase and the END-OF-PAGE phrase allow control of the vertical positioning of each line on a representation of a printed page.

    If the ADVANCING phrase is not used, automatic advancing is provided when output is directed to a list device (PRINTER or PRINTER-1), to act as if you had specified AFTER ADVANCING 1 LINE. If the ADVANCING phrase is used, advancing is provided as follows:

    1. If identifier-2 is specified, the representation of the printed page is advanced the number of lines equal to the current value associated with identifier-2.
    2. If integer is specified, the representation of the printed page is advanced the number of lines equal to the value of integer.
    3. If mnemonic-name is specified, the representation of the printed page is advanced as specified in the topic The Special-Names Paragraph.
    4. If the BEFORE phrase is used, the line is presented before the representation of the printed page is advanced according to rules a, b, and c above.
    5. If the AFTER phrase is used, the line is presented after the representation of the printed page is advanced according to rules a, b, and c above.
    6. If PAGE is specified, the record is presented on the logical page before or after (depending on the phrase used) the device is repositioned to the next logical page. If the record to be written is associated with a record sequential file whose file description entry contains a LINAGE clause, the device is repositioned to the first line that can be written on the next logical page as specified in the LINAGE clause.
  17. The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement.

General Rules for Formats 1, 2, and 3 (Sequential Files)

  18. The associated file must be open in the OUTPUT or EXTEND mode at the time of the execution of this statement. (See the topic The OPEN Statement.)
  19. The logical record released by the execution of the WRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause or the execution of the WRITE statement was unsuccessful due to a boundary violation.

    The logical record is also available as a record of other files referenced in the SAME RECORD AREA clause as the associated output file, as well as the file associated with record-name.

General Rules for Format 2 (Record Sequential Files)

  20. OSVS When the AFTER POSITIONING phrase is used in a WRITE statement, the system moves a suitable character into the first position of the record before it is written to the file. This first character position must be reserved for this purpose. If the identifier-2 option is used, then the character moved into the output record is simply the value held by identifier-2 and should be one of the following:
    Identifier-2 | Interpretation
    (space) | Single-spacing
    0 | Double-spacing
    - Triple-spacing
    + Suppress spacing
    1-9 | Skip to channel 1 through 9, respectively
    A, B, C | Skip to channel 10, 11, 12, respectively
    V, W | Pocket select 1 or 2

    If the integer-1 option is used, then the character placed in the output record is determined as follows:

    Integer | Output Character | Interpretation
    0 | 1 | Skip to channel 1
    1 | (space) | Single-space
    2 | 0 | Double-spacing
    3 - Triple-spacing
  21. OSVS The END-OF-PAGE phrase, if specified, is documentary.

General Rules for Format 3 (RecordSequential Files)

  22. OSVS VSC2 MF When an attempt is made to write beyond the externally defined boundaries of a sequential file, an INVALID KEY condition occurs. When the INVALID KEY condition occurs, the execution of the WRITE statement is unsuccessful; the contents of the record area are unaffected, and the FILE STATUS data item, if any, of the associated file is set to a value indicating the cause of the condition. Execution proceeds according to the rules stated in The INVALID KEY Condition in this chapter (see also the section I-O Status in the chapter Procedure Division).

General Rules for Format 4 (Relative and Indexed Files)

  23. The associated file must be open in the OUTPUT, I/O or EXTEND mode at the time of execution of this statement; an indexed file must not be open in the I/O mode with sequential access mode. (See the topic The File Control Entry and the section The OPEN Statement.)
  24. The logical record released by the execution of the WRITE statement is available in the record area only if the associated file is named in a SAME RECORD AREA clause, or the execution of the WRITE statement is unsuccessful due to an INVALID KEY condition.

    The logical record is also available as a record of other files referenced in the same SAME RECORD AREA clause as the associated output file, as well as the file associated with record-name.

  25. When the INVALID KEY condition is recognized, the execution of the WRITE statement is unsuccessful; the contents of the record area are unaffected, and the FILE STATUS data item, if any, of the associated file is set to a value indicating the cause of the condition. Execution proceeds according to the rules stated in The INVALID KEY Condition in this chapter (see also the section I-O Status in the chapter Procedure Division).

General Rules for Format4 (Relative Files)

  26. When a file is opened in the OUTPUT mode, the WRITE statement proceeds as follows:
    1. If access mode is sequential, the WRITE statement causes a record to be released to the operating system. The first record has a relative record number of one and subsequent records releasedhave relative record numbers of 2, 3, 4, ... . If the RELATIVE KEY data item has been specified in the file control entry for the associated file, the relative record number of the record just released is placed into the RELATIVE KEY data item by the operating system during execution of the WRITE statement.
    2. If access mode is random or dynamic, the value of the RELATIVE KEY data item must be initialized in the runtime element, prior to the execution of the WRITE statement, with the relative record number, or be associated with the record in the record area. That record is then released to the operating system by execution of the WRITE statement.
  27. When a file is opened in I/O mode and access mode is random or dynamic, the value of the RELATIVE KEY data item must be initialized by the runtime element with the relative record number to be associated with the record in the record area. Execution of a WRITE statement then causes the contents of the record area to be released to the operating system.
  28. The INVALID KEY condition exists under either of the following circumstances:
    1. When access mode is random or dynamic, and the RELATIVE KEY data item specifies a record which already exists in the file:
    2. When an attempt is made to write beyond the externally defined boundaries of the file.

General Rules for Format 4 (Indexed Files)

  29. Execution of the WRITE statement causes the contents of the record area to be released. The operating system uses the contents of the record keys so that subsequent access of the record can be made via any of those specified record keys.
  30. The value of the prime record key should be unique within the records in the file.
  31. The data item specified as the prime record key must be set by the runtime element to the desired value prior to the execution of the WRITE statement.
  32. If sequential access mode is specified for the file, records must be released to the operating system in ascending order of prime record key values.
  33. If random or dynamic access mode is specified, records can be released to the operating system in any program-specified order.
  34. When the ALTERNATE RECORD KEY clause is specified in the file control entry for an indexed file, the value of the alternate record key can be non-unique only if the DUPLICATES phrase is specified for that record key data item. In this case, the operating system provides storage of records so that when records are accessed sequentially, records with duplicate alternate record keys are retrieved in the order in which they are released to the operating system.
  35. The INVALID KEY condition exists under the following circumstances:
    1. When sequential access mode is specified for a file opened in OUTPUT mode, and the value of the prime record key is not greater than the value of the prime record key of the previous record, or:
    2. When the file is opened in OUTPUT or I/O mode, and the value of the prime record key is equal to the value of a prime record key of a record already existing in the file, or:
    3. When the file is opened in OUTPUT or I/O mode, and the value of an alternate record key for which duplicates are not allowed equals the corresponding data item of a record already existing in the file, or:
    4. When an attempt is made to write beyond the externally defined boundaries of the file.
  36. ANS85 Transfer of control following the successful or unsuccessful execution of the WRITE operation depends on the presence or absence of the INVALID KEY and NOT INVALID KEY phrases. (See the topic The INVALID KEY Condition.)
Parent topic: Statements
Related information
The Special-Names Paragraph
I-O Status
The USE Statement
The OPEN Statement
The File Control Entry
The INVALID KEY Condition


XML GENERATE Statement (COBOL)

The XML GENERATE Statement

The XML GENERATE statement converts data to XML format.

General Format

when-phrase

generic-suppression-phrase

Syntax Rules

  1. Identifier-1 must be an alphanumeric or national data item. It must not be described with the JUSTIFIED clause, and cannot be a function identifier.
  2. Identifier-1 can be subscripted or reference modified.
  3. Identifier-1 must not overlap identifier-2 or identifier-3.
  4. Identifier-1 must be a national data item if the generated XML includes data from identifier-2 for:
    1. Any national data item or DBCS data item
    2. Any data item with a DBCS name (that is, a data item whose name contains DBCS characters)
    3. An alphanumeric data item that contains DBCS characters
  5. Identifier-2 cannot be a function identifier or be reference modified.
  6. Identifier-2 can be subscripted.
  7. Identifier-2 must not overlap with identifier-1 or identifier-3.
  8. Identifier-2 must not specify the RENAMES clause.
  9. All data items specified by identifier-2 that are not ignored according to General Rule 5 must satisfy the following conditions:
    1. Each elementary data item must either have class alphabetic, alphanumeric, numeric, or national, or be an index data item. That is, no elementary data item can be described with the USAGE POINTER, USAGE FUNCTION-POINTER, USAGE PROCEDURE-POINTER, or USAGE OBJECT REFERENCE phrase.
    2. There must be at least one such elementary data item.
    3. Each non-FILLER data-name must be unique within any immediately superordinate group data item.
  10. Identifier-3 must be an integer data item defined without the symbol P in its picture string.
  11. Identifier-3 must not overlap identifier-1 or identifier-2.
  12. codepage must be an unsigned integer data item or unsigned integer literal and must represent a valid coded character set identifier (CCSID).
  13. identifier-4 and identifier-5 must reference data items of category alphanumeric or national.
  14. identifier-4 and identifier-5 must not overlap identifier-1 or identifier-3.
  15. literal-4 and literal-5 must be of category alphanumeric or national, and must not be figurative constants.
  16. identifier-6 must reference identifier-2 or one of its subordinate data items. It cannot be a function identifier and cannot be reference modified or subscripted. It must not specify any data item which is ignored by the XML GENERATE statement. For more information about identifier-2, see the description of identifier-2.
  17. literal-6 must be an alphanumeric or national literal containing the attribute or element name to be generated in the XML document corresponding to identifier-6.
  18. If literal-6 is a national literal, identifier-1 must reference a data item of category national.
  19. identifier-7 must reference an elementary data item that is subordinate to identifier-2. It must not specify any data item that is ignored by the XML GENERATE statement. It cannot be a function identifier and cannot be reference modified or subscripted. For more information about identifier-2, see the description of identifier-2.
  20. If specified without the WHEN phrase, identifier-8 can reference an elementary data item or a group item that is subordinate to identifier-2. If a group item is specified, all subordinate data items are suppressed. If the WHEN phrase is specified, identifier-8 must reference an elementary data item that is subordinate to identifier-2, and must not be a data item that is ignored by the XML GENERATE operation.
  21. If ZERO, ZEROES, or ZEROS is specified in the WHEN phrase, the following rules apply:
    • identifier-8 must not be of USAGE DISPLAY-1.
    • Data items of USAGE DISPLAY-1 are not identified for potential suppression in the generic-suppression-phrase.
  22. If SPACE or SPACES is specified in the WHEN phrase, the following rules apply:
    • identifier-8 must be of USAGE DISPLAY, DISPLAY-1 or NATIONAL. If identifier-8 is a zoned or national decimal item, it must be an integer.
    • Data items of USAGE DISPLAY, DISPLAY-1 or NATIONAL are identified for potential suppression in the generic-suppression-phrase. For zoned or national decimal item, only integers are identified.
  23. If LOW-VALUE, LOW-VALUES, HIGH-VALUE, or HIGH-VALUES is specified in the WHEN phrase, the following rules apply:
    • identifier-8 must be of USAGE DISPLAY or NATIONAL. If identifier-8 is a zoned or national decimal item, it must be an integer.
    • Data items of USAGE DISPLAY or NATIONAL are identified for potential suppression in the generic-suppression-phrase. For zoned or national decimal item, only integers are identified.

General Rules

  1. Identifier-1 is the receiving area for a generated XML document.
  2. If identifier-1 is a national data item, the generated XML document is encoded in UTF-16.
  3. Identifier-1 must be large enough to contain the generated XML document. Typically, it should be from five to eight times the size of identifier-2, depending on the length of the data name or data names within identifier-2. If identifier-1 is not large enough, an error condition occurs at the end of the XML GENERATE statement.
  4. Identifier-2 is the group or elementary data item to be converted to XML format.
  5. The following data items specified by identifier-2 are ignored by the XML GENERATE statement:
    1. Unnamed elementary data items or elementary FILLER data items
    2. Slack bytes inserted for SYNCHRONIZED items
    3. Data items subordinate to identifier-2 that are described with the REDEFINES clause or that are subordinate to such a redefining item
    4. Data items subordinate to identifier-2 that are described with the RENAMES clause
    5. Group data items all of whose subordinate data items are ignored
  6. The content of each eligible elementary data item within identifier-2 is converted to character format as described below. The converted content is then inserted as element character content in XML markup. The XML element names are derived from the data names within identifier-2. The names of group items that contain the selected elementary items are retained as parent elements. No extra white space (new lines, indentation, etc.) is inserted to make the generated XML more readable. The exact mixed-case spelling of data names from the data description entry is retained and data names that start with a digit are prefixed by an underscore.
    Note: The exact mixed-case spelling of data names from the data description entry is retained only if you specify the PRESERVECASE directive.
  7. Elementary data items are converted to character format depending on the type of the data item:
    1. Alphabetic, alphanumeric, alphanumeric-edited, DBCS, external floating-point, national, and numeric-edited items are not converted.
    2. Fixed-point numeric data items other than COMPUTATIONAL-5 (COMP-5) binary data items are converted as if they were moved to a numeric-edited item that has:
      • As many integer positions as the numeric item has, but with at least one integer position
      • An explicit decimal point, if the numeric item has at least one decimal position
      • The same number of decimal positions as the numeric item
      • A leading '-' picture symbol if the data item is signed
    3. COMPUTATIONAL-5 (COMP-5) binary data items are converted in the same way as the other fixed-point numeric items except for the number of integer positions. The number of integer positions is computed depending on the number of '9' symbols in the picture character string as follows:
      • 5 minus the number of decimal places, if the data item has one to four '9' picture symbols
      • 10 minus the number of decimal places, if the data item has five to nine '9' picture symbols
      • 20 minus the number of decimal places, if the data item has 10 to 18 '9' picture symbols
    4. Internal floating-point data items are converted as if they were moved to a data item as follows:
      • For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
      • For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99
    5. Index data items are converted as if they were declared USAGE COMP-5 PICTURE S9(9).
    6. If identifier-1 is a national data item, any non-national values are converted to national format.
  8. After any conversion to character format, leading and trailing spaces and leading zeroes are eliminated as follows:
    1. For values converted from signed numeric values, the leading space is removed if the value is positive.
    2. For values converted from numeric items, leading zeroes (after any initial minus sign) up to but not including the digit immediately before the actual or implied decimal point are eliminated. Trailing zeroes after a decimal point are retained. For example:
      • -012.340 becomes -12.340
      • 0000.45 becomes 0.45
      • 0013 becomes 13
      • 0000 becomes 0
    3. Character values from alphabetic, alphanumeric, DBCS, and national data items have either trailing or leading spaces removed, depending on whether the corresponding data items have left (default) or right justification, respectively. That is, trailing spaces are removed from values whose corresponding data items do not specify the JUSTIFIED clause. Leading spaces are removed from values whose data items do specify the JUSTIFIED clause. If a character value consists only of spaces, one space remains as the value after trimming is finished.
  9. If a data item after any conversion contains any characters that are illegal in XML content, the original data value - the value in the data item before any conversion or trimming - is represented in hexadecimal, and an element tag name with the prefix hex. is substituted for the regular tag name. For example, if data item My-Name is found at run time to contain LOW-VALUES, the XML element tag name hex.My-Name is used instead, and the content is represented as a string of pairs of zero digits.
  10. If a data item after any conversion contains instances of any of the following the five symbols:
    • & (ampersand)
    • ' (apostrophe)
    • > (greater-than sign)
    • < (less-than sign)
    • " (quotation mark)

    the symbols are converted into the equivalent XML references &amp;, &apos;, &gt;, &lt;, and &quot;, respectively.

  11. If identifier-1 is longer than the generated XML document, only that part of identifier-1 in which XML is generated is changed. The rest of identifier-1 contains the data that was present before this execution of the XML GENERATE statement. To avoid referring to that data, either initialize identifier-1 to spaces before the XML GENERATE statement or specify the COUNT IN phrase.
  12. If the COUNT IN phrase is specified, identifier-3 contains (after execution of the XML GENERATE statement) the count of generated XML character positions. If identifier-1 (the receiver) is a national data item, the count is in national character positions (UTF-16 character encoding units). Otherwise, the count is in bytes.
  13. The ENCODING phrase is documentary only.
  14. If the XML-DECLARATION phrase is specified, the generated document starts with an XML declaration that includes the XML version information and an encoding declaration. If identifier-1 is of category national, the encoding declaration has the value UTF-16 (encoding="UTF-16" ). If the XML-DECLARATION phrase is omitted, the generated XML document does not include an XML declaration.
  15. If the ATTRIBUTES phrase is specified, each eligible item in the generated document is expressed as an attribute of the XML element that corresponds to the data item immediately superordinate to that eligible item (and not as a child element of the XML element). To be eligible, a data item must be elementary, must have a name other than FILLER, and must not specify an OCCURS clause in its data description entry.
  16. The NAMESPACE phrase identifies a namespace for the generated XML document. If the NAMESPACE phrase is not specified, or if identifier-4 has length zero or contains all spaces, the element names of XML documents produced by the XML GENERATE statement are not in any namespace.
  17. The NAMESPACE-PREFIX phrase identifies a prefix to qualify the start and end tag of each element in the generated XML document.
    • If the NAMESPACE-PREFIX phrase is not specified, or if identifier-5 is of length zero or contains all spaces, the NAMESPACE phrase specifies the default namespace for the document. In this case, the namespace declared on the root element applies by default to each element name in the document, including that of the root element.
    • If the NAMESPACE-PREFIX phrase is specified, and identifier-5 is not of length zero and does not contain all spaces, then the start and end tag of each element in the generated document is qualified with the specified prefix. When the XML GENERATE statement is executed, the prefix must be a valid XML name, but without the colon (:). The prefix can have trailing spaces, which are removed before use.

  18. The NAME phrase allows you to supply element and attribute names. If identifier-6 is specified more than once in the NAME phrase, the last specification is used. literal-6 must be a valid XML local name.

  19. The TYPE phrase allows you to control attribute and element generation. If identifier-7 is specified more than once in the TYPE phrase, the last specification is used.
    • If the XML GENERATE statement also includes a WITH ATTRIBUTES phrase, the TYPE phrase has precedence for identifier-7.
    • When ATTRIBUTE is specified, identifier-7 must be eligible to be an XML attribute. identifier-7 is expressed in the generated XML as an attribute of the XML element immediately superordinate to identifier-7 rather than as a child element.
    • When ELEMENT is specified, identifier-7 is expressed in the generated XML as an element. The XML element name is derived from identifier-7 and the element character content is derived from the converted content of identifier-7 as described in Operation of XML GENERATE.
    • When CONTENT is specified, identifier-7 is expressed in the generated XML as element character content of the XML element that corresponds to the data item immediately superordinate to identifier-7. The value of the element character content is derived from the converted content of identifier-7 as described in Operation of XML GENERATE. When CONTENT is specified for multiple identifiers all corresponding to the same superordinate identifier, the multiple contributions to the element character content are concatenated.

  20. The SUPPRESS phrase allows you to identify items that are subordinate to identifier-2, and suppress them when generating the XML. Use the WHEN clause to conditionally suppress such items.

    If the SUPPRESS phrase is specified, identifier-1 must be large enough to contain the generated XML document before any suppression.

    With the generic-suppression-phrase, elementary items subordinate to identifier-2 that are not otherwise ignored by XML GENERATE operations are identified generically for potential suppression. Either items of class numeric, if the NUMERIC keyword is specified, or items that are not of class numeric, if the NONNUMERIC keyword is specified, or both, may be suppressed. If the ATTRIBUTE keyword is specified, only items that would be expressed in the generated XML document as an XML attribute are identified for potential suppression. If the CONTENT keyword is specified, only items that would be expressed in the generated XML document as element character content of the XML element corresponding to identifier-2 are identified. If the ELEMENT keyword is specified, only items that would be expressed in the generated XML document as an XML element are identified. If multiple generic-suppression-phrase are specified, the effect is cumulative.

    identifier-8 explicitly identifies items for potential suppression. If identifier-8 is specified more than once in the SUPPRESS phrase, the last specification is used. The explicit suppression specification for identifier-8 overrides the suppression specification that is implied by any generic-suppression-phrase, if identifier-8 is also one of the identifiers generically identified.

  21. An exception condition exists when an error occurs during generation of the XML document, for example if identifier-1 is not large enough to contain the generated XML document. In this case, XML generation stops and the content of the receiver, identifier-1, is undefined. If the COUNT IN phrase is specified, identifier-3 contains the number of character positions that were generated, which can range from 0 to the length of identifier-1. If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If the ON EXCEPTION phrase is not specified, the NOT ON EXCEPTION phrase, if any, is ignored and control is transferred to the end of the XML GENERATE statement. Special register XML-CODE contains an exception code.
  22. If an exception condition does not occur during generation of the XML document, control is passed to imperative-statement-2, if specified. Otherwise, it is passed to the end of the XML GENERATE statement. The ON EXCEPTION phrase, if specified, is ignored. Special register XML-CODE contains zero after execution of the XML GENERATE statement.
Parent topic: Statements


XML PARSE Statement (COBOL)

The XML PARSE Statement

The XML PARSE statement is used to interface with an XML parser that is part of the COBOL run-time system. The XML PARSE statement parses an XML document into its individual pieces and passes each piece, one at a time, to a user-written processing procedure.

General Format

Syntax Rules

  1. Identifier-1 must be an alphanumeric or national data item, cannot be a function-identifier, and should contain the XML document character stream. If identifier-1 is a national data item, its contents must be encoded using CCSID 1200 (Unicode UTF-16). It must not contain any character entities that are represented using multiple encoding units. Use a character reference, for example "" or "", to represent any such characters.
  2. Procedure-name-1 specifies the first or only section or paragraph in the processing procedure
  3. Procedure-name-2 specifies the last section or paragraph in the processing procedure.
  4. codepage must be an unsigned integer data item or an unsigned integer literal that represents a valid coded character set identifier (CCSID).
  5. If identifier-1 references a data item of category national, codepage must specify CCSID 1200, for Unicode UTF-16.
  6. If identifier-1 references a data item of category alphanumeric, codepage must specify CCSID 1208 for UTF-8 or one of the supported values, namely 1140 or 1047.
  7. identifier-2 must be of category alphanumeric and cannot be a function identifier.
  8. xml-schema-name-1 must be defined in the XML-SCHEMA clause of the SPECIAL-NAMES paragraph.
  9. The RETURNING NATIONAL phrase can be specified only when the XMLPARSE(XMLSS) compiler option is in effect.
  10. The VALIDATING phrase can be specified only when the XMLPARSE(XMLSS) compiler option is in effect.
  11. The ENCODING phrase can be specified only when the XMLPARSE(XMLSS) compiler option is in effect.

General Rules

  1. The PROCESSING PROCEDURE phrase specifies the name of a procedure to handle the various events that the XML parser generates. The processing procedure consists of the statements that handle XML events. The range of the processing procedure also includes all statements executed by CALL, EXIT, GO TO, GOBACK, INVOKE, and PERFORM statements in the processing procedure. The Compiler inserts a return mechanism after the last statement in the processing procedure. The processing procedure can terminate the run unit with a STOP RUN statement. It must not attempt to return to the parser with a GOBACK or EXIT PROGRAM statement.
  2. The ENCODING phrase specifies an encoding that is assumed for the source XML document in identifier-1.
  3. When identifier-1 references a national data item, XML document fragments are always returned in Unicode UTF-16 representation in the national special registers XML-NTEXT, XML-NNAMESPACE, and XML-NNAMESPACE-PREFIX.
    • When the RETURNING NATIONAL phrase is specified and identifier-1 references a data item of category alphanumeric, XML document fragments are automatically converted to Unicode UTF-16 representation and returned to the processing procedure in the national special registers XML-NTEXT, XML-NNAMESPACE, and XML-NNAMESPACE-PREFIX.
    • When the RETURNING NATIONAL phrase is not specified and identifier-1 references a data item of category alphanumeric, the XML document fragments are returned to the processing procedure in the alphanumeric special registers XML-TEXT, XML-NAMESPACE, and XML-NAMESPACE-PREFIX except that: text for the ATTRIBUTE-NATIONAL-CHARACTER and CONTENT-NATIONAL-CHARACTER XML events is always returned in special register XML-NTEXT.
  4. The VALIDATING phrase specifies that the parser should validate the XML document against an XML schema while parsing it. The schema used for XML validation needs to be in its unprocessed text format..
    • If the FILE keyword is not specified, identifier-2 must reference a data item that contains the XML schema.
    • If the FILE keyword is specified, xml-schema-name-1 identifies an existing file that contains the XML schema.

    During parsing with validation, normal XML events are returned as for non-validating parsing until an exception occurs due to a validation error or other error in the document.

    When an XML document is not valid, the parser signals an XML exception and passes control to the processing procedure with special register XML-EVENT containing 'EXCEPTION' and special-register XML-CODE containing return code 24 in the high-order halfword and a reason code in the low-order halfword.

  5. The ON EXCEPTION phrase specifies imperative statements that are executed when the XML PARSE statement raises an exception condition. An exception condition occurs when the XML parser detects an error in processing the XML document. The parser first signals an exception XML event by passing control to the processing procedure with special register XML-EVENT set to contain "EXCEPTION". The parser provides a numeric error code in special register XML-CODE.

    An exception condition also occurs if the processing procedure deliberately terminates parsing by setting XML-CODE to -1 before returning to the parser from any normal XML event. In this case, the parser does not signal an EXCEPTION XML event. The following applies:

    1. If the ON EXCEPTION phrase is specified, the parser then transfers control to imperative-statement-1.
    2. If the ON EXCEPTION phrase is not specified, the NOT ON EXCEPTION phrase, if any, is ignored, and control is transferred to the end of the XML PARSE statement.
    3. If the XML processing procedure handles the exception XML event and sets XML-CODE to zero before returning control to the parser, the exception condition no longer exists.
    4. If no other unhandled exceptions occur before the termination of the parser, control is transferred to imperative-statement-2 of the NOT ON EXCEPTION phrase, if specified.
  6. The NOT ON EXCEPTION phrase specifies imperative statements that are executed when no exception condition exists at the termination of XML PARSE processing. The following applies:
    1. If an exception condition does not exist at termination of XML PARSE processing, control is transferred to imperative-statement-2 of the NOT ON EXCEPTION phrase, if specified.
    2. If the NOT ON EXCEPTION phrase is not specified, control is transferred to the end of the XML PARSE statement. In this case, ON EXCEPTION, if specified, is ignored. Special register XML-CODE contains zero after execution of the XML PARSE statement.

  7. When XMLPARSE"COMPAT" is set and when running under native COBOL, XML character entities, for example &apos;, are output as individual events. When XMLPARSE"XMLSS" is set or when running under managed COBOL, XML entities are converted to the single character in which they represent and included in the general text that surrounds them, generating a single event.

Parent topic: Statements
Related information
XML PARSE


Compiler-directing Statements

  • Source Text Manipulation
  • Editor Control
  • The BASIS Mechanism
  • The ++INCLUDE and -INC Mechanisms
  • Conditional Compilation
  • The Listing Control Statements
  • Compiler Directives Specific to Your COBOL System
Parent topic: Part 2. Program Definition


Source Text Manipulation

Source text manipulation allows you to include text from one or more COBOL source libraries in your program. COBOL source libraries are collections of source text that programmers can use in many different programs, reducing effort and promoting consistency between programs. Any suitable source text editor can be used to create the source text.

You use the COPY statement to include source text from a library in your program. The effect of the COPY statement is to insert text into the compilation group, where it is treated by the COBOL system as part of the compilation group. All occurrences of a given literal, identifier, word or group of words in the library text can be replaced with alternative text during the copy process.

ANS85 Source text manipulation also allows you to replace source text in your program. You use the REPLACE statement to replace source text. The effect of the REPLACE statement is to replace source text in your program by new text supplied in the REPLACE statement; the COBOL system treats the new text as part of the compilation group.

  • The COPY Statement
    The COPY statement incorporates text into a COBOL compilation group.
  • The REPLACE Statement
    The REPLACE statement modifies source text in a compilation group.
Parent topic: Compiler-directing Statements


The COPY Statement

The COPY statement incorporates text into a COBOL compilation group.

General Format for Format 1

General Formats for Format 2 (Hitachi syntax)

General Formats for Format 3 (Fujitsu syntax)

General Formats for Format 4 (Fujitsu syntax)

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • COPYEXT - specifies the filename extension to be used for locating copy files.
    • COPYLBR - specifies that library-names are equivalent to .lbr files.
    • COPYLIST - causes the result of a COPY statement to be included in the listing file.
    • FOLD-COPY-NAME - allows the Compiler to find a copy library member when the library name on disk and the text-name in the COPY statement do not use the same upper-case and lower-case letters for the library member name.
    • OLDCOPY - changes the handling of COPY statements to match the ANS'68 and OS/VS COBOL LANGLVL(1) rules.

Syntax Rules for All Formats

  1. The COPY statement must be preceded by a space and terminated by the separator period.
  2. A COPY statement can occur in the compilation group anywhere a character-string or a separator can occur except that a COPY statement must not occur within another COPY statement.
  3. OSVS VSC2 MF The SUPPRESS phrase is used to suppress the printing of the contents of the copy member on the source listing.
  4. ANS85 If the word COPY appears in a comment-entry or in the place where a comment entry can appear, it is considered part of the comment-entry.

    OSVS A COPY statement that appears in a comment-entry is processed.

  5. Library text must conform to the rules for COBOL reference format.

Syntax Rules for Format 1

  6. If more than one COBOL library is available while the source is passed through the COBOL system, text-name must be qualified by the library-name identifying the COBOL library in which the text associated with text-name resides.

    OSVS VSC2 MF This restriction is removed.

  7. Pseudo-text-1 must not be null, nor can it consist solely of either the character space(s) or comment lines.
  8. Pseudo-text-2 can be null.
  9. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued. However, both characters of a pseudo-text delimiter must be on the same line. (See the topic Continuation of Lines in the chapter Language Fundamentals.)
  10. Word-1 or word-2 can be any single COBOL word.
  11. Text-name defines a unique external file-name which conforms to the rules for user-defined words.

    OSVS VSC2 MF COB370 External-file-name-literal is an alphanumeric literal that conforms to the operating system rules for file-names. It can be specified with or without enclosing quotation marks.

    Text-names and unquoted external-file-name-literals are always converted to upper case.

  12. MF Library-name-literal is an alphanumeric literal that conforms either to the operating system rules for file-names or to the operating system rules for device identifiers. It can be specified with or without enclosing quotation marks.

    Library-name-literals not inside quotation marks are always converted to upper case.

  13. OSVS MF External-file-name-literal and library-name-literal, when enclosed in quotation marks, may contain the $, #, and @ characters.
  14. ISO2002 MF Partial-word-1 must consist of one text-word.
  15. ISO2002 MF Partial-word-2 must consist of zero or one text-word.
  16. ISO2002 MF Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.
  17. Library text must conform to the rules for COBOL reference format.
  18. ISO2002 MF XOPEN A concatenation expression must not be specified for external-file-name-literal, library-name-literal, literal-1 or literal-2.

Syntax Rules for Format 2 - 4

  19. word-3, word-4, word-5, word-6 or word-7 can be any single COBOL word.

General Rules for All Formats

  1. The compilation of a compilation group containing COPY statements is logically equivalent to the processing of all COPY statements before the processing of the resultant compilation group.
  2. The effect of processing a COPY statement is that the library text associated with text-name is copied into the source text, logically replacing the entire COPY statement, beginning with the reserved word COPY and ending with the punctuation character period, inclusive.
  3. If the unit identifier is not explicitly specified, the default drive is used. (The default is operating system-dependent.)

General Rules for Format 1

  4. If the REPLACING phrase is not specified, the library text is copied unchanged.

    If the REPLACING phrase is specified, the library text is copied and each properly matched occurrence of pseudo-text-1, identifier-1, literal-1, word-1 and partial-word-1 in the library text is replaced by the corresponding pseudo-text-2, identifier-2, literal-2, word-2 or partial-word-2.

  5. For purposes of matching, identifier-1, literal-1 and word-1 are treated as pseudo-text containing only identifier-1, literal-1 or word-1, respectively.
  6. The comparison operation to determine text replacement occurs in the following manner:
    1. The leftmost library text-word which is not a separator comma or a separator semicolon is the first text-word used for comparison. Any text-word or space preceding this text-word is copied into the source text. Starting with the first text-word for comparison and first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 that was specified in the REPLACING phrase, the entire REPLACING phrase operand that precedes the reserved word BY is compared to an equivalent number of contiguous library text-words.
    2. Pseudo-text-1, identifier-1, word-1, or literal-1 match the library text if, and only if, the ordered sequence of text-words that forms pseudo-text-1, identifier-1, word-1, or literal-1 is equal, character for character, to the ordered sequence of library text-words.
    3. ISO2002 MF When the LEADING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of a library text-word. When the TRAILING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of a library text-word.
    4. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the library text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.
      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.
      3. Text-words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.
      4. ISO2002 MF XOPEN Each operand and operator of a concatenation expression is a separate text-word.
    5. If no match occurs, the comparison is repeated with each next successive pseudo-text-1, identifier-1, word-1, literal-1, or pseudo-text-1, if any, in the REPLACING phrase until either a match is found or there is no next successive REPLACING operand.
    6. When all the REPLACING phrase operands have been compared and no match has occurred, the leftmost library text-word is copied into the source text. The next successive library text-word is then considered as the leftmost library text-word, and the comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1, or partial-word-1 specified in the REPLACING phrase.
    7. Whenever a match occurs between pseudo-text-1, identifier-1, word-1, or literal-1 and the library text, the corresponding pseudo-text-2, identifier-2, word-2, or literal-2 is placed into the source text.

      ISO2002 MF When a match occurs between partial-word-1 and the library text-word, the library text-word is placed into the resultant text with the matched characters either replaced by partial-word-1 or deleted when partial-word-2 consists of zero text-words.

      The library text-word immediately following the rightmost text-word that participated in the match is then considered as the leftmost text-word. The comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 specified in the REPLACING phrase.

    8. The comparison operation continues until the rightmost text-word in the library text has either participated in a match or been considered as a leftmost library text-word and participated in a complete comparison cycle.
  7. A comment line occurring in either the library text or pseudo-text-1 is interpreted, for purposes of matching, as a single space. Comment lines appearing in either pseudo-text-2 or library text are copied into the source text unchanged.
  8. The text produced as a result of the complete processing of a COPY statement must not contain a COPY statement.

    VSC2 This text can contain a COPY statement provided neither this contained COPY nor the already expanded COPY includes the REPLACING phrase. However, recursive COPY statements (where a library-text is referred to by a COPY statement within it) are not allowed.

    MF COPY statements may be nested in this way to any level. One of the COPY statements in this structure may include the REPLACING phrase, and the replacements specified are in effect for all subsidiary COPY statements.

  9. The syntactic correctness of the library text cannot be independently determined.

    ANS85 Except for COPY statements,

    the syntactic correctness of the entire COBOL compilation group cannot be determined until all COPY statements have been completely processed.

  10. MF If the REPLACING phrase is specified, the library text must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.
  11. Each text-word copied from the library but not replaced, or only partially replaced, is copied so as to start in the same area of the line in the resultant source text as it begins in the line within the library. However, if a text-word copied from the library begins in area A but follows another text-word, which also begins in area A of the same line, and if replacement of a preceding text-word in the line by replacement text of greater length occurs, the following text-word begins in area B if it cannot begin in area A. Each text-word in pseudo-text-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as it appears in pseudo-text-2. Each identifier-2, literal-2, and word-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as the leftmost library text-word that participated in the match would appear if it had not been replaced.

    If additional lines are introduced into the source text as a result of a COPY statement, each text-word introduced appears on a debugging line if the copy statement begins on a debugging line, or if the text-word being introduced appears on a debugging line in library text. When a text-word specified in the BY phrase is introduced, it appears on a debugging line if the first library text-word being replaced is specified on a debugging line. Except in the preceding cases, only those text-words that are specified on debugging lines where the debugging line is within pseudo-text-2 appear on debugging lines in the resultant source text. If any literal specified as literal-2 or within pseudo-text-2 or library text is of too great a length to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced which contain the remainder of the literal. If replacement requires that the continued literal be continued on a debugging line, the compilation group is in error.

  12. For purposes of compilation, text-words after replacement are placed in the source text according to the rules for reference format as described in the section Reference Format in the chapter Language Fundamentals.
  13. OSVS The OLDCOPY Compiler directive causes the entire entry to be replaced by the information identified by text-name, except that the data-name preceding the COPY statement replaces the corresponding data-name in the text-name.
  14. ANS85 If certain conventions are followed in library text, parts of names, for example the prefix portion of data-names, can be changed with the REPLACING phrase. To use this type of "partial word replacement" the portion of the words to be modified must be enclosed in one of the following ways:
    1. In pairs of left and right parentheses. For example, (ABC)
    2. Within colons. For example :XYZ:
    Note: The LEADING and TRAILING phrases can also be used for partial word replacement. The LEADING and TRAILING phrases are supported by the MF dialect and ISO2002, however, they are not included in the ANSI '85 COBOL standard.

General Rules for Format 2

  15. If the PREFIXING phrase is specified, the library text is copied and each of the following data names are prefixed by word-3:
    • data name, condition name and literal name immediately after the level number (except for FILLER)
    • data name right after REDEFINES (except for 01 level)
    • data name right after RENAMES and the qualifier
    • index of OCCURS, data name for KEY IS and the qualifier
    • address name
  16. If the SUFFIXING phrase is specified, the same rule applies as PREFIXING apart from the data names are suffixed by word-4.
Restriction: The replaced text is not shown in list files and in the debugger.

General Rules for Format 3

  17. If the JOINING phrase is specified with PREFIX, the library text is copied and each of the following data names are prefixed by word-5 followed by a single hyphen, "-":
    • data name, condition name and literal name immediately after the level number (except FILLER)
    • data name right after REDEFINES (except 01 level)
  18. If the JOINING phrase is specified with SUFFIX, the same rule applies as PREFIX apart from the data names are suffixed by a single hyphen character, "-", followed by word-5.
Restriction: The replaced text is not shown in list files and in the debugger.

General Rules for Format 4

  19. The phrase DISJOINING word-6 JOINING word-7 AS PREFIX is equivalent to REPLACING LEADING word-6 BY word-7.
  20. The phrase DISJOINING word-6 JOINING word-7 AS SUFFIX is equivalent to REPLACING TRAILING word-6 BY word-7.

Examples

Examples of the following are provided in the chapter Examples in your Language Reference - Additional Topics:

  • Using the OLDCOPY Compiler directive to achieve ANSI'68 or LANGLVL(1) behavior. See the topic COPY (ANSI'68 or LANGLVL(1) Variation)
  • Using the COPY statement with partial word replacement supported by ANSI'85 rules. See the section Example Using ANSI'85 with Special Characters in the topic COPY (Partial Word Replacement)
  • Using the COPY statement with partial word replacement supported by ISO2000 rules. See the section Example Using ISO2002 and MF Dialects in the topic COPY (Partial Word Replacement)
Parent topic: Source Text Manipulation
Related information
Preprocessor Response Codes
COPY (ANSI'68 or LANGLVL(1) Variation)
COPY (Partial Word Replacement)
Continuation of Lines
Reference Format


The REPLACE Statement

The REPLACE statement modifies source text in a compilation group.

General Formats for Format 1

General Formats for Format 2

Syntax Rules

  1. A REPLACE statement can be specified anywhere in source text or in library text that a character-string or a separator, other than the closing delimiter of a literal, can appear. It must be preceded by a separator space except when it is the first statement in a compilation group.
  2. A REPLACE statement must be terminated by a separator period.
  3. Pseudo-text-1 must contain one or more text-words.
  4. Pseudo-text-2 can contain zero, one, or more text-words.
  5. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued.
  6. A text-word within pseudo-text must be between 1 and 322 characters long.
  7. Pseudo-text-1 must not consist entirely of a separator comma or a separator semicolon.
  8. If the word REPLACE appears in a comment-entry or in the place where a comment-entry can appear, it is considered part of the comment-entry.
  9. ISO2002 MF Partial-word-1 must consist of one text-word.
  10. ISO2002 MF Partial-word-2 must consist of zero or one text-word.
  11. ISO2002 MF Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.

General Rules

  1. Pseudo-text-1 specifies the source text to be replaced by pseudo-text-2.
  2. ISO2002 MF Partial-word-1 specifies the text to be replaced by partial-word-2.
  3. The Format 2 REPLACE statement specifies that any text replacement currently in effect is discontinued.
  4. A given occurrence of the REPLACE statement is in effect from the point at which it is specified until the next occurrence of the REPLACE statement or the end of the compilation unit, respectively.
  5. Any REPLACE statements contained in a source unit are processed after the processing of any COPY statements contained in that source unit.
  6. The text produced as a result of the processing of a REPLACE statement must contain neither a COPY statement nor a REPLACE statement.
  7. The comparison operation to determine text replacement begins with the text immediately following the REPLACE statement and occurs in the following manner:
    1. Starting with the leftmost source text-word and the first pseudo-text-1 or partial-word-1, pseudo-text-1 or partial-word-1 is compared to an equivalent number of contiguous source text-words.
    2. Pseudo-text-1 matches the source text if, and only if, the order sequence of text-words that forms pseudo-text-1 is equal, character for character, to the ordered sequence of source text-words.

      ISO2002 MF When the LEADING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of that source text-word. When the TRAILING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of that source text-word.

    3. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the source text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.
      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.
      3. text-words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.
      4. ISO2002 MF XOPEN Each operand and operator of a concatenation expression is a separate text-word.
    4. If no match occurs, the comparison is repeated with each next successive occurrence of pseudo-text-1 or partial-word-1, until either a match is found or there is no next successive occurrence of pseudo-text-1 or partial-word-1.
    5. When all occurrences of pseudo-text-1 or partial-word-1 have been compared and no match has occurred, the next successive source text-word is then considered as the leftmost source text-word, and the comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.
    6. Whenever a match occurs between pseudo-text-1 and the source text, the corresponding pseudo-text-2 replaces the matched text in the source text.

      ISO2002 MF When a match occurs between partial-word-1 and the source text-word, the matched characters of that source text-word are either replaced by partial-word-2 or deleted when partial-word-2 consists of zero text-words.

      The source text-word immediately following the rightmost text-word that participated in the match is then considered as the leftmost source text-word. The comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.

    7. The comparison operation continues until the rightmost text-word in the source text which is within the scope of the REPLACE statement has either participated in a match or been considered as a leftmost source text-word and participated in a complete comparison cycle.
  8. Comment lines or blank lines occurring in either the source text or pseudo-text-1 are ignored for purposes of matching; and the sequence of text-words in the source text and in pseudo-text-1 is determined by the rules for reference format. See the topic Reference Format Representation in the chapter Language Fundamentals. Comment lines or blank lines in pseudo-text-2 are placed into the resultant source text unchanged whenever pseudo-text-2 is placed into the source text as a result of text replacement. A comment line or blank line in source text is not placed into the resultant source text if that comment line or blank line appears within the sequence of text-words that match pseudo-text-1.
  9. Only after all COPY and REPLACE statements have been completely processed, can the syntactical correctness of the rest of the source code be determined.
  10. text-words inserted into the source text as a result of processing a REPLACE statement are placed in the source text according to the rules for reference format. See the topic Reference Format in the chapter Language Fundamentals. When inserting text-words of pseudo-text-2 into the source text, additional spaces can be introduced only between text-words where a space (including the assumed space between source lines) already exists.
  11. If additional lines are introduced into the source text as a result of the processing of REPLACE statements, the indicator area of the introduced lines contains the same character as the line on which the text being replaced begins, unless that line contains a hyphen, in which case the introduced line contains a space.

    If any literal within pseudo-text-2 is of a length too great to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced to contain the remainder of the literal. If replacement requires the continued literal to be continued on a debugging line, the compilation unit is in error.

  12. MF The source text for which a REPLACE statement is in effect must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.
Parent topic: Source Text Manipulation
Related information
Preprocessor Response Codes
Reference Format Representation
Reference Format


Editor Control

  • $REGION Statement
    A block of code surrounded by $REGION and $END-REGION statements can be folded or expanded in the editor.
Parent topic: Compiler-directing Statements


$REGION Statement

A block of code surrounded by $REGION and $END-REGION statements can be folded or expanded in the editor.

General Format

Syntax Rules

  1. $REGION must end with $END-REGION.
  2. $REGION blocks can be nested.
  3. $REGION and $IF statements must not overlap.
Parent topic: Editor Control


The BASIS Mechanism

The BASIS mechanism provides support to allow an entire COBOL source file to be non-interactively edited, temporarily, and the result of this edit to be submitted to your COBOL system. The COBOL source file referenced as the source of the temporary edit (the "subject program") remains unchanged, and there is no record of the result of the edit other than the files output by your COBOL system (listing, and so on). The resulting code file cannot be animated since there is no source file for reference.

The BASIS mechanism is valid for fixed-format source only.

The program submitted to your COBOL system consists of two files: an edit control file (containing the BASIS statement and editing information) and the COBOL source file (the subject program as described above).

Three special statements are associated with the BASIS mechanism:

  1. BASIS
  2. INSERT
  3. DELETE.

These special statements are not part of the COBOL language. Each one must, in its entirety, be contained on a single line and must be in upper case.

If you use INSERT or DELETE statements to modify a COBOL source program specified in a BASIS statement, the sequence field of the COBOL source program must contain numeric sequence numbers in ascending order.

General Rules

  1. To use the BASIS mechanism, you must specify the BASIS preprocessor directive: PREPROCESS(BASIS) or P(BASIS).
  2. A DELETE statement wholly within area B of the source-program line, not followed by a valid subject-sequence or subject-sequence-range, is treated as a COBOL DELETE statement by your COBOL system.
  3. Within the BASIS mechanism DELETE statement, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.
  4. Within the edit control file, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.
  • The BASIS Statement
    The BASIS statement identifies that the program (the edit control file and the COBOL source file) is to be submitted to your COBOL system under the BASIS mechanism rules.
  • The DELETE Statement - BASIS Control
    The DELETE statement (under the BASIS mechanism) identifies lines of the COBOL source file to be ignored by your COBOL system. Any COBOL statements that follow the DELETE statement (up to the next BASIS mechanism INSERT or DELETE statement in the edit control file) are included.
  • The INSERT Statement - BASIS Control
    The INSERT statement (under the BASIS mechanism) lists lines of COBOL source to be included in the program submitted to your COBOL system.
Parent topic: Compiler-directing Statements


The BASIS Statement

The BASIS statement identifies that the program (the edit control file and the COBOL source file) is to be submitted to your COBOL system under the BASIS mechanism rules.

General Format

Syntax Rules

  1. The BASIS statement must be the first line of the edit control file.
  2. The BASIS reserved word can commence anywhere between columns 1 and 66 of the statement line.
  3. Sequence numbers can be included anywhere in columns 1 through 6 of the statement and must be followed by a space.
  4. Text-name defines a unique external file-name which conforms to the rules for user-defined words. Lower case is translated into upper case. External-file-name-literal is an alphanumeric literal enclosed in quotation marks, which conforms to the operating system rules for file-names.

General Rules

  1. Text-name or external-file-name-literal determines the COBOL source file to be edited by the control file.
  2. The editing of the COBOL source file is determined by the INSERT and DELETE statements in the edit control file.
Parent topic: The BASIS Mechanism
Related information
The DELETE Statement - BASIS Control
The INSERT Statement - BASIS Control


The DELETE Statement - BASIS Control

The DELETE statement (under the BASIS mechanism) identifies lines of the COBOL source file to be ignored by your COBOL system. Any COBOL statements that follow the DELETE statement (up to the next BASIS mechanism INSERT or DELETE statement in the edit control file) are included.

General Format

Syntax Rules

  1. The DELETE reserved word can commence anywhere between columns 1 and 66 of the statement line.
  2. Sequence numbers can be included anywhere in columns 1 through 6 of the statement and must be followed by a space.
  3. Subject-sequence-1, subject-sequence-2, and so on, must be 6-digit positive integers (following the rules for integer numeric-literals).
  4. Subject-sequence-range-1, subject-sequence-range-2, and so on, must consist of two subject-sequence numbers (as above) separated by a hyphen (-).
  5. The comma between subject-sequences and/or subject-sequence ranges is mandatory.

General Rules

  1. Subject-sequence-1, subject-sequence-2, and so on, refer to sequence numbers of those statements within the COBOL source file which are to be ignored by your COBOL system.
  2. Subject-sequence-range-1, subject-sequence-range-2, and so on, refer to inclusive ranges of statement sequence numbers within the COBOL source file, all of which statements are to be ignored when the intermediate code is produced.
  3. Any COBOL statements following the DELETE statement in the edit control file up to the next BASIS mechanism DELETE or INSERT statement are included in the source submitted to your COBOL system. These COBOL source statements are inserted in place of the last statement omitted by this BASIS mechanism DELETE statement.
Parent topic: The BASIS Mechanism
Related information
The BASIS Statement
The INSERT Statement - BASIS Control


The INSERT Statement - BASIS Control

The INSERT statement (under the BASIS mechanism) lists lines of COBOL source to be included in the program submitted to your COBOL system.

General Format

Syntax Rules

  1. The INSERT reserved word can commence anywhere between columns 1 and 66 of the statement line.
  2. Subject-sequence must be a positive numeric integer (following the rules for integer numeric literals).

General Rules

  1. Subject-sequence refers to that statement within the COBOL source file after which the COBOL statement(s) is to be included.
  2. All the COBOL statements following the INSERT statement in the edit control file up to the next BASIS mechanism DELETE or INSERT statement are included in the source submitted to your COBOL system. At least one COBOL statement must immediately follow the BASIS mechanism INSERT statement.
Parent topic: The BASIS Mechanism
Related information
The BASIS Statement
The DELETE Statement - BASIS Control


The ++INCLUDE and -INC Mechanisms

The ++INCLUDE and -INC mechanisms provide an IBM-mainframe compatible means whereby a COBOL program source file or portion of source code can be included in a file to be compiled.

  • The -INC Statement
    The -INC statement is used to include all of the data records of one source file in another source file at compilation time.
  • The ++INCLUDE Statement
    The ++INCLUDE statement is used to include all of the data records of one source file in another source file at compilation time.
Parent topic: Compiler-directing Statements


The -INC Statement

The -INC statement is used to include all of the data records of one source file in another source file at compilation time.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • LIBRARIAN - enables the use of -INC syntax.

Syntax Rules

  1. -INC must begin in column 1 and be followed by one or more spaces.
  2. Text-name defines a unique external file-name which conforms to the rules for user-defined words.
  3. This special statement is not part of the COBOL language. It must, in its entirety, be contained on a single line and must be in upper case.

General Rules

  1. Text-name determines the COBOL source file to be included at this specific place in the source code.
  2. Any other text appearing on the line is treated as a comment.
Parent topic: The ++INCLUDE and -INC Mechanisms


The ++INCLUDE Statement

The ++INCLUDE statement is used to include all of the data records of one source file in another source file at compilation time.

General Format

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
    • PANVALET - enables the use of ++INCLUDE syntax.

Syntax Rules

  1. ++INCLUDE must begin in column 8, must be in upper case and must be followed by one or more spaces.
  2. Text-name defines a unique external file-name which conforms to the rules for user-defined words.
  3. This special statement is not part of the COBOL language. It must, in its entirety, be contained on a single line and must be in upper case.

General Rules

  1. Text-name determines the COBOL source file to be included at this place in the source code.
  2. Any other text appearing on the line is treated as a comment.
Parent topic: The ++INCLUDE and -INC Mechanisms


Conditional Compilation

The COBOL system provides two mechanisms for selectively compiling part or all of your COBOL source code.

  • Micro Focus Conditional Compilation
  • ISO2002 Conditional Compilation
Parent topic: Compiler-directing Statements


Micro Focus Conditional Compilation

To benefit fully from the advantages of Micro Focus conditional compilation, the use of level 78 (see the topic Level Number) and the CONSTANT Compiler directive is recommended. Micro Focus conditional compilation is controlled by $IF, $ELSE, $END constructs, which behave in a similar way to the COBOL IF construct. Micro Focus conditional compilation also supplies the $DISPLAY statement, which can be used to display a message during compilation or include a version number in the object file.

Syntax Rules

  1. Micro Focus conditional compilation statements are indicated by a dollar ($) in column 7 in fixed-format source, or column 1 in free-format source of the COBOL source line followed by one of the key words IF, DISPLAY, ELSE, END.
  2. Micro Focus conditional compilation should not be used to split a COBOL character string; that is, continuation lines should not be split by conditional compilation controls.
  3. You cannot use include Boolean data items in Micro Focus conditional compilation statements.
  • $DISPLAY Statement
    The $DISPLAY statement displays a message on the standard output device during compilation or includes a version number in the object file.
  • $ELSE Statement
    The $ELSE statement is used in conjunction with the $IF statement to control Micro Focus conditional compilation.
  • $END Statement
    The $END statement is used in conjunction with the $IF statement to control Micro Focus conditional compilation.
  • $IF Statement
    A $IF statement provides the means whereby selected parts of the source text are not included in the compilation.
Parent topic: Conditional Compilation
Related information
Level Number


$DISPLAY Statement (Conditional Compilation)

$DISPLAY Statement

The $DISPLAY statement displays a message on the standard output device during compilation or includes a version number in the object file.

General Format for Format 1

General Format for Format 2

Syntax Rules

  1. The whole $DISPLAY statement must appear on a single line.

General Rules for Format 1

  1. Text-data is displayed on the standard output device during compilation.

General Rules for Format 2

  2. Version-number is the content of the entire source line following the "=", excluding leading and trailing spaces.
  3. The character string formed by concatenating "@(#)", version-number and a null character (binary zero) is included in the object file, no matter which type of object file is created. If version-number begins with the characters "@(#)", the system does not concatenate these characters when forming the character string.
    Note:
    • Version-number can be any text string, however, it is intended to contain a version number for which a pattern matching tool, such as the UNIX sccs "what" utility, can search the object file.
    • Unreachable procedural code is eliminated by the Compiler during the optimization phase and the literals used only in that code are discarded. The practice of including version numbers in Procedure Division statements by using the following technique does not work:
       filename-what section. move "@(#)filename %I%>" to what-string perform filename-what
    • Since the $DISPLAY statement can be specified anywhere in the source code, each text-name (copybook) can have its own version number.
    • Older compilers treat a format 2 $DISPLAY statement as a format 1 $DISPLAY statement.
Parent topic: Micro Focus Conditional Compilation


$ELSE Statement

The $ELSE statement is used in conjunction with the $IF statement to control Micro Focus conditional compilation.

General Format

Syntax Rules

  1. The whole statement must appear on a single line.

General Rules

  1. The most recent $IF condition is reversed. If the now active $IF condition is true, the source lines following the $ELSE statement are processed. If the $IF condition is false, COBOL source lines are ignored until the next Micro Focus conditional compilation line is encountered.
Parent topic: Micro Focus Conditional Compilation


$END Statement

The $END statement is used in conjunction with the $IF statement to control Micro Focus conditional compilation.

General Format

Syntax Rules

  1. The whole statement must appear on a single line.

General Rules

  1. The innermost $IF statement is terminated. The now active $IF condition is considered. If the active condition is true the source lines following the $END are processed. If the condition is false, COBOL source lines are ignored until the next Micro Focus conditional compilation line is encountered.
Parent topic: Micro Focus Conditional Compilation


$IF Statement

A $IF statement provides the means whereby selected parts of the source text are not included in the compilation.

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

Syntax Rules

  1. Constant-name-1 is defined by a level 78 entry or a CONSTANT Compiler directive.
  2. If literal-1 is numeric, it must be zero or a positive integer.
  3. Directive-setting is specified in the same format as it is given in a $SET statement and may be preceded by NO. However, the format used in the $IF statement differs from the format used in the $SET statement as follows:
    1. No spaces are permitted between the NO and directive name
    2. Hyphens in the directive must be specified exactly
    3. If the directive has a parameter it may be omitted
  4. Only directives used in the syntax-check phase and produced in the directive settings list (see compiler directive SETTINGS) may be specified for directive-setting
  5. The whole statement must appear on a single line.
  6. $IF can be nested within another $IF.

General Rules

  1. Constant-name-2 is DEFINED if it is the subject of a level 78 entry or a CONSTANT Compiler directive, otherwise it is NOT DEFINED.
  2. Directive-setting SET evaluates true if the given setting matches the actual directive setting. If a parameter is specified then it must also match.
  3. The comparison between Directive-setting and the actual directive setting is not case sensitive.
  4. If the condition evaluates true the source lines following the $IF statement are processed. If the condition evaluates false, COBOL source lines are ignored until the next Micro Focus conditional compilation line is encountered.

Examples

  1. An example of using Micro Focus conditional compilation is provided in the topic $IF Statement (Micro Focus Conditional Compilation).
Parent topic: Micro Focus Conditional Compilation
Related information
$IF Statement (Conditional Compilation)


ISO2002 Conditional Compilation

Note: In this section, the compiler directing statements DEFINE, EVALUATE, and IF are referenced using the ISO2002 terminology of directives. When referring to the DEFINE Compiler option, it will be explicitly referenced as such.

ISO2002 conditional compilation uses the DEFINE Compiler option and/or the DEFINE directive to define compilation variables. These compilation variables can then be used in the IF and EVALUATE directives to include or omit selected lines of source code, enabling one to maintain a single source code that is capable of creating multiple variants of the same program.

ISO2002 conditional compilation directives are processed according to the following rules:

  • If a directive appears before a COPY or REPLACE statement, it is processed before the COPY or REPLACE statement is processed. This means that you can use ISO2002 conditional compilation to exclude COPY and REPLACE statements from a program.
  • The REPLACE statements or the REPLACING phrase of COPY statement has no effect on any of the conditional compilation directives.
  • Directives can appear in copybooks.
  • The DEFINE Directive
  • The EVALUATE Directive
  • The IF Directive
  • Appendices - ISO2002 Conditional Compilation
Parent topic: Conditional Compilation


The DEFINE Directive

The DEFINE directive defines or undefines a compilation variable that is used with the conditional compilation directives DEFINE, EVALUATE, and IF. A compilation variable is treated as a symbolic reference to the literal value it currently represents.

Note: In this section, the compiler directing statements DEFINE, EVALUATE, and IF are referenced using the ISO2002 terminology of directives. When referring to the DEFINE Compiler option, it will be explicitly referenced as such.

General Format

Syntax Rules

  1. The DEFINE directive must begin on a new line, in either area A or B, and must be specified entirely on one line.
  2. literal-1 must be one of the following:
    • An alphanumeric literal, specified as a regular alphanumeric literal (for example, 'abcd'), or as a hexadecimal literal (for example, x'F1F2F3'). National literals, DBCS literals, and null-terminated alphanumeric literals (Z literals) are not supported.
    • An integer literal.
    • A Boolean literal of either B'0' or B'1'.
  3. arithmetic-expression-1 must be formed in accordance with the arithmetic expression rules as described in Appendix E - Compile-Time Arithmetic Expressions.
  4. If the DEFINE directive does not specify the OFF or OVERRIDE phrase, one of the following must be true:
    • compilation-variable-name-1 has not previously been declared in the same compilation group.
    • Any previous DEFINE directive that refers to compilation-variable-name-1 must have been specified with the OFF phrase.
    • Any previous DEFINE directive that refers to compilation-variable-name-1 must have specified the same value for it.

General Rules

  5. A DEFINE directive is not processed if it is subject of another conditional compilation and the result is that it is omitted.
  6. In the text that follows a DEFINE directive that defines compilation-variable-name-1 and does not include the OFF phrase, compilation-variable-name-1 can be used in a conditional compilation directive wherever a literal of the category associated with the name is permitted, including in a defined condition and a Boolean condition.
  7. In the text that follows a DEFINE directive that specifies compilation-variable-name-1 with the OFF phrase, compilation-variable-name-1 can be used only in a defined condition, unless compilation-variable-name-1 is redefined in a subsequent DEFINE directive that does not specify the OFF phrase.
  8. When the OVERRIDE phrase is specified, compilation-variable-name-1 is unconditionally set to reference the value of the specified operand.
  9. If the AS PARAMETER phrase is specified, the value referenced by compilation-variable-name-1 is obtained from a DEFINE Compiler option (see DEFINE) for compilation-variable-name-1, if the option is in effect. If no DEFINE Compiler option is in effect for compilation-variable-name-1, compilation-variable-name-1 is not defined.
  10. If arithmetic-expression-1 is specified, it is evaluated according to Appendix E - Compile-Time Arithmetic Expressions, and compilation-variable-name-1 references the resultant value.
  11. If literal-1 is specified, compilation-variable-name-1 references literal-1.
Parent topic: ISO2002 Conditional Compilation
Related reference
The EVALUATE Directive
The IF Directive
DEFINE
Appendix E - Compile-time Arithmetic Expressions


The EVALUATE Directive

The EVALUATE directive provides a way of evaluating which source lines to include in a compilation group.

Note: In this section, the compiler directing statements DEFINE, EVALUATE, and IF are referenced using the ISO2002 terminology of directives. When referring to the DEFINE Compiler option, it will be explicitly referenced as such.

General Format 1

General Format 2

General Format 3

Syntax Rules for All Formats

  1. Throughout the rules descriptions:
    • operand-1 refers to literal-1 or arithmetic-expression-1 in format 1, and to the TRUE or FALSE keyword in formats 2 and 3.
    • operand-2 refers to literal-2 or arithmetic-expression-2 in format 1, and to constant-conditional-expression-1 in formats 2 and 3.
    • operand-3 refers to literal-3 or arithmetic-expression-3 in format 1.
  2. The keywords >>EVALUATE. >>WHEN, >>WHEN OTHER, and >>END-EVALUATE must begin on a new line in either area A or area B, and must be specified entirely on that line.
  3. The identifiers text-1 and text-2:
    • Must begin on a new line, and can consist of multiple lines.
    • May be any kind of source lines, including compiler directives.
    • May also include COPY statements.
    • The phrases of a given EVALUATE directive must be specified all in the same library text or all in source text. For purposes of this rule, text-1 and text-2 are not considered phrases of the EVALUATE directive.
  4. A nested EVALUATE directive specified in text-1 or text-2 is considered a new EVALUATE directive.

Syntax Rules for Format 1

  5. All operands of the EVALUATE directive must be of the same category. (Arithmetic expressions are considered of category numeric.)
  6. The phrases THROUGH and THRU are equivalent.
  7. If the THROUGH or THRU phrase is specified, all selected items must be of category numeric.
  8. arithmetic-expression-1, arithmetic-expression-2, and arithmetic-expression-3 must be constructed as per the rules as stated in Appendix E - Compile-Time Arithmetic Expressions.

Syntax Rules for Format 2 and Format 3

  9. constant-conditional-expression-1 must be constructed as per the rules as stated in Appendix B - Constant Conditional Expressions.

General Rules for All Formats

  10. text-1 and text-2 do not form part of the EVALUATE directive line.
  11. text-1 and text-2 that are in the first true branch of the EVALUATE statement are subject to matching and replacing rules, as per COPY and REPLACE statements.
  12. If the statement reaches the END-EVALUATE keyword without any WHEN phrase evaluating true (or false for EVALUATE FALSE constructs), or without encountering a WHEN OTHER phrase, all lines of text-1 associated with WHEN phrases are omitted from the result.

General Rules for Format 1

  13. The comparison of the selection subject to the values specified in each WHEN phrase is as follows:
    • If the THROUGH phrase is not specified, a TRUE result is returned if the selection subject is equal to operand-2.
    • When the THROUGH phrase is specified, a TRUE result is returned if the selection subject is greater than or equal to operand-2, and less than or equal to operand-3.
    • If a WHEN phrase evaluates TRUE, the lines of text-1 associated with that WHEN phrase are included in the resultant text. All other text-1 and text-2 lines in the EVALUATE directive are omitted.
    • If no WHEN phrase evaluates TRUE, all lines of text-2 associated with the WHEN OTHER phrase, if specified, are included in the resultant text. All text-1 lines in the EVALUATE directive are omitted.
    • If literal-1 is alphanumeric, a character-by-character comparison for equality, based on the binary representation of each character's encoding, is used. They are not equal if the literals are of unequal length.

General Rules for Format 2

  14. For each WHEN phrase in turn, constant-conditional-expression-1 is evaluated according to the rules as stated in Appendix B - Constant Conditional Expressions.
  15. If a WHEN phrase evaluates to TRUE, the lines of text-1 associated with that WHEN phrase are included in the resultant text. All other text-1 and text-2 lines in the EVALUATE directive are omitted.
  16. If no WHEN phrase evaluates TRUE, all lines of text-2 associated with the WHEN OTHER phrase, if specified, are included in the resultant text. All text-1 lines in the EVALUATE directive are omitted.

General Rules for Format 3

  17. For each WHEN phrase in turn, constant-conditional-expression-1 is evaluated according to the rules as stated in Appendix B - Constant Conditional Expressions.
  18. If a WHEN phrase evaluates to FALSE, the lines of text-1 associated with that WHEN phrase are included in the resultant text. All other text-1 and text-2 lines in the EVALUATE directive are omitted.
  19. If no WHEN phrase evaluates FALSE, all lines of text-2 associated with the WHEN OTHER phrase, if specified, are included in the resultant text. All text-1 lines in the EVALUATE directive are omitted.
Parent topic: ISO2002 Conditional Compilation
Related reference
The DEFINE Directive
The IF Directive
Appendix B - Constant Conditional Expressions
Appendix E - Compile-time Arithmetic Expressions


The IF Directive

The IF directive provides a one- or two-way conditional compilation.

Note: In this section, the compiler directing statements DEFINE, EVALUATE, and IF are referenced using the ISO2002 terminology of directives. When referring to the DEFINE Compiler option, it will be explicitly referenced as such.

General Format

Syntax Rules

  1. The keywords >>IF, >>ELSE, and >>END-IF must begin on a new line in either area A or area B, and must be specified entirely on that line.
  2. The identifiers text-1 and text-2:
    • Must begin on a new line, and may consist of multiple lines.
    • May be any kind of source lines, including Compiler directives.
    • Can include COPY statements.
    • The phrases of a given IF directive must be specified all in the same library text or all in source text. For purposes of this rule, text-1 and text-2 are not considered phrases of the IF directive. A nested IF directive specified in text-1 or text-2 is considered a new IF directive.

General Rules

  3. text-1 and text-2 are not part of the IF compiler directive line.
  4. The text in the branch that evaluates true is subject to matching and replacing rules of the COPY and REPLACE statements.
  5. If constant-conditional-expression-1 evaluates to TRUE, all the lines of text-1 are included in the resultant text. All lines of text-2 are omitted.
  6. If constant-conditional-expression-1 evaluates to FALSE, all the lines of text-2 are included in the resultant text. All lines of text-1 are omitted.
Parent topic: ISO2002 Conditional Compilation
Related reference
The DEFINE Directive
The EVALUATE Directive


Appendices - ISO2002 Conditional Compilation

  • Appendix A - Examples of Conditional Compilation
  • Appendix B - Constant Conditional Expressions
  • Appendix C - Defined Conditions
  • Appendix D - Boolean Conditions
  • Appendix E - Compile-time Arithmetic Expressions
Parent topic: ISO2002 Conditional Compilation


Appendix A - Examples of Conditional Compilation

The following excerpts show some examples of conditional compilation in effect.

Example 1:

This example is dependent on the DEFINE Compiler option setting the 64BIT variable (DEFINE 64BIT (TRUE)). If it is set, the INIT64 program is called:

...
   >>DEFINE 64BIT AS PARAMETER
...
   >>IF 64BIT IS DEFINED
       CALL "INIT64"
   >>ELSE
       CALL "INIT32"
   >>END-IF
...

Example 2:

In this example, the variables are defined inline, and so do not need to be defined using the DEFINE Compiler option. This excerpt demonstrates that you can use the OVERRIDE keyword to change the value of a defined variable:

...
   >>DEFINE VAR AS 10
...
   >>DEFINE VAR AS VAR - 2 OVERRIDE
   >>IF VAR = 10
     DISPLAY "FAIL"
   >>ELSE
     DISPLAY "PASS"
   >>END-IF
...

Example 3:

Again, the variable is defined inline, and shows the EVALUATE directive, which produces "PASS". If you used the EVALUATE FALSE construct, the result would be reversed (that is, display "FAIL"):

...
   >>DEFINE VAR2 as 10 * 2
...
   >>EVALUATE TRUE

   >>WHEN VAR2 > 12
       DISPLAY "PASS"
   >>WHEN VAR2 < 12
       DISPLAY "FAIL"
   >>END-EVALUATE
...

Example 4:

This example uses two variables within the EVALUATE directive, executing the clause indicated below.

...
   >>DEFINE VAR1 AS 3
   >>DEFINE VAR2 AS 1
...
   >>EVALUATE VAR1
   >>WHEN VAR2+1
       COMPUTE X = X + (X * 0.20)
   >>WHEN VAR2+2
       COMPUTE X = X + (X * 0.40)  *> this clause is executed
   >>WHEN VAR2+3
       COMPUTE X = X + (X * 0.45)
   >>WHEN OTHER
       COMPUTE X = X
   >>END-EVALUATE
DISPLAY X.
...
Parent topic: Appendices - ISO2002 Conditional Compilation
Related reference
DEFINE


Appendix B - Constant Conditional Expressions

A constant conditional expression is an expression used in the ISO2002 conditional compilation directives, DEFINE, EVALUATE, and IF, and determines the text that is included in the resultant program.
Note: In this context, literals also refer to compilation variables, which means that you can use compilation variables in constant conditional expressions.
A constant conditional expression can be one of the following:
  • A relation condition in which both operands are literals or arithmetic expressions that contain only literal terms. The condition must follow the rules for relation conditions, with the following additions:
    • All operands must be of the same category. (An arithmetic expression is of the category numeric.)
    • If non-numeric literals are specified, the relational operator shall be "IS EQUAL TO", "IS NOT EQUAL TO", "IS =", "IS NOT =", or "IS <>".
  • A defined condition.
  • A Boolean condition.
  • A complex condition formed by combining the above forms of simple conditions into complex conditions by using AND, OR, and NOT. Abbreviated combined relation conditions cannot be specified.
Parent topic: Appendices - ISO2002 Conditional Compilation


Appendix C - Defined Conditions

A defined condition expression tests if a compilation variable is currently defined.

General Format

Syntax Rules

  1. An IS DEFINED condition evaluates as TRUE if compilation-variable-name-1 is defined.
  2. If compilation-variable-1 was defined via a DEFINE Compiler option, but preceding the defined condition in the program there is neither a corresponding DEFINE directive with the AS PARAMETER phrase nor a DEFINE directive without the OFF phrase for the compilation variable, then the defined condition for the compilation variable evaluates to FALSE.
  3. An IS NOT DEFINED condition evaluates as TRUE if compilation-variable-name-1 is not defined.
  4. If the most recent definition of compilation-variable-name-1 is via a DEFINE directive with the OFF phrase, it is considered to be not defined.
Parent topic: Appendices - ISO2002 Conditional Compilation
Related reference
DEFINE


Appendix D - Boolean Conditions

Note: In this context, literals also refer to compilation variables, which means that you can use compilation variables in constant conditional expressions.

A Boolean condition determines if a Boolean literal is true or false.

General Format

Syntax Rules

  1. boolean-literal-1 evaluates to TRUE if its value is B'1', and FALSE if its value is B'0'.
  2. NOT boolean-literal-1 evaluates to FALSE if its value is B'1', and TRUE if its value is B'0'.
Parent topic: Appendices - ISO2002 Conditional Compilation


Appendix E - Compile-time Arithmetic Expressions

Note: In this context, literals also refer to compilation variables, which means that you can use compilation variables in constant conditional expressions.

Within the DEFINE and EVALUATE directives, you can specify a compile-time arithmetic expression. Also, you can include compile-time arithmetic expressions in and as part of a constant conditional expression, such which can form part of the IF directive or WHEN phrase of the EVALUATE directive.

A compile-time arithmetic expression follows the usual arithmetic expression rules, with the following exceptions:

  • The exponentiation operator is not permitted.
  • All operands must be integer numeric literals or arithmetic expressions in which all operands are integer numeric literals.
  • The expression must be constructed in such a way that a division by zero does not occur.
Parent topic: Appendices - ISO2002 Conditional Compilation


The Listing Control Statements

The listing control statements provide a control for producing output file listings during the compile process.

Three statements are associated with the listing control statements:

  1. EJECT
  2. SKIP1, SKIP2 AND SKIP3
  3. VSC2 MF TITLE.
  • The EJECT Statement
    The EJECT statement tells your COBOL system to print the next line of source code at the top of the next page.
  • The SKIP1, SKIP2 and SKIP3 Statements
    The SKIP1, SKIP2 and SKIP3 statements control the vertical spacing of the source code listing produced by your COBOL system. They specify the lines to be skipped in the source code listing.
  • The TITLE Statement
    The TITLE statement tells your COBOL system what title to print on the first line of all subsequent pages of the listing.
Parent topic: Compiler-directing Statements


The EJECT Statement

The EJECT statement tells your COBOL system to print the next line of source code at the top of the next page.

General Format

Syntax Rules

  1. EJECT may begin either in area A or in area B, must be the only statement on the line and may optionally be followed by a period.

General Rules

  1. The EJECT statement itself is not printed.
Parent topic: The Listing Control Statements


The SKIP1, SKIP2 and SKIP3 Statements

The SKIP1, SKIP2 and SKIP3 statements control the vertical spacing of the source code listing produced by your COBOL system. They specify the lines to be skipped in the source code listing.

General Format

Syntax Rules

  1. The statement can begin in area A or in area B, must be the only statement on the line

    VSC2 MF and can optionally be followed by a period.

General Rules

  1. SKIP1 tells your COBOL system to skip one line (double spacing). SKIP2 tells your COBOL system to skip two lines (triple spacing). SKIP3 tells your COBOL system to skip three lines (quadruple spacing).
  2. The SKIP statement itself is not printed.
Parent topic: The Listing Control Statements


The TITLE Statement

The TITLE statement tells your COBOL system what title to print on the first line of all subsequent pages of the listing.

General Format

Syntax Rules

  1. Literal-1 must be nonnumeric and can be followed by a period. It cannot be a figurative constant.
  2. The word TITLE can begin either in Area A or Area B and must be the only statement on the line.
  3. The TITLE statement can appear anywhere in the compilation group.

General Rules

  1. Literal-1 is used as a title on all subsequent pages of the listing. The default title, which is used until a TITLE directive is encountered, identifies your COBOL system and its current release level.
  2. The chosen or default title occupies the left-hand side of the first line of each page. The remainder of the line gives the date and time the intermediate code is produced and a page number.
  3. A second title line is also output containing the name of the main source file and of the current text-name (copybook).
  4. The TITLE statement causes an immediate new page.
  5. The TITLE statement itself is not printed.
Parent topic: The Listing Control Statements


Compiler Directives Specific to Your COBOL System

Your COBOL system provides a large number of Compiler directives. For details of these, see your COBOL system documentation.

Parent topic: Compiler-directing Statements


Examples

This chapter provides annotated examples of some of the source code clauses and statements explained in detail elswhere in the COBOL Language Reference. For the complete syntax and general rules for any item included in this chapter, please see the appropriate reference manual entry.

The sample code extracts provided within this chapter are not intended to be complete COBOL programs but rather sufficient excerpts to illustrate specific coding tasks. A number of complete COBOL source programs are provided with your COBOL system in machine readable format. If you look in the on-disk document, Products Contents Checklist and search for the word "sample", you will see which sample programs are provided with your COBOL system.

Note: No boxes, bubbles or other dialect designations are included in this chapter. See relevant reference entries and your COBOL system documentation for information on what syntax and semantic differences may exist for the COBOL options used in this chapter.

The examples in this chapter are presented in alphabetic order according to the phrase, clause, or statement which they are primarily demonstrating. Of course, within most of these examples other COBOL syntax may also appear. These examples are not divided according to the division or module in which they appear.

  • Call Prototypes
  • Calling and Setting a Procedure-Pointer
  • Call Returning a Dynamically Allocated Data Area from a Subprogram
  • Compilation Group
  • COPY (ANSI'68 or LANGLVL(1) Variation)
  • COPY (Partial Word Replacement)
  • CRT STATUS Clause of the SPECIAL-NAMES Paragraph
  • $IF Statement Example (Micro Focus Conditional Compilation)
  • INSPECT Statement (Tallying, Replacing, and Converting)
  • NEXT Phrase of CONSTANT-NAMES
  • SEARCH statement
  • SORT a File Using Input and Output Procedures
  • SORT Table Entries
  • Split Key
  • Typedef - User Defined USAGE or Structure
Parent topic: Part 2. Program Definition


Call Prototypes

The following program demonstrates the use of call prototypes. Assume that you have defined the following call prototype:

 identification division.
 program-id.  callsub is external.
 environment division.
 configuration section.
 special-names.
     call-convention 3 is some-language.
 data division.
 linkage section.
 01  x1     pic 9(4) comp-5.
 01  x2     pic xx.
 01  x3     pic 9(8).
 01  x7     pic x.
 procedure division some-language using by value     x1
                                        by reference x2
                                        by reference x3.
 entry "callsub2" using x2 delimited
                        any
                        x1.
 entry "printf" using x7 delimited
                       any repeated.
 end program callsub.

If you had the following "real" source coded in the same source file as the previous call prototype:

 identification division.
 program-id.  prog-1.
 data division.
 working-storage section.
 01  x1      pic 9(4) comp-5.
 01  x2.
     05      pic 9(4) comp-5.
     05      pic x(20).
 01  x3      pic 9(8).
 01  x4      pic 9(9) comp-5.
 01  x5      pic x.
 01  x6      pic x(20).
 procedure division.
 mainline.
     call "callsub" using x1 x2 x3

the preceding CALL statement would be equivalent to using:

                          by value x1
                          by reference x2
                          by reference x3

The following examples show the results of different call statements:

Example 1

     call "callsub" using x1 x2

The preceding CALL statement would generate an error since the number of parameters is wrong.

Example 2

     call other-language "callsub" using x1 x2 x3

The preceding CALL statement would generate an error since the call-convention is wrong.

Example 3

     call "callsub" using by reference x1 x2 x3

The preceding CALL statement would generate an error since x1 should be passed by value.

Example 4

     call "callsub" using 99 x2 x3

The preceding CALL statement would be equivalent to a call using:

                          by value 99 size 2
                          by reference x2
                          by reference x3

Example 5

     call "callsub" using x4 x2 x3

The preceding CALL statement would generate an error since x4 has the wrong length.

Example 6

     call "callsub" using x1 x5 x3

The preceding CALL statement would generate an error since x5 is too small.

Example 7

     call "printf" using "A long %1\n" x4

In the preceding CALL statement x4 is a parameter covered by ANY REPEATED.

Example 8

     call "callsub2" using "Hello" x2 x1

The preceding CALL statement is equivalent to:

     move "Hello" & x"00" to temp
     call "callsub2" using temp x2 x1

Example 9

     call "callsub2" using x6 x2 x1

The preceding CALL statement is equivalent to:

     move x6 to temp
     move x"00" to temp (21:1)
     call "callsub2" using temp x2 x1

Example 10

     call "callsub2" using x6 x2 x1 x4

The preceding CALL statement would generate an error as there are too many parameters being passed.

Example of Call Prototype Usage

If a COBOL application programmer wants to call a C function from within his COBOL application the following need to be done:

  • The C function parameters need to be defined within the COBOL application. This means the mapping of C data types to COBOL data types.
  • The actual call to the C function must contain the correct number of parameters and each parameter must be of the correct type.
  • Any strings of text that need to passed to a C function will need to be converted into a null terminated C string.

The use of COBOL typedefs and COBOL call prototypes may be used to automate the above process. This includes the automatic conversion of text strings into null terminated C strings. The following is an example of how all this may be done.

Suppose I have a C function that I want to call. Let us call it my_C_function. The following is a segment of C code that shows this function:

sample.c
-------------------------------------------------------------

/*** start of source module sample.c ***/

/*------------------------*/
/*  Include Header Files  */
/*------------------------*/
#include <stdio.h>
#include "sample.h"

/*-------------------*/
/*  Sample Function  */
/*-------------------*/
int my_C_function (parm_1, parm_2, parm_3)
num_type parm_1;
unsigned char *parm_2;
complex_type *parm_3;
{
    int rtn_code = 0;

    printf("  my-C_function: invoked\n");

    printf("  my-C_function: parm_1 = %d\n", parm_1);

    if (parm_2 == NULL) {
        printf("  my_C_function: parm_2 = IS NULL\n", parm_2);
        rtn_code = -1;
    } else {
        printf("  my_C_function: parm_2 = %s\n", parm_2);
    }

    if (parm_3 == NULL ) {
        printf("  my_C_function: parm_3 = IS NULL\n", parm_3);
        rtn_code = -1;
    } else {
        printf("  my_C_function: parm_3\n");
        printf("                (num1) = %d\n", parm_3->num1);
        printf("                (num2) = %d\n", parm_3->num2);
    }

    printf("    my_C_function: completed\n");
    return(rtn_code);
}

/*** end of source module sample.c ***/
-------------------------------------------------------------

In this example we have three parameters for the C function:

  • A typdef'ed value
  • A C string
  • A constructed data type

There is a header file that contains the C typedef definitions and also the C function prototype. It is as follows:

sample.h

-------------------------------------------------------------

/*** start of source module sample.h ***/

#ifndef     SAMPLE
#define     SAMPLE

/*------------*/
/*  Typedefs  */
/*------------*/
typedef int num_type;
typedef struct {
        int num1;
        long num2;
} complex_type;

/*----------------------*/
/*  Function Prototype  */
/*----------------------*/
extern int my_C_function (
        num_type parm_1,
        unsigned char *parm_2,
        complex_type *parm_3
);
#endif      /* SAMPLE */
/*** end of source module sample.h ***/
-------------------------------------------------------------

The first step is to convert the C typedefs and function prototypes into COBOL typedefs and COBOL call prototypes.

sample.cpy
-------------------------------------------------------------
 program-id. "c_typedefs" is external.
 77  char                   pic s9(2)  comp-5 is typedef.
 77  uns-char               pic  9(2)  comp-5 is typedef.
 77  short                  pic s9(4)  comp-5 is typedef.
 77  uns-short              pic  9(4)  comp-5 is typedef.
 77  int                    pic s9(9)  comp-5 is typedef.
 77  uns-int                pic  9(9)  comp-5 is typedef.
 77  long                   pic s9(9)  comp-5 is typedef.
 77  uns-long               pic  9(9)  comp-5 is typedef.
 77  d-l-float                         comp-2 is typedef.
 77  d-float                           comp-2 is typedef.
 77  float                             comp-1 is typedef.
 77  proc-pointer           procedure-pointer is typedef.
 77  data-pointer                     pointer is typedef.
 77  void                   pic  9(2)  comp-5 is typedef.
 01  num-type          is typedef       usage int.
 01 complex-type       is typedef.
     02 num1              usage int.
     02 num2              usage long.
 entry "my_C_function" using
         by value      int
         by reference  uns-char
         by reference  complex-type
     returning         int
     .
 end program "c-typedefs".
-------------------------------------------------------------

In the above we have:

  • Level 77's that map all the basic C data types to COBOL typedefs.
  • Level 01's that are typedefs that match the C typedefs in the header file
  • An entry statement that acts as a COBOL call prototype for the C function

The following changes should be made to this file with a text editor.

  • Remove the level 77 data items that are not needed
  • Change the uns-char mapping to map to "pic x" instead of a numeric field. If this is not done then an attempt to pass a PIC X field as a parameter would be rejected as not conforming to the prototype parameter specification.
  • Add the keyword delimited beside uns-char in the call prototype. This has the result of converting the TEXT string passed as a parameter into a null terminated C string at run time for the caller.

The result of the above editing is the following:

sample.cpy
-------------------------------------------------------------
 program-id. "c_typedefs" is external.

 77  uns-char               pic x             is typedef.
 77  int                    pic s9(9)  comp-5 is typedef.
 77  long                   pic s9(9)  comp-5 is typedef.
 77  data-pointer                     pointer is typedef.

 01 num-type           is typedef       usage int.
 01 complex-type       is typedef.
     02 num1              usage int.
     02 num2              usage long.

 entry "my_C_function" using
         by value      int
         by reference  uns-char delimited
         by reference  complex-type
     returning         int
     .

 end program "c_typedefs".
-------------------------------------------------------------

The following is an example of the COBOL application that makes a call to the my_C_function function.

-------------------------------------------------------------
 copy 'sample.cpy'.

 identification division.
 program-id.  prog.
 working-storage section.
 01  ws-parm-1                       usage num-type.
 01  ws-parm-2                       pic x(50)
      value "This is a PIC X string from COBOL".
 01  ws-parm-3                       usage complex-type.
 01  ws-return-code                  usage int.

 procedure division.
 main-code section.
     display "prog: started"

     move 123     to ws-parm-1
     move 1       to num1 IN ws-parm-3
     move 2       to num2 IN ws-parm -3

     display " "
     display "prog: call 'my_C_function' with ALL parameters"
     call "my_C_function" using ws-parm-1
                                ws-parm-2
                                ws-parm-3
                          returning ws-return-code
     end-call
     display "prog: 'my_C_function' return code = "
             ws-return-code

     display " "
     display "prog: call 'my_C_function' with NULL parameters"
     call "my_C_function" using 0
                                OMITTED
                                OMITTED
                          returning ws-return-code
     end-call
     display "prog: 'my_C_function' return code = "
             ws-return-code

     display " "
     display "prog: completed"
     exit program
     stop run.
-------------------------------------------------------------

In the above example the following has been coded:

  • The copybook sample.cpy has been included as the first statement in the source. This is the copybook that contains the COBOL typedefs and COBOL call prototypes.

    Typedefs and prototypes are defined as complete external programs. They are placed before real source programs in a similar way to multi-program source files.

  • The parameters for the C function have been defined in the Working-Storage Section using the COBOL typedefs.
  • In this example two calls are made to the C function. The following should be noted from this:
    • BY REFERENCE/VALUE has not been specified. The correct default is picked up from the prototype.
    • The prototype will ensure that the correct number of parameters of the correct type has been specified. If not, then the checker will flag an error at compile time.
    • In the second call the special word OMITTED has been specified to pass a BY REFERENCE parameter as a NULL instead of a parameter value.

      This is required because it is not possible to just go BY VALUE 0 which would be flagged as invalid because BY REFERENCE is mandatory for that parameter. OMITTED will pass a NULL instead of a pointer to the parameter being passed to the C function.

The following is the output that results when the specific example above is run:

-------------------------------------------------------------
%prog
prog: started

prog: call 'my_C_function' with ALL parameters
      my_C_function: invoked
      my_C_function: parm_1 = 123
      my_C_function: parm_2 = This is a COBOL PIC X string
      my_C_function: parm_3
                     (num1) = 1
                     (num2) = 2
      my_C_function: completed
prog: 'my_C_function' return code = +0000000000

prog: call 'my_C_function' with NULL parameters
      my_C_function: invoked
      my_C_function: parm_1 = 0
      my_C_function: parm_2 = IS NULL
      my_C_function: parm_3 = IS NULL
      my_C_function: completed

prog: 'my_C_function' return code = -0000000001

prog: completed
%
-------------------------------------------------------------
Parent topic: Examples
Related information
Examples


Calling and Setting a Procedure-Pointer

*> Calling program:

 program-id. startup.
 working-storage section.
 01 start-point  usage procedure-pointer.
 procedure division.
     set start-point to entry "menu"
     call "controller" using start-point
     display "End of run"
     stop run.

 entry "illegal"
*> Recursive calls invalid without local-storage section.
     stop run.
 end program startup.

*> Called program:

 program-id. controller.
 working-storage section.
 01 next-option  pic x.
 linkage section.
 01 current-proc usage procedure-pointer.
 procedure division using current-proc.
     perform until current-proc = NULL
         call current-proc returning next-option
*>       Note program-id must be called before any entry point
         evaluate next-option
          when "a"    set current-proc to entry "sub1"
          when other  set current-proc to NULL
         end-evaluate
     end-perform.
     exit program.
 end program controller.

 program-id. menu.
 working-storage section.
 01 exit-option  pic x.
 procedure division.
     display "In menu"
     move "a" to exit-option
     exit program returning exit-option.
*>    Note that the maximum size of returned value is 4 bytes

 entry "sub1"
     display "In sub1"
     exit program returning 1.
Parent topic: Examples
Related information
Examples


Call Returning a Dynamically Allocated Data Area from a Subprogram

* Calling program:

 program-id. calling.
 working-storage section.
 01 call-size   pic x(4) comp-5 value 64.
 linkage section.
 01 call-area   pic x.
 procedure division.
     call "sub2" using call-size
              returning address of call-area
     if address of call-area not = null
         display "Contents of new area: " call-area(1:call-size)
     end-if
     stop run.
end program calling.

* Called program:

 program-id. sub2.
 working-storage section.
 01 sub-pointer usage pointer.
 linkage section.
 01 link-size   pic x(4) comp-5.
 01 link-area   pic x.
 procedure division using link-size.
     call "CBL_ALLOC_MEM" using sub-pointer
                                by value link-size
                                         0 size is 4
     if return-code = 0
         set address of link-area to sub-pointer
         move "Hello!" to link-area(1:call-size)
     else
         set sub-pointer to null
     end-if
     exit program returning sub-pointer.
Parent topic: Examples
Related information
Examples


Compilation Group

A compilation group is everything that is submitted to a compiler at one time. A compilation group contains a series of source units. A source element is a term used to refer to a source unit excluding any nested source units. For more information on compilation groups and source units, see the topic Compilation Groups.

The following compilation group is an example of some of these concepts.

  FUNCTION-ID. factorial.
  DATA DIVISION.
  LINKAGE SECTION.
  01  parm1 BINARY-LONG.
  01  fact  BINARY-LONG.
  PROCEDURE DIVISION USING parm1 RETURNING fact.
     IF parm1 = 0
        COMPUTE fact = 1
     ELSE
        COMPUTE fact = parm1 * factorial (parm1 - 1)
     END-IF
     EXIT FUNCTION.
  END FUNCTION factorial.
  PROGRAM-ID. program-1.
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  REPOSITORY.
      FUNCTION factorial.
  DATA DIVISION.
  WORKING-STORAGE SECTION.
  01  i  BINARY-LONG.
  PROCEDURE DIVISION.
      COMPUTE i = factorial (10)
  ...
  END PROGRAM program-1.
  PROGRAM-ID. program-2.
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  REPOSITORY.
      FUNCTION-ID. factorial.
  DATA DIVISION.
  WORKING-STORAGE SECTION.
  01  i  BINARY-LONG.
  01  global-item PIC X(30) GLOBAL VALUE "The factorial is: "
  PROCEDURE DIVISION.
      COMPUTE i = factorial (11)
      CALL display-it USING i
      ...

      PROGRAM-ID. display-it.
      LINKAGE SECTION.
      01 n BINARY-LONG.
      PROCEDURE DIVISION USING n.
          DISPLAY global-item, n
      END PROGRAM display-it.

  END PROGRAM program-2.

This compilation group consists of three compilation units: the function factorial, the program program-1, and the program program-2. Each compilation unit is also a source unit. The source unit program-2 contains another source unit, the program display-it. Each of the four source units is also a source element. The difference between the source elements and the source units is that the source element program-2 does not include the nested program.

From each of the 3 compilation units, a separate runtime module is created by the compiler. Typically, a linkage editor is used to combine runtime modules, from one or multiple compilations, into a run unit.

The runtime module for the function factorial contains one runtime element, the function factorial. The runtime module for the program program-1 contains one runtime element. The runtime module for program-2 contains two runtime elements, one for program-2 and one for display-it.

This example illustrates how the user-defined function factorial can override the intrinsic function factorial. The compiler would use the factorial intrinsic function if FUNCTION factorial INTRINSIC were specified in the REPOSITORY paragraph. However, since the INTRINSIC phrase is not specified in the example, the user-defined function is the function that is activated.

To compile these programs, use the REPOSITORY directive. For example, use:

cobol program-1.cbl nognt repository(update on)
Parent topic: Examples
Related information
Compilation Groups
Examples


COPY (ANSI'68 or LANGLVL(1) Variation)

The COPY statement's behavior is slightly modified when the OLDCOPY Compiler directive is set. This modification changes it from acting as defined by the ANSI'74 and ANSI'85 standards to behaving as the old ANSI'68 standard defined. This modified behavior is also consistent with how OS/VS COBOL and DOS/VS COBOL behave when the LANGLVL(1) compiler option is used on an IBM mainframe.

When the OLDCOPY Compiler directive is set and a copy member is intended to include an entire 01 level data description, both the COPY statement and the copied description should be defined with an 01 level item. However, only the data name from the copying statement will be available to the rest of the COBOL program. For example:

Source file Code.

 01   PRODUCT-CODE COPY COPYPROD.

Copybook Code "COPYPROD":

 01   PROD-CD.
     05   ITEM-NAME      PIC X(30).
     05   ITEM-NUMBER    PIC X(5).

Resulting COBOL Code:

 01   PRODUCT-CODE.
     05   ITEM-NAME      PIC X(30).
     05   ITEM-NUMBER    PIC X(5).
Parent topic: Examples
Related information
Examples


COPY (Partial Word Replacement)

Example Using ANSI'85 with Special Characters

The COPY statement in an ANSI'85 conforming compiler can be used to modify parts of words in the copy member source. It should be carefully noted that this syntax only works when certain conventions (and special characters) are used. When using this technique, the programmer must set up their copy members with the modifiable sections pre-established. In fact, once this technique is used, the copy members will NOT compile cleanly when not replaced. For example:

Source file Code:

     copy Payroll
          replacing ==(TAG)== by ==Payroll==.

Copybook Code:

 01  (TAG).
     05 (TAG)-Week      pic s99.
     05 (TAG)-Gross-Pay pic s9(5)v99.
     05 (TAG)-Hours     pic s9(3)
                          occurs 1 to 52 times
                           depending on (TAG)-Week of (TAG).

Is treated as if it were coded as:

 01  Payroll.
     05 Payroll-Week      pic s99.
     05 Payroll-Gross-Pay pic s9(5)v99.
     05 Payroll-Hours     pic s9(3)
                            occurs 1 to 52 times
                              depending on Payroll-Week of Payroll.

Example Using ISO 2002 and Micro Focus Dialects

Both the ISO 2002 and the Micro Focus dialects support partial word replacement as specified in the ISO 2002 COBOL standard. As above, the modifiable sections must be pre-established, however, the use of special characters is not required and the copy members will compile cleanly even when no replacement is done to them.

The above example could equivalently be coded as follows:

     copy Payroll
          replacing leading ==TAG== by ==Payroll==.

Copybook Code:

 01  TAG.
     05 TAG-Week      pic s99.
     05 TAG-Gross-Pay pic s9(5)v99.
     05 TAG-Hours     pic s9(3)
                          occurs 1 to 52 times
                           depending on TAG-Week of TAG.

Is treated exactly as the code is treated in the ANSI'85 example.

Parent topic: Examples
Related information
Examples


CRT STATUS Clause of the SPECIAL-NAMES Paragraph

The CRT STATUS clause of the SPECIAL-NAMES paragraph provides a data item composed as follows:

  • Status Key 1 - indicates the conditon that caused the termination of the ACCEPT operation
  • Status Key 2 - further distinguishes between ACCEPT termination actions
  • Status Key 3 - contains the raw keyboard code for the key that terminated the ACCEPT operation.

The following examples show how the CRT status key should be coded and referenced.

************************************************************
*                                                          *
*   The following shows how the special-names paragraph    *
*   sets up both a cursor position field and a CRT status  *
*   key field.                                             *
*                                                          *
************************************************************

 special names.
     cursor is cursor-position
     crt status is crt-status.
       ...

 working-storage section.
 01 cursor-position                    pic 9(4).

************************************************************
*   The following group item defines the CRT status key    *
*   field and establishes certain 78-level condition-names *
*   associated with key fields.                            *
*                                                          *
*   Programs using these definitions should be compiled    *
*   with NOIBMCOMP and MF to function as expected.         *
*                                                          *
************************************************************

 01  crt-status.
     05 crt-status-1                   pic 9.
        88  terminate-key                  value 0.
        88  function-key                   value 1.
        88  adis-key                       value 2.
        88  status-1-error                 value 9.
    05  crt-status-2                   pic 99 comp-x.
        88  esc-key                        value 0.
        88  f1-key                         value 1.
        88  enter-key                      value 1.
        88  fun-key-num-user               values 0 thru 127.
        88  fun-key-num-system             values 0 thru 26.
    05  crt-status-3                   pic 99 comp-x.
        88 raw-key-code                    values 0 thru 255.
       ...
 procedure-division.
      ...
************************************************************
*                                                          *
*   The following shows the procedural code that would     *
*   evaluate the CRT status keys and direct processing     *
*   accordingly.                                           *
*                                                          *
************************************************************

     evaluate terminate-key also function-key also adis-key
      when true  also any  also any
         if esc-key
             evaluate crt-status-3
              when 0  perform raw-key-0
              when 1  perform raw-key-1
              when 2  perform raw-key-2
              when 3  perform raw-key-3
               ...
             end-evaluate
        else
            perform logic-for-terminator-key
        end-if

      when any  also true  also any
         evaluate crt-status-2
          when 1  perform user-function-1
          when 2  perform user-function-2
          when 3  perform user-function-3
          when 4  perform user-function-4
          when 5  perform user-function-5
           ...
         end-evaluate

      when any  also any  also true
         evaluate crt-status-2
          when 1 perform sys-function-1
          when 2 perform sys-function-2
          when 3 perform sys-function-3
          when 4 perform sys-function-4
          when 5 perform sys-function-5
           ...
         end-evaluate
     end-evaluate
Parent topic: Examples
Related information
Examples


$IF Statement Example (Micro Focus Conditional Compilation)

The $IF statement can be used to "conditionally compile" portions of your source code. In the following example, if the program is compiled with the directives:

/MF /CONSTANT WHERE "PC"

then at compile time, the word "NO" will be displayed and the object code will include an EVALUATE rather than a GO TO statement. If the MF directive were not set, "Not MF dialect" would also be displayed.

$if WHERE = "PC"
     evaluate test-field
       when 5  perform test-a
     end-evaluate
$if OTHER-CONSTANT defined
$display Program compiled with other-constant set
$else
$display NO
$end
$else
     go to test-a test-b depending on test-field
$end
$if NOMF set
$display Not MF dialect
$end
Parent topic: Examples


INSPECT Statement (Tallying, Replacing, and Converting)

The INSPECT statement can be used to tally the number of occurrences of specific character strings, to replace characters by other characters, or to convert from one set of characters to another. Setting the conditons for these inspections can be quite complex. The following examples demonstrate some of the variations and uses of this verb.

In each of the following examples of the INSPECT statement, COUNT-n is assumed to be zero immediately prior to execution of the statement. The results shown for each example, except the last, are the result of executing the two successive INSPECT statements shown above them.

Example 1:

     inspect item tallying
         count-0 for all "AB", all "D"
         count-1 for all "BC"
         count-2 for leading "EF"
         count-3 for leading "B"
         count-4 for characters;

     inspect item replacing
         all "AB" by "XY", "D" by "X"
         all "BC" by "VW"
         leading "EF" by "TU"
         leading "B" by "S"
         first "G" by "R"
         first "G" by "P"
         characters by "Z"
Initial Value of ITEM | COUNT-0 | COUNT-1 | COUNT-2 | COUNT-3 | COUNT-4 | Final Value of ITEM
EFABDBCGABEFGG | 3 | 1 | 1 | 0 | 5 | TUXYXVWRXYZZPZ
BABABC | 2 | 0 | 0 | 1 | 1 | SXYXYZ
BBBC | 0 | 1 | 0 | 2 | 0 | SSVW

Example 2:

     inspect item tallying
         count-0 for characters
         count-1 for all "A";

     inspect item replacing
         characters by "Z"
         all "A" by "X"
Intial Value of ITEM | COUNT-0 | COUNT-1 | Final Value of ITEM
BBB | 3 | 0 | ZZZ
ABA | 3 | 0 | ZZZ

Example 3:

     inspect item tallying
         count-0 for all "AB" before "BC"
         count-1 for leading "B" after "D"
         count-2 for characters after "A" before "C"

     inspect item replacing
         all "AB" by "XY" before "BC"
         leading "B" by "W" after "D"
         first "E" by "V" after "D"
         characters by "Z" after "A" before "C"
Initial Value of ITEM | COUNT-0 | COUNT-1 | COUNT-2 | Final Value of ITEM
BBEABDABABBCABEE | 3 | 0 | 2 | BBEXYZXYXYZCABVE
ADDDDC | 0 | 0 | 4 | AZZZZC
ADDDDA | 0 | 0 | 5 | AZZZZZ
CDDDDC | 0 | 0 | 0 | CDDDDC
BDBBBDB | 0 | 3 | 0 | BDWWWDB

Example 4:

     inspect item tallying
         count-0 for all "AB" after "BA" before "BC";

     inspect item replacing
         all "AB" by "XY" after "BA" before "BC"
Initial Value of Item | COUNT-0 | Final Value of Item
ABABABABC | 1 | ABABXYABC

Example 5:

     inspect item converting
  "ABCD" to "XYZX" after quote before "#".

The above INSPECT is equivalent to the following INSPECT:

     inspect item replacing
         all "A" by "X" after quote before "#"
         all "B" by "Y" after quote before "#"
         all "C" by "Z" after quote before "#"
         all "D" by "X" after quote before "#".
Initial Value of ITEM | Final Value of ITEM
AC"AEBDFBCD#AB"D | AC"XEYXFYZX#AB"D
Parent topic: Examples
Related information
Examples


NEXT Phrase of CONSTANT-NAMES

The NEXT phrase of the constant-name format of a VALUE clause always points to the offset at which the next byte of storage occurs after the previous data declaration. For example, given the following:

 01  x1             pic x(10).
 01  x2 redefines x1    pic x.
     78  next-offset    value next.
 01  x3             pic xx.

the value in next-offset will be the location of the second byte of x1 and not the starting location of x3.

This also can cause confusion with OCCURS clauses. For example, given the following:

 01  group-item.
     05  tabl occurs 10 times.
             78  offset-a   value next.
         10 elem            pic x.
             78  offset-b   value next.
     05  after-tabl     pic x(02).

offset-a will point to the offset at the start of the first occurrence of elem while offset-b will point to the starting location of the second occurrence of table element elem and not to the starting location of after-tabl. If you wanted to get the starting location of after-tabl, you should recode your source as follows:

 01  group-item.
     05  dummy-item     pic x(10).
          78 offset-c            value next.
     05  tabl redefines dummy-item
               occurs 10 times.
          78 offset-a     value next.
         10 elem            pic x.
             78 offset-b     value next.
     05  after-tabl     pic x (02).

In this example, offset-c will point to the starting offset of after-tabl.

Parent topic: Examples
Related information
Examples


SEARCH statement

There are two types of SEARCH statements.

The first type, a serial search, starts with an element determined by the setting of the associated index. To search the entire table, the index must be set to one.

The second type is a binary search. It ignores the initial setting of the associated index and searches the entire table.

In both formats

  • the programmer specifies the conditions that a table element must satisfy to terminate the search successfully
  • the WHEN phrase can be used to specify an action to be taken when an element is found that does satisfy these conditions
  • the AT END phrase can be used to specify an action to be taken if no element satisfies these conditions

The following data description is used in both examples of the SEARCH statement. The binary search requires that the KEY phrase be specified in the OCCURS clause, the serial search does not require this, but does allow it.

 working-storage section.
 01 states.
   03 state-abbr pic x(2) occurs 50 ascending key state-abbr indexed by i.
 01 state-code pic x(2).

The two coding examples are equivalent. They illustrate the difference between the serial and the binary search. In both examples, the user enters a two-character state abbreviation and the SEARCH statement is used to determine whether the entered abbreviation matches any of the valid abbreviations listed in the table. If the abbreviation is invalid, another one must be entered. A CONTINUE statement is coded at the location where you would process a valid state abbreviation, if additional processing beyond the validation were desired.

Serial Search

 enter-state.
     accept state-code
     set i to 1
     search state-abbr
      at end display "invalid state code, please reenter"
         go to enter-state
      when state-code = state-abbr (i)
         continue
     end-search
     stop run.

Binary Search

 enter-state.
     accept state-code
     search all state-abbr
      at end display "invalid state code, please reenter"
             go to enter-state
      when state-code = state-abbr (i)
         continue
     end-search
     stop run.

The differences in these two examples of the SEARCH statement are

  • the keyword ALL in the second example indicates that a binary search is to be used
  • the example of the serial search initializes the associated index with a SET statement
  • before a binary search is executed, the elements of the table must be ordered according to the specified keys. (The section SORT Table Entries shows an example of this.)
Parent topic: Examples
Related information
Examples
SORT Table Entries


SORT a File Using Input and Output Procedures

The SORT statement can be used to sort the records in a file. Note that SORT procedures should not be invoked by multiple threads simultaneously. The following program takes the names of the input and output files from the command line. RELEASE and RETURN statements are used in the input and output procedures, which input records, sort the records, and then output a sorted file.

$SET ANS85
 select ifile assign to ipf
     organization is line sequential
     file status is ipstat.

 select sfile assign to "temp.dat".

 select ofile assign to opf
     organization is line sequential.

 fd ifile.
 01 irec     pic x(80).
 fd ofile.
 01 orec     pic x(80).
 sd sfile.
 01 srec     pic x(80).

 working-storage section.
 01 ipstat.
   03 iskey1 pic x.
   03 iskey2 pic x.
 01 ipf  pic x(20).
 01 opf  pic x(20).
 01 ext  pic x(20).
 01 clin     pic x(132).
 01 len  pic 9(2) comp-x.
 01 a    pic 9(2) comp-x value 0.
 procedure division.
     accept clin from command-line
     unstring clin delimited by space into ipf, opf, ext
     if ext not = space
         display "too many arguments"
     end-if.
     sort sfile on ascending srec
      input procedure sortin
      output procedure sortout

     stop run.

 sortin section.
     open input ifile
     read ifile
     perform until ipstat not = "00"
         move irec to srec
         release srec
         read ifile
     end-perform
     close ifile.
 sortout section.
     return sfile at end go to sortout-exit
     display srec
     go to sortout.
 sortout-exit.
     display "Done".
Parent topic: Examples
Related information
Examples


SORT Table Entries

A table sort using KEYS in OCCURS clause for sequencing:

 working-storage section.
 01 group-item.
     05   tabl   occurs 10 times
                     ascending elem-item2
                     descending elem-item1.
          10 elem-item1 pic x.
          10 elem-item2 pic x.
     . . .
 procedure division.
     . . .
     sort tabl.
     if tabl (1) . . .

This is a simple sort in which the table is sorted in ascending order using the key definitions in the OCCURS clause of data item Tabl to determine the sequence, that is Elem-Item2 would be the major key (ascending) and Elem-Item1 would be the secondary key (descending).

A table sort using the entire element for sequencing:

 working-storage section.
 01 group-item.
     05 tabl occurs 10 times
         10 elem-item1 pic x.
         10 elem-item2 pic x.
     . . .
 procedure division.
     . . .
     sort tabl ascending.
     if tabl (1) ...

This is a simple sort in which the table is sorted in ascending order using each entire element of the table to determine the sequence.

A table sort with specified items for sequencing:

 working-storage section.
 01 group-item.
     05  tabl    occurs 10 times
                      ascending elem-item3
                      descending elem-item1.
         10 elem-item1 pic x.
         10 elem-item2 pic x.
         10 elem-item3 pic x.
     . . .
 procedure division.
     . . .
     sort tabl descending elem-item2 elem-item3
     if tabl (1) ...

This is a sort in which the table is sorted based on specified key data items. The major key would be Elem-Item2, even though it was not specified as a KEY in the OCCURS clause. The secondary key would be Elem-Item3. It would be treated as a DESCENDING key for this sort because the DESCENDING (which is transitive across KEY data items) specified in the SORT statement would take precedence over the ASCENDING specified in the OCCURS clause.

A table sort for a nested table:

 working-storage section.
 01 group-item.
     05  tabl1   occurs 10 times
                     indexed by t1-ind t2-ind.
         10  tabl2 occur 5 times.
             15 group1.
                 20 elem-item1 pic x.
             15 group2.
                 20 elem-item1 pic 9.
     . . .
 procedure division.
     . . .
     set t1-ind to 3
     sort tabl2 descending elem-item1 of group2
     if group1 (3 1) ...

This sorts only the third instance of Tabl2, that is Tabl2(3). It uses the qualified data-item, Elem-Item1 of Group2 as its key. In normal Procedure Division references, Elem-Item1 of Group2 would require two levels of subscripting/indexing while in this reference it has none. (Similarly, Tabl2 normally requires one level of subscripting, but cannot be subscripted as data-name-2 in the SORT statement. Instead it uses the value of T1-Ind for determining which instance is to be sorted.)

Parent topic: Examples
Related information
Examples


Split Key

If a program contained the following definition:

 01 rec.
     03 forename     pic X(10).
     03 personnel-no pic X(4).
     03 surname      pic X(15).

the syntax:

     record key is fullname =
  surname forename

would cause the COBOL system to treat fullname as though it were an explicitly defined group item consisting of:

     03 surname      pic X(15).
     03 forename     pic X(10).
Parent topic: Examples
Related information
Examples


Typedef - User Defined USAGE or Structure

The Compiler supports the following data descriptions:

 01 struct-1        TYPEDEF.
    05  part-1  pic x (20).
    05  part-2  pic x(10).
 01 USHORT  pic 9 (4)   comp-5 typedef.

which defines struct-1 and USHORT to be new usages that can be used as in the following:

 01  a.
     05  b  struct-1.
     05  x  USHORT.

which would be interpreted as if it had been coded as:

 01  a.
     05  b.
         10  part-1 pic x(20).
         10  part-2     pic x(10).
     05  x              pic 9(4) comp-5.
Parent topic: Examples
Related information
Examples


Part 3. Additional Topics

  • XML Syntax Extensions
  • Report Writer
  • Debug Module
  • Segmentation
  • Double-Byte Character Set Support
  • Micro Focus Extensions for Double-Byte Character Support
  • Micro Focus OO COBOL Extensions
  • Additional Dialect Support
Parent topic: COBOL Language Reference


XML Syntax Extensions

Your COBOL development system supports the creation of relationships between COBOL data structures and element definitions in XML schemas. Do this using COBOL XML syntax extensions, which allow you to code references to XML structures right into your COBOL definitions. These XML structures are used to input and output information in an XML format.

  • XML File Status Codes
  • XML Preprocessor Restrictions
  • XML Syntax - CLOSE Statement
    The CLOSE statement in XML syntax closes the XML stream and prevents further operation on it unless the file is subsequently reopened using the OPEN statement.
  • XML Syntax - COUNT IN Clause
  • XML Syntax - DELETE Statement
    The DELETE statement in XML syntax deletes an XML element and all sub-elements from the in-memory representation of an XML document.
  • XML Syntax - IDENTIFIED BY Clause
    The IDENTIFIED BY clause enables you to map an XML data name (tag) to a COBOL data name.
  • XML Syntax - NAMESPACE clause
    The NAMESPACE clause sets or identifies the namespaces that are contained in an XML document.
  • XML Syntax - PROCESSING-INSTRUCTION Clause
    The PROCESSING-INSTRUCTION clause enables you to embed a processing instruction directly into the data associated with an XML tag.
  • XML Syntax - OPEN Statement
    The OPEN statement in XML syntax opens the I/O stream which contains or will contain XML data.
  • XML Syntax - READ Statement
    The READ statement in XML syntax reads an XML document from an I/O stream or retrieves an XML element from the in-memory representation of an XML document.
  • XML Syntax - REWRITE Statement
    The REWRITE statement in XML syntax modifies an XML element in the in-memory representation of the XML document.
  • XML Syntax - SELECT Clause
    This extended version of the SELECT clause assigns a filename to an XML stream.
  • XML Syntax - START Statement
    The START statement in XML syntax resets the position of a key.
  • XML Syntax - WRITE Statement
    The WRITE statement in XML syntax writes an XML document to an I/O stream or add an XML element to the in-memory representation of the XML document.
  • XML Syntax - XD File Description
    The XD file description defines a set of record definitions to receive data in an XML stream. COBOL programs that use XML must specify ORGANIZATION IS XML.
Parent topic: Part 3. Additional Topics
Related information
XML Syntax Extensions


XML File Status Codes

The following table shows return codes for the file status of the last I/O operation.

Return Code | Meaning
> 0 | After a successful READ action, the ordinal number of the record read is returned as the status code. After a successful WRITE action, the size of the XML file written is returned as the status code.
0 | Success. The XML I/O action is performed without problem.
-1 | The XML I/O action is trying to access an XML stream that is not opened.
-2 | This is an invalid XML I/O action.
-3 | Invalid mode is specified in the OPEN statement.
-4 | The XML stream cannot be opened.
-5 | The XML I/O action is attempting to access an internal DOM (Document Object Model) representation which is not present. DOM enables you to create and modify HTML pages and XML documents as full-fledged program objects.
-6 | An invalid KEY is specified in the XML I/O action.
-7 | The end of the XML stream has been reached.
-8 | This is an invalid position to insert the specified XML item.
-9 | The current record read is not a well-formed XML document.
-10 | The internal DOM representation is not written out to any XML stream and has been cleared after a READ statement or a CLOSE statement.
-11 | There is a problem reading an XML stream that is a URL.
-12 | There is a problem writing to an XML stream that is a URL.
-13 | There is a problem reading an XML stream that is not a URL.
-14 | There is a problem writing to an XML stream that is not a URL.
-15 | There is a problem closing an XML stream.
Parent topic: XML Syntax Extensions
Related information
Data Related


XML Preprocessor Restrictions

The following restrictions apply to applications using the XML Preprocessor:

  • Any level-78s used in an XD must be defined within the scope of the XD. Any references to these level 78s are only valid in the scope of that XD and in the procedure division. Do not use them in other Data Division sections.
  • There is no support for AT END or INVALID KEY phrases of the READ or WRITE verbs. Use the XML FILE status variable instead.
  • All variable names with the prefix 'PREXML--' are reserved for use by the Preprocessor.
  • In the Debugger, you cannot position the cursor in a data field when using "locate data" for an XML field definition.
Parent topic: XML Syntax Extensions


XML Syntax - CLOSE Statement

The CLOSE statement in XML syntax closes the XML stream and prevents further operation on it unless the file is subsequently reopened using the OPEN statement.

Format

XML Syntax - CLOSE statement

Syntax Rules:

  1. File-name-1 is the filename as declared in the SELECT statement as ORGANIZATION IS XML.
Parent topic: XML Syntax Extensions


XML Syntax - COUNT IN Clause

Format

XML Syntax - COUNT IN clause

Syntax Rules:

  1. Data-name-1 is an implicitly defined numeric data item with a picture clause of PIC S9(9) USAGE COMP-5.

General Rules:

The COUNT IN clause enables the program to determine the number of occurrences just read, or to specify the number of element occurrences to be output.

  1. If COUNT IN appears on a data description entry with an OCCURS clause, the dimension of data-name-1 is one less than the dimension of the associated data item.
  2. If COUNT IN appears on a data description without an OCCURS clause, the dimension of data-name-1 is the same as the dimension of the associated data item.
Parent topic: XML Syntax Extensions
Related information
COUNT IN Clause


XML Syntax - DELETE Statement

The DELETE statement in XML syntax deletes an XML element and all sub-elements from the in-memory representation of an XML document.

Format

XML Syntax - DELETE statement

Syntax Rules:

  1. File-name-1 is the filename as declared in the SELECT statement with ORGANIZATION IS XML.
  2. Data-name-1 can be qualified, and references a data item whose declaration includes an IDENTIFIED BY clause and is included in the XD record declarations for file-name-1.

General Rules:

  1. When you specify DELETE KEY IS, this deletes the internal representation of the elements and child elements associated with data-name-1. All other elements represented in the record remain unchanged.
  2. No stream I/O is actually performed by the DELETE statement.
  3. If the internal representation of the XML document is modified through the use of WRITE KEY, REWRITE KEY, or DELETE KEY, and the internal representation is cleared with either a CLOSE or READ (no key) statement, then the CLOSE or READ statement will return a status of -10, indicating the operation succeeded but no write was done.
Parent topic: XML Syntax Extensions


XML Syntax - IDENTIFIED BY Clause

The IDENTIFIED BY clause enables you to map an XML data name (tag) to a COBOL data name.

General Format

XML Syntax - IDENTIFIED BY clause

Syntax Rules:

  1. Data-name-1 is a COBOL data name.
  2. Literal-1 is an XML tag or attribute name.
  3. If data-name-1 is specified, this clause must appear on a group item and data-name-1 must be defined directly within that group item.
  4. The IS ATTRIBUTE clause is mandatory when literal-1 or data-name-1 defines an attribute.

General Rules:

  1. If a group item has an IDENTIFIED BY clause for it, any non-IDENTIFIED data items within it receive the data contained within the tag identified for the group item.
Parent topic: XML Syntax Extensions
Related information
IDENTIFIED BY and IS ATTRIBUTE Clauses


XML Syntax - NAMESPACE clause

The NAMESPACE clause sets or identifies the namespaces that are contained in an XML document.

Format

XML Syntax - NAMESPACE clause

Syntax Rules:

  1. Data-name-1 is an alphanumeric data item which contains the namespace URI (Uniform Resource Identifier).
  2. Literal-1 is a fixed namespace URI.
  3. If the NAMESPACE clause appears on a group item's declaration, then data-item-1 must be defined directly within that group item.
Parent topic: XML Syntax Extensions
Related information
NAMESPACE Clause


XML Syntax - PROCESSING-INSTRUCTION Clause

The PROCESSING-INSTRUCTION clause enables you to embed a processing instruction directly into the data associated with an XML tag.

Format

XML Syntax - PROCESSING INSTRUCTION clause

Syntax Rules:

  1. If the PROCESSING-INSTRUCTION clause is specified on a data item, the IDENTIFIED BY clause must not be.
Parent topic: XML Syntax Extensions
Related information
PROCESSING-INSTRUCTION Clause


XML Syntax - OPEN Statement

The OPEN statement in XML syntax opens the I/O stream which contains or will contain XML data.

Format

XML Syntax - OPEN statement

Syntax Rules:

  1. File-name-1 is the filename as declared in the SELECT statement as ORGANIZATION IS XML.

General Rules:

  1. Any OPEN request establishes an internal tree-based representation of an XML stream:
    • The various I/O verbs with the KEY IS clause allow traversal, update, deletion or insertion of tree nodes within that internal representation; however this does not cause any disk or other I/O operation.
    • When used with the READ verb in its basic form, I/O is performed and populates the internal representation, deleting the previous internal representation.
    • The WRITE verb in its basic form performs I/O and commits the current internal representation to the I/O stream.
  2. OPEN INPUT opens a multi-document XML input stream that contains multiple root elements.
  3. OPEN OUTPUT opens a multi-document XML output stream that can write multiple root elements.
  4. OPEN EXTEND opens a multi-document XML output stream that can write multiple root elements. The previous contents of the file are left intact and output begins at the previous end of file. OPEN EXTEND works on physical files only.
  5. OPEN I-O implicitly defines handshaking, based on the program execution flow, for streams such as pipes to another process, consoles, or Web-based streams.
  6. OPEN I-O performed on a stream which does not easily support handshaking causes all input and output operations to be based at file offset 0. In this case, multiple successive READs (not READ NEXTs) read the same record based on a file offset of 0. Multiple successive WRITEs (without the KEY IS clause) successively overwrite the entire file from a file offset of 0.
Parent topic: XML Syntax Extensions


XML Syntax - READ Statement

The READ statement in XML syntax reads an XML document from an I/O stream or retrieves an XML element from the in-memory representation of an XML document.

Format

XML Syntax - READ statement

Syntax Rules:

  1. File-name-1 is the filename as declared in the SELECT statement as ORGANIZATION IS XML.
  2. Data-name-1 can be qualified, and references a data item whose declaration includes an IDENTIFIED BY clause and is included in the XD record declarations for file-name-1.

General Rules:

  1. The READ statement without NEXT KEY specified reads an XML document and creates an internal tree-based representation of that document. In addition, it populates the appropriate record definition from the XD with as much data as possible, based on the record elements and occurrence limitations of the associated XML tags. The populated elements are associated with their in-memory counterparts to allow DELETE, REWRITE, and WRITE to modify the internal representation.
  2. READ NEXT finds the associated internal counterpart of the indicated key and either populates the key and all subordinate items with the next occurrence of that internal counterpart, or returns end-of-file if there is no next occurrence.
  3. No stream I/O is actually performed by the READ NEXT KEY IS statement.
  4. The READ statement cannot read PROCESSING-INSTRUCTIONs that are outside the body of the XML record. If you need this flexibility, use the XML PARSE verb.
Parent topic: XML Syntax Extensions


XML Syntax - REWRITE Statement

The REWRITE statement in XML syntax modifies an XML element in the in-memory representation of the XML document.

Format

XML Syntax - REWRITE statement

Syntax Rules:

  1. Record-name-1 is the name of an 01 level group item defined in an XD record declaration within the Data Division.
  2. Data-name-1 can be qualified, and references a data item whose declaration includes an IDENTIFIED BY clause and is included in the XD record declarations for file-name-1.

General Rules:

  1. No stream I/O is performed by the REWRITE verb.
  2. REWRITE KEY IS updates the in-memory representation of the elements and child elements associated with data-name-1. All other elements in the in-memory representation remain unchanged.
  3. If the internal representation of the XML document is modified through the use of WRITE KEY, REWRITE KEY, or DELETE KEY, and the internal representation is cleared with either a CLOSE or READ (no key) statement, then the CLOSE or READ statement returns a status of -10, indicating the operation succeeded but no write was done.
Parent topic: XML Syntax Extensions


XML Syntax - SELECT Clause

This extended version of the SELECT clause assigns a filename to an XML stream.

Format

XML Syntax - SELECT clause

Syntax Rules:

  1. File-name-1 is the name of the file that contains the XML stream.
  2. LINE ADVANCING specifies that line feeds are included in the output.
  3. NOT LINE ADVANCING specifies that no line feeds are included in the output.
  4. Literal-1 must be an alphanumeric literal.
  5. Literal-1 or data-name-1 must be a COBOL file specifier.
  6. Data-name-2 is an alphanumeric data item that contains XML data at run time.
  7. Pointer-name-1 is the address a memory buffer containing XML data.
  8. Data-name-3 is the length of the buffer pointed to by pointer-name-1.
  9. EXTERNAL indicates that the schema this XML stream conforms to is external. This is for documentation purposes alone and does not affect input or output.
  10. OMITTED specifies that no schema is associated with the XML file.
  11. Literal-2 or data-name-4 is a generated or external name of the schema the record conforms to. For example, for an external schema, this could be an entire URL to the file such as "http://www.microfocus.com/nx40/cobol/v2.0/foo.xsd"
  12. Data-name-5 must be declared in the data division as a PIC S9(9) (any usage) and holds the file status for the last I/O operation.

General Rules:

  1. When neither LINE ADVANCING nor NOT LINE ADVANCING is specified, line feeds are included in the output.
  2. Literal-1 or data-name-1 in an application that is not Web-based can be a COBOL file specifier as follows:
    • stdin, use ":CI:"
    • stout, use ":CO:"
    • file, use ".myxmlfile"

      where myxmlfile is the name of the file. Generally, XML files use the file extension .xml.

    • pipe, use "<myprog, ">myprog" or "|myprog"

      where myprog is the name of a program that uses stdin and/or stdout to communicate through the pipe.

  3. Literal-1 or data-name-1, in a client-side Web-based application, can be:
    • A CGI program hosted on a Web site, such as "http://www.bookdb.com:80/cgibin/xmlprog.exe"
    • An XML file, such as or "http://localhost/xmlfile.xml"
  4. Literal-1 or data-name-1, in a CGI, server-side Web application can be ":CGI:", which causes the environment variable CONTENT_LENGTH to be considered when reading the standard input stream (stdin). ":CGI:" can only be opened INPUT or OUTPUT, never I-O or EXTEND.
  5. When DOCUMENT-TYPE is not specified, no schema is associated with the XML file. For example:

    The following code:

    SELECT xml-addressdb
    ASSIGN 'address.xml'
    ORGANIZATION IS XML
    DOCUMENT-TYPE IS OMITTED

    FILE STATUS xml-status.

    Is equivalent to:

    SELECT xml-addressdb
    ASSIGN 'address.xml'
    ORGANIZATION IS XML
    FILE STATUS xml-status.
  6. The CHECK clause can be repeated multiple times. For example:
    SELECT foobar
    ASSIGN TO "foobar.xml"
    ORGANIZATION IS XML
    DOCUMENT TYPE IS "foobar.xsd"
    CHECK VALIDITY ON INPUT
    CHECK OUTPUT.
Parent topic: XML Syntax Extensions
Related information
SELECT Paragraph


XML Syntax - START Statement

The START statement in XML syntax resets the position of a key.

Format

XML Syntax - START statement

Syntax Rules:

  1. File-name-1 is the file name as declared in the SELECT statement as ORGANIZATION IS XML.
  2. Data-name-1 is a data item whose declaration includes an IDENTIFIED BY clause, and is included in the XD record declarations for file-name-1.
  3. Identifier-1 or literal-1 is a numeric value indicating which occurence of the tag name referenced by xml_file_record_node is returned by the next READ NEXT statement.

General Rules:

  1. The KEY IS clause resets the current internal counterpart so that a subsequent READ NEXT reads the occurrence of that key specified by data-name-1.
  2. If the INDEX clause is omitted, the index is assumed to be 1.
  3. Once a START request is performed, the indicated key and all sub-keys are associated with a position, and not with any data in the internal representation.
  4. If a START is followed immediately by WRITE KEY, that key is placed immediately before the node that would have been read if a START had been followed with READ NEXT. To add a node after this node, use a READ NEXT statement specifying the same key specified on the START.
  5. Do not immediately follow START with REWRITE KEY.
Parent topic: XML Syntax Extensions


XML Syntax - WRITE Statement

The WRITE statement in XML syntax writes an XML document to an I/O stream or add an XML element to the in-memory representation of the XML document.

Format

XML Syntax - WRITE statement

Syntax Rules:

  1. Record-name-1 is the name of an 01 level group item defined in an XD record declaration within the Data Division .
  2. Data-name-1 can be qualified, and references a data item whose declaration includes an IDENTIFIED BY clause and is included in the XD record declarations for file-name-1.

General Rules:

  1. WRITE without KEY IS takes the record specified, creates a new internal representation (if one does not exist already) and then writes that internal representation to the stream.
  2. If the following conditions are met when an XML file is opened I-O:
    • an internal representation is created by a READ statement
    • the internal representation is modified by any combination of WRITE, REWRITE, or DELETE KEY statements
    • WRITE without the KEY IS clause is performed
    The current contents of the record specified are ignored; instead, the internal representation as established by the READ and modified by the WRITE, REWRITE, or DELETE KEY statements, is written to the stream.
  3. WRITE KEY IS PLAIN-TEXT, data-name-2 or literal-1 is a string value which contains plain text to be output to the XML stream.
  4. WRITE KEY IS PLAIN-TEXT can be decoration such as "Content-type: text/xml."
  5. No stream I/O is actually performed by the WRITE KEY IS statement.
  6. AT END and INVALID KEY are not supported. Use the XML file status variable instead.
  7. WRITE KEY IS adds the node specified to the internal representation of the XML document immediately after the current position. If any containing nodes are required for the node specified, these are also created in the internal representation.
  8. If ALL is specified, any contained nodes are also added to the internal representation of the XML document. Otherwise only the specific node and its attributes and data are added. No stream I/O is performed.
  9. WRITE KEY IS PROCESSING-INSTRUCTION causes an XML processing-instruction node to be added immediately after the current position. When using sequential I/O, where your other WRITE statements have no usage of the KEY clause, a processing instruction is either written before or after the entire XML record, depending on order of execution. When using random I/O, you can write a processing instruction immediately before or after any pre-existing node, using the following sequence:
    START  xml_file_record KEY IS xml_file_node
    IF write-after
       READ xml_file_record NEXT KEY IS xml_file_node
    END-IF
    WRITE  xml_file_record KEY IS PROCESSING-INSTRUCTION 'processing-id processing-data'

    For example, this technique is useful when dealing with the root node and the processing instruction 'xml version="1.0"'.

  10. When using WRITE KEY IS PROCESSING-INSTRUCTION:
    • Data-name-2 is a defined level 78 or a simple data name.
    • Literal-1 is a string value which contains an XML-specific processing instruction. Upon output, this string is decorated with the XML delimiters '<? 'and '?>'.
  11. WRITE KEY IS PLAIN-TEXT adds a plain text node immediately after the current position. When using sequential I/O, where your other WRITE statements have no usage of the KEY clause, plain text will either be written before or after the entire XML record, depending on order of execution. When using random I/O, you can write plain text immediately before or after any pre-existing node, using the following sequence:
    START  xml_file_record KEY IS xml_file_node
    IF write-after
       READ xml_file_record NEXT KEY IS xml_file_node
    END-IF
    WRITE  xml_file_record KEY IS PLAIN-TEXT  'processing-id processing-data'

    This technique is useful when your XML program needs to 'decorate' an XML record with plain text data, for example, specifying "Content-type: text/xml" when operating in a CGI context.

  12. If the internal representation of the XML document is modified through the use of WRITE KEY, REWRITE KEY, or DELETE KEY, and the internal representation is cleared with either a CLOSE or READ (no key) statement, then the CLOSE or READ statement returns a status of -10, indicating the operation succeeded but no write was done.
Parent topic: XML Syntax Extensions


XML Syntax - XD File Description

The XD file description defines a set of record definitions to receive data in an XML stream. COBOL programs that use XML must specify ORGANIZATION IS XML.

Format

XML Syntax - XD file description

Syntax Rules:

  1. File-name-1 is the filename as declared in the SELECT statement as ORGANIZATION IS XML.
  2. Record-description-entry is the COBOL record definition that uses XML syntax extensions.

General Rules:

  1. Do not code an OCCURS DEPENDING ON clause into the XD record of a program that is compiled with the ODOSLIDE directive.
Parent topic: XML Syntax Extensions
Related information
XML Description Paragraph (XD)


Report Writer

The Report Writer is a special purpose feature which places its emphasis on the organization, format, and contents of an output report. Although a report can be produced using the standard COBOL language, the Report Writer language features provide a more concise facility for report structuring and report production. Much of the Procedure Division programming which would normally be supplied by the programmer is instead provided automatically by the Report Writer Control System (RWCS). Thus the programmer is relieved of writing procedures for moving data, constructing print lines, counting lines on a page, numbering pages, producing heading and footing lines, recognizing the end of logical data subdivisions, updating sum counters, and so on. All these operations are accomplished by the RWCS as a consequence of source language statements that appear primarily in the report section of the data division of the source program.

XOPEN Although it is a part of the standard COBOL definition, this module is explicity excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

OSVS The OS/VS COBOL compiler provides support for Report Writer that is based on the ANSI'68 Standard (even when the mainframe LANGLVL(2) compiler option is used - which normally requests ANSI'74 support). However, there are many cases in which that compiler actually supports a cross between the two COBOL Standards. Therefore, you should not attempt to use your COBOL system with OS/VS COBOL emulation along with any other dialect.

OSVS Within this chapter, many of these OS/VS COBOL extensions are indicated by an OSVS bubble. However, for the exact rules for the OS/VS COBOL Report Writer syntax, you should refer to your IBM OS/VS COBOL Language Reference.

  • Report Section
  • Report Structure
  • Report Subdivisions
  • Language Concepts
  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Part 3. Additional Topics


Report Section

The Report Section of a COBOL Data Division contains one or more Report Description entries (RD entries), each of which forms the complete description of a report.

The report named in the RD entry is not assigned directly to an output file. Instead, it is associated with a file-name in the File Section and that file-name is associated with a file when an OPEN statement specifying the file-name is executed. More than one report can be associated with the same file-name and the CODE clause is used to differentiate among the reports. For an external file connector referenced by a file-name, separately compiled programs can specify different reports for the same file-name. This file description entry must specify the name of a report description entry for each report associated with that file-name in this program.

The RD entry contains a set of clauses that names the report and supplies specific information about the format of the printed page and the organization of the subdivisions of the report. An identification code can be given in the RD entry so that each report can be identified separately in an intermediate output file.

Following each RD entry are one or more 01 level-number entries, each followed by a hierarchical structure similar to COBOL record descriptions. Each 01 level-number entry and its subordinate entries describes a report group. Each report group consists of one or more print lines that are regarded as a unit. A report group that is to be printed is printed entirely on one logical page; it is never split across pages.

Parent topic: Report Writer


Report Structure

When structuring a report, major consideration must be given to vertical and horizontal spacing requirements, manipulation of data, and the physical and logical subdivisions of a report.

  • Vertical Spacing
  • Horizontal Spacing
  • Data Manipulation
Parent topic: Report Writer


Vertical Spacing

The Report Writer feature allows the user to describe report groups containing multiple lines. The vert ical positioning of the lines on a page is specified by the LINE NUMBER clause that is associated with each line. The NEXT GROUP clause indicates how many lines to space after presenting the last line of the group. The first LINE NUMBER clause of the next group indicates additional spacing information to be used in positioning of that group.

Parent topic: Report Structure


Horizontal Spacing

The Report Writer allows the user to position the fields of data on a report line by means of the COLUMN NUMBER clause. The RWCS supplies space fill between all defined fields.

Parent topic: Report Structure


Data Manipulation

When the Report Writer feature is used, data movement to a report group is directed by report section clauses rather than Procedure Division statements. The report section clauses that affect the manipulation of data are the SOURCE, SUM, and VALUE clauses.

The SOURCE clause specifies the sending data item of an implicit MOVE statement. The receiving printable item is defined by the description of the report group item in which the SOURCE clause appears.

The SUM clause automatically causes the establishment of a sum counter. The object of the SUM clause names the data item(s) which are added to the sum counter when a GENERATE statement is executed. The moving of the sum counter contents to the receiving printable item, defined by the description of the report group item in which the SUM clause appears, is accomplished automatically when that report group is presented.

The VALUE clause defines a literal that appears in the printable item of a report group each time that report group is to be presented.

In summary, a data item in a report group is presented only if it has a COLUMN NUMBER clause specifying where it is to be presented. The value that is placed in a printable item is determined by the SOURCE, SUM, or VALUE clause stated in the report group description. Under no circumstances can a report group printable item receive a value directly via a Procedure Division statement.

Note: Report Writer does not support boolean data items.
Parent topic: Report Structure


Report Subdivisions

The physical and logical organization of a report interact to determine what is presented on a page.

  • Physical Subdivision of a Report
  • Logical Subdivisions of a Report
  • Procedure Division Report Writer Statements
Parent topic: Report Writer


Physical Subdivision of a Report

The PAGE clause specifies the length of the page, the size of the heading and footing areas, and the size of the area in which the detail lines will appear. The RWCS uses the LINE NUMBER and NEXT GROUP clauses to position these report groups, and when necessary, to advance to a new page with automatic production of PAGE HEADING and PAGE FOOTING report groups.

Parent topic: Report Subdivisions


Logical Subdivisions of a Report

DETAIL report groups can be structured into a nested set of control groups. Each control group can begin with a CONTROL HEADING report group and end with a CONTROL FOOTING report group.

When nested control groups are defined, the recognition of a change in value of a control data item in a control hierarchy is called a control break and the heading and footing lines associated with the control data-name are called CONTROL HEADING and CONTROL FOOTING report groups.

During the execution of a GENERATE statement, the RWCS uses the control hierarchy to check automatically for control breaks. If a control break has occurred, all controls that are minor to it are considered to have changed, even though they may not in fact have changed. The occurrence of a control break causes the following sequence of events to take place:

  1. ALL CONTROL FOOTING report groups are presented up to and including the one at the level at which the control break occurred.
  2. ALL CONTROL HEADING report groups are presented from the control break level down to the most minor control.
  3. The DETAIL report group named in the GENERATE statement is presented.
Parent topic: Report Subdivisions


Procedure Division Report Writer Statements

The Report Writer statements that appear in the Procedure Division are: INITIATE, GENERATE, TERMINATE, SUPPRESS, and USE BEFORE REPORTING.

The INITIATE statement causes the RWCS to perform automatically a number of initialization functions. A report must be initiated before any detail processing can take place.

The GENERATE statement which specifies a data-name causes the named DETAIL report group to be formatted and written to the output device. In addition, it triggers the RWCS to perform the many implicit actions described in the preceding section.

The GENERATE statement which specifies a report-name provides a means of summary reporting. A report produced by this type of statement has all detail print lines suppressed automatically and consists of only the summary totals accumulated during the processing of the DETAIL report group. The RWCS processing for a GENERATE report-name statement is identical to that which occurs for a GENERATE data-name statement, except that the former results in the suppression of detail print lines.

The TERMINATE statement causes the RWCS to perform all of the automatic functions associated with the termination of a report. The TERMINATE statement must be executed before the file containing the report is closed.

The SUPPRESS statement provides the object time facility to suppress the printing of an entire report group.

The BEFORE REPORTING phrase of the USE statement provides a mechanism whereby Procedure Division statement can be executed at specific instances in the automatic procedures performed by the RWCS. The statements in the USE BEFORE REPORTING procedure can alter the contents of the data items that are referenced by SOURCE clauses. Thus control is possible over the contents of data items referenced in report groups that are produced automatically.

Parent topic: Report Subdivisions


Language Concepts

  • Report File
  • Special Register PAGE-COUNTER
  • Special Register LINE-COUNTER
  • Special Register PRINT-SWITCH
  • Subscripting
Parent topic: Report Writer


Report File

A report file is an output file having sequential organization. A report file has a file description entry containing a REPORT clause. The content of a report file consists of records that are written under control of the RWCS.

A report file is named by a file control entry and is described by a file description entry containing a REPORT clause. A report file is referred to and accessed by the OPEN, GENERATE, INITIATE, SUPPRESS, TERMINATE, USE BEFORE REPORTING, and CLOSE statements.

Parent topic: Language Concepts


Special Register PAGE-COUNTER

The reserved word PAGE-COUNTER is a name for a page counter that is generated for each RD entry in the report section of the Data Division. The implicit description is PIC 9(6) BINARY. The value in PAGE-COUNTER is maintained by the RWCS and is used by the program to number the pages of a report. PAGE-COUNTER can be referenced only in the SOURCE clause of the Report Section and in Procedure Division statements. (See the section PAGE-COUNTER Rules.)

Parent topic: Language Concepts
Related information
PAGE-COUNTER Rules


Special Register LINE-COUNTER

The reserved word LINE-COUNTER is a name for a line counter that is generated for each RD entry in the report section of the data division. The implicit description is PIC 9(6) BINARY. The value in LINE-COUNTER is maintained by the RWCS, and is used to determine the vertical positioning of a report. LINE-COUNTER can be referenced only in the SOURCE clause of the report section and in Procedure Division statements; however, only the RWCS can change the value of LINE-COUNTER. (See the section LINE-COUNTER Rules.)

Parent topic: Language Concepts
Related information
LINE-COUNTER Rules


Special Register PRINT-SWITCH

The reserved word PRINT-SWITCH is a name for a register whose value may be set to non-zero in the course of a USE BEFORE REPORTING declarative procedure. This has the effect of suppressing printing of the corresponding report group.

Parent topic: Language Concepts


Subscripting

In the Report Section, neither a sum counter nor the special registers LINE-COUNTER and PAGE-COUNTER can be used as a subscript.

Parent topic: Language Concepts


Environment Division

  • Input-Output Section
  • The File-Control Paragraph
  • The I-O-Control Paragraph
Parent topic: Report Writer


Input-Output Section

Information concerning the Input-Output Section is located in the section Input-Output Section.

Parent topic: Environment Division
Related information
Input-Output Section


The File-Control Paragraph

Information concerning the File-Control paragraph is located in the section The File-Control Paragraph.

Function

The file-control entry declares the relevant physical attributes of a report file.

Additional Syntax Rules

  1. The OPTIONAL phrase applies only to a report opened in the extend mode. Its specification is required for a report file that is not necessarily present each time the object program is executed.
  2. A report file must have sequential organization. Each report file specified in the SELECT clause must have a file description entry containing a REPORT clause in the Data Division of the same program.
Parent topic: Environment Division
Related information
The File-Control Paragraph


The I-O-Control Paragraph

Information concerning the I-O-Control paragraph is located in the section The I-O-Control Paragraph.

Additional Syntax Rules

  1. A report file can not appear in a SAME clause for which the RECORD phrase is specified.
Parent topic: Environment Division
Related information
The I-O-Control Paragraph


Data Division

  • The File Description Entry (Report Writer)
    The file description entry furnishes information concerning the physical structure, identification, and record-names pertaining to a given file.
  • The REPORT Clause
    The REPORT clause specifies the names of reports that comprise a report file.
  • Report Section
    The Report Section is located in the Data Division of a source program. The Report Section describes the reports to be written onto report files. The description of each report must begin with a RD entry and be followed by one or more report group description entries.
  • The Report Description Entry
    The RD entry names a report, specifies any identifying characters to be appended to each print line in the report and describes the physical structure and organization of that report.
  • The Report Group Description Entry
    The report group description entry specifies the characteristics of a report group and of the individual items in a report group.
Parent topic: Report Writer


The File Description Entry (Report Writer)

The file description entry furnishes information concerning the physical structure, identification, and record-names pertaining to a given file.

ANS85 It determines the internal or external attributes of a file connector, of the associated data records, and of the associated data items. The file description entry also determines whether a file-name is a local name or a global name.

General Format

Syntax Rules

  1. The level indicator FD identifies the beginning of the file description entry for a report file and must precede the file-name of the report file.
  2. The clauses which follow file-name-1 can appear in any order.
  3. File-name-1 can only reference a sequential file.
  4. No record description entries can follow the file description entry for a report file.

    OSVS MF Record description entries are permitted.

  5. The subject of a file description entry that specifies a REPORT clause can be referenced in the procedure division only by the USE statement, the CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.

General Rules

  1. With the exception of the REPORT clause, all clauses in the file description entry for a report file are presented in the sequential I-O module.
  2. Details on the REPORT clause are presented below.
Parent topic: Data Division


The REPORT Clause

The REPORT clause specifies the names of reports that comprise a report file.

General Format

Syntax Rules

  1. Each report-name specified in a REPORT clause must be the subject of a RD entry in the report section of the same program. The order of appearance of the report-names is not significant.
  2. A report-name must appear in only one REPORT clause.

    OSVS A report-name can appear in two REPORT clauses.

  3. The subject of a file description entry that specifies a REPORT clause can be referenced in the procedure division only by the USE statement, the CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.

General Rules

  1. The presence of more than one report-name in a REPORT clause indicates that the file contains more than one report.
  2. After execution of an INITIATE statement and before the execution of a TERMINATE statement for the same report file, the report file is under the control of the RWCS. While a report file is under the control of the RWCS, no input-output statement can be executed which references that report file.
  3. ANS85 If the associated file connector is an external file connector, every file description entry in the run unit which is associated with that file connector must describe it as a report file.
Parent topic: Data Division


Report Section

The Report Section is located in the Data Division of a source program. The Report Section describes the reports to be written onto report files. The description of each report must begin with a RD entry and be followed by one or more report group description entries.

General Format

Comments

In addition to naming the report, the RD entry defines the format of each page of the report by specifying the vertical boundaries of the region within which each type of report group can be printed. The RD entry also specifies the control data items. When the report is produced, changes in the values of the control data items cause the detail information of the report to be processed in groups called control groups.

Each report named in the REPORT clause of a file description entry in the file section must be the subject of a RD entry in the report section. Furthermore, each report in the report section must be named in one and only one file description entry.

The report groups that will comprise the report are described following the RD entry. The description of each report group begins with a report group description entry; that is an entry that has a 01 level-number and a TYPE clause. Subordinate to the report group description entry, there can appear group and elementary entries that further describe the characteristics of the report group.

Parent topic: Data Division


The Report Description Entry

The RD entry names a report, specifies any identifying characters to be appended to each print line in the report and describes the physical structure and organization of that report.

ANS85 It also determines whether a report-name is a local name or a global name.

General Format

Syntax Rules

  1. Report-name-1 must appear in one and only one REPORT clause.
  2. The order of appearance of the clauses following report-name-1 is immaterial.
  3. Report-name-1 is the highest permissible qualifier that can be specified for LINE-COUNTER, PAGE-COUNTER, and all data-names defined in the report section.

General Rules

  1. The CODE clause, the CONTROL clause, and the PAGE clause are resented in alphabetical order below.
  2. ANS85 If the RD entry contains the GLOBAL clause, the special registers LINE-COUNTER and PAGE-COUNTER are global names.
  • PAGE-COUNTER Rules
  • LINE-COUNTER Rules
  • The CODE Clause
    The CODE clause specifies a two-character literal that identifies each print line as belonging to a specific report.
  • The CONTROL Clause
    The CONTROL clause establishes the levels of the control hierarchy for the report.
  • The PAGE Clause
    The PAGE clause defines the length of a page and the vertical subdivisions within which report groups are presented.
Parent topic: Data Division


PAGE-COUNTER Rules

  1. PAGE-COUNTER is the reserved word used to reference a special register that is automatically created for each report specified in the report section. (See the section Special Register PAGE-COUNTER.)
  2. In the report section, a reference to PAGE-COUNTER can appear only in a SOURCE clause. In the Procedure Division, PAGE-COUNTER can be used in any context in which a data item with an integer value can appear.
  3. If more than one PAGE-COUNTER exists in a program, PAGE-COUNTER must be qualified by a report-name whenever it is referenced in the Procedure Division.

    In the report section an unqualified reference to PAGE-COUNTER is qualified implicitly by the name of the report in whose RD entry the reference is made. Whenever the PAGE-COUNTER of a different report is referenced, PAGE-COUNTER must be explicitly qualified by the report-name associated with the different report.

  4. Execution of the INITIATE statement causes the RWCS to set the PAGE-COUNTER of the referenced report to one.
  5. PAGE-COUNTER is automatically incremented by one each time the RWCS executes a page advance.
  6. PAGE-COUNTER can be altered by Procedure Division statements.
Parent topic: The Report Description Entry
Related information
Special Register PAGE-COUNTER


LINE-COUNTER Rules

  1. LINE-COUNTER is the reserved word used to reference a special register that is automatically created for each report specified in the Report Section. (See the section Special Register LINE-COUNTER.)
  2. In the report section a reference to LINE-COUNTER can appear only in a SOURCE clause. In the Procedure Division, LINE-COUNTER can be used in any context in which a data item with an integral value can appear. However, only the RWCS can change the content of LINE-COUNTER.
  3. If more than one LINE-COUNTER exists in a program, LINE-COUNTER must be qualified by a report-name whenever it is referenced in the Procedure Division.

    In the Report Section an unqualified reference to LINE-COUNTER is qualified implicitly by the name of the report in whose description entry the reference is made. Whenever the LINE-COUNTER of a different report is referenced, LINE-COUNTER must be explicitly qualified by the report-name associated with the different report.

  4. Execution of an INITIATE statement causes the RWCS to set the LINE-COUNTER of the referenced report to zero. The RWCS also automatically resets LINE-COUNTER to zero each time it executes a page advance.
  5. The value of LINE-COUNTER is not affected by the processing of nonprintable report groups nor by the processing of a printable report group whose printing is suppressed by means of the SUPPRESS statement.
  6. At the time each print line is presented, the value of LINE-COUNTER represents the line number on which the print line is presented. The value of LINE-COUNTER after the presentation of a report group is governed by the presentation rules for the report group. (See the section Presentation Rules Tables.)
Parent topic: The Report Description Entry
Related information
Special Register LINE-COUNTER
Presentation Rules Tables


The CODE Clause

The CODE clause specifies a two-character literal that identifies each print line as belonging to a specific report.

General Format

Syntax Rules

  1. Literal-1 must be a two-character nonnumeric literal.

    OSVS Literal-1 may be replaced by a mnemonic-name specified in the special-names paragraph. See the OS/VS COBOL Language Reference for additional details.

  2. If the CODE clause is specified for any report in a file, it must be specified for all reports in that file.

General Rules

  1. When the CODE clause is specified, literal-1 is automatically placed in the first two character positions of each report writer logical record.
  2. The positions occupied by literal-1 are not included in the description of the print line, but are included in the logical record size.
Parent topic: The Report Description Entry


The CONTROL Clause

The CONTROL clause establishes the levels of the control hierarchy for the report.

General Format

Syntax Rules

  1. Data-name-1 must not be defined in the Report Section. Data-name-1 can be qualified.
  2. Each recurrence of data-name-1 must identify a different data item.
  3. Data-name-1 must not have subordinate to it a variable occurrence data item.

General Rules

  1. Data-name-1 and the word FINAL specify the levels of the control hierarchy. FINAL, if specified, is the highest control, data-name-1 is the major control, the next recurrence of data-name-1 is an intermediate control, and so on. The last recurrence of data-name-1 is the minor control.
  2. The execution of the chronologically first GENERATE statement for a given report causes the RWCS to save the values of all control data items associated with that report. On subsequent executions of all GENERATE statements for that report, control data items are tested by the RWCS for a change of value. A change of value in any control data item causes a control break to occur. This control break is associated with the highest level for which a change of value is noted. (See the section The GENERATE Statement.)
  3. The RWCS tests for a control break by comparing the content of each control data item with the prior content of each control data item that was saved when the previous GENERATE statement for the same report was executed. The RWCS applies the inequality relation test as follows:
    1. If the control data item is a numeric data item, the relation test is for the comparison of two numeric operands.
    2. If the control data item is an index data item, the relation test is for the comparison of two index data items.
    3. If the control data item is a data item other than as described in 3a and 3b above, the relation test is for the comparison of two nonnumeric operands.

    The relation test is further explained in the appropriate paragraph. (See the topic Relation Condition.)

  4. FINAL is used when the most inclusive control group in the report is not associated with a control data-name.
Parent topic: The Report Description Entry
Related information
The GENERATE Statement
Relation Condition


The PAGE Clause

The PAGE clause defines the length of a page and the vertical subdivisions within which report groups are presented.

General Format

Syntax Rules

  1. The HEADING, FIRST DETAIL, LAST DETAIL, and FOOTING phrases can be written in any order.
  2. Integer-1 must not exceed three significant digits in length.
  3. Integer-2 must be greater than or equal to one.
  4. Integer-3 must be greater than or equal to integer-2.
  5. Integer-4 must be greater than or equal to integer-3.
  6. Integer-5 must be greater than or equal to integer-4.
  7. Integer-1 must be greater than or equal to integer-5.
  8. The following rules indicate the vertical subdivision of the page in which each type of report group can appear when the PAGE clause is specified. (See the section Page Regions.)
    1. A report heading report group that is to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-1, inclusive.

      A report heading report group that is not to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-3 minus 1, inclusive.

    2. A page heading report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-3 minus 1, inclusive.
    3. A control heading or detail report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-3 to the line number specified by integer-4, inclusive.
    4. A control footing report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-3 to the line number specified by integer-5, inclusive.
    5. A page footing report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-5 plus 1 to the line number specified by integer-1, inclusive.
    6. A report footing report group that is to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-1, inclusive.

      A report footing report group that is not to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-5 plus 1 to the line number specified by integer-1, inclusive.

  9. All report groups must be described such that they can be presented on one page. The RWCS never splits a multi-line report group across page boundaries.

General Rules

  1. The vertical format of a report page is established using the integer values specified in the PAGE clause.
    1. Integer-1 defines the size of a report page by specifying the number of lines available on each page.
    2. HEADING integer-2 defines the first line number on which a report heading or page heading report group can be presented.
    3. FIRST DETAIL integer-3 defines the first line number on which a body group can be presented. Report heading and page heading report groups cannot be presented on or beyond the line number specified by integer-3.
    4. LAST DETAIL integer-4 defines the last line number on which a control heading or detail report group can be presented.
    5. FOOTING integer-5 defines the last line number on which a control footing report group can be presented. Page footing and report footing report groups must follow the line number specified by integer-5.
  2. If the PAGE clause is specified the following implicit values are assumed for any omitted phrases:
    1. If the HEADING phrase is omitted, a value of one is assumed for integer-2.
    2. If the FIRST DETAIL phrase is omitted, a value equal to integer-2 is given to integer-3.
    3. If the LAST DETAIL and the FOOTING phrases are both omitted, the value of integer-1 is given to both integer-4 and integer-5.
    4. If the FOOTING phrase is specified and the LAST DETAIL phrase is omitted, the value of integer-5 is given to integer-4.
    5. If the LAST DETAIL phrase is specified and the FOOTING phrase is omitted, the value of integer-4 is given to integer-5.
  3. If the PAGE clause is omitted, the report consists of a single page of indefinite length.
  4. The presentation rules for each type of report group are specified in the appropriate paragraph. (See the section Presentation Rules Tables.)

Pageregion Page Regions

Page regions that are established by the PAGE clause are described in the table below.

Table 1. Page Regions
Report Groups that can be represented in the Region | First line no. of the Region | Last line no. of the Region
Report heading described with NEXT GROUP NEXT PAGE Report footing described with LINE integer-1 NEXT PAGE | integer-2 | integer-1
Report heading not described with NEXT GROUP NEXT PAGE Page heading | integer-2 | integer-3 minus 1
Control footing Detail | integer-3 | integer-4
Control footing | integer-3 | integer-5
Page footing Report footing not described with LINE integer-1 NEXT PAGE | integer-5 plus 1 | integer-1
Parent topic: The Report Description Entry
Related information
Presentation Rules Tables


The Report Group Description Entry

The report group description entry specifies the characteristics of a report group and of the individual items in a report group.

General Formats for Format 1

General Formats for Format 2

General Formats for GROUP INDICATE clause Format 3

Syntax Rules for All Formats

  1. The report group description entry can appear only in the Report Section.
  2. Except for the data-name clause, which when present must immediately follow the level-number, the clauses can be written in any sequence.
  3. A description of a report group can consist of one, two, three or four hierarchic levels:
    1. The first entry that describes a report group must be a Format 1 entry.
    2. Both Format 2 and Format 3 entries can be immediately subordinate to a Format 1 entry.
    3. At least one Format 3 entry must be immediately subordinate to a Format 2 entry.
    4. Format 3 entries must define elementary data items.
  4. In the Report Section, the USAGE clause is used only to declare the usage of printable items.
    1. If the USAGE clause appears in a Format 3 entry, that entry must define a printable item.
    2. If the USAGE clause appears in a Format 1 or Format 2 entry, at least one subordinate entry must define a printable item.
  5. An entry that contains a LINE NUMBER clause must not have a subordinate entry that also contains a LINE NUMBER clause.

    OSVS However an entry containing the LINE NUMBER NEXT PAGE clause can have a subordinate entry containing a LINE NUMBER clause but without the NEXT PAGE option.

Syntax Rules for Format 1

  6. Data-name-1 is required only when:
    1. A detail report group is referenced by a GENERATE statement.
    2. A detail report group is referenced by the UPON phrase of a SUM clause.
    3. A report group is referenced in a USE BEFORE REPORTING sentence.
    4. The name of a control footing report group is used to qualify a reference to a sum counter.

    If specified, data-name-1 can be referenced only by a GENERATE statement, the UPON phrase of a SUM clause, a USE BEFORE REPORTING sentence, or as a sum counter qualifier.

Syntax Rules for Format 2

  7. The level-number can be any integer from 02 to 48 inclusive.
  8. An entry must contain at least one optional clause.
  9. Data-name-1 is optional. If present it can be used only to qualify a sum counter reference.

Syntax Rules for Format 3

  10. The level-number can be any integer from 02 to 49 inclusive.
  11. In Format 3:
    1. A GROUP INDICATE clause can appear only in a type detail report group.
    2. A SUM clause can appear only in a type control footing report group.
    3. An entry that contains a COLUMN NUMBER clause but no LINE NUMBER clause must be subordinate to an entry that contains a LINE NUMBER clause.
    4. Data-name-1 is optional but can be specified in any entry. Data-name-1 can be referenced only if the entry defines a sum counter.
    5. An entry that contains a VALUE clause must also have a COLUMN NUMBER clause.
  12. The table below shows all permissible clause combinations for a Format 3 entry. The table is read from left to right along the selected row.

    An "M" indicates that the presence of the clause is mandatory.

    A "P" indicates that the presence of the clause is permitted, but not required.

    A blank indicates that the clause is not permitted.

    Table 1. Permissible Clause Combinations in Format 3 Entries
    PIC | COLUMN | SOURCE | SUM | VALUE | JUST | BLANK WHEN ZERO | GROUP INDICATE | USAGE | SIGN | LINE
    M | M | P | P
    M | M | M | P | P | P | P
    M | P | M | P | P | P | P | P
    M | P | M | P | P | P | P | P
    M | M | M | P | P | P | P | P

General Rules

  1. Format 1 is the report group entry. The report is defined by the contents of this entry and all of its subordinate entries.
  2. The BLANK WHEN ZERO clause, the JUSTIFIED clause, and the PICTURE clause for the Report Writer module are the same as The BLANK WHEN ZERO Clause, The JUSTIFIED Clause, and The PICTURE Clause in the nucleus. The other clauses of the report group description entry are presented in alphabetical order later in this chapter.
  • Presentation Rules Tables
  • The COLUMN NUMBER Clause (Report Writer)
    The COLUMN NUMBER clause identifies a printable item and specifies the position of the item on a print line.
  • Data-name (Report Writer)
    A data-name specifies the name of the data item being described.
  • The GROUP INDICATE Clause
    The GROUP INDICATE clause specifies that the associated printable item is presented only on the first occurrence of its report group after a control break or page advance.
  • Level-Number (Report Writer)
    The level-number indicates the position of a data item in the hierarchical structure of a report group.
  • The LINE NUMBER Clause (Report Writer)
    The LINE NUMBER clause specifies vertical positioning information for its report group.
  • The NEXT GROUP Clause
    The NEXT GROUP clause specifies information for vertical positioning of a page following the presentation of the last line of a report group.
  • The SIGN Clause (Report Writer)
    The SIGN clause specifies the position and the mode of representation of the operational sign when it is necessary to describe these properties explicitly.
  • The SOURCE Clause (Report Writer)
    The SOURCE clause identifies the sending data item that is moved to an associated printable item defined in a report group description entry.
  • The SUM Clause (Report Writer)
    The SUM clause establishes a sum counter and names the data items to be summed.
  • The TYPE Clause
    The TYPE clause specifies the particular type of report group that is described by this entry and indicates the time at which the report group is to be processed by the RWCS.
  • The USAGE Clause
    The USAGE clause specifies the format of a data item in the computer storage.
  • The VALUE Clause (Report Writer)
    The VALUE clause defines the value of Report Section printable items.
Parent topic: Data Division
Related information
The BLANK WHEN ZERO Clause
The JUSTIFIED Clause
The PICTURE Clause


Presentation Rules Tables

The tables and rules on the following pages specify:

  1. The permissible combinations of LINE NUMBER and NEXT GROUP clauses for each type of report group.
  2. The requirements that are placed on the use of these clauses, and
  3. The interpretation that the RWCS gives to these clauses.
  • Organization
  • Line Number Clause Notation
  • Line Number Clause Sequence Substitutions
  • Saved Next Group Integer Description
  • Report Heading Group Presentation Rules
  • Page Heading Group Presentation Rules
  • Body Group Presentation Rules
  • Page Footing Presentation Rules
  • Report Footing Presentation Rules
Parent topic: The Report Group Description Entry


Organization

There is an individual presentation rules table for each of the following types of report groups: report heading, page heading, page footing, report footing. In addition, detail report groups, control heading report groups, or control footing report groups are treated jointly in the body group presentation rules table. (See the section Body Group Presentation Rules.)

Columns 1 and 2 of a presentation rules table list all of the permissible combinations of LINE NUMBER and NEXT GROUP clauses for the designated report group type. Consequently, for the purpose of identifying the set of presentation rules that apply to a particular combination of LINE NUMBER and NEXT GROUP clauses, a presentation rules table is read from left to right, along the selected row.

The applicable rules columns of a presentation rules table are partitioned into two parts. The first part specifies the rules that apply if the report description contains a PAGE clause, and the second part specifies the rules that apply if the PAGE clause is omitted. The purpose of the rules named in the applicable rules columns is discussed below:

  1. Upper limit rules and lower limit rules.

    These rules specify the vertical subdivisions of the page within which the specified report group can be represented.

    In the absence of a PAGE clause the printed report is not considered to be partitioned into vertical subdivisions. Consequently, in the tables no upper limit rule or lower limit rule is specified for a report description in which the PAGE clause is omitted

  2. Fit test rules.

    The fit test rules are applicable only to body groups, and hence fit test rules are specified only in the body group presentation rules table. At object time the RWCS applies the fit test rules to determine whether the designated body group can be presented on the page to which the report is currently positioned.

    However, even for body groups there are no fit test rules when the PAGE clause is omitted from the report description entry.

  3. First print line position rules.

    The first print line position rules specify where on the report medium the RWCS shall present the first print line of the given report group.

    The presentation rules tables do not specify where on the report medium the RWCS shall present the second and subsequent print lines (if any) of a report group. Certain general rules determine where the second and subsequent print lines of a report group shall be presented. Refer to the LINE NUMBER clause general rules for this information.

  4. Next group rules.

    The next group rules relate to the proper use of the NEXT GROUP clause.

  5. Final LINE-COUNTER setting rules.

    The terminal values that the RWCS places in LINE-COUNTER after presenting report groups are specified by the final LINE-COUNTER setting rules.

Parent topic: Presentation Rules Tables
Related information
Body Group Presentation Rules


Line Number Clause Notation

Column 1 of the presentation rules table uses a shorthand notation to describe the sequence of LINE NUMBER clauses that can appear in the description of a report group. The meaning of the abbreviations used in column 1 is as follows.

  1. The letter "A" represents one or more absolute LINE NUMBER clauses, none of which has the NEXT PAGE phrase, that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry.
  2. The letter "R" represents one or more relative LINE NUMBER clauses that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry.
  3. The letters "NP" represent one or more absolute LINE NUMBER clauses that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry with the phrase NEXT PAGE appearing in the first and only in the first LINE NUMBER clause.

    OSVS This entry can appear without a line number.

When two abbreviations appear together, they refer to a sequence of LINE NUMBER clauses that consists of the two specified consecutive sequences. For example "A R" refers to a report group description entry within which the "A" sequence (defined in rule 1 above) is immediately followed by the "R" sequence (defined in rule 2 above).

Parent topic: Presentation Rules Tables


Line Number Clause Sequence Substitutions

Where "A R" is shown to be a permissible sequence in the presentation rules table, "A" is also permissible and the same presentation rules are applicable.

Where "NP R" is shown to be a permissible sequence in the presentation rules table, "NP" is also permissible and the same presentation rules are applicable.

Parent topic: Presentation Rules Tables


Saved Next Group Integer Description

Saved next group integer is a data item that is addressable only by the RWCS. When an absolute NEXT GROUP clause specifies a vertical positioning value which cannot be accommodated on the current page, the RWCS stores that value in saved next group integer. After page advance processing, the RWCS positions the next body group using the value stored in saved next group integer.

Parent topic: Presentation Rules Tables


Report Heading Group Presentation Rules

The Report Heading Group Presentation Rulestable below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a report heading report group. The report heading group presentation rules are as follows:

  1. Upper limit rule.

    The first line number on which the report heading report group can be presented is the line number specified by the HEADING phrase of the PAGE clause.

  2. Lower limit rules.
    1. The last line number on which the report heading report group can be presented is the line number that is obtained by subtracting 1 from the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.
    2. The last line number on which the report heading report group can be presented is the line number specified by integer-1 of the PAGE clause.
  3. First print line position rules.
    1. The first print line of the report heading report group is presented on the line number specified by the integer of its LINE NUMBER clause.
    2. The first print line of the report heading report group is presented on the line number obtained by adding the integer of the first LINE NUMBER clause and the value obtained by subtracting 1 from the value of integer-2 of the HEADING phrase of the PAGE clause.
    3. The report heading report group is not presented.
    4. The first print line of the report heading report group is presented on the line number obtained by adding the content of its LINE-COUNTER (in this case, zero) to the integer of the first LINE NUMBER clause.
  4. Next group rules.
    1. The NEXT GROUP integer must be greater than the line number on which the final print line of the report heading report group is presented. In addition, the NEXT GROUP integer must be less than the line number specified by the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.
    2. The sum of the NEXT GROUP integer and the line number on which the final print line of the report heading report group is presented must be less than the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.
    3. NEXT GROUP PAGE signifies that the report heading report group is to be presented entirely by itself on the first page of the report. The RWCS processes no other report group while positioned to the first page of the report.
  5. Final LINE-COUNTER setting rules.
    1. After the report heading report group is presented, the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.
    2. After the report heading report group is presented, the RWCS places the sum of the NEXT GROUP integer and the line number on which the final print line of the report heading report group was presented into LINE-COUNTER as the final LINE-COUNTER setting.
    3. After the report heading report group is presented, the RWCS places zero into LINE-COUNTER as the final LINE-COUNTER setting.
    4. After the report heading report group is presented, the final LINE-COUNTER setting is the line number on which the final print line of the report heading report group was presented.
    5. LINE-COUNTER is unaffected by the processing of a non-printable report group.
Table 1. Report Heading Group Presentation Rules
1 |  | Applicable Rules2
 |  | If the PAGE Clause is specified |  |  |  |  | If the PAGE Clause is omitted
Sequence of LINE NUMBER Clauses3 | NEXT GROUP Clause | Upper Limit | Lower Limit | First Print Line Position | Next Group | Final LINE COUNTER Setting | First Print Line Position | Final LINE COUNTER Setting
AR | Absolute | 1 | 2a | 3a | 4a | 5a | Illegal Combination
AR | Relative | 1 | 2a | 3a | 4b | 5b | Illegal Combination 4
AR | NEXT PAGE | 1 | 2b | 3a | 4c | 5c | Illegal Combination 4
AR |  | 1 | 2a | 3a |  | 5d | Illegal Combination 4
R | Absolute | 1 | 2a | 3b | 4a | 5a | Illegal Combination
R | Relative | 1 | 2a | 3b | 4b | 5b | 3b | 5b
R | NEXT PAGE | 1 | 2b | 3b | 4c | 5c | Illegal Combination 5
R |  | 1 | 2a | 3b |  | 5d | 3d | 5d
 |  |  |  | 3c |  | 5e | 3c | 5e
Parent topic: Presentation Rules Tables
Related information
The NEXT GROUP Clause
Line Number Clause Notation
1 A blank entry in column 1 or column 2 indicates that the named clause is totally absent from the report group description entry.
2 A blank entry in an applicable rules column indicates the absence of the named rule for the given combination of LINE NUMBER and NEXT GROUP clauses.
3 See the section Line Number Clause Notation for a description of the abbreviations used in column 1.
4 See the section Line Number Clause Notation.
5 See the section The NEXT GROUP Clause.


Page Heading Group Presentation Rules

The table below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a page heading report group.

Table 1. Page Heading Group Presentation Rules
1 |  | Applicable Rules2
 |  | If the PAGE Clause is specified3
Sequence of LINE NUMBER Clauses4 | NEXT GROUP Clause | Upper Limit | Lower Limit | First Print Line Position | Next Group | Final LINE COUNTER Setting
AR | Absolute | 1 | 2 | 3a |  | 4a
R | Relative | 1 | 2 | 3b |  | 4a
 |  |  |  | 3c |  | 4b

The page heading group presentation rules are as follows:

  1. Upper limit rule.

    If a report heading report group has been presented on the page on which the page heading report group is to be presented, then the first line number on which the page heading report group can be presented is one greater than the final LINE-COUNTER setting established by the REPORT HEADING.

    Otherwise the first line number on which the page heading report group can be presented is the line number specified by the HEADING phrase of the PAGE clause.

  2. Lower limit rule.

    The last line number on which the page heading report group can be presented is the line number that is obtained by subtracting one from the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.

  3. First print line position rules.
    1. The first print line of the page heading report group is presented on the line number specified by the integer of its LINE NUMBER clause.
    2. If a report heading report group has been presented on the page on which the page heading report group is to be present, then the sum of the final LINE-COUNTER setting established by the report heading report group and the integer of the first LINE NUMBER clause of the page heading report group defines the line number on which the first print line of the page heading report group is presented.

      Otherwise the sum of the integer of the first LINE NUMBER clause of the page heading report group and the value obtained by subtracting one from the value of integer-2 of the HEADING phrase of the PAGE clause defines the line number on which the first print line of the page heading report group is presented.

    3. The page heading report group is not presented.
  4. Final LINE-COUNTER setting rules.
    1. The final LINE-COUNTER setting is the line number on which the final print line of the page heading report group was presented.
    2. LINE-COUNTER is unaffected by the processing of a nonprintable report group.
Parent topic: Presentation Rules Tables
Related information
The TYPE Clause
LINE NUMBER Clause Notation
1 A blank entry in column 1 or column 2 indicates that the named clause is totally absent from the report group description entry.
2 A blank entry in an applicable rules column indicates the absence of the named rule for the given combination of LINE NUMBER and NEXT GROUP clauses.
3 If the PAGE clause is omitted from the report description entry, then a page heading report group can not be defined. (See the section The TYPE Clause.)
4 See the section LINE NUMBER Clause Notation for a description of the abbreviations used in column 1.


Body Group Presentation Rules

The Body Group Presentation Rules table below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in control heading, detail, and control footing report groups. The body group presentation rules are as follows:

  1. Upper limit rule.

    The first line number on which a body group can be presented is the line number specified by the FIRST DETAIL phrase of the PAGE clause.

  2. Lower limit rules.

    The last line number on which a control heading report group or detail report group can be presented is the line number specified by the LAST DETAIL phrase of the PAGE clause.

    The last line number on which a control footing report group can be presented is the line number specified by the FOOTING phrase of the PAGE clause.

  3. Fit test rules.
    1. If the value in LINE-COUNTER is less than the integer of the first absolute LINE NUMBER clause, then the body group is presented on the page to which the report is currently positioned.

      If the value in LINE-COUNTER is not less than the integer of the first absolute LINE NUMBER clause, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not set, the body group shall be presented on the page to which the report is currently positioned. If saved next group integer was set, the RWCS moves the saved next group integer into LINE-COUNTER, resets saved next group integer to zero, and reapplies this rule.

    2. If a body group has been presented on the page to which the report is currently positioned, the RWCS computes a trial sum in a work location. The trial sum is computed by adding the content of LINE-COUNTER to the integers of all LINE NUMBER clauses of the report group. If the trial sum is not greater than the body group's lower limit integer, then the report group is presented on the current page. If the trial sum exceeds the body group's lower limit integer, then the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS reapplies this rule.

      If no body group has yet been presented on the page to which the report is currently positioned, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not so set, the body group shall be presented on the page to which the report is currently positioned.

      If saved next group integer was so set, the RWCS moves the saved next group integer into LINE-COUNTER, resets saved next group integer to zero, and computes a trial sum in a work location.

      The trial sum is computed by adding the content of LINE-COUNTER to the integer one and the integers of all but the first LINE NUMBER clause of the body group. If the trial sum is not greater than the body group's lower limit integer, then the body group is presented on the current page. If the trial sum exceeds the body group's lower limit integer, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS presents the body group on that page.

    3. If a body group has been presented on the page to which the report is currently positioned, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS reapplies this rule.

      If no body group has yet been presented on the page to which the report is currently positioned, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not so set, the body group shall be presented on the page to which the report is currently positioned. If saved next group integer was so set, the RWCS moves the saved next group integer into LINE-COUNTER and resets saved next group integer to zero.

      If then the value in LINE-COUNTER is less than the integer of the first absolute LINE NUMBER clause, the body group shall be presented on the page to which the report is currently positioned. Otherwise the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS presents the body group on that page.

  4. First print line position rules.
    1. The first print line of the body group is presented on the line number specified by the integer of its LINE NUMBER clause.
    2. If the value in LINE-COUNTER is equal to or greater than the line number specified by the FIRST DETAIL phrase of the PAGE clause, and if no body group has previously been presented on the page to which the report is currently positioned, then the first print line of the current body group is presented on the line immediately following the line indicated by the value contained on LINE-COUNTER.

      If the value in LINE-COUNTER is equal to or greater than the line number specified by the FIRST DETAIL phrase of the PAGE clause, and if a body group has previously been presented on the page to which the report is currently positioned, then the first print line of the current body group is presented on the line that is obtained by adding the content of LINE-COUNTER and the integer of the first LINE NUMBER clause of the current body group.

      If the value in LINE-COUNTER is less than the line number specified by the FIRST DETAIL phrase of the PAGE clause, then the first printer line of the body group is presented on the line specified by the FIRST DETAIL phrase.

    3. The body group is not presented.
    4. The sum of the content of LINE-COUNTER and the integer of the first LINE NUMBER clause defines the line number on which the first print line is presented.
  5. Next group rule.

    The integer of the absolute NEXT GROUP clause must specify a line number that is not less than that specified in the FIRST DETAIL phrase of the PAGE clause, and that is not greater than that specified in the FOOTING phrase of the PAGE clause.

  6. Final LINE-COUNTER setting rules.
    1. If the body group that has just been presented is a control footing report group and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases, the RWCS makes a comparison of the line number on which the final print line of the body group was presented and the integer of the NEXT GROUP clause. If the former is less than the latter, then the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting. If the former is equal to or greater than the latter, then the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting; in addition the RWCS places the NEXT GROUP integer into the saved next group integer location.

    2. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS computes a trial sum in a work location. The trial sum is computed by adding the integer of the NEXT GROUP clause to the line number on which the final print line of the body group was presented. If the sum is less than the line number specified by the FOOTING phrase of the PAGE clause, then the RWCS places that sum into LINE-COUNTER as the final LINE-COUNTER setting. If the sum is equal to or greater than the line number specified by the FOOTING phrase of the PAGE clause, then the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting.

    3. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting.

    4. The final LINE-COUNTER setting is the line number on which the final print line of the body group was presented.
    5. LINE-COUNTER is unaffected by the processing of a nonprintable body group.
    6. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS places the sum of the line number on which the final print line was presented and the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.

Table 1. Body Group Presentation Rules
1 |  | Applicable Rules 2
 |  | If the PAGE Clause is specified |  |  |  |  | If the PAGE Clause is omitted
Sequence of LINE NUMBER Clauses 3 | NEXT GROUP Clause | Upper Limit | Lower Limit | First Print Line Position | Next Group | Final LINE COUNTER Setting | First Print Line Position | Final LINE COUNTER Setting
AR | Absolute | 1 | 2 | 3a | 4a | 5 | Illegal Combination 4
AR | Relative | 1 | 2 | 3a | 4a |  | Illegal Combination 4
AR | NEXT PAGE | 1 | 2 | 3a | 4a |  | Illegal Combination 4
AR |  | 1 | 2 | 3a | 4a |  | Illegal Combination 4
R | Absolute | 1 | 2 | 3b | 4b | 5 | Illegal Combination 4
R | Relative | 1 | 2 | 3b | 4b |  | 4d | 6f
R | NEXT PAGE | 1 | 2 | 3b | 4b |  | Illegal Combination 4
R |  | 1 | 2 | 3b | 4b |  | 4d | 6f
NP R | Absolute | 1 | 2 | 3c | 4a | 5 | Illegal Combination 4
NP R | Relative | 1 | 2 | 3c | 4a |  | Illegal Combination 4
NP R | NEXT PAGE | 1 | 2 | 3c | 4a |  | Illegal Combination 4
NP R |  | 1 | 2 | 3c | 4a |  | Illegal Combination 4
 |  |  |  |  | 4c |  | 4c | 6e
Parent topic: Presentation Rules Tables
Related information
The LINE NUMBER Clause (Report Writer)
The NEXT GROUP Clause
1 A blank entry in column 1 or column 2 indicates that the named clause is totally absent from the report group description entry.
2 A blank entry in an applicable rules column indicates the absence of the named rule for the given combination of LINE NUMBER and NEXT GROUP clauses.
3 See the section LINE NUMBER Clause Notation for a description of the abbreviations used in column 1.
4 See the section The LINE NUMBER Clause.


Page Footing Presentation Rules

The table below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a PAGE FOOTING report group.

Table 1. Page Footing Presentation Rules
1 |  | Applicable Rules 2
 |  | If the PAGE Clause is specified 3
Sequence of LINE NUMBER Clauses 4 | NEXT GROUP Clause | Upper Limit | Lower Limit | First Print Line Position | Next Group | Final LINE COUNTER Setting
AR | Absolute | 1 | 2 | 3a | 4a | 5a
AR | Relative | 1 | 2 | 3a | 4b | 5b
AR |  | 1 | 2 | 3a |  | 5c
 |  |  |  | 3b |  | 5d

The page footing presentation rules are as follows:

  1. Upper limit rule.

    The first line number on which the page footing report group can be presented is the line number obtained by adding one to the value of integer-5 of the FOOTING phrase of the PAGE clause.

  2. Lower limit rule.

    The last line number on which the page footing report group can be presented is the line number specified by integer-1 of the PAGE clause.

  3. First print line position rules.
    1. The first print line of the page footing report group is presented on the line specified by the integer of its LINE NUMBER clause.
    2. The page footing report group is not presented.
  4. Next group rules.
    1. The NEXT GROUP integer must be greater than the line number on which the final print line of the page footing report group is presented. In addition, the NEXT GROUP integer must not be greater than the line number specified by integer-1 of the PAGE clause.
    2. The sum of the NEXT GROUP integer and the line number on which the final print line of the page footing report group is presented must not be greater than the line number specified by integer-1 of the PAGE clause.
  5. Final LINE-COUNTER setting rules.
    1. After the page footing report group is presented, the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.
    2. After the page footing report group is presented, the RWCS places the sum of the NEXT GROUP integer and the line number on which the final print line of the PAGE FOOTING report group was presented into LINE-COUNTER as the final LINE-COUNTER setting.
    3. After the PAGE FOOTING report group is presented the final LINE-COUNTER setting is the line number on which the final print line of the PAGE FOOTING report group was presented.
    4. LINE-COUNTER is unaffected by the processing of a nonprintable report group.
Parent topic: Presentation Rules Tables
Related information
The TYPE Clause
The LINE NUMBER Clause (Report Writer)
1 A blank entry in column 1 or column 2 indicates that the named clause is totally absent from the report group description entry.
2 A blank entry in an applicable rules column indicates the absence of the named rule for the given combination of LINE NUMBER and NEXT GROUP clauses.
3 If the PAGE clause is omitted from the report description entry, then a page footing report group can not be defined. (See the section The TYPE Clause.)
4 See the section LINE NUMBER Clause Notation for a description of the abbreviations used in column 1


Report Footing Presentation Rules

The Report Heading Group Presentation Rules table points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a report footing report group. The report footing presentation rules are as follows:

  1. Upper limit rules.
    1. If a page footing report group has been presented on the page to which the report is currently positioned, then the first line number on which the report footing report group can be presented is one greater than the final LINE- COUNTER setting established by the page footing report group.

      Otherwise the first line number on which the report footing report group can be presented is the line number obtained by adding one and the value of integer-5 of the PAGE clause.

    2. The first line number on which the report footing report group can be presented, is the line number specified by the HEADING phrase of the PAGE clause.
  2. Lower limit rule:

    The last line number on which the report footing report group can be presented is the line number specified by integer-1 of the PAGE clause.

  3. First print line position rules:
    1. The first print line of the report footing report group is presented on the line specified by the integer of its LINE NUMBER clause.
    2. If a page footing report group has been presented on the page to which the report is currently positioned, then the sum of the final LINE-COUNTER setting established by the page footing report group and the integer of the first LINE NUMBER clause of the report footing report group defines the line number on which the first print line of the report footing report group is presented. Otherwise the sum of the integer of the first LINE NUMBER clause of the report footing report group, and the line number specified by the value of integer-5 of the FOOTING phrase of the PAGE clause defines the line number on which the first print line of the report footing report group is presented.
    3. The NEXT PAGE phrase in the first absolute LINE NUMBER clause directs that the report footing report group is presented on a page on which no other report group has been presented. The first print line of the report footing report group is presented on the line number specified by the integer of its LINE NUMBER clause.
    4. If LINE IS NEXT PAGE is the only LINE clause in this report group, the first line of the report heading report group is presented on line HEADING integer-2.
    5. The sum of the content of LINE-COUNTER and the integer of the first LINE NUMBER clause defines the line number on which the first print line is presented.
    6. The report footing report group is not presented.
  4. Final LINE-COUNTER setting rules.
    1. The final LINE-COUNTER setting is the line number on which the final print line of the report footing report group is presented.
    2. LINE-COUNTER is unaffected by the processing of a nonprintable report group.
Table 1. Report Heading Group Presentation Rules
1 |  | Applicable Rules 2
 |  | If the PAGE Clause is specified |  |  |  |  | If the PAGE Clause is omitted
Sequence of LINE NUMBER Clauses 3 | NEXT GROUP Clause | Upper Limit | Lower Limit | First Print Line Position | Next Group | Final LINE COUNTER Setting | First Print Line Position | Final LINE COUNTER Setting
AR |  | 1a | 2 | 3a |  | 4a | Illegal Combination4
R |  | 1b | 2 | 3b |  | 4a | 3b | 4a
NP R |  | 1c | 2 | 3c |  | 4a | Illegal Combination 4
 |  |  |  | 3e |  | 4b | 3e | 4b
Parent topic: Presentation Rules Tables
Related information
The LINE NUMBER Clause (Report Writer)
1 A blank entry in column 1 or column 2 indicates that the named clause is totally absent from the report group description entry.
2 A blank entry in an applicable rules column indicates the absence of the named rule for the given combination of LINE NUMBER and NEXT GROUP clauses.
3 See the section LINE NUMBER Clause Notation for a description of the abbreviations used in column 1.
4 See the section The LINE NUMBER Clause.


The COLUMN NUMBER Clause (Report Writer)

The COLUMN NUMBER clause identifies a printable item and specifies the position of the item on a print line.

General Format

Syntax Rules

  1. The COLUMN NUMBER clause can be specified only at the elementary level in a report group. The COLUMN NUMBER clause, if present, must appear in or be subordinate to an entry that contains a LINE NUMBER clause.
  2. Within a given print line, the printable items should be defined in ascending column number order such that each printable item defined occupies a unique sequence of contiguous character positions.

    OSVS No restrictions on the sequence of COLUMN NUMBER clauses are enforced.

General Rules

  1. The COLUMN NUMBER clause indicates that the object of a SOURCE clause or the object of a VALUE clause or the sum counter defined by a SUM clause is to be presented on the print line. The absence of a COLUMN NUMBER clause indicates that the entry is not to be presented on a print line.
  2. Integer-1 specifies the column number of the leftmost character position of the printable item.
  3. The RWCS supplies space characters for all positions of a print line that are not occupied by printable items.
  4. The leftmost position of the print line is considered to be column number 1.
Parent topic: The Report Group Description Entry


Data-name (Report Writer)

A data-name specifies the name of the data item being described.

General Format

Syntax Rules

  1. In the report section data-name-1 need not appear in a data description entry.

General Rules

  1. In the Report Section, data-name-1 must be given in the following cases:
    1. When data-name-1 represents a report group to be referred to by a GENERATE or a USE statement in the procedure division.
    2. When reference is to be made to the sum counter in the procedure division or report section.
    3. When a DETAIL report group is referenced in the UPON phrase of the SUM clause.
    4. When data-name-1 is required to provide sum counter qualification.
Parent topic: The Report Group Description Entry


The GROUP INDICATE Clause

The GROUP INDICATE clause specifies that the associated printable item is presented only on the first occurrence of its report group after a control break or page advance.

General Format

Syntax Rules

  1. The GROUP INDICATE clause must be specified only in a DETAIL report group entry that defines a printable item.

General Rules

  1. If a GROUP INDICATE clause is specified, it causes the SOURCE or VALUE clause to be ignored and spaces supplied, except:
    1. On the first presentation of the DETAIL report group in the report, or:
    2. On the first presentation of the DETAIL report group after every page advance, or:
    3. On the first presentation of the DETAIL report group after every control group.
  2. If the report description entry specifies neither a PAGE clause nor a CONTROL clause, then a GROUP INDICATE printable item is presented the first time its DETAIL is presented after the INITIATE statement is executed. Thereafter spaces are supplied for indicated items with SOURCE or VALUE clauses.
Parent topic: The Report Group Description Entry


Level-Number (Report Writer)

The level-number indicates the position of a data item in the hierarchical structure of a report group.

General Format

Syntax Rules

  1. A level-number is required as the first element in each data description entry.
  2. Data description entries subordinate to an RD entry must have level-numbers 01 through 49 only.

General Rules

  1. The level-number 01 identifies the first entry in a report group.
  2. Multiple level 01 entries subordinate to a report description entry having the level indicator RD do not represent implicit redefinitions of the same area.
Parent topic: The Report Group Description Entry


The LINE NUMBER Clause (Report Writer)

The LINE NUMBER clause specifies vertical positioning information for its report group.

General Format

Syntax Rules

  1. Integer-1 and integer-2 must not exceed three significant digits in length.

    Neither integer-1 nor integer-2 can be specified in such a way as to cause any line of a report group to be presented outside the vertical subdivision of the page designated for that report group type, as defined by the PAGE clause. (See the section The PAGE Clause.)

    Integer-2 can be zero.

  2. Within a given report group description entry, an entry that contains a LINE NUMBER clause must not contain a subordinate entry that also contains a LINE NUMBER clause.
  3. Within a given report group description entry, all absolute LINE NUMBER clauses must precede all relative LINE NUMBER clauses.
  4. Within a given report group description entry, successive absolute LINE NUMBER clauses must specify integers that are in ascending order. The integers need not be consecutive.
  5. If the PAGE clause is omitted from a given report description entry, only relative LINE NUMBER clauses can be specified in any report group description entry in that report.
  6. Within a given report group description entry a NEXT PAGE phrase can appear only once and, if present, must be in the first LINE NUMBER clause in that report group description entry.
  7. A LINE NUMBER clause with the NEXT PAGE phrase can appear only in the description of body groups and in a REPORT FOOTING report group.
  8. Every entry that defines a printable item (see the section The COLUMN NUMBER Clause) must either contain a LINE NUMBER clause, or be subordinate to an entry that contains a LINE NUMBER clause.
  9. The first LINE NUMBER clause specified in a PAGE FOOTING report group must be an absolute LINE NUMBER clause.

General Rules

  1. A LINE NUMBER clause must be specified to establish each print line of a report group.
  2. The RWCS affects the vertical positioning specified by a LINE NUMBER clause, before presenting the print line established by that LINE NUMBER clause.
  3. Integer-1 specifies an absolute line number. An absolute line number specifies the line number on which the print line is presented.
  4. Integer-2 specifies a relative line number. If a relative LINE NUMBER clause is not the first LINE NUMBER clause in the report group description entry, then the line number on which its print line is presented is determined by calculating the sum of the line number on which the previous print line of the report group was presented and integer-2 of the relative LINE NUMBER clause. If integer-2 is zero, the line will be printed on the same line as the previous print line.

    If a relative LINE NUMBER clause is the first LINE NUMBER clause in the report group description entry, then the line number on which its print line is presented is determined by specified rules. (See the section Presentation Rules Tables.)

  5. The NEXT PAGE phrase specifies that the report group is to be presented beginning on the indicated line number on a new page. (See the section Presentation Rules Tables.) You need not specify integer-1 for the NEXT PAGE phrase.
Parent topic: The Report Group Description Entry
Related information
The PAGE Clause
The COLUMN NUMBER Clause (Report Writer)
Presentation Rules Tables


The NEXT GROUP Clause

The NEXT GROUP clause specifies information for vertical positioning of a page following the presentation of the last line of a report group.

General Format

Syntax Rules

  1. A report group entry must not contain a NEXT GROUP clause unless the description of that report group contains at least one LINE NUMBER clause unless you are running under DIALECT"MF". Under DIALECT"MF", you can specify the NEXT GROUP clause without a LINE NUMBER clause.
  2. Integer-1 and integer-2 must not exceed three significant digits in length.
  3. If the PAGE clause is omitted from the report description entry only a relative NEXT GROUP clause can be specified in any report group description entry in that report.
  4. The NEXT PAGE phrase of the NEXT GROUP clause must not be specified in a PAGE FOOTING report group.
  5. The NEXT GROUP clause must not be specified in a REPORT FOOTING report group or in a PAGE HEADING report group.

General Rules

  1. Any positioning of the page specified by the NEXT GROUP clause takes place after the presentation of the report group in which the clause appears. (See the section Presentation Rules Tables.)
  2. The RWCS uses the vertical positioning information supplied by the NEXT GROUP clause along with information from the TYPE and PAGE clauses, and the value in LINE-COUNTER, to determine a new value for LINE-COUNTER. (See the section Presentation Rules Tables.)
  3. The NEXT GROUP clause is ignored by the RWCS when it is specified on a CONTROL FOOTING report group that is at a level other than the highest level at which a control break is detected.
  4. The NEXT GROUP clause of a body group refers to the next body group to be presented, and therefore can affect the location at which the next body group is presented. The NEXT GROUP clause of a REPORT HEADING report group can affect the location at which the PAGE HEADING report group is presented. The NEXT GROUP clause of a PAGE FOOTING report group can affect the location at which the REPORT FOOTING report group is presented. (See the section Presentation Rules Tables.)
Parent topic: The Report Group Description Entry
Related information
Presentation Rules Tables


The SIGN Clause (Report Writer)

The SIGN clause specifies the position and the mode of representation of the operational sign when it is necessary to describe these properties explicitly.

General Format

Syntax Rules

  1. The SIGN clause can be specified only for a numeric data description entry whose PICTURE contains the character "S".
  2. The numeric data description entries to which the SIGN clause applies must be described, implicitly or explicitly, as USAGE IS DISPLAY.
  3. When the SIGN clause is included in a report group description entry, the SEPARATE CHARACTER phrase must be specified.

General Rules

  1. The optional SIGN clause, if present, specifies the position and the mode of representation of the operational sign for the numeric data description entry to which it applies. The SIGN clause applies only to numeric data description entries whose PICTURE contains the character "S"; The "S" indicates the presence of, but neither the representation nor, necessarily, the position of the operational sign.
  2. A numeric data description entry whose PICTURE contains the character "S", but to which no optional SIGN clause applies, has an operational sign, but neither the representation nor, necessarily, the position of the operational sign is specified by the character "S". In this (default) case, General Rule 3 does not apply to such signed numeric data items. The representation of the default operational sign is defined in the section Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.
  3. Since a SIGN clause in a report group description entry must specify the SEPARATE CHARACTER phrase, then:
    1. The operational sign will be presumed to be the leading (or, respectively, trailing) character position of the elementary numeric data item; this character position is not a digit position.
    2. The letter "S" in a PICTURE character-string is counted in determining the size of the item (in terms of standard data format characters).
    3. The operational signs for positive and negative are the standard data format characters "+" , and "–", respectively.
  4. Every numeric data description entry whose PICTURE contains the character "S" is a signed numeric data description entry. If a SIGN clause applies to such an entry and conversion is necessary for purposes of computation or comparisons, conversion takes place automatically.
Parent topic: The Report Group Description Entry
Related information
Selection of Character Representation and Radix


The SOURCE Clause (Report Writer)

The SOURCE clause identifies the sending data item that is moved to an associated printable item defined in a report group description entry.

General Format

Syntax Rules

  1. Identifier-1 can be defined in any section of the data division or be a function-identifier. If identifier-1 is a report section item it must be a:
    1. PAGE-COUNTER, or:
    2. LINE-COUNTER, or:
    3. Sum counter that is part of the report within which the SOURCE clause appears.
  2. Identifier-1 specifies the sending data item of the implicit MOVE statement that the RWCS executes to move the content of the data item referenced by identifier-1 to the printable item. Identifier-1 must be defined such that it conforms to the rules for sending items in the MOVE statement. (See the section The MOVE Statement.)

General Rules

  1. The RWCS formats the print lines of a report group just prior to presenting the report group. (See the section The TYPE Clause.) It is at this time that the implicit MOVE statements specified by SOURCE clauses are executed by the RWCS.
Parent topic: The Report Group Description Entry
Related information
The MOVE Statement
The TYPE Clause


The SUM Clause (Report Writer)

The SUM clause establishes a sum counter and names the data items to be summed.

General Format

Syntax Rules

  1. The data item that is the subject of the report group description entry in which the SUM clause appears must not be defined as alphabetic. Identifier-1 must reference a numeric data item. If identifier-1 is defined in the report section, identifier-1 must reference a sum counter.

    If the UPON phrase is omitted, any identifiers in the associated SUM clause which are themselves sum counters must be defined either in the same report group that contains this SUM clause or in a report group which is at a lower level in the control hierarchy of this report.

    If the UPON phrase is specified, any identifiers in the associated SUM clause must not be sum counters.

  2. Data-name-1 must be the name of a DETAIL report group described in the same report as the CONTROL FOOTING report group in which the SUM clause appears. Data-name-1 can be qualified by a report-name.
  3. A SUM clause can appear only in the description of a CONTROL FOOTING report group.
  4. Data-name-2 must be one of the data-names specified on the CONTROL clause for this report. Data-name-2 must not be a lower level control than the associated control for the report group in which the RESET phrase appears.

    FINAL, if specified in the RESET phrase, must also appear in the CONTROL clause for this report.

    OSVS This rule is not enforced.

  5. The highest permissible qualifier of a sum counter is the report-name.

General Rules

  1. The SUM clause establishes a sum counter. The sum counter is a numeric data item with an optional sign. At object time, the RWCS adds into the sum counter the value in each data item referenced by identifier-1. This addition is consistent with the rules for arithmetic statements. (See the sections Arithmetic Statements and Overlapping Operands.)
  2. The size of the sum counter is equal to the number of receiving character positions specified by the PICTURE clause that accompanies the SUM clause in the description of the elementary item.
  3. Only one sum counter exists for an elementary report entry regardless of the number of SUM clauses specified in the elementary report entry.
  4. If the elementary report entry for a printable item contains a SUM clause, the sum counter serves as a source data item. The RWCS moves the data contained in the sum counter, according to the rules of the MOVE statement, to the printable item for presentation.
  5. If a data-name appears as the subject of an elementary report entry that contains a SUM clause, the data-name is the name of the sum counter; the data-name is not the name of the printable item that the entry can also define.
  6. It is permissible for Procedure Division statements to alter the contents of sum counters.
  7. Addition of the values of the data items referenced by identifiers into sum counters is performed by the report writer control system during the execution of GENERATE and TERMINATE statements. There are three categories of sum counter incrementing called subtotalling, crossfooting, and rolling forward. Subtotalling is accomplished only during execution of GENERATE statements and after any control break processing but before processing of the DETAIL report group. (See the section The GENERATE Statement.) Crossfooting and rolling forward are accomplished during the processing of CONTROL FOOTING report groups. (See the section The TYPE Clause.)
  8. The UPON phrase provides the capability to accomplish selective subtotalling for the DETAIL report groups named in the phrase.
  9. The RWCS adds each individual addend into the sum counter at a time that depends upon the characteristics of the addend.
    1. When the addend is a sum counter defined in the same CONTROL FOOTING report group, then the accumulation of that addend into the sum counter is termed crossfooting.

      Crossfooting occurs when a control break takes place and at the time the CONTROL FOOTING report group is processed.

      Crossfooting is performed according to the sequence in which sum counters are defined in the CONTROL FOOTING report group. That is, all crossfooting into the first sum counter defined in the CONTROL FOOTING report group is completed, and then all crossfooting into the second sum counter defined in the CONTROL FOOTING report group is completed.

      When one of the addends is the sum counter defined by the data description entry in which that SUM clause appears, the initial value of that sum counter at the time of summation is used in the summing operation.

    2. When the addend is a sum counter defined in a lower level CONTROL FOOTING report group, then the accumulation of that addend into the sum counter is termed rolling forward. A sum counter in a lower level CONTROL FOOTING report group is rolled forward when a control break occurs and at the time that the lower level CONTROL FOOTING report group is processed.
    3. When the addend is not a sum counter the accumulation into a sum counter of such an addend is called subtotalling. If the SUM clause contains the UPON phrase, the addends are subtotalled when a GENERATE statement for the designated DETAIL report group is executed. If the SUM clause does not contain the UPON phrase, the addends which are not sum counters are subtotalled when any GENERATE data-name statement is executed for the report in which the SUM clause appears.
  10. If two or more of the identifiers specify the same addend, then the addend is added into the sum counter as many times as the addend is referenced in the SUM clause. It is permissible for two or more of the data-names to specify the same DETAIL report group. When a GENERATE data-name statement for such a DETAIL report group is given, the incrementing occurs repeatedly, as many times as data-name appears in the UPON phrase.
  11. The subtotalling that occurs when a GENERATE report-name statement is executed is discussed in the appropriate paragraph. (See the section The GENERATE Statement.)
  12. In the absence of an explicit RESET phrase, the report writer control system will set a sum counter to zero at the time that the report writer control system is processing the CONTROL FOOTING report group in which the sum counter is defined. If an explicit RESET phrase is specified, then the report writer control system will set the sum counter to zero at the time that the report writer control system is processing the designated level of the control hierarchy. (See the section The TYPE Clause.)

    Sum counters are initially set to zero by the report writer control system during the execution of the INITIATE statement for the report containing the sum counter.

Parent topic: The Report Group Description Entry
Related information
Arithmetic Statements
Overlapping Operands
The GENERATE Statement
The TYPE Clause


The TYPE Clause

The TYPE clause specifies the particular type of report group that is described by this entry and indicates the time at which the report group is to be processed by the RWCS.

General Format

Syntax Rules

  1. RH is an abbreviation for REPORT HEADING. PH is an abbreviation for PAGE HEADING. CH is an abbreviation for CONTROL HEADING. DE is an abbreviation for DETAIL. CF is an abbreviation for CONTROL FOOTING. PF is an abbreviation for PAGE FOOTING. RF is an abbreviation for REPORT FOOTING.
  2. REPORT HEADING, PAGE HEADING, CONTROL HEADING FINAL, CONTROL FOOTING FINAL, PAGE FOOTING, and REPORT FOOTING report groups can each appear no more than once in the description of a report.
  3. PAGE HEADING and PAGE FOOTING report groups can be specified only if a PAGE clause is specified in the corresponding report description entry.
  4. Data-name-1, data-name-2, and FINAL, if present, must be specified in the CONTROL clause of the corresponding report description entry.

    OSVS This rule is not enforced with regard to FINAL.

    At most, one CONTROL HEADING report group and one CONTROL FOOTING report group can be specified for each data-name or FINAL in the CONTROL clause of the report description entry. However, neither a CONTROL HEADING report group nor a CONTROL FOOTING report group is required for a data-name or FINAL specified in the CONTROL clause of the report description entry.

  5. In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, AND REPORT FOOTING report groups, SOURCE clauses and USE statements must not reference any of the following:
    1. Group data items containing a control data item.
    2. Data items subordinate to a control data item.
    3. A redefinition or renaming of any part of a control data item.

    In PAGE HEADING and PAGE FOOTING report groups, SOURCE clauses and USE statements must not reference control data-names.

  6. When a GENERATE report-name statement is specified in the Procedure Division, the corresponding report description entry must include no more than one DETAIL report group. If no GENERATE data-name statements are specified for such a report, a DETAIL report group is not required.
  7. The description of a report must include at least one body group.

General Rules

  1. DETAIL report groups are processed by the RWCS as a direct result of GENERATE statements. If a report group is other than TYPE DETAIL its processing is an automatic RWCS function.
  2. The REPORT HEADING phrase specifies a report group that is processed by the RWCS only once, per report, as the first report group of that report. The REPORT HEADING report group is processed during the execution of the chronologically first GENERATE statement for that report.
  3. The PAGE HEADING phrase specifies a report group that is processed by the RWCS as the first report group on each page of that report except under the following conditions:
    1. A PAGE HEADING report group is not processed on a page that is to contain only a REPORT HEADING report group or only a REPORT FOOTING report group.
    2. A PAGE HEADING report group is processed as the second report group on a page when it is preceded by a REPORT HEADING report group that is not to be presented on a page by itself.

    (See the section Presentation Rules Tables.)

  4. The CONTROL HEADING phrase specifies a report group that is processed by the RWCS at the beginning of a control group for a designated control data-name or, in the case of FINAL, is processed during the execution of the chronologically first GENERATE statement for that report. During the execution of any GENERATE statement at which the RWCS detects a control break, any CONTROL HEADING report groups associated with the highest control level of the break and lower levels are processed.
  5. The DETAIL phrase specifies a report group that is processed by the RWCS when a corresponding GENERATE statement is executed.
  6. The CONTROL FOOTING phrase specifies a report group that is processed by the RWCS at the end of a control group for a designated control data-name.

    In the case of FINAL, the CONTROL FOOTING report group is processed only once per report as the last body group of that report. During the execution of any GENERATE statement in which the RWCS detects a control break, any CONTROL FOOTING report group associated with the highest level of the control break or more minor levels is presented. All CONTROL FOOTING report groups are presented during the execution of the TERMINATE statement if there has been at least one GENERATE statement executed for the report. (See the section The TERMINATE Statement.)

  7. The PAGE FOOTING phrase specifies a report group that is processed by the RWCS as the last report group on each page except under the following conditions:
    1. A PAGE FOOTING report group is not processed on a page that is to contain only a REPORT HEADING report group or only a REPORT FOOTING report group.
    2. A PAGE FOOTING report group is processed as the second to last report group on a page when it is followed by a REPORT FOOTING report group that is not to be processed on a page by itself.

    (See the section Presentation Rules Tables.)

  8. The REPORT FOOTING phrase specifies a report group that is processed by the RWCS only once per report and as the last report group of that report. The REPORT FOOTING report group is processed during the execution of a corresponding TERMINATE statement, if there has been at least one GENERATE statement executed for the report. (See the section The TERMINATE Statement.)
  9. The sequence of steps that the RWCS executes when it processes a REPORT HEADING, PAGE HEADING, CONTROL HEADING, PAGE FOOTING, or REPORT FOOTING report group is described below.
    1. If a USE BEFORE REPORTING procedure references the data-name of the report group, the USE procedure is executed.
    2. If a SUPPRESS statement has been executed or if the report group is not printable, no further processing is done for the report group.
    3. If a SUPPRESS statement has not been executed and the report group is printable, the RWCS formats the print lines and presents the report group according to the presentation rules for that type of report group. (See the section Presentation Rules Tables.)
  10. The sequence of steps that the RWCS executes when it processes a CONTROL FOOTING report group is described below.

    The GENERATE rules specify that when a control break occurs, the RWCS produces the CONTROL FOOTING report groups beginning at the minor level, and proceeding upwards, through the level at which the highest control break was sensed. In this regard, it should be noted that even though no CONTROL FOOTING report group has been defined for a given control data-name, the RWCS will still have to execute the step described in rule 10f below if a RESET phrase in the report description specifies that control data-name.

    1. Sum counters are crossfooted; that is, all sum counters defined in this report group that are operands of SUM clauses in the same report group are added to their sum counters. (See the section The SUM Clause.)
    2. Sum counters are rolled forward; that is, all sum counters defined in the report group that are operands of SUM clauses in higher level CONTROL FOOTING report groups are added to the higher level sum counters. (See the section The SUM Clause.)
    3. If a USE BEFORE REPORTING procedure references the data-name of the report group the USE procedure is executed.
    4. If a SUPPRESS statement has been executed or if the report group is not printable, the RWCS next executes the step described in rule 10e below.
    5. If a SUPPRESS statement has not been executed and the report group is printable, the RWCS formats the print lines and presents the report group according to the presentation rules of CONTROL FOOTING report groups.
    6. Then the RWCS resets those sum counters that are to be reset when the RWCS processes this level in the control hierarchy. (See the section The SUM Clause.)
  11. The DETAIL report group processing that the RWCS system executes in response to a GENERATE data-name statement is described in rules 11a through 11e below.

    When the description of a report includes exactly one DETAIL report group, the detail-related processing that the RWCS executes in response to a GENERATE report-name statement is described in rules 11a through 11e below. These steps are performed as though a GENERATE data-name statement were being executed.

    When the description of a report includes no DETAIL report groups, the detail-related processing that the RWCS executes in response to a GENERATE report-name statement is described in rule 11a below. This step is performed as though the description of the report included exactly one DETAIL report group, and a GENERATE data-name statement were being executed.

    1. The RWCS performs any subtotalling that has been designated for the DETAIL report group. (See the section The SUM Statement.)
    2. If a USE BEFORE REPORTING procedure refers to the data-name of the report group, the USE procedure is executed.
    3. If a SUPPRESS statement has been executed or if the report group is not printable no further processing is done for the report group.
    4. If the DETAIL report group is being processed as a consequence of a GENERATE report-name statement, no further processing is done for the report group.
    5. If neither 11c nor 11d above applies, the RWCS formats the print lines and presents the report group according to the presentation rules for DETAIL report groups. (See the section Presentation Rules Tables.)
  12. When the RWCS is processing a CONTROL HEADING, CONTROL FOOTING, or DETAIL report group, as described in General Rules 9, 10, and 11, the RWCS may have to interrupt the processing of that body group after determining that the body group is to be presented, and execute a page advance ( and process PAGE FOOTING and PAGE HEADING report groups) before actually presenting the body group.
  13. During control break processing, the values of control data items that the RWCS used to detect a given control break are referred to as prior values.
    1. During control break processing of a CONTROL FOOTING report group, any references to control data items in a USE procedure or SOURCE clause associated with that CONTROL FOOTING report group are supplied with prior values.
    2. When a TERMINATE statement is executed, the RWCS makes the prior control data item values available to SOURCE clause or USE procedure references in CONTROL FOOTING and REPORT FOOTING report groups as though a control break had been detected in the highest control data-name.
    3. All other data item references in report groups and their USE procedures access the current values that are contained in the data items at the time the report group is processed.
Parent topic: The Report Group Description Entry
Related information
Presentation Rules Tables
The TERMINATE Statement
The SUM Clause (Report Writer)
The SUM Function


The USAGE Clause

The USAGE clause specifies the format of a data item in the computer storage.

General Format

Syntax Rules

  1. The USAGE clause can be written in any data description entry.
  2. If the USAGE clause is written in the data description entry for a group item, it can also be written in the data description entry for a subordinate elementary item or group item.
  3. The USAGE clause for a report group item can specify only USAGE IS DISPLAY.

General Rules

  1. If the USAGE clause is written at a group level, it applies to each elementary item in the group.
  2. The USAGE clause specifies the manner in which a data item is represented in the storage of a computer. It does not affect the use of the data item, although the specifications for some statements in the Procedure Division can restrict the USAGE clause of the operands referred to. The USAGE clause can affect the radix or type of character representation of the item.
  3. The USAGE IS DISPLAY clause indicates that the format of the data is a standard data format.
  4. If the USAGE clause is not specified for an elementary item, or for any group to which the item belongs, the usage is implicitly DISPLAY.
Parent topic: The Report Group Description Entry


The VALUE Clause (Report Writer)

The VALUE clause defines the value of Report Section printable items.

General Format

Syntax Rules

  1. A signed numeric literal must have associated with it a signed numeric PICTURE character-string.
  2. A numeric literal in a VALUE clause of an item must have a value which is within the range of values indicated by the PICTURE clause, and must not have a value which would require truncation of nonzero digits. A nonnumeric literal in a VALUE clause of an item must not exceed the size indicated by the PICTURE clause.

General Rules

  1. The VALUE clause must not conflict with other clauses in the data description of the item or in the data description in the hierarchy of the item. The following rules apply:
    1. If the category of the item is numeric, literal-1 in the VALUE clause must be numeric.
    2. If the category of the item is alphabetic, alphanumeric, alphanumeric edited, or numeric edited, literal-1 in the VALUE clause must be a nonnumeric literal. The literal is aligned in the data item as if the data item had been described as alphanumeric (See the section Standard Alignment Rules). Editing characters in the PICTURE clause are included in determining the size of the data item but have no effect on initialization of the data item (see the section The PICTURE Clause. Therefore, the value for an edited item must be specified in an edited form.
    3. Initialization is not affected by any BLANK WHEN ZERO or JUSTIFIED clause that can be specified.
  2. In the report section, if the elementary report entry containing the VALUE clause does not contain a GROUP INDICATE clause, then the printable item will assume the specified value each time its report group is printed. However, when the GROUP INDICATE clause is also present, the specified value will be presented only when certain object item conditions exist (see the section The GROUP INDICATE Clause).
Parent topic: The Report Group Description Entry
Related information
The PICTURE Clause
The GROUP INDICATE Clause
Standard Alignment Rules


Procedure Division

  • General Description
    The Procedure Division contains declarative procedures when the USE BEFORE REPORTING statement from the report writer module is present in a COBOL source program. Shown below is the general format of the Procedure Division when the USE BEFORE REPORTING statement is present.
  • The CLOSE Statement
    The CLOSE statement terminates the processing of reel/units and files with optional rewind and/or lock or removal where applicable.
  • The GENERATE Statement
    The GENERATE statement directs the RWCS to produce a report in accordance with the Report Description specified in the Report Section of the Data Division.
  • The INITIATE Statement
    The INITIATE statement causes the RWCS to begin the processing of a report.
  • The OPEN Statement (Report Writer)
    See the section The OPEN Statement.
  • The SUPPRESS Statement
    The SUPPRESS statement causes the RWCS to inhibit the presentation of a report group.
  • The TERMINATE Statement
    The TERMINATE statement causes the RWCS to complete the processing of the specified reports.
  • The USE BEFORE REPORTING Statement
    The USE BEFORE REPORTING statement specifies Procedure Division statements that are executed just before a report group named in the Report Section of the Data Division of this program, and optionally a contained program, is presented.
Parent topic: Report Writer


General Description

The Procedure Division contains declarative procedures when the USE BEFORE REPORTING statement from the report writer module is present in a COBOL source program. Shown below is the general format of the Procedure Division when the USE BEFORE REPORTING statement is present.

General Format:

Parent topic: Procedure Division


The CLOSE Statement

The CLOSE statement terminates the processing of reel/units and files with optional rewind and/or lock or removal where applicable.

General Format

Syntax Rules

  1. The files referenced in the CLOSE statement need not all have the same organization or access.

General Rules

Except where otherwise stated in the general rules below, the terms "reel" and "unit" are equivalent and completely interchangeable in the CLOSE statement. Treatment of sequential mass storage files is logically equivalent to the treatment of a file on tape or analogous sequential media. Treatment of a file contained in a multiple file tape environment is logically equivalent to the treatment of a sequential single-reel/unit file if the file is wholly contained on one reel.

  1. A CLOSE statement can only be executed for a file in an open mode.
  2. For the purpose of showing the effect of various types of CLOSE statements as applied to various storage media, all report files are divided into the following categories:
    1. Non-reel/unit. A file whose output medium is such that the concepts of rewind and reels/units have no meaning.
    2. Sequential single-reel/unit. A sequential file that is entirely contained on one reel/unit.
    3. Sequential multi-reel/unit. A sequential file that is contained on more than one reel/unit.
  3. The results of executing each type of CLOSE for each category of file are summarized in the table below.
    Table 1. Relationship of Categories of Files and the Formats of the CLOSE Statements
    CLOSE Statement Format | File Category
    Non-Reel/Unit | Sequential Single-Reel/Unit | Sequential Multi-Reel/Unit
    CLOSE | C | C,G | A,C,G
    CLOSE WITH LOCK | C,E | C,E,G | A,C,E,G
    CLOSE WITH NO REWIND | C,H | B,C | A,B,C
    CLOSE WITH REEL/UNIT | F | F,G | F,G
    CLOSE REEL/UNIT FOR REMOVAL | F | D,F,G | D,F,G

    The definitions of the symbols in the table are given below.

    • A. Effect on Previous Reels/Units for an Output Report File

      All reels/units in the report file prior to the current reel/unit are closed except those reels/units controlled by a prior CLOSE REEL/UNIT statement.

    • B. No Rewind of Current Reel

      The reel/unit is left in its current position.

    • C. Close Output Report File

      If label records are specified for the report file, the labels are processed according to the implementor's standard label convention. The behavior of the CLOSE statement when label records are specified but not present, or when records are not specified but are present, is undefined. Closing operations specified by the implementor are executed. If label records are not specified for the report file, label processing does not take place but other closing operations specified by the implementor are executed.

    • D. Reel/Unit Removal

      The current reel or unit is rewound, when applicable, and the reel or unit is logically removed from the run unit; however, the reel or unit can be accessed again, in its proper order of reels or units in the report file, if a CLOSE statement without the REEL or UNIT phrase is subsequently executed for this report file followed by the execution of an OPEN statement for the report file.

    • E. File Lock

      The report file is locked and cannot be opened again during this execution of this run unit.

    • F. Close Reel/Unit

      Output Report File (Reel/Unit Media):

      The following operations take place:

      1. The standard ending reel/unit label procedure is executed.
      2. A reel/unit swap. The current volume pointer is updated to point to the new reel/unit.
      3. The standard beginning reel/unit label procedure is executed.
      4. The next executed write operation that references that file directs the next logical data record to the next reel/unit of the file.

      Output Report File (Non-Reel/Unit Media):

      Execution of this statement is considered successful. The file remains in the open mode, and no action takes place except as specified in general rule 4.

    • G. Rewind

      The current reel or analogous device is positioned at its physical beginning.

    • H. Optional Phrases Ignored

      The CLOSE statement is executed as if none of the optional phrases is present.

  4. The execution of the CLOSE statement causes the value of the I/O status associated with file-name-1 to be updated.
  5. All reports associated with a report file that have been initiated must be ended with the execution of a TERMINATE statement before a CLOSE statement is executed for that report file.
  6. Following the successful execution of a CLOSE statement without the REEL or UNIT phrase, the report file is removed from the open mode, and the report file is no longer associated with the file connector.
  7. If more than one file-name-1 is specified in a CLOSE statement, the result of executing this CLOSE statement is the same as if a separate CLOSE statement had been written for each file-name-1 in the same order as specified in the CLOSE statement.
Parent topic: Procedure Division


The GENERATE Statement

The GENERATE statement directs the RWCS to produce a report in accordance with the Report Description specified in the Report Section of the Data Division.

General Format

Syntax Rules

  1. Data-name-1 must name a TYPE DETAIL report group and can be qualified by a report-name.
  2. Report-name-1 can be used only if the referenced report description contains:
    1. A CONTROL clause, and
    2. Not more than one DETAIL report group, and
    3. At least one body group.

General Rules

  1. In response to a GENERATE report-name-1 statement, the RWCS performs summary processing. If all of the GENERATE statements that are executed for a report are of the form GENERATE report-name-1, then the report that is produced is called a summary report.
  2. In response to a GENERATE data-name-1 statement, the RWCS performs detail processing that includes certain processing that is specific for the DETAIL report group designated by the GENERATE statement. Normally, the execution of a GENERATE data-name-1 statement causes the RWCS to present the designated DETAIL report group.
  3. During the execution of the chronologically first GENERATE statement for a given report, the RWCS saves the values in the control data items. During the execution of the second and subsequent GENERATE statements for the same report, and until a control break is detected, the RWCS utilizes this set of control values to determine whether a control break has occurred. When a control break occurs, the RWCS saves the new set of control values, which it thereafter uses to sense for a control break until another control break occurs.
  4. During the report presentation, an automatic function of the RWCS is to process PAGE HEADING and PAGE FOOTING report groups, if defined, when the RWCS must advance the report to a new page for the purpose of presenting a body group. (See the section Presentation Rules Tables)
  5. When the chronologically first GENERATE statement for a given report is executed, the RWCS processes, in order, the report groups that are named below, provided that such report groups are defined in the report description. The RWCS also processes PAGE HEADING and PAGE FOOTING report groups as described in General Rule 4. The actions taken by the RWCS when it processes each type of report group are explained under the appropriate paragraph. (See the section The TYPE Clause.)
    1. The REPORT HEADING report group is processed.
    2. The PAGE HEADING report group is processed.
    3. All CONTROL HEADING report groups are processed from major to minor.
    4. If a GENERATE data-name-1 statement is being executed, the processing for the designated DETAIL report group is performed. If a GENERATE report-name-1 statement is being executed, certain of the steps that are involved in the processing of a DETAIL report group are performed. (See the section The TYPE Clause.)
  6. When a GENERATE statement other than the chronologically first is executed for a given report, the RWCS performs the steps enumerated below, as applicable. The RWCS also processes PAGE HEADING and PAGE FOOTING report groups as described in General Rule 4. The actions taken by the RWCS when it processes each type of report group are explained under the appropriate paragraph. (See the section The TYPE Clause.)
    1. Sense for control break. The rules for determining the equality of control data items are the same as those specified for relation conditions. If a control break has occurred then:
      1. Enable the CONTROL FOOTING USE procedures and CONTROL FOOTING SOURCE clauses to access the control data item values that the RWCS used to detect a given control break. (See the section The TYPE Clause.)
      2. Process the CONTROL FOOTING report groups in the order minor to major. Only CONTROL FOOTING report groups that are not more major than the highest level at which a control break occurred are processed.
      3. Process the CONTROL HEADING report groups in the order major to minor. Only the CONTROL HEADING report groups that are not more major than the highest level at which a control break occurred are processed.
    2. If a GENERATE data-name-1 statement is being executed, the processing for the designated DETAIL report group is performed. If a GENERATE report-name-1 statement is being executed, certain of the steps that are involved in the processing of a DETAIL report group are performed. (See the section The TYPE Clause.)
  7. GENERATE statements for a report can be executed only after an INITIATE statement for the report has been executed and before a TERMINATE statement for the report has been executed.
Parent topic: Procedure Division
Related information
Presentation Rules Tables
The TYPE Clause


The INITIATE Statement

The INITIATE statement causes the RWCS to begin the processing of a report.

General Format

Syntax Rules

  1. Report-name-1 must be defined by a report description entry in the report section of the Data Division.

General Rules

  1. The INITIATE statement performs the following initialization functions for each named report:
    1. All sum counters are set to zero.
    2. LINE-COUNTER is set to zero.
    3. PAGE-COUNTER is set to one.
  2. The INITIATE statement does not place the file associated with the report in the open mode; therefore, an OPEN statement with either the OUTPUT phrase or the EXTEND phrase for the file must be executed prior to the execution of the INITIATE statement.
  3. A subsequent INITIATE statement for report-name-1 must not be executed unless an intervening TERMINATE statement has been executed for report-name-1.
  4. If more than one report-name is specified in an INITIATE statement, the result of executing this INITIATE statement is the same as if a separate INITIATE statement had been written for each report-name in the same order as specified in the INITIATE statement.
Parent topic: Procedure Division


The OPEN Statement (Report Writer)

See the section The OPEN Statement.

Additional Syntax Rules:

  1. A report file must have sequential organization.
  2. The OPEN statement for a report file must contain only the OUTPUT phrase or the EXTEND phrase.

Additional General Rules:

  1. The OPEN statement for a report file must be executed prior to the execution of an INITIATE statement for any reports contained in the file.
Parent topic: Procedure Division
Related information
The OPEN Statement


The SUPPRESS Statement

The SUPPRESS statement causes the RWCS to inhibit the presentation of a report group.

General Format

Syntax Rules

  1. The SUPPRESS statement can only appear in a USE BEFORE REPORTING procedure.

General Rules

  1. The SUPPRESS statement inhibits presentation only for the report group named in the USE procedure in which the SUPPRESS statement appears.
  2. The SUPPRESS statement must be executed each time the presentation of the report group is to be inhibited.
  3. When the SUPPRESS statement is executed, the RWCS is instructed to inhibit the processing of the following report group functions:
    1. The presentation of the print lines of the report group.
    2. The processing of all LINE clauses in the report group.
    3. The processing of the NEXT GROUP clause in the report group.
    4. The adjustment of LINE-COUNTER.
  4. OSVS The SUPPRESS PRINTING function can also be achieved by moving the value 1 to the special register PRINT- SWITCH.

    The statement

         MOVE 1 TO PRINT-SWITCH

    has exactly the same effect as the statement

         SUPPRESS PRINTING
Parent topic: Procedure Division


The TERMINATE Statement

The TERMINATE statement causes the RWCS to complete the processing of the specified reports.

General Format

Syntax Rules

  1. Report-name-1 must be defined by a report description entry in the Report Section of the Data Division.

General Rules

  1. The TERMINATE statement causes the RWCS to produce all the CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING report group. Then the REPORT FOOTING report group is produced. The RWCS makes the prior set of control data item values available to the CONTROL FOOTING and REPORT FOOTING SOURCE clauses and USE procedures, as though a control break has been sensed in the most major control data-name.
  2. If no GENERATE statements have been executed for a report during the interval between the execution of an INITIATE statement and a TERMINATE statement, for that report, the TERMINATE statement does not cause the RWCS to produce any report groups or perform any of the related processing.
  3. During report presentation, an automatic function of the RWCS is to process PAGE HEADING and PAGE FOOTING report groups, if defined, when the RWCS must advance the report to a new page for the purpose of presenting a body group. (See the section Presentation Rules Tables.)
  4. The TERMINATE statement cannot be executed for a report unless the TERMINATE statement was chronologically preceded by an INITIATE statement for that report and for which no TERMINATE statement has yet been executed.
  5. If more than one report-name is specified in a TERMINATE statement, the result of executing this TERMINATE statement is the same as if a separate TERMINATE statement had been written for each report-name in the same order as specified in the TERMINATE statement.
  6. The TERMINATE statement does not close the file with which the report is associated; a CLOSE statement for the file must be executed. Every report that is in an initiated condition must be terminated before a CLOSE statement is executed for the associated file.
Parent topic: Procedure Division
Related information
Presentation Rules Tables


The USE BEFORE REPORTING Statement

The USE BEFORE REPORTING statement specifies Procedure Division statements that are executed just before a report group named in the Report Section of the Data Division of this program, and optionally a contained program, is presented.

General Format

Syntax Rules

  1. A USE BEFORE REPORTING statement, when present, must immediately follow a section header in the declaratives portion of the Procedure Division and must appear in a sentence by itself. The remainder of the section must consist of zero, one, or more procedural paragraphs that define the procedures to be used.
  2. Identifier-1 must reference a report group. The same identifier-1 must not appear in more than one USE BEFORE REPORTING statement in the same Procedure Division.
  3. The GENERATE, INITIATE, or TERMINATE statements must not appear in a paragraph in a USE BEFORE REPORTING procedure. A PERFORM statement in a USE BEFORE REPORTING procedure must not have GENERATE, INITIATE, or TERMINATE statements in its range.
  4. A USE BEFORE REPORTING procedure must not alter the value of any control data item.
  5. The USE BEFORE REPORTING statement itself is never executed; it merely defines the conditions calling for the execution of the USE procedures.

General Rules

  1. A declarative procedure is invoked just before the named report group is produced during the execution of the program. The report group is named by identifier-1 in the USE BEFORE REPORTING statement which prefaces the declarative.
  2. Within a declarative procedure, there must be no reference to any nondeclarative procedures.
  3. Procedure-names associated with a USE BEFORE REPORTING statement can be referenced in a different declarative section or in a nondeclarative procedure only with a PERFORM statement.
  4. In the USE BEFORE REPORTING statement, the designated procedures are executed by the RWCS just before the named report group is produced. (See the section The TYPE Clause.)
  5. Within a USE procedure, there must not be the execution of any statement that would cause the execution of a USE procedure that had previously been invoked and had not yet returned control to the invoking routine.
  6. Special precedence rules are followed when programs are contained within other programs. In applying these rules, only the first qualifying directive will be selected for execution. The declarative which is selected for execution must satisfy the rules for execution of that declarative. The order of precedence for selecting a declarative is:
    1. The declarative within the program that contains the statement which caused the qualifying condition.
    2. The declarative in which the GLOBAL phrase is specified and which is within the program directly containing the program which was last examined for a qualifying declarative.
    3. Any declarative selected by applying rule 6b to each more inclusive containing program until rule 6b is applied to the outermost program. If no qualifying directive is found, none is executed.
Parent topic: Procedure Division
Related information
The TYPE Clause


Debug Module

Debugging provides a means by which the user can describe the conditions under which procedures are to be monitored during the execution of the object program.

ANS85 The ANSI Debug Module is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this module is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

  • Standard ANSI COBOL Debug
  • Object-time Switch
  • COBOL Debug RTS Switch
  • Debugging Lines
  • Environment Division
  • Procedure Division
Parent topic: Part 3. Additional Topics


Standard ANSI COBOL Debug

The decisions of what to monitor and what information to display are explicitly in the domain of the user. The COBOL debug facility simply provides a convenient access to pertinent information.

The features of the language that support the COBOL debug module are:

  • a WITH DEBUGGING MODE Switch – used at object code creation time
  • an RTS switch
  • a USE FOR DEBUGGING statement
  • a special register – DEBUG-ITEM
  • debugging lines.

The reserved word DEBUG-ITEM is the name for a special register generated automatically by your COBOL system that supports the debugging facility. Only one DEBUG-ITEM is allocated per program. The names of the subordinate data items in DEBUG-ITEM are also reserved words.

Parent topic: Debug Module


Object-time Switch

The DEBUGGING MODE clause is written as part of the SOURCE-COMPUTER paragraph in the Environment Division. It serves as an object-time switch over debugging statements written in the program.

When the WITH DEBUGGING MODE clause is specified in a program, all debugging sections and all debugging lines are handled as specified in this section of the document.

When the DEBUGGING MODE clause is not specified in a program, all the debugging sections and debugging lines are treated as if they were comment lines and their syntax is not checked.

Parent topic: Debug Module


COBOL Debug RTS Switch

An RTS switch dynamically activates the debugging code inserted by your COBOL system. This switch cannot be addressed in the program; it is controlled outside the COBOL environment. If the switch is on, the effects of any USE FOR DEBUGGING statements written in the source program are permitted. If the switch is off, all the effects described in the USE FOR DEBUGGING statement are inhibited. Re-creation of the object code is not required to provide or take away this facility.

The object time switch has no effect on the execution of the object program if the WITH DEBUGGING MODE clause was not specified in the source program.

Parent topic: Debug Module


Debugging Lines

A debugging line is any line with a "D" or "d" in the indicator area of the line. Any debugging line that consists solely of spaces from margin A to margin R is considered the same as a blank line.

The contents of a debugging line must be such that a syntactically correct program is formed with or without the debugging lines being considered as comment lines.

A debugging line will be considered to have all the characteristics of a comment line, if the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph.

Successive debugging lines are allowed. Continuation of debugging lines is permitted, except that each continuation line must contain a "D" or "d" in the indicator area, and character-strings can not be broken across two lines.

A debugging line is permitted in the program only after theOBJECT-COMPUTER paragraph .

Note: Debugging lines are part of the ANSI Nucleus and not the ANSI Debug module. Therefore, they are not obsolete and are not scheduled to be deleted from the next full revision of the ANSI Standard.
Parent topic: Debug Module


Environment Division

  • The WITH DEBUGGING MODE Clause
    The WITH DEBUGGING MODE clause indicates that all debugging sections and all debugging lines are to be included in the object code. If this clause is not specified, all debugging lines and sections are treated as if they were comment lines.
Parent topic: Debug Module


The WITH DEBUGGING MODE Clause

The WITH DEBUGGING MODE clause indicates that all debugging sections and all debugging lines are to be included in the object code. If this clause is not specified, all debugging lines and sections are treated as if they were comment lines.

The WITH DEBUGGING MODE clause is not an obsolete feature in ANSI'85 as it can also be used in the Nucleus.

General Format

General Rules

Note: The WITH DEBUGGING MODE clause is part of the ANSI Nucleus as well as the ANSI Debug module. It is not obsolete and is not scheduled to be deleted from the next full revision of the ANSI Standard.
  1. If the WITH DEBUGGING MODE clause is specified in the SOURCE-COMPUTER paragraph of the Configuration Section of a program, all USE FOR DEBUGGING statements and all debugging lines are included in the object code.
  2. If the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph of the Configuration Section of a program, any USE FOR DEBUGGING statements and all associated debugging sections, and any debugging lines are treated as if they were comment statements.
Parent topic: Environment Division


Procedure Division

  • The READY TRACE Statement
  • The RESET TRACE Statement
    The RESET TRACE statement disables the tracing of section and paragraph names on the screen.
  • The USE FOR DEBUGGING Statement
    The USE FOR DEBUGGING statement identifies the user items that are to be monitored by the associated debugging section.
Parent topic: Debug Module


The READY TRACE Statement

General Format

General Rules

  1. The COBOL Compiler directive TRACE must be set to on to allow execution of the statement. When the directive is not set, READY TRACE is documentary only.
  2. VSC2 READY TRACE is accepted, but is treated as documentary only.

Comments:

The READY TRACE statement is a debugging feature which causes each section and paragraph name subsequently reached to appear on the screen in order of execution.

Parent topic: Procedure Division


The RESET TRACE Statement

The RESET TRACE statement disables the tracing of section and paragraph names on the screen.

General Format

General Rules

  1. The COBOL Compiler directive TRACE must be set to on to allow execution of the statement. When the directive is not set or when no previous READY TRACE is in effect, RESET TRACE is documentary only.
  2. VSC2 RESET TRACE is accepted, but is treated as documentary only.
Parent topic: Procedure Division


The USE FOR DEBUGGING Statement

The USE FOR DEBUGGING statement identifies the user items that are to be monitored by the associated debugging section.

General Format

RTS switches

  1. The following RTS switch may impact either the syntax or semantics described in this section.
    • D – Activates ANSI Debug facilities

Syntax Rules

  1. Debugging section(s), if specified, must appear together immediately after the DECLARATIVES header.
  2. Except in the USE FOR DEBUGGING statement itself, there must be no reference to any non-declarative procedure in the debugging section.

    OSVS VSC2 MF This restriction is not enforced.

  3. Statements appearing outside of the set of debugging sections must not reference procedure-names defined in the set of debugging sections.
  4. Except for the USE FOR DEBUGGING statement itself, statements appearing in a given debugging section can reference procedure-names defined in a different USE procedure only with a PERFORM statement.
  5. Procedure-names defined in debugging sections must not appear in USE FOR DEBUGGING statements.
  6. Any given identifier, file-name, or procedure-name can appear in only one USE FOR DEBUGGING statement and can appear only once in that statement.
  7. The ALL PROCEDURES phrase can appear only once in a program.
  8. When the ALL PROCEDURES phrase is specified, procedure-name-1 must not be specified in any USE FOR DEBUGGING statement.
  9. If the data description entry of the data item referenced by identifier-1 contains an OCCURS clause or is subordinate to a data description entry that contains an OCCURS clause, identifier-1 must be specified without the subscripting or indexing normally required.
  10. References to the special register DEBUG-ITEM are restricted to references from within a debugging section.

General Rules

  1. Automatic execution of a debugging section is not caused by a statement appearing in a debugging section.
  2. When file-name-1 is specified in a USE FOR DEBUGGING statement , that debugging section is executed:
    1. After the execution of any OPEN or CLOSE statement that references file-name-1, and:
    2. After the execution of any READ statement (after any other specified USE procedure) not resulting in the execution of an associated AT END or INVALID KEY imperative statement, and:
    3. After the execution of any DELETE or START statement that references file-name-1.
  3. When procedure-name-1 is specified in a USE FOR DEBUGGING statement that debugging section is executed:
    1. Immediately before each execution of the named procedure.
    2. Immediately after the execution of an ALTER statement which references procedure-name-1.
  4. The ALL PROCEDURES phrase causes the effects described in General Rule 3 to occur for every procedure-name in the program, except those appearing in a debugging section.
  5. When the phrase, ALL REFERENCES OF identifier , is specified, that debugging section is executed for every statement that explicitly references identifier-1 at each of the following times:
    1. In the case of a WRITE or REWRITE statement immediately before the execution of that WRITE or REWRITE statement and after the execution of any implicit move resulting from the presence of the FROM phrase.
    2. In the case of a GO TO statement with a DEPENDING ON phrase, immediately before control is transferred and prior to the execution of any debugging section associated with the procedure-name to which control is to be transferred.
    3. In the case of a PERFORM statement in which a VARYING, AFTER, or UNTIL phrase references identifier-1, immediately after each initialization, modification or evaluation of the contents of the data item referenced by identifier-1.
    4. In the case of any other COBOL statement, immediately after execution of that statement.

    If identifier-1 is specified in a phrase that is not executed or evaluated, the associated debugging section is not executed.

  6. When identifier-1 is specified without the ALL REFERENCES OF phrase , that debugging section is executed at each of the following times:
    1. In the case of a WRITE or REWRITE statement that explicitly references identifier-1, immediately before the execution of that WRITE or REWRITE statement and after the execution of any implicit move resulting from the presence of the FROM phrase.
    2. In the case of a PERFORM statement in which a VARYING, AFTER or UNTIL phrase references identifier-1, immediately after each initialization, modification or evaluation of the contents of the data item referenced by identifier-1.
    3. Immediately after the execution of any other COBOL statement that explicitly references and causes the contents of the data item referenced by identifier-1 to be changed.

    If identifier-1 is specified in a phrase that is not executed or evaluated, the associated debugging section is not executed.

  7. The associated debugging section is not executed for a specific operand more than once as a result of the execution of a single statement, regardless of the number of times that operand is explicitly specified. In the case of a PERFORM statement which caused iterative execution of a referenced procedure, the associated debugging section is executed once for each iteration.

    Within an imperative statement, each individual occurrence of an imperative verb identifies a separate statement for the purpose of debugging.

  8. A reference to file-name-1, identifier-1, or procedure-name-1 as a qualifier does not constitute reference to that item for the debugging described in the General Rules above.
  9. Associated with each execution of a debugging section is the special register DEBUG-ITEM , which provides information about the conditions that caused the execution of a debugging section . DEBUG-ITEM has the following implicit description:
     01 debug-item.
     02 debug-line      pic x(6).
     02 filler          pic x value space.
     02 debug-name      pic x(30).
     02 filler          pic x value space.
     02 debug-sub-1     pic s9999 sign is leading separate character.
     02 filler          pic x value space
     02 debug-sub-2     pic s9999 sign is leading separate character.
     02 filler          pic x value space.
     02 debug-sub-3     pic s9999 sign is leading separate character.
     02 filler          pic x value space.
     02 debug-contents  pic x(n).
  10. Prior to each execution of a debugging section, the contents of the data item referenced by DEBUG-ITEM are space-filled. The contents of data items subordinate to DEBUG-ITEM are then updated, according to the following general rules, immediately before control is passed to that debugging section. The contents of any data item not specified in the following general rules remains spaces.

    Updating is accomplished in accordance with the rules for the MOVE statement, the sole exception being the move to DEBUG-CONTENTS when the move is treated exactly as if it was an alphanumeric to alphanumeric elementary move with no conversion of data from one form of internal representation to another.

  11. The contents of DEBUG-LINE is the relevant COBOL source line number. This provides the means of identifying a particular source statement.
  12. DEBUG-NAME contains the first 30 characters of the name that caused the debugging section to be executed.

    All qualifiers of the name are separated in DEBUG-NAME by the word IN or OF.

    Subscripts/indices, if any, are not entered into DEBUG-NAME.

  13. If the reference to a data item that causes the debugging section to be executed is subscripted or indexed, the occurrence number of each level is entered in DEBUG-SUB-1, DEBUG-SUB-2, DEBUG-SUB-3, respectively, as necessary.
  14. DEBUG-CONTENTS is a data item that is large enough to contain the data required by the following General Rules.
  15. If the first execution of the first nondeclarative procedure in the program causes the debugging section to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the first statement of that procedure.
    2. DEBUG-NAME contains the name of that procedure.
    3. DEBUG-CONTENTS contains "START PROGRAM".
  16. If a reference to procedure-name-1 in an ALTER statement causes the debugging section to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the ALTER statement that references procedure-name-1.
    2. DEBUG-NAME contains procedure-name-1.
    3. DEBUG-CONTENTS contains the applicable procedure-name associated with the TO phrase of the ALTER statement.
  17. If the transfer of control associated with the execution of a GO TO statement causes the debugging section to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the GO TO statement whose execution transfers control to procedure-name-1.
    2. DEBUG-NAME contains procedure-name-1.
  18. If reference to procedure-name-1 in the INPUT or OUTPUT phrase of a SORT or MERGE statement causes the debugging section to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the SORT or MERGE statement that references procedure-name-1.
    2. DEBUG-NAME contains procedure-name-1.
    3. DEBUG-CONTENTS contains:
      1. If the reference to procedure-name-1 is the INPUT phrase of a SORT statement, "SORT INPUT".
      2. If the reference to procedure-name-1 is in the OUTPUT phrase of a SORT statement, "SORT OUTPUT".
      3. If the reference to procedure-name-1 is in the OUTPUT phrase of a MERGE statement, "MERGE OUTPUT".
  19. If the transfer to control from the control mechanism associated with a PERFORM statement causes the debugging section associated with procedure-name-1 to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the PERFORM statement that references procedure-name-1.
    2. DEBUG-NAME contains procedure-name-1.
    3. DEBUG-CONTENTS contains "PERFORM LOOP".
  20. If procedure-name-1 is a USE procedure that is to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the statement that causes execution of the USE procedure.
    2. DEBUG-NAME contains procedure-name-1.
    3. DEBUG-CONTENTS contains "USE PROCEDURE".
  21. If an implicit transfer of control from the previous sequential paragraph to procedure-name-1 causes the debugging section to be executed, the following conditions exist:
    1. DEBUG-LINE identifies the previous statement.
    2. DEBUG-NAME contains procedure-name-1.
    3. DEBUG-CONTENTS contains "FALL THROUGH".
  22. If references to file-name-1 cause the debugging section to be executed, then:
    1. DEBUG-LINE identifies the source statement that references file-name-1 .
    2. DEBUG-NAME contains the name of file-name-1 .
    3. For READ, DEBUG-CONTENTS contains the entire record read.
    4. For all other references to file-name-1, DEBUG-CONTENTS contains spaces.
  23. If a reference to identifier-1 causes the debugging section to be executed, then:
    1. DEBUG-LINE identifies the source statement that references identifier-1,
    2. DEBUG-NAME contains the name of identifier-1, and:
    3. DEBUG-CONTENTS contains the contents of the data item referenced by identifier-1 at the time that control passes to the debugging section (see General Rules 5 and 6).
Parent topic: Procedure Division


Segmentation

The segmentation module provides a capability to specify object program overlay requirements.

Segmentation provides a facility for specifying permanent and independent segments. Segmentation also allows the intermixing of sections with different segment-numbers and allows the fixed portion of the source program to contain segments that can be overlaid.

ANS85 The Segmentation module is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MF All dialects in this COBOL implementation fully support this syntax. The FLAGSTD directive can be used to detect all occurrences of this syntax.

XOPEN Although it is a part of the standard COBOL definition, this module is explicity excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

  • General Description of Segmentation
  • Organization
  • Segmentation Classification
  • Segmentation Control
  • Structure of Program Segments
  • Restrictions on Program Flow
  • The ALTER Statement
  • The PERFORM Statement
  • The MERGE Statement
  • The SORT Statement
Parent topic: Part 3. Additional Topics
Related reference
Program Identification and Data Names


General Description of Segmentation

COBOL segmentation is a facility that provides a means by which the user can communicate with your COBOL system to specify object program overlay requirements.

COBOL segmentation deals only with segmentation of procedures. As such, only the Procedure Division is considered in determining segmentation requirements for an object program.

Parent topic: Segmentation


Organization

  • Program Segments
  • Fixed Portion
  • Independent Segments
Parent topic: Segmentation


Program Segments

Although it is not mandatory, the Procedure Division for a source program is often written as a consecutive group of sections, each of which is composed of a series of closely related operations that are designed to collectively perform a particular function. However, when segmentation is used, the entire Procedure Division must be in sections. In addition, each section must be classified as belonging either to the fixed portion or to one of the independent segments of the object program. Segmentation in no way affects the need for qualification of procedure-names to ensure uniqueness.

Parent topic: Organization


Fixed Portion

The fixed portion is defined as that part of the object program which is logically treated as if it were always in memory. This portion of the program is composed of fixed permanent segments, and fixed overlayable segments.

A fixed permanent segment is a segment in the fixed portion which cannot be overlaid by any other part of the program.

A fixed overlayable segment is a segment in the fixed portion which, although logically treated as if it were always in memory, can be overlaid by another segment to optimize memory utilization.

Parent topic: Organization


Independent Segments

An independent segment is defined as part of the object program which can overlay, and can be overlaid by either a fixed overlayable segment or another independent segment. An independent segment is in its initial state whenever control is transferred (either implicitly or explicitly) to that segment for the first time during the execution of a program. On subsequent transfers of control to the segment, an independent segment is also in its initial state when:

  • control is transferred to that segment as a result of the implicit transfer of control between consecutive statements from a segment with a different segment-number
  • control is transferred to that segment as the result of the implicit transfer of control between a SORT or MERGE statement, in a segment with a different segment-number, and an associated input or output procedure in that independent segment
  • control is transferred explicitly to that segment from a segment with a different segment-number (with the exception noted in paragraph 2 below).

On subsequent transfer of control to the segment, an independent segment is in its last-used state when:

  • control is transferred implicitly to that segment from a segment with a different segment-number (except as noted in paragraph 1).
  • control is transferred explicitly to that segment as the result of the execution of an EXIT PROGRAM

    OSVS VSC2 MF or GOBACK

    statement.

Parent topic: Organization


Segmentation Classification

Sections which are to be segmented are classified, using a system of segment-numbers and the following criteria:

  • Logic Requirements.

    Sections which must be available for reference at all times, or which are referred to very frequently, are normally classified as belonging either to one of the overlayable fixed segments or to one of the permanent segments; sections which are used less frequently are normally classified as belonging to one of the independent segments, depending on logic requirements.

  • Frequency of Use.

    Generally, the more frequently a section is referred to, the lower its segment-number; the less frequently it is referred to, the higher its segment-number.

  • Relationship to Other Sections.

    Sections which frequently communicate with one another should be given the same segment-numbers.

Parent topic: Segmentation


Segmentation Control

The logical sequence of the program is the same as the physical sequence except for specific transfers of control. Control can be transferred in a source program to any paragraph in a section; that is, it is not mandatory to transfer control to the beginning of a section.

Parent topic: Segmentation


Structure of Program Segments

  • Segment-Numbers
    Section classification is accomplished by means of a system of segment-numbers. The segment-number is included in the section header.
  • The SEGMENT-LIMIT Clause
Parent topic: Segmentation


Segment-Numbers

Section classification is accomplished by means of a system of segment-numbers. The segment-number is included in the section header.

General Format

Syntax Rules

  1. The segment-number must be an integer ranging in value from 0 through 99.
  2. If the segment-number is omitted from the section header, the segment-number is assumed to be 0.
  3. Sections in the declaratives must contain segment-numbers less than 50.
  4. OSVS VSC2 The segment-number must be a signed integer, but must not be a floating-point literal.

General Rules

  1. All sections which have the same segment-number constitute a program segment. All sections which have the same segment-number need not be physically contiguous in the source program.
  2. Segments with segment-number 0 through 49 belong to the fixed portion of the object program.
  3. Segments with segment-number 50 through 99 are independent segments.
Parent topic: Structure of Program Segments


The SEGMENT-LIMIT Clause

General Format

The SEGMENT-LIMIT clause appears in the OBJECT-COMPUTER paragraph and has the following format:

The SEGMENT-LIMIT clause appears in the OBJECT-COMPUTER paragraph and has the following format:

Syntax Rules

  1. Segment-number must be an integer ranging in value from 1 thru 49.

General Rules

  1. MF The SEGMENT-LIMIT clause is treated as documentary.
Parent topic: Structure of Program Segments


Restrictions on Program Flow

When segmentation is used, the following restrictions are placed on the ALTER, PERFORM, MERGE and SORT statements.

Parent topic: Segmentation


The ALTER Statement

A GO TO statement in a section whose segment-number is greater than or equal to 50 must not be referred to by an ALTER statement in a section with a different segment-number.

All other uses of the ALTER statement are valid and performed even if the GO TO to which the ALTER refers is in a fixed overlayable segment.

Parent topic: Segmentation


The PERFORM Statement

A PERFORM statement that appears in a section that is not in an independent segment can have within its range, in addition to any declarative sections whose execution is caused within that range, only one of the following:

  • Sections and/or paragraphs wholly contained in one or more non-independent segments.
  • Sections and/or paragraphs wholly contained in a single independent segment.

A PERFORM statement that appears in an independent segment can have within its range, in addition to any declarative sections whose execution is caused within that range, only one of the following:

  • Sections and/or paragraphs wholly contained in one or more non-independent segments.
  • Sections and/or paragraphs wholly contained in the same independent segment as that PERFORM statement.
Parent topic: Segmentation


The MERGE Statement

If the MERGE statement appears in a section that is not in an independent segment, then any output procedure referenced by that MERGE statement must appear:

  • totally within non-independent segments, or
  • wholly contained in a single independent segment.

If a MERGE statement appears in an independent segment, then any output procedure referenced by that MERGE statement must be contained:

  • totally within non-independent segments, or
  • wholly within the same independent segment as that MERGE statement.
Parent topic: Segmentation


The SORT Statement

If a SORT statement appears in a section that is not an independent segment, then any input procedures or output procedures referenced by that SORT statement must appear:

  • totally within non-independent segments, or
  • wholly contained in a single independent segment.

If a SORT statement appears in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained:

  • totally within non-independent segments, or
  • wholly within the same independent segment as that SORT statement.

SORT procedures should not be invoked by multiple threads simultaneously.

Parent topic: Segmentation


Double-Byte Character Set Support

Many of the world's languages use sets of characters that run into the thousands. Most computers use 8-bit bytes, and assign a different 8-bit code to represent each character; this scheme can represent no more than 256 different characters.

Ideally a COBOL programmer should not need to be aware of the internal code used to represent characters. However, in practice some features of the internal code can affect the source programmer, and this limitation to 256 different characters is one of the most restricting of these.

For this reason the Double-Byte Character Set (DBCS) is provided. In this scheme each character is represented by a 16-bit code, each character occupying a pair of adjacent bytes. This scheme can represent thousands of different characters.

The assignment of DBCS character codes to characters varies from country to country.

The 8-bit code used by your COBOL system is the American Standard Code for Information Interchange (ASCII). In this chapter this will be referred to as the Single-Byte Character Set (SBCS).

MF Double-Byte Character set support is sensitive to the DBCS Compiler directive.

See also the chapter Micro Focus Extensions for Double-Byte Character Support, primarily for Japanese language support.

  • DBCS Data
  • Roman Script in DBCS
  • Multivendor Integration Architecture Support
  • Source Programs
  • Language Extensions
  • Comments and Comment-entries
  • User-defined Words
  • Spaces
  • Data Items
  • Literals
  • Program Structure
  • Identification Division
  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Part 3. Additional Topics
Related information
Micro Focus Extensions for Double-Byte Character Support


DBCS Data

The DBCS Compiler directive makes your COBOL compiler recognize two data categories in which data is stored in DBCS. It does not prevent the use of other data categories; thus you can still use those data categories in which data is stored in SBCS.

Provided you have the necessary hardware support, DBCS data items used in input and output will be recognized and their data displayed and accepted correctly on such devices as screens, keyboard, printers, et cetera.

Parent topic: Double-Byte Character Set Support


Roman Script in DBCS

The character set that can be represented by SBCS is based on the Roman alphabet plus some other characters. In some countries the DBCS character codes also include codes for many of these characters.

On some hardware the character displayed is visibly different according to whether the character is stored in SBCS or DBCS; for example on some screens the DBCS code for a letter causes it to be printed larger than does its SBCS code.

Parent topic: Double-Byte Character Set Support


Multivendor Integration Architecture Support

Programs written to the NTT Multivendor Integration Architecture (MIA) Support are accepted by the COBOL compiler, using the DBCS and CURRENCY-SIGN"92" directives.

Parent topic: Double-Byte Character Set Support


Source Programs

DBCS characters can be used in literals, in comments and comment-entries, and in user-defined words. Otherwise the NCHAR or JAPANESE directives do not change the range of characters that can be used in source programs - the program is still written using the COBOL character set (see the chapter Concepts of the COBOL Language).

Parent topic: Double-Byte Character Set Support
Related information
Concepts of the COBOL Language


Language Extensions

There are extensions to the PICTURE and USAGE clauses to define items that are to contain DBCS data. A new format of literal is required for DBCS data.

There are additional rules for various options, clauses and statements to define the behavior of DBCS data.

Except where otherwise stated, all the rules and features of COBOL remain applicable when DBCS is in use. The following sections give only the additional rules and formats pertaining to DBCS.

Parent topic: Double-Byte Character Set Support


Comments and Comment-entries

SBCS and DBCS characters can be mixed freely in comments and comment-entries.

Parent topic: Double-Byte Character Set Support


User-defined Words

Either SBCS or DBCS characters can be used in user-defined words for: Alphabet-name, Class-name, Condition-name, Data-name/Identifier, Record-name, File-name, Index-name, Mnemonic-name, Paragraph-name, Section-name, and Symbolic-character.

MF SBCS and DBCS characters can be freely mixed in user-defined words. Where a character exists in both the DBCS and SBCS character sets, its DBCS and SBCS representations will not be regarded as equivalent. See the section Roman Script in DBCS.

Parent topic: Double-Byte Character Set Support
Related information
Roman Script in DBCS


Spaces

Spaces in data of class DBCS will be represented by the DBCS code for space. A space character represented by a 2-byte code is referred to as a DBCS space.

MF The values assigned to a DBCS space are sensitive to the DBCS and DBSPACE Compiler directives.

Parent topic: Double-Byte Character Set Support


Data Items

  • DBCS Data Items
  • Mixed Data Items
Parent topic: Double-Byte Character Set Support


DBCS Data Items

There is a class of data additional to the classes described in the section Class and Category of Data: it is called DBCS. It includes two data categories: DBCS and DBCS edited.

A data item of class DBCS is described by using the USAGE DISPLAY-1 clause. An item with this clause can have only the characters "G" and "B" in its PICTURE character-string. A " G" represents a DBCS character position; "B" is an editing character, and indicates a position that will always have a DBCS space inserted in editing. An item whose PICTURE character-string is all "G"s is of category DBCS; an item whose PICTURE character-string contains both "G" s and "B"s is of category DBCS edited.

Note that each "G" or "B" represents one 2-byte character position. Except where otherwise stated, the length of the data item for all purposes is the number of "G" s and "B"s in its PICTURE character-string.

For reference modification, the leftmost-character-position and length specify the number of DBCS characters, not bytes.

Data items of class DBCS can be used wherever data items of class alphanumeric can be used, subject to rules and exceptions given in the appropriate places in this chapter.

Parent topic: Data Items
Related information
Class and Category of Data


Mixed Data Items

DBCS characters can be included in data stored in data items of category alphanumeric. In such data, SBCS characters are represented by SBCS codes and DBCS characters by DBCS codes. Each space character is represented by the SBCS code for space.

On input and output both the SBCS and the DBCS codes will be recognized. The first byte of a DBCS code is never a valid SBCS code; hence the two can be used together without confusion. But in operations within the program the data will be treated as ordinary alphanumeric data. It is the programmer's responsibility to ensure that the two halves of a DBCS code do not get separated.

The length of the data item for all purposes is its length in bytes.

Parent topic: Data Items


Literals

  • DBCS Literals
  • Mixed Literals
  • Figurative Constants
  • The "N" literal
Parent topic: Double-Byte Character Set Support


DBCS Literals

There is a fourth type of literal in addition to the nonnumeric, numeric and national literals described in the section Literals, the DBCS literal.

A DBCS literal is a character-string delimited at both ends by quotation marks or apostrophes, with the beginning delimiter preceded by a "G". It can consist of any characters in the computer's DBCS character set. It can be up to 28 DBCS characters in length. It cannot be continued across lines.

Whether quotation marks or apostrophes are used, the presence of that delimiter within a DBCS literal can be represented by two contiguous occurrences. The presence of the character that is not serving as the delimiter is represented by a single occurrence. The value of a DBCS literal in the object program is the string of characters itself, except:

  1. The initial G and the delimiters are excluded, and
  2. Each embedded pair of contiguous delimiter characters represents a single character.
  • Category of DBCS Literals
Parent topic: Literals
Related information
Literals


Category of DBCS Literals

All DBCS literals can be used wherever nonnumeric literals can be used, subject to rules and exceptions given in the appropriate places in this chapter.

Parent topic: DBCS Literals


Mixed Literals

DBCS characters can be included in nonnumeric literals. A nonnumeric literal that includes DBCS characters is called a mixed literal. In such a literal, SBCS characters are represented by SBCS codes and DBCS characters by DBCS codes. Each space character is represented by the SBCS code for space.

On output both the SBCS and the DBCS codes will be recognized. The first byte of a DBCS code is never a valid SBCS code; hence the two can be used together without confusion. But in operations within the program the literal will be treated as an ordinary nonnumeric literal. It is the programmer's responsibility to ensure that the two halves of a DBCS code do not get separated.

A nonnumeric literal is of category alphanumeric, not DBCS, regardless of whether it includes DBCS characters.

A mixed literal cannot be continued across lines.

MF This restriction has been removed.

Parent topic: Literals


Figurative Constants

If a figurative constant is used where only a DBCS literal is allowed (according to the rules concerning classes and categories given in the appropriate places in this chapter), it is a DBCS literal. Each space in this literal is a DBCS space.

Only the figurative constant SPACE(S) can be a DBCS literal.

Parent topic: Literals


The "N" literal

Another format of literal, equivalent to the DBCS literal, is used in COBOL/370 and the MIA COBOL specification.

General Format

Syntax Rules

  1. An N-literal can contain no more than 18 DBCS-characters, and can not be split over two lines.
  2. An N-literal can contain only double-byte characters for your computer's Double Byte Character Set.
  3. Any double-byte quotation marks used in the literal should be written twice. For example, in order to express a double-byte quotation mark in the literal, you should write:

    N"ABC""DEF"

  4. N-literal specification and behavior can be modified in exactly the same way as G-literals using the APOST Compiler directive to replace a quotation (double-line) by an apostrophe (single-line) character.

General Rules

  1. The N-literal can be used in conjunction with ALL to make a figurative constant (see the section Figurative Constants.
  2. All characters must be double-byte characters.
Parent topic: Literals
Related information
Figurative Constants


Program Structure

  • The END PROGRAM Header (DBCS)
Parent topic: Double-Byte Character Set Support


The END PROGRAM Header (DBCS)

Syntax Rules

  1. Program-name must not contain DBCS characters.

    MF This restriction is removed.

Parent topic: Program Structure


Identification Division

  • The PROGRAM-ID Paragraph (DBCS)
Parent topic: Double-Byte Character Set Support


The PROGRAM-ID Paragraph (DBCS)

Syntax Rules

  1. Program-name must not contain DBCS characters.

    MF This restriction is removed.

  2. Comment-entries can contain DBCS characters.
Parent topic: Identification Division


Environment Division

  • The SOURCE-COMPUTER Paragraph (DBCS)
  • The OBJECT-COMPUTER Paragraph (DBCS)
  • The SPECIAL-NAMES Paragraph (DBCS)
  • The FILE-CONTROL Paragraph (DBCS)
Parent topic: Double-Byte Character Set Support


The SOURCE-COMPUTER Paragraph (DBCS)

Syntax Rules

  1. Source-computer-name can contain DBCS characters.
Parent topic: Environment Division


The OBJECT-COMPUTER Paragraph (DBCS)

Syntax Rules

  1. Object-computer-name can contain DBCS characters.
Parent topic: Environment Division


The SPECIAL-NAMES Paragraph (DBCS)

Syntax Rules

  1. In the CURRENCY SIGN clause, literal-6 must not be a DBCS literal and must not be "G"

    MF COB370 or "N".

  2. In the ALPHABET clause, literal-1, -2, and -3 must not be DBCS literals.
  3. In the CLASS clause, literal-4 and -5 must not be DBCS literals.
Parent topic: Environment Division


The FILE-CONTROL Paragraph (DBCS)

Syntax Rules

  1. In the ASSIGN clause, literal-1 must not be a DBCS literal and external-file-reference must not contain DBCS characters.

    MF This restriction is removed.

Parent topic: Environment Division


Data Division

  • The JUSTIFIED Clause (DBCS)
  • The PICTURE Clause (DBCS)
  • The REDEFINES Clause (DBCS)
  • The RENAMES Clause (DBCS)
  • The USAGE Clause (DBCS)
  • The VALUE Clause (DBCS)
Parent topic: Double-Byte Character Set Support


The JUSTIFIED Clause (DBCS)

General Rules

  1. The JUSTIFIED clause can be used with DBCS data items.
Parent topic: Data Division


The PICTURE Clause (DBCS)

General Rules for All Formats

  1. There are two additional categories of data that can be described with a PICTURE clause: DBCS and DBCS edited. Both these categories must be described as USAGE IS DISPLAY-1.

    MF These categories need not be described as USAGE DISPLAY-1.

    COB370 DISPLAY-1 is optional for PIC N, but not for PIC G items.

General Rules for DBCS Data

  2. Its PICTURE character-string can contain only the symbol "G"

    MF COB370 or "N".

  3. Its contents can be any characters in the DBCS character set.

General Rules for DBCS Edited Data

  4. Its PICTURE character string can contain any combination of the symbols "G" and "B".

General Rules for Editing

  5. The type of editing that can be performed on an item depends on the category to which the item belongs. The table Editing Types for Data Categories in the topic The PICTURE Clause is extended with the information shown in the table below:
    Table 1. Editing Types for Data Categories
    Category | Type of Editing
    DBCS | None
    DBCS Edited | Simple insertion "B" only

General Rules for Fixed Insertion Editing

  6. When used in an SBCS item, "B" (space) represents an SBCS space. When used in a DBCS item it represents a DBCS space.

Symbols Used

The functions of these symbols are as follows:

G - | Each "G" represents a character position which can contain only a DBCS character or a DBCS space.
B - | Each "B" represents a character position into which the DBCS space character will be inserted.
MF COB370 N - | Each "N" represents a character position which can contain only a DBCS character or a DBCS space.

Note that each "G" or "B"

ANS85 or "N"

represents a single double-byte character position.

Parent topic: Data Division
Related information
The PICTURE Clause


The REDEFINES Clause (DBCS)

Syntax Rules

  1. If either data-name-1 or data-name-2 is of class DBCS, then both must be of class DBCS.

    MF This restriction is removed.

Parent topic: Data Division


The RENAMES Clause (DBCS)

Syntax Rules

  1. If either data-name-1 or data-name-2 is of class DBCS, then both must be of class DBCS. No THROUGH clause is allowed.
Parent topic: Data Division


The USAGE Clause (DBCS)

General Format

The General Format is extended by the addition of the following:

The General Format is extended by the addition of the following:

Syntax Rules

  1. The PICTURE character-string of a DISPLAY-1 item can contain only "G"s and "B" s. An item whose PICTURE character-string contains "G"s must have a USAGE IS DISPLAY-1 clause.

    Note that therefore the USAGE IS DISPLAY-1 clause makes an item's class DBCS.

    MF COB370 USAGE IS DISPLAY-1 is not required for items whose PICTURE clause contains

    MF "G"s or

    MF COB370 "N"s.

    MF Whenever a PICTURE clause contains a "G" the associated item is considered to be of class DBCS.

  2. The BLANK WHEN ZERO clause cannot be used with group or elementary items described as USAGE IS DISPLAY-1. The SYNCHRONIZED clause is ignored.
  3. The usage of a Screen Section data item may be implicitly or explicitly defined as USAGE DISPLAY-1.

General Rules

  1. The USAGE IS DISPLAY-1 clause indicates that the format of the data is DBCS.
Parent topic: Data Division


The VALUE Clause (DBCS)

Syntax Rules for All Formats

  1. In a data description entry, if the category of the item is DBCS the literal in the VALUE clause must be of category DBCS. A DBCS literal is allowed only if the category of the item is DBCS or if the category of the item is DBCS edited.
  2. A DBCS literal in the VALUE clause must not exceed the size given by the PICTURE character-string.

Syntax Rules for Condition-name Rules

  3. In a condition-name entry, if the associated data item is of category DBCS, all literals in the VALUE clause must be of category DBCS. DBCS literals are allowed only if the category of the associated data item is DBCS.
Parent topic: Data Division


Procedure Division

  • Conditional Expressions (DBCS)
  • Statements that Involve Moving Data
  • The ACCEPT Statement (DBCS)
  • The CALL Statement (DBCS)
  • The CANCEL Statement (DBCS)
  • The INITIALIZE Statement (DBCS)
  • The INSPECT Statement (DBCS)
  • The MOVE Statement (DBCS)
  • The SEARCH Statement (DBCS)
  • The STOP Statement (DBCS)
  • The STRING Statement (DBCS)
  • The UNSTRING Statement (DBCS)
Parent topic: Double-Byte Character Set Support


Conditional Expressions (DBCS)

  • Relation Conditions
  • Class Condition
Parent topic: Procedure Division


Relation Conditions

Data items and literals of class DBCS can be used in a relation condition with any relational operator. Each operand must be either a group item or of class DBCS. No conversion, editing, or de-editing is done; no distinction is made between items of category DBCS and items of category DBCS edited.

The operation performed is a nonnumeric comparison. Since there is in general no collating sequence between the characters in a DBCS character set, the collating sequence used is based on the numeric values of the bit patterns representing the characters, interpreted as if they were binary numbers.

Note that if the DBCS character codes include codes for characters in the SBCS character set, there is no guarantee that this collating sequence will order them the same as in SBCS.

MF Where a character exists in both the DBCS and SBCS character sets, its DBCS and SBCS representations will not be regarded as equivalent. See the section Roman Script in DBCS.

The PROGRAM COLLATING SEQUENCE clause has no effect on comparisons involving data items of class DBCS or DBCS literals.

If the operands are of unequal size, comparison proceeds as though the shorter operand were extended on the right by enough DBCS spaces to make them the same size.

Parent topic: Conditional Expressions (DBCS)
Related information
Roman Script in DBCS


Class Condition

The class tests available for DBCS items are IS [NOT] DBCS, IS [NOT] KANJI, and IS [NOT] JAPANESE.

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.

Parent topic: Conditional Expressions (DBCS)


Statements that Involve Moving Data

All statements that involve moving data between items and/or literals of class DBCS obey the rules given for such moves under the General Rules for The MOVE Statement; see the section The MOVE Statement.

Parent topic: Procedure Division
Related information
The MOVE Statement


The ACCEPT Statement (DBCS)

Syntax Rules

  1. In Format 2, identifier must not be of class DBCS.

General Rules

  1. In Format 1, DBCS data can be entered only if identifier is of class DBCS.
Parent topic: Procedure Division


The CALL Statement (DBCS)

Syntax Rules

  1. Identifier-1 must not be a data item of class DBCS; literal-1 must not be a DBCS literal.

    MF This restriction is removed.

  2. The program-name given by identifier-1 or literal-1 must not contain DBCS characters.

    MF This restriction is removed.

General Rules

  1. Each item of class DBCS referenced in the USING clause must correspond to an item of class DBCS in the USING clause of the Procedure Division header of the called program.
Parent topic: Procedure Division


The CANCEL Statement (DBCS)

Syntax Rules

  1. Identifier-1 must not be a data item of class DBCS; literal-1 must not be a DBCS literal.

    MF This restriction is removed.

  2. The program-name given by identifier-1 or literal-1 must not contain DBCS characters.

    MF This restriction is removed.

Parent topic: Procedure Division


The INITIALIZE Statement (DBCS)

General Format

The General Format is extended by the options DBCS,

MF NATIONAL or NATIONAL-EDITED

as additional alternatives to ALPHABETIC, ALPHANUMERIC, et cetera.

General Rules

  1. Specifying the DBCS,

    MF NATIONAL or NATIONAL-EDITED option causes

    data items of categories DBCS and DBCS-EDITED to be initialized.

Parent topic: Procedure Division


The INSPECT Statement (DBCS)

Syntax Rules

  1. All the identifiers and literals except identifier-2 must be of class DBCS if any one of them is of class DBCS.

General Rules

  1. The count maintained in identifier-2 is of DBCS characters, not bytes.
Parent topic: Procedure Division


The MOVE Statement (DBCS)

Syntax Rules

  1. All the identifiers and literals must be of class DBCS if any one of them is.

    MF Items of class DBCS, category alphanumeric, and category alphabetic can be mixed freely.

  2. In Format 2, the MOVE CORRESPONDING format, if either of a pair of matching items is of class DBCS then they both must be.

General Rules

  1. If the sending field is of class DBCS and a receiving field is of category DBCS Edited, editing is carried out on that receiving field. For any other combination of fields of class DBCS, no conversion, editing, or de-editing is done.

    MF This rule is relaxed as follows. If a receiving field is of category DBCS edited, it is edited. For any other combination that includes a field of class DBCS, no conversion, editing, or de-editing is done.

  2. If a receiving field is a different size from the sending field, the data is stored in that receiving item and truncated or padded on the right with DBCS spaces.
Parent topic: Procedure Division


The SEARCH Statement (DBCS)

Syntax Rules

  1. In Format 2, if identifier-1 is of class DBCS, then the ASCENDING/DESCENDING KEY item defined in its OCCURS clause must be of class DBCS also.
Parent topic: Procedure Division


The STOP Statement (DBCS)

Syntax Rules

  1. Literal must not be a DBCS literal.

    MF This restriction is removed.

Parent topic: Procedure Division


The STRING Statement (DBCS)

Syntax Rules

  1. All the identifiers and literals except identifier-4 must be of class DBCS if any one of them is of class DBCS.

General Rules

  1. The relative position indicated by identifier-4 gives the position in DBCS characters.
Parent topic: Procedure Division


The UNSTRING Statement (DBCS)

Syntax Rules

  1. All of identifier-1, -2, -3, literal-1, and -2 must be of class DBCS if any one of them is of class DBCS.

General Rules

  1. The relative position indicated by identifier-7 gives the position in DBCS characters.
  2. The count maintained in identifier-6 is of DBCS characters.
Parent topic: Procedure Division


Micro Focus Extensions for Double-Byte Character Support

The Micro Focus Extensions for Double-Byte Character Support is the additional facility we provide as the programming solution for environments using 16-bit coding schemes (DBCS). This facility incorporates every implementation of Japanese language support from earlier Micro Focus products.

(MIA) If you wish your program to comply with the Multivendor Integration Architecture Standard or to be compatible with IBM VS COBOL II, COBOL/370 or IBM SAA you should use the DBCS Support defined earlier in the topic Double-Byte Character Set Support.

8-bit codes used by your COBOL system are referred to as the Single-Byte Character Set (SBCS). 16-bit codes, each character occupying a pair of adjacent bytes are referred as the Double-Byte Character Set (DBCS).

Micro Focus Extensions for Double-Byte Character Support is enabled by the NCHAR or JAPANESE Compiler directives.

When the Micro Focus Extensions for Double-Byte Character Support is enabled, the support defined in the topic Double-Byte Character Set Support is modified. In particular, in this chapter MOVE operations from SBCS to DBCS data items perform SBCS to DBCS conversion.

The classes NCHAR and JAPANESE, and NCHAR-EDITED and JAPANESE-EDITED are synonyms and interchangeable. In this chapter, reference to the class or category NCHAR or the category NCHAR-EDITED is equivalent to the class or category JAPANESE or the category JAPANESE-EDITED respectively.

  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Part 3. Additional Topics


Environment Division

  • The OBJECT-COMPUTER Paragraph
  • The SPECIAL-NAMES Paragraph
  • The FILE-CONTROL Paragraph
Parent topic: Micro Focus Extensions for Double-Byte Character Support


The OBJECT-COMPUTER Paragraph

General Rule

The compiler is designed to allow only 8-bit characters to be used in the PROGRAM COLLATING SEQUENCE IS phrase.

It is meaningless to define a collating sequence using an ALPHABET clause in which the literals contain double-byte characters. This is because double-byte appears as two separate 8-bit characters. If you attempt to use double-byte in this way, double-byte characters are collated as two single bytes – any double-byte meaning is ignored.

You can, however, use non-ASCII characters in the ALPHABET clause literals when you define the program collating sequence. For example, in a Japanese environment single-byte Katakana can be used in a Shift-JIS environment as they are stored and displayed as one byte. If you are using EUC you cannot use single-byte characters in the ALPHABET IS phrase, because such characters are hybrid two-byte characters.

Parent topic: Environment Division


The SPECIAL-NAMES Paragraph

Syntax Rules

  1. In the CURRENCY SIGN clause, literal-6 must not be an NCHAR literal and must not be "N".
  2. In the ALPHABET clause, literal-1, -2, and -3 must not be NCHAR literals.
  3. In the CLASS clause, literal-4 and -5 must not be NCHAR literals.
Parent topic: Environment Division


The FILE-CONTROL Paragraph

Syntax Rules

  1. In the ASSIGN clause, literal-1 can be an NCHAR literal and external-file-reference can contain DBCS characters.
Parent topic: Environment Division


Data Division

  • The JUSTIFIED Clause
  • The PICTURE Clause (DBCS)
  • The USAGE Clause
  • The VALUE Clause
Parent topic: Micro Focus Extensions for Double-Byte Character Support


The JUSTIFIED Clause

General Rules

  1. The JUSTIFIED clause can be used with NCHAR data items.
Parent topic: Data Division


The PICTURE Clause (DBCS)

General Rules for NCHAR data itemrules Rules for NCHAR Data

  1. Its PICTURE character-string can contain only the symbol "N".
  2. Its contents can be any characters in the DBCS character set.

General Rules for NCHAR-EDITED data rule Rules for NCHAR-EDITED Data

  3. Its PICTURE character string can contain any combination of the symbols "N", "B", "/" and "0". Refer to the section The PICTURE Clause for edited-data rules.

Symbols Used

The functions of these symbols are as follows:

Symbol | Representation | Example NCHAR Japanese Values
 |  | Shift-JIS | EUC
N | Each "N" represents a character position which can contain only a DBCS character or a DBCS space. |  |
B | Each "B" represents a character position into which the DBCS space character is inserted. | x"8140" | x"A1A1"
/ | Each "/" represents a character position into which the DBCS forward slash is inserted. | x"851E" | x"A1BF"
0 | Each "0" represents a character position into which the DBCS Zero is inserted. | x"824F" | x"A3B0"
Note: Each "N", "B", "/", "0" represents a single double-byte character position.

DBCS Characters Editing Rules

The type of editing that can be performed on an item depends on the category to which the item belongs. The table Editing Types for Data Categories in the section The PICTURE Clause is extended with the information shown in the table below:

Category | Type of Editing
NCHAR | None
NCHAR-EDITED | Simple insertion "B", "/", "0" only

Fixed Insertion Editing

When used in an SBCS item, "B" (space) represents an SBCS space. When used in an NCHAR item it represents a DBCS space.

When used in an SBCS item, "/" (forward slash) represents an SBCS forward slash. When used in an NCHAR item it represents a DBCS forward slash.

When used in an SBCS item, "0" (zero) represents an SBCS zero. When used in an NCHAR item it represents a DBCS zero.

Parent topic: Data Division
Related information
The PICTURE Clause


The USAGE Clause

General Format

The General Format is extended by the addition of the following:

The General Format is extended by the addition of the following:

Syntax Rules

  1. The PICTURE character-string can contain only "N"s, "B"s, "/"s, and "0"s.

    Whenever a PICTURE clause contains an "N" the associated item is considered to be of class NCHAR, Japanese.

  2. The BLANK WHEN ZERO clause cannot be used with group or elementary items described as USAGE IS NCHAR or USAGE IS JAPANESE. The SYNCHRONIZED clause is ignored.

General Rules

  1. The USAGE IS NCHAR or USAGE IS JAPANESE clause indicates that the format of the data is NCHAR.
Parent topic: Data Division


The VALUE Clause

Syntax Rules

  1. In a data description entry, if the category of the item is NCHAR, the literal in the VALUE clause must be of category NCHAR. An NCHAR literal is allowed only if the category of the item is NCHAR or NCHAR-EDITED.

    An NCHAR literal in the VALUE clause must not exceed the size given by the PICTURE character-string.

Parent topic: Data Division


Procedure Division

  • Conditional Expressions
  • The ACCEPT Statement
  • The INITIALIZE Statement
  • The INSPECT Statement
  • The MOVE Statement
    All statements that involve moving data between items and/or literals of class NCHAR obey the rules given for such moves under the General Rules below.
  • The SEARCH Statement
  • The STRING Statement
  • The UNSTRING Statement
Parent topic: Micro Focus Extensions for Double-Byte Character Support


Conditional Expressions

  • Condition-name
  • Relation Conditions
  • Class Condition
Parent topic: Procedure Division


Condition-name

If a condition-name with a literal of class NCHAR is associated with an elementary item which is not of class NCHAR, the literal is treated as an SBCS alphanumeric literal.

Parent topic: Conditional Expressions


Relation Conditions

Data items and literals of class NCHAR can be used in a relation condition with any relational operator. No conversion, editing or de-editing is done and no distinction is made between items of category NCHAR and items of category NCHAR-EDITED.

The operation performed is a nonnumeric comparison. Since there is in general no collating sequence between the characters in a DBCS character set, the collating sequence used is based on the numeric values of the bit patterns representing the characters, interpreted as if they were binary numbers.

Note that if the DBCS character codes include codes for characters in the SBCS character set, there is no guarantee that this collating sequence orders them the same as in SBCS.

Where a character exists in both the DBCS and SBCS character sets, its DBCS and SBCS representations are not regarded as equivalent.

The PROGRAM COLLATING SEQUENCE clause has no effect on comparisons involving data items of class NCHAR or NCHAR literals.

If the operands are of unequal size, comparison proceeds as though the shorter operand were extended on the right by enough DBCS spaces to make them the same size.

Parent topic: Conditional Expressions


Class Condition

An additional class test, JAPANESE, is available.

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.

Parent topic: Conditional Expressions


ACCEPT (DBCS characters)

The ACCEPT Statement

General Rules

Note: In some environments, such as a Japanese EUC environment, special actions or behavior may occur.
  1. In Format 1, both SBCS and DBCS data can be entered. SBCS data is not converted to DBCS data.

    In a Format 1 ACCEPT of an NCHAR-EDITED data item, there is no validation, conversion or character alignment of the data that you enter. As a result, the data might be corrupted. Therefore, we recommend that you do not use this method, or use it with caution.

    In Formats 4 and 5, both single-byte and double-byte characters are valid characters to be entered into an NCHAR data item. However single-byte characters are converted to their double-byte equivalent.

    All normal editing features are supported for the ACCEPT of NCHAR data items (backspace, retype, delete, restore, overtype and insert) on a character by character basis.

Parent topic: Procedure Division


The INITIALIZE Statement

General Format

The General Format is extended by the options NCHAR and JAPANESE as additional alternatives to options such as ALPHABETIC or ALPHANUMERIC.

Syntax Rules

  1. NCHAR and JAPANESE may not be specified together or in conjunction with DBCS or NATIONAL.

General Rules

  1. Specifying the NCHAR or JAPANESE option causes data items of category NCHAR to be initialized.
Parent topic: Procedure Division


The INSPECT Statement

Syntax Rules

  1. All the identifiers and literals except identifier-2 must be of class NCHAR if any one of them is of class NCHAR.

General Rules

  1. If identifier-1 is of class NCHAR, the count maintained in identifier-2 is of DBCS characters, not bytes.
Parent topic: Procedure Division


The MOVE Statement

All statements that involve moving data between items and/or literals of class NCHAR obey the rules given for such moves under the General Rules below.
Category of Sending Item | Category of Receiving Data Item
 | Alpha-numeric | NCHAR | NCHAR-EDITED | NCHAR with JUSTIFIED
Alpha-numeric | See Note | Yes/G1 | Yes/G4 | No/S2
NCHAR | Yes/G2 | Yes/G3 | Yes/G4 | Yes/G5
NCHAR-EDITED | No/S1 | No/S1 | No/S1 | No/S1
NCHAR with JUSTIFIED | Yes/G2 | Yes/G3 | Yes/G4 | Yes/G5
Note: Class Alphanumeric is specified in this table as an illustration of the usage of single-byte or group data items. For details of MOVE operations involving only single-byte data items refer to the topic The MOVE Statement. For details of MOVE operations mixing single- and double-byte data item, refer to the following information and the table above.

Syntax Rules

  1. The sending data item must not be of category NCHAR-EDITED.
  2. If the receiving data item is of class NCHAR and the JUSTIFIED clause is specified, the sending data item must be of class NCHAR.

General Rules

  1. If the sending data item is of class alphanumeric or alphabetic and the receiving data item is of class NCHAR then the single-byte characters in the source are converted into the equivalent double-byte characters in the target. DBCS characters in the source are moved unchanged into the target.

    If a receiving data item is a different size from the sending data item, the data that is stored in the receiving item is truncated or padded on the right with DBCS spaces.

  2. If the sending data item is of class NCHAR and the receiving data item is of class alphanumeric, then the hexadecimal values in the source are moved, unchanged, to the target data item on a byte by byte basis.

    If a receiving data item is a different size from the sending data item, the data that is stored in the receiving item is truncated or padded on the right with SBCS spaces.

  3. If the sending data item is of class NCHAR and the receiving data item is also of class NCHAR, then the values in the source are moved, unchanged, to the target data item on a byte by byte basis.

    If a receiving data item is a different size from the sending data item, the data that is stored in the receiving item is truncated or padded on the right with DBCS spaces.

  4. If the sending data item is of class alphanumeric, alphabetic or NCHAR and a receiving data item is of category NCHAR-EDITED, editing is carried out on that receiving data item.

    If a receiving data item is a different size from the sending data item, the data is stored in that receiving item and truncated or padded on the right with DBCS spaces.

    If the sending data item is of class alphanumeric or alphabetic, the hexadecimal values of the single-byte characters in the source are converted to the equivalent double-byte characters in the target. DBCS characters in the source are moved unchanged into the target.

  5. If the sending data item is of class NCHAR and the receiving data item is class NCHAR with the JUSTIFIED clause specified, then the values in the source data item are moved, unchanged, to the target data item on a byte by byte basis.

    When a receiving data item is described with JUSTIFIED clause and the sending data item is larger than the receiving data item, the leftmost characters are truncated. When the receiving data item is described with the JUSTIFIED clause and it is larger than the sending data item, data is aligned at the rightmost character position in the data item with DBCS spaces padding from the leftmost character positions.

Parent topic: Procedure Division
Related information
The MOVE Statement


The SEARCH Statement

General Rules

  1. If identifier-1 is of class NCHAR then in Format 1 the value maintained in identifier-2 consists of DBCS characters.
Parent topic: Procedure Division


The STRING Statement

Syntax Rules

  1. All the identifiers and literals except identifier-4 must be of class NCHAR if any one of them is of class NCHAR.

General Rules

  1. If identifier-3 is of class NCHAR then the relative position indicated by identifier-4 gives the position in DBCS characters.
Parent topic: Procedure Division


The UNSTRING Statement

Syntax Rules

  1. All of identifier-1, identifier-2, identifier-3, literal-1 and literal-2 must be of class NCHAR if any one of them is of class NCHAR.

General Rules

  1. If identifier-1 is of class NCHAR then the relative position indicated by identifier-7 gives the position in DBCS characters and the count maintained in identifier-6 is of DBCS characters.
Parent topic: Procedure Division


Micro Focus OO COBOL Extensions

  • Directives
  • Class Definition
    A Class describes an Object COBOL Class object and its instance objects. It contains nested programs for class methods and instance methods.
  • Class Extension
    A class extension enables you to add extra functionality to an object COBOL class without changing the original source code.
  • Class-body
    The class body contains all the code that defines class data and class methods.
  • Class-object
    The class object is an object that acts as a creator of objects.
  • Object-program
    The object program contains the definition of data and methods for all instances of the class.
  • Method
  • Method Interface Definition
    A method interface definition defines the parameters for the method, how they are passed, and any alternate syntax that can be used to invoke the method.
Parent topic: Part 3. Additional Topics


Directives

In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.

  • ALIGN - specifies the memory boundaries on which data items of 01-level or 77-level are aligned.
  • IBMCOMP - turns on word-storage mode.
  • MAPNAME - impacts the handling of non-alphabetic characters in the method-name.
  • REPOSITORY - tells the Compiler whether to create a repository entry for a class, ignore the repository entry for a class, or check against the repository entry for a class.
  • OOCTRL - provides specific switches for OO options. The settings can be enabled or disabled by use of the + and - signs, respectively, preceding the option character. The default is OOCTRL(+F-G-P+Q-W). The meaning of the options is:
    +F Folds method names invoked by the program being compiled to lower case. Use -F if your program calls Java methods, since Java method names are case-sensitive. See your COBOL system documentation for information on using Java and COBOL together.
    +G Makes class data global for instances.
    Note: The use of this option is not recommended. It is provided for compatibility with earlier releases.
    +P Makes parameter type information available to the Object COBOL runtime system.
    Note: Needed for messages sent to OLE and SOM.
    +Q Disables the use of IN and OF any place that could possibly follow a data name in the verb-signature of a Method Interface Definition.

    Disables the use of any verb in the verb-signature of a Method Interface Definition (see the topic Categories of Statements in the chapter Language Fundamentals).

    -Q Enables the use of IN and OF in the verb-signature of a Method Interface Definition. Disables the use of qualification in a verb-signature that invokes a method.

    Enables the use of verbs in the verb-signature of a Method Interface Definition (see the topic Categories of Statements in the chapter Language Fundamentals).

    +W Uses working storage in the object and factory (class) object to mean object storage.
    Note: Provides compatibility with the ISO 2002 COBOL standard.
Parent topic: Micro Focus OO COBOL Extensions
Related information
Categories of Statements


Class Definition

A Class describes an Object COBOL Class object and its instance objects. It contains nested programs for class methods and instance methods.

General Format

Syntax Rules

  1. The words PROTECTED and RESTRICTED are equivalent.
  2. If the EXTERNAL clause is specified, neither the DATA nor the INHERITS clause may be specified.
  3. If the ABSTRACT clause is specified, the FINAL clause must not be specified.
  4. If the WITH DATA phrase is specified in the INHERITS clause, the DATA IS PRIVATE clause must not be specified explicitly or implicitly in the source code for class-name-2.
  5. Class-name-2 must not be the same as class-name-1.
  6. Class-name-2 must not inherit from class-name-1 directly or indirectly.
  7. Class-name-1 in the END CLASS header must be identical to the class-name-1 specified in the preceding Class-ID paragraph.

General Rules

  1. Class-name-1 identifies the class being declared.
  2. The ABSTRACT clause indicates that class-name-1 is an abstract class. You cannot create an instance of an abstract class.
  3. The EXTERNAL phrase indicates that class-name-1 is an external class. No code is produced.
  4. The RESTRICTED phrase enables subclasses to directly access data inherited from class-name-1.
  5. The PRIVATE phrase prevents subclasses from directly accessing data inherited from class-name-1.
  6. The INHERITS phrase specifies that class-name-2 is a parent class of class-name-1.
  7. If the INHERITS phrase is not specified, class-name-1 forms a new root in the classification scheme. There can be one or more roots in a classification scheme.
  8. The WITH DATA phrase specifies that class-name-1 is able to access directly data inherited from class-name-2.
Parent topic: Micro Focus OO COBOL Extensions


Class Extension

A class extension enables you to add extra functionality to an object COBOL class without changing the original source code.

The difference between extending a class with a class extension as opposed to using inheritance is that the class extensions are inherited by all existing subclasses. For example, if class A has a subclass, class B (B INHERITS FROM A), you can add methods to class A by subclassing it to create subclass C. However, class B does not inherit the methods of class C, because it is a subclass of A. If you extend class A with a class extension, X, the effect at run time is the same as if you had changed and recompiled class A: class B inherits all the extra methods in class X.

General Format

Syntax Rules

  1. Extension-name-1 must not be the same as class-name-1.
  2. Extension-name-1 in the END CLASS header must be identical to the extension-name-1 specified in the preceding Class-ID paragraph.
  3. Class-name-1 must be the name of a class specified in the Class-Control paragraph.
  4. The Data Division of the class-body may contain an empty Object-Storage Section. The only other sections that may be specified in the Data Division of a Class Extension are the Working-Storage Section and the Linkage Section.
  5. Statements in the class extension may reference data declared in class-name-1 only when both the following cocnditions are true:
    • The DATA IS PROTECTED or DATA IS RESTRICTED phrase is specified in the Class-ID paragraph of class-name-1
    • The WITH DATA phrase is specified in the Class-ID paragraph of the class extension.

General Rules

  1. The EXTEND clause specifies a class extension. A class extension adds methods to an object class. The methods specified in extension-name-1 are inherited by all subclasses, existing and new, of class-name-1.
  2. During the execution of a run unit, a COBOL call statement to extension-name-1 must be executed before any of the methods in the class extension are invoked. This registers the methods in the class extension with the OO runtime system.
Parent topic: Micro Focus OO COBOL Extensions


Class-body

The class body contains all the code that defines class data and class methods.

General Format for Format 1

Used when the Compiler directive OOCTRL(+N) is specified.

Note: This is the preferred syntax.

General Format for Format 2

Used when the Compiler directive OOCTRL(-N) is specified.

Syntax Rules for All Formats

  1. Class-name-3 must not be specified more than once in the Class-Control paragraph.
  2. Class-name-3 may be the same as the class-name specified in the Class-ID paragraph.
  3. The Data Division may not contain a Linkage Section.

Syntax Rules for Format 1

  4. The Data Division may not contain an Object-Storage Section.
  5. Data items declared in the Data Division may be referenced from instance methods and class methods.

Syntax Rules for Format 2

  6. Data items declared in the Local-Storage Section, Report Section, and Screen Section may be referenced only from the statements in the Procedure Division of this class, not from any methods.
  7. Data items declared in the File Section or Working-Storage Section can be referenced from instance methods and class methods and from the Procedure Division of this class.
  8. Data items declared in the Object-Storage Section may be referenced from class methods.

General Rules for All Formats

  1. Class-name-3 is implicitly defined as USAGE IS OBJECT REFERENCE.
  2. Class-name-3 is the name of a class that may be used throughout the scope of the containing Environment Division.
  3. External-name-1 specifies the external name of the file containing the class.
  4. Method-1 is a class method.
  5. Only data items in the Object-Storage Section are inherited by subclasses.

General Rules for Format 1

  6. Data items are in their initial state at the start of the run unit and remain in their last used state between method invocations.

General Rules for Format 2

  7. The statements in the class Procedure Division are executed before the first time any class method or instance method of this class is executed in the run unit.
  8. When execution of the class Procedure Division begins, the contents of the data items in the Local-Storage Section are undefined. This storage is deallocated immediately after execution of the class Procedure Division.
  9. Data items declared in the File Section and Working-Storage Section remain in their last used state between invocations of class and instance methods.
    Note: Working storage data is useful for class or instance initialization data.
  10. Data items declared in the Object-Storage Section remain in their last used state between invocations of class methods.
Parent topic: Micro Focus OO COBOL Extensions


Class-object

The class object is an object that acts as a creator of objects.

General Format

General Rules

  1. If a data-item is declared in the Object-Storage Section of a class object, it is class data. Class data may be referenced only in class methods. Class data can be inherited by subclasses.
  2. Data is in its initial state at the start of the run unit and remains in its last used state between method invocations.
  3. Method-1 is a class method.
Parent topic: Micro Focus OO COBOL Extensions


Object-program

The object program contains the definition of data and methods for all instances of the class.

General Format

General Rules

  1. If a data-item is declared in the Object-Storage Section of an object program, it is instance data. Instance data may be referenced only in instance methods.
  2. Data items are in their initial state at the start of the run unit and remain in their last used state between method invocations.
  3. Method-1 is an instance method.
Parent topic: Micro Focus OO COBOL Extensions


Method

Genral Format:

Syntax Rules

  1. Method-name-1 in the END METHOD header must be identical to the method-name-1 declared in the preceding Method-ID paragraph.
  2. Data declared in the Data Division of a method is accessible only within that method.
  3. Quotation marks around method-name-1 are optional.
    Note: Quotation marks enable you to use reserved words as method-names and to use non-COBOL characters.
  4. A method definition must be contained in a Class Definition.
  5. The format of the PROCEDURE DIVISION header for a method is the same as the format 1 PROCEDURE DIVISION header for a program. The GIVING or RETURNING data-name clause shown in the format 2 header may also be specified. (See the section The PROCEDURE DIVISION Header for details.)

General Rules

  1. Method-name-1 names the method declared by this method definition.
  2. Data declared in the Local-Storage Section of a method is allocated separate storage for each invocation of the method and deallocated upon return from the method. This data is in an undefined state each time the method is invoked.
    Note: If you declare your data in the Local-Storage Section, separate invocations of the method do not interfere with each other's data.
  3. Data and files declared in a method in sections other than the Local-Storage Section or the Linkage Section are shared among all invocations of the method and are in their last used state when the method is invoked.
  4. Method-name-1 may be used in a method invocation with an object identifier that references an object containing this method.
  5. If a RETURNING or GIVING phrase is specified in the PROCEDURE DIVISION header of a method, the contents of the data item specified in that phrase when the method terminates become the result of the method. This result is placed in the identifier specified in the RETURNING or GIVING phrase of the INVOKE statement.
Parent topic: Micro Focus OO COBOL Extensions
Related information
The PROCEDURE DIVISION Header


Method Interface Definition

A method interface definition defines the parameters for the method, how they are passed, and any alternate syntax that can be used to invoke the method.

General Format:

where verb-signature is:

Syntax Rules

  1. A method interface definition must be nested within an external class.
  2. Procedure-division-header is a format 2 procedure-division-header as specified for a program, except that neither mnemonic-name nor the REPEATED phrase may be specified. The INVOKED phrase, shown in the format above, may optionally be included in the header just before the terminating period. (See the topic The PROCEDURE DIVISION Header for details.)
  3. When the FUNCTION phrase is specified in the verb-signature, the RETURNING phrase must be specified in the PROCEDURE DIVISION header.
  4. Verb-1 must be a COBOL word that is neither a reserved word nor a procedure-name.
  5. The words <OBJECT>, <SELF> and <THIS> are equivalent. One of them must be present once and only once in each verb-signature.
  6. Data-name-3 must be preceded by "<" and followed by ">".
  7. Compulsory-word must be a COBOL word.
  8. Noise-word must be a COBOL word and must be preceded by "[" and followed by "]".
  9. Open-parenthesis and close-parenthesis are "(" and ")" respectively.
    Note: Open-parenthesis and close-parenthesis enable you to define functions that look like intrinsic functions, with parameters enclosed in parentheses.
  10. A verb-signature must not be a subset of another verb-signature.

General Rules

  1. When method-name-1 is invoked using verb-signature, <SELF> is replaced with the object reference to the receiving object.
  2. Noise-words are for readability and are optional when the syntax is used to invoke a method.
  3. If verb-1 is also declared as a data-name in a program, then any reference to that word in that program is to the data-name.
Parent topic: Micro Focus OO COBOL Extensions
Related information
The PROCEDURE DIVISION Header


Summary of Obsolete Language Elements

The elements of the COBOL language listed here are marked as obsolete in the ANSI X3.23-1985 COBOL specification.

  • They are to be deleted at the next revision of the standard COBOL specification.
  • They will not be enhanced, modified or maintained.
  • They should not be used in a conforming X/Open source program.

List of Obsolete Language Elements

  • Associating the figurative constant ALL literal where literal is longer than one character with a data item that is numeric or numeric edited.
  • The paragraphs AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED, and SECURITY within the Identification Division.
  • The MEMORY SIZE clause of the OBJECT-COMPUTER paragraph.
  • The RERUN clause of the I-O-CONTROL paragraph.
  • The MULTIPLE FILE TAPE clause of the I-O-CONTROL paragraph.
  • The LABEL RECORDS clause in the file description entry.
  • The VALUE OF clause in the file description entry.
  • The DATA RECORDS clause in the file description entry.
  • The ALTER statement.
  • The KEY phrase within the DISABLE statement.
  • The KEY phrase within the ENABLE statement.
  • The ENTER statement.
  • The option to exclude procedure-name in the GO TO statement.
  • The REVERSED phrase within the OPEN statement.
  • The STOP literal statement.
  • The segmentation module.
  • The debug module.


Additional Dialect Support

  • ACUCOBOL-GT Syntax Extensions
    Use the abbreviated ACUCOBOL-GT language reference for details of ACUCOBOL-GT's syntax extensions to ANSI 85 COBOL.
  • Data General Interactive COBOL V1.3 Syntax Support
  • DOS/VS COBOL Support
  • Microsoft COBOL V1.0 and V2.0 Syntax Support
  • RM/COBOL Syntax Support
  • Siemens BS2000 COBOL Syntax Support
  • VS COBOL II Compatibility
Parent topic: Part 3. Additional Topics


ACUCOBOL-GT Syntax Extensions

Use the abbreviated ACUCOBOL-GT language reference for details of ACUCOBOL-GT's syntax extensions to ANSI 85 COBOL.

ACUCOBOL-GT (Acu) is an implementation of the ANSI 85 COBOL programming language (ANSI X3.23-1985 and the ANSI X3.23a-1989 supplement). This section contains an abbreviated ACUCOBOL-GT language reference, which provides descriptions of Acu's language extensions when programs are compiled in Acu compatibility mode (DIALECT"ACU"). For details on all other syntax supported by this COBOL system, see the COBOL Language Reference.

Since Micro Focus COBOL is also an implementation of ANSI 85 COBOL, Acu's ANSI 85 elements and behaviors are identical (or compatible) to Micro Focus COBOL.

You can obtain a complete ACUCOBOL-GT reference manual from the ACUCOBOL-GT product documentation set, which is available from the Micro Focus Product Documentation Page.

  • Program Structure
    Supported ACUCOBOL-GT program structures and elements when compiling for Acu compatibility.
  • Identification Division
    Supported elements when compiling for Acu compatibility.
  • Environment Division
    Supported ACUCOBOL-GT Environment Division elements when compiling for ACU compatibility.
  • Data Division
    Supported ACUCOBOL-GT Data Division elements and types when compiling for Acu compatibility.
  • Procedure Division
    Supported ACUCOBOL-GT extensions to Procedure Division statements and elements when compiling for Acu compatibility.
Parent topic: Additional Dialect Support


Program Structure

Supported ACUCOBOL-GT program structures and elements when compiling for Acu compatibility.
  • Identifiers
  • Numeric Literals
  • Nonnumeric Literals
  • Source Formats
Parent topic: ACUCOBOL-GT Syntax Extensions


Identifiers

  • Identifiers can be up to 62 characters long.
  • Underscore "_" is treated as a dash "-" in identifiers.
  • Data names can have the same name as procedure names.
  • Index-name identifiers can be used on different tables in SEARCH statements.
Parent topic: Program Structure


Numeric Literals

A numeric literal is a character string selected from the digits, the plus sign, the minus sign, and the decimal point.

The following rules govern the formation of numeric literals:

  • A literal must contain at least one digit
  • A literal must contain no more than one sign character and, if one is used, it must be the leftmost character of the string
  • A literal must not contain more than one decimal point. The decimal point is treated as an assumed decimal point and may appear anywhere within the literal except as the rightmost character

If a literal conforms to the rules for formation of a numeric literal, but is enclosed in quotation marks, it is a nonnumeric literal.

Numeric literals may also be specified using binary, octal, or hexadecimal notation. To specify a numeric literal in one of these forms, preface the number with one of the following prefixes:

Binary | "B#"
Octal | "O#"
Hexadecimal | “X#” or “H#”

For example:

Number | Binary | Octal | Hexadecimal
3 | B#11 | O#3 | X#3 or H#3
8 | B#1000 | O#10 | X#8 or H#8
12 | B#1100 | O#14 | X#C or H#C
128 | B#10000000 | O#200 | X#80 or H#80
255 | B#11111111 | O#377 | X#FF or H#FF

Leading zeroes after the # are ignored. For example, X#00FF and X#FF are equivalent.

The Compiler converts each numeric literal specified in this way to an unsigned long integer. In most cases, this is a 32-bit unsigned number, so the maximum value of a numeric literal that can specified with this notation is 4294967295, or (2**32) -1.

LENGTH OF expression

The LENGTH OF expression can be used anywhere you would use a numeric literal, except as a subscript or reference modifier. The Compiler treats this expression as if you have coded a numeric literal. The LENGTH OF expression is written as follows:

LENGTH OF data-name

data-name can be a numeric or nonnumeric literal or the name of a data item of any type. Data-name may include subscripts if it refers to a table item. The Compiler calculates the value of the LENGTH OF expression and replaces it with a numeric literal equivalent to the current number of bytes of storage used by the data item or literal referenced in LENGTH OF. For example:

77 my-item PIC x(10).
78 my-item-length value LENGTH OF my-item.

becomes:

77 my-item PIC x(10).
78 my-item-length value 10.

The LENGTH OF expression can also be used in the procedure division as demonstrated in this example:

01 my-data.
   03 my-table occurs 20 times.
      05 my-element-1 pic x(10).
   05 my-element-2 pic 99.

MOVE LENGTH OF my-element-1 TO data-size.
MOVE LENGTH OF my-table TO data-size.
MOVE LENGTH OF my-table(1) TO data-size.

In this example the Compiler treats the first MOVE as MOVE 10 TO data-size, the second MOVE as MOVE 240 TO data-size, and the third MOVE as MOVE 12 TO data-size.

Note: This expression (when used on a table) works differently in ACUCOBOL-GT than in other COBOL Compilers, such as IBM Enterprise COBOL. ACUCOBOL-GT returns the size of the entire table, while IBM returns the size of a single element of the table. You can use the IBM method by compiling the program with -Cv, which turns on the Compiler’s IBM compatibility mode.

Floating-Point Literals

  1. A floating-point literal has the following format:
    [ + ] k.m { E } [ + ] n
[ - ]     { e } [ - ]

    In the above:

    • k.m represents a number with at least one digit.
    • n represents one or more digits.
    • If the functions of the decimal point and comma are switched with DECIMAL IS COMMA, then k.m will be k,m.

    Here are a few examples of floating-point numbers:

    -12.345e12
.0123E-6
123.E1
  2. Floating-point literals in the Procedure Division are stored internally as USAGE DOUBLE.
  3. The legal range of floating-point values is determined by the target machine. If you express a literal that is out of range for a particular machine, the runtime reports a warning message and substitutes the closest boundary value--either zero or the maximum floating-point value for the machine.
  4. On some computers, floating-point computations may give imprecise results. This is a hardware limitation; some floating point numbers cannot be precisely represented on some machines.
Parent topic: Program Structure


Nonnumeric Literals

A nonnumeric literal (sometimes called an alphanumeric literal) is a character string delimited at the beginning and at the end by quotation marks or apostrophes. The beginning and ending delimiters must be the same (that is, either both quotes or both apostrophes).

Nonnumeric literals may be up to 4096 characters in length. The characters contained in the delimiters may be selected from all characters available on the host computer.

To place the delimiter character in a nonnumeric literal, use two contiguous delimiter characters (either two quotes or two apostrophes). These two characters represent a single occurrence of that character.

You can also specify nonnumeric literals by supplying the hexadecimal value of the characters desired using the native character set. This can be used, for example, to encode device control codes. Any of the following formats are recognized:

X"hex-values"
X'hex-values'
H"hex-values"
H'hex-values'

The initial H or X may be either upper- or lower-case. The hex-values consist of one or more hexadecimal digits. These digits are drawn from the set of characters '0' – '9' and 'A' – 'F'. Every two hexadecimal digits represent one character position, with the first digit encoding the high-order 4 bits of the character, and the second digit encoding the low-order 4 bits. If an odd number of hexadecimal digits is specified, the low-order 4 bits of the last character are treated as zeros.

Note: In ACUCOBOL-GT h"123" is a nonnumeric literal and not numeric literal for all other dialects.

Example:

The following pairs of nonnumeric literals are equivalent (when the native character set is ASCII):

X"414243" | "ABC"
h'32313' | "210"
H"6E" | "n"
x"22" | """"
Parent topic: Program Structure


Source Formats

Terminal format is convenient for developing programs interactively. This format has the following characteristics:

  • The sequence number area is eliminated.
  • The indicator area is in column 1. All of the usual COBOL indicators are accepted here except for the conditional debugging line indicator D.
  • Area A also starts in column 1 unless an indicator is present, in which case it starts immediately after the indicator character.
  • Area B starts in column 5 and extends to the end of the line.
  • The line ends when a carriage-return or new-line is found. Lines may be longer or shorter than 80 characters.

ACUCOBOL-GT Terminal format is compatible with the VAX COBOL terminal source format, except for the introduction of the identification area, which VAX COBOL does not support. ACUCOBOL-GT Terminal mode is also compatible with ICOBOL terminal source format, except that area A must start in column 1 (in ICOBOL area A may start in column 2).

Set this terminal format using the SOURCEFORMAT"TERMINAL" Compiler directive, or using the -St compiler option.

Parent topic: Program Structure


Identification Division

Supported elements when compiling for Acu compatibility.
  • PROGRAM-ID Paragraph
Parent topic: ACUCOBOL-GT Syntax Extensions


PROGRAM-ID Paragraph

General Format

[ PROGRAM-ID. program-name [ IS {INITIAL } PROGRAM ] . ]
                                {RESIDENT}

General Rules

  1. The RESIDENT clause is an ACUCOBOL-GT extension.
  2. The RESIDENT clause specifies that the program is to remain resident in memory after its first execution. A program with the RESIDENT clause cannot be affected by a CANCEL statement. Note that the RESIDENT clause shields selected programs from the effects of a CANCEL Statement.
Note: The NOCANCEL Compiler directive has the same effect as the RESIDENT clause.
Parent topic: Identification Division


Environment Division

Supported ACUCOBOL-GT Environment Division elements when compiling for ACU compatibility.
  • The File-Control Paragraph
Parent topic: ACUCOBOL-GT Syntax Extensions


SELECT (ACUCOBOL-GT File-Control Paragraph)

The File-Control Paragraph

The File-Control paragraph contains descriptions of the physical aspects of files used in a program.

Format 3 - Indexed Files

SELECT [OPTIONAL] file-name

 ASSIGN TO [DYNAMIC] [device] [file-spec]
           [EXTERNAL]

   [WITH {COMPRESSION} ... ]
         {ENCRYPTION}

     [ORGANIZATION IS] INDEXED.

General Rules

  1. The WITH ENCRYPTION phrase specifies that record encryption is required on the file. Encryption is currently available with the Vision indexed file system only. Encryption takes effect only when the file is initially created or re-created via the OPEN statement.

  2. The WITH COMPRESSION phrase specifies that record compression is required on the file. This phrase must be specified before the ORGANIZATION IS INDEXED phrase. Compression is currently available with the Vision indexed file system only. The WITH COMPRESSION phrase takes effect only when the file is initially created or re-created via the OPEN statement.

Parent topic: Environment Division


Data Division

Supported ACUCOBOL-GT Data Division elements and types when compiling for Acu compatibility.
  • SYNCHRONIZED Clause
  • USAGE Clause
Parent topic: ACUCOBOL-GT Syntax Extensions


SYNCHRONIZED Clause

The SYNCHRONIZED clause specifies elementary item alignment on word boundaries of the computer's memory.

General Format

{SYNCHRONIZED}  [LEFT ]
{SYNC        }  [RIGHT]

Syntax Rules

  1. SYNC is an abbreviation of SYNCHRONIZED.
  2. The SYNCHRONIZED clause can be used for elementary items only.
  3. A SYNCHRONIZED clause may not be used with an external floating-point data item.

General Rules

  1. The SYNCHRONIZED clause is used to specify that word boundary alignment should be performed for the data item. Normally, data contained in records is aligned on byte boundaries. Only data items whose underlying representation is binary are affected by the SYNCHRONIZED clause.
  2. The SYNCHRONIZED clause causes the data item to be placed on a boundary that is an even multiple of the natural size of the data item. The following table lists the boundary used for each size of data item:
    Data Size | Boundary Multiple
    1-2 | 2
    3-4 | 4
    5-8 | 8
  3. A group item that contains a synchronized data item is also synchronized on the same boundary. Regardless of the effects of synchronization, a group item always begins at the same location as its first elementary data item.
  4. Synchronization may result in the creation of filler bytes. These bytes count in the size of any group item that contains them. For this reason, a group item that contains synchronized data may be larger than the total size of its elementary items.
  5. Level 01 and level 77 data items that are not otherwise synchronized are placed on a boundary that can be selected at compile time. By default, these items are placed at word boundaries that are divisible by two.
  6. Level 01 and level 77 data items that are POINTER or COMP-5 items are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. All C-style data types are automatically synchronized regardless of their level. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.
  7. A compile-time (-Dl) option can be used to cut back the maximum boundary multiple. For example, -Dl4 would cause items of size 1 or 2 to be synchronized on 2-byte boundaries, and all other items synchronized on 4-byte boundaries. If this option is not specified, then the maximum boundary multiple depends on the compatibility mode being used:
    Mode | Boundary Limit
    VAX COBOL | 8
    RM/COBOL | 2
    ICOBOL | 1

    A limit of 1 effectively inhibits synchronization.

  8. The LEFT and RIGHT options are treated as commentary. They have the same effect as a SYNCHRONIZED clause without either option.
Parent topic: Data Division


USAGE Clause

The USAGE clause specifies the format of a data item in computer memory or in a file record.

In some circumstances, a data item's file-record format may differ from its computer-memory format as specified by the USAGE clause. This can occur when non-COBOL file systems with different data storage formats are being accessed through an interface. For example, Acu4GL uses SQL to access non-COBOL file systems, and in the process a translation occurs on the data.

Note: There are numerous compiler options for affecting data storage behavior. See Data Storage Options in the ACUCOBOL-GT Compatibility section.

General Format

[ USAGE IS ] {COMPUTATIONAL                                 }
             {COMP                                          }
             {COMPUTATIONAL-1                               }
             {COMP-1                                        }
             {COMPUTATIONAL-2                               }
             {COMP-2                                        }
             {COMPUTATIONAL-3                               }
             {COMP-3                                        }
             {COMPUTATIONAL-4                               }
             {COMP-4                                        }
             {COMPUTATIONAL-5                               }
             {COMP-5                                        }
             {COMPUTATIONAL-6                               }
             {COMP-6                                        }
             {COMPUTATIONAL-X                               }
             {COMP-X                                        }
             {COMPUTATIONAL-N                               }
             {COMP-N                                        }
             {BINARY                                        }
             {PACKED-DECIMAL                                }
             {DISPLAY                                       }
             {INDEX                                         }
             {POINTER                                       }
             {FLOAT                                         }
             {DOUBLE                                        }
             {SIGNED-SHORT                                  }
             {UNSIGNED-SHORT                                }
             {SIGNED-INT                                    }
             {UNSIGNED-INT                                  }
             {SIGNED-LONG                                   }
             {UNSIGNED-LONG                                 }
             {HANDLE [ OF {WINDOW                       } ] }
                          {SUBWINDOW                    }
                          {FONT [font-name]             }
                          {control-type                 }
                          {THREAD                       }
                          {MENU                         }
                          {VARIANT                      }
                          {LAYOUT-MANAGER [layout-name] }

Syntax Rules

  1. The column on the left shows the accepted abbreviations for the terms on the right:
    COMP      COMPUTATIONAL

COMP-1    COMPUTATIONAL-1

COMP-2    COMPUTATIONAL-2

COMP-3    COMPUTATIONAL-3

COMP-4    COMPUTATIONAL-4

COMP-5    COMPUTATIONAL-5

COMP-6    COMPUTATIONAL-6

COMP-X    COMPUTATIONAL-X

COMP-N    COMPUTATIONAL-N
  2. A USAGE clause may be used in any data description entry except those with level-numbers 66, 78, and 88.
  3. A USAGE clause may not be used with an external floating-point data item.
  4. If a USAGE clause is in the data description entry for a group item, then any USAGE clauses that appear for subordinate entries must be of the same type.
  5. The PICTURE string of a COMP, COMP-1, COMP-2, COMP-3, COMP-4, COMP-5, COMP-6, BINARY, or PACKED-DECIMAL item can contain only the symbols "9", "S", "V", and "P". COMP-6 items may not use the "S" symbol.
  6. The PICTURE string of a COMP-X or COMP-N item may contain only all "9" symbols or all "X" symbols.
  7. The data description entry for a USAGE IS INDEX data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, PICTURE, and VALUE IS.
  8. Level 88 items may not be specified for a USAGE IS INDEX data item.
  9. The data description entry for a USAGE IS POINTER data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. A POINTER data item may have a value clause specified for it, but the value must be the word NULL.
  10. The data description entry for a USAGE IS FLOAT or a USAGE IS DOUBLE data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. FLOAT or DOUBLE data items may have a value clause. The value may be a floating point literal, a numeric literal, or the word ZERO. Here is an example of a Working-Storage Section data item:
    01  F-DATA-1  USAGE IS FLOAT
              VALUE IS 3.97E+24.
  11. The following are collectively called the "C-style" data types: SIGNED-INT, UNSIGNED-INT, SIGNED-SHORT, UNSIGNED-SHORT, SIGNED-LONG, UNSIGNED-LONG. These data types are similar to the data types found in the C programming language.

    The data description entry for a C-style data type cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE.

  12. Control-type is one of the graphical control type names known to the compiler, such as LABEL or ENTRY-FIELD, or the name of an ActiveX, COM, or .NET control.
  13. The data description entry for USAGE HANDLE data items may not contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. If it contains a VALUE clause, the value specified must be the word NULL.
  14. Font-name is one of the following identifiers: DEFAULT-FONT, FIXED-FONT, TRADITIONAL-FONT, SMALL-FONT, MEDIUM-FONT, LARGE-FONT.
  15. It should be noted that either the "-Df" option or the "-Cv" option will cause the compiler to treat COMP-1 and COMP-2 as FLOAT and DOUBLE, respectively. For more information, see section 5.4 in Transitioning to ACUCOBOL-GT.
  16. Layout-name is the name of one of the system's standard layout managers. Currently, this can only be LM-RESIZE.

General Rules

  1. A USAGE clause written at a group level applies to every elementary item subordinate to that group item.
  2. If no USAGE clause is specified, then USAGE IS DISPLAY is implied.
  3. The internal format of a USAGE IS DISPLAY item is ASCII.
  4. The format of an index item is 32-bit signed binary. Its size is always four, and it holds a range of values from -2147483647 to 2147483647. When using a compile switch for compatibility with versions prior to 6.0.0 (-Z52 for example) an index item is 16-bit unsigned binary, size is always two, and it holds values from 0 to 65535.
  5. The format of a COMP-1 data item is 16-bit signed binary. The legal values range from -32767 to 32767. The size of the data item is always two bytes, and the high-order half of the data is stored in the leftmost byte. The PICTURE string that describes the item is irrelevant. Unlike other numeric data types, a size error will occur on a COMP-1, COMP-X, or COMP-N data item only when the value exceeds the physical storage of the item (in other words, the number of "9"s in the item's PICTURE is ignored when size error is determined).
  6. For COMP-2 (decimal storage), each digit is stored in one byte in decimal format. If the value is signed, then an additional trailing byte is allocated for the sign. The storage of COMP-2 is identical with USAGE DISPLAY with the high-order four bits stripped from each byte.
  7. For COMP-3 (packed-decimal storage), two digits are stored in each byte. An additional half byte is allocated for the sign, even if the value is unsigned. The sign is placed in the rightmost position, and its value is 0x0D for negative; all other values are treated as positive (but see rule 18 below). The size of an item (including one for the implied sign) is divided by two to arrive at its actual size (rounding fractions up).
  8. The format of a COMP-4 item is two's-complement binary (the value without its decimal point). COMP-4 values are stored in a machine-independent format. This format places the highest-order part of the value in the leftmost position and follows down to the low-order part in the rightmost position. The number of bytes a data item occupies depends on the number of "9"s in its PICTURE and on the presence of various compile-time options. For example, you may include more than eighteen "9"s only if your program has been compiled for 31-digit support. This is summarized in the following table:
    # of "9"s | Default | -D1 | -Dm | -D7
    1-2 | 2 | 1 | 1 | 1
    3-4 | 2 | 2 | 2 | 2
    5-6 | 4 | 4 | 3 | 3
    7 | 4 | 4 | 4 | 3
    8-9 | 4 | 4 | 4 | 4
    10-11 | 8 | 8 | 5 | 5
    12 | 8 | 8 | 6 | 5
    13-14 | 8 | 8 | 6 | 6
    15-16 | 8 | 8 | 7 | 7
    17-18 | 8 | 8 | 8 | 8
    19 | 12 | 12 | 9 | 8,9
    20 | 12 | 12 | 9 | 9
    21 | 12 | 12 | 9 | 9
    22 | 12 | 12 | 10 | 10
    23 | 12 | 12 | 10 | 10
    24 | 12 | 12 | 11 | 10,11
    25 | 12 | 12 | 11 | 11
    26 | 12 | 12 | 11 | 11
    27 | 12 | 12 | 12 | 12
    28 | 12 | 12 | 12 | 12
    29 | 16 | 16 | 13 | 13
    30 | 16 | 16 | 13 | 13
    31 | 16 | 16 | 13 | 13
    Note: Where two values are given, the smaller value applies to unsigned data items, and the larger value applies to signed data items.
  9. COMP-5 is primarily used to communicate with external programs that expect native data storage.

    The format of a COMP-5 data item is identical to a COMP-4 data item, except that the data is stored in a machine-dependent format. It is stored in an order that is natural to the host machine. For example, a PIC S9(9) COMP-5 data item is equivalent to a 32-bit binary word on the host machine, and a PIC S9(20) COMP-5 item is equivalent to a 64-bit word.

    Note: Data stored in a COMP-5 field may not be transportable to other machines because different machines have different natural byte-orderings. On many machines (68000, most RISC), COMP-5 is identical to COMP-4. On others (80x86, VAX), it is the same with the bytes in the reverse order.

    A VALUE clause for a COMP-5 data item is stored in a machine-independent format and is adjusted when it is loaded into the data item. This ensures that the value is the same from machine to machine.

    On arithmetic and non-arithmetic stores into COMP-5 items, if truncation is required, by default ACUCOBOL-GT truncates in decimal to the number of digits given in the PICTURE clause. You can use the "--TruncANSI" compiler option to force truncation in binary to the capacity of the allocated storage of COMP-5 items. The "-Dz" and "--noTrunc"options also effects truncation. See Book 1, section 2.1.9, "Data Storage Options," for more information.

    Level 01 and level 77 data items that are COMP-5 are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

    If COMP-5 is used with a PIC X(n) data item and assigned an alphanumeric value, the results are undefined. For example, the following code fragment causes NUM to have an undefined number and the resulting value for the last line will be "100":

    NUM PIC X(5) COMP-5.
ALPHANUM PIC X(9).
MOVE "ABC" TO NUM.
MOVE "1,000" TO NUM.
MOVE ALPHANUM TO NUM.
MOVE "100" TO NUM.

    A PIC X(n) data item used with COMP-5 cannot be signed.

  10. The format of a COMP-6 item is identical to a COMP-3 item except that it is unsigned and no space is allocated for the sign. If the number of digits is odd, a zero is added to the left end of the number before it is packed. Thus there are two decimal digits per byte, and the actual size of the item is determined by dividing its PICTURE size by two and rounding up.
  11. A COMP-X data item must be described with a picture string consisting of only "9" or only "X" symbols. In either case, the data item is treated as an unsigned binary integer, with internal storage similar to that of a COMP-4 data item. If "X" symbols are used to describe the item, then the number of bytes allocated to the item is the same as the number of "X" symbols in the picture string. If "9" symbols are used instead, then the number of bytes allocated is the least number of bytes required to hold a number of that size. For example, a "PIC 99" data item will be allocated 1 byte; a "PIC 9(9)" data item will be allocated 4 bytes.

    Regardless of the number of "9" symbols in the item's picture string, the maximum value that can be stored in a COMP-X item is determined by the number of bytes allocated to it (to a maximum of 18 digits, or a maximum of 31 digits if 31-digit support is in effect). For example, a COMP-X item consisting of 1 byte can hold a range of numbers from 0 to 255. A 2-byte COMP-X number can hold from 0 to 65535. A size error occurs on a COMP-X item only when the value is larger than the data item can physically hold. When COMP-X is used with a PIC(X) data item, the maximum is PIC X(8). (This maximum is increased to PIC X(16) when 31-digit support is in effect.)

  12. A COMP-N data item is identical to a COMP-X data item, except that the data is stored in the host machine's native format, instead of machine-independent format.
  13. Data items described as PACKED-DECIMAL are identical to COMP-3. You can cause unsigned PACKED-DECIMAL to be treated as COMP-6 by using a compile-time option.
  14. By default, a BINARY data item is identical to a COMP-4 data item. The compile-time option "-D5" treats BINARY data items as COMP-5 items instead.
  15. In VAX/COBOL compatibility mode, a COMP data item is the same as COMP-4 and is treated as binary data. In RM/COBOL compatibility mode, COMP is the same as COMP-2. You can use compile-time options to change the default behavior.
  16. A pointer data item is treated as an unsigned numeric data item. The internal format differs for each machine. Pointer data items are intended to hold addresses of other data items (see the SET Statement.) A pointer data item may have a VALUE clause specified for it, but the specified value must be the word NULL. This indicates that the pointer does not currently point to any item. If a pointer is not explicitly given an initial value, then its initial value is arbitrary.

    Pointer data items occupy 8 bytes. This provides enough space to hold an address on a 64-bit machine. If you are on a smaller machine, the runtime uses only the first 4 bytes of pointer data items (the trailing 4 bytes remain in memory, they are just left unused). You can use the "-Dw" compile-time option to adjust the space allocated to pointer data items. You can do this to conserve storage if you know you will not be running on a 64-bit machine.

    Pointers may be used in conditional expressions, where they can be compared to each other or to the value NULL. A comparison involving a pointer must be either "equals" or "not equals" ("greater" and "less than" comparisons are not allowed).

    Level 01 and level 77 data items that are POINTER items are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

    Except for the automatic synchronization, USAGE POINTER data items are treated in all respects like USAGE UNSIGNED-LONG data items. This handles all current machines correctly. This behavior may change to meet the requirements of some future machine.

  17. Floating-point data items are stored in a machine-dependent format. USAGE FLOAT items have 4 bytes allocated to them. USAGE DOUBLE items occupy 8 bytes.

    Level 01 and level 77 data items that are USAGE FLOAT or DOUBLE are automatically synchronized to appropriate machine boundaries, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

  18. The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). ACUCOBOL-GT lets you select alternate sign-storage conventions by using the compile-time options "-Dca", '-Dcb", "-Dci", "-Dcm", "-Dcn", "-Dcr", and "-Dcv". Specifying a sign-storage convention is sometimes useful when you are exporting and importing data. For additional information, see the User's Guide, section 2.2.10, "Data Storage Options."

    The storage convention affects how data appears in USAGE DISPLAY, COMP-2, and COMP-3 data types. In USAGE DISPLAY, standard ASCII storage, if the sign is incorporated into a digit position, the digit is encoded according to the following table:

    USAGE DISPLAY

    DIGIT VALUE -Dca,

    -Dcb,

    -Dcm,

    -Dcr

    Positive

            -Dci,

    -Dcn

    Positive

            -Dca,

    -Dci,

    -Dcn

    Negative

            -Dcb

    Negative

            -Dcm

    Negative

            -Dcr

    Negative

    0 '0' '{' '}' '@' 'p' ' ' (space)
    1 '1' 'A' 'J' 'A' 'q' '!'
    2 '2' 'B' 'K' 'B' 'r' '"' (double-quote)
    3 '3' 'C' 'L' 'C' 's' '#'
    4 '4' 'D' 'M' 'D' 't' '$'
    5 '5' 'E' 'N' 'E' 'u' '%'
    6 '6' 'F' 'O' 'F' 'v' '&'
    7 '7' 'G' 'P' 'G' 'w' ''' (single-

    quote)

    8 '8' 'H' 'Q' 'H' 'x' '('
    9 '9' 'I' 'R' 'I' 'y' ')'
    Note:

    For import compatibility with some systems that do not have the symbols "{" and "}", the symbols "[" and "?" are considered equivalent to "{", and the symbols "]", ":", and "!" are considered equivalent to "}", when an item with USAGE DISPLAY is read.

    The next two tables show sign representation for COMP-2 and COMP-3 items, when you are using the "-Dca", "-Dcb", "-Dci", "-Dcm", "-Dcn", "-Dcr", and "-Dcv" storage conventions. For COMP-2, the trailing byte is reserved for the sign. For COMP-3, the trailing half-byte is reserved for the sign.

    USAGE COMP-2

    -Dca Positive | x'0B'
    -Dcb/-Dci/-Dcm/-Dcn/-Dcr Positive | x'0C'
    -Dca/-Dcb/-Dci/-Dcm/-Dcn/-Dcr Negative | x'0D'

    USAGE COMP-3

    -Dca Positive | x'0F'
    -Dcb/-Dci/-Dcm/-Dcr Positive | x'0C'
    -Dca/-Dcb/-Dci/-Dcm/-Dcr Negative | x'0D
    -Dca/-Dcb/-Dci/-Dcm/-Dcr Unsigned | x'0F'
    -Dcv Unsigned | x'0C'
  19. There are six USAGE types for integer data that simplify communications with other programming languages such as C. These types are designed to provide a portable method for handling machine-dependent data. The six USAGE types handle three classes of machine data: "short words," "words," and "long words." These three correspond to the C data types: "short", "int", and "long". There are signed and unsigned versions of each of these data types.

    These USAGE types are specified without a PICTURE clause (like USAGE INDEX and POINTER).

    The names of the types are:

    SIGNED-SHORT | UNSIGNED-SHORT
    SIGNED-INT | UNSIGNED-INT
    SIGNED-LONG | UNSIGNED-LONG

    Each of these represents a binary value that is stored using the machine's native byte ordering. Since there is no PICTURE phrase, size checking for these items is performed only on byte boundaries. These data types are automatically SYNCHRONIZED.

    The unusual characteristic of these data types is that their size is not necessarily set at compile time. Instead, the size of these items is determined at execution time. This allows them to match the working characteristics of the host machine. For example, a SIGNED-LONG data item will contain 64 bits when run on a DEC Alpha machine, but it will have 32 bits when run on an Intel 80486-based machine. This lets you write one program that can communicate effectively with an external routine written in another language (such as C), regardless of the target environment.

    In order to lay out memory, the compiler assigns a maximum size to each of these data types. This is the number of bytes that the item will occupy. At run time, these items may be reduced in size to match the host machine's characteristics. Any remaining bytes are then treated as FILLER. The "-Dw" compile option (see the User's Guide section 2.2.10, "Data Storage Options.") determines the maximum size of these types:

    USAGE -Dw32 -Dw64
    SIGNED-SHORT

    UNSIGNED-SHORT

            2* 2*
    SIGNED-INT

    UNSIGNED-INT

            4 4
    SIGNED-LONG

    UNSIGNED-LONG

            4* 8

    Table entries marked with an asterisk indicate fixed-size items. A fixed-size item is the same size regardless of the target machine. Entries without an asterisk are variable in size. These items will occupy space up to the number of bytes listed in the table.

    Note: The sizes listed in the table above cover all current and anticipated machines that run ACUCOBOL-GT. Future architectures may require changes to the maximum size assigned to these items.

    In the execution environment, these items act in all ways as if they were fixed-size data items of the appropriate size.

    For example, the following code fragment:

       77  LONG-1         SIGNED-LONG.
   77  SIZE-1         PIC 9.

   SET SIZE-1 TO SIZE OF LONG-1.
   DISPLAY SIZE-1.

    will print "4" when run on a 32-bit machine, but it will print "8" when run on a 64-bit machine.

    Examples

    In the following examples, each byte is represented by two hexadecimal digits or by a single quoted character. Each value is shown in the various formats. Also shown is USAGE DISPLAY using the various SIGN options. The following examples use the default ACUCOBOL-GT sign-storage conventions.

    PIC 9(3) VALUE 123.
TRAILING            '1'   '2'   '3'
TRAILING SEPARATE   '1'   '2'   '3'
LEADING             '1'   '2'   '3'
LEADING SEPARATE    '1'   '2'   '3'
COMP-1                    00    7B
COMP-2              01    02    03
COMP-3                    12    3F
COMP-4                    00    7B
COMP-5(68000)             00    7B
COMP-5(8086)              7B    00
COMP-6                    01    23

PIC S9(3) VALUE -123.
TRAILING                 '1'   '2'   'L'
TRAILING SEPARATE  '1'   '2'   '3'   '-'
LEADING                  'J'   '2'   '3'
LEADING SEPARATE   '-'   '1'   '2'   '3'
COMP-1                         FF    85
COMP-2             01    02    03    0D
COMP-3                         12    3D
COMP-4                         FF    85
COMP-5(68000)                  FF    85
COMP-5(8086)                   85    FF
COMP-6             illegal

PIC 9(5)V9 VALUE 12345.6.
TRAILING             '1'   '2'   '3'   '4'   '5'   '6'
TRAILING SEPARATE    '1'   '2'   '3'   '4'   '5'   '6'
LEADING              '1'   '2'   '3'   '4'   '5'   '6'
LEADING SEPARATE     '1'   '2'   '3'   '4'   '5'   '6'
COMP-1               illegal
COMP-2               01    02    03    04    05    06
COMP-3                           01    23    45    6F
COMP-4                           00    01    E2    40
COMP-5(68000)                    00    01    E2    40
COMP-5(8086)                     40    E2    01    00
COMP-6                                 12    34    56

PIC S9(5)V9 VALUE -12345.6.
TRAILING                '1'  '2'  '3'  '4'  '5'  '0'
TRAILING SEPARATE  '1'  '2'  '3'  '4'  '5'  '6'  '-'
LEADING                 'J'  '2'  '3'  '4'  '5'  '6'
LEADING SEPARATE   '-'  '1'  '2'  '3'  '4'  '5'  '6'
COMP-1             illegal
COMP-2             01   02   03   04   05   06   0D
COMP-3                            01   23   45   6D
COMP-4                            FF   FE   1D   C0
COMP-5(68000)                     FF   FE   1D   C0
COMP-5(8086)                      C0   1D   FE   FF
COMP-6             illegal
  20. HANDLE data items make up their own data class and category in COBOL. Internally they are stored as integer values, and behave like numbers when used. A HANDLE data item is normally used to store the handle of a dynamically created object such as a floating window or a graphical control.

    HANDLE data items come in two forms: typed and generic. You create a generic handle when you omit the OF phrase. You create a typed handle when you include the OF phrase.

  21. You may use HANDLE data items only when explicitly allowed, or as part of a MOVE statement, a CALL statement (as a parameter), or in a Boolean expression.
  22. Generic handles may be used in any situation where handles are allowed. When you use a generic handle as the source of a MODIFY statement, you will not be able to use any control-specific property or style names in that statement. This is because the generic handle could be associated with any type of control. In this case, the compiler cannot determine which set of style and property names is valid.
  23. Typed handles may be used in statements where any handle is allowed, or when you are referring to an object of a matching type. For example, a HANDLE OF WINDOW cannot be used as the handle in a DISPLAY LABEL statement. Instead, you must use either a generic handle or a HANDLE OF LABEL. Typed handles allow the compiler to recognize associated style and property names when appropriate. Typed handles also improve the readability of your program by providing additional information about the intended use of the handle, in addition to providing compile-time checking to ensure that you are using the handles in appropriate situations.
  24. Handles may be used in comparisons. There are only two meaningful comparisons: checking for equality or inequality to NULL, and comparison to another handle data item. A handle value of NULL always indicates an invalid handle.
  25. Handles are stored internally as 4-byte binary integers. This information can be useful when you are debugging a program (you can examine the values of handles in the debugger). You should not rely on this definition in your program, however, because it is subject to change in the future.
  26. Handle data items are automatically SYNCHRONIZED on a 4-byte boundary. Note that this occurs regardless of the setting of the "-Dl" compile-time option (which limits the amount of synchronization). The runtime system requires this level of alignment to avoid generating bus errors on some machines.
  27. If font-name is specified, then the data item described by the USAGE clause is initialized at program startup with the corresponding font handle. This acts identically to placing the statement:
    ACCEPT data-item FROM STANDARD OBJECT "font-name"

    at the beginning of your program, where data-item is the data item described by the USAGE clause and font-name is the same as font-name in the USAGE clause.

Parent topic: Data Division
Related tasks
Data Storage Options


Procedure Division

Supported ACUCOBOL-GT extensions to Procedure Division statements and elements when compiling for Acu compatibility.
  • Procedure Division Statements
    Supported ACUCOBOL-GT extensions to Procedure Division statements and elements when compiling for Acu compatibility.
Parent topic: ACUCOBOL-GT Syntax Extensions


Procedure Division Statements

Supported ACUCOBOL-GT extensions to Procedure Division statements and elements when compiling for Acu compatibility.
  • ACCEPT FROM
    ACUCOBOL-GT ACCEPT 3 format, which returns selected data from the operating environment.
  • ACCEPT FROM ENVIRONMENT
    ACUCOBOL-GT format 5 ACCEPT extension.
  • INSPECT
    ACUCOBOL-GT extension to the INSPECT statement.
  • OPEN Statement
    ACUCOBOL-GT extensions to the OPEN statement: WITH/FOR MASS-UPDATE and BULK-ADDITION.
  • SET ENVIRONMENT
    ACUCOBOL-GT format 6 SET extension.
Parent topic: Procedure Division


ACCEPT FROM (ACUCOBOL-GT)

ACCEPT FROM

ACUCOBOL-GT ACCEPT 3 format, which returns selected data from the operating environment.

Syntax

ACCEPT dest-item FROM {CENTURY-DATE}
                                            {CENTURY-DAY }

General Rules

  1. The Format 3 ACCEPT statement causes information to be transferred to dest-item according to the rules for the MOVE statement.
  2. ACCEPT FROM CENTURY-DATE returns the current date in the format YYYYMMDD (year/month/day). ACCEPT FROM DATE YYYYMMDD is equivalent to ACCEPT FROM CENTURY-DATE. ACCEPT FROM CENTURY-DAY returns the current date in the format YYYYDDD (year/day-of-year). ACCEPT FROM DAY YYYYDDD is equivalent to ACCEPT FROM CENTURY-DAY. These are the same as ACCEPT FROM DATE and ACCEPT FROM DAY, except that the year field is 4 digits instead of 2 digits.

    The compiler option -Zy lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. For details, see the ACUCOBOL-GT User's Guide documentation.

Parent topic: Procedure Division Statements


ACCEPT FROM ENVIRONMENT

ACUCOBOL-GT format 5 ACCEPT extension.

Format 5

ACCEPT dest-item FROM {ENVIRONMENT} env-name

      [ ON EXCEPTION statement-1 ]

      [ NOT ON EXCEPTION statement-2 ]

      [ END-ACCEPT ]

Syntax Rules

  1. dest-item is a data item that receives the accepted data. It must be USAGE DISPLAY unless the WITH CONVERSION phrase is also used.
  2. EXCEPTION and ESCAPE are equivalent.
  3. A NOT AT END phrase may not be paired with an ON EXCEPTION phrase, nor may a NOT ON EXCEPTION phrase be paired with an AT END phrase.
Note: ACCEPT FROM CONFIGURATION is not supported.

General Rules

  1. A Format 5 ACCEPT statement returns values from the user's environment. Env-name is the name of the environment setting whose value is to be returned. The value returned from this item is moved to dest-item.
    Note: ACUCOBOL-GT allows you to specify an ACUCOBOL-GT runtime configuration variable for Env-name. This COBOL system does not support specifying runtime configuration variables.
Parent topic: Procedure Division Statements


INSPECT

ACUCOBOL-GT extension to the INSPECT statement.

Formats 1 and 2

Formats 1 and 2 are identical to MF COBOL. Refer to the Micro Focus COBOL Language Reference section or the ACUCOBOL-GT Reference manual.

Format 3

INSPECT source

    [ TALLYING counter FOR TRAILING comp-value ]
    [ REPLACING TRAILING target BY replace ]

TRAILING is an ACUCOBOL-GT extension. It is used to find the rightmost occurrence, or set of contiguous occurrences, in the source data item. If a TRAILING occurrence is found, a right to left scan of the source data item is made to find contiguous occurrences.

If the TRAILING phrase is present, the REPLACING option causes all contiguous occurrences of target to be replaced by replace, provided that these occurrences end in the rightmost character position of source.

Source and Comp-value must be of usage DISPLAY.

Comp-value, Target, and Replace must be nonnumeric literals or single-character alphanumeric data items.

Parent topic: Procedure Division Statements
Related information
The INSPECT Statement


OPEN Statement

ACUCOBOL-GT extensions to the OPEN statement: WITH/FOR MASS-UPDATE and BULK-ADDITION.

Syntax:

OPEN { {OUTPUT} { file [ {WITH} {MASS-UPDATE  } ] } ... } ...
       {I-O   }          {FOR } {BULK-ADDITION}
       {EXTEND}

Syntax Rules:

  1. The MASS-UPDATE and BULK-ADDITION phrases may be specified only for indexed files, and may not be specified along with the INPUT phrase.
  2. You must compile with the DIALECT"ACU" Compiler directive.

General Rules:

  1. The WITH MASS-UPDATE phrase is equivalent to the WITH LOCK phrase with some additional effects. It may be specified only for indexed files. This phrase indicates to the runtime system that the file in question will be heavily updated by this program. The runtime system may be able to use this information to access the file more efficiently.
  2. The BULK-ADDITION phrase is equivalent to the MASS-UPDATE phrase with some additional effects. For Vision files, the BULK-ADDITION phrase opens the file in "bulk addition" mode, which substantially increases efficiency when you are writing a large number of new records to the file. BULK-ADDITION has several significant effects, including some changes to standard COBOL file handling rules. See section 6.1.6.3 of ACUCOBOL-GT User's Guide for details. For host file systems other than Vision, specifying BULK-ADDITION has the same effect as specifying MASS-UPDATE. In this case, none of the special handling dictated by BULK-ADDITION applies.
Parent topic: Procedure Division Statements


SET ENVIRONMENT

ACUCOBOL-GT format 6 SET extension.

FORMAT 6

SET { env-name TO env-value } ...
    {ENVIRONMENT  }
Note: The CONFIGURATION option that is supported in ACUCOBOL-GT is not supported in Visual COBOL.

Syntax Rules

  1. env-name is a nonnumeric literal or data item.
  2. env-value is a USAGE DISPLAY numeric or nonnumeric literal or data item. If numeric, it must be an integer.

General Rules

  1. A format 6 SET statement is used to set environment variables. ACUCOBOL-GT maintains a set of configuration variables that can affect various aspects of the runtime system. These variables can be initially set in the ACUCOBOL-GT runtime configuration file described in Appendix H of the ACUCOBOL-GT Appendices Manual. The Format 6 SET statement can be used to modify these values at runtime.
    Note: ACUCOBOL-GT allows you to set runtime configuration variables and to change their values. This COBOL system does not support this functionality.
Parent topic: Procedure Division Statements


Data General Interactive COBOL V1.3 Syntax Support

The syntax listed here is accepted by your COBOL system purely for compatibility with version 1.3 of Data General Interactive COBOL. Many features found in Data General Interactive COBOL exist already in this COBOL implementation. These are documented in your COBOL Language Reference. Some of the compatibility syntax listed in this chapter is identical to standard COBOL syntax, but behaves differently if you set the DG Compiler directive when you submit your source code to your COBOL system. See the Data General Interactive Programmer's Reference Manual for a full description of the Data General syntax.

Note: Setting the DG Compiler directive does not affect the reserved words at all.
  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Additional Dialect Support
Related concepts
The DG Directive
Related reference
DG
Related information
COBOL Language Reference


Environment Division

  • Switch-Names
  • File-Name on Disk
  • The DATA SIZE Clause
  • The INDEX SIZE Clause
  • Duplicate Alternate Keys
  • Alternate Keys
  • I-O-Control Paragraph
Parent topic: Data General Interactive COBOL V1.3 Syntax Support


Switch-Names

In addition to the switches 0 to 8 supported by COBOL, another form of switch-name can be used. It is an upper-case letter in the range A to Z.

These letters are mapped to switches 0 to 25, so at run time you should use the appropriate digit on your command line and not the letter itself.

For example, to turn on switch J you would put:

+9 filename

after the run command. You cannot, however, specify a run-time switch in a CALL statement, as in:

CALL "PROG.INT/A"

because this is not supported.

Parent topic: Environment Division


File-Name on Disk

When you assign a file to disk, the file on disk is named in upper case letters, regardless of whether the name you specify is in upper- or lowercase letters.

Parent topic: Environment Division


The DATA SIZE Clause

You can use the following clause in a SELECT statement:

It is treated as documentary.

Parent topic: Environment Division


The INDEX SIZE Clause

You can use the following clause in a SELECT statement for a relative or indexed file:

It is treated as documentary.

Parent topic: Environment Division


Duplicate Alternate Keys

If you specify the DG Compiler directive when you submit your source files to your COBOL system, you can have duplicate alternate keys in an indexed file regardless of whether or not you have specified the DUPLICATES phrase.

Parent topic: Environment Division


Alternate Keys

If you specify the DG Compiler directive when you submit your source files to your COBOL system, alternate keys can occupy the same area as primary keys.
Note: Note , however, that under UNIX, if you issue START and/or READ statements, you will receive an error message. This will not stop your program running, but is merely to inform you that you might ncounter problems with that coding.
Parent topic: Environment Division


I-O-Control Paragraph

If you specify the DG Compiler directive when you submit your source files to your COBOL system, the SAME AREA phrase is treated as equivalent to the SAME RECORD AREA phrase.

Parent topic: Environment Division


Data Division

  • VALUE Clause
  • The Screen Section
Parent topic: Data General Interactive COBOL V1.3 Syntax Support


VALUE Clause

A numeric literal can be used in a VALUE clause in the data description of a nonnumeric data item.

Parent topic: Data Division


The Screen Section

If you specify the DG Compiler directive when you submit your source files to your COBOL system, the HIGHLIGHT option when used with TO or USING items highlights all the non-protected areas of the screen.

Parent topic: Data Division


Procedure Division

  • The CALL Statement
  • The COPY INDEXED Statement
  • The DISPLAY Statement
  • File Sharing Syntax
  • The OPEN Statement
  • The READ Statement
Parent topic: Data General Interactive COBOL V1.3 Syntax Support


CALL Statement (DG I COBOL)

The CALL Statement

General Format

The following format of the CALL statement is supported:

General Rules

  1. This format is treated as equivalent to a CHAIN statement.
Parent topic: Procedure Division


The COPY INDEXED Statement

If you specify the DG Compiler directive when you submit your source files to your COBOL system, the COPY verb can be followed by the word INDEXED. The word INDEXED is treated as documentary.

Parent topic: Procedure Division


The DISPLAY Statement

If you specify the DG Compiler directive when you submit your source files to your COBOL system, the behavior of the DISPLAY statement with the WITH NO ADVANCING option is changed to be as in Data General Interactive COBOL.

Parent topic: Procedure Division


File Sharing Syntax

If you specify the DG Compiler directive when you submit your source files to your COBOL system, the default lock mode for both ISAM and relative files is MANUAL WITH LOCK ON MULTIPLE RECORDS.

Parent topic: Procedure Division


The OPEN Statement

The OPEN verb can be followed by the keyword EXCLUSIVE. It is treated as equivalent to the WITH LOCK phrase.

Parent topic: Procedure Division


The READ Statement

The file-name and the optional word RECORD can be followed by the keyword LOCK. It causes the READ statement to acquire a lock on the record read.

This does not apply to line sequential files.

Parent topic: Procedure Division


DOS/VS COBOL Support

This Micro Focus COBOL system provides limited support for DOS/VS COBOL syntax. This COBOL system provides no distinction for the VS COBOL II dialect as it is implemented on VSE/ESA as opposed to MVS and CMS.

A directive, DOSVS, is supplied to enable all DOS/VS COBOL reserved words. The Compiler directive FLAG"DOSVS" will flag any syntax that is not part of DOS/VS COBOL.

DOS/VS COBOL is identical to OS/VS COBOL, apart from the differences below:

If the ASSIGN (EXTERNAL) Compiler directive has been set, the variable to be defined in the SET command is either:

  1. all of the text following the last hyphen, if it is not one of P, R, S, SR or AS, or;
  2. that part of the name preceding the first hyphen.

In the Special Registers table (see the section Special Registers), an entry should be made for DOS/VS COBOL as follows:

Special Register:

COM-REG

Implicit Data Description Picture:

PIC X(11)

Usage:

In DOS/VS COBOL, this field corresponds to bytes 12 through 22 of the DOS Communication Region. In the Micro Focus COBOL system, however, the data area is simply allocated, is initialized, and has no special meaning attached to any data that is placed in it by the program.

Parent topic: Additional Dialect Support
Related information
Special Registers


Microsoft COBOL V1.0 and V2.0 Syntax Support

The Microsoft syntax listed in this chapter is accepted by your COBOL system purely for compatibility with IBM 1.0 syntax and Microsoft V2.0 syntax. Many features found in Microsoft COBOL exist already in COBOL. Some of the compatibility syntax listed in this chapter is identical to standard COBOL syntax, but behaves differently if you set the MS Compiler directive when you submit your source code to your COBOL system. Other Microsoft syntax is available only if this directive is set. See your IBM COBOL 1.0 manual and the Microsoft COBOL V2.0 manual for further information on the Microsoft syntax. This manual covers IBM COBOL V1.0; where syntax is a Microsoft V2.0 extension it is explicitly indicated.

  • Special Registers LIN and COL
  • Environment Division
  • Data Division
  • Procedure Division
  • Microsoft V2.0 Additional Syntax Support
Parent topic: Additional Dialect Support


Special Registers LIN and COL

LIN and COL are intended to be used for specifying the line number and column number, respectively, of the current cursor position on the screen. Together they form part of the position-spec phrase which is supported in the ACCEPT, DISPLAY and EXHIBIT statements documented later in this chapter. You must set the MS Compiler directive when you submit your source code to your COBOL system if it contains these registers.

The format of both LIN and COL is PIC S9(4) COMP. They are used like ordinary data items, except that they must not be declared; they are automatically declared by the system. You must set them to the desired values before using them in the position-spec phrase.

Note that COL, the abbreviation for COLUMN, is not available as a COBOL reserved word if the MS Compiler directive is set.

Parent topic: Microsoft COBOL V1.0 and V2.0 Syntax Support


Environment Division

  • The Special-Names Paragraph
Parent topic: Microsoft COBOL V1.0 and V2.0 Syntax Support


The Special-Names Paragraph

The following two clauses are supported:

where: n is an integer in the range 0 to 8. The default setting is OFF.

Parent topic: Environment Division


Data Division

  • The USAGE Clause
Parent topic: Microsoft COBOL V1.0 and V2.0 Syntax Support


The USAGE Clause

General Format

The following format of the USAGE clause is supported:

Syntax Rules

  1. COMP and COMPUTATIONAL are synonymous.
  2. COMP-0 and COMPUTATIONAL-0 are synonymous.

General Rules

  1. USAGE IS COMPUTATIONAL means the same as USAGE IS DISPLAY, if you set the MS Compiler directive when you submit your source code to your COBOL system.
  2. USAGE IS COMP-0 is allowed only with numeric items. If an item is described with a PICTURE no larger than S9(4), the effect is a data item whose description is PIC S9(4) USAGE COMP; that is, a 2-byte signed binary item. Otherwise, the effect is a data item with the PICTURE clause actually specified and with USAGE DISPLAY.
Parent topic: Data Division


Procedure Division

  • The Position-Specification Phrase
  • The ACCEPT Statement
  • The DISPLAY Statement
  • The EXHIBIT Statement
Parent topic: Microsoft COBOL V1.0 and V2.0 Syntax Support


The Position-Specification Phrase

The position-specification phrase specifies the screen position in the ACCEPT, DISPLAY and EXHIBIT statements described in this chapter. You must set the MS Compiler directive when you submit your source code to your COBOL system if it contains this phrase.

General Format

Syntax Rules

  1. The comma shown in the above format is mandatory.
Parent topic: Procedure Division


ACCEPT (Microsoft COBOL V1.0 and V2.0)

The ACCEPT Statement

The following format of the ACCEPT statement is supported:

General Format

General Rules

  1. The ACCEPT operation treats a group item as an elementary item, if you set the MS Compiler directive when you submit your source code to your COBOL system: it accepts the item itself and not its subordinate elementary items.
  2. If the screen position at which the first operand is to appear is not specified, the default is the current cursor position, if you set the MS Compiler directive when you submit your source code to your COBOL system.
  3. Rules 1 and 2 above also apply to Format 5 of the ACCEPT statement as described in the topic The ACCEPT Statement.
  4. The WITH phrase options and their equivalents are:

    AUTO/AUTO-SKIP BACKGROUND-COLOR BELL/BEEP BLINK FOREGROUND-COLOR LENGTH-CHECK REVERSE-VIDEO RIGHT-JUSTIFY SECURE/NO-ECHO SIZE SPACE-FILL TRAILING-SIGN UNDERLINE UPDATE ZERO-FILL

    These options also apply to Format 5 of the ACCEPT statement as described in the topic The ACCEPT Statement.

    The options listed below differ from standard COBOL, as follows:

    1. UPDATE. If the UPDATE option is not specified, a data item for data entry is displayed initially as spaces, if you set the MS Compiler directive when you submit your source code to your COBOL system. (If the MS directive is not set, the display of initial data is a configuration option.)

      If the UPDATE option is specified, initial data of the data item for data entry is displayed.

    2. PROMPT. This option need not be specified to display prompt characters, if you set the MS Compiler directive when you submit your source code to your COBOL system.
    3. LENGTH-CHECK. If this option is specified, it causes an implicit EMPTY-CHECK option, so that the operator must enter something. You set the MS Compiler directive when you submit your source code to your COBOL system, if you have specified this option.
  5. FOREGROUND-COLOR and BACKGROUND-COLOR. Integer-1 in these options specifies the foreground color and background color of the screen item respectively, and can be defined by a value from 0 to 15, as follows:
    0 | black | 8 | grey
    1 | blue | 9 | light blue
    2 | green | 10 | light green
    3 | cyan | 11 | light cyan
    4 | red | 12 | light red
    5 | magenta | 13 | light magenta
    6 | brown | 14 | yellow
    7 | white | 15 | high intensity white

    On a color screen, if the FOREGROUND-COLOR option specifies an integer whose value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the HIGHLIGHT option. On a monochrome screen, this is equivalent to simply specifying the HIGHLIGHT option.

    On a color screen, if the BACKGROUND-COLOR option specifies an integer whose value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the BLINK option. On a monochrome screen, this is equivalent to simply specifying the BLINK option.

Parent topic: Procedure Division
Related information
The ACCEPT Statement


DISPLAY Statement (Microsoft COBOL)

The DISPLAY Statement

General Format

The following format of the DISPLAY statement is supported:

General Rules

  1. The DISPLAY operation treats a group item as an elementary item, if you set the MS Compiler directive when you submit your source code to your COBOL system: it displays the item itself and not its subordinate elementary items.
  2. If the screen position at which the first operand is to appear is not specified, the default is the current cursor position, if you set the MS Compiler directive when you submit your source code to your COBOL system.
  3. Rules 1 and 2 above also apply to Format 3 of the DISPLAY statement as described in the topic The DISPLAY Statement.
  4. If ERASE is specified, the screen is cleared from the current cursor position onwards.

The following two rules are additional rules which apply to Format 3 of the DISPLAY statements described in the topic The DISPLAY Statement.

  1. The WITH phrase options and their synonyms are:

    BACKGROUND-COLOR BELL/BEEP BLANK BLINK FOREGROUND-COLOR HIGHLIGHT REVERSE-VIDEO SIZE UNDERLINE

  2. FOREGROUND-COLOR and BACKGROUND-COLOR. Integer-1 in these clauses specifies the foreground color and background color of the screen item respectively, and can be defined by a value from 0 to 15, as follows:
    0 | black | 8 | grey
    1 | blue | 9 | light blue
    2 | green | 10 | light green
    3 | cyan | 11 | light cyan
    4 | red | 12 | light red
    5 | magenta | 13 | light magenta
    6 | brown | 14 | yellow
    7 | white | 15 | high intensity white

    On a color screen, if the FOREGROUND-COLOR option specifies an integer whose value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the HIGHLIGHT option. On a monochrome screen, this is equivalent to simply specifying the HIGHLIGHT option.

    On a color screen, if the BACKGROUND-COLOR option specifies an integer whose value is from 8 to 15, this is equivalent to specifying an integer from 0 to 7 and specifying the BLINK option. On a monochrome screen, this is equivalent to simply specifying the BLINK option.

Parent topic: Procedure Division
Related information
The DISPLAY Statement


The EXHIBIT Statement

An EXHIBIT statement with neither the CHANGED nor the NAMED option behaves as if the NAMED option were specified.

General Format

The following format of the EXHIBIT statement is supported:

Syntax Rules

  1. Mnemonic-name should be associated with sysout, syslist, syslst, syspunch, syspch, console or printer.

General Rules

  1. ERASE clears the screen from the current cursor position onwards.
Parent topic: Procedure Division


Microsoft V2.0 Additional Syntax Support

  • Record LOCKING
  • OPEN LOCKING Statement
  • READ Statement (in Manual Mode)
  • START Statement
Parent topic: Microsoft COBOL V1.0 and V2.0 Syntax Support


Record LOCKING

If you set the MS Compiler directive, the LOCKING clause in the SELECT statement is supported.

General Format

General Rules

  1. For SEQUENTIAL and LINE SEQUENTIAL files only EXCLUSIVE locking is allowed.
  2. If MANUAL is specified multiple locks can be applied to the file.
  3. If AUTOMATIC is specified a single lock is applied automatically to the current record.
  4. For SEQUENTIAL and LINE SEQUENTIAL files the default LOCKING mode is EXCLUSIVE.
  5. For RELATIVE and INDEXED files the default LOCKING mode is AUTOMATIC.
  6. If the MANUAL option is specified the UNLOCK statement will release all locks.
Parent topic: Microsoft V2.0 Additional Syntax Support


OPEN LOCKING Statement

If you set the MS Compiler directive the LOCKING clause in the OPEN statement is supported.

General Format

General Rules

  1. For SEQUENTIAL and LINE SEQUENTIAL files only EXCLUSIVE is allowed.
  2. If the NO LOCKING phase is specified EXCLUSIVE is implied.
Parent topic: Microsoft V2.0 Additional Syntax Support


READ Statement (in Manual Mode)

General Format

General Rules

  1. If you set the MS Compiler directive, the WAIT clause in the READ statement is allowed and treated as documentary.
Parent topic: Microsoft V2.0 Additional Syntax Support


START Statement

General Format

General Rules

  1. If you set the MS Compiler directive the LOCK and WAIT clauses in the START statement are allowed and treated as documentary.
Parent topic: Microsoft V2.0 Additional Syntax Support


RM/COBOL Syntax Support

The syntax listed in this chapter is accepted by your COBOL system purely for compatibility with version 12 of RM/COBOL. Many features found in RM/COBOL exist already in this COBOL implementation. Some of the compatibility syntax listed in this chapter is identical to standard COBOL syntax, but behaves differently when the DIALECT"RM" Compiler directive is set when you submit your source code. See the RM/COBOL Language Reference Manual for a full description of the RM/COBOL syntax.

  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: Additional Dialect Support
Related tasks
Converting RM/COBOL Applications


Environment Division

  • The ASSIGN Clause
  • The CODE-SET Clause
  • The ORGANIZATION Clause
  • The RECORD DELIMITER Clause
Parent topic: RM/COBOL Syntax Support


The ASSIGN Clause

General Format

The following format of the ASSIGN clause is supported:

General Rules

  1. The words INPUT, OUTPUT, INPUT-OUTPUT, PRINT and RANDOM are treated as documentary.
Parent topic: Environment Division


The CODE-SET Clause

General Format

The following format of the CODE-SET clause is supported under the DIALECT"RM" Compiler directive.

General Rules

The CODE-SET clause specifies the character code set used to represent data on the external media. See The CODE-SET Clause in the File Description Entry Skeleton. If CODE-SET is present in both the File Control Entry and File Description Entry of a file, they must contain the same value for alphabet-name.

Parent topic: Environment Division


The ORGANIZATION Clause

General Format

The following format of the ORGANIZATION clause is supported:

General Rules

  1. This clause is treated as equivalent to ORGANIZATION IS SEQUENTIAL.

    However, if you specify the RM"ANSI" Compiler directive when you submit your source code to your COBOL system, this clause is treated as equivalent to ORGANIZATION IS LINE SEQUENTIAL.

  2. If you do not specify an ORGANIZATION clause for a file then ORGANIZATION IS LINE SEQUENTIAL is assumed, providing you set the RM Compiler directive when you submit your source code to your COBOL system.

    However, if you specify the RM"ANSI" Compiler directive when you submit your source code to your COBOL system, then ORGANIZATION IS SEQUENTIAL is assumed.

Parent topic: Environment Division


The RECORD DELIMITER Clause

General Format

General Rules

  1. The RECORD DELIMITER clause may only be specified in a file control entry that describes a sequential organization file.
  2. The specified record delimiting technique is applied to the file when running under DIALECT"RM", and only when the RECORD DELIMITER clause does not conflict with the ORGANIZATION clause. When the two clauses have incompatible options set, the RECORD DELIMITER clause is ignored.
  3. The two clauses are compatible when:
    • RECORD DELIMITER is set to LINE-SEQUENTIAL, and the ORGANIZATION clause:
      • Omits the record delimiting technique (that is, specifies ORGANIZATION SEQUENTIAL).
      • Specifies ORGANIZATION LINE SEQUENTIAL.
      • Is omitted entirely (no ORGANIZATION clause, which implies SEQUENTIAL organization).
    • RECORD DELIMITER is set to BINARY-SEQUENTIAL, and the ORGANIZATION clause:
      • Omits the record delimiting technique (that is, specifies ORGANIZATION SEQUENTIAL).
      • Specifies ORGANIZATION BINARY SEQUENTIAL.
      • Specifies ORGANIZATION RECORD SEQUENTIAL.
      • Is omitted entirely (no ORGANIZATION clause, which implies SEQUENTIAL organization).
  4. Other implementor-names are accepted for the record delimiting technique as before in Visual COBOL and are ignored, even when DIALECT"RM" is in effect. (This means that if LINE-SEQUENTIAL or BINARY-SEQUENTIAL are misspelled, they will still be ignored.)
Parent topic: Environment Division
Related reference
COBCH1773 ORGANIZATION and RECORD DELIMITER clauses have incompatible options; RECORD DELIMITER ignored


Data Division

  • Default Sign Representation
  • Empty Groups
    In the Data Division, groups with no subordinate items are allowed if you set the RM Compiler directive when you submit your source code.
  • The CONTROL Clause
  • The USAGE Clause
Parent topic: RM/COBOL Syntax Support


Default Sign Representation

The syntax:

is assumed in the SPECIAL-NAMES paragraph if you set the DIALECT"RM" or RM"ANSI" Compiler directives when you submit your source code to your COBOL system. However, if you specify the RM Compiler directive or the SIGN(TRAILING-SEPARATE) directive, then NUMERIC SIGN IS TRAILING SEPARATE is assumed instead. For included signs, SIGN(EBCDIC) is assumed.

Parent topic: Data Division


Empty Groups

In the Data Division, groups with no subordinate items are allowed if you set the RM Compiler directive when you submit your source code.
Parent topic: Data Division
Related reference
DIALECT


The CONTROL Clause

General Format

The following formats of the CONTROL clause are supported under DIALECT"RM":

General Rules

  1. When an ACCEPT or DISPLAY statement is executed that implicitly or explicitly references the subject of this entry, the contents of the data item referenced by identifier-1 can contain elements of the following set in addition to those specified for the Micro Focus COBOL Control clause:

  2. If the keyword UPDATE is specified, input data conversion is implied; unless identifier-1 is numeric edited, the keywords CONVERT and NO CONVERT are ignored. In the cases when identifier-1 is numeric and UPDATE is not specified, NO CONVERT may be used to suppress implicit or explicit input conversion.
Parent topic: Data Division
Related reference
The CONTROL Clause


The USAGE Clause

The USAGE clause supports the following RM/COBOL behavior in this COBOL system.

General Formats for Format 1

The following formats of the USAGE clause are supported:

The USAGE Clause

General Formats for Format 2

The following formats of the USAGE clause are supported:

The USAGE Clause

General Syntax Rules

  1. COMP and COMPUTATIONAL are synonymous.
  2. COMP-1 and COMPUTATIONAL-1 are synonymous.
  3. COMP-3 and COMPUTATIONAL-3 are synonymous.
  4. COMP-4 and COMPUTATIONAL-4 are synonymous.
  5. COMP-5 and COMPUTATIONAL-5 are synonymous.
  6. COMP-6 and COMPUTATIONAL-6 are synonymous.

  7. The USAGE clause may be written at any level. If the USAGE clause is written at a group level, it applies to each elementary item in the group. The USAGE clause of an elementary item cannot contradict the USAGE clause of a group to which the item belongs. When the usage is COMPUTATIONAL-4, COMP-4, COMPUTATIONAL-5, COMP-5 or BINARY, the binary allocation override may also be included or omitted at any level as part of a USAGE clause at that level. If included, the binary allocation override may specify a different value than that specified in the USAGE clause for a containing group. The rules for the binary allocation override within group structure are as follows:

    • If the USAGE clause is written at a group level and specifies COMPUTATIONAL-4, COMP-4, COMPUTATIONAL-5, COMP-5, or BINARY usage with the allocation override n specified in parentheses following the usage type, the allocation override n applies to each elementary item in the group that does not specify a USAGE clause and is not subordinate to another group with a higher level-number that specifies a USAGE clause.
    • If the USAGE clause is written at a group level and specifies COMPUTATIONAL-4, COMP-4, COMPUTATIONAL-5, COMP-5, or BINARY usage without the allocation override n, the configured binary allocation scheme applies to each elementary item in the group that does not specify a USAGE clause and is not subordinate to another group with a higher level-number that specifies a USAGE clause.

Syntax Rules for Format 2

  1. n specifies the number of bytes allocated to the data item. The value of n must not be less than 1 or greater than 16.

General Rules

  1. Compile your programs with the DIALECT"RM" Compiler directive to emulate RM/COBOL behavior for these data types in this COBOL system.
Parent topic: Data Division


Procedure Division

  • Bound Checking
  • I-O Status Codes
  • Literals as CALL Parameters
  • Locked Records
  • Non-Standard Operations on Alphanumeric Data Items
  • OPEN and CLOSE on SEQUENTIAL Files
  • Procedure Names
  • REWRITE on LINE SEQUENTIAL Files
  • Size Allocation for Index Data Items
  • The ACCEPT Statement
  • The DISPLAY Statement
  • The EXIT PROGRAM Statement
  • The PERFORM Statement
  • The STOP RUN Statement
Parent topic: RM/COBOL Syntax Support


Bound Checking

If you set the RM Compiler directive when you submit your source code to your COBOL system, table subscripts are not bound checked.

Parent topic: Procedure Division


I-O Status Codes

When the DIALECT"RM" Compiler directive is in effect, the FILETYPE Compiler directive is set to 21 (RM/COBOL files); this ensures that RM/COBOL status codes are returned for I-O operations.

However, if some other FILETYPE or DIALECT (which sets another FILETYPE) is in effect, you can use the following method to continue to return RM/COBOL status codes:

Set the following option in the XFH-DEFAULT tag of the File Handler configuration file.

CONVERTSTATUS=rmstat
Parent topic: Procedure Division
Related reference
RM DIALECT setting
FILETYPE
CONVERTSTATUS
RMCOBOL File Status Codes


Literals as CALL Parameters

Literals can be used as parameters to CALL statements.

Parent topic: Procedure Division


Locked Records

If you specify the RM Compiler directive when you submit your source files to your COBOL system and a record is found to be locked, the following happens:

  • If the file has an applicable Declaratives Section and it has a file status value associated with it:
    • processing is transferred to the Declaratives Section
    • the record area contains the correct record from the read
    • the I-O status code indicates the "record locked" condition
  • If the file has no applicable Declaratives Section or file status value associated with it, the locked record is continually retried until its lock is released.
Parent topic: Procedure Division


Non-Standard Operations on Alphanumeric Data Items

Alphanumeric values can be stored in numeric data items, but will be right justified (as is normal with a numeric receiving item) and space-filled on the left. For example, if "AB" is moved to an item decribed as PIC 9(5), the value stored will be "     AB".

Parent topic: Procedure Division


OPEN and CLOSE on SEQUENTIAL Files

The RM/COBOL language permits OPEN and CLOSE statements to be specified with NO REWIND on a sequential file. In the standard COBOL language, such statements are treated as documentary only.

Parent topic: Procedure Division


Procedure Names

Programs can contain procedure-names that are the same as data-names.

Parent topic: Procedure Division


REWRITE on LINE SEQUENTIAL Files

The REWRITE statement can be used on sequential files, providing the new record is the same length as the original.

Parent topic: Procedure Division


Size Allocation for Index Data Items

Two bytes are allocated to index data items, instead of the normal four, if you set the RM Compiler directive when you submit your source code to your COBOL system.

Four bytes are allocated to index data items if you set the DIALECT"RM" Compiler directive when you submit your source code to your COBOL system.

Parent topic: Procedure Division


ACCEPT (RM/COBOL)

The ACCEPT Statement

General Formats for Format 1

The following format of the ACCEPT statement is supported under DIALECT"RM":

Syntax Rules for Format 1

  1. Identifier-3, identifier-6 and identifier-7, if specified, must be integer identifiers. Literal-2, literal-5 and literal-6, if specified, must be integer literals.
  2. Literal-6 must be a single character.
  3. identifier-9 must be defined as PIC9(9) BINARY(4).

General Rules for Format 1

  1. In order for the ACCEPT statement to properly emulate RM/COBOL behavior, it will be necessary to use the ADISCF utility to enable the RM/COBOL configuration (RM2VCOB). Follow the tutorial Configuring Your Application for for more details.

  2. This format is treated as equivalent to Format 5 of the ACCEPT statement as described in the section The ACCEPT Statement, but multiple operands are allowed.
Parent topic: Procedure Division
Related information
The ACCEPT Statement


DISPLAY Statement (RM/COBOL )

The DISPLAY Statement

The following formats of the DISPLAY statement are supported under DIALECT"RM".

General Format for Format 1

General Rules for Format 1

  1. With either DIALECT"RM" or DIALECT"ACU" in effect, the Format 1 DISPLAY statement is processed using the ADIS screen I/O package unless the UPON phrase is specified. If neither dialect directive is set or the UPON phrase is used, the statement is handled by the standard Micro Focus DISPLAY method.

General Format for Format 3

Syntax Rules for Format 3

  1. Identifier-3, identifier-4 and identifier-5, if specified, must be integer identifiers. Literal-2, literal-3 and literal-5, if specified, must be integer literals.
  2. Literal-5 must be a single character.

General Rules for Format 3

  1. This format is treated as equivalent to Format 3 of the DISPLAY statement as described in the section The DISPLAY Statement.
Parent topic: Procedure Division
Related information
The DISPLAY Statement


The EXIT PROGRAM Statement

The EXIT PROGRAM statement closes all files that the subprogram being exited has open, if you set the RM Compiler directive when you submit your source code to your COBOL system.

However, if you specify the RM"ANSI" Compiler directive, the EXIT PROGRAM statement does not do this.

Parent topic: Procedure Division


The PERFORM Statement

Your COBOL system normally uses a stack for handling PERFORM statements, while the RM/COBOL system associates a return address with a specific procedure name. As a result, under the RM/COBOL system all end-points of PERFORM statements are active until they are used, whereas under your COBOL system only the end-point of the innermost current PERFORM statement is active at any one time.

However, if the PERFORM-TYPE"RM" Compiler directive is set, your COBOL system will handle PERFORM statements in the way RM/COBOL does.

Parent topic: Procedure Division


The STOP RUN Statement

General Format

The following format of the STOP RUN statement is supported:

Syntax Rules

  1. identifier must be a numeric integer data item.
  2. literal must be a numeric integer.

General Rules

  1. The value held in the numeric integer data item or the value of the literal is placed in a special register RETURN-CODE.
Parent topic: Procedure Division


Siemens BS2000 COBOL Syntax Support

When the DIALECT Compiler directive is set to BS2000 or BS2000-OFFLOAD, the syntax listed in this chapter is accepted by your COBOL system for compatibility with Siemens BS2000 COBOL. Many features found in Siemens BS2000 COBOL exist already in this COBOL implementation, marked as ANS85. Some of the compatibility syntax listed in this chapter is identical to standard COBOL syntax, but behaves differently if you set the DIALECT Compiler directive to BS2000 or BS2000-OFFLOAD when you submit your source code to your COBOL system. See the COBOL85 (BS2000) COBOL Compiler Reference Manual for a full description of the Siemens BS2000 COBOL syntax.

  • Concepts
  • Identification Division
  • Environment Division
  • Data Division
  • Procedure Division
  • Compiler Directing Statements
Parent topic: Additional Dialect Support


Concepts

  • Indicator Area
  • Areas A and B
  • Special Registers
  • Nonnumeric Literals
  • Floating-point Literals
  • Function-Identifier
  • Representation of Numeric Items
  • File Concepts
  • Subscripts
  • Object Views
Parent topic: Siemens BS2000 COBOL Syntax Support


Indicator Area

A comment line may appear anywhere in the compilation group.

Parent topic: Concepts


Areas A and B

The level number 01 may begin in either area A or area B.

Parent topic: Concepts


Special Registers

The special registers SORT-CORE-SIZE, SORT-FILE-SIZE, SORT-MODE-SIZE, SORT-RETURN and TALLY are supported as described in the section Special Registers.

The following additional behaviors are in effect when the DIALECT"BS2000" Compiler directive is set:

  • The BYTE-LENGTH special register is supported and generates a value representing the current number of bytes of storage used by the specified data name. The expression can be used wherever a numeric data item can be used except as a subscript or a reference modifier.
  • The LENGTH OF special register returns the number of characters of storage used by the specified data name. (LENGTH OF returns the number of bytes under the effect of DIALECT"MF".)
  • The RETURN-CODE special register has the description PIC S9(8) COMP-5 SYNC. (This comes under the control of the RTNCODE-TYPE Compiler directive: RTNCODE-TYPE"COMP5" is set by DIALECT"BS2000".)
Parent topic: Concepts
Related information
Special Registers


Nonnumeric Literals

Nonnumeric literals may be from 1 to 180 characters in length.

Parent topic: Concepts


Floating-point Literals

Floating-point literals are supported as described in the section Floating-point Numeric Literals.

Parent topic: Concepts
Related information
Floating-point Numeric Literals


Function-Identifier

A function-identifier that references an integer or numeric function can be used as the source of a MOVE statement, as well as in an arithmetic expression.

Parent topic: Concepts


Representation of Numeric Items

  • The BINARY, COMPUTATIONAL and COMPUTATIONAL-5 phrases
Parent topic: Concepts


The BINARY, COMPUTATIONAL and COMPUTATIONAL-5 phrases

Syntax Rules

  1. These phrases specify binary data items.
  2. The PICTURE clause of a binary data item must contain only 9s, the operational sign S, the assumed decimal point V, and one or more Ps (see the topic The PICTURE Clause).
  3. The data items are stored in a halfword, fullword, or doubleword, and are aligned only if the SYNCHRONIZED clause is specified.
  4. If a data item described with USAGE IS BINARY is used as a receiving data item, a check is made to determine whether the value to be transferred to this data item exceeds the maximum possible value indicated by the PICTURE character-string. If this is the case, the value is made to conform by truncation. If a receiving data item is described with USAGE IS COMPUTATIONAL or COMPUTATIONAL- 5, this check and any subsequent truncation which may be required is not performed.

General Rules

  1. The storage requirements for binary items vary depending on the number of decimal digits specified in the PICTURE clause, as follows:
    Decimal digits in the PICTURE clause | Bytes required in computer storage | Alignment
    1-4 5-9 10-18 | 2 4 8 | halfword fullword fullword
  2. The leftmost bit of a binary data item is the operational sign. The remaining bits represent the value.
Parent topic: Representation of Numeric Items
Related information
The PICTURE Clause


File Concepts

The line sequential file organization is supported as described in the section Line Sequential Input/Output. This support is consistent with the X/Open Portability Guide.

Parent topic: Concepts
Related information
Line Sequential Input/Output


Subscripts

A subscript may be an arithmetic expression that has the value of a positive integer.

As specified in the standard, the value of an index should correspond to a valid occurrence number of the associated table. This compiler also permits corresponding occurrence numbers for 0, negative numbers, and values beyond the maximum permissible occurrence number, but the binary value of the index must remain within the range that is representable in 4 bytes, i.e. -2 ** 31 to 2 ** 31 -1. In these cases, the index must be set to a valid occurrence number before it is used (e.g. with SET UP or SET DOWN), or relative indexing must be used to ensure that only valid table elements are addressed.

Parent topic: Concepts


Object Views

Object views are supported as described in the section Object-view

Parent topic: Concepts
Related information
Object-view


Identification Division

  • Identification Division Header
  • Identification Division Structure
  • The Class-ID Paragraph
  • The Factory Paragraph
  • The Interface-ID Paragraph
  • The Method-ID Paragraph (Siemens BS2000 COBOL)
  • The Object Paragraph
Parent topic: Siemens BS2000 COBOL Syntax Support


Identification Division Header

The following additional format of the Identification Division header is supported:

 ID DIVISION.
Parent topic: Identification Division


Identification Division Structure

The paragraphs of the Identification Division can be written in any order.

Parent topic: Identification Division


The Class-ID Paragraph

The Class-ID paragraph may be specified as documented in the topic The Class-ID Paragraph. Neither the AS phrase nor the USING phrase is permitted.

Parent topic: Identification Division
Related information
The Class-ID Paragraph


The Factory Paragraph

The Factory paragraph may be specified as documented in the topic The Factory Paragraph. The IMPLEMENTS clause is not permitted.

Parent topic: Identification Division
Related information
The Factory Paragraph


The Interface-ID Paragraph

The Interface-ID paragraph may be specified as documented in the topic The Interface-ID Paragraph. Neither the AS phrase nor the USING phrase is permitted.

Parent topic: Identification Division
Related information
The Interface-ID Paragraph


The Method-ID Paragraph (Siemens BS2000 COBOL)

The Method-ID paragraph may be specified as documented in the topic The Method-ID Paragraph. Neither the AS phrase nor the PROPERTY phrase is permitted.

Parent topic: Identification Division
Related information
The Method-ID Paragraph


The Object Paragraph

The Object paragraph may be specified as documented in the topic The Object Paragraph. The IMPLEMENTS clause is not permitted.

Parent topic: Identification Division
Related information
The Object Paragraph


Environment Division

  • The Special-Names Paragraph
  • The File Control Entry
  • The Repository Paragraph
Parent topic: Siemens BS2000 COBOL Syntax Support


The Special-Names Paragraph

ARGUMENT-NAME, ARGUMENT-VALUE, ENVIRONMENT-NAME and ENVIRONMENT-VALUE may be specified in the Special-Names paragraph for use in ACCEPT and DISPLAY statements. Their use is consistent with the X/Open Portability Guide and the Micro Focus implementation.

An implementor-name is a system-name and must be a name from the left column of the following table. The implementor-names and their meanings are:

Implementor-name | Meaning
COMPILER-INFO | used in ACCEPT statement
CONSOLE | System or main console or subconsole; used in ACCEPT and DISPLAY statements
CPU-TIME | used in ACCEPT statement
DATE-ISO4 | used in ACCEPT statement
JV_jobvariable-name | used in ACCEPT and DISPLAY statements
PRINTER | System logical printer; used in DISPLAY statement
PRINTER01 ... PRINTER99 | treated as PRINTER-1
PROCESS-INFO | used in ACCEPT statement
SYSIPT SYSOPT | treated as comment
TERMINAL | used in ACCEPT and DISPLAY statements; same as CONSOLE
TERMINAL-INFO | used in ACCEPT statement
TSW-0 ... TSW-31 | task switches, used in SET statement and in compares
USW-0 ... USW-31 | user switches, used in SET statement and in compares

The mnemonic-name can be the same as the implementor-name. For example:

 TERMINAL IS TERMINAL

JV_jobvariable-name, TSW-n, and USW-n only work when the BS/2000 add-on is present to provide the necessary run-time support.

Parent topic: Environment Division


The File Control Entry

For all file organizations, the data-name-1 phrase in the ASSIGN clause is supported as described in the topic File Control Entry.

For all file organizations, a second data-name may be specified in the FILE STATUS clause, but it is treated as commentary only.

Parent topic: Environment Division
Related information
The File Control Entry


The Repository Paragraph

The Repository paragraph may be specified as documented in the topic The Repository Paragraph. The program-specifier is not permitted.

Parent topic: Environment Division
Related information
The Repository Paragraph


Data Division

  • The File Description Entry
  • The Sort-Merge File Description Entry
  • The Working-Storage Section
  • The BASED Clause
  • The DYNAMIC Clause
  • The OCCURS Clause
  • The PICTURE Clause
  • The REDEFINES Clause
  • The SYNCHRONIZED Clause
  • The USAGE Clause
  • The VALUE Clause
Parent topic: Siemens BS2000 COBOL Syntax Support


The File Description Entry

The RECORDING MODE clause may be specified as documented in the topic The RECORDING MODE Clause. The S phrase is not permitted.

Data-name-1 may be specified in the LABEL RECORDS clause as documented in the topic The LABEL RECORDS Clause.

Parent topic: Data Division
Related information
The RECORDING MODE Clause
The LABEL RECORDS Clause


The Sort-Merge File Description Entry

The RECORDING MODE clause is permitted, however, there is no need for it since the compiler can determine the information from the associated record descriptions.

The LABEL RECORDS clause may be specified.

Parent topic: Data Division


The Working-Storage Section

The Working-Storage Section may be specified in method definitions. The data in these sections is static.

Parent topic: Data Division


The BASED Clause

The BASED clause identifies a record as being a simple template to which no storage space is allocated.

Format

BASED

Syntax Rules:

  1. Only specify the BASED clause on a level 01 or 77 item from the LINKAGE SECTION.
  2. The BASED and REDEFINES phrases are mutually exclusive.

General Rules:

The start address of this record is set to the predefined address NULL. An address is not assigned until it is explicitly set.

Parent topic: Data Division


The DYNAMIC Clause

General Format

The following clause is accepted in level-01 entries in the Working-Storage Section:

  IS DYNAMIC

General Rules

  1. This clause is treated as documentary.
Parent topic: Data Division


The OCCURS Clause

In an OCCURS clause with the DEPENDING phrase, the lower bound (integer-1) may be omitted.

Parent topic: Data Division


The PICTURE Clause

External floating-point data items are supported as described in the section The PICTURE Clause.

Parent topic: Data Division
Related information
The PICTURE Clause


The REDEFINES Clause

Data-name-2 may qualified, however, the qualification is ignored since the required placement of the REDEFINES clause determines the item that is redefined.

Parent topic: Data Division


The SYNCHRONIZED Clause

The SYNCHRONIZED clause may be specified on a group item. The clause applies to the items subordinate to that group.

The SYNCHRONIZED clause may be specified for a data item whose usage is index, in addition to the usages allowed by the standard.

Parent topic: Data Division


The USAGE Clause

The additional usages COMPUTATIONAL-1 (COMP-1), COMPUTATIONAL-2 (COMP-2) and COMPUTATIONAL-3 (COMP-3) are supported as described in the section The USAGE Clause.

The additional usage COMPUTATIONAL-5 (COMP-5) is described in the section Representation of Numeric Items.

The additional usage OBJECT REFERENCE is supported with all its optional phrases.

Parent topic: Data Division
Related information
The USAGE Clause
Representation of Numeric Items


The VALUE Clause

Format 1 - Additional Syntax Rules

The VALUE clause is prohibited for external floating-point data items.

Format 2

The WHEN SET TO FALSE phrase is supported, as described in the section The VALUE Clause.

Format 3

The VALUE clause may be used to initialize the elements of a table.

Format 4

Syntax Rules

Format 4

  1. Format 4 of the VALUE clause must be used only in the Working-Storage section.
  2. All numeric literals in a VALUE clause of an item must have a value which is within the range of values indicated by the associated PICTURE clause, and must not have a value which would require truncation of non-zero digits.
  3. Nonnumeric literals in a VALUE clause of an item must not exceed the size indicated by the associated PICTURE clause.
  4. If the VALUE clause is used in an entry at the group level, the literal must be a figurative constant or a nonnumeric literal, and the group area is initialized without consideration for the individual elementary or group items contained within this group. The VALUE clause must not be stated at the subordinate levels within this group.
  5. The VALUE clause must not be specified for a group item containing items subordinate to it with descriptions including JUSTIFIED or USAGE (other than USAGE IS DISPLAY).
  6. When format 4 is specified, the data description entry must contain an OCCURS clause or be subordinate to a data description entry that contains an OCCURS clause.
  7. Subscript-1 must be a numeric literal that is an integer. If all subscripts have the value 1, no subscripts need be specified; otherwise, all subscripts required to reference an individual element in a table must be specified.
  8. The number of table elements to be initialized is determined as follows:
    1. If integer-1 is not specified, it is the number of repetitions of literal-2.
    2. If integer-1 is specified, it is the number of repetitions of literal-2 times integer-1.

    The number of table elements to be initialized must not exceed the maximum number of occurrences in the table from the point of reference to the end of the table.

  9. If multiple format 4 VALUE clauses are specified in an entry, the TO END phrase may be specified only once.

General Rules

Format 4

  1. All formats of the VALUE clause can be used in one table.
  2. Within the same data description entry, if more than one VALUE clause references the same table element, the value defined by the last specified VALUE clause in the data description entry is assigned to the table element.
  3. A format 4 VALUE clause initializes a table element to the value of literal-2. The table element initialized is identified by subscript-1. Consecutive table elements are initialized, in turn, to the successive occurrences of the value of literal-2. Consecutive table elements are referenced by augmenting by 1 the subscript that represents the least inclusive dimension of the table. When any reference to a subscript, prior to augmenting it, is equal to the maximum number of occurrences specified by its corresponding OCCURS clause, that subscript is set to 1 and the subscript for the next most inclusive dimension of the table is augmented by 1.
  4. If the REPEATED phrase is specified, all occurrences of literal-2 are reused, in the order specified.

    If the TO END phrase is specified, this reuse occurs until the end of the table is reached.

    If the integer-1 TIMES phrase is specified, the occurrences of literal-2 are reused, in the order specified, integer-1 times.

    If the REPEATED phrase is not specified, the occurrences of literal-2 are used, in the order specified, only once.

  5. If a VALUE clause is specified in a data description entry of a data item which is associated with a variable-occurrence data item, the initialization of the data item behaves as if the value of the data item referenced by the DEPENDING ON phrase in the OCCURS clause specified for the variable-occurrence data item is set to the maximum number of occurrences as specified by that OCCURS clause. A data item is associated with a variable-occurrence data item in any of the following cases:
    1. It is a group data item which contains a variable-occurrence data item.
    2. It is a variable-occurrence data item.
    3. It is a data item that is subordinate to a variable-occurrence data item.
  6. The VALUE clause must not conflict with other clauses in the data description of the item or in the data description within the hierarchy of the item. The following rules apply:

    If the category of the item is numeric, all literals in the VALUE clause must be numeric. The literal is aligned in the data item according to the standard alignment rules.

    If the category of the item is alphabetic or alphanumeric, all literals in the VALUE clause must be nonnumeric literals. The literal is aligned in the data item as if the data item had been described as alphanumeric.

    Initialization is not affected by any BLANK WHEN ZERO or JUSTIFIED clause that was specified.

Parent topic: Data Division
Related information
The VALUE Clause


Procedure Division

  • Class Condition
  • Intrinsic Functions
  • The ACCEPT Statement
  • The CALL Statement
  • The CLOSE Statement
  • The DISPLAY Statement
  • The ENTRY Statement
  • The EVALUATE Statement
  • The EXIT PERFORM Statement
  • The GOBACK Statement
  • The INSPECT Statement
  • The INVOKE Statement
  • The MERGE Statement
  • The MOVE Statement
  • The OPEN Statement
  • The READ Statement
  • The REWRITE Statement
  • The SEARCH Statement
  • The SET Statement
  • The SORT Statement
  • The START Statement
  • The STRING Statement
  • The USE Statement
  • The WRITE Statement
Parent topic: Siemens BS2000 COBOL Syntax Support


Class Condition

The identifier in the class condition can be of usage COMPUTATIONAL-3, as well as the usages DISPLAY and PACKED-DECIMAL that are allowed by the standard.

Parent topic: Procedure Division


Intrinsic Functions

In addition to the intrinsic functions specified in the standard, the following intrinsic functions are supported: ADDR, BYTE-LENGTH, DATE-TO-YYYYMMDD, DAY-TO-YYYYDDD, and YEAR-TO-YYYY. The ADDR and BYTE-LENGTH functions are described below. The other intrinsic functions are described in the topic Intrinsic Functions.

  • The ADDR Function
  • The BYTE-LENGTH Function
Parent topic: Procedure Division
Related information
Intrinsic Functions
Arguments
Data Item Functions
Date Conversion Functions
Trigonometric Functions
Definitions of Functions


The ADDR Function

Description

The ADDR function returns an integer representing the address of argument-1. The type of this function is integer

General Format

FUNCTION ADDR (argument-1)

Arguments

  1. Argument-1 can be a literal or a data-item of any class or category.

Returned Values

  1. The returned value is an integer representing the address of argument-1 at run time.
Parent topic: Intrinsic Functions


The BYTE-LENGTH Function

Description:

The BYTE-LENGTH function returns an integer value that is the length in bytes of argument-1. The type of this function is integer.

General Format

FUNCTION BYTE-LENGTH (argument-1)

Arguments

  1. Argument-1 can be a nonnumeric literal or a data item of any class or category.
  2. If argument-1 or any data item subordinate to argument-1 is described with the DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by the data-name specified in the DEPENDING phrase are used at the time the BYTE-LENGTH function is evaluated.

Returned values

  1. If argument-1 is an alphanumeric literal or is an elementary data item of class other than national or is a group data item that does not contain a variable occurrence data item, the value returned is an integer equal to the length of argument-1 in alphanumeric character positions.
  2. If argument-1 is a group data item containing a variable occurrence data item, the returned value is an integer determined by evaluation of the data item specified in the DEPENDING phrase of the OCCURS clause for that variable occurrence data item. This evaluation is accomplished according to the rules in the OCCURS clause dealing with the data item as a sending data item. See the section The OCCURS Clause in Data Division - File and Data Description.
  3. The returned value includes implicit FILLER characters, if any.
Parent topic: Intrinsic Functions


ACCEPT (Siemens BS2000)

The ACCEPT Statement

Mnemonic-names associated with the implementor-names ARGUMENT-NUMBER, ARGUMENT-VALUE, ENVIRONMENT-NAME and ENVIRONMENT-VALUE are supported as described in the section The Special-Names Paragraph.

Mnemonic-name may be associated with one of the following implementor-names: COMPILER-INFO, CONSOLE, CPU-TIME, DATE-ISO4, job-variable-name (BS2000 job variable), PROCESS-INFO, SYSIPT, TERMINAL or TERMINAL-INFO.

Job-variable-names only work when the BS/2000 add-on is present to provide the necessary run-time support.

SYSIPT, TERMINAL, or CONSOLE specifies the system file from which data is to be read. SYSIPT refers to the system file of that name. TERMINAL refers to the system file SYSDTA (normally assigned to the data terminal). CONSOLE refers to the system console.

When a mnemonic-name is associated with a job-variable-name, it references the associated operating system job variable which is to be read in. If the job variable cannot be read in for some reason, the runtime system issues an error message, and the program is then either continued or aborted, as determined by a compiler directive. In the former case, /* is assumed as the value of identifier.

When mnemonic-name is associated with COMPILER-INFO, CPU-TIME, PROCESS-INFO, or TERMINAL-INFO, it specifies the information which is to be requested. COMPILER-INFO refers to information provided by the compiler. CPU-TIME, PROCESS-INFO, TERMINAL-INFO and DATE-ISO4 refer to information provided by the operating system.

CPU-TIME is moved in accordance with the rules of the MOVE statement from a field with the description PIC 9(6)V9(4).

Parent topic: Procedure Division
Related information
The Special-Names Paragraph


CALL Statement (Siemens BS2000 COBOL)

The CALL Statement

Identifiers in the USING phrase may be groups or elementary items and may have any level number except 88.

BY VALUE identifier may be specified in the USING phrase. BY CONTENT literal may be specified in the USING phrase. Additional details are specified in the section The CALL Statement.

Parent topic: Procedure Division
Related information
The CALL Statement


The CLOSE Statement

  • Record Sequential Files
  • Line Sequential Files
Parent topic: Procedure Division


Record Sequential Files

The REEL and UNIT phrases are treated as commentary.

Parent topic: The CLOSE Statement


Line Sequential Files

The only optional phrase permitted for a line sequential file is the WITH LOCK phrase.

Parent topic: The CLOSE Statement


The DISPLAY Statement

Mnemonic-names associated with the implementor-names ARGUMENT-NUMBER, ENVIRONMENT-NAME and ENVIRONMENT-VALUE are supported as described in the section The Special-Names Paragraph.

Mnemonic-name may be associated with one of the following implementor-names: CONSOLE, PRINTER, PRINTER01 - PRINTER99, SYSOPT, TERMINAL, job-variable-name (BS2000 job variable).

Job-variable-names only work when the BS/2000 add-on is present to provide the necessary run-time support.

A mnemonic-name associated with CONSOLE, SYSOPT or TERMINAL specifies that the data is to be written to the system operator console.

A mnemonic-name associated with PRINTER or PRINTER01 - PRINTER99 specifies that the data is to be written to the printer.

A mnemonic-name associated with a job-variable-name references a job variable which has a maximum record length of 256 characters. If the total number of characters in the sending operands exceeds the maximum record length, the record will be truncated to the maximum length.

Parent topic: Procedure Division
Related information
The Special-Names Paragraph


The ENTRY Statement

The ENTRY statement is supported as documented in the section The ENTRY Statement.

Parent topic: Procedure Division
Related information
The ENTRY Statement


The EVALUATE Statement

Partial expressions are supported in the WHEN and ALSO phrases of the EVALUATE statement as described in the section The EVALUATE Statement.

Parent topic: Procedure Division
Related information
The EVALUATE Statement


The EXIT PERFORM Statement

The EXIT PERFORM statement makes it possible to branch to the end of the PERFORM statement or to a repetition of the loop from an in-line PERFORM statement.

General Formats

 EXIT [TO TEST OF] PERFORM

Syntax Rules

  1. An EXIT [TO TEST OF] PERFORM statement can only be specified within an in-line PERFORM.
  2. An EXIT TO TEST OF PERFORM statement can only refer to format 2, 3, or 4 PERFORM statements (see the section The PERFORM Statement).

General Rules

  1. The associated in-line PERFORM statement is exited by the execution of an EXIT PERFORM.
  2. Depending on the format of the PERFORM statement, different branches are made as the result of EXIT TO TEST OF PERFORM:
    1. In a format 2 PERFORM, control passes to the test of "end of loop".
    2. In a format 3 PERFORM, control passes to the test of "UNTIL condition".
    3. When TEST AFTER is specified in format 4, control passes to the test of "UNTIL condition". If the condition is satisfied, the PERFORM statement is terminated. If the condition is not satisfied, augmentation is carried out.
    4. When TEST BEFORE is specified in format 4, control is passed to the increment counter. The test of "UNTIL condition" then follows.
Parent topic: Procedure Division
Related information
The PERFORM Statement


The GOBACK Statement

The GOBACK statement is supported as documented in the section The GOBACK Statement.

Parent topic: Procedure Division
Related information
The GOBACK Statement


The INSPECT Statement

Identifier-3 ... identifier-n may reference a group item, as well as the elementary items allowed by the standard.

Parent topic: Procedure Division


The INVOKE Statement

The INVOKE statement is supported as documented in the section The INVOKE Statement. The Micro Focus extensions are not permitted.

Parent topic: Procedure Division
Related information
The INVOKE Statement


The MERGE Statement

The optional word KEY in the ASCENDING or DESCENDING phrase may be replaced by the word KEY-YY. When KEY-YY is specified, the behavior of the MERGE statement is not changed.

Parent topic: Procedure Division


The MOVE Statement

Multiple receiving identifiers may be specified in a MOVE statement with the CORRESPONDING phrase.

Parent topic: Procedure Division


The OPEN Statement

For line sequential files, the only permissible open modes are INPUT and OUTPUT; and the REVERSED and NO REWIND phrases must not be specified.

Parent topic: Procedure Division


The READ Statement

  • Relative and Indexed Files
Parent topic: Procedure Division


Relative and Indexed Files

The NO LOCK phrase may be specified in both formats of the READ statement. The effect of the NO LOCK phrase is described in the section The READ Statement. The placement of the phrase differs from the placement in the MF dialect, here the NO LOCK phrase immediately follows the file-name.

In a format 1 READ statement in which the AT END phrase or the NOT AT END phrase is specified, the NEXT phrase is implied and may be omitted.

Parent topic: The READ Statement
Related information
The READ Statement


The REWRITE Statement

The REWRITE statement is not permitted for line sequential files.

Parent topic: Procedure Division


The SEARCH Statement

The key (data-name-1 or data-name-2) in a format 2 SEARCH statement (SEARCH ALL) may be specified on either the right hand side or the left hand side of the equality operator in the WHEN phrase. This is shown in the general format of the section The SEARCH Statement as an OSVS extension.

Parent topic: Procedure Division
Related information
The SEARCH Statement


The SET Statement

The FALSE phrase is supported in a format 2 SET statement, as specified in the section The SET Statement.

The value of an index-name after the execution of a format 5 or format 6 SET statement need not be a valid occurrence number in the corresponding table, but must be within the range of permissible values for the index as specified in the section Subscripts.

The format 8 SET statement (object references) is permitted.

Parent topic: Procedure Division
Related information
The SET Statement
Subscripts


The SORT Statement

  • Sorting of Tables
  • Sorting Two-digit Years with a Century Window
Parent topic: Procedure Division


Sorting of Tables

Format 2 of the SORT statement (table sort) is supported. Most of the details are given in the section The SORT Statement. Additional details are contained in this section.

General format

Syntax Rules

  1. For data-name-3, the same rules apply as for data-name-2.
  2. If the USING phrase is used, data-name-2 and data-name-3 must be described as alphanumeric data items.

General Rules

  1. Data-name-3, if specified, is the table to be sorted; otherwise, the table specified by data-name-2 is sorted.
  2. By specifying USING data-name-3, a second table is used for sort processing. In this case, the elements of the table specified by data-name-3 are transferred to the table specified by data-name-2 and then sorted in the table specified by data-name-2. The individual table elements are transferred in accordance with the rules for the MOVE statement:
    • If the "sending" element is shorter than the "receiving" element, it is padded with blanks;
    • if it is longer, it is truncated.
  3. Transfer of the data-name-3 table elements to the data-name-2 table ends with the last table element of data-name-3 or on reaching the number of table elements for data-name-2. This means that if the data-name-3 table contains more elements than the data-name-2 table, the excess elements are not transferred. If it contains fewer elements, the excess elements of the data-name-2 table are retained unchanged.
  4. Sort processing does not change the contents of the data-name-3 table.
Parent topic: The SORT Statement
Related information
The SORT Statement


Sorting Two-digit Years with a Century Window

In both formats 1 and 2 of the SORT statement, the optional word KEY in the ASCENDING or DESCENDING phrase may be replaced by the word KEY-YY. When KEY-YY is specified, the behavior of the SORT statement is not changed.

Parent topic: The SORT Statement


The START Statement

  • Relative and Indexed Files
Parent topic: Procedure Division


Relative and Indexed Files

The NO LOCK phrase may be specified immediatly after START file-name, but is treated as a comment.

The relational operators LESS, LESS OR EQUAL, NOT GREATER and their equivalents are supported as specified in the section The START Statement.

Parent topic: The START Statement
Related information
The START Statement


The STRING Statement

As in the Micro Focus dialect, the following extension is supported:

The DELIMITED phrase may be omitted only immediately preceding the INTO phrase. If it is omitted, DELIMITED BY SIZE is implied.

Parent topic: Procedure Division


The USE Statement

A PERFORM statement within a declarative procedure (USE statement) may reference a nondeclarative procedure, as well as a declarative procedure.

Formats 2 and 3 are supported as specified in the section The USE Statement.

Parent topic: Procedure Division
Related information
The USE Statement


The WRITE Statement

  • Sequential Files
Parent topic: Procedure Division


Sequential Files

The identifier in the ADVANCING phrase of the WRITE statement may be an elementary one-character nonnumeric item, as well as an elementary integer data item. If a nonnumeric item is specified, the ADVANCING phrase is treated as a comment.

Parent topic: The WRITE Statement


Compiler Directing Statements

  • The COPY Statement
Parent topic: Siemens BS2000 COBOL Syntax Support


The COPY Statement

The SUPPRESS phrase of the COPY statement is supported as described in the section The COPY Statement.

COPY statements may be nested as described in the section The COPY Statement.

Parent topic: Compiler Directing Statements
Related information
The COPY Statement


VS COBOL II Compatibility

The VS COBOL II compatibility features available in this COBOL system are controlled by the two Compiler directives:

FLAG "VSC2" VSC2 "integer"

where integer provides compatibility as follows:

VSC2 (1) VS COBOL II release 1.x VSC2 (2) VS COBOL II release 2 VSC2 (3) VS COBOL II release 3.x VSC2 (4) VS COBOL II release 4.x

Most differences are reflected as flagging differences when the FLAG "VSC2" Compiler directive is specified. COBOL will not report any differences in the four levels of support. Indication is always given in the form of a flag.

Element | VSC2(1) | VSC2(2) | VSC2(3) | VSC2(4)
ADD..TO..GIVING | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
ALPHABET alphabetic class test | Keyword is prohibited in SPECIAL-NAMES | Keyword is prohibited in SPECIAL-NAMES | Keyword is required in SPECIAL-NAMES | Keyword is required in SPECIAL-NAMES
Alpha-numeric literal 160 chars. | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
BINARY usage | Rejected | Rejected | Supported | Supported
CALL BY CONTENT | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
CALL ON EXCEPTION | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Class Name | User defined class names are rejected Only upper case accepted | User defined class names are rejected Only upper case is accepted | Additional user class names can be defined in the SPECIAL-NAMES paragraph Both upper and lower case are accepted | Additional user class names can be defined in the SPECIAL-NAMES paragraph Both upper and lower case are accepted
COMMON | Rejected | Rejected | Supported | Supported
Data - name following level number allowed in margin A | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
DAY - OF - WEEK | Rejected | Rejected | Supported | Supported
DISPLAY WITH NO ADVANCING | Flagged as ANSI'85 extension | Flagged as ANSI'85 extension | Supported | Supported
END PROGRAM | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
EVALUATE omitted ALSO | Supported | Flagged as MF extension | Flagged as MF extension | Flagged as MF extension
EXIT PROGRAM not alone in paragraph | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
EXTERNAL | Rejected | Rejected | Supported | Supported
File Status Code | ANSI 74 codes | ANSI 74 codes | ANSI'85 codes | ANSI'85 codes
GLOBAL clause | Rejected | Rejected | Supported | Supported
OCCURS nest depth seven | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
OPEN EXTEND for relative and indexed organizations | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Optional FILLER or data name | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
INITIAL program-id | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
INITIALIZE Replacing DBCS | Rejected | Rejected | Supported | Supported
INSPECT CONVERTING | Rejected | Rejected | Supported | Supported
LESS OR EQUAL, GREATER OR EQUAL, <=, >= | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Lower case letters | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
MERGE GIVING Multiple files | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
NOT scope delimiter | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
OPTIONAL RELATIVE files | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
PACKED - DECIMAL | Rejected | Rejected | Supported | Supported
PADDING CHARACTER | Rejected | Rejected | Supported | Supported
PIC continuation | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Program-name can be the same as a user-defined word | Rejected | Rejected | Rejected | Rejected
RECORD DELIMITER | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
RECORD IS VARYING | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Reference modification | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
REPLACE | Rejected | Rejected | Supported | Supported
SET TO ON/OFF | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
SIGN nested | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
SORT DUPLICATES phrase | Rejected if ORDER used | Rejected if ORDER used | Supported | Supported
STANDARD -2 | Rejected | Rejected | Supported | Supported
Symbolic chars. | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
VALUE with OCCURS | Flagged as ANSI'85 | Flagged as ANSI'85 | Supported | Supported
Parent topic: Additional Dialect Support


Part 4: Appendices

  • Character Sets and Collating Sequences
  • ANSI File Status Summary
  • Reserved Words
  • JSON-CODE Exception Codes
  • JSON-STATUS Non-Exception Codes
  • XML-CODE Exception Codes
  • Glossary
    The terms in this glossary are defined in accordance with their meaning as used in this document. These definitions are, in most instances, brief and do not include detailed syntactic rules, or dialect bubbles. Therefore, parts of the information may or may not be relevant based on the dialect selected.
Parent topic: COBOL Language Reference


Character Sets and Collating Sequences

The Character Set Encoding and Collating Sequence table, below, lists the ASCII and EBCDIC character sets and collating sequences, and show, the hexadecimal equivalent of the characters. For each ASCII and EBCDIC character, a further column contains an X if the character is not available as part of the recognized COBOL character set.

See your COBOL system documentation for details of the ALPHASTART and SYMBSTART Compiler directives, which set the number from which the compiler counts positions in the collating sequence.

The EBCDIC column shows the IBM standard U.S. bit pattern assignments. Some characters have a different bit pattern in different languages, and these are boxed within the table.

Table 1. Character Set Encoding and Collating Sequence
 | ASCII |  | EBCDIC
Hex | Character | COBOL | Character | COBOL
00 | NUL | X | NUL | X
01 | SOH | X | SOH | X
02 | STX | X | STX | X
03 | ETX | X | ETX | X
04 | EOT | X | SEL | X
05 | ENQ | X | HT | X
06 | ACK | X | RNL | X
07 | BEL | X | DEL | X
08 | BS | X | GE | X
09 | HT | X | SPS | X
0A | LF | X | RPT | X
0B | VT | X | VT | X
0C | FF | X | FF | X
0D | CR | X | CR | X
0E | SO | X | SO | X
0F | SI | X | SI | X
10 | DLE | X | DLE | X
11 | DCI | X | DC1 | X
12 | DC2 | X | DC2 | X
13 | DC3 | X | DC3 | X
14 | DC4 | X | RES/ENP | X
15 | NAK | X | NL | X
16 | SYN | X | BS | X
17 | ETB | X | POC | X
18 | CAN | X | CAN | X
19 | EM | X | EM | X
1A | SUB | X | UBS | X
1B | ESC | X | CU1 | X
1C | FS | X | IFS | X
1D | GS | X | IGS | X
1E | RS | X | IRS | X
1F | US | X | ITB/IUS | X
20 | SPACE |  | DS | X
21 | ! | X | SOS | X
22 | " |  | FS | X
23 | # | X | WUS | X
24 | $ |  | BYP/INP | X
25 | % | X | LF | X
26 | & |  | ETB | X
27 | ' |  | ESC | X
28 | ( |  | SA | X
29 | ) |  | SFE | X
2A | * |  | SM/SW | X
2B | + |  | CSP | X
2C | , |  | MFA | X
2D | – |  | ENQ | X
2E | . |  | ACK | X
2F | / |  | BEL | X
30 | 0 |  |  | X
31 | 1 |  |  | X
32 | 2 |  | SYN | X
33 | 3 |  | IR | X
34 | 4 |  | PP | X
35 | 5 |  | TRN | X
36 | 6 |  | NBS | X
37 | 7 |  | EOT | X
38 | 8 |  | SBS | X
39 | 9 |  | IT | X
3A | : |  | RFF | X
3B | ; |  | CU3 | X
3C | < |  | DC4 | X
3D | = |  | NAK | X
3E | > |  |  | X
3F | ? | X | SUB | X
40 | @ | X | SP | X
41 | A |  | RSP | X
42 | B |  |  | X
43 | C |  |  | X
44 | D |  |  | X
45 | E |  |  | X
46 | F |  |  | X
47 | G |  |  | X
48 | H |  |  | X
49 | I |  |  | X
4A | J |  | c (cent) | X
4B | K |  | . | X
4C | L |  | < | X
4D | M |  | ( | X
4E | N |  | + | X
4F | O |  | | | X
50 | P |  | & |
51 | Q |  |  | X
52 | R |  |  | X
53 | S |  |  | X
54 | T |  |  | X
55 | U |  |  | X
56 | V |  |  | X
57 | W |  |  | X
58 | X |  |  | X
59 | Y |  |  | X
5A | Z |  | ! | X
5B |  | X | $ |
5C |  | X | * |
5D |  | X | ) |
5E |  | X | ; |
5F | _ |  | ¬ | X
60 |  | X | – |
61 | a |  | / |
62 | b |  |  | X
63 | c |  |  | X
64 | d |  |  | X
65 | e |  |  | X
66 | f |  |  | X
67 | g |  |  | X
68 | h |  |  | X
69 | i |  |  | X
6A | j |  | | | X
6B | k |  | , |
6C | l |  | % | X
6D | m |  | _ |
6E | n |  | > |
6F | o |  | ? | X
70 | p |  | . | X
71 | q |  |  | X
72 | r |  |  | X
73 | s |  |  | X
74 | t |  |  | X
75 | u |  |  | X
76 | v |  |  | X
77 | w |  |  | X
78 | x |  |  | X
79 | y |  | ` | X
7A | z |  | : |
7B |  | X | # | X
7C |  | X | @ | X
7D |  | X | ' |
7E |  | X | = |
7F | DEL | X | " |
80 |  |  |  | X
81 |  |  | a |
82 |  |  | b |
83 |  |  | c |
84 |  |  | d |
85 |  |  | e |
86 |  |  | f |
87 |  |  | g |
88 |  |  | h |
89 |  |  | i |
8A |  |  |  | X
8B |  |  |  | X
8C |  |  |  | X
8D |  |  |  | X
8E |  |  |  | X
8F |  |  |  | X
90 |  |  |  | X
91 |  |  | j |
92 |  |  | k |
93 |  |  | l |
94 |  |  | m |
95 |  |  | n |
96 |  |  | o |
97 |  |  | p |
98 |  |  | q |
99 |  |  | r |
9A |  |  |  | X
9B |  |  |  | X
9C |  |  |  | X
9D |  |  |  | X
9E |  |  |  | X
9F |  |  |  | X
A0 |  |  |  | X
A1 |  |  | ~ | X
A2 |  |  | s |
A3 |  |  | t |
A4 |  |  | u |
A5 |  |  | v |
A6 |  |  | w |
A7 |  |  | x |
A8 |  |  | y |
A9 |  |  | z |
AA |  |  |  | X
AB |  |  |  | X
AC |  |  |  | X
AD |  |  |  | X
AE |  |  |  | X
AF |  |  |  | X
B0 |  |  |  | X
B1 |  |  |  | X
B2 |  |  |  | X
B3 |  |  |  | X
B4 |  |  |  | X
B5 |  |  |  | X
B6 |  |  |  | X
B7 |  |  |  | X
B8 |  |  |  | X
B9 |  |  |  | X
BA |  |  |  | X
BB |  |  |  | X
BC |  |  |  | X
BD |  |  |  | X
BE |  |  |  | X
BF |  |  |  | X
C0 |  |  | ( | X
C1 |  |  | A |
C2 |  |  | B |
C3 |  |  | C |
C4 |  |  | D |
C5 |  |  | E |
C6 |  |  | F |
C7 |  |  | G |
C8 |  |  | H |
C9 |  |  | I |
CA |  |  | SHY | X
CB |  |  |  | X
CC |  |  |  | X
CD |  |  |  | X
CE |  |  |  | X
CF |  |  |  | X
D0 |  |  | ) | X
D1 |  |  | J |
D2 |  |  | K |
D3 |  |  | L |
D4 |  |  | M |
D5 |  |  | N |
D6 |  |  | O |
D7 |  |  | P |
D8 |  |  | Q |
D9 |  |  | R |
DA |  |  |  | X
DB |  |  |  | X
DC |  |  |  | X
DD |  |  |  | X
DE |  |  |  | X
DF |  |  |  | X
E0 |  |  | \ | X
E1 |  |  | NSP | X
E2 |  |  | S |
E3 |  |  | T |
E4 |  |  | U |
E5 |  |  | V |
E6 |  |  | W |
E7 |  |  | X |
E8 |  |  | Y |
E9 |  |  | Z |
EA |  |  |  | X
EB |  |  |  | X
EC |  |  |  | X
ED |  |  |  | X
EE |  |  |  | X
EF |  |  |  | X
F0 |  |  | 0 |
F1 |  |  | 1 |
F2 |  |  | 2 |
F3 |  |  | 3 |
F4 |  |  | 4 |
F5 |  |  | 5 |
F6 |  |  | 6 |
F7 |  |  | 7 |
F8 |  |  | 8 |
F9 |  |  | 9 |
FA |  |  | | | X
FB |  |  |  | X
FC |  |  |  | X
FD |  |  |  | X
FE |  |  |  | X
FF |  |  | E0 | X
Parent topic: Part 4: Appendices


ANSI File Status Summary

This provides a summary of the ANSI file status codes. See the topic The File Control Entry, the topic I-O Status and your COBOL system documentation for more details.

  • ANSI'74 File Status Codes
  • ANSI'85 File Status Codes
Parent topic: Part 4: Appendices
Related information
The File Control Entry
I-O Status


ANSI'74 File Status Codes

The ANSI'74 file status codes are as follows:

Status key 1 | Status key 2 | Description
0 | 0 | Successful completion
2 Indexed files only. One of two possibilities:
  1. For a READ statement, the key value for the current key is equal to the value of that same key in the next record within the current key of reference.
  2. 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.
1 | 0 | There is no next logical record. You have reached the end of the file.
2 | 1 | Sequentially accessed files only. Indicates a sequence error. The ascending key requirement 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 the execution of the next REWRITE statement for that file.
2 | Relative and indexed files only. Indicates a duplicate key value. An attempt has been made to write or rewrite a record that would create a duplicate key in a relative or indexed file.
3 | 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.
3 | 0 | There was either a boundary violation for a sequential file or an I/O error, such as a data check parity error, or a transmission error.
4 | 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.
9 | Extended file status code
Parent topic: ANSI File Status Summary


ANSI'85 File Status Codes

ANSI'85 file status codes include all ANSI'74 status codes together with the following status codes:

Status key 1 | Status key 2 | Description
0 | 4 | The length of the record being processed does not conform to the record length specified in the fixed file attributes for that file.
5 | The referenced optional file is not present at the time the OPEN statement is executed.
7 | Sequential files only. For a CLOSE statement with the REEL/UNIT phrase the referenced file is a non-reel/unit medium.
1 | 4 | Relative files only. The number of significant digits in the relative record number is larger than the number of significant digits in the relative key data item described for that file.
2 | 2 | Indexed and relative files only. Indicates a duplicate key condition. An 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 for a file that does not allow duplicates.
3 | The conditions listed under ANSI'74 code "23". In addition, a START or READ statement has been attempted on an optional input file that is not present.
4 Relative and indexed files only. Indicates a boundary violation arising from one of the following conditions:
  1. An atttempt has been made to write beyond the externally defined boundaries of a file.
  2. A sequential WRITE statement has been attempted for a relative file, but the number of significant digits in the relative record number was larger than the size of the relative key data item described for the file.
3 | 5 | An OPEN statement with the I-O, INPUT, or EXTEND phrases has been attempted on a non-OPTIONAL file that is not present.
7 | An OPEN statement has been attempted on a file which does not support the open mode specified in the OPEN statement.
8 | An OPEN statement has been attempted on a file previously closed with a lock.
9 | A conflict has been detected between the fixed file attributes specified for that file in the program.
4 | 1 | An OPEN has been attempted on a file already opened.
2 | A CLOSE has been attempted on a file already closed.
3 | Sequentially accessed files only. The last I/O statement executed for the file, prior to the execution of a DELETE or REWRITE statement, was not a READ statement.
4 | A boundary violation exists.
6 | A sequential READ statement has been attempted on a file open in the INPUT or I-O mode but no valid next record has been established.
7 | A READ or START statement has been attempted on a file not opened INPUT or I-O.
8 | A WRITE statement has been attempted: on a file not open in the OUTPUT, I-O or EXTEND mode; or on a file open in the I-O and sequential access modes.
9 | A DELETE or REWRITE statement has been attempted on a file that is not opened I-O.
Parent topic: ANSI File Status Summary


Reserved Words

This appendix details all of the words which are reserved words in the COBOL language.

  • Reserved Words Table
  • Context-sensitive Words Table
Parent topic: Part 4: Appendices


Reserved Words Table

The following table indicates which reserved words are enabled when a particular dialect is in use, as specified by the use of the appropriate Compiler directive.

If you use any of these words as identifiers in your COBOL sources, you have the following choices:

Change the source

Set an appropriate Micro Focus reserved word level using the MF or MFLEVEL Compiler directive

Remove the word explicitly (as a reserved word) by using the REMOVE Compiler directive, for example REMOVE(ENCODING)

#

3-D

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

A

ABSENT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ABSTRACT

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACCEPT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ACCESS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ACQUIRE

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

ACTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ACTIVE-CLASS

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

ACU

ACTIVE-X

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ACTUAL

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

ADD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ADDRESS

MF3

...

...

I2

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ADDRESS-ARRAY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ADDRESS-OFFSET

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ADJUSTABLE-COLUMNS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ADVANCING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AFP-5A

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

AFTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ALIGNED

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ALIGNMENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ALL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ALLOCATE

MF19

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

ALLOW

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ALLOWING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ALPHABET

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ALPHABETIC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ALPHABETIC-LOWER

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ALPHABETIC-UPPER

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ALPHANUMERIC

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ALPHANUMERIC-EDITED

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ALSO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ALTER

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ALTERNATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AND

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ANY

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

APPLY

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

ACU

ARE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AREA

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AREAS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ARITHMETIC

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

AS

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

ACU

ASCENDING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ASSEMBLY-ATTRIBUTES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ASSIGN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ATTACH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ATTRIBUTE

MF18

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

MGD

ACU

ATTRIBUTES

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

AUTHOR

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

AUTO

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

AUTO-DECIMAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

AUTO-HYPHEN-SKIP

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

AUTO-MINIMIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

AUTO-RESIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

AUTO-SKIP

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

AUTO-SPIN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

AUTOMATIC

MF1

...

...

I2

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

AUTOTERMINATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

AX-EVENT-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

B

B-AND

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-EXOR

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-LEFT

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-NOT

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-OR

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-RIGHT

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

B-XOR

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BACKGROUND-COLOR

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

BACKGROUND-COLOUR

MF3

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BACKGROUND-HIGH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BACKGROUND-LOW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BACKGROUND-STANDARD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BACKWARD

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BASED

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BASIS

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

BEEP

MF3

...

...

...

...

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

ACU

BEFORE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BEGINNING

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

BELL

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

BINARY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BINARY

MF7

...

85

I2

...

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

RM

...

...

BS

OS390

ENT

...

...

BINARY-CHAR

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BINARY-DOUBLE

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BINARY-LONG

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BINARY-SHORT

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BIND

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BIT

MF14

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BITMAP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-END

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-HANDLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-NUMBER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-RAW-HEIGHT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-RAW-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-SCALE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-START

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-TIMER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-TRAILING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BITMAP-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BLANK

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BLINK

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

ACU

BLINKING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BLOB

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BLOB-FILE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BLOB-LOCATOR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BLOCK

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BOLD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BOOLEAN

MF14

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BOTTOM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BOX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BOXED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BROWSING

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BUSY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BUTTONS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

BY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

BYTE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

C

C01

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C02

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C03

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C04

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C05

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C06

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C07

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C08

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C09

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C10

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C11

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

C12

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

CALENDAR-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CALL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CALLED

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CANCEL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CANCEL-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CATCH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CBL

...

...

...

...

...

...

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

CBL-CTR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

CCOL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CELL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CELL-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CELL-DATA

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CELL-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CELL-PROTECTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CELLS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CENTER

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CENTERED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CENTERED-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CENTURY-DATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CENTURY-DAY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CHAIN

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

CHAINING

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

CHANGED

MF3

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

CHAR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CHAR-VARYING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CHARACTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CHARACTERS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CHART

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CHECK-BOX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CHECKING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

CLASS

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

CLASS-ATTRIBUTES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CLASS-CONTROL

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CLASS-ID

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

CLASS-OBJECT

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CLEAR-SELECTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CLINE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CLINES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CLOB

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CLOB-FILE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CLOB-LOCATOR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CLOCK-UNITS

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CLOSE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COBOL

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CODE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CODE-SET

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COERCION

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

COL

MF3

...

...

I2

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

COLLATING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLORS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLOUR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLOURS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLS

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

COLUMN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COLUMN-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLUMN-DIVIDERS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLUMN-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLUMN-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLUMN-PROTECTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COLUMNS

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

COM-REG

...

...

...

...

...

...

...

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

COMBO-BOX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COMMA

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COMMIT

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

COMMITMENT

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

COMMON

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

COMMUNICATION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COMP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COMP-0

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

COMP-1

MF7

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

...

...

BS

OS390

ENT

...

...

COMP-2

MF7

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

COMP-3

MF1

...

...

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

...

BS

OS390

ENT

...

...

COMP-4

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

...

...

...

...

...

COMP-5

MF3

...

...

...

XO(1,2)

...

...

...

...

...

...

...

...

...

BS

OS390

ENT

...

...

COMP-6

MF10

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

COMP-X

MF2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

COMPRESSION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

COMPUTATIONAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COMPUTATIONAL-0

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

COMPUTATIONAL-1

MF7

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

...

...

BS

OS390

ENT

...

...

COMPUTATIONAL-2

MF7

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

COMPUTATIONAL-3

MF1

...

...

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

...

BS

OS390

ENT

...

...

COMPUTATIONAL-4

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

...

OS390

ENT

...

...

COMPUTATIONAL-5

MF3

...

...

...

XO(1,2)

...

...

...

...

...

...

...

...

...

BS

OS390

ENT

...

...

COMPUTATIONAL-6

MF10

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

COMPUTATIONAL-X

MF2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

COMPUTE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CONDITION-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CONFIGURATION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CONSOLE

MF1

...

...

...

...

...

OS

DVS

...

...

...

...

MS(2)

...

...

...

...

...

...

CONSTANT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CONSTRAIN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CONSTRAINTS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CONTAINS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CONTENT

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

CONTINUE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

CONTROL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CONTROL-AREA

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

CONTROLS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CONTROLS-UNCROPPED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CONVERSION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CONVERT

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

CONVERTING

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

COPY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COPY-SELECTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CORE-INDEX

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

CORR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CORRESPONDING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

COUNT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CREATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CREATING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

CRT

MF1

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CRT-UNDER

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CSIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CSP

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

BS

...

...

...

...

CURRENCY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

CURRENT-DATE

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

CURSOR

MF1

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CURSOR-COL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CURSOR-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CURSOR-FRAME-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CURSOR-ROW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CURSOR-X

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CURSOR-Y

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CUSTOM-ATTRIBUTE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

CUSTOM-PRINT-TEMPLATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

CYCLE

MF7

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

CYL-INDEX

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

CYL-OVERFLOW

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

D

DASHED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DATA

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DATA-COLUMNS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DATA-POINTER

MF15

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

DATA-TYPES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DATABASE-KEY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

DATABASE-KEY-LONG

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

DATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DATE-AND-TIME

MF17

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

DATE-COMPILED

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DATE-ENTRY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DATE-RECORD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DATE-WRITTEN

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DAY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DAY-AND-TIME

MF17

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

DAY-OF-WEEK

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

DBCLOB

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DBCLOB-FILE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DBCLOB-LOCATOR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DBCS

MF7

...

...

...

...

SAA(1,2)

...

...

VS( 3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

DE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

DEBUG-CONTENTS

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-ITEM

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-LINE

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-NAME

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-SUB-1

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-SUB-2

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUG-SUB-3

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEBUGGING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DECIMAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

DECIMAL-POINT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DECLARATIVES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DECLARE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

DEFAULT

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

DEFAULT-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DEFAULT-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DEFINITION

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

DELEGATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

DELEGATE-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

DELETE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DELIMITED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DELIMITER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DEPENDING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DESCENDING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DESTINATION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DESTROY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DETAIL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DICTIONARY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

DISABLE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DISC

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

DISJOINING

MF13

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

DISK

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

DISP

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

DISPLAY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DISPLAY-1

MF7

...

...

...

...

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

DISPLAY-COLUMNS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DISPLAY-FORMAT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DISPLAY-ST

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

DIVIDE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DIVIDER-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DIVIDERS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DIVISION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DOT-DASH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DOTTED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DOWN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DRAG-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DRAW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DROP

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

DROP-DOWN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DROP-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

DUPLICATES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

DYNAMIC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

E

EBCDIC

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

ECHO

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

EGCS

...

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

EGI

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EJECT

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

BS

OS390

ENT

...

...

ELEMENT

MF18

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

ELEMENTARY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ELSE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EMI

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EMPTY-CHECK

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

ENABLE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ENABLED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ENCODING

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

END

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

END-ACCEPT

MF4

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

END-ADD

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-CALL

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-CHAIN

MF5

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

END-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

END-COMPUTE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-DELEGATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

END-DELETE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-DISPLAY

MF7

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

END-DIVIDE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-EVALUATE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-IF

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-INVOKE

MF11

...

...

...

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-JSON

MF19

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

END-MODIFY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

END-MOVE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

END-MULTIPLY

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-OF-PAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

END-PERFORM

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-READ

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-RECEIVE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-RETURN

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-REWRITE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-SEARCH

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-START

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-STRING

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-SUBTRACT

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-SYNC

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

END-TRY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

END-UNSTRING

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-WAIT

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

END-WRITE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

END-XML

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

ENDING

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ENGRAVED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ENSURE-VISIBLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ENTER

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ENTRY

MF5

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ENTRY-FIELD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ENTRY-REASON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ENUM

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ENUM-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ENVIRONMENT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EOL

MF7

...

...

I2

XO(1,2)

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

EOP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EOS

MF7

...

...

I2

XO(1,2)

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

EQUAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EQUALS

MF7

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ERASE

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

...

ERROR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ESCAPE

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

ESCAPE-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ESI

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EVALUATE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

EVENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

ACU

EVENT-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

EVENT-POINTER

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EVERY

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EXAMINE

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

EXCEEDS

MF7

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXCEPTION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EXCEPTION-OBJECT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXCEPTION-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

EXCESS-3

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXCLUDE-EVENT-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

EXCLUSIVE

MF1

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

EXEC

MF2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXECUTE

MF2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXHIBIT

MF3

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

MS(2)

...

...

...

...

...

...

EXIT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EXPAND

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

EXPANDS

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXTEND

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

EXTENDED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

EXTENDED-SEARCH

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

EXTENSION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

EXTERNAL

MF2

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

EXTERNAL-FORM

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

EXTERNALLY-DESCRIBED-KEY

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

F

FACTORY

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

FALSE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

FD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FH--FCD

MF5

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FH--KEYDEF

MF5

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FILE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FILE-CONTROL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FILE-ID

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

FILE-LIMIT

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

FILE-LIMITS

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

BS

...

...

...

...

FILE-NAME

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FILE-POS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FILL-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FILL-COLOR2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FILL-PERCENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FILLER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FINAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FINALLY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

FINISH-REASON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FIRST

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FIXED

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FIXED-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FIXED-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FLAT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FLAT-BUTTONS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FLOAT-EXTENDED

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FLOAT-LONG

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FLOAT-SHORT

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FLOATING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FOOTING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FOR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FOREGROUND-COLOR

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

ACU

FOREGROUND-COLOUR

MF3

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FOREVER

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FORMAT

...

...

...

I2

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

FRAME

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FRAMED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FREE

MF19

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

FROM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

FULL

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

FULL-HEIGHT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

FUNCTION

MF7

...

85

I2

XO(1,2)

SAA(2)

...

...

...

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

FUNCTION-ID

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

FUNCTION-POINTER

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

G

GENERATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

GET

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

GETTER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

GIVING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

GLOBAL

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

GO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

GO-BACK

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GO-FORWARD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GO-HOME

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GO-SEARCH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GOBACK

MF5

...

...

I2

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

GRAPHICAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GREATER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

GRID

MF4

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

GRIP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

GROUP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

GROUP-USAGE

MF14

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

GROUP-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

H

HANDLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HAS-CHILDREN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEADING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

HEADING-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEADING-DIVIDER-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEADING-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEAVY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEIGHT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HEIGHT-IN-CELLS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HELP-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HIDDEN-DATA

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HIGH

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

HIGH-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HIGH-VALUE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

HIGH-VALUES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

HIGHLIGHT

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

HORIZONTAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HOT-TRACK

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HSCROLL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

HSCROLL-POS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

I

I-O

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

I-O-CONTROL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ICON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ID

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

IDENTIFICATION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

IDENTIFIED

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

IF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

IGNORE

MF8

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

IGNORING

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

IMPLEMENTS

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

IN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INDEPENDENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

INDEX

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INDEXED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INDEXER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

INDEXER-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

INDIC

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

INDICATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INDICATOR

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

INDICATORS

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

INHERITING

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

INHERITS

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

INITIAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INITIALIZE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

INITIALIZED

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

INITIATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INPUT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INPUT-OUTPUT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INQUIRE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

INSERT

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

INSERT-ROWS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

INSERTION-INDEX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

INSPECT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INSTALLATION

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INSTANCE

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

INTERFACE

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

INTERFACE-ID

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

INTERNAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

INTO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INTRINSIC

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

INVALID

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

INVOKE

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

INVOKED

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

IS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ITEM

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-BOLD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-TO-ADD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-TO-DELETE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-TO-EMPTY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITEM-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ITERATOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

ITERATOR-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

J

JAPANESE

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

JOINED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

JOINING

MF13

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

JSON

MF19

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

JSON-CODE

MF19

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

JSON-STATUS

MF20

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

JUST

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

JUSTIFIED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

K

KANJI

MF8

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

KEPT

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

KEY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

KEY-YY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

KEYBOARD

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

L

LABEL

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LABEL-OFFSET

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LARGE-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LAST

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LAST-ROW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LAYOUT-DATA

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LAYOUT-MANAGER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LC_ALL

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_COLLATE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_CTYPE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_CURRENCY

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_MESSAGES

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_MONETARY

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_NUMERIC

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LC_TIME

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LEADING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LEADING-SHIFT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LEAVE

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

LEFT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LEFT-JUSTIFY

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

LEFT-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LEFTLINE

MF4

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LENGTH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LENGTH-CHECK

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

LESS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LIMIT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LIMITS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LIN

...

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

LINAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LINAGE-COUNTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LINE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LINE-COUNTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LINES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LINES-AT-ROOT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LINK

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LINKAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

LIST-BOX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LM-RESIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LOCAL-STORAGE

MF5

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

LOCALE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LOCK

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LOCKING

...

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

LONG-DATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LONG-VARBINARY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LONG-VARCHAR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LOW

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

LOW-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LOW-VALUE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LOW-VALUES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

LOWER

MF8

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

LOWERED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

LOWLIGHT

MF7

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

...

M

MANUAL

MF1

...

...

I2

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

MASS-UPDATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MASTER-INDEX

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

MAX-HEIGHT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-LINES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-PROGRESS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-SIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-VAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MAX-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MDI-CHILD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MDI-FRAME

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MEDIUM-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MEMORY

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MENU

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MERGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MESSAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MESSAGES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

METACLASS

...

...

...

...

...

...

...

...

...

C370(2)

MVS

...

...

...

...

OS390

ENT

...

...

METHOD

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

METHOD-ID

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

MIN-HEIGHT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MIN-LINES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MIN-SIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MIN-VAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MIN-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MODAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MODE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MODELESS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MODIFIED

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

MODIFY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MODULES

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MONITOR-POINTER

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MORE-LABELS

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

MOVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MULTILINE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

MULTIPLE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MULTIPLY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

MUTEX-POINTER

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

N

NAME

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

NAMED

MF3

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

MS(2)

...

...

...

...

...

...

NAMESPACE

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

NAMESPACE-PREFIX

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

NATIONAL

MF8

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

NATIONAL-EDITED

MF8

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

NATIVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NAVIGATE-URL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NCHAR

MF5

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

NEGATIVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NESTED

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

NET-EVENT-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NEW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

NEWABLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

NEXT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NEXT-ITEM

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NO-AUTO-DEFAULT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-AUTOSEL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-BOX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-CELL-DRAG

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-CLOSE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-DIVIDERS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-ECHO

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

NO-F4

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-FOCUS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-GROUP-TAB

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-KEY-LETTER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-SEARCH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-TAB

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NO-UPDOWN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NOMINAL

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

NONE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

NONNUMERIC

MF18

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

NORMAL

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

NOT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NOTE

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

NOTIFY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NOTIFY-CHANGE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NOTIFY-DBLCLICK

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NOTIFY-SELCHANGE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NSTD-REELS

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

NULL

MF6

...

...

I2

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

NULLABLE

MGD

NULLS

MF6

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

NUM-COL-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NUM-ROW-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NUM-ROWS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

NUMBER

MF3

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NUMBERS

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

NUMERIC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

NUMERIC-EDITED

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

NUMERIC-FILL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

O

O-FILL

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

OBJECT

MF11

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

OBJECT-COMPUTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OBJECT-ID

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OBJECT-REFERENCE

MF15

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OBJECT-STORAGE

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OCCURS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OFF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OK-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

OMITTED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ON

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ONLY

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

OOSTACKPTR

MF10

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OPEN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OPERATOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

OPERATOR-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

OPTIONAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OPTIONS

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ORDER

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

ORGANIZATION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OTHER

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

OTHERWISE

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

OUTPUT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OVERFLOW

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

OVERLAP-LEFT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

OVERLAP-TOP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

OVERLAPPED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

OVERLINE

MF4

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

OVERRIDE

MF12

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

P

PACKED-DECIMAL

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

PADDING

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

PAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PAGE-COUNTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PAGE-SETUP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PAGE-SIZE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PAGED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PANEL-INDEX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PANEL-STYLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PANEL-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PANEL-WIDTHS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PARAGRAPH

MF7

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PARAMS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

PARENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

ACU

PARSE

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

PARTIAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

PASSWORD

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

PERFORM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PERMANENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PIC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PICTURE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PIXEL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PIXELS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PLACEMENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PLUS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

POINTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

POP-UP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

POSITION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

POSITION-SHIFT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

POSITIONING

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

POSITIVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PREFIXING

MF13

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PRESENT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PREVIOUS

MF3

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PRINT

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

PRINT-CONTROL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PRINT-NO-PROMPT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PRINT-PREVIEW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PRINT-SWITCH

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

BS

...

...

...

...

PRINTER

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

PRINTER-1

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PRINTING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PRIOR

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

PRIORITY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PRIVATE

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PROCEDURE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PROCEDURE-POINTER

MF5

...

...

...

...

...

...

...

...

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

PROCEDURES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PROCEED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PROCESS

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

PROCESSING

MF12

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

PROGRAM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PROGRAM-ID

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

PROGRAM-POINTER

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PROGRESS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PROMPT

MF3

...

...

...

...

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

...

PROPERTIES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

PROPERTY

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

PROPERTY-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

PROPERTY-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

PROTECTED

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PROTOTYPE

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PUBLIC

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

PURGE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

PUSH-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

Q

QUERY-INDEX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

QUEUE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

QUOTE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

QUOTES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

R

RADIO-BUTTON

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RAISE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

RAISED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RAISING

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RANDOM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RANGE

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

READ

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

READ-ONLY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

READING

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

READY

MF3

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

...

OS390

ENT

...

...

RECEIVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RECORD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RECORD-DATA

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RECORD-OVERFLOW

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

RECORD-TO-ADD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RECORD-TO-DELETE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RECORDING

MF3

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

RECORDS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RECURSIVE

MF12

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

...

OS390

ENT

...

...

REDEFINE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

REDEFINES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REDEFINITION

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

REEL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REFERENCE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

REFERENCES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REFRESH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

REGION-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RELATION

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RELATIVE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RELEASE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RELOAD

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

REMAINDER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REMARKS

...

...

...

...

...

...

OS

DVS

...

...

...

RM

...

...

...

...

...

...

ACU

REMOVAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RENAMES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REORG-CRITERIA

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

REPEATED

MF10

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

REPLACE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

REPLACING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REPORT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REPORTING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REPORTS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REPOSITORY

MF12

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

BS

OS390

ENT

...

...

REQUIRED

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

REREAD

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

RERUN

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RESERVE

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RESET

MF3

...

...

I2

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

BS

OS390

ENT

...

...

RESET-GRID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RESET-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RESET-TABS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RESIZABLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RESTRICTED

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RESULT-SET-LOCATOR

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RESUME

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RETRY

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

RETURN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RETURN-CODE

MF5

...

...

...

XO(1,2)

SAA(2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

RETURNING

MF5

...

...

I2

...

...

...

...

...

C370,(2)

MVS

...

...

...

BS

OS390

ENT

...

...

REVERSE

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

REVERSE-VIDEO

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

REVERSED

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REWIND

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

REWRITE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RF

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RIGHT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RIGHT-ALIGN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

RIGHT-JUSTIFY

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

RIMMED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROLLBACK

MF1

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

ROLLING

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

ROUNDED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ROW-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROW-COLOR-PATTERN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROW-DIVIDERS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROW-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROW-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROW-PROTECTION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

ROWID

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

RUN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

S

S01

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

S02

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

S03

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

S04

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

S05

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

SAME

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SAVE-AS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SAVE-AS-NO-PROMPT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SCREEN

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

SCROLL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SCROLL-BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEARCH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEARCH-OPTIONS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SEARCH-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SECONDS

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SECTION

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SECURE

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

SECURITY

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEEK

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

SEGMENT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEGMENT-LIMIT

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SELECT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SELECT-ALL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SELECTION-INDEX

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SELECTION-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SELECTIVE

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

SELF

MF10

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

...

OS390

ENT

...

...

SELF-ACT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SELFCLASS

MF10

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SEMAPHORE-POINTER

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SEND

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SENTENCE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEPARATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEPARATION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SEQUENCE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SEQUENTIAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SERVICE

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

SET

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SETTER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

SHADING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SHADOW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SHARING

MF11

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SHIFT-IN

...

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

SHIFT-OUT

...

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

SHORT-DATE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SHOW-LINES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SHOW-NONE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SHOW-SEL-ALWAYS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SIGN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SIGNED

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SIZE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SKIP1

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SKIP2

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SKIP3

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SMALL-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SORT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SORT-CONTROL

...

...

...

...

...

...

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

SORT-CORE-SIZE

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SORT-FILE-SIZE

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SORT-MERGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SORT-MESSAGE

...

...

...

...

...

...

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

SORT-MODE-SIZE

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SORT-OPTION

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

SORT-ORDER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SORT-RETURN

MF7

...

...

...

...

SAA(2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

SORT-TAPE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

SORT-TAPES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

SOURCE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SOURCE-COMPUTER

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SOURCES

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SPACE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SPACE-FILL

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

SPACES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SPECIAL-NAMES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SPINNER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SQL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SQUARE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STANDARD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

STANDARD-1

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

STANDARD-2

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

STANDARD-3

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

START

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

START-X

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

START-Y

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STARTING

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

STATIC

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

STATIC-LIST

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STATUS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

STATUS-BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STATUS-TEXT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STEP

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

STOP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

STOP-BROWSER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

STRING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

STRONG

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

STYLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SUB-QUEUE-1

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SUB-QUEUE-2

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SUB-QUEUE-3

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SUBFILE

MF7

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

SUBTRACT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SUBWINDOW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SUFFIXING

MF13

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SUM

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SUPER

MF10

...

...

I2

...

...

...

...

...

C370(2)

MVS

...

...

...

...

OS390

ENT

...

...

SUPPRESS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SYMBOL

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

OS390

ENT

...

...

SYMBOLIC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SYNC

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SYNCHRONIZED

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

SYSIN

...

...

...

...

...

...

OS

...

...

...

...

...

...

...

...

...

...

...

...

SYSIPT

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

SYSLST

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

SYSOUT

...

...

...

...

...

...

OS

...

...

...

...

...

...

...

...

...

...

...

...

SYSPCH

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

SYSPUNCH

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

SYSTEM

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

SYSTEM-DEFAULT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SYSTEM-INFO

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

T

TAB

...

...

...

...

...

...

...

...

...

...

...

RM

...

...

...

...

...

...

...

TAB-CONTROL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TAB-TO-ADD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TAB-TO-DELETE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TABLE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TALLY

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

TALLYING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TAPE

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TAPES

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

TEMPORARY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TERMINAL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TERMINAL-INFO

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TERMINATE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TERMINATION-VALUE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TEST

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

TEXT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

...

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

THAN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

THEN

MF1

...

85

I2

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

THREAD

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

THREAD-LOCAL

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

THREAD-LOCAL-STORAGE

MF10

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

THREAD-POINTER

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

THROUGH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

THRU

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

THUMB-POSITION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TILED-HEADINGS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TIME

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIME-OF-DAY

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TIME-OUT

MF7

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

TIME-RECORD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIMEOUT

MF7

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

TIMES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIMESTAMP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIMESTAMP-OFFSET

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIMESTAMP-OFFSET-RECORD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TIMESTAMP-RECORD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TITLE

MF7

...

...

...

...

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

TITLE-BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TITLE-POSITION

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TOOL-BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TOP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TOTALED

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TOTALING

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TRACE

MF3

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

MS(2)

...

...

OS390

ENT

...

...

TRACK-AREA

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TRACK-LIMIT

...

...

...

...

...

...

OS

...

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TRACK-THUMB

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TRACKS

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TRADITIONAL-FONT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TRAILING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TRAILING-SHIFT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TRAILING-SIGN

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

TRANSACTION

...

...

...

...

...

SAA(1,2)

...

...

...

...

...

...

...

...

...

...

...

...

...

TRANSFORM

...

...

...

...

...

...

OS

DVS

VS(1,2)

...

...

...

...

...

...

...

...

...

...

TRANSPARENT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TRANSPARENT-COLOR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TREE-VIEW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

TRUE

MF7

...

85

I2

XO(1,2)

SAA(1,2)

...

...

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

BS

OS390

ENT

...

...

TRY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

TYPE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

TYPEDEF

MF10

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

U

UCS-4

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

UNDERLINE

MF3

...

...

I2

XO(1,2)

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

UNDERLINED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

UNEQUAL

MF7

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

UNFRAMED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

UNIT

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UNITS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

UNIVERSAL

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

BS

...

...

...

...

UNLOCK

MF1

...

...

I2

...

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

...

UNSIGNED

MF12

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

UNSORTED

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

UNSTRING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UNTIL

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UP

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UPDATE

MF3

...

...

...

...

...

...

...

...

...

...

RM

MS(1,2)

...

...

...

...

...

...

UPON

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UPPER

MF8

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

UPSI-0

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-1

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-2

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-3

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-4

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-5

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-6

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

UPSI-7

...

...

...

...

...

...

OS

DVS

...

...

...

...

...

...

...

...

...

...

...

USAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

USE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

USE-ALT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USE-RETURN

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USE-TAB

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USER

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

USER-COLORS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USER-DEFAULT

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

USER-GRAY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USER-WHITE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

USING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

UTF-16

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

UTF-8

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

V

VALID

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

VALIDATE

...

...

...

I2

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

VALIDATING

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

VALUE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

VALUE-FORMAT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VALUES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

VALUETYPE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

VALUETYPE-ID

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

VARBINARY

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

VARIABLE

MF3

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

VARIANT

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VARYING

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

VERTICAL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VERY-HEAVY

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VIRTUAL-WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VISIBLE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VOLATILE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

VPADDING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VSCROLL

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VSCROLL-BAR

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VSCROLL-POS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

VTOP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

W

WAIT

MF8

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

WEB-BROWSER

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

WHEN

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

WHEN-COMPILED

MF7

...

...

...

...

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

WHERE

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

WIDTH

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

WIDTH-IN-CELLS

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

WINDOW

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

WITH

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

WORDS

MF1

74

85

...

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

WORKING-STORAGE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

WRAP

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

WRITE

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

WRITE-ONLY

...

...

...

...

...

...

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

...

...

...

...

OS390

ENT

...

...

WRITE-VERIFY

...

...

...

...

...

...

...

DVS

...

...

...

...

...

...

...

...

...

...

...

WRITING

MF11

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

X

X

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

XML

MF12

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

XML-CODE

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

XML-DECLARATION

MF16

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

XML-EVENT

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

XML-NTEXT

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

XML-SCHEMA

MF16

ENT

XML-TEXT

MF12

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ENT

...

...

Y

Y

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

ACU

YIELDING

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

MGD

...

YYYYDDD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

YYYYMMDD

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

Z

ZERO

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ZERO-FILL

MF3

...

...

...

...

...

...

...

...

...

...

...

MS(2)

...

...

...

...

...

...

ZEROES

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

ZEROS

MF1

74

85

I2

XO(1,2)

SAA(1,2)

OS

DVS

VS(1,2,3,4)

C370(1,2)

MVS

RM

MS(1,2)

DG

BS

OS390

ENT

...

...

Key

The definitions of the dialect codes in the table are given below.

Dialect Code

Compiler Directive

Meaning

74

None

Word reserved in ANSI 74 standard

85

ANS85

Word reserved in ANSI 85 standard

I2

ISO2002

Word reserved in ISO 2002 standard

OS

OSVS

Word reserved in OSVS COBOL

VS(2)

VSC2"2"

Word reserved in VS COBOL II revision 2

VS(3)

VSC2"3"

Word reserved in VS COBOL II revision 3, IBM LE COBOL/370 and IBM COBOL for MVS and VM unless indicated otherwise

VS(4)

VSC2"4"

Word reserved in VS COBOL II revision 4, IBM LE COBOL/370 and IBM COBOL for MVS and VM unless indicated otherwise

C370

COBOL370"2"

Word reserved in IBM LE COBOL/370 revision 2 and IBM COBOL for MVS and VM, but not in VS COBOL II

OS390

OS390

Word reserved in COBOL for OS/390 and VM V2R2, but not in IBM LE COBOL/370 revision 2 and IBM COBOL for MVS and VM

ENT

ENTCOBOL

Word reserved in IBM Enterprise COBOL for z/OS and OS/390

XO

XOPEN

Word reserved as part of X/Open definition

MF<integer>

MF"<integer>"

<integer> corresponds to the level as shown in the MFLEVEL Compiler directive topic. Levels are cumulative, and so all reserved words for previous levels are in effect when a level is set.

MS1

MS"1"

Word reserved in Microsoft COBOL Version 1

MS2

MS"2"

Word reserved in Microsoft COBOL Version 2

RM

RM

Word reserved in RM/COBOL

DVS

DOSVS

Word reserved in DOSVS COBOL

BS

BS2000

Word reserved in Siemens BS2000 COBOL

MGD

JVMGEN

Word reserved in managed COBOL.

Parent topic: Reserved Words

Related information

Context-sensitive Words Table


Context-sensitive Words Table

The following table lists context-sensitive words, which are words that are reserved in the specified language construct when the specified dialect is chosen. If a context-sensitive word is used where a context-sensitive word is permitted in the general format, the word is treated as a keyword; otherwise, it is treated as a user-defined word. The dialect codes have the same meanings as in the section Reserved Words Table.

Context-sensitive Word | Language Context or Construct | Dialect Code
ARITHMETIC | OPTIONS paragraph | I2
ASYNC | METHOD-ID paragraph | MGD
ASYNC-VALUE | METHOD-ID paragraph | MGD
ASYNC-VOID | METHOD-ID paragraph | MGD
AUTO | screen description entry | I2, XO, MF3, MS2
BACKGROUND-COLOR | screen description entry | I2, XO, MF3, MS2
BACKGROUND-COLOUR | screen description entry | I2, MF3
BELL | screen description entry and SET attribute statement | I2, XO, MF3, MS2
BLINK | screen description entry and SET attribute statement | I2, XO, MF3, RM, MS2
CENTER | COLUMN clause | I2
CYCLE | EXIT statement | I2, MF7
DATA-POINTER |  | I2, MF15
ELEMENT | XML-GENERATE statement | MF18, ENT
EOL | ERASE phrase in screen description entry | I2, XO, MF7, RM
EOS | ERASE phrase in screen description entry | I2, XO, MF7, RM
ERASE | screen description entry | I2, XO, MF3, RM, MS2
EXPANDS | CLASS phrase and INTERFACE phrase of the REPOSITORY paragraph | I2, MF12
FOREGROUND-COLOR | screen description entry | I2, XO, MF3, MS2
FOREGROUND-COLOUR | screen description entry | I2, MF3
FOREVER | RETRY phrase | I2
FULL | screen description entry | I2, XO, MF3, MS2
HIGH | ACCEPT statement and DISPLAY statement | RM
HIGHLIGHT | screen description entry and SET attribute statement | I2, XO, MF3, MS2
IGNORING | READ statement | I2
INITIALIZED | ALLOCATE statement | MF19, I2, ENT
INTRINSIC | function-specifier of the REPOSITORY paragraph | I2
LC_ALL | SET statement | I2
LC_COLLATE | SET statement | I2
LC_CTYPE | SET statement | I2
LC_MESSAGES | SET statement | I2
LC_MONETARY | SET statement | I2
LC_NUMERIC | SET statement | I2
LC_TIME | SET statement | I2
LOW | ACCEPT statement and DISPLAY statement | RM
LOWLIGHT | screen description entry and SET attribute statement | I2, XO, MF7
MANUAL | LOCK MODE clause | I2, MF1, MS2
MULTIPLE | LOCK ON clause | all dialects
NAME | XML-GENERATE, INVOKE, and ACCEPT...FROM statements | MF3, ENT
NONE | DEFAULT clause | I2
NONNUMERIC | XML-GENERATE statement | MF18, ENT
NORMAL | STOP statement | I2
NUMBERS | COLUMN clause and LINE clause | I2
ONLY | Object-view, SHARING clause, SHARING phrase and USAGE clause | I2, MF11, BS
PARAGRAPH | EXIT statement | I2, MF7
PREVIOUS | READ statement | I2, MF3
RECURSIVE | PROGRAM-ID paragraph | I2, MF12, C370
RELATION | VALIDATE-STATUS clause | I2
REQUIRED | screen description entry | I2, XO, MF3, MS2
REVERSE | ACCEPT statement and DISPLAY statement | RM
REVERSE-VIDEO | screen description entry and SET attribute statement | I2, XO, MF3, MS2
SECONDS | RETRY phrase | I2
SECURE | screen description entry | I2, XO, MF3, MS2
SIGNED | USAGE clause | I2, MF12
STEP | OCCURS clause | I2
STRONG | TYPEDEF clause | I2
SYMBOL | CURRENCY clause | I2, MF12, OS390
UCS-4 | ALPHABET clause | I2
UNDERLINE | screen description entry and SET attribute statement | I2, XO, MF3, MS2
UNSIGNED | USAGE clause | I2, MF12
UTF-8 | ALPHABET clause | I2
UTF-16 | ALPHABET clause | I2
YYYYDDD | ACCEPT statement | all dialects
YYYYMMDD | ACCEPT statement | all dialects
Parent topic: Reserved Words
Related information
Reserved Words Table
Reserved Words Table


JSON-CODE Exception Codes

Your COBOL system supports the following exception codes that are available via the JSON-CODE special register. If one of these exceptions occurs, control is passed to the statement in the ON EXCEPTION phrase, or to the end of the JSON PARSE or JSON GENERATE statement if you did not code an ON EXCEPTION.

Table 1. JSON GENERATE exception codes
Code | Description
1 | The receiver was too small to contain the generated JSON text. The COUNT IN data item, if specified, contains the count of character positions that were actually generated.
Table 2. JSON PARSE exception codes
Code | Description
100 | JSON PARSE on line <line-num>, JSON text invalid at offset <offset>.
101 | JSON PARSE on line <line-num>, JSON text zero-length or entirely whitespace.
104 | JSON PARSE on line <line-num>, JSON name/value pair with name <name> at offset <offset> was incompatible with matching data item.
105 | JSON PARSE on line <line-num>, matching JSON name had value true or false at offset <offset>.
106 | JSON PARSE on line <line-num>, no JSON name matched any data item. Target was unmodified.
Parent topic: Part 4: Appendices
Related concepts
Special Registers


JSON-STATUS Non-Exception Codes

Your COBOL system supports the following non-exception JSON PARSE codes that are available via the JSON-STATUS special register:

Code | Description
1 | JSON PARSE on line <line-num>, no JSON name matched <name>.
2 | JSON PARSE on line <line-num>, no data item matched JSON name <name>.
8 | JSON PARSE on line <line-num>, JSON array <name> at offset <offset> had fewer elements than matching table.
16 | JSON PARSE on line <line-num>, JSON array <name> at offset <offset> had more elements than matching table.
32 | JSON PARSE on line <line-num>, data item matching JSON name <name> was unmodified because of value null at offset <offset>.
64 | JSON PARSE on line <line-num>, JSON array <name> included null at offset <offset>, corresponding element unmodified.
128 | JSON PARSE on line <line-num>, SIZE ERROR during assignment to numeric item from JSON name <name> at offset <offset>.
256 | JSON PARSE on line <line-num>, truncation during assignment from JSON name <name> at offset <offset>.
Parent topic: Part 4: Appendices
Related concepts
Special Registers


XML-CODE Exception Codes

Your COBOL system supports a subset of the exception codes that are available via the XML-CODE special register. If one of these exceptions occurs, control is passed to the statement in the ON EXCEPTION phrase, or to the end of the XML PARSE or XML GENERATE statement if you did not code an ON EXCEPTION.

Exception Codes supported when XMLPARSE is set to COMPAT

The following exception codes are dependent on the XMLPARSE(COMPAT) compiler directive being in effect when using XML PARSE.

Code | Description
1 | The parser found an invalid character while scanning white space outside element content.
2 | The parser found an invalid start of a processing instruction, element, comment or document type declaration outside element content.
3 | The parser found a duplicate attribute name.
4 | The parser found the markup character '<' in an attribute value.
5 | The start and end tag names of an element did not match.
6 | The parser found an invalid character in element content.
8 | The parser found in element content the CDATA closing character sequence '' without the matching opening character sequence ''.
9 | The parser found an invalid character in a comment.
10 | The parser found in a comment the character sequence '--' (dashdash) not followed by '>'.
11 | The parser found an invalid character in a processing instruction data segment.
12 | A processing instruction target name was 'xml' in lower-case, upper-case or mixed-case.
13 | The parser found an invalid digit in a hexadecimal character reference (of the form &#xdddd;).
14 | The parser found an invalid digit in a decimal character reference (of the form &#dddd;).
15 | The encoding declaration value in the XML declaration did not begin with lower- or upper-case A through Z
16 | A character reference did not refer to a legal XML character.
17 | The parser found an invalid character in an entity reference name.
18 | The parser found an invalid character in an attribute value.
100 | The parser reached the end of the document while scanning the start of the XML declaration.
101 | The parser reached the end of the document while looking for the end of the XML declaration.
102 | The parser reached the end of the document while looking for the root element.
103 | The parser reached the end of the document while looking for the version information in the XML declaration.
104 | The parser reached the end of the document while looking for the version information value in the XML declaration.
106 | The parser reached the end of the document while looking for the encoding declaration value in the XML declaration.
108 | The parser reached the end of the document while looking for the standalone declaration value in the XML declaration.
109 | The parser reached the end of the document while scanning an attribute name.
110 | The parser reached the end of the document while scanning an attribute value.
111 | The parser reached the end of the document while scanning a character reference or entity reference in an attribute value.
112 | The parser reached the end of the document while scanning an empty element tag.
113 | The parser reached the end of the document while scanning the root element name.
114 | The parser reached the end of the document while scanning an element name.
115 | The parser reached the end of the document while scanning character data in element content.
116 | The parser reached the end of the document while scanning a processing instruction in element content.
117 | The parser reached the end of the document while scanning a comment or CDATA section in element content.
118 | The parser reached the end of the document while scanning a comment in element content.
119 | The parser reached the end of the document while scanning a CDATA section in element content.
120 | The parser reached the end of the document while scanning a character reference or entity reference in element content.
122 | The parser found a possible invalid start of a document type declaration.
123 | The parser found a second document type declaration.
124 | The first character of the root element name was not a letter, '_' or ':'.
125 | The first character of the first attribute name of an element was not a letter, '_' or ':'.
126 | The parser found an invalid character either in or following an element name.
127 | The parser found a character other than '=' following an attribute name.
128 | The parser found an invalid attribute value delimiter.
130 | The first character of an attribute name was not a letter, '_' or ':'.
131 | The parser found an invalid character either in or following an attribute name.
132 | An empty element tag was not terminated by a '>' following the '/'.
133 | The first character of an element end tag name was not a letter, '_' or ':'.
134 | An element end tag name was not terminated by a '>'.
135 | The first character of an element name was not a letter, '_' or ':'.
138 | The first character of a processing instruction target name was not a letter, '_' or ':'.
139 | The parser found an invalid character in or following a processing instruction target name.
140 | A processing instruction was not terminated by the closing character sequence '?>'.
141 | The parser found an invalid character following '&' in a character reference or entity reference.
142 | The version information was not present in the XML declaration.
143 | 'version' in the XML declaration was not followed by a '='.
144 | The version declaration value in the XML declaration is either missing or improperly delimited.
145 | The version information value in the XML declaration specified a bad character, or the start and end delimiters did not match.
146 | The parser found an invalid character following the version information value closing delimiter in the XML declaration.
147 | The parser found an invalid attribute instead of the optional encoding declaration in the XML declaration.
148 | 'encoding' in the XML declaration was not followed by a '='.
149 | The encoding declaration value in the XML declaration is either missing or improperly delimited.
150 | The encoding declaration value in the XML declaration specified a bad character, or the start and end delimiters did not match.
151 | The parser found an invalid character following the encoding declaration value closing delimiter in the XML declaration.
152 | The parser found an invalid attribute instead of the optional standalone declaration in the XML declaration.
153 | 'standalone' in the XML declaration was not followed by a '='.
154 | The standalone declaration value in the XML declaration is either missing or improperly delimited.
155 | The standalone declaration value was neither 'yes' nor 'no' only.
156 | The standalone declaration value in the XML declaration specified a bad character, or the start and end delimiters did not match.
157 | The parser found an invalid character following the standalone declaration value closing delimiter in the XML declaration.
158 | The XML declaration was not terminated by the proper character sequence '?>', or contained an invalid attribute.
159 | The parser found the start of a document type declaration after the end of the root element.
160 | The parser found the start of an element after the end of the root element.
201 | Miscellaneous XML document parsing errors.
300 | The document was encoded in EBCDIC, but the CODEPAGE compiler option specified a supported ASCII code page.
306 | The document was encoded in ASCII, but the CODEPAGE compiler option specified a supported EBCDIC code page.
310 | The CODEPAGE compiler option specified a supported EBCDIC code page, but the document was encoded in Unicode.

Exception Codes supported when XMLPARSE is set to XMLSS

The following exception codes are dependent on the XMLPARSE(XMLSS) compiler directive being in effect when using XML PARSE.

The exception code is formed from the return code and the reason code that the parser generates. The return code and the reason code are each a halfword binary value. The value in XML-CODE is a concatenation of these two values: the return code in the high-order halfword, and the reason code in the low-order halfword.

Return Codes
Code | Value | Description
0000 | XRC_SUCCESS | XMLPARSE processing was successful.
000C | XRC_NOT_WELL_FORMED | The document is not well-formed.
0010 | XRC_FATAL | Processing failed. Returned data areas or output parameters cannot be relied on to contain valid data.
0018 | XRC_NOT_VALID | The document is not valid according to the specified schema.
Reason Codes
Code | Value | Description
0000 | XRSN_SUCCESS | The XMLPARSE processing was successful.
1154 | XRSN_UNKNOWN_ERROR | An unknown abend occurred.
1203 | XRSN_PARM_UNSUPPORT_ENCODING | XML encoding string is not supported.
1502 | XRSN_NO_SCHEMAS_SPECIFIED | Either the schema vector parameter passed was NULL, or the number of schemas specified in the vector was zero.
2000 | XRSN_COMMENT_INCOMPLETE | The document ended within comment markup.
3000 | XRSN_ATTR_DUPLICATE | Duplicate attributes were found.
3002 | XRSN_NS_ATTR_PREFIX_NOT_DECL | Namespace prefix on attribute not declared.
3007 | XRSN_COMMENT_DASH_MISSING | Comment without starting dash found.
3008 | XRSN_COMMENT_CHAR_INVALID | Comment markup contains incorrect character.
3009 | XRSN_COMMENT_RIGHT_ANGLE_MISSING | Comment is missing the ending angle bracket at the end of the markup.
3010 | XRSN_CDATA_KEYWORD_INVALID | CDATA keyword expected but not found.
3011 | XRSN_CDATA_LEFT_BRACKET_MISSING | Left square bracket expected in CDATA markup.
3013 | XRSN_CDATA_CHAR_INVALID | A character was found that is not allowed within a CDATA section.
3017 | XRSN_PI_CHAR_INVALID | A character was found that is not allowed within a Processing instruction.
3018 | XRSN_ATTR_NAME_CHAR_INVALID | A character was found that is not allowed within an attribute name.
3020 | XRSN_ATTR_EQUAL_MISSING | An incorrect character was found after the attribute name, and the only character allowed is "=".
3021 | XRSN_ATTR_QUOTE_MISSING | An incorrect character was found after the attribute "=" character, and he only characters allowed here is either white space, or a single or double quote.
3022 | XRSN_ATTR_VALUE_CHAR_INVALID | An incorrect character was found in an attribute value.
3030 | XRSN_CONTNT_CHAR_INVALID | An incorrect character is found in element content
3031 | XRSN_TAG_ELEMNAME_INVALID | An incorrect character is found in an element tag name.
3034 | XRSN_TAG_EMPTY_INVALID | An incorrect character is found after the "/" character to end the element tag. The only character allowed is a greater than symbol to end the empty element tag.
3035 | XRSN_ENDTAG_NAME_MISMATCH | At the element end tag, a mis-match element name is found compared o the name of the start element
3036 | XRSN_ENDTAG_EMPTY_TAG_INVALID | An incorrect character is found in the element end tag after the element name. The only characters allowed after the name is white pace or the greater than symbol.
3046 | XRSN_XML_VER_VALUE_INVALID | An incorrect XML version number was specified. The only allowed values are "1.0" or "1.1".
3050 | XRSN_XML_CHAR_INVALID | In the XML Declaration after the close of the version value, an incorrect character is detected.
3055 | XRSN_XML_ENC_CHAR_INVALID | An incorrect character is detected in the XML Declaration encoding value.
3057 | XRSN_XML_STD_VALUE_INVALID | An incorrect value for standalone was specified. The only allowed values are "yes" or "no".
3060 | XRSN_XML_END_CHAR_INVALID | An incorrect character is detected at the end of the XML declaration, where "?>" is expected.
3061 | XRSN_ENTITY_NOT_DEFINED | Entity not defined or not defined correctly.
3062 | XRSN_CHAR_INVALID | An incorrect character was detected in the document. Either white pace or "<" was expected.
3067 | XRSN_NS_URI_EMPTY | A non-default namespace declaration contains a URI value of zero length and the XML version is 1.0.
3068 | XRSN_INVALID_CHAR_SEQ | An invalid character sequence ]]> found in the content portion of the document.
3069 | XRSN_ENTITY_MARKUP_INCOMPLETE | Incomplete markup in entity.
8406 | XRSN_DEM_CDSECTUNTERMINATED | The CDATA section must end with ]]>.
8410 | XRSN_DEM_VERSIONINFOREQD | The version is required in the XML declaration.
8415 | XRSN_DEM_ELEMUNTERMINATED | The element must be followed by either attribute specifications, > or />.
8429 | XRSN_DEM_COMMENTUNTERM | The comment must end with a comment ending sequence.
8432 | XRSN_DEM_PIUNTERMINATED | The processing instruction must end with ?>.
8433 | XRSN_DEM_RESERVEDPITARGET | The processing instruction target matching [xX][mM][lL] is not allowed.
8435 | XRSN_DEM_DIGREQDINCHARREF | A decimal representation must immediately follow the &# in the character reference.
8437 | XRSN_DEM_SEMICOLONREQDINCHARREF | The character reference must end with a semicolon delimiter.
8438 | XRSN_DEM_INVCHARREF | The character reference contains an invalid character.
8601 | XRSN_VME_INVATTVALUEFORFIXED | The attribute value is not valid with respect to its fixed value constraint.
8603 | XRSN_VME_NONWSCHARINELEMONLYCONT | The element cannot have non-white space character data because the type's content type is element-only.
8604 | XRSN_VME_EXPELEMNOMATCH | An expected element match was not found.
8605 | XRSN_VME_REQDELEMMISSING | The required element or one of its substitutions is required.
8612 | XRSN_VME_UNDECLATT | The attribute found is not allowed to appear in the element.
8613 | XRSN_VME_REQDATTMISSING | The attribute must appear on the element.
8619 | XRSN_VME_XSITVALDOESNOTEXIST | The value cannot be resolved to a type definition for the element.
8622 | XRSN_VME_FIXEDVCFAILURE | The value does not match the fixed value constraint value for the element.

Exception Codes supported for XML GENERATE

Code | Description
400 | The receiver was too small to contain the generated XML document. The COUNT IN data item, if specified, contains the count of character positions that were actually generated.
Parent topic: Part 4: Appendices
Related concepts
Special Registers


Glossary

!

77 level-description-entry

A data description entry that describes a noncontiguous data item with the level-number 77.

78 level-description-entry

A data description entry that describes a constant-name with the level-number 78.

88 level-description-entry

A data description entry that describes a condition-name with the level-number 88.

A

abbreviated combined relation condition

The combined condition that results from the omission of a common subject or a common subject and common relational operator in a consecutive sequence of relation conditions.

abstract class

A class which does not act as a creator of instance objects. Abstract classes implement behavior for their subclasses.

access mode

The manner in which records are to be operated upon within a file.

activated runtime element

A function, method or program placed into the active state by a statement.

activating runtime element

A function, method or program that contains the activating statement.

activating statement

A statement that causes the execution of a function, method or program.

active state

The state of a function, method or program that has been activated but has not yet returned to the activating runtime element.

actual decimal point

The physical representation, using either of the decimal point characters "." (period) or "," (comma), of the decimal point position in a data item.

alphabet-name

A user-defined word in the Special-Names paragraph of the Environment Division that assigns a name to a specific character set and/or collating sequence.

alphabetic character

A character that belongs to the following set of letters: 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, 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 and z and the space.

alphanumeric character

Any letter or number in the computer's character set.

alphanumeric function

A function whose value is composed of a string of one or more characters from the computer's character set.

alternate record key

A key, other than the prime record key, whose contents identify a record within an indexed file.

argument

An operand specified in the activating statement of a function, a method or a program that specifies the data to be passed upon activation of the intrinsic function or runtime element.

arithmetic expression

An identifier or a numeric elementary item, a numeric literal, such identifiers and literals separated by arithmetic operators, two arithmetic expressions separated by an arithmetic operator, or an arithmetic expression enclosed in parentheses.

arithmetic operator

A single character, or a fixed two-character combination, that belongs to the following set:

Character Meaning
+ Addition
- Subtraction
* Multiplication
/ Division
** Exponentiation
ascending key

A key upon the values of which data is ordered starting with the lowest value of key up to the highest value of key in accordance with the rules for comparison of data items.

assumed decimal point

A decimal point position which does not involve the existence of an actual character in a data item. The assumed decimal point has logical meaning but no physical representation.

at end condition

A condition caused in one of three circumstances:

  1. During the execution of a READ statement for a sequentially accessed file.
  2. During the execution of a RETURN statement when no next logical record exists for the associated sort or merge file.
  3. During the execution of a SEARCH statement, when the search operation terminates without satisfying the condition specified in any of the associated WHEN phrases.
automatic data

The data described in the Local-Storage Section.

automatic data item

A data item that is described as part of an automatic data record.

automatic data record

A logical record that is described in the Local-Storage Section.

B

block

A physical unit of data that is normally composed of one or more logical records. For mass storage files, a block can contain a portion of a logical record. The size of a block has no direct relationship to the size of the file within which the block is contained or to the size of the logical record(s) that are either continued within the block or that overlap the block. The term is equivalent to physical record.

C

call prototype

A program with the EXTERNAL clause in the Program-ID paragraph. A call prototype is a program declaration that is not executed but is used by the compiler system to validate CALL statements in program definitions that appear in the same source file.

called program

A program that receives control as the result of the execution of a CALL statement.

calling runtime element

A function, method or program that transfers control to a program by execution of a CALL statement.

chained program

A program which is the object of a CHAIN statement.

chaining program

A program which executes a CHAIN to another program.

character

The basic indivisible unit of the language.

character boundary

The leftmost bit of an addressing boundary in the storage of the computer.

character position

The amount of physical storage required to store a single standard data format character described as USAGE IS DISPLAY.

character set

The complete COBOL language character set consists of all the characters listed below:

Character | Meaning
0,1,...,9 | Numeric digit
A,B,...,Z | Upper-case alphabetic
a,b,...,z | Lower-case alphabetic
Space (blank)
+ Plus sign
- Minus sign
* Asterisk
/ Stroke (virgule, slant or slash)
= Equal sign
$ Currency sign
, Comma
; Semicolon
. Period (decimal point, full stop)
" Quotation mark
( Left parenthesis
) Right parenthesis
> Greater than symbol
< Less than symbol
: Colon
' Apostrophe
& Ampersand
Note: If the computer character set includes lower-case letters, they can be used in character strings and text words. Except when used in nonnumeric literals, each lower-case letter is equivalent to the corresponding upper-case letter.
character-string

A sequence of contiguous characters which form a COBOL word, a literal, a PICTURE character-string or a comment-entry.

class

The entity that defines common behavior and implementation for zero, one or more objects. Objects that share the same implementation are considered to be objects of the same class.

class condition

The proposition, for which a truth value can be determined, that an operand is wholly alphabetic or is wholly numeric, or alphabetic-lower, or alphabetic-upper, or contains only the characters in the set of characters specified by the CLASS clause as defined in the Special-Names paragraph of the Environment Division.

class definition

The source unit that defines a class.

class method

A method for a class object.

class-name (for object orientation)

A user-defined word that identifies a class.

class-name (for truth value proposition)

A user-defined word defined in the Special-Names paragraph of the Environment Division that assigns a name to the proposition for which a truth value can be determined, that the content of a data item consists exclusively of those characters listed in the definition of the class-name.

clause

An ordered set of consecutive COBOL character-strings whose purpose is to specify an attribute of an entry.

COBOL word

See word.

collating sequence

The sequence in which the characters that are acceptable in a computer are ordered for purposes of sorting, merging, comparing and for processing indexed files sequentially.

column

A character position within a print line or a screen line. The columns are numbered from one, by one, starting at the leftmost character position of the line and extending to the rightmost character position of the line.

combined condition

A condition that is the result of connecting two or more conditions with the "AND" or the "OR" logical operator.

comment entry

An entry in the Identification Division that can be any combination of characters from the computer's character set. A comment entry is for documentary purposes only, may extend over more than one line and is terminated upon encountering a division, section or paragraph name or encountering any character in area A of a line.

comment indicator

The two contiguous COBOL characters '*>', which indicate a comment line or an in-line comment.

comment line

A source line represented by an asterisk in the indicator area of the line and any characters from the computer's character set in area A and area B of that line. The comment line serves only for documentation . A special form of comment line is represented by a slash (/) in the indicator area of the line and any characters from the computer's character set in area A and area B of that line causes page ejection before the comment is printed.

common program

A program that is directly contained within another program, and can be called from any program directly or indirectly contained in that other program.

compilation group

A sequence of source units submitted for compilation together.

compilation unit

A source unit that is not nested within another source unit.

compile time

The time at which a compilation group is translated to a runtime module consisting of one or more executable runtime elements.

compiler-directing statement

A compiler directive or a source text manipulation statement.

compiler directive

An instruction to the COBOL Compiler to take specific action when compiling a compilation group.

compiler directive line

A line of source text beginning with the two contiguous COBOL characters >> followed by a compiler-directive word.

compiler-directive word

A COBOL word that is used in the syntax of a compiler directive.

complex condition

A condition in which one or more logical operators act upon one or more conditions. See negated simple condition, combined condition, negated combined condition.

computer-name

A system-name that identifies the computer upon which the compilation group is to be converted to object code, or the object code run.

condition

A status for which a truth value can be determined at execution time. Where the term "condition" (condition-1, condition-2, ...) appears in a general format or in rules that reference a general format, it is a conditional expression consisting of either a simple condition optionally parenthesized, or a combined condition consisting of a syntactically correct combination of simple conditions, logical operators, and parentheses for which a truth value can be determined.

condition-name

A user-defined word assigned to a specific value, set of values, or range of values, within the complete set of values that a conditional variable can possess; or the user-defined word assigned to a status of an implementor-defined switch or device.

condition-name condition

The proposition, for which a truth value can be determined, that the value of a conditional variable is a member of the set of values attributed to a condition-name associated with the conditional variable.

conditional expression

A simple condition or a complex condition specified in an IF, PERFORM, EVALUATE or SEARCH statement. See simple condition and complex condition.

conditional statement

A statement for which the truth value of a specified condition is evaluated and used to determine subsequent flow of control.

conditional variable

A data item, one or more values of which has a condition-name assigned to it.

Configuration Section

A section of the Environment Division that describes overall specifications of source and run computers.

conformance (for object orientation)

The property that allows an object with a given interface to be used where an object with a different interface is expected. Conformance ensures that any operation specified for the conformed interface is supported by the conforming interface.

constant-name

A user-defined word assigned as the name of a fixed value.

context-sensitive words

COBOL words that are specified in formats but are reserved only in the context in which they are specified.

contiguous items

Items that are described by consecutive entries in the Data Division and that bear a definite hierarchic relationship to one another.

counter

A data item used for storing numbers or number representations in a manner that permits these numbers to be increased or decreased by the value of another number, or to be changed or reset to zero or to an arbitrary positive or negative value.

CRT status

A conceptual entity whose value is set to indicate the status of a terminal input-output operation during the execution of an ACCEPT screen statement.

currency sign

The COBOL character '$', used as the default currency symbol in a picture character-string and as the default currency string that appears in the edited format of data items.

Note: Features exist for selection of other currency strings and currency symbols.
currency string

The set of characters to be placed into numeric-edited data items as a result of editing operations when the item includes a currency symbol in its picture character-string. See the topic The Special-Names Paragraph.

currency symbol

The character used in a picture character-string to represent the presence of a currency string. See the section The Special-Names Paragraph.

current record

In file processing, the record that is available in the record area associated with a file.

current volume pointer

A conceptual entity that points to the current volume of a sequential file.

cursor

A visible indicator on a character-addressable terminal screen that shows the position on the screen at which the next data character input at the keyboard will be displayed.

cursor control keys

Keys on the keyboard of a character-addressable terminal that control the positioning of the cursor on the screen. Typically these include keys that move the cursor up, down, left, right, to the next screen item, to the previous screen item.

D

data description entry

An entry in the Data Division that is composed of a level-number followed by a data-name, if required, and then followed by a set of data clauses as required.

data item

A unit of data defined by a data description entry or resulting from the evaluation of an identifier.

data keys

Keys on the keyboard of a character-addressable terminal that represent individual printable data characters.

data-name

A user-defined word that names a data item described in a data description entry in the Data Division. When used in the general formats, "data-name" represents a word which can neither be subscripted nor indexed unless specifically permitted by the rules for that format.

DBCS

See double-byte character set.

debugging Line

Any line with "D" or "d" in the indicator area of the line for fixed format source, or any line with "D" or "d" as the first character and space as the second character of the line for free format source.

Debugging Section

A section that contains a USE FOR DEBUGGING statement.

declaratives

A set of one or more special purpose sections written at the beginning of the Procedure Division, the first of which is preceded by the key word DECLARATIVES and the last of which is followed by the key words END DECLARATIVES. A declarative is composed of a section header, followed by a USE COBOL system-directing-sentence, followed by a set of associated paragraphs (zero or more).

declarative-sentence

A COBOL system-directing sentence consisting of a single USE statement terminated by the separator period (. ).

de-edit

The logical removal of all editing characters from a numeric-edited data item in order to determine that item's unedited numeric value.

delimited scope statement

Any statement that includes its explicit scope terminator.

delimiter

A character (or sequence of contiguous characters) that identifies the end of a string of characters, and separates that string of characters from the following string of characters. A delimiter is not part of the string of characters that it delimits.

descending key

A key upon the values of which data is ordered starting with the highest value of key down to the lowest value of key, in accordance with the rules for comparing data items.

digit position

The amount of physical storage required to store a single digit. This amount varies depending on the usage of the data item describing the digit position.

division

There are four divisions in a COBOL source element: Identification, Environment, Data and Procedure. Each division consists of zero or more sections or paragraphs.

division header

A combination of words followed by a period and a space that indicate the beginning of a division. The division headers are:

double-byte character set

A character set in which two bytes are used for each character.

dynamic access

An access mode in which specific logical records can be obtained from or placed into a disk file in a non-sequential manner (see random access) and obtained from a file in a sequential manner (see sequential access) during the scope of the same OPEN statement.

E

editing character

A single character or two-character combination that is specified in the PICTURE character-string and inserted into the data item when it is edited.

elementary item

A data item that is not logically subdivided.

end marker

A marker for the end of a source unit.

end of Procedure Division

The physical position in a COBOL source element after which no further procedures appear.

end program marker
A combination of words, followed by a separator period, that indicates the end of a COBOL source program. The end program header is:
 END PROGRAM program-name.
Enter key

A key on the keyboard of a character-addressable terminal that signals that the input of the screen item or the screen record is complete.

entry

Any descriptive set of consecutive clauses terminated by a separator period (. ) (except for a comment entry) and written in the Identification Division, Environment Division or Data Division.

entry-name

A user-defined word that identifies an alternative point at which to start executing a program from the default point which is the first non-declarative procedural statement in the source program.

execution time

The time at which a function, method or program is executed.

explicit attribute

Any attribute which has been explicitly defined.

explicit interface member implementation

An explicit interface member implementation is a method that may not be invoked explicitly. The method may be invoked implicitly when the corresponding method is invoked on an instance of this class which has been cast to the interface type.

explicit scope terminator

A reserved word that terminates the scope of a particular Procedure Division statement.

exponent

In floating-point representation, that power to which the radix of the representation is to be raised.

expression

An arithmetic or conditional expression.

extend mode

The state of a file connector after execution of an OPEN statement, with the EXTEND phrase specified, for that file connector and before the execution of a CLOSE statement without the REEL or UNIT phrase for that file connector.

external data

Data described as external data items and external file connectors.

external file connector

A file connector which is accessible to one or more runtime elements in the run unit.

external repository

See repository.

external switch

A hardware or software device, defined and named by the implementor, that is used to indicate that one of two alternate states exists.

F

factory definition

The source unit that defines a factory object.

factory method

A method for a factory object.

factory object

The single object of a class, defined by the factory definition of a class. There is one factory object for each class. The factory object is the creator of objects of the class.

factory (object) data

The data for a factory object, declared in the Data Division of a factory definition and common for all objects of the class.

field (of a screen)

A contiguous area of a terminal screen that represents an elementary screen item.

figurative constant

A value generated by your COBOL system which is referenced through the use of certain reserved words.

file

A physical collection of logical records.

file connector

A storage area which contains information about a file and is used as the linkage between a file-name and a physical file and between a file-name and its associated record area.

file control entry

A SELECT clause and subordinate clauses that declare the relevant physical attributes of a file.

file description entry

An entry in the File Section of the Data Division that is composed of the level indicator FD, followed by a file-name, and then followed by a set of file clauses as required.

file-name

A user-defined word that names a file connector described in a file description entry or a sort-merge file description entry within the File Section of the Data Division.

file organization

The permanent logical file structure established at the time that a file is created.

file position indicator

A conceptual entity that contains the value of the current key within the key of reference for an indexed file, or the record number of the current record for a sequential file, or the relative record number of the current record for a relative file, or indicates that no next logical record exists, or that the number of significant digits in the relative record number is larger than the size of the relative key data item, or that an optional input file is not present, or that the at end condition already exists, or that no valid next record has been established.

File Section

The section of the Data Division that contains file description entries and sort-merge file description entries together with their associated record descriptions.

file status

A conceptual entity that contains a two-character value indicting the status of an input-output operation.

file sharing

A cooperative environment that controls concurrent access to the same physical file.

fixed file attributes

Information about a file which is established when a file is created and cannot subsequently be changed during the existence of the file. These attributes include the organization of the file (sequential, relative, or indexed), the prime record key, the alternate record keys, the code set, the minimum and maximum record size, the record type (fixed or variable), the collating sequence of the keys for indexed files, the maximum and minimum physical record size, the padding character, and the record delimiter.

fixed format mode

The default manner in which data entry is made to numeric and numeric-edited screen fields. This mode formats and echoes the entered data and also moves the cursor in accordance with the requirements of the field's picture specification, as each keystroke is received. Characters other than " +", "-", and the decimal point character, are rejected; insertion characters in edited fields are skipped over as the cursor moves backwards and forwards; any sign indicator is modified in accordance with its normal specification; floating symbols move left and right in the field, and insertion symbols appear and disappear as digits are inserted or deleted.

fixed format source

A source format in which each COBOL source line consists of 80 characters which are divided into various fixed areas. There are restrictions on the syntax that can appear in each area. The alternative is free format source.

fixed-length record

A record associated with a file whose file description or sort-merge description entry requires that all records contain the same number of character positions.

fixed-point numeric item

A numeric data item using fixed-point representation.

fixed-point numeric literal

A quantity, in fixed-point representation, that has a radix of ten and is expressed as a literal composed of one or more numeric characters and optionally either a decimal point or an algebraic sign, or both.

fixed-point representation

A positional representation in which each number is represented by a single sequence of digits, the position of the radix point being fixed with respect to the rightmost end of the set according to the position of the implicit or explicit radix point.

floating-point literal

A quantity, in floating-point representation, that has a base of ten and is written as a signed fixed-point numeric literal that must have a decimal point in any character position (the significand), immediately followed by the letter "E", which is, in turn, immediately followed by a signed fixed-point numeric literal that does not contain a decimal point (the exponent).

floating-point representation

A number representation in which a number is represented by two sequences of digits, the significand and the exponent.

footing area

The position of the page body adjacent to the bottom margin of the printed page.

format

A specific arrangement of a set of data.

format parameter

A data-name specified in the USING phrase of the PROCEDURE DIVISION header or ENTRY statement that gives the name used in the function, method or program for a parameter.

free format mode

An alternative manner in which data entry can be made to numeric and numeric-edited screen fields. The default mode is fixed format mode. This configurable mode allows data to be keyed into a PIC X field of appropriate length, and it is only when the operator leaves the field that the data is reformatted to comply with the picture specification. Once the operator moves the cursor from the field, your COBOL system disregards all characters other than digits and the sign and decimal point symbols. It then extracts, stores, or reformats the numeric value in accordance with the normal COBOL rules for a MOVE to an item with the same picture as the screen or working-storage item. The numeric value is then usually echoed to the screen.

free format source

A source format in which each COBOL source line can consist of up to 250 bytes of characters. There is no restriction on where syntax may appear on the line. The alternative is fixed format source.

function

A temporary data item whose value is determined at the time an intrinsic or a user-defined function is referenced during the execution of a statement.

function-identifier

An identifier that references an intrinsic-function-name, a user-defined-name, or a function-prototype-name. The data item represented by a function is uniquely identified by a function-name with its arguments, if any. A function-identifier can include a reference-modifier. A function-identifier that references an alphanumeric function can be specified anywhere in the general formats that an identifier can be specified, subject to certain restrictions. A function-identifier that references an integer or numeric function can be referenced anywhere in the general formats that an arithmetic expression can be specified.

function key

A key on the keyboard of a character addressable terminal that, when enabled and pressed, signals that input of the screen record is complete and a function is requested.

function-name

A word that names a mechanism provided by the implementor to determine the value of a function.

function prototype definition

A definition that specifies the rules governing the arguments needed for the evaluation of a particular function, the data item resulting from the evaluation of the function, and all other requirements needed for the evaluation of that function.

G

global name

A name declared in only one program that may be referenced from that program and from any program contained within that program.

group item

A named contiguous set of elementary items.

H

high order end

The leftmost character of a string of characters.

I

I-O-Control

The name of an Environment Division paragraph in which requirements for specific input/output techniques, rerun points, sharing of same areas by several data files, and multiple file storage on a single input/output device are specified.

I-O mode

The state of a file connector after execution of an OPEN statement with the I-O phrase specified, for that file connector and before the execution of a CLOSE statement without the REEL or UNIT phrase for that file connector.

identifier

A sequence of character-strings and separators that uniquely references a unit of data.

imperative statement

A statement that specifies an unconditional action to be taken or a conditional statement that is delimited by its explicit scope terminator (delimited scope statement). An imperative statement can consist of a sequence of imperative statements.

implementor-name
A system-name defined in the Environment division that identifies a hardware or software feature of the operating system. Link it to a mnemonic-name, which can be used in your source code to communicate with the feature.
implicit attribute

Any attribute which has not been explicitly specified.

implicit scope terminator

A separator period that terminates the scope of any preceding unterminated statement, or a phrase of a statement which by its occurrence indicates the end of the scope of any statement contained within the preceding phrase.

implicit segment

A segment created by your COBOL system to control the size of code segments.

index

A computer storage area or register, the contents of which represent the identification of a particular element in a table.

index data item

A data item in which the value associated with an index-name can be stored.

index-name

A user-defined word that names an index associated with a specific table.

indexed data-name

An identifier that is composed of a data-name, followed by one or more index-names enclosed in parentheses.

indexed file

A file with indexed organization.

indexed organization

The permanent logical file structure in which each record is identified by the value of one or more keys within that record.

indicator area

The leftmost position of a COBOL source record that indicates the use of the record.

inheritance (for classes)

A mechanism for using the interface and implementation of one or more classes as the basis for another class. A subclass inherits from one or more superclasses. The interface of an inheriting class conforms to the interface of the inherited classes.

inheritance (for interfaces)

A mechanism for using the specification of one or more interfaces as the basis for another interface. An inheriting interface conforms to the inherited interface.

initial data

The data described in the Working-Storage or File Section of an initial program.

initial data item

A data item that is described as part of an initial data record.

initial data record

A logical record that is described in the Working-Storage or File Section of an initial program and is initialized on every call to the program.

initial file connector

A file connector that is described in an initial program and is not in an open mode on any call to the program.

initial program

A program that is placed into an initial state every time the program is called in a run unit.

initial state

The state of a function, method or program when it is first activated in a run unit.

in-line comment

A comment preceded on a source line by one or more COBOL words or character-strings.

input field

A screen item whose description contains a TO phrase.

input file

A file that is opened in the input mode.

input mode

The state of a file connector after execution of an OPEN statement with the INPUT phrase specified, for that file connector and before the execution of a CLOSE statement without the REEL or UNIT phrase for that file connector.

input-output control system (IOCS)

A system provided by the implementor that directs, or controls, the processing of files.

input-output file

A file that is opened in the I-O mode.

Input-Output Section

The section of the Environment Division that names the files and the external media used and which provides information required for transmission and handling of data during execution .

input-output statement

A statement that causes files to be processed by performing operations upon individual records or upon the file as a unit. The input-output statements are: CLOSE, DELETE, OPEN, READ, REWRITE, START and WRITE.

input procedure

A set of statements to which control is given during the execution of a SORT statement, for the purpose of controlling the release of specified records to be sorted..

instance method

A method of an instance object (as opposed to a class method).

instance-of condition

The proposition, for which a truth value can be determined, that an object reference is an instance of a particular class or interface.

integer

A numeric literal or a numeric data item that does not include any digit positions to the right of the decimal point.

integer function

A function whose category is numeric and whose definition provides that all digits to the right of the decimal point are zero in the returned value for any possible evaluation of the function.

interface (for a method)

The information needed to invoke a method correctly.

interface (the language construct)

A grouping of method prototypes.

interface definition

The source unit that defines an interface.

internal data

The data described in a source unit excluding all external data items and external file connectors. Items described in the Linkage Section are treated as internal data.

internal file connector

A file connector which is accessible to only one runtime module in a run unit.

intrinsic-function-name

A word that names a mechanism provided by the implementor to determine the value of a function.

invalid key condition

A condition occurring at execution time when a specific value of the key associated with an indexed or relative file is determined to be invalid.

invocation

See method invocation.

IOCS

See input-output control system.

K

key

A data item which identifies the location of a record, or a set of data items which serve to identify the ordering of data.

key of reference

The key, either prime or alternate, currently being used by a file connector to access records within an indexed file.

key word

A reserved word or intrinsic-function-name whose presence is required when the general format in which the word appears is used.

L

language-name

A system-name that specifies a particular programming language.

level indicator

Two alphabetic characters that identify a specific type of file. The level indicators in the Data Division are: FD, RD and SD.

level-number

A user-defined word which indicates the position of a data item in the hierarchical structure of a logical record or which indicates special properties of a data description entry. A level-number is expressed as a one- or two-digit number.

Level-numbers in the range 1 through 49 indicate the position of a data item in the hierarchical structure of a logical record. Level-numbers in the range 1 through 9 can be written either as a single digit or as a zero followed by a significant digit.

Level-numbers 66, 77, 78 and 88 identify special properties of a data description entry.

library-name

A user-defined word that names a COBOL library source file that is to be used by your COBOL system during creation of the object code.

library-text

Text that resides in a COBOL library for the purpose of being introduced into the source text at compile time by a COPY statement.

line sequential file organization

A type of sequential file containing variable length records in the format of text files produced by the host operating system.

Linkage Section

The section in the Data Division of the activated element that describes data items available from the activating element. These data items can be referenced by both the activating and the activated elements.

literal

A character-string whose value is derived from the ordered set of characters in the string.

literal field

An elementary screen item whose description contains no PICTURE clause.

lock mode

The state of an open file connector when record locking is in effect that indicates whether record locking is manual or automatic.

logical operator

One of the reserved words AND, OR and NOT. In the formation of a condition, both or either of AND and OR can be used as logical connections. NOT can be used for logical negation.

logical page

A conceptual entity consisting of the top margin, the page body and the bottom margin.

logical record

The most inclusive data item. The level-number for a record is 01.

low order end

The rightmost character of a string of characters.

M

mass storage

A storage medium in which data may be organized and maintained in both a sequential and nonsequential manner.

mass storage file

A collection of records that is assigned to mass storage.

merge file

A collection of records to be merged by a MERGE statement. The merge file is created and can be used only by the merge function.

method

Procedural code that is declared in the Procedure Division of a method definition and is executed by a method invocation on that object.

method definition

The source unit that defines a method.

method invocation

The request to execute a named method on a given object. A method invocation identifies an object, a method name, and the parameters required by the method definition.

method-name

A user-defined word that identifiers a method.

method prototype

The method-name and parameter types (including a returning item if specified) for a method. It is specified by a method definition in an interface.

mixed literal

A nonnumeric literal that includes DBCS characters.

mnemonic-name

A user-defined word that is associated in the Environment Division with a specified implementor-name.

N

native character set

The implementor-defined character set associated with the computer specified in the Object-Computer paragraph.

native collating sequence

The default collating sequence associated with the computer specified in the Object-Computer paragraph.

negated combined condition

The "NOT" logical operator immediately followed by a parenthesized combined condition.

negated simple condition

The "NOT" logical operator immediately followed by a simple condition.

next executable sentence

The next sentence to which control will be transferred after execution of the current statement is complete.

next executable statement

The next statement to which control will be transferred after execution of the current statement is complete.

next record

The record which logically follows the current record of a file.

noncontiguous items

Elementary data items, in the Working-Storage, Local-Storage and Linkage Sections, which bear no hierarchic relationship to other data items.

nonnumeric item (alphanumeric item)

A data item whose description permits its contents to be composed of any combination of characters taken from the computer's character set. Certain categories of nonnumeric items can be formed from more restricted character sets.

nonnumeric literal (alphanumeric literal)

A character-string bounded by quotation marks. The string of characters can include any character in the computer's character set. To represent a single quotation mark character within a nonnumeric literal, two contiguous quotation marks must be used.

null
  1. The state of a pointer that guarantees no storage is addressed by that data item - indicated by the predefined null data address value.
  2. The state of a procedure-pointer that guarantees no program is addressed by that data item - indicated by the predefined null program address value.
  3. The state of an object reference that guarantees no object is referenced by that data item - indicated by the value of the predefined object reference NULL.
numeric character

A character that belongs to the following set of digits: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9.

numeric function

A function whose class and category are numeric but which for some possible evaluation does not satisfy the requirements of an integer function.

numeric item

A data item whose description restricts its contents to a value represented by characters chosen from the digits 0 through 9; if signed, the item can also contain a "+", "-" , or other representation of an operational sign.

numeric literal

See fixed-point numeric literal and floating-point numeric literal.

O

object (instance)

A unit consisting of data and the methods that can act upon that data.

object data

Data described in the Data Division of an object definition, excluding data described in its methods.

object definition

The source unit that defines an object.

object method

A method of an object (as opposed to a factory method, which is a method of factory object).

object property

A name that may be used to qualify an object reference to get a value from or pass a value to an object.

object reference

An explicitly or implicitly defined data item that contains a reference to an object.

object view

Syntax that causes an object reference to be treated at complie time as though it had the specified description. At run time a conformance check for this description is performed on the object.

obsolete element

A language element in Standard COBOL that is to be deleted from the next edition of Standard COBOL.

open mode

The state of a file after execution of an OPEN statement for that file and before the execution of a CLOSE statement without the REEL or UNIT phrase for that file. The particular open mode is specified in the OPEN statement as either INPUT, OUTPUT, I-O or EXTEND.

operand

Any lower-case word (or words) that appears in a statement or entry format can be considered to be an operand and, as such, is an implied reference to the data indicated by the operand.

operational sign

An algebraic sign, associated with a numeric data item or a numeric literal, that indicates whether its value is positive or negative.

optional file

A file declared as being not necessarily present each time the runtime module is executed.

optional word

A reserved word that is included in a specific format only to improve the readability of the language.

output field

A screen item whose description contains a FROM phrase.

output file

A file that is opened in either the output mode or extend mode.

output mode

The state of a file connector after execution of an OPEN statement with the OUTPUT phrase specified, for that file connector and before the execution of a CLOSE statement without the REEL or UNIT phrase for that file connector.

output procedure

A set of statements to which control is given during execution of a SORT statement after the sort function is completed, or during execution of a MERGE statement after the merge function reaches a point at which it can select the next record in merged order when requested.

P

paragraph

In the Identification and Environment Divisions, a paragraph header followed by zero, one, or more entries. In the Procedure Division, a paragraph-name followed by a period and a space and optionally by one or more sentences.

paragraph header

A reserved word, followed by a period and a space that indicates the beginning of a paragraph in the Identification and Environment Divisions.

paragraph-name

A user-defined word that identifies and begins a paragraph in the Procedure Division.

parameterized class

A class where the full details of one or more dependent classes or interfaces are not specified in the class definition. The full details of these dependent classes or interfaces are specified by parameters before the parameterized class is used.

parameterized interface

An interface where the full details of one or more dependent classes or interfaces are not specified in the interface definition. The full details of these dependent classes or interfaces are specified by parameters before the parameterized interface is used.

phrase

An ordered set of COBOL character-strings that specifies an attribute of an entry or a statement and is a subset of a clause or paragraph in all divisions except the Procedure Division, and a subset of a statement in the Procedure Division.

physical page

A device-dependent concept defined by the implementor.

physical record

See block.

pointer data item

A data item in which the address of a data item may be stored.

predefined object reference

An implicitly generated data item referenced by one of the identifiers NULL, SELF, SELFCLASS or SUPER.

prime record key

A key whose contents uniquely identify a record within an indexed file.

procedure

A paragraph or group of logically successive paragraphs, or a section or group of logically successive sections, within the Procedure Division.

procedure branching statement

A statement that causes the explicit transfer of control to a statement other than the next executable statement in the sequence in which the statements are written. The procedure branching statements are: CALL, EXIT, EXIT METHOD, EXIT PROGRAM, GO TO, GOBACK, INVOKE, MERGE (with the OUTPUT PROCEDURE phrase), PERFORM, and SORT (with the INPUT PROCEDURE or OUTPUT PROCEDURE phrase).

procedure-name

A user-defined word that names a paragraph or section in the Procedure Division.

procedure-pointer data item

A data item in which the address of a program may be stored.

program declaration

A source program that merely declares how the program is to be called, a call prototype. Unlike a program definition, it does not include any executable procedures. See call prototype.

program definition

A source program that defines how a program is to execute by procedures specified in a Procedure Division. A traditional COBOL program, as distinct from a program declaration.

program-name

A user-defined word that identifies a COBOL source program.

program prototype definition

A definition that specifies the rules governing the class of the parameters expected to be received by a particular subprogram, and any other requirements needed to transfer control to and get control and return information from that subprogram.

prompt character

The character used to mark empty character positions in a screen item.

property

See object property.

pseudo-text

A sequence of text-words, comment lines, or the separator space in a source text or a COBOL library bounded by, but not including, pseudo-text delimiters.

pseudo-text delimiter

Two contiguous equal sign (=) characters used to delimit pseudo-text.

punctuation character

A character that belongs to the following set:

Character Meaning
, Comma
; Semicolon
. Period
" Quotation mark
( Left parenthesis
) Right parenthesis
Space
= Equal sign in pseudo-text delimiters
' Apostrophe
: Colon
& Ampersand

Q

qualified data-name

An identifier that is composed of a data-name followed by one or more sets of either of the connectives OF and IN, followed by a data-name qualifier.

qualifier
  1. A data-name or name associated with a level indicator that is used in a reference either together with a data-name of an item that is subordinate to the qualifier or together with a condition-name.
  2. A section-name which is used in a reference together with a paragraph-name specified in that section.
  3. A library-name which is used in a reference together with a text-name associated with that library.

R

radix

In positional representation of numeric values, that positive integer by which the significance of a digit place must be multiplied to give the significance of the next higher digit position.

random access

An access mode in which the programmer-specified value of a key data item identifies the logical record that is obtained from, deleted from or placed into a relative or indexed file.

receiving item

A data item referenced in a TO or USING phrase in a PICTURE clause in the Screen Section.

record

See logical record.

record area

A storage area allocated for the purpose of processing the record described in a record description entry in the File Section.

record description entry

The total set of data description entries associated with a particular record.

record key

A key, either the prime record key or an alternate record key, whose contents identify a record within an indexed file.

record lock

An indicator that is associated with a specific record in a file and is set and released by the locking facility. It is used to determine whether multiple file connectors may access the record concurrently.

record locking

The controlling of record access for shared files in which a record lock prevents access to the associated record from other file connectors.

record-name

A user-defined word that names a record described in a record description entry in the Data Division.

record number

The ordinal number of a record in a file whose organization is sequential.

reel (unit, volume)

A discrete portion of a storage medium that contains part of a file, all of a file, or any number of files.

reference-format

A format that provides a standard method for describing source text and library text.

reference modification

A definition of a data item by specifying a leftmost character and length for the data item.

reference-modifier

An identifier that references a unique data item created by specifying an identifier, a starting position and a length.

relation

See relational operator.

relation character

A character that belongs to the following set:

Character Meaning
> Greater than
< Less than
= Equal to
>= Greater than or equal to
<= Less than or equal to
< > Unequal to
relation condition

A proposition, for which a truth value can be determined, that the value of an arithmetic expression, data item, literal or index has a specific relationship to the value of another arithmetic expression, data item, literal or index.

relational operator

A reserved word, a relation character, a group of consecutive reserved words, or a group of consecutive reserved words and relation characters used in the construction of a relation condition. The permissible operators and their meanings are:

Relational Operator | Meaning
IS [NOT] GREATER THAN IS [NOT] > | Greater than or not greater than
IS [NOT] LESS THAN IS [NOT] < | Less than or not less than
IS [NOT] EQUAL TO IS [NOT] = | Equal to or not equal to
IS GREATER THAN OR EQUAL TO IS >= | Greater than or equal to
IS LESS THAN OR EQUAL TO IS <= | Less than or equal to
IS UNEQUAL TO IS < > | Not equal to
EQUALS | Equal to
EXCEEDS | Greater than
relative file

A file with relative organization.

relative key

A key whose contents identify a logical record in a relative file.

relative organization

The permanent logical file structure in which each record is uniquely identified by an integer value greater than zero, which specifies the record's logical ordinal position in the file.

relative record number

The ordinal number of a record in a file whose organization is relative.

repository

Implementor-provided storage for information relating to class names, method names, method parameters, and any other information that the implementor requires.

Repository paragraph

A paragraph in the Configuration Section of the Environment Divisison that allows specification of program prototype names, function prototype names, property-names, class names, and interface names that may be used within the scope of that Environment Division. It also allows declaration of intrinsic-function-names that may be used without specifying the word FUNCTION.

reserved word

A COBOL word specified in the list of words which can be used in COBOL, but which must not appear as a user-defined word or a system-name.

resultant identifier

A user-defined data item that is to contain the result of an arithmetic operation.

root class

A class with no superclass.

routine-name

A user-defined word that identifies a procedure written in a language other than COBOL.

run time

The time at which the code produced by your COBOL system is executed.

runtime system (RTS)

The software that interprets the code produced by your COBOL system and enables it to be executed by providing interfaces to the operating system.

run unit

One or more runtime modules that interact with one another and that function, at execution time, as an entity to provide problem solutions.

runtime element

The executable unit resulting from compiling a source element, which may be a function, method or a program.

runtime module

The result of compiling a compilation unit.

S

screen description entry

An entry in the Screen Section of the Data Division that is composed of a level number, followed by an optional screen-name, and then by a set of screen clauses as required. This entry is very similar in structure to a data description entry, but while a data description entry declares areas in memory, a screen description entry declares areas on the screen.

screen item

A field on the screen to which the screen description entry assigns properties.

screen-name

A user-defined word that names a screen item described in a screen description entry.

screen record

A screen description entry with a level-number of 1.

Screen Section

A section in the Data Division in which the layouts of the screen areas accessed in Format 4 of the ACCEPT and Format 2 of the DISPLAY statements are defined.

section

A set of zero, one, or more paragraphs or entries, called a section body, the first of which is preceded by a section header. Each section consists of the section header and the related section body.

section header

A combination of words followed by a period and a space that indicates the beginning of a section in the Environment, Data and Procedure Divisions.

section-name

A user-defined word which names a section in the Procedure Division.

segment-number

A user-defined word which classifies sections in the Procedure Division for purposes of segmentation. Segment-numbers can contain only the characters "0" through "9". A segment-number can be expressed either as a one- or two-digit number.

sending item

A data item referenced in a FROM or USING phrase in a PICTURE clause in the Screen Section.

sentence

A sequence of one or more statements, the last of which is terminated by a period followed by a space.

separate program

A program, together with its contained programs, that is not contained in another program.

separator

A character or two contiguous characters used to delimit character-strings.

sequential access

An access mode in which logical records are obtained from or placed into a file in a consecutive predecessor-to-successor logical record sequence determined by the order of records in the file.

sequential file

A file with sequential organization.

sequential organization

The permanent logical file structure in which a record is identified by a predecessor-successor relationship established when the record is placed into the file.

shared file

A file for which file sharing has been specified.

sharing mode

The state of an open file connector that indicates the mode of file sharing. The sharing modes are: sharing with all other, sharing with no other, and sharing with read only.

sign condition

The proposition, for which a truth value can be determined, that the algebraic value of a data item or an arithmetic expression is less than, greater than, or equal to zero.

signature

The information stored about a source unit in the external repository.

significand

In floating-point representation, the fixed-point numeral that represents the significant digits of the number.

simple condition

Any of the following:

relation condition class condition switch-status condition condition-name condition sign condition (simple-condition)

sort file

A collection of records to be sorted by a SORT statement. The sort file is created and can be used by the sort function only.

sort-merge file description entry

A Data Division entry that specifies the characteristics of a sort or merge file.

source element

A source unit excluding any nested source units.

source text manipulation statement

A statement beginning with the word COPY or the word REPLACE that provides the capability to insert and replace source text during compilation.

source unit

A sequence of statements beginning with an Identification Division and finishing with an end marker or the end of the compilation group, including any contained source units.

special character

A character that belongs to the following set:

Character Meaning
+ Plus sign
- Minus sign
* Asterisk
/ Slash (virgule, stroke)
= Equal sign
$ Currency sign
, Comma (decimal point)
; Semicolon
. Period (decimal point)
' Quotation mark
( Left parenthesis
) Right parenthesis
> Greater than symbol
< Less than symbol
' Apostrophe
: Colon
& Ampersand
special-character word

A reserved word that is composed entirely of special characters.

Special-Names

The name of an Environment Division paragraph in which implementor-names are related to user-specified mnemonic-names.

special registers

Storage areas created by your COBOL system whose primary use is to store information produced in conjunction with the use of specific COBOL features.

split key

A concatenation of one or more data items within a record associated with that file-name. It can be referenced only in START and READ statements. See the chapter Examples for an example of Split Key.

standard data format

A concept used to describe data in a COBOL Data Division whereby the characteristics or properties of the data are expressed in terms of the appearance of graphic characters on a printed page, rather than the manner in which the data is stored internally in the computer or on a particular external medium.

statement

A syntactically valid combination of words and symbols written in the Procedure Division beginning with a verb.

static data

The data described in the File or Working-Storage Section of a source element that is not an initial program.

static data item

A data item that is described as part of a static data record.

static data record

A logical record described in the File or Working-Storage Section of a source element that is not an initial program.

subclass

A class that inherits from another class. When two classes in an inheritance relationship are considered together, the subclass is the inheritor or inheriting class; the superclass is the inheritee or inherited class.

In the industry literature, the term derived class is also often used as an alternative to the term subclass. These terms are equivalent

subject of entry

The data item that is being defined by a data description entry.

subprogram

See called program.

subscript

An occurrence number represented by either an integer, a data-name optionally followed by an integer with the operator + or -, or an index-name optionally followed by an integer with the operator + or -, that identifies a particular element in a table. A subscript can be the word ALL when the subscripted identifier is used as a function argument.

subscripted data-name

An identifier that is composed of a data-name followed by one or more subscripts enclosed in parentheses.

superclass

A class that is inherited by another class. See also subclass.

switch-status condition

The proposition, for which a truth value can be determined, that an implementor-defined switch, capable of being set to an "on" or "off" status, has been set to a specified status.

symbolic-character

A user-defined word that specifies a user-defined figurative constant.

syntax

The order in which elements must be put together to form a compilation group.

system-directing statement

A statement, beginning with a directing verb, that causes your COBOL system to take a specific action during creation of the intermediate code.

system-name

A COBOL word which is used to communicate with the operating environment.

T

table

A set of logically consecutive items of data that are defined in the Data Division by means of the OCCURS clause.

table element

A data item that belongs to the set of items in a table.

terminal

A character-addressable device that includes a display and a keyboard.

termination key

Any function key or the enter key of a terminal.

text-name

A user-defined word which identifies library text.

text-word

A character or a sequence of contiguous characters between margin A and margin R in a COBOL library, source text, or in pseudo-text which is:

  1. A separator, except for: space; a pseudo text delimiter; and the opening and closing delimiters for nonnumeric literals. The right-parenthesis and left-parenthesis characters, regardless of context within the library, source text, or pseudo-text, are always considered text-words.
  2. A literal including, in the case of nonnumeric literals, the opening quotation mark and the closing quotation mark which bound the literal.
  3. Any other sequence of contiguous COBOL characters except comment lines and the word "COPY", bounded by separators, which is neither a separator nor a literal. One or both of the bounding separators can be a pseudo-text delimiter.
truth value

The representation of the result of the evaluation of a condition in terms of one of two values:

true false

typedef-name

A user-defined word which identifies a type definition.

type definition

A programmer-defined type or USAGE that may be used to define data items of that type. A type definition is defined in a data description entry that includes the TYPEDEF clause. The type contains all the characteristics of a data item and its subordinates.

U

unit

See reel.

universal object reference

An object reference that is not restricted to a specific class or interface.

unsuccessful execution

The attempted execution of a statement that does not result in the execution of all the operations specified by that statement.

update field

A screen item whose description contains a USING phrase.

user-defined word

A COBOL word supplied by the user to satisfy the format of a clause or statement.

V

variable

A data item whose value can be changed at run time.

variable-length record

A record associated with a file whose file description or sort-merge description entry permits records to contain a varying number of character positions.

variable-occurrence data item

A table element that is repeated a variable number of times. Such an item contains an OCCURS clause with the DEPENDING phrase in its data description entry or is subordinate to such an item.

verb

A word that expresses an action to be taken during creation of native code or at run time.

volume

See reel..

W

word

A character-string of not more than 30 characters which forms a user-defined word, a system-name, a reserved word, or an intrinsic-function-name.

Working-Storage Section

The section of the Data Division that describes working storage data items, composed either of noncontiguous items or of working storage records, or of both.

Z

zero-length group item

An item whose minimum length is zero and whose length at execution time is zero. A zero-length group item can result from one of the following:

  • A group data item containing only a variable-occurrence data item in which the minimum number of occurrences is zero.
  • A group data item containing only a subordinate zero-length group item.
  • A record that has been specified using format 2 or format 3 of the RECORD clause in which the minimum number of character positions is zero.
  • A function that returns a zero-length item.
Parent topic: Part 4: Appendices


Language References

  • COBOL Language Reference Guide
  • .NET and JVM COBOL Reference Guide
Parent topic: General Reference


Command line reference

A range of command line utilities and interfaces are available for creating, building, debugging and running COBOL applications.

Important:

If you installed Visual COBOL in a directory other than the default location, which is /opt/microfocus/VisualCOBOL, you must run the following script before you can use the command line tools:

. <product-install-dir>/bin/cobsetenv

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

  • Setting Directives
  • Compiling and Linking from the Command Line
  • Converting Header Files Using the H2cpy Utility
  • Running an Application from the Command Line
  • Enhanced ACCEPT/DISPLAY Syntax
  • Configuring Enhanced ACCEPT and DISPLAY
  • Keyboard Configuration Utility (Keybcf)
  • Profiler
    Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.
  • Test Coverage (Native COBOL)
  • The cobutf8 Utility
    Use the cobutf8 utility to handle non-UTF-8 data in your COBOL applications when running under a UTF-8 locale.
Parent topic: General Reference


Setting Directives

You use directives to control the way the Compiler behaves: what output it produces, what code is compiled and how the compiled code behaves when it runs.

You can specify Compiler directives in a number of other ways, such as on the command line, or in a directives file.

  • The Order in which Compiler Directives are Processed
    Compiler directives can be specified using more than one method. During compilation, they are processed in a particular order according to the method in which they have been specified.
  • System-wide Directives File, cobol.dir
    Use a system-wide directives file if you want to permanently override the default value of a directive.
  • $SET Statements in the Source Code
    Use $SET statements if your program is affected by particular circumstances that none of the other programs in an application needs.
  • User Directives File
    Use this file when you have a set of directives that you always want to use together.
Parent topic: Command line reference


The Order in which Compiler Directives are Processed

Compiler directives can be specified using more than one method. During compilation, they are processed in a particular order according to the method in which they have been specified.

The Compiler processes directives specified on the command line from left to right. If a directive appears more than once, the Compiler uses the setting that it processed last for that directive.

The Compiler processes directives in the following order:

  1. Directives contained within the system-wide directives file cobol.dir.
    Note: If NOCOBOLDIR is set anywhere, the directives in this file are not processed.
  2. On the command line, system default directives contained in cob options in the file $COBDIR/etc/cobopt .
  3. On the command line, user default directives contained in cob options in the environment variable COBOPT .
  4. Directives set via the $SET statement within the source code.

    In addition, you can set directives in a user directives file, which you specify with the USE directive; these are processed when they are encountered.

The above order means that, for example, a directive set using a $SET statement would override the setting for that directive that has been set in the project properties.

Parent topic: Setting Directives
Related information
System-wide Directives File, cobol.dir
$SET Statements in the Source Code
User Directives File


System-wide Directives File, cobol.dir

Use a system-wide directives file if you want to permanently override the default value of a directive.

To override one or more directives, create a flat system-wide directives file named cobol.dir, and list the directives in the file: specify each directive either on a separate line, or on the same line, delimited by a space, colon or semicolon. Place cobol.dir in the etc sub-directory of the location specified by the COBDIR environment variable.

Note: If the COBDIR environment variable is not set then the COBOL system acts as if it had been set to the default COBOL system directory.

The Compiler automatically processes the directives in the system-wide directives file. Firstly, it looks for a cobol.dir file in the current directory, and then in the $COBDIR/etc directory.

Compilation terminates if the Compiler rejects a directive specified on the command line or in a directives file. Therefore, whenever you create or change a cobol.dir file, run a trial compilation and watch for "Rejected" messages at the beginning when the directives are processed.

Parent topic: Setting Directives
Related information
The Order in which Compiler Directives are Processed
$SET Statements in the Source Code
User Directives File


$SET Statements in the Source Code

Use $SET statements if your program is affected by particular circumstances that none of the other programs in an application needs.

Syntax

$SET directive["parameter"] ...

where the parameters are:

directive
A Compiler directive whose phase is identified as "syntax check". It cannot be a generate phase directive. Multiple directives must be separated by spaces.
parameter
A qualifier to directive. It must appear in one of the following forms:
  • "parameter" - can contain spaces
  • (parameter) - cannot contain spaces

parameter must not be preceded with an equals sign (=)

Rules:

  • The $ character must be in column 7.
  • $SET statements must not be terminated with a period (.).
  • $SET statements cannot be continued onto a new line, but it can be followed by additional $SET statements.
  • Some directives must be set at the start of the program; these are known as initial $SET statements. They can precede or follow other $SET statements, but must come before any other statements.
  • When a directive is specified on a statement after the initial $SET statements, the directive affects compilation from that point onwards.
  • Dialect-controlling directives must be on an initial $SET statement. Once you have set a dialect, you cannot unset it later in the program.

Example

If your program requires a specific currency symbol that none of your other programs need, start the program with the line:

$set currency-sign"157"
Parent topic: Setting Directives
Related information
The Order in which Compiler Directives are Processed
System-wide Directives File, cobol.dir
User Directives File


User Directives File

Use this file when you have a set of directives that you always want to use together.

The user directives file is an ASCII text file, which defines a set of directives to pass to the Compiler altogether at the same time. You use either the DIRECTIVES or USE Compiler directives to pass this file to the Compiler.

For example, to migrate some programs from a different dialect, put the directives you need to get compatibility with this dialect into a directives file, which you could call myDialectDirectives.dir. Specify each directive either on a separate line, or on the same line, delimited by a space, colon or semicolon.

To use this file when compiling, use the USE or DIRECTIVES directive either in the project's properties in the IDE or in a $SET statement in your program. For example

USE"myDialectDirectives.dir"

The directives file is searched for in the current and COBOL system directories. If no extension is specified, a file extension of .dir is added before the search is made. If no file is found, the search is repeated with no extension.

You can also use an environment variable as a parameter in either USE or DIRECTIVES:
DIRECTIVES"$mydirs"
When the environment variable mydirs is set to the path of your user directives file, it is resolved at compile time when you compile from the command line.

The Compiler processes the directives in the file as if they replace the USE or DIRECTIVES directive. Consequently, the restrictions applying to a directive at that time also apply to the directives read from the file at that time. Also any directives set later override the directives in your directives file

You can specify another directives file within the original directives file. The Compiler switches to the new directives file for processing and then returns to the original directives file. When the Compiler finishes processing the directives file, it then processes subsequent directives on the command line or in $SET statements.

Parent topic: Setting Directives
Related concepts
Specifying an SQL Preprocessor and Compiler Directive Options
Setting the COBSQL Preprocessor and Compiler Directive Options
Setting the DB2 ECM Preprocessor and Compiler Directive Options
Setting the OpenESQL Preprocessor and Compiler Directive Options
Related information
The Order in which Compiler Directives are Processed
System-wide Directives File, cobol.dir
$SET Statements in the Source Code


Compiling and Linking from the Command Line

In addition to using your COBOL development environment to compile and link, you can use command line utilities.

  • Introduction to the cob command
  • cob (cob32 or cob64) Command
  • cob Options Syntax
  • cob Option Processing and Search Order
  • cobopt File
  • COBOPT Environment Variable
  • The cobmode Utility
    Run the cobmode utility from the command line to set the global effective working mode or view the current mode in effect for your session.
  • Creating Different Types of Files
  • cob Flags
  • cob Error Messages
  • cob Command Examples
Parent topic: Command line reference


Introduction to the cob command

The cob command enables you to produce executable files of the following types:

Intermediate code

.int files are dynamically loadable, and don't need to be linked into a system executable.

Generated code

.gnt files are dynamically loadable, and don't need to be linked into a system executable.

Callable shared object files
These files are dynamically loadable, and don't need to be linked into a system executable.
Shared library files
These are system linkable files that can be linked into executable files. They cannot be directly executed themselves.
System executable files
These files are directly executable. They are loaded by the operating system, which creates a new process in which to run them.

The cob command provides the interface between your COBOL source program and the following COBOL system components:

  • The Compiler - to syntax check and compile your COBOL source files into intermediate (.int) code files, and to generate the .int files into generated (.gnt) or object (.o) code files
  • The system linker - to link object code into a callable shared object, shared library or system executable file

It also provides an interface to the C++ compiler, cc (the C compiler) and as (the Assembler).

If the source code to be compiled contains characters beyond the standard 7-bit ASCII character set (for example, accented characters or characters belonging to multi-byte character sets), you must ensure that the locale has been set correctly, to match the source encoding of these characters. This means setting LANG, LC_CTYPE, or LC_ALL appropriately; each of these variables takes precedence over the former.

Parent topic: Compiling and Linking from the Command Line


cob (cob32 or cob64) Command

To invoke the Cob utility, enter the following from a UNIX system command prompt:

cob-command [options|filename] ...

Where:

cob-command
The version of the Cob utility to run, which can be:
cob
Executes the 32-bit or 64-bit version of the Cob utility depending on your effective working mode.

Your effective working mode is determined by the COBMODE environment variable, global settings or, if none of these is set, the default (64-bit). To show the effective working mode, enter cobmode at the command line without any arguments.

cob32
Executes the 32-bit version of the Cob utility.
cob64
Executes the 64-bit version of the Cob utility.
options
Either one cob option or a group of cob options comprising one or more cob flags.
filename
The name of an input file. These files can be any mixture of COBOL source code (.cbl, .CBL or .cob), intermediate code (.int), linkable object code (.o or .so), C source (.c), C++ source (.C), Assembler source (.s), or archive (.a) files.

The cob command assumes that any unrecognized options are either input files or valid linker options to be saved and used at link time. In this way, any archive files you supply to the cob command are passed to the linker, which pulls out only the referenced files from the archive.

Example

cob -xve "" -o my_rts -C xopen prog.cbl prog2.c

The above command passes the XOPEN directive to the Compiler and instructs cob to compile the COBOL source file prog.cbl and the C source file prog2.c and to link the result into a system executable file named my_rts that, when run, expects the name of the program to run to be given on its own command line. The cob utility also gives verbose notification of its progress.

The above command assumes that neither the file $COBDIR/etc/cobopt nor the COBOPT environment variable exist.

Parent topic: Compiling and Linking from the Command Line
Related concepts
COBSQL
Related information
cob Options Syntax


cob Options Syntax

A cob option takes the form:

 flag-intro flag-letter [parameter]
 flag-intro flag-letter[flag-letter]... [parameter]

where the parameters are:

flag-intro
The hyphen (-) or the plus (+) character. flag-intro must be preceded by a space character. There must be no spaces between flag-intro and flag-letter.
flag-letter
A letter (or occasionally letters) indicating cob flag that defines the action required. There must be no spaces between flag-intro and flag-letter or between two adjacent flag-letters. There can be any number of spaces, or none space between the last flag-letter and the parameter if it is present. For example -xve "" in which "" represents a null parameter.
parameter
An optional string of characters that details exactly how the flagged option is to behave. Where a group of cob options are specified, the parameter applies to the last option. The parameter cannot contain a space or tab character unless that character is contained in single (') or double (") quotation marks. A parameter enclosed in a pair of quotation marks must not exceed 255 characters.

Parameters to directives given on the cob command line or in a directives file retain their case, but parameters to directives given in a $SET statement are converted to upper case.

You might need to set options as a system or user default and then to unset them again in specific instances. By specifying a hyphen after the flag letter with no intervening space, you can unset the following options: -c, -P and -U.

Special Characters

Options specified on the cob command line pass through the UNIX shell, which preprocesses certain characters such as space, asterisk (*), parentheses (), single (') and double (") quotation marks. To pass these special characters unchanged as part of an option, you must escape the shell processing, as follows:

  • Under the UNIX shell, precede the character with a backslash (\) or enclose it in a pair of single or double quotation marks.
  • Use the syntax mode=setting in place of the backslash or quotation marks. Ths is converted into the form "mode(setting)".

    To pass an equals sign (=) to the COBOL components, use two equals signs together (==).

The cob command treats single and double quotation marks in an option in the same way, regardless of whether the option is specified on the command line or in the cobopt file or COBOPT environment variable.

Parent topic: Compiling and Linking from the Command Line
Related information
cob Flags


cob Option Processing and Search Order

The cob command processes options from left to right. In general, if an option appears more than once, cob uses the setting that it processed last for that option. Some options, such as -C and -N that take Compiler directives, are cumulative.

You can specify cob options in a number of ways, and the method used determines the order in which cob processes them. The cob command searches for options in the following sequence:

  1. System default options in the file $COBDIR/etc/cobopt. This is the file the cob command reads when first invoked.

    The contents of the file $COBDIR/etc/cobopt affect the operation of COBOL for all users using the same $COBDIR; you should alter the file only after careful consideration of the implications.

  2. User default options in the environment variable COBOPT.
  3. Execution-time options on the cob command line.

Example

The file $COBDIR/etc/cobopt contains:

-U -P -C "ans85 noalter warning=1"

The cob command line specifies:

cob -xU -C alter -C warning=2 prog.cbl

In the above example, the cob command passes the COBOL source file prog.cbl to the Compiler with the final directive settings of ANS85 ALTER LIST"prog.lst" WARNING"2". An executable program prog is built, with any unresolved symbols being dynamically loaded at run time and flagged as missing at link time.

Parent topic: Compiling and Linking from the Command Line


cobopt File

System-wide default options are defined in the file $COBDIR/etc/cobopt. This is the file the cob command reads when first invoked. Each line of this text file corresponds to one of the following formats:

[set environment-variable=value]
[options] ...
[cobextn: .ext [.ext] ... ]

where the parameters are:

environment-variable
Any one of the environment variables supported by the COBOL system.
value
The value to which to set the environment variable.
options
Either one cob option or a group of cob options comprising one or more cob flags.
.ext
A filename extension that, in addition to the standard ones of .cob, .cbl, or .CBL, denotes a file that cob should treat as a COBOL source file. The extension must begin with a period, and if more than one is specified on one line they must be separated by a space or tab character. You can use more than one cobextn line.

If a line does not begin with set or cobextn:, it is taken as an options line.

Note:

The contents of the file $COBDIR/etc/cobopt affect the operation of COBOL for all users using the same $COBDIR; you should alter the file only after careful consideration of the implications.

Example

The $COBDIR/etc/cobopt file contains:

cobextn: .AD  .FD
-N "nobound" -C ans85

The cob command line specifies:

cob -u a.FD b.AD

In the above example, the cob command passes the COBOL source files a.FD and b.AD to the syntax-check phase of the Compiler to be translated, under the ANS85 directive, into intermediate code. The intermediate code is then passed in turn to the Compiler's generate phase to be translated, under the NOBOUND directive, into generated code.

Parent topic: Compiling and Linking from the Command Line
Related information
cob Options Syntax


COBOPT Environment Variable

The COBOPT environment variable defines the options for the cob command. COBOPT contains options that either supplement or override the system default options defined in $COBDIR/etc/cobopt. COBOPT can also specify the path of a file that contains such options.

The COBOPT definition takes the same form as in the $COBDIR/etc/cobopt file. For example, the following COBOPT definition passes the directives COPYEXT"CPY,cpy" and NOOPTIONAL-FILE to the Compiler's syntax-check phase and the NOBOUND directive to the Compiler's generate phase:

COBOPT='-C "copyext=CPY,cpy nooptional-file" -N "nobound"'

COBOPT can be set to a value that includes several lines by enclosing the entire value in single (') or double (") quotation marks. Under the Bourne shell, the Enter key can be typed to indicate the line-break. Other types of shell might need a different way of showing the line-break. For example:

COBOPT="set COBCPY=/usr/lib/cblcpy:$COBDIR/cpylib:$HOME/mylib::
-N nobound -C \"ans85 noalter list\"
cobextn: .AD .FD"
export COBOPT

The above example:

  • Sets the environment variable COBCPY for the duration of the cob command
  • Passes the directives ANS85 NOALTER LIST to the Compiler's syntax-check phase
  • Passes the directive NOBOUND to the Compiler's generate phase
  • Note that $COBDIR and $HOME get expanded by the shell if the double quotation marks are used but not if single quotation marks are used.

You can include any valid cob command line in the COBOPT environment variable. If the line includes the -v cob flag, the whole line is echoed to the screen when it is passed to cob.

Parent topic: Compiling and Linking from the Command Line
Related information
cobopt File
cob Flags


The cobmode Utility

Run the cobmode utility from the command line to set the global effective working mode or view the current mode in effect for your session.

The effective working mode determines your ability to compile and run 32- and 64-bit applications. Using the effective working mode in conjunction with the generic cob and cobrun commands has the same effect as using one of the bit-specific commands (for example, cob32 or cobrun64).

The cobmode utility enables you to set the global effective working mode, which affects all users that currently point the $COBDIR variable at the same location. Local effective working mode, which is set using the COBMODE environment variable, only affects your current session. If both modes are set, the local effective working mode is used.

The cobmode utility, and the need to set the effective working mode, is only available if your system is capable of developing or running both 32-bit and 64-bit applications. If it is capable and the effective working mode is not set, effective working mode defaults to 64-bit.

  • Setting the Effective Working Mode
    Set the local or global effective working mode, using the COBMODE environment variable or the cobmode command line utility.
  • Displaying the Effective Working Mode
    Display the current effective working mode for your session.
Parent topic: Compiling and Linking from the Command Line
Related reference
cobrun Command
Using the Java/COBOL Application Launcher from the Command Line


Setting the Effective Working Mode

To set the global effective working mode:

cobmode -s version

where version can be 32 or 64. For example, to set the global working mode to 64-bit:

cobmode -s 64

To set the local effective working mode, set the $COBMODE environment variable:

COBMODE=version
export COBMODE

where version can be 32 or 64.

If both modes are set, the local effective working mode is used.

Parent topic: The cobmode Utility
Related information
Displaying the Effective Working Mode


Displaying the Effective Working Mode

To display the current effective working mode, enter:

cobmode

To display the current local effective working mode, enter:

cobmode -l

To display the current global effective working mode, enter:

cobmode -s

To display how your effective working mode is determined, enter:

cobmode -v

Example:

The following command:

cobmode -v

has determined that the local effective working mode (i.e. the COBMODE variable) is set to 32.

Determining EFFECTIVE working mode
            Determining SHELL default: Contents indicate 32-bit
Effective Default Working Mode: 32-bit
Parent topic: The cobmode Utility
Related information
Setting the Effective Working Mode


Creating Different Types of Files

  • Simple Default Linking
  • Resolving Unresolved References in System Executables
  • Creating Intermediate Code Files
  • Creating Generated Code Files
  • Callable Shared Objects
  • Self-Contained Callable Shared Objects
  • Creating Executables that Use Library Files
  • Creating Shared Libraries
  • Creating an Executable Run-time System (RTS)
  • Creating Executables that Use the Dynamic Loader
  • Creating Dynamically Loadable Files
Parent topic: Compiling and Linking from the Command Line


Simple Default Linking

You can create a system executable application file by specifying the -x flag to the cob command, together with a list of the application files that you want included in the system executable file. The application files can include COBOL, C or C++ source files, .int files or any type of .o object files. The name of the system executable file is the basename of the first application file in the list unless you specify another name by using the -o flag.

For example, the following command, compiles the program myprog.cbl to native object code and links it with the run-time support routines to produce a system executable myprog. The program can then be run by entering the name of the system executable at the command line.

cob -x myprog.cbl

If the current directory is not set in your PATH environment variable, you can run the program with a command:

./myprog

If your application contains several programs, then all the programs can be linked together. For example, the following command converts myprog.cbl and mysub.int to native object code, compiles the C source file csub.c to an object file, links them together with the COBOL run-time support routines and creates a system executable file myapp. The -v flag causes cob to give informational messages on its progress.

cob -xv myprog.cbl mysub.int csub.c -o myapp

If your application contains code written in C++ then the -x,CC cob flag should be used so that the C++ compiler (and not the system linker) creates the final system executable. For example, the following command creates the system executable myapp using the COBOL programs myprog.cbl and mysub.int, the C source file csub.c and the C++ source file cppsub.c.

cob -x,CC myprog.cbl mysub.int csub.c cppsub.C -o myapp

The default initial entry point of a system executable application file is the basename of the first program name on the command line, such as myprog in the previous example. If your application requires a different initial entry point, use the cob -e flag. For example, the following command specifies myentry as the initial entry point.

cob -xo myapp myprog.cbl subprog.o -e myentry
Parent topic: Creating Different Types of Files


Resolving Unresolved References in System Executables

If you use COBOL syntax of the following form, a direct reference is produced to literal.

CALL "literal"

If you create a system executable, any such references are tightly bound only if an entry point literal is provided when the program is linked. If no entry point literal is available, the reference to literal is unresolved and a link error is produced.

Unresolved references can be resolved by using cob -d symb. This causes the system executable to be built in a way that enables symb to be dynamically loaded at run-time.

For example, the following command resolves the reference to myref in one of the specified COBOL programs. When myref is called at run-time the dynamic loader is invoked to search for and load the call to myref.

cob -x myprog.cbl subprog.cbl -d myref

If there are several unresolved references you can resolve them all at once using the cob -U option. For example, the following command creates myprog, resolving any (and all) unresolved references.

cob -x myprog.cbl subprog.cbl -U
Parent topic: Creating Different Types of Files


Callable Shared Objects

  • Creating Callable Shared Objects
  • Entry Points
  • Resolving Unresolved References in Callable Shared Objects
  • Advanced Uses
Parent topic: Creating Different Types of Files


Creating Callable Shared Objects

To create a callable shared object, use the cob -z command.

For example, the following command creates the callable shared object myprog.so.

cob -z myprog.cbl

If this is the main (or only) module of an application it can be run using the following command:

cobrun myprog

Alternatively, if myprog is a subprogram, it can be loaded and run using the COBOL CALL syntax, such as CALL "myprog", and canceled and unloaded using the following command:

CANCEL "myprog".
Parent topic: Callable Shared Objects


Entry Points

Several COBOL programs can be combined into a single callable shared object. This has the advantage that any references between the COBOL programs can be resolved using direct references without having to use the dynamic loader to search for and then load another module. For example, the following command, compiles all the COBOL programs and links them together, creating myprog.so. The main entry point is myprog, which is the main entry point of the first COBOL program specified, myprog.cbl.

cob -z myprog.cbl subprog.cbl entry.cbl

The name of the created callable shared object can be specified with the -o cob flag. For example, the following command compiles all the COBOL programs and links them together, creating entry.so. Here, the basename of the callable shared object entry is used as the main entry point; entry is the main entry point of entry.cbl.

cob -zo entry.so myprog.cbl subprog.cbl entry.cbl

The entry point can also be specified with the -e cob option. This is useful if your application name is not the same as your source program filenames. For example, the following command compiles all the COBOL programs and links them together, creating myapp.so. The main entry point is specified as entry, which is the main entry point of entry.cbl. Any entry point in any of the COBOL programs could be specified with the -e option.

cob -zo myapp.so myprog.cbl subprog.cbl entry.cbl -e entry

If no -e option is specified then the basename of the callable shared object is used as the main entry point. If the main entry point cannot be found at run time, the callable shared object cannot be loaded and a run-time load error results.

Parent topic: Callable Shared Objects
Related information
cob Flags


Resolving Unresolved References in Callable Shared Objects

For programs compiled with the LITLINK Compiler directive, calls made using the COBOL syntax CALL "literal" produce a direct reference to literal. Any such references are tightly bound to any entry point of the same name, that is defined in a program specified on the cob line, when creating a callable shared object. Any direct reference to a name that does not have a corresponding entry point name, in any program specified when creating a callable shared object, is called an unresolved reference.

When a callable shared object is loaded at run time any unresolved references are resolved by the operating system dynamic linker using symbols in the system executable file, loaded shared libraries and any loaded callable shared objects. If any symbol remains unresolved then the callable shared object cannot be loaded and a load error results. On some platforms, one or any of the unresolved symbol names might also be listed.

To prevent a load error all unresolved references must be resolved when the callable shared object is created. This can be done using the -d or -U cob options.

If the name of an unresolved reference is known it can be resolved using the -d option. For example, the following command resolves reference to myref in one of the specified COBOL programs. When called at run time myref is dynamically loaded using the standard search rules that first look at the currently loaded entry points and then, if myref cannot be found, search for myref on disk (for example, for myref.so).

cob -z myprog.cbl subprog.cbl entry.cbl -d myref

To get a list of all unresolved references when you create the callable shared object, you can use the -z,U cob option. For example, the following command creates myprog.so and lists any unresolved references.

cob -z,U myprog.cbl subprog.cbl entry.cbl

You can then add -d cob options to resolve the references. You do not need to use -d options for any symbols that you know will be linked into the calling system executable (if not using cobrun or cobrun_t), or which are defined in callable shared objects that you know will have been already loaded.

If you want to resolve all unresolved references then you can use the -U cob option. For example, the following command creates myprog.so resolving any (and all) unresolved references.

cob -z myprog.cbl subprog.cbl entry.cbl -U
Parent topic: Callable Shared Objects
Related reference
Produce a Callable Shared Object for COBOL Applications (-z[,U][,CC])


Advanced Uses

The cob -z option accepts .int files and system object (.o) files as input, as well as recognized source code programs. Hence, C and C++ source and/or object code can be linked into a callable shared object.

For example, the following command creates myapp.so using the COBOL programs mycobol.cbl and myint.int, the C source code myc.c, and an object file myobj.o. The object file could be COBOL, C, C++ or some other language or third party system object file. The main entry point is specified as myentry which could be in any of the specified modules.

cob -zo myapp.so mycobol.cbl myint.int myc.c myobj.o
    -e myentry

When creating callable shared objects that contain C++, the -z,CC option should be used so that the C++ compiler creates the final callable shared object. For example, the following command creates myapp.so using the COBOL program mycobol.cbl, the C source code myc.c, and a C++ source file mycpp.C. The main entry point is specified as myentry which could be in any of the specified modules.

cob -z,CC -o myapp.so mycobol.cbl myc.c mycpp.C -e myentry

A shared library can be linked into a callable shared library using the -l and -L cob options. The shared library will be loaded when the callable shared object is loaded and unloaded when the callable shared object is unloaded. For example, the following command creates a shared library libmylib.so and then links it into myapp.so. When myapp.so is loaded at run time the operating system searches for and loads the shared library libmylib.so.

cob -Z mylib.cbl myobj.o
cob -zo myapp.so myprog.cbl myc.c -L. -lmylib -e myentry

A callable shared object does not need to contain COBOL and so could contain just C or C++ or objects supplied by a third party.

C, C++ or third party objects can be linked into callable shared objects or libraries. For example, you can now code your application to cope with situations in which a third party product is not installed on a machine. This is achieved by linking the third party objects and shared libraries into a callable shared object, not a system executable. You then load this callable shared object, when required, using the COBOL ON EXCEPTION syntax. If the third party product is not installed then the callable shared object will not load and the ON EXCEPTION route of your code will be taken.

Parent topic: Callable Shared Objects


Self-Contained Callable Shared Objects

A self-contained callable shared object is similar to an executable, but is designed to be loaded by non-COBOL executables. Only use this type of object when you are not able to use the cob command to relink the object to a main executable, for example, when used with third-party executables such as DB2.

You create a self-contained callable shared object using the -y cob flag:

cob -y obj1.o obj2.o obj3.o

By default, the base-name of the resulting file takes the name of the first file being linked, and has the filename extension .so; the example above results in the file obj1.so. The base-name forms the main entry point, but this can be overridden using the -e flag.

Input files can be any file type except .gnt files. If you use object module files (.o), they are linked in using the system linker (ld). You can also use the CC option to also link C++ objects into the library file. If C++ source files are specified, the C++ compiler is invoked to compile them to object code first.

To load a self-contained callable shared object, you must use the dlopen() function, as follows:

handle=dlopen("obj1.so", RTLD_GLOBAL|RTLD_NOW);
Restriction: You can only load one self-contained callable shared object into a process at any one time; the current self-contained callable shared object must be unloaded before you can load another one in the same process.
Parent topic: Creating Different Types of Files
Related reference
Produce a Self-Contained Callable Shared Object for non-COBOL Applications (-y[,U][,CC])


Creating Executables that Use Library Files

You can create a system executable application file that is linked to a shared library file or includes an archive file using the -l flag on the cob -x command line. The command line should have the following form:

cob -x filenames [-L dir] [-l name]

where the parameters are:

filenames
List of the files input to the cob command.
-L dir
Changes the order in which the system linker searches for libraries that were specified with the -l cob flag.
-l name
libname.so (or libname.a) is to be searched to resolve any references

This links all the application programs and subprograms with the specified libraries as well as the default COBOL run-time system libraries and operating system support libraries. The result is a system executable file that, when run, preloads the specified shared libraries before execution is passed to the main entry point.

When creating a system executable file, the code for any referenced modules that are held in shared libraries are not included in your system executable file. Instead, if such a module is referenced at run time, then the shared library is loaded into memory from the shared library file before control is passed to it.

The cob command uses a shared library in preference to an archive library of the same basename. If a cob flag names a library then cob assumes it is a shared library, but if no such library exists then it uses an archive library of the same name.

For example, if you specify two libraries abc and xyz on the cob command line as follows:

cob -x prog.cbl -labc -lxyz

where the libraries libxyz.so, libxyz.a and libabc.a exist, then only libxyz.so and libabc.a are scanned to resolve references and libxyz.a is ignored.

Bear in mind that a reference to a subprogram held in a shared library file creates a link to the whole library, whereas a reference to a subprogram held in an archive library only links to that subprogram. Unreferenced subprograms in a shared library file can be available to the dynamic loader; unreferenced subprograms in the archive library are not available to the dynamic loader.

Parent topic: Creating Different Types of Files
Related reference
cob Flags


Creating Shared Libraries

Shared libraries cannot be directly executed. They need to be linked into a system executable or callable shared object. A shared library name must always start with the prefix lib and have the extension .so.

By default, cob creates a shared library name of libname.so, where name is the base-name of the first application supplied to cob. For example, the following command compiles the program myprog.cbl to native object code and then links it to create a shared library libmyprog.so.

cob -Z myprog.cbl

A shared library file is not executable itself. It must be linked into a system executable using the -l flag on the cob command line. For example, the following command creates a system executable myapp that loads libmyprog.so when it is run.

cob -x myapp.o -L. -lmyprog

A shared library can be created from a combination of COBOL, C and C++ source files, .int files or any type of .o files. For example, the following command compiles the COBOL programs myprog.cbl and mysub.int to native object code, compiles the C source file mysub.c to an object file and then links them together to create the shared library libmyapp.so.

cob -Z myprog.cbl mysub.int csub.c -o libmyapp.so

If any C++ code is linked into a shared library, the cob -Z,CC flag should be used so that the C++ compiler (and not the system linker) creates the shared library file. For example, the following command: creates the shared library libmyprog.so using the COBOL programs myprog.cbl and mysub.int, the C source file csub.c, and the C++ source file cppsub.C

cob -Z,CC myprog.cbl mysub.int csub.c cppsub.C
Parent topic: Creating Different Types of Files


Creating an Executable Run-time System (RTS)

An executable RTS is a system executable file that requires the first entry point to be specified at run time. C and C++ programs can exist within callable shared objects; you do not have to create an executable RTS for this.

If you require, you can create an executable RTS using cob. For example, the following command creates an executable RTS that contains the same level of functionality as the default run-time system ($COBDIR/bin/rts32 or $COBDIR/bin/rts32_t) that also includes the C subroutines held in the file subprogs.c:

cob -xo rts.new subprogs.c -e ""

At run time the dynamically loadable program myapp could then be run with the command line:

./rts.new myapp

Specifying the cob option -e "" causes the system executable to be built so that the executable file's entry point must be specified at run time.

Parent topic: Creating Different Types of Files
Related concepts
Callable Shared Objects
Related reference
cob Flags


Creating Executables that Use the Dynamic Loader

The dynamic loader enables callable file formats to be loaded dynamically at run-time. The dynamic loader can also be selected by cob flags used to build a system executable with:

  • Explicit dynamic loading requested for a named program
  • Implicit dynamic loading for run-time selection of entry point.

Specifying the cob option -d symb causes the system executable to be built so that if the program named symb is called at run time, it is loaded dynamically; cob gives an error if the program is presented to cob for static linking.

Specifying the cob -e"" flag causes the system executable to be built so that the executable file's entry point must be specified at run time. You specify the entry point at run time by including the name of the entry point on the command line. The dynamic loader is used to locate the named program, first checking if the program is linked or previously loaded and, if not, trying to load the program dynamically.

The statement CALL data-name and any CALL statement that includes an ON EXCEPTION clause implies use of the dynamic loader. However, you might not want dynamic loading, for example if the subprogram to be called is a C routine. If the sub-program is called using the dynamic loader, then if the sub-program is linked into the system executable file, the linked version is used and no attempt is made at run time to dynamically load it.

If you have a subprogram in an archive library and you do not want the subprogram to be dynamically loaded you can ensure that it is linked by using one of the following:

  • A CALL literal with no ON EXCEPTION clause in one of the programs linked into the system executable file.
  • The cob -I symb flag; for example:
    cob -x prog.cbl -I subprog -l lib

Alternatively, the archive library can be turned into a shared library using the -Z cob flag.

Parent topic: Creating Different Types of Files
Related concepts
Dynamic Loading
Related reference
cob Flags


Creating Dynamically Loadable Files

A dynamically loadable file can be created as an .int file, .gnt file or callable shared object from any COBOL source file.

The cob command creates .int files by default, for example:

cob filenames

You can create .gnt files by using the -u flag, as follows:

cob -u filenames

You can create callable shared objects by using the -z flag, as follows:

cob -z filenames

where filenames is a list of the COBOL files to be linked.

Parent topic: Creating Different Types of Files
Related concepts
Callable Shared Objects


cob Flags

The following flags can be used with the cob command:

  • Pass Option to Assembler (-A as_option)
  • Compile for Animation (-a)
  • Pass Syntax-check Phase Directive to the Compiler (-C directive)
  • Pass Option to the C Compiler (-CC cc_option)
  • Pass Option to the C++ Compiler (+CC cc_option)
  • Compile No Further Than Linkable Object Module (-c)
  • Dynamically Load Symbol (-d symb)
  • Set Initial Entry Point (-e epsym)
  • Create Information for Symbolic Debugger (-g)
  • Include Symbol in Executable File (-I symb)
  • Compile to Intermediate Code for Unlinked Environment (-i)
  • Compile to JVM Byte Code (-j)
  • Recognize COBOL Source File with Non-standard Filename Extensions (-k cobol-file)
  • Pass Option to System Linker Changing Search Algorithm and Maintaining Relative Ordering (-L dir)
  • Pass Option to System Linker After All Other Options Changing the Search Algorithm (+L dir)
  • Pass Option to System Linker Maintaining Relative Ordering (-l lib)
  • Pass Option to System Linker After All Other Options (+l lib)
  • Map Symbol to New Symbol (-m symb=newsym)
  • Pass Generate Phase Directive (-N directive)
  • Enable Optimization (-O)
  • Specify Output File-name (-o filename)
  • Produce Listing File (-P)
  • Pass Flag to C Compiler to Use Profiling Routines (-p)
  • Pass Option to System Linker (-Q ld_option or -Q,1 ld_option or -Q,2ld_option)
  • Create Multi-threading Program (-t)
  • Dynamically Load Unresolved Reference (-U)
  • Compile to Generated Code for Unlinked Environment (-u)
  • Report Version Number (-V)
  • Set Verbose Module (-v)
  • Control Error Level for cob Termination (-W err-level)
  • Exclude Symbol from the Executable Output File (-X symb)
  • Process to System Executable File (-x[,CC])
  • Produce a Shared Library for non-COBOL Applications (-Y[,CC])
  • Produce a Self-Contained Callable Shared Object for non-COBOL Applications (-y[,U][,CC])
  • Produce a Shared Library File for COBOL Applications (-Z[,CC])
  • Produce a Callable Shared Object for COBOL Applications (-z[,U][,CC])
  • Flags Reserved for Future Use
Parent topic: Compiling and Linking from the Command Line


Pass Option to Assembler (-A as_option)

Passes the specified option to the UNIX system assembler (as).
Parent topic: cob Flags


Compile for Animation (-a)

Compiles the COBOL source files (with extension .cbl, .CBL or .cob) input to the cob command into an intermediate code file (with the extension .int) and Animator information files (with extension .idy), both of which are used by Animator.

Any object module files (with extension .o), C source files, or assembler source files input to the cob command are linked with the COBOL libraries to form a single system executable file, which also can be used by Animator. This enables you to animate programs that call, or are called by, programs that are written in languages other than COBOL.

The -a flag does not specify an end point for cob processing, only the type of intermediate code file produced by the COBOL Compiler.

Because this is the default action for the cob command, you do not actually have to specify the -a flag on the cob command line. However, you might find it useful to do so for clarity in your coding.

For example, if you use the command:

cob -a myfile.cbl c.o

The files myfile.int, myfile.idy and c are created. The file c contains the run-time system and the file c.o. The command:

cob myfile.cbl c.o

has the same effect. To animate myfile.int, use the commands:

COBSW=+A
export COBSW
c myfile.int
Parent topic: cob Flags


Pass Syntax-check Phase Directive to the Compiler (-C directive)

Passes directive to the Compiler's syntax-check phase, where directive is one or more of the Compiler directives listed in the topic Compiler directives.
Parent topic: cob Flags


Pass Option to the C Compiler (-CC cc_option)

Passes cc_option to the C compiler cc. If you specify the -CC cob flag, you must ensure that the only options you enter are options used by the C compiler itself. This is because the system assumes that if you are using the cob command rather than cc to compile a C program, you want to link the C program to COBOL programs before it is run. To do this, cob needs the .o file output by the C compiler once it has compiled the C program. cob can then take the resulting .o file and link it with other object modules to create a callable shared object, shared library or system executable file. Therefore, you should not try to use the -CC flag to pass options that the Compiler normally would try to pass to the system linker.
Parent topic: cob Flags


Pass Option to the C++ Compiler (+CC cc_option)

Passes cc_option to the C++ compiler. If you specify the +CC cob flag, you must ensure that the only options you enter are options used by the C++ compiler itself. This is because the system assumes that if you are using the cob command rather than the C++ compiler to compile a C++ program, you want to link the C++ program to COBOL programs before it is run. To do this, cob needs the .o file output by the C++ compiler once it has compiled the C++ program. cob can then take the resulting .o file and link it with other object modules to create a callable shared object, shared library or system executable file. Therefore, you should not try to use the -CC flag to pass options that the Compiler normally would try to pass to the system linker.
Parent topic: cob Flags


Compile No Further Than Linkable Object Module (-c)

Suppresses the link editing of any linked executable module, so the object modules can subsequently be linked. This option does not specify an end point and has an effect only if the specified end point would cause link editing; for example, if the -x, -z or -Z cob flags had been specified.
Parent topic: cob Flags


Dynamically Load Symbol (-d symb)

Note: For PowerLinux platforms only - when developing stub code for C programs, you cannot use this option in conjunction with the -O flag. To work around the issue, either link to the shared object or library containing the code in question, or compile without the -O flag.

Causes the symbol symb to be dynamically loaded if it is called. symb can be either of:

 symbol[, symbol]
 :symbol-filename

where symbol is a function name and symbol-filename is a text file containing a list of symbols, one per line. Spaces between -d and ":" are allowed. There can be no spaces between ":" and the filename.

This option can be used when producing a linked executable module, to specify any missing modules that are to be loaded dynamically at run time.

Parent topic: cob Flags


Set Initial Entry Point (-e epsym)

Overrides the default entry point symbol, using instead the symbol identified by epsym, which must already have been defined in a COBOL module. By default, the entry point address for a linked module is the basename of the first file input to the cob command. If you are linking to a system executable (-x cob flag) and want the entry point address to be read from the command line at run-time, you can define the value of epsym as null, that is -e "".
Parent topic: cob Flags


Create Information for Symbolic Debugger (-g)

When compiling, the ANIM directive is passed to the compiler to produce .int, .gnt or .o code that can be used by the Animator.

When linking, the linker creates additional information needed for the use of a symbolic debugger such as dbx. With this flag set, no symbols are stripped from the output file. This flag is passed through to the C or C++ compiler if any .c or .C files respectively are being processed, so it is useful if your program contains some C or C++ functions that you want to debug.

Parent topic: cob Flags


Include Symbol in Executable File (-I symb)

Marks symb for inclusion in the executable output file. symb can be either of:

 symbol[, symbol]
 :symbol-filename

where symbol is a function name and symbol-filename is a text file containing a list of symbols, one per line. Spaces between -I and ":" are allowed. There can be no spaces between ":" and the filename.

When symb is pulled in by the system linker, the entire object is pulled in along with any other objects that are referenced. For example:

cob -xo rts32 -e "" -I func1 -I func2
Parent topic: cob Flags


Compile to Intermediate Code for Unlinked Environment (-i)

Compiles the COBOL source code (.cbl, .CBL or .cob) files input to the cob command into dynamically loadable intermediate code files (with the file extension .int). These files can then be run without any further processing.
Parent topic: cob Flags


Compile to JVM Byte Code (-j)

Compiles the COBOL source code files (.cbl, .CBL, .COB or .cob) into JVM byte code (.class files), and in some circumstances additional .cbldat static data files.

Ensure any .cbldat files are deployed with the compiled source or located on the classpath.

Parent topic: cob Flags
Related concepts
Compiling JDBC Applications from the Command Line


Recognize COBOL Source File with Non-standard Filename Extensions (-k cobol-file)

Identifies to cob COBOL source files either with no extensions or with extensions other than the default extensions .cbl, .CBL or .cob. This allows COBOL files without the recognized extension to be compiled without having to alter their filename.
Parent topic: cob Flags


Pass Option to System Linker Changing Search Algorithm and Maintaining Relative Ordering (-L dir)

Changes the order in which the system linker searches for libraries that were specified with the -l cob flag. -L options affect only those -l options that they precede on the cob command line.

The -L cob flag is effectively the same as the -L option for the system linker, ld (see your operating system documentation for further details on this linker option). Normally, ld will search for libraries only in a predefined set of default directories; typically /usr/lib and /lib, but this varies from system to system. However, specifying the -L flag causes the system linker instead to search the specified directory first for such libraries. The order in which -L options are specified is significant as directories are searched in that order.

Paths in the environment variable LD_LIBRARY_PATH, or LIBPATH (AIX only) are searched after -L, +L directories but before the default paths.

Example:

The following example illustrates the use of the +L and -L flags in determining the order in which directories are searched for libraries:

cob +L /usr/mylib +llib1 object.o -L /usr/grouplib -llib2 +llib3

The relative ordering of the options passed to the system linker is:

  1. object.o
  2. -L/usr/grouplib
  3. -llib2
  4. -L/usr/mylib
  5. -llib1
  6. -llib3

Note that the ‘+’ options become ‘-’ options when passed to ld, and move to the end of the list.

This affects the order in which ld searches for libraries, and in which directory. The principle is that ld searches for a library (specified by –lname) in the following order:

  1. -L directories specified before –l on the command line, in the order in which they were specified
  2. LD_LIBRARY_PATH
  3. the default directories – typically /usr/lib but varies significantly from operating system to operating system

AIX does not use LD_LIBRARY_PATH, but uses LIBPATH.

ld searches for libraries in the above example using (directory, library) combinations in the following order:

  1. -L/usr/grouplib -llib2
  2. $LD_LIBRARY_PATH -llib2
  3. default-directories -llib2
  4. -L/usr/grouplib -llib1
  5. -L/usr/mylib -llib1
  6. $LD_LIBRARY_PATH -llib1
  7. default-directories -llib1
  8. -L/usr/grouplib -llib3
  9. -L/usr/mylib -llib3
  10. $LD_LIBRARY_PATH -llib3
  11. default-directories -llib3

The complete search path for every library would be searched only if a status of "file not found" is returned on earlier paths.

Parent topic: cob Flags


Pass Option to System Linker After All Other Options Changing the Search Algorithm (+L dir)

Has the same effect as -L except that +L options are passed (as -L options) to the system linker after all other objects and linker options. The ordering of +L and +l options relative to each other is preserved. See the description of -L for an example of the search order
Parent topic: cob Flags


Pass Option to System Linker Maintaining Relative Ordering (-l lib)

Causes the system linker to search the specified library for any external routines. The -l cob flag is effectively the same as the -l option for the system linker, ld (see your operating system documentation for further details on this linker option). The order in which -l options are specified is significant as libraries are searched in that order.

A library is searched when its name is encountered, so the placement of the -l flag is significant. See -L for more details.

Parent topic: cob Flags


Pass Option to System Linker After All Other Options (+l lib)

Has the same effect as -l except that +l options are passed (as -l options) to the system linker after all other options and linker options. The ordering of +l and -l options relative to each other is preserved. See the description of -L for an example of the search order.
Parent topic: cob Flags


Map Symbol to New Symbol (-m symb=newsym)

Maps unresolved symbol symb to newsym, which must already have been defined in a COBOL module; that is, any call to symb will go to newsym.

You also can use this flag to map parts of linked executables produced by cob onto user-supplied routines or tailored modules. Possible RTS symbols that can be mapped are:

Symbol | Description
sqfile | sequential fixed-length record file-handler
ixfile | indexed fixed-length record file-handler
rlfile | relative fixed-length record file-handler
lsfilev | line sequential variable-length record file-handler
sqfilev | sequential variable-length record file-handler
ixfilev | indexed variable-length record file-handler
rlfilev | relative variable-length record file-handler

When mapping symbols from any of the COBOL libraries, such as the file handler symbols above, if newsym has unresolved references to a user library, use the +L and +l flags to specify the library search path and name to ensure references from the COBOL libraries to the new symbols are correctly located.

If you do use this option to substitute the file handler supplied by Micro Focus with your own file handler, your file handler must conform to the Micro Focus Callable File Handler interface standard. Additionally, you can use the -m flag to link with the RTS a version of C-ISAM other than the version supplied with your Micro Focus COBOL system.

Parent topic: cob Flags


Pass Generate Phase Directive (-N directive)

Passes the specified option to the Compiler's generate phase. directive is one or more of the generate phase directives listed in the topic Compiler directives.
Parent topic: cob Flags
Related information
Compiler directives


Enable Optimization (-O)

Note: For PowerLinux platforms only - when developing stub code for C programs, you cannot use this option in conjunction with either the -d symb flag or the -U flag. To work around the issue, either compile without the -O flag, or link to the shared object or library containing the code that is referenced.
Enables maximum performance at run time by carrying out the minimum run-time checks. This option is for use after all debugging has taken place and maximum performance with minimum run-time checks is required. The exact operation of this flag is environment dependent, but at a minimum it passes the NOCHECK directive to the Compiler. If any .c or .C files are being processed, this flag also is passed through to cc or the C++ compiler.
Parent topic: cob Flags


Specify Output File-name (-o filename)

Changes the default name of the linked executable module created using the -x, -z or -Z option to the filename specified. The default filename for system executable files is the basename of the first file entered to the cob command. The default filename for callable shared objects is the basename of the first file entered to the cob command with .so appended. The default filename for shared library files is the basename of the first file entered to the cob command with a prefix lib and a suffix .so appended.
Parent topic: cob Flags


Produce Listing File (-P)

Produces a listing file (with the extension .lst) for each COBOL source file input to the cob command. Any errors detected by the Compiler are also reported both on the standard error and in the listing file (at the point at which the error was located).
Parent topic: cob Flags


Pass Flag to C Compiler to Use Profiling Routines (-p)

Note: This flag is not supported for PowerLinux on Red Hat.

Passes the option -p to the C or C++ compiler. If linking to a system executable module, it causes cob to use profiling startup and termination routines that call monitor(3) and causes the monitor information to be written to the file mon.out on normal termination of the executable module. See your system manual for more details on the -p flag.

Some operating systems do not support profiling for linked executables.

Parent topic: cob Flags


Pass Option to System Linker (-Q ld_option or -Q,1 ld_option or -Q,2ld_option)

Passes the specified cob option(s) to the system linker. The Micro Focus COBOL system uses a two-pass link process to build a linked executable module to support dynamic loading and reference to C external data. Specifying -Q ld_option passes the options to both linker passes (that is, calls of the command ld). Specifying -Q,1 ld_option passes the options to only the first linker pass. Specifying -Q,2 ld_option passes the options to only the second linker pass.

You must use a separate -Q flag for each option, and any options that begin with hyphens must be enclosed in quotation marks. Use the format -Q "flag value" only where flag and value are not separate arguments, but represent one argument containing an embedded space.

Parent topic: cob Flags


Create Multi-threading Program (-t)

Creates multi-threading programs that use the multi-threading run-time system. It passes the REENTRANT Compiler directive to the Compiler and appropriate options to the C and C++ compilers if required, and selects the multi-threading libraries.
Parent topic: cob Flags


Dynamically Load Unresolved Reference (-U)

Note: For PowerLinux platforms only - when developing stub code for C programs, you cannot use this option in conjunction with the -O flag. To work around the issue, either link to the shared object or library containing the code in question, or compile without the -O flag.
Causes any unresolved reference to be treated as a COBOL program to be dynamically loaded. Normally, such references would cause a fatal error at link time when creating a system executable, or cause a fatal error at run-time for callable shared objects.
Parent topic: cob Flags


Compile to Generated Code for Unlinked Environment (-u)

Compiles the COBOL source code files (.cbl, .CBL or .cob) into intermediate code and then generates them to dynamically loadable native code (generated code) files. These files have the file extension .gnt.

If the -g flag is also specified, the resulting generated code contains debugging information so that it can be debugged with Animator.

You can supply intermediate code files to the cob command instead of COBOL source code files; these are just code generated. You can also input any object module files (.o) to the cob command; these are linked to create an executable RTS. Dynamically loaded programs can call any of the modules in the linked executable RTS as well as any other valid dynamically loadable program.

Example

The following examples illustrate the types of processing available using the -u flag:

cob Command line Output Files
cob -u tmp/a.cbl
a.int, a.idy, a.gnt
cob -u b.cbl
b.int, b.idy, b.gnt
cob -u a.int
a.gnt
cob -u tmp/b.int
b.gnt
cob -ug a.cbl
a.int, a.idy, a.gnt
Parent topic: cob Flags


Report Version Number (-V)

Sends to the screen the version number of any of the COBOL system components that have been invoked. This option is passed to the system programming utilities (for example, cc and ld).
Parent topic: cob Flags


Set Verbose Module (-v)

Sends to the screen messages output by the Compiler concerning accepted directives, the size of the code and data areas, and the entry points of each module. This flag also outputs to the screen warning messages concerning non-error conditions (for example if a flag you have specified overrides one you have already set), which by default are suppressed. Additionally, it echoes to the screen the entire command line when it is passed to cob.
Parent topic: cob Flags


Control Error Level for cob Termination (-W err-level)

Causes cob processing to terminate after the COBOL Compiler err-level has been exceeded. By default, the cob command terminates if your code contains reported errors in the category severe or above.

err-level is a single alphabetic character representing the possible levels of error:

Character | Level
u | unrecoverable
s | severe
e | error
w | warning
i | information

The cob process (not the compile process) is terminated if your code contains an error at the specified level or higher, provided such errors are reported to the cob command by the Compiler. This depends on the setting of the WARNING Compiler directive, which controls the level of error reported by the Compiler.

Thus, for example, if you set the WARNING directive to force the Compiler to report only unrecoverable, severe and error level errors, but also set the -W flag to abort the cob command if any errors at the information level (or above) are reported, errors only in the categories unrecoverable, severe or error actually causes the cob command to terminate, as warning and information errors are not reported.

Parent topic: cob Flags


Exclude Symbol from the Executable Output File (-X symb)

Excludes the unresolved text symbol symb from the executable output file. symb can be either of:
 symbol[, symbol]
 :symbol-filename

where symbol is a function name and symbol-filename is a text file containing a list of symbols, one per line. Spaces between -I and ":" are allowed. There can be no spaces between ":" and the filename.

This flag creates a stub routine to satisfy any reference to symb, which if called produces RTS error 107:

Operation not implemented in this Run-Time System

It can be used to satisfy undefined symbols to modules that you know are not required (but are referenced), thereby still allowing an executable file to be produced. The resulting file might not actually be any smaller than it would have been if you had not specified this flag. However, setting this flag does ensure that should you try to call any excluded module, you receive a meaningful error message.

Parent topic: cob Flags


Process to System Executable File (-x[,CC])

Creates a system executable file from the files input to the cob command. The input file can be any file type except a .gnt file. By default, the name of this module is the base-name of the first object being linked. It has no extension.

You also can use this option to produce a full RTS, for example,

cob -xo rts.new

The CC option to the -x flag enables you to link COBOL and C++ objects into an executable file. If C++ (.C) source files are specified, the C++ compiler is invoked to compile them to object code first.

For example, if you want to link the C++ program cprg.C and the COBOL program cobprg.cbl, use the following commands:

cob -x,CC cobprg.cbl cprg.C
Parent topic: cob Flags


Produce a Shared Library for non-COBOL Applications (-Y[,CC])

The -Y flag creates a shared library file from the files input to the cob command. This file can then be linked to non-COBOL executables.

Input files can be any file type except .gnt files.

The CC option enables you to also link C++ objects into the library file. If C++ (.C) source files are specified, the C++ compiler is invoked to compile them to object code first.

By default, the base-name of the resulting shared library file takes the name of the first object being linked, prefixed with lib, and the filename extension is .so.

For example, the following command line links the C++ program cprg.C and the COBOL program cobprg.cbl into the resulting shared library libcobprg.so:

cob -Y,CC cobprg.cbl cprg.C
Parent topic: cob Flags
Related reference
Produce a Self-Contained Callable Shared Object for non-COBOL Applications (-y[,U][,CC])


Produce a Self-Contained Callable Shared Object for non-COBOL Applications (-y[,U][,CC])

The -y flag creates a self-contained callable shared object file from the files input to the cob command. This file can then be called by non-COBOL executables.

Input files can be any file type except .gnt files. If you use object module files (.o), they are linked in using the system linker (ld).

The CC option enables you to also link C++ objects into the library file. If C++ ( .C) source files are specified, the C++ compiler is invoked to compile them to object code first.

The source code files are compiled into intermediate code, generated to object code (.o) files, and then linked to create a dynamically loadable self-contained callable shared object.

By default, the base-name of the resulting shared object file takes the name of the first object being linked, and has the filename extension .so. The base-name forms the main entry point, but this can be overridden using the -e flag.

The U option specifies that an error message should be issued if there are any undefined symbols.

If the -g flag is also specified, the resulting self-contained callable shared object contains debugging information so that it can be debugged with Animator.

Examples:

The following examples illustrate the types of processing available using the -y flag:

cob Command line Output files
cob -y tmp/a.cbl
a.int, a.idy, a.o, a.so
cob -y b.cbl
b.int, b.idy, b.o, b.so
cob -y a.int
a.o, a.so
cob -y c.o
c.so
cob -yg a.cbl
a.int, a.idy, a.o, a.so
cob -y,CC cobprg.cbl cprg.C
cobprg.int, cobprg.idy, cobprg.o, cprg.o, cobprg.so
Parent topic: cob Flags
Related concepts
Self-Contained Callable Shared Objects
Related reference
Produce a Shared Library for non-COBOL Applications (-Y[,CC])


Produce a Shared Library File for COBOL Applications (-Z[,CC])

The -Z flag creates a shared library file from the files input to the cob command. This file can then be linked to COBOL executables.

Input files can be any file type except .gnt files.

The CC option enables you to also link C++ objects into the library file. If C++ (.C) source files are specified, the C++ compiler is invoked to compile them to object code first.

By default, the base-name of the resulting shared library file takes the name of the first object being linked, prefixed with lib, and the filename extension is .so.

For example, the following command line links the C++ program cprg.C and the COBOL program cobprg.cbl into the resulting shared library libcobprg.so:

cob -Z,CC cobprg.cbl cprg.C
Parent topic: cob Flags
Related reference
Produce a Callable Shared Object for COBOL Applications (-z[,U][,CC])


Produce a Callable Shared Object for COBOL Applications (-z[,U][,CC])

The -z flag creates a callable shared object file from the files input to the cob command. This file can then be called by COBOL executables.

Input files can be any file type except .gnt files. If you use object module files (.o), they are linked in using the system linker (ld).

The ,CC option enables you to also link C++ objects into the library file. If C++ ( .C) source files are specified, the C++ compiler is invoked to compile them to object code first.

The source code files are compiled into intermediate code, generated to object code (.o) files, and then linked to create a dynamically loadable callable shared object.

By default, the base-name of the resulting shared object file takes the name of the first object being linked, and has the filename extension .so. The base-name forms the main entry point, but this can be overridden using the -e flag.

The ,U option specifies that an error message should be issued if there are any undefined symbols.

If the -g flag is also specified, the resulting callable shared object contains debugging information so that it can be debugged with Animator.

Examples:

The following examples illustrate the types of processing available using the -z flag:

cob Command line Output files
cob -z tmp/a.cbl
a.int, a.idy, a.o, a.so
cob -z b.cbl
b.int, b.idy, b.o, b.so
cob -z a.int
a.o, a.so
cob -z c.o
c.so
cob -zg a.cbl
a.int, a.idy, a.o, a.so
cob -z,CC cobprg.cbl cprg.C
cobprg.int, cobprg.idy, cobprg.o, cprg.o, cobprg.so
Parent topic: cob Flags
Related concepts
Resolving Unresolved References in Callable Shared Objects
Related reference
Produce a Shared Library File for COBOL Applications (-Z[,CC])


Flags Reserved for Future Use

The following cob flags are reserved for our future use:

-f -q

Parent topic: cob Flags


cob Error Messages

The cob command outputs error messages. Most of these messages are self-explanatory, but the following are worthy of special note:

  • argument expected: option-name
  • cobol version number invalid - Call Technical Support
  • entry defined: entryname-1 conflicting "main" found in entrypoint-2
  • entry: entryname does not have "main" defined
  • I see no use for file-name
  • I see no work
  • invalid entry point name: entryname
  • options clash: option-names
    The options that you have specified to the cob command are not valid.
Parent topic: Compiling and Linking from the Command Line
Related information
COBOL


argument expected: option-name

The specified option requires an argument.

Parent topic: cob Error Messages


cobol version number invalid - Call Technical Support

The contents of the cobver file are incorrect.

Parent topic: cob Error Messages


entry defined: entryname-1 conflicting "main" found in entrypoint-2

You have defined the symbol "main" in a module other than the specified entry point module. If the first program specified to cob when building an executable is a COBOL module, the COBOL system "main" routine is linked in from the COBOL libraries.

Parent topic: cob Error Messages


entry: entryname does not have "main" defined

The specified entry point module (which is a non-COBOL module) does not define the symbol "main". This is the compulsory entry point for any non-COBOL modules that are specified as the first program on the cob command line when building an executable file.

Parent topic: cob Error Messages


I see no use for file-name

Cob is unable to process the files you have specified as they have already been progressed beyond the specified end-point, or the specified options are not recognized.

Parent topic: cob Error Messages


I see no work

You have specified inappropriate parameters that do not match the options you have used.

Parent topic: cob Error Messages


invalid entry point name: entryname

The specified entry point symbol is not a valid symbol name. Valid symbol names can consist of any of the characters a through z, A through Z, 0 through 9 or the underscore ( _ ). A name cannot begin with a digit.

Parent topic: cob Error Messages


options clash: option-names

Parent topic: cob Error Messages


cob Command Examples

cob -x pi.cbl
Compiles the program in pi.cbl into a file called pi.int suitable for animation. As this is the default case, the -a flag does not need to be specified. Then links the COBOL source file pi.cbl to the run-time support libraries to form a system executable file named pi.
cob -i pi.cbl
Compiles the COBOL source file pi.cbl for the unlinked environment to produce an intermediate code file, pi.int
cob -u pi.cbl
Syntax-checks and generates the program in pi.cbl into a dynamically loadable .gnt file.
cob -z pi.cbl
Syntax-checks and generates the program in pi.cbl into a dynamically loadable callable shared object file.
cob -xo newrts routines.c
Builds an executable run-time system that contains C routines.
cob -z myprog routines.c
Syntax-checks, generates and links a callable shared object file that contains C routines
cob -xve "" -o my_rts -C xopen prog.cbl prog2.c
  • Compiles the COBOL source file prog.cbl and the C source file prog2.c
  • Compiles using the XOPEN Compiler directive
  • Links the result into a system executable file named my_rts that, when run, expects the name of the program to run to be given on its own command line
  • Gives verbose notification of progress
cob -x prog.cbl -d subprog
Builds a system executable file that has the main program prog linked and dynamically loads the subprogram subprog at run time.
cob -z subprog.cbl
Creates a dynamically loadable file for subprog as high performance machine. code. At run time, the program prog can be run by invoking the system executable file, as follows:
prog

The dynamic loader loads the subprogram when it is called. If the subprogram cannot be found and loaded, then if an ON EXCEPTION clause for the CALL exists it is executed, otherwise the run-time system gives an error.

Note: To run a system executable file by just giving its filename on the command line, the file must be held in a directory that appears in your PATH environment variable. Alternatively you can specify the full pathname, which for the above example would be . /prog .
cob -xe "" prog1.cbl prog2.cbl -o runprog

Builds an executable RTS that contains two programs such that the program to be run is selected at run time. The cob option -e "" specifies that the entry point, or the main program is given at run time and the -o option specifies the name of the system executable file as runprog.

To run the first program, enter the command:

runprog prog1

To run the second program, enter the command:

runprog prog2
Parent topic: Compiling and Linking from the Command Line


Converting Header Files Using the H2cpy Utility

You can run the Header-to-copy utility directly from the command line or invoke it automatically using the PREPROCESS(headers) Compiler directive. The Headers preprocessor allows C header files, with an extension of .h, to be specified in a COPY statement in a COBOL source file. The preprocessor recognizes these as C header files and uses the Header-to-copy utility to convert them. This can be very convenient for relatively small header files.

See Converting Header Files Using the H2cpy Utility in the Programming folder for full details.

Parent topic: Command line reference


Running an Application from the Command Line

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

  • Command to Run a Linked System Executable Program
  • cobrun Command
  • cobrun Command Examples
  • Create a Live Recording File from the Command Line
    Create a live recording file so that you can replay it through the debug engine in Eclipse, on another machine.
Parent topic: Command line reference


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

cobrun -F demo.int

To run demo.int in ANSI debug mode whilst disabling the display of trailing spaces:

cobrun +D+A1 demo.int
Parent topic: Running an Application from the Command Line


Create a Live Recording File from the Command Line

Restriction: This feature is only supported on the following platforms:
  • Red Hat Linux (x86 and x64)
  • SUSE Linux Enterprise Server (SLES) 12 SP2 (x64 only)

Additional restrictions apply. For details, see the Reverse Debug and Live Recording topic in the Known Issues and Restrictions section of this documentation.

You can create a recording of your application execution, and then load the recording into the Eclipse debugger, on another machine, to watch the execution path. To play the recording back, you must ensure that it is played on a machine that is using the same operating system as the one that it was created on.

As the programs run, the recorder captures everything that influences the running of the programs, including all input, disk access, keyboard strokes, database connections and processes, interactions with the operating system, etc. After loading the recording into the debugger, you can move forwards and backwards seamlessly through the recording.

To be able to run the recording successfully, you must have access to the program source files (COBOL program files and copybooks) and debug symbol files (.idy files) used in the application.

  • To Create a Live Recording File from the Command Line
Parent topic: Running an Application from the Command Line


To Create a Live Recording File from the Command Line

Restriction: This feature is only supported on the following platforms:
  • Red Hat Linux (x86 and x64)
  • SUSE Linux Enterprise Server (SLES) 12 SP2 (x64 only)

Additional restrictions apply. For details, see the Reverse Debug and Live Recording topic in the Known Issues and Restrictions section of this documentation.

  1. From a shell prompt, set the COB_LIVE_RECORD environment variable to the path and filename of the intended file:
    export COB_LIVE_RECORD=path/and/filename
  2. (Optional) Set the COB_LIVE_RECORD_SIZE environment variable to control the amount of memory used to store events that are to be written to the live recording file:
    export COB_LIVE_RECORD_SIZE=mem-size

    where mem-size is the amount of memory (in MB) allocated. If not set, the amount of memory used defaults to 268MB. The minimum value you can set is 67, and the maximum value is dependant on your environment (available memory, bitism, etc...).

    Warning: When the limit is reached, the buffer is cycled so that the oldest events are removed to make space for the most recent events; therefore, when debugging a recording file where this has occurred, debugging won't necessarily start at the beginning of the program.
  3. Run the application from the shell prompt:
    cobrun [switch-params] program-name [program-params]

    See the cobrun Command topic for a full explanation of the syntax.

When the application terminates, a recording file is created at the path specified, and with the filename appended with <processID>.mfr; for example MyProg.1884.mfr. You can now use this file on another machine to step through the recorded execution.
Parent topic: Create a Live Recording File from the Command Line
Related reference
cobrun Command


Enhanced ACCEPT/DISPLAY Syntax

  • Overview
  • Accepting Elementary Data Items from Single Fields
  • Displaying Elementary Data Items in Single Fields
  • Accepting and Displaying Group Items
  • Accepting and Displaying Screen Section Items
  • Accepting and Displaying Data on Large Screens
  • Keyboard Handling Via Adis
Parent topic: Command line reference


Overview

The enhanced ACCEPT/DISPLAY syntax (Adis) is a run-time support module which is provided for Screen Section and enhanced ACCEPT/DISPLAY syntax.

Note: Micro Focus recommends that the enhanced ACCEPT/DISPLAY syntax (Adis) is only used with existing applications and should not be used for new applications.

Adis can be configured to an application's requirements using its configuration utility Adiscf. Alternatively, calls can be made from the COBOL application to Adis to configure it at run time; for example, to enable function keys.

The enhanced ACCEPT/DISPLAY syntax provides functionality beyond the standard ANSI ACCEPT syntax.

The following table represents those features of Adis over and above those of the standard ANSI ACCEPT and DISPLAY syntax:

Syntax type Features
ANSI ACCEPT
  • Input data item
  • Accept day, date, time into data item
ANSI DISPLAY
  • Output literals
  • Output contents of data items
Adis
  • Specify screen position and screen attributes
  • Accept and display data from and into:
    • Elementary data items in individual fields
    • Group items in multiple fields screen

      For multiple-field ACCEPT operations, FILLER describes the number of character positions to skip over to the next field. In a DISPLAY operation, FILLER defines the number of spaces between literals. All areas defined as FILLER are unaffected by the ACCEPT or DISPLAY operation.

    • Screen Section items
  • Configure keyboard keys

You can also set up the keys on the keyboard so that you can use them during the execution of an ACCEPT statement.

  • Distinguishing between the types of Adis keys
  • Using the Adis function keys
  • Mapping the Adis keys to the functions

Adis consists of the following modules:

Module | Description
adis | The main support module
adisinit | The initialization module, used only when the enhanced ACCEPT/DISPLAY syntax is first loaded
adiskey | The keyboard-handling module
adisdyna | The enhanced ACCEPT/DISPLAY syntax dynamic attributes module.

They interact as shown in the diagram below.

Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Accepting Elementary Data Items from Single Fields

The ACCEPT statement is executed differently for alphanumeric fields and numeric fields.

  • Accepting Single Fields
  • Alphanumeric Fields
  • Numeric and Numeric-edited Fields
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Accepting Single Fields

To use ACCEPT and DISPLAY elementary items from and into single fields at run time, use the syntax:

display data-item at xxyy ...
accept data-item at xxyy ...

where:

data-item
is an elementary item defined in the Data Division of your program.
xxyy
is the position on the screen (xx=line,yy=column) where the DISPLAY or ACCEPT field starts. The length of the field is governed by the length and type of data-item, and by the SIZE clause of the ACCEPT or DISPLAY statement.
Parent topic: Accepting Elementary Data Items from Single Fields


Alphanumeric Fields

The term alphanumeric field is used here to cover all alphanumeric, alphabetic and alphanumeric-edited fields. For the purposes of an ACCEPT statement, an alphanumeric-edited field is treated as an alphanumeric field of the same length. Any insertion symbols such as the forward slash character (/) or zero are ignored and treated as an X. Therefore, a field defined as PIC XX0XX0XX is treated as if it was specified as PIC X(8).

If the field is defined as alphabetic, only the characters "A" to "Z", "a" to "z" and space are allowed into the field.

The cursor is initially placed at the start of the field.

As data is entered into the field, the cursor advances to the next character. The cursor can be moved back over the data in the field using the cursor keys, and editing functions such as backspace and delete are provided.

Parent topic: Accepting Elementary Data Items from Single Fields


Numeric and Numeric-edited Fields

The form of data entry for numeric and numeric-edited fields can be one of the following:

  • Fixed-format
  • Free-format
  • RM style

Use Adiscf to select the style you want. The default form of data entry is Fixed-format. You should experiment with free-format to see which method you prefer, especially when accepting into simple numeric fields.

  • Fixed-format Data Entry
  • Free-format Data Entry
  • RM-style Data Entry
Parent topic: Accepting Elementary Data Items from Single Fields


Fixed-format Data Entry

Fixed-format mode is also known as formatted mode. It can best be described as "What you see is what you get". As each key is pressed, the field is automatically reformatted to conform to the picture string. The enhanced ACCEPT/DISPLAY syntax tries to ensure that the field always looks on the screen as it is stored in the Data Division, and its size is the same as the size of the data item.

Therefore, as with the DISPLAY statement, it is only really sensible to accept fields that are defined as USAGE DISPLAY with no implied sign or decimal point.

During data entry, characters other than numeric digits, the plus sign (+), minus sign (-) and the decimal point (.) are rejected. Insertion characters in edited fields are automatically skipped over as the cursor is moved backward and forward. Any sign indicator is automatically modified if a + or - is pressed, regardless of where the cursor is in the field.

Zeros are allowed as insertion characters only as a leading symbol before a decimal point, or as a trailing symbol following a decimal point. For example, PIC 0.9999 and PIC 999.90 are valid, but PIC 0.0009 and PIC 999.000 are not.

Data entry of simple numeric and numeric-edited fields with no zero suppression is similar to that for alphanumeric fields, except that insert mode is not supported in numeric and numeric-edited fields. If the decimal point character is pressed in a simple numeric field, the digits are right justified. For example, a field defined as PIC 9(5) which initially contains zeros is accepted as follows ( underscored characters indicate cursor position):

Initial display
00000
Pressing 1 gives
10000
Pressing 2 gives
12000
Pressing 4 gives
12400
Pressing Backspace gives
12000
Pressing "." gives
00012

Data entry into zero-suppressed fields is handled differently. The cursor is initially placed on the first character position that is not zero-suppressed. If all the digits before the decimal point are suppressed, the cursor is positioned on the decimal point itself.

While the cursor is to the left of the decimal point; that is, in the integer part of the field, the cursor moves to the right as digits are entered until the decimal point is reached. Any further digits are inserted immediately before the decimal point until all the integer places are filled. The cursor is then automatically moved to the first decimal digit and advances as the decimal digits are entered.

If you wish to enter digits after the decimal point when there are integer places still unfilled, the decimal point (.) must be entered.

For example, assume that a numeric-edited data field is defined as PIC ZZZ99.99 and initially contains zeros, the field is displayed as follows during the ACCEPT:

Initial display
00.00
Pressing 1 gives
10.00
Pressing 2 gives
12.00
Pressing 3 gives
123.00
Pressing 4 gives
1234.00
Pressing Backspace gives
123.00
Pressing 5 gives
1235.00
Pressing 6 gives
12356.00
Pressing 7 gives
12356.70
Pressing 8 gives
12356.78

If you want to enter 123.45 into the same field, the field appears as follows:

Initial display
00.00
Pressing 1 gives
10.00
Pressing 2 gives
12.00
Pressing 3 gives
123.00
Pressing "." gives
123.00
Pressing 4 gives
123.40
Pressing 5 gives
123.45

Fixed format mode is only allowed on numeric-edited data items of up to 32 characters in length. If they are longer than 32 characters, they are automatically handled in free-format mode as described in the section Free-format Data Entry. Fields are also automatically treated as free-format if a SIZE clause is specified in the ACCEPT statement.

Parent topic: Numeric and Numeric-edited Fields
Related reference
Free-format Data Entry


Free-format Data Entry

Free-format mode can be selected for either numeric fields or numeric-edited fields or both. This can be done using Adiscf.

During data entry into a free-format field, the field is treated as an alphanumeric field of the appropriate length. It is only when the user leaves the field that it is reformatted to comply with the picture string. Any characters other than the digits, the sign character and the decimal point character are discarded.

Fields occupy the same number of characters on the screen as they do bytes in memory, with the exception that an additional character is allocated for implied signs and decimal points. Therefore, a data item defined as PIC S99V99 occupies six characters on the screen in free-format mode as opposed to four characters in Fixed-format mode.

It is advisable to compile the program with the DE-EDIT"1" Compiler directive set, since free-format allows data that does not conform to the screen item's PICTURE clause; with DE-EDIT"2" this is interpreted as zeros when moved to the USING or TO data item.

Data entry is the same as for alphanumeric fields.

If an enhanced ACCEPT statement is being used, the clauses SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN are applicable only to free-format non-edited fields (and are ignored with fixed format fields).

Parent topic: Numeric and Numeric-edited Fields
Related concepts
Fixed-format Data Entry


RM-style Data Entry

RM style data entry is selected using the appropriate Accept/Display option in Adiscf. It is provided for emulation of numeric and numeric-edited ACCEPT operations in RM/COBOL V2.0. If this mode is selected, all other Accept/Display option numeric and numeric-edited data entries are ignored. Data entry is the same as for alphanumeric fields. All ACCEPT and DISPLAY statements behave as if the phrase MODE IS BLOCK has been specified.

This style of numeric input is not intended for use with the screen handling syntax in this COBOL system, only with programs originally written for RM/COBOL.

See MODE IS BLOCK Clause for more information.

Parent topic: Numeric and Numeric-edited Fields
Related reference
MODE IS BLOCK Clause


Displaying Elementary Data Items in Single Fields

When a data item is displayed on the screen, it normally occupies the same number of characters on the screen as it does bytes in memory. The only exceptions are DBCS encoding schemes such as EUC which includes characters which differ in storage space and display size.

  • Displayed Data Format - Examples
  • Displaying Single Fields
  • Control Sequences in Displayed Data
  • Displaying Highlighted Text
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Displayed Data Format - Examples

Data Description | Size on Screen | Comment
X(5) | 5 characters |
N(5) | 10 characters | Each PIC N character occupies 2 bytes in memory.
G(5) | 10 characters | Each PIC G character occupies 2 bytes in memory.
9(5) | 5 characters |
99.99 | 5 characters |
Z(4)9 | 5 characters |
99V99 | 4 characters | V is an implied decimal point and so is not displayed on the screen.
S9(4) | 4 characters | The sign is implied and so is not displayed on the screen.
S9(4) SIGN LEADING SEPARATE | 5 characters |
9(4) COMP | 2 characters | COMP fields are stored in binary; a 9(4) COMP field occupies 2 bytes in memory

As you can see from the above examples, it is only really sensible to display fields defined as USAGE DISPLAY which do not contain implied signs or decimal points. When the field is displayed, it is copied byte-for-byte from the data item onto the screen at the required position.

Note:

ANSI DISPLAY operations convert non-USAGE DISPLAY numeric items to USAGE DISPLAY before displaying.

Parent topic: Displaying Elementary Data Items in Single Fields


Displaying Single Fields

To use ACCEPT and DISPLAY elementary items from and into single fields, use the syntax:

display data-item at xxyy ...
accept data-item at xxyy ...

where:

data-item
is an elementary item defined in the Data Division of your program.
xxyy
is the position on the screen (xx=line,yy=column) where the DISPLAY or ACCEPT field starts. The length of the field is governed by the length and type of data-item, and by the SIZE clause of the ACCEPT or DISPLAY statement.
Parent topic: Displaying Elementary Data Items in Single Fields


Control Sequences in Displayed Data

Control sequences cannot be embedded in the data that is displayed. If you do embed control codes (that is, ASCII codes less than 32) into the data, the character corresponding to that code is displayed. For example, displaying ASCII code 7 results in a diamond character being displayed instead of sounding the bell. (In some environments, such characters are replaced by a space.) All highlighting and cursor control must be done through the syntax provided.

Parent topic: Displaying Elementary Data Items in Single Fields


Displaying Highlighted Text

If you use the CRT-UNDER phrase in a DISPLAY statement, the data item is displayed with an attribute to make the display stand out from normal displayed text. Depending on your environment, use of the CRT-UNDER phrase might cause data items to be displayed underlined, highlighted, colorized or in reverse video. This can be changed using Adiscf.

Parent topic: Displaying Elementary Data Items in Single Fields


Accepting and Displaying Group Items

When accepting or displaying group items, each elementary item within the group is treated as a separate field. If an elementary item is defined as FILLER, it is simply used as a positioning item of the appropriate size; that is, you cannot accept into or display FILLER items.

  • Accepting into Group Items
  • Displaying Group Items
  • MODE IS BLOCK Clause
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Accepting into Group Items

When accepting into a group item, each field is accepted into as described for single-field ACCEPT statements, as in the sections below.

Unless you explicitly position the cursor using the CURSOR IS cluase, the cursor is initially placed at the start of the first field.

When the end of a field is reached, the cursor is normally advanced to the beginning of the next field automatically. This action can be prevented by turning off auto-skip using Adiscf. The cursor keys, and the keys set up for next and previous field operations (usuallyTab and Backtab) move the cursor around the fields.

Parent topic: Accepting and Displaying Group Items


Displaying Group Items

Consider the following group item:

 01 display-item.
     03 display-item-1        pic x(20).
     03 filler                pic x(35).
     03 display-item-2        pic 9(10).
     03 filler                pic x(105).
     03 display-item-3        pic z(4)9.
If the following statement is executed on a screen 80 characters wide:
display display-item at 0101
display-item-1 is displayed at row 1, column 1, display-item-2 is displayed at row 1, column 56, display-item-3 is displayed at row 3, column 11

All other areas of the screen are unaffected by this DISPLAY statement. FILLER items do not cause any data to be displayed on the screen. Consequently, data already on the screen in the positions defined by each FILLER is not altered in any way by this DISPLAY statement.

If a data item is defined as follows:

 01 data-item.
    03 data-char                       pic x occurs 2000.

and the following statement is executed:

display data-item at 0101

then this is treated as a display of 2000 fields, each defined as PIC X, which is unlikely to be what you require. To avoid this, either redefine data-item as a PIC X(2000) and display that, or use the MODE IS BLOCK clause described in the section MODE IS BLOCK Clause.

Parent topic: Accepting and Displaying Group Items
Related reference
MODE IS BLOCK Clause


MODE IS BLOCK Clause

If the MODE IS BLOCK clause is added to an ACCEPT or DISPLAY of a group item, the group item is treated as if it was an elementary item of the total size of the group item.

Note:

If a program is compiled with the IBM-MS, MS"1", MS"2" or RM directives set, the Compiler treats all DISPLAY and ACCEPT operations of group items as if MODE IS BLOCK had been specified.

Parent topic: Accepting and Displaying Group Items
Related concepts
RM-style Data Entry
Displaying Group Items


Accepting and Displaying Screen Section Items

ACCEPT and DISPLAY operations involving Screen Section items are treated like any other ACCEPT or DISPLAY operation, but with one important difference. Consider the following code:

 working-storage section.
 01 item-a              pic 9(5).
 01 item-b              pic 9(10).
 01 item-c              pic x(10).
 ...
 screen section.
 01 demo-screen.
     03 blank screen.
     03 line 1 column 1 pic z(4)9 from item-a.
     03 line 3 column 1 pic 9(10) to item-b.
     03 line 5 column 1 pic x(10) using item-c.

When this code is compiled, the Compiler sets up a work area for each Screen Section level-01 item (record). In this example, a work area is set up for demo-screen, large enough to hold the data for the three fields.

When the following statement is executed:

display demo-screen

the contents of item-a and item-c are moved from Working-Storage Section into the work area, then the data in the work area for these two fields is displayed on the screen. item-b is not displayed because it is an ACCEPT-only field.

When the following statement is executed:

accept demo-screen

data is accepted into the work area for item-b and item-c and then the data for these two fields is moved from the work area into the Working-Storage Section. Data is not accepted into item-a because it is a DISPLAY-only field.

It is important to note that moves from the Data Division to the work area occur only on execution of a DISPLAY statement, and moves from the work area to the Data Division occur only during execution of an ACCEPT statement. If two ACCEPT statements are executed one after another with no intervening DISPLAY statement, the initial contents of the fields at the start of the second ACCEPT are those which were put into the work area during the previous ACCEPT operation not the current contents of the Data Division items.

Another implication of this is that a field should not be defined as numeric-edited in both the Data Division and the Screen Section. This results in the compiler making numeric-edited to numeric-edited moves in order to move the Data Division item into the work area and back again. The action of such moves is undefined and has unpredictable results. This is the case even if both the Data Division item and the Screen Section item have the same picture.

For example, if the following lines are coded in your program:

working-storage section.
 01 ws-item     pic zz9.99 value 1.23
 screen section.
 01 demo-screen.
     03 pic zz9.99 using ws-item.
 procedure division.
     display demo-screen.

The result of the DISPLAY operation is undefined. The items used in the Data Division as source or target for Screen Section ACCEPT or DISPLAY statements should always be non-edited fields.

  • Positioning the Cursor for ACCEPT Statements
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Positioning the Cursor for ACCEPT Statements

The CURSOR IS clause specifies where in a field the cursor is positioned at the start of the ACCEPT operation, and returns where the cursor is left at the end of an ACCEPT operation. If you do not specify a CURSOR IS clause in your program, the cursor is positioned at the start of the first field for every ACCEPT operation.

Syntax:

The CURSOR IS clause is defined in the Special-Names paragraph, as follows:

 special-names.
     cursor is cursor-position.

where cursor-position is a field defined in the Working-Storage Section of your program as follows:

 01 cursor-position.
     03 cursor-row       pic 99.
     03 cursor-column    pic 99.

or:

 01 cursor-position.
     03 cursor-row       pic 999.
     03 cursor-column    pic 999.

where:

cursor-row
is the row the cursor is positioned on. Valid values are between 1 and the number of lines on the screen.
cursor-column
is the column the cursor is positioned on. Valid values are between 1 and the number of columns on the screen.

Operation:

Whenever an ACCEPT statement is executed, the enhanced ACCEPT/DISPLAY syntax attempts to initially position the cursor at the position specified in cursor-position. If the position specified is invalid (that is, either cursor-row or cursor-column does not contain a valid value), the cursor is positioned at the start of the first field on the screen.

If the value in cursor-position is valid, the enhanced ACCEPT/DISPLAY syntax searches through all of the fields to see if the requested cursor position lies within one of them. If it does, the cursor is positioned at the required point. If it does not, then the cursor is positioned at the start of the first field. Therefore, if you want the cursor to be positioned at the start of the first field, set both cursor-row and cursor-column to 1.

Where the defined position is on a suppressed character or insertion symbol in a numeric edited field, the cursor moves to the first available character to the right. If there is no further data item, the cursor returns to the first data item on the screen.

When the ACCEPT is terminated, if the value in cursor-position at the start of the ACCEPT was valid, the position of the cursor when the terminating key is pressed is returned in cursor-position. This might not be the same position as the current cursor position, since the enhanced ACCEPT/DISPLAY syntax usually moves the cursor to the end of the field upon termination of an ACCEPT operation to allow relative positioned ACCEPT statements to start at the correct point on the screen.

If the value in cursor-position at the start of the ACCEPT operation was invalid, then, when the ACCEPT operation is terminated, the contents of cursor-position are unchanged.

One example of the use of this facility is that in menu-type operations, the operator need only move the cursor to a position on the screen corresponding to the selection required. The operator's choice can be determined by the returned value of cursor-position.

Parent topic: Accepting and Displaying Screen Section Items


Accepting and Displaying Data on Large Screens

Screens larger than 25 lines are detected automatically by your COBOL system.

Programs using ANSI ACCEPT/DISPLAY statements, enhanced ACCEPT/DISPLAY syntax, Screen Section and the COBOL system library routines should run correctly on large screens. If an application is developed for a screen larger than the screen it is run on, the extra lines of a multiple-field ACCEPT or DISPLAY are lost. In addition, if the position specified by the AT clause of an ACCEPT or DISPLAY statement is off the screen, the screen is scrolled up by one line.

  • CONTROL Clause
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


CONTROL Clause

The CONTROL clause enables attributes associated with a Screen Section item to be defined at run time. You specify this clause within the WITH phrase of Format 2 of the screen handling ACCEPT and DISPLAY statements, and within Adis ACCEPT and DISPLAY statements.

Parent topic: Accepting and Displaying Data on Large Screens


Keyboard Handling Via Adis

The following subjects are described in this section:

  • Types of Adis Keys
  • The CRT STATUS Clause
  • Normal termination of an ACCEPT operation
  • Default User Function Keys
  • Using the Adis Keys
  • Defining a Key in Both the User and Adis Key Lists
  • Data Key Handling
  • Shift Key Handling
  • Lock Key Handling
Parent topic: Enhanced ACCEPT/DISPLAY Syntax


Types of Adis Keys

There are several types of Adis keys: function keys, data keys, shift keys, and lock keys.

Adis Keys
Adis Function Keys User Function Keys Data Keys Shift Keys Lock Keys
  • cursor keys
  • Tab
  • Backspace
  • Enter
  • Del
  • F1…F12
  • Esc
  • ASCII codes 32-255
  • Ctrl
  • Alt
  • Insert
  • Shift
  • Caps Lock
  • Num Lock
  • Scroll Lock
  • Function Keys
  • Data Keys
  • Shift Keys
  • Lock Keys
  • Function Key Handling
Parent topic: Keyboard Handling Via Adis


Function Keys

The most general definition of a function key is any key you do not find on a typewriter keyboard. This definition includes explicit function keys on the keyboard (usually labeled F1, F2 ... F12) and such keys as Esc, the cursor keys, Tab, and Backspace. Enter is also treated as a function key, but with special considerations.

These function keys are divided into two groups:

  • Adis function keys. These are used by Adis during the execution of an ACCEPT statement. This includes the cursor keys, Tab, Backspace, Del and Enter.

    Normally, these keys operate as defined during an ACCEPT operation. For example, the left key moves the cursor to the left, Backspace erases the previous character, and so on. With the exception of the Enter key, they do not normally terminate the ACCEPT operation. However, you can make these keys terminate the ACCEPT operation if required.

  • User function keys. These are so called because you can decide what they are used for when you are writing an application. There is no predefined action assigned to these keys. The user function keys generally include the keys labeled F1,F2 ...F12, the Escape key, and any other special keys that are on the keyboard.
Parent topic: Types of Adis Keys


Data Keys

Data keys are those keys that generate characters that are in the extended ASCII character set; that is, those with ASCII codes in the range 128 to 255. During an ACCEPT operation, pressing one of these keys simply places the character into the field. However, it is possible to disable a key completely or make it terminate the ACCEPT operation (similar to the action of a function key).

ASCII codes in the range 0 to 31 can be considered as either data keys or control keys. For most purposes, they are treated as control keys and are disabled as data keys.

Parent topic: Types of Adis Keys


Shift Keys

A shift key is a key whose depression and release are regarded as separate events. Examples of shift keys in the enhanced ACCEPT/DISPLAY syntax are Alt, Ctrl and Shift. See the section Shift Key Handling for more information on shift keys.

Parent topic: Types of Adis Keys
Related reference
Shift Key Handling


Lock Keys

A lock key is a key whose state is toggled when it is pressed. Examples of lock keys are Caps Lock, Insert, Num Lock and Scroll Lock. See the section Lock Key Handling for more information on lock keys.

Parent topic: Types of Adis Keys
Related reference
Lock Key Handling


Function Key Handling

This section describes how to use function keys in this COBOL system. It describes the portable method that works on all environments. There is another method, using the x"B0" routine, which is not described here as it is machine dependent. If you are using this routine, see the section Conflict with the x"B0" COBOL System Library Routine for details of how this could cause problems with certain configurations.

Parent topic: Types of Adis Keys
Related reference
Conflict With the x"B0" COBOL System Library Routine


The CRT STATUS Clause

If you decide that you want your application to use function keys, it is highly likely that you will want to be able to determine exactly which key has been pressed. To do this you need to include the CRT STATUS clause in the Special-Names paragraph of your program as follows:

 special-names.
     crt status is key-status.

where:

key-status
is a three-byte data item in the Working-Storage Section of your program with the following definition:
01 key-status.
    03 key-type     pic x.
    03 key-code-1   pic 9(2) comp-x.
    03 key-code-2   pic 9(2) comp-x.

Whenever an ACCEPT statement is executed, key-status is set to indicate how the ACCEPT was terminated. The exact usage of the individual fields in key-status is described later. However, in general they have the following uses:

key-type
is how the ACCEPT was terminated. The values returned are as follows :
"0"
is a normal termination of the ACCEPT
"1"
is termination by a user function key
"2"
is termination by an Adis key
"3"
is termination by an 8-bit data key
"4"
is termination by a 16-bit data key
"5"
is termination by a shift key
"6"
is termination by a lock key
"9"
is termination by a lock key

These different values are described fully later in this section.

key-code-1
is the number of the key that terminated the ACCEPT operation. The exact meaning of this number depends on the value returned in key-type.
key-code-2
if key-type and key-code-1 are 0, key-code-2 contains the raw keyboard code for the key that terminated the ACCEPT operation. Where a sequence of keystrokes rather than a single key has been configured to perform a single function, only the code for the first keystroke is returned.

If key-type is 4, key-code-2 contains the second byte of the character which caused the ACCEPT operation to terminate.

Otherwise, the contents of key-code-2 are undefined.

Parent topic: Keyboard Handling Via Adis


Normal termination of an ACCEPT operation

Normal termination of an ACCEPT operation returns a value of 0 in key-type, and in key-code-1 it returns a value of:

48
The ASCII code for 0, when the ACCEPT operation is terminated by pressing Enter.
1
When an auto-skip in the last field on the screen terminates the ACCEPT operation.

Example

     accept data-item at 0101
     if key-type = "0"
     and key-code-1 = 48
       display "Terminated by return key"
     else
       display "Terminated by auto-skip last field"
     end-if.
Parent topic: Keyboard Handling Via Adis


Default User Function Keys

There are up to 128 user function keys. The defaults supplied with your COBOL system differ on different operating environments, but some keys are standard.

Keystroke | User Function Key Number
Escape | 0
F1 | 1
F2 | 2
F3 | 3
F4 | 4
F5 | 5
F6 | 6
F7 | 7
F8 | 8
F9 | 9
F10 | 10

Your keyboard might not have these keys, but if they are there, they should be configured as above. Additionally, the following user function keys might be defined:

Keystroke | User Function Key Number
Shift+F1 - Shift+F10 | 11 - 20
Ctrl+F1 - Ctrl+F10 | 21 - 30
Alt+F1 - Alt+F10 | 31 - 40
Alt+1 - Alt+9 | 41 - 49
Alt+0 | 50
Alt+- | 51
Alt+= | 52
PgUp | 53
PgDn | 54
Ctrl+PgUp | 55
Ctrl+PgDn | 56
Alt+A - Alt+Z | 65 - 90
F11 | 91
F12 | 92
Shift+F11 | 93
Shift+F12 | 94
Ctrl+F11 | 95
Ctrl+F12 | 96
Alt+F11 | 97
Alt+F12 | 98
  • Enabling and Disabling User Function Keys
  • Detecting User Function Keys
  • Using the Compatibility Key List for Adis Keys
  • The User Function Keys and Validation Clauses
Parent topic: Keyboard Handling Via Adis


Enabling and Disabling User Function Keys

By default, the Adis function keys are enabled, although you can disable them or make them act as function keys instead.

However, before you can use the user function keys, they must be enabled. If a user key is enabled, it terminates the ACCEPT operation when it is pressed. If the key is disabled, the key is rejected and the bell rung.

Use the following call to selectively enable and disable the user function keys:

 call x"AF" using   set-bit-pairs
                    user-key-control

where set-bit-pairs and user-key-control are defined in the Working-Storage Section of your program as follows:

01 set-bit-pairs          pic 9(2) comp-x value 1.
01 user-key-control.
   03 user-key-setting    pic 9(2) comp-x.
   03 filler              pic x value "1".
   03 first-user-key      pic 9(2) comp-x.
   03 number-of-keys      pic 9(2) comp-x.

where:

user-key-setting
is set to 0 to disable keys or 1 to enable keys.
first-user-key
is the number of the first key to be enabled or disabled.
number-of-keys
is the number of consecutive keys to enable or disable.

Function keys are enabled or disabled until explicitly changed by another call to x"AF", or until the application terminates. Calls to enable or disable function keys are cumulative. For example, if you call x"AF" to enable function key F1, then make a second call to enable F10, both keys are enabled.

Example

The following code enables the Escape key and function keys F1 and F10, but disables all other user function keys:

* Enable Escape key
     move 1 to user-key-setting
     move 0 to first-user-key
     move 1 to number-of-keys
     call x"AF" using set-bit-pairs
        user-key-control
* Disable 126 keys starting from key 1
     move 0 to user-key-setting
     move 1 to first-user-key
     move 126 to number-of-keys
     call x"AF" using set-bit-pairs
        user-key-control.
* Enable F1 and F10.
     move 1 to user-key-setting
* Enable F1.
     move 1 to first-user-key
     move 1 to number-of-keys
     call x"AF" using set-bit-pairs
        user-key-control
* Enable F10
     move 10 to first-user-key
     call x"AF" using set-bit-pairs
        user-key-control
Parent topic: Default User Function Keys
Related reference
Enabling and Disabling Adis Keys


Detecting User Function Keys

If you press an enabled user function key during an ACCEPT operation, the ACCEPT operation is terminated and the fields in key-status are set as follows:

key-type
is "1"
key-code-1
is set to the number of the user key that was pressed.
key-code-2
is undefined.
Parent topic: Default User Function Keys


Using the Compatibility Key List for Adis Keys

Most of the time, you need use only the one list of user function keys. However, if you are converting from another dialect of COBOL, you might have some programs that expect the values returned from the default user key list and some programs that expect the values returned by the function keys in some other dialect of COBOL. To enable you to do this, the compatibility key list is provided. This works in exactly the same way as the normal key list. Any program can use either the default user key list or the compatibility list, but not both.

If you want all programs in your system to use the compatibility key list, you can use Adiscf to select its use. If you want different programs to use different lists, insert the following call into your programs to select the list you require:

call x"AF" using   set-bit-pairs
                   key-list-selection

where set-bit-pairs and key-list-selection are defined in the Working-Storage Section of your program as follows:

01 set-bit-pairs      pic 9(2) comp-x value 1.
01 key-list-selection.
   03 key-list-number pic 9(2) comp-x.
   03 filler          pic x value "1".
   03 filler          pic 9(2) comp-x value 87.
   03 filler          pic 9(2) comp-x value 1.

where key-list-number is set to one of the following values:

1
To select the default user function key list.
2
To select the compatibility key list.
Parent topic: Default User Function Keys


The User Function Keys and Validation Clauses

Normally, if a validation clause, such as FULL or REQUIRED, is specified in an ACCEPT statement, that clause must be satisfied before you can leave the field. For example, when the statement:

     accept data-item with required

is executed, you are not allowed to terminate the ACCEPT operation unless something has been entered into the field.

However, if an enabled user function key is pressed during an ACCEPT operation, it is regarded as an exception and terminates the ACCEPT operation even if the validation clause has not been satisfied. If you do not want function keys to terminate the ACCEPT operation without satisfying validation clauses, you can set ACCEPT/DISPLAY option 9 using Adiscf.

Parent topic: Default User Function Keys


Using the Adis Keys

You must appreciate the distinction between the keys that perform the functions, and the functions themselves; there is actually a soft mapping between the keys and the functions they perform. This means that you can change the function that any of the enhanced ACCEPT/DISPLAY syntax keys perform.

  • Key Mappings for Standard Adis Functions
  • Key Mappings for Special Adis Functions
  • Changing Adis Key Mappings from a Program
  • Conflict With the x"B0" COBOL System Library Routine
  • Enabling and Disabling Adis Keys
  • Detecting Adis Function Keys
Parent topic: Keyboard Handling Via Adis


Key Mappings for Standard Adis Functions

There are 28 enhanced ACCEPT/DISPLAY syntax keys (numbered 0 through 27). Each key is mapped onto a function, so that when a key is pressed, it performs the function it has been mapped to.

You must also be aware that the enhanced ACCEPT/DISPLAY syntax keys themselves are given names. However, this name is used to distinguish the different keys; it might not necessarily describe the function the key actually performs. The following list gives the names of the keys and the keystrokes required to obtain them. You might have a different configuration for your environment.

Key No. | Function | Default Key/Keystroke
0 | Terminate ACCEPT | None
1 | Terminate program | Ctrl+K
2 | Carriage return | Enter
3 | Cursor left | Cursor Left
4 | Cursor right | Cursor Right
5 | Cursor up | Cursor Up
6 | Cursor down | Cursor Down
7 | Home | Home
8 | Tab | Tab
9 | Backtab | Backtab
10 | End | End
11 | Next field | None
12 | Previous field | None
13 | Change case | Ctrl+F
14 | Erase character | Backspace
15 | Retype character | Ctrl+Y
16 | Insert character | Ctrl+O
17 | Delete character | Del
18 | Restore character | Ctrl+R
19 | Clear to end of field | Ctrl+Z
20 | Clear field | Ctrl+X
21 | Clear to end of screen | Ctrl+End
22 | Clear screen | Ctrl+Home
23 | Set Insert mode | Insert
24 | Set Replace mode | None
25 | Reset field | Ctrl+A
26 | Start of field | None
27 | Move to mouse position | None
Note:

The carriage return (CR) key is referred to here as the Enter key. On some keyboards, there is a CR key and an Enter key. In this case, the enhanced ACCEPT/DISPLAY syntax carriage return key should be set up as CR and the enhanced ACCEPT/DISPLAY syntax key "Terminate Accept" should be set up as Enter.

  • Standard Adis Key Functions
  • Mapping the Adis Keys to the Functions
  • Special Mapping Functions in Adis
Parent topic: Using the Adis Keys
Related reference
Standard Adis Key Functions


Standard Adis Key Functions

Below is a full list of the functions performed by the Adis keys. Functions 0 through 27 are simple functions. Functions 55 to 62 are complex functions which can perform different actions depending on some state. For example, those functions provided for RM compatibility have a different action depending on whether or not the UPDATE clause is specified in the ACCEPT statement.

Function 0, Terminate Accept
This function terminates an ACCEPT operation. The first byte of any CRT STATUS field (defined as pic 9 display) is set to the character "0" (ASCII 48) and the second byte (defined as PIC 9(2) COMP-X) is set to 0.
Function 1, Terminate Program
If enabled, this function causes the Abort confirmation message to be output to the screen and a character requested from the user. If the user responds with anything other than "Y" or "y", the message is blanked and normal processing of the ACCEPT operation continues. If the user presses "Y", or "y" or no message is configured, the program is terminated as if a STOP RUN had been executed.
Function 2, Carriage Return
The cursor is moved to the first character position that occurs within a field at or after column one on the next or subsequent line of the screen. If there is no such field, no action takes place.
Function 3, Cursor Left
Moves the cursor to the previous character in the field. If the current character is the first character of the field, the cursor is moved to the last character of the preceding field. If the current character is the first character of the first field on the screen, an error is signalled to the user.
Function 4, Cursor Right
Moves the cursor to the next character in the field. If the current character is the last character of the field, the cursor is moved to the first character of the next field. If the current character is the last character of the last field on the screen, an error is signalled to the user.
Function 5, Cursor Up
The cursor is moved to the next unprotected character position; that is, a position that occurs in a field in direct line above the current position.
Function 6, Cursor Down
Moves the cursor to the next unprotected character position in direct line below the current position.

For cursor up and cursor down (functions 5 and 6), cursor movement functions follow the same rules as items defined using the CURSOR IS clause if a position is found that is within a field but is protected by virtue of containing an insertion character or a suppressed numeric digit. In such situations the cursor is moved right to the first unprotected character position within that field. If all such positions are protected, the cursor is moved to the last unprotected character position within the field.

Function 7, Move to the Start of the Screen
Moves the cursor to the first unprotected character position of the current screen.
Function 8, Move to Next Tab Position
Moves the cursor to the next column Tab stop position. The cursor is never moved forward further than the first available character position after the end of the current field (or line in multi-line fields).
Function 9, Move to Previous Tab Position
Moves the cursor to the previous column Tab stop position. The cursor is never moved back further than the last available character position before the start of the current field (or line in multi-line fields).
Function 10, End
Moves the cursor to unprotected character positions in the order:
  1. The last character position of the current line in a multi-line alphanumeric field.
  2. The last character position of the current field.
  3. The first character position of the last field on the current screen.
Function 11,Move to Next Field
Moves the cursor to the first unprotected character position of the next field on the screen. If already in the last field and auto-skip out of an ACCEPT is not enabled for this key, the cursor is positioned to the last character of the field and the request is considered to have been unsuccessful.
Function 12, Move to Previous Field
Moves the cursor to the first unprotected character position in the current field. If the cursor is already at the first position, it moves to the first character position of the previous field. If the cursor is already at the first character of the first field, the request is considered unsuccessful.
Function 13, Change Case of Current Character
Retrieves the character at the current cursor position, changes its case if alphabetic and processes it as if it were just keyed. The function is not permitted in numeric or Kanji fields. Changing case on a non-alphabetic character is treated as equivalent to simply typing the character again. The function cannot be used to override the fold to upper-case mechanism which simply re-inverts the case if an attempt is made to fold a character to lower-case.
Function 14, Backspace Character
Moves the cursor to the unprotected character position logically preceding the current one, pushes the character there into the retype buffer and replaces it with one popped from the restore buffer. When in insert mode, removal is achieved by moving the remaining characters in the field along one position and popping a character from the overflow buffer to occupy the gap at the end.

In either case, if the relevant buffer is empty or the next character is not valid for the field, a space or zero (according to type of field) is used. Action is slightly different when to the left of the decimal point in numeric fields, but the logical effect is the same - that of reversing the effect of typing a character.

One unusual effect emanating from the logical requirements is that where the cursor was unable to move out of a field when a character was keyed into the last position, the cursor is not moved prior to character replacement.

Function 15, Retype Character
Pops a character from the restore buffer and proceeds as if it had been received from the keyboard. An error is signalled if the buffer is empty or the character is illegal in the current field.
Function 16, Insert Single Character
Places a space or zero character (according to the field type) under the current cursor position, making room for it by shuffling characters along the field. Except when to the left of the decimal point in numeric fields, significant characters can be pushed off the end (the character that is lost is pushed into the overflow buffer and an error is signalled to the user). When to the left of the decimal point in a numeric field, an attempted insertion is unsuccessful if a significant digit would otherwise be lost or if the cursor is on the leftmost digit position (since the functionality of numeric insertion operations in these circumstances implies a requirement to insert before the current digit).
Function 17, Delete Character
Pushes the character currently under the cursor into the restore buffer, moving the remaining characters in the field left by one position and pops a character from the overflow buffer to occupy the gap at the end. If the overflow buffer is empty, a space or zero (according to type of field) is used. Action is slightly different when to the left of the decimal point in numeric fields, but the logical effect is normally the same - that of reversing the effect of inserting or restoring a character. If the field is numeric, the character is discarded and not pushed into the restore buffer.
Function 18, Restore Character
The effect and restrictions of this function are identical to insert character (function 16 above) except that the character to be inserted is popped from the restore buffer. An error is signalled if the buffer is empty or if the character popped is not valid in the current field. This function is not available in numeric fields.
Function 19, Clear to End of Field
Characters at, and to the right of, the current cursor position in the current field are pushed into the restore buffer and replaced by spaces or zeros (according to the type of field). Operation is from left to right and includes trailing nonsignificant spaces and zeros. The cursor does not move. Multi-line alphanumeric fields are treated as being split at line boundaries for the purposes of this operation.
Function 20, Clear Field
The entire contents of the current field (or the current line in the case of a multi-line alphanumeric field) are pushed into the restore buffer as for clear to end of field on the first character position. The field then has spaces (alphanumerics) or zeros (numerics) moved to it and the cursor is placed on its initial position as defined for the type and format of the field.
Function 21, Clear to End of Screen
The action defined for clear to end of field is performed on the current field (or line), and the following fields have spaces or zeros moved to them, as appropriate.
Function 22, Clear Screen
All fields on the screen have spaces or zeros (as appropriate) moved to them and the cursor is moved to its home position (the first unprotected character of the first field). The restore and retype buffers are cleared by this function.
Function 23, Set Insert Mode
Sets the current editing mode to insert and displays or clears any relevant configured indicators. Any Off end of field indicator is cleared by this function.
Function 24, Set Replace Mode
Sets the current editing mode to replace, and displays or clears any relevant configured indicators. Any Off end of field indicator is cleared by this function.

The concept of insert mode and replace mode apply only in alphanumeric fields. The mode flag is therefore suppressed while in numeric fields and reinstated on moving to another alphanumeric field.

Replace mode is sometimes known as overtype mode.

Function 25, Undo
Reinstates the current field (or line) to its state when the cursor last moved into it. Operations involving hidden MOVE operations out of the current field (clear screen, clear to end of screen) can cause edits to cease to be undoable as well as the more obvious operations such as field-tab and auto-skip out.
Function 26, Home
Moves the cursor to unprotected character positions in the order:
  1. The first character position of the current line in a multi-line alphanumeric field.
  2. The first character position of the current field.
  3. The first character position of the current screen.
Parent topic: Key Mappings for Standard Adis Functions
Parent topic: Keyboard Configuration Utility (Keybcf)
Related concepts
Key Mappings for Standard Adis Functions


Mapping the Adis Keys to the Functions

In general, the enhanced ACCEPT/DISPLAY syntax keys are mapped onto the function of the same name. Therefore, the <cursor left> key moves the cursor to the left, the Backspace key erases a character and so on. However, there are some keys that are mapped onto different functions by default.

Key | Function
Carriage return | Terminate ACCEPT operation, function 0
Tab | Move to next field, function 11
Backtab | Move to previous field, function 12
Set Insert mode | Insert Toggle, function 58

Therefore, when you press Enter on your keyboard, it terminates an ACCEPT operation, because Enter is mapped onto carriage return, and carriage return causes an ACCEPT operation to be terminated.

Note:

Because functions are mapped, you need to reference keys 11 and 12 in order to enable/disable Adis keys 8 and 9 respectively using the x"AF" call-by-number routine.

At this stage, the idea of mapping keys may seem an unnecessary complication. Where it becomes really useful is in the emulation of other dialects of COBOL. For example, in Microsoft COBOL V2.2, the Enter key moves to the next field rather than terminating an ACCEPT operation. This is easy to emulate by simply changing the mapping for key 2 (carriage return) from 0 (terminate ACCEPT) to 11 (move to next field). If you look at the function mappings screen in Adiscf for the Microsoft COBOL V2.2 compatibility configuration, you can see that this has been done.

The RM/COBOL V2.0 compatibility configuration contains even more changes to the default mappings to emulate the action of keys in RM/COBOL.

If a key is mapped on to a value of 255, that key does not perform any function during an ACCEPT operation.

Parent topic: Key Mappings for Standard Adis Functions


Special Mapping Functions in Adis

55 | RM Clear Field | This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Cursor Home (function 7) is performed, otherwise Clear Field (function 20) is performed.
56 | RM Backspace | This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Cursor Left (function 3) is performed, otherwise Backspace Character (function 24) is performed.
57 | RM Tab | This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Terminate Accept (function 0) is performed, otherwise there is no action.
58 | Insert Toggle | If the current mode is insert mode, Set Replace Mode (function 24) is performed, otherwise Set Insert Mode (function 23) is performed.
59 | Replace Toggle | If the current mode is replace mode, Set Insert Mode (function 23) is performed, otherwise Set Replace Mode (function 24) is performed.
60 | Forward Tab | If in a multi-field ACCEPT, Move to next field (function 11) is performed, otherwise Move to next tab stop (function 8) is performed.
61 | Backward Tab | If in a multi-field ACCEPT, Move to previous field (function 12) is performed, otherwise Move to previous Tab stop (function 9) is performed.
62 | Restore | If the current field is numeric or the restore buffer is empty, Insert Single Character (function 16) is performed, otherwise Restore Character (function 18) is performed.
255 | Undefined Mapping | This value is used if no key has been set up for a particular function.
Parent topic: Key Mappings for Standard Adis Functions
Parent topic: Keyboard Configuration Utility (Keybcf)
Related concepts
Key Mappings for Special Adis Functions


Key Mappings for Special Adis Functions

All of the standard functions in the enhanced ACCEPT/DISPLAY syntax key mappings always perform the same function, regardless of context. For example, the move to next field function always attempts to move to the next field. However, there are some functions that behave differently depending on the context. These functions are described in the section Special Mapping Functions in Adis earlier in this chapter.

For example, the Set Insert mode key (key number 23) is normally mapped to function 58 (Insert toggle). This means that pressing the Insert key toggles between Insert and Replace mode.

Parent topic: Using the Adis Keys
Related reference
Special Mapping Functions in Adis


Changing Adis Key Mappings from a Program

Use the following call:

call x"AF" using       set-map-byte
                       adis-key-mapping

where set-map-byte and adis-key-mapping are defined in the Working-Storage Section of your program as follows:

01 set-map-byte       pic 9(2) comp-x value 3.
01 adis-key-mapping.
   03 adis-map-byte   pic 9(2) comp-x.
   03 adis-key-number pic 9(2) comp-x.

where:

adis-map-byte
is set to the number of the function you wish the key to be mapped to.
adis-key-number
is set to the number of the key you wish to change.

Example

The following code changes the action of the Backspace key (key number 14) to simply move the cursor to the left (function 3), and changes the Tab key (key number 8) to perform the Tab function (function 8):

* Change mapping of Backspace key
     move 14 to adis-key-number
     move 3 to adis-mapping-byte
     call x"AF" using set-map-byte
                      adis-key-mapping
* Change mapping of the tab key
     move 8 to adis-key-number
     move 8 to adis-mapping-byte
     call x"AF" using set-map-byte
                      adis-key-mapping
Parent topic: Using the Adis Keys


Conflict With the x"B0" COBOL System Library Routine

The x"B0" COBOL system library routine is an alternative method of defining function keys. It is not supported under UNIX and some other environments. However, we recommend that you use the method of detecting function keys defined in the section Detecting Adis Function Keys, rather than the x"B0" routine.

In general, you can use the x"B0" routine to define function keys which terminate an ACCEPT operation. However, there is one limitation. If you use x"B0", the carriage return key must be mapped on to the terminate ACCEPT function. This is the default for this product. If you change the mapping of carriage return or use a configuration that changes the mapping (such as Microsoft COBOL V2.2 or IBM COBOL 1.0 compatibility), then any key set up by the x"B0" call does not terminate the ACCEPT operation. Instead, it performs the function that carriage return has been mapped onto.

Parent topic: Using the Adis Keys
Related concepts
Function Key Handling
Related reference
Detecting Adis Function Keys


Enabling and Disabling Adis Keys

Use the following call:

 call x"AF" using  set-bit-pairs
                     adis-key-control

where set-bit-pairs and adis-key-control are defined in the Working-Storage Section of your program as follows:

01 set-bit-pairs          pic 9(2) comp-x value 1.
01 adis-key-control.
   03 adis-key-setting    pic 9(2) comp-x.
   03                     pic x value "2".
   03 first-adis-key      pic 9(2) comp-x.
   03 number-of-adis-keys pic 9(2) comp-x.

where:

adis-key-setting
defines the action of the keys affected, as follows:
0
the keys are disabled. If the key is pressed during an ACCEPT operation, the key is rejected.
1
the key acts like a function key. If pressed during an ACCEPT operation, the ACCEPT operation is terminated.
2
the key performs its normal action during an ACCEPT operation. This is the default.
3
the key performs its normal action unless it causes the cursor to leave the current field. If this happens, it behaves like a function key.
first-adis-key
is the number of the first key to be affected.
number-of-adis-keys
is the number of consecutive keys to be affected.
Parent topic: Using the Adis Keys
Related concepts
Enabling and Disabling User Function Keys


Detecting Adis Function Keys

If you have set up an Adis key to act as a function key, it terminates the ACCEPT operation, and key-status is returned with the following values:

Data Item | Setting
key-type | "2"
key-code-1 | Set to the number of the pressed enhanced ACCEPT/DISPLAY syntax key. This is the number of the key not the number of the function the key has been mapped to.
key-code-2 | Undefined.

Example

The following code sets up Tab and Backtab to act as function keys and the cursor-left and cursor-right keys to act as function keys if they cause the cursor to leave the field.

* Set up Tab (key 8) and Backtab (Key 9) to act as function
* keys
     move 1 to adis-key-setting
     move 8 to first-adis-key
     move 2 to number-of-adis-keys
     call x"AF" using set-bit-pairs
                      adis-key-control
* Set up cursor-left (key 3) and cursor-right (key 4) to act
* as function keys ONLY if they cause the cursor to leave
* the field.
     move 3 to adis-key-setting
     move 3 to first-adis-key
     move 2 to number-of-adis-keys
     call x"AF" using set-bit-pairs
                      adis-key-control
     accept data-item at 0101

     if key-type = "2"
         evaluate key-code-1
          when 3  display "cursor-left caused the cursor " &
                          "to leave the field"
          when 4  display "cursor right caused the cursor " &
                          "to leave the field"
          when 8  display "the tab key was pressed"
          when 9  display "the back tab key was pressed"
         end-evaluate
     end-if.
Parent topic: Using the Adis Keys
Related concepts
Conflict With the x"B0" COBOL System Library Routine


Defining a Key in Both the User and Adis Key Lists

In general, a particular key is defined in either the User key list or the enhanced ACCEPT/DISPLAY syntax key list, but not both. However, there is no reason why you should not define the same key in both lists.

If a key that is defined in both lists is pressed during an ACCEPT operation, the sequence of actions is as follows:

Parent topic: Keyboard Handling Via Adis


Data Key Handling

The data keys are the 256 keys in the extended ASCII character set. Normally, when you press one of these keys during an ACCEPT operation, the character is simply put straight into the field. The exception to this is the keys with ASCII codes in the range 0 to 31, that is, the control keys. These are generally disabled.

  • Controlling the Data Keys
  • Detecting Data Keys Set Up to Act as Function Keys
Parent topic: Keyboard Handling Via Adis


Controlling the Data Keys

Like most other keys on the keyboard, it is possible to disable data keys or make them act like function keys, that is, terminate the ACCEPT operation. To do this, use the following call:

call x"AF" using    set-bit-pairs
                    data-key-control

where set-bit-pairs and data-key-control are defined in the Working-Storage Section of your program as follows:

 01 set-bit-pairs               pic 9(2) comp-x value 1.
 01 data-key-control.
    03 data-key-setting         pic 9(2) comp-x.
    03                          pic x value "3".
    03 first-data-key           pic x.
    03 number-of-data-keys      pic 9(2) comp-x.

The fields in data-key-control should be set up as follows:

data-key-setting
Defines the action of the keys affected, as follows:
0
The key is disabled. If it is pressed during an ACCEPT operation, the bell is rung and the key rejected.
1
The key acts as a function key. It terminatesthe ACCEPT operation.
2
The character is simply entered into thefield. This is the default.
first-data-key
The first character to be affected.
number-of-data-keys
The number of characters to be affected.
Parent topic: Data Key Handling


Detecting Data Keys Set Up to Act as Function Keys

If a data key has been set up to act as a function key, it terminates the ACCEPT operation when pressed, and key-status is set up as follows:

Data Item | Setting
key-type | "3"
key-code-1 | Set to the ASCII code of the key that was pressed.
key-code-2 | Undefined.

Example

* Set up the characters "A" through "Z" to terminate the
* ACCEPT operation
     move 1 to data-key-setting
     move "A" to first-data-key
     move 26 to number-of-data-keys
     call x"AF" using set-bit-pairs
                      data-key-control

     accept data-item at 0101
     if key-type = "3"
         evaluate key-code-1
          when 65    display "A pressed"
          when 66    display "B pressed"
          when 90    display "Z pressed"
         end-evaluate
     end-if
      .
Parent topic: Data Key Handling


Shift Key Handling

Adis provides a number of routines to enable an applicaton to make use of the shift key capabilities of a keyboard.

Most UNIX terminals cannot detect when the Alt or Ctrl keys are pressed unless they are pressed in conjunction with another valid key. You should, therefore, avoid using these keys by themselves in portable applications. Alternatively, the key sequences /a and /c can be used to simulate the use of Alt and Ctrl keys.

  • Determining Available Shift Keys
  • Detecting the Current State of the Shift Keys
  • Enabling or Disabling Shift Keys to Terminate an ACCEPT
Parent topic: Keyboard Handling Via Adis
Related concepts
Shift Keys


Determining Available Shift Keys

This routine enables you to find out which of the shift keys are detectable as unique events.

Use the following call to determine which shift keys are available to your program:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

 01 adis-function        pic 9(2) comp-x.
 01 adis-parameter       pic 9(4) comp-x.

where:

adis-function
is 44.
adis-parameter
returns the shift keys that are available to your program. The 16 bits in adis-parameter refer to shift keys as follows, with bit 0 the least significant:
Bit | Associated Key
4 - 15 | Reserved
3 | Alt
2 | Ctrl
1 | Left-shift
0 | Right-shift
Parent topic: Shift Key Handling


Detecting the Current State of the Shift Keys

This routine enables you to determine which, if any, of the shift keys are currently pressed.

Use the following call to determine which of the shift keys are currently pressed:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

 01 adis-function       pic 9(2) comp-x.
 01 adis-parameter      pic 9(4) comp-x.

where:

adis-function
is 46.
adis-parameter
returns which of the shift keys are currently pressed. The 16 bits in adis-parameter refer to shift keys as follows, with bit 0 the least significant:
Bit | Associated Key
4 - 15 | Reserved
3 | Alt
2 | Ctrl
1 | Left-shift
0 | Right-shift
Parent topic: Shift Key Handling


Enabling or Disabling Shift Keys to Terminate an ACCEPT

By default, all of the shift keys are disabled during an ACCEPT operation, or the x"AF" call used to obtain a key. However, this routine enables you to enable or disable the shift keys dynamically.

Use the following call to enable or disable shift keys:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

  01 adis-function              pic 9(2) comp-x.
  01 adis-parameter.
     03 shift-key-setting       pic 9(2) comp-x.
     03 filler                  pic x value "4".
     03 first-shift-key         pic 9(2) comp-x.
     03 number-of-shift-keys    pic 9(2) comp-x.
where:
adis-function
is 1.
shift-key-setting
is the action of the keys affected, as follows:
0
the keys are disabled. If the key is pressed it will be ignored.
1
the keys are enabled.
first-shift-key
is the number of the first key to be affected. The events to enable are numbered as follows:
0
Alt pressed
1
Alt released
2
Ctrl pressed
3
Ctrl released
4
Left-shift pressed
5
Left-shift released
6
Right-shift pressed
7
Right-shift released
number-of-shift-keys
is the number of consecutive keys to be affected.

The following code enables Ctrl so that it can terminate an ACCEPT operation, then checks to see whether an ACCEPT operation was terminated by Ctrl:

* Enable Ctrl
      move 1 to shift-key-setting
      move 2 to first-shift-key
      move 1 to number-of-shift-keys
      move 1 to adis-function
      call x"AF" using adis-function
                       adis-parameter
      accept data-item at 0101
      if key-type = "5"
          evaluate key-code-1
           when 2     display "Ctrl pressed"
           when other display "Other shift key pressed"
          end-evaluate
      end-if.
Parent topic: Shift Key Handling


Lock Key Handling

Adis provides a number of routines to enable an applicaton to make use of the lock key capabilities of a keyboard.

  • Determining Available Lock Keys
  • Detecting the Current State of the Lock Keys
  • Enabling or Disabling Lock Keys to Terminate an ACCEPT
  • Converting Accepted Characters to Uppercase
Parent topic: Keyboard Handling Via Adis
Related concepts
Lock Keys


Determining Available Lock Keys

This routine enables you to find out which of the lock keys are detectable as unique events.

Use the following call to determine which lock keys are available to your program:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

 01 adis-function       pic 9(2) comp-x.
 01 adis-parameter      pic 9(4) comp-x.

where:

adis-function
is 45.
adis-parameter
is the lock keys available to your program. The 16 bits in adis-parameter refer to lock keys as follows, with bit 0 the least significant:
Bit | Associated Key
4 - 15 | Reserved
3 | Ins Lock
2 | Caps Lock
1 | Num Lock
0 | Scroll Lock

A value of 1 for any particular bit indicates that the associated key is uniquely detectable.

Parent topic: Lock Key Handling


Detecting the Current State of the Lock Keys

This routine enables you to determine which, if any, of the lock keys are currently active. For example, the Scroll Lock key is active when scroll lock is on.

Use the following call to determine which of the lock keys are currently active:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

 01 adis-function        pic 9(2) comp-x.
 01 adis-parameter       pic 9(4) comp-x.

where:

adis-function
is 47.
adis-parameter
returns which of the lock keys are currently active. The 16 bits in adis-parameter refer to lock keys as follows, with bit 0 the least significant:
Bit | Associated Key
4 - 15 | Reserved
3 | Ins Lock
2 | Caps Lock
1 | Num Lock
0 | Scroll Lock
Parent topic: Lock Key Handling


Enabling or Disabling Lock Keys to Terminate an ACCEPT

By default, all of the lock keys are disabled during an ACCEPT operation, or the x"AF" call used to obtain a key. However, this routine enables you to enable or disable the lock keys dynamically.

Use the following call to enable or disable lock keys:

call x"AF" using    adis-function
                    adis-parameter

where adis-function and adis-parameter are defined in the Working-Storage Section of your program as follows:

 01 adis-function             pic 9(2) comp-x.
 01 adis-parameter.
    03 lock-key-setting       pic 9(2) comp-x.
    03 filler                 pic x value "5".
    03 first-lock-key         pic 9(2) comp-x.
    03 number-of-lock-keys    pic 9(2) comp-x.

where:

adis-function
is 1.
lock-key-setting
is the action of the keys affected, as follows:
0
the keys are disabled. If the key is pressed it will be ignored.
1
the keys are enabled.
first-lock-key
is the number of the first key to be affected. The keys to enable are numbered as follows:
0
Ins Lock
1
Caps Lock
2
Num Lock
3
Scroll Lock
number-of-lock-keys
is the number of consecutive keys to be affected.
Parent topic: Lock Key Handling


Converting Accepted Characters to Uppercase

Use the following call:

   call x"AF" using adis-function
                    adis-parameter

where:

   01  adis-function        pic x comp-x value 1.
   01  adis-parameter
       03  bitpair-setting  pic x comp-x value 1.
       03  bitpair-section  pic x value "2".
       03  bitpair-index    pic x comp-x value 85.
       03  bitpair-count    pic x comp-x value 1.

To restore Adis so that characters are accepted in the case in which they are typed, set bitpair-setting to 0.

Parent topic: Lock Key Handling


Configuring Enhanced ACCEPT and DISPLAY

Use the Adis Configuration utility to configure enhanced ACCEPT and DISPLAY statements.

  • Overview
  • Invoking the Adis Configuration Utility
  • Menus
  • Adiscf Functions
  • Configurable ACCEPT/DISPLAY Options
Parent topic: Command line reference


Overview

The Adis Configuration utility enables you to alter the default behavior of the enhanced ACCEPT and DISPLAY statements as described in your Language Reference.

The Adis module can be configured to change behavior in many areas. Full details on Adis are provided in the chapter Adis. Adis contains an internal set of defaults which it uses unless the file ADISCTRL is present. Any configuration changes affect ADISCTRL, and not the defaults internal to Adis.

ADISCTRL is the configuration database for the Adis module. It can hold up to a maximum of 16 configurations, any of which are available to you. An entry at the start of ADISCTRL determines which configuration Adis uses.

ADISCTRL contains all of the machine-independent information required by Adis. This includes:

  • How ACCEPT and DISPLAY statements are to be executed.
  • The messages outputted by Adis in response to errors.
  • Which keys are enabled or disabled.

You can alter any of the configurations held in ADISCTRL using the Adis Configuration utility. This utility is designed around a hierarchy of menus. These menus appear at the bottom of your screen and list the options available to you at any time.

The ADISCTRL file that is supplied with your COBOL system contains a number of configurations that are set up to emulate different dialects of COBOL. Most of the time you do not need to do anything other than use the Adis Configuration utility to select which one of these configurations you wish to use (use the Choose option on the main menu of the Adis Configuration utility).

The configurations supplied with your COBOL system include:

Default Configuration
This is exactly the same as the configuration built into Adis that is used at run time if no ADISCTRL file is found. This provides the standard mode of operation during execution of ACCEPT and DISPLAY statements.
IBM V1.0 Compatibility
Provides emulation for IBM COBOL V1.0. It is not a close emulation, especially in the action of ACCEPT operations into numeric and numeric-edited fields.
RM Compatibility
This configuration should be selected if your program was originally written in RM/COBOL V2.0. This configuration provides a very close emulation of the action of ACCEPT and DISPLAY statements in RM/COBOL V2.0.
DG ICOBOL Compatibility
Provides emulation of the actions of ACCEPT and DISPLAY statements under Data General's ICOBOL.
Microsoft V2 Compatibility
Provides emulation for Microsoft COBOL V2.2. It is not a close emulation, especially in the action of ACCEPT operations into numeric and numeric-edited fields.
RM2VCOB
Provides emulation for DIALECT"RM" applications running within Visual COBOL.
RM-Panels
Provides emulation of RM/Panel controls, for users migrating an RM/Panels application to Visual COBOL.

See the Compatibility Guides for full details on RM/COBOL and RM/Panels, DG ICOBOL, IBM and Microsoft compatibility.

If you do want to create your own configuration, we recommend that you do not change any of the supplied configurations directly. Instead, you should save the configuration you want to change under a different name and make changes to that.

If you create a custom ADISCTRL file, it must be accessible to your program (in the current directory or the etc sub-directory of your product installation directory) at run time. If it is not, defaults are used.

Parent topic: Configuring Enhanced ACCEPT and DISPLAY


Invoking the Adis Configuration Utility

To invoke the Adis Configuration utility, enter the command line:

adiscf

The utility searches for ADISCTRL, first in the current directory and then in the etc sub-directory of your product installation directory. If one exists, the Adis Configuration utility reads in the configuration currently selected for use by Adis. If ADISCTRL does not exist, the following message is displayed on your screen:

adisctrl does not exist - Defaults used

The Adis Configuration utility has a set of default values built into it. These are used if ADISCTRL does not exist.

If the message:

Old style adisctrl found. Converting to new format.

is displayed, the Adis Configuration utility has located an ADISCTRL file from an earlier product. This file is of a different format. However, the Adis Configuration utility can read the old format and convert it. Once files have been converted to the new format, versions of Adis supplied with previous versions of the COBOL system can no longer read them.

Parent topic: Configuring Enhanced ACCEPT and DISPLAY


Menus

The Adis Configuration utility menus are organized to provide rapid access to its most commonly used functions.

You can access a help menu from any menu by pressing F1=Help. This calls the help screen for the option from which it is called.

The menus described in this section appear in alphabetical order according to the menu-name. The name of a menu is displayed on the left-hand side of the information line.

The information line lists information concerning which menu you are on or, if you are on the main menu, which configuration is currently loaded. Each menu contains a similar information line as you will discover while using the Adis Configuration utility.

  • The Adis Configuration Utility Main Menu
  • The Adis Key Control Menu
  • The Alter Accept/Display Options Menu
  • The Alter All Messages Menu
  • The Alter All ACCEPT/DISPLAY Options Menu
  • The Alter Configuration Menu
  • The Alter Crt-Under Highlighting Menu
  • The Alter Function Mappings Menu
  • The Alter Indicators Menu
  • The Alter Individual Messages Menu
  • The Alter Individual Options Menu
  • The Alter Message/Indicator Positions Menu
  • The Alter Messages Menu
  • The Alter Tab Stops Menu
  • The Choose Configuration Menu
  • The Delete Configuration Menu
  • The Enable/Disable Adis Keys Menu
  • The Load Configuration Menu
  • The Save Menu
Parent topic: Configuring Enhanced ACCEPT and DISPLAY


The Adis Configuration Utility Main Menu

Once you have invoked the Adis Configuration utility it displays its main menu and the information line.

The main menu provides access to a number of submenus, enabling you to perform the following actions:

  • Alter any aspect of a configuration.
  • Load a configuration.
  • Save a configuration.
  • Delete a configuration.
  • Choose a configuration for Adis to use when running your programs.
Parent topic: Menus


The Adis Key Control Menu

Pressing F8=Key Control from the Alter Configuration menu displays the Adis Key Control menu.

This menu enables you to perform the following actions:

  • Alter the function performed by a specific key
  • Make a key act as an Adis function key
  • Disable a key completely

where an Adis function key is a key which is used during an ACCEPT operation to perform an editing function; for example, to move the cursor.

Parent topic: Menus


The Alter Accept/Display Options Menu

Pressing F3=Accept/Display Options from the Alter Configuration menu displays the Alter Accept/Display Options menu.

This menu enables you to specify how you want the cursor to behave, and what you want the fields to look like, during an ACCEPT operation. You can choose to alter all the available options or individual ones.

Parent topic: Menus


The Alter All Messages Menu

Pressing F2=All Messages or A from the Alter Messages menu displays the Alter All Messages menu.

This menu enables you to change the messages Adis displays when certain conditions (such as the cursor being at the end of a field) occur.

Parent topic: Menus


The Alter All ACCEPT/DISPLAY Options Menu

Pressing F2=All Options or A from the Alter Accept/Display Options menu displays the Alter All Options menu.

This menu enables you to change a set of options (such as the range of data keys allowed during an ACCEPT operation) that determine the behavior of the ACCEPT and DISPLAY operations.

Parent topic: Menus


The Alter Configuration Menu

Selecting the Alter menu by pressing F2=Alter from the main menu enables you to alter all or part of a configuration.

Parent topic: Menus


The Alter Crt-Under Highlighting Menu

Pressing F2=Crt-Under Highlighting from the Alter Configuration menu displays the Alter Crt-Under Highlighting menu.

This menu enables you to alter the type of highlighting that is used with the DISPLAY ... UPON CRT-UNDER statement, the DISPLAY ... WITH UNDERLINE statement, or when the UNDERLINE clause is used in the Screen Section of your programs.

Parent topic: Menus


The Alter Function Mappings Menu

Pressing F3=Function Mappings from the Adis Key Control menu displays the Alter Function Mappings menu.

This menu enables you to map Adis keys so that they perform different functions to those originally associated with those keys.

Parent topic: Menus


The Alter Indicators Menu

Pressing F5=Indicators from the Alter Configuration menu displays the Alter Indicators menu.

This menu enables you to alter the text displayed by Adis during an ACCEPT operation to indicate various conditions. The text for each message can be up to 32 characters long. Once you have typed your own message press Enter to make that change.

Parent topic: Menus


The Alter Individual Messages Menu

Pressing F3=Individual Messages or I from the Alter Messages menu displays the Alter Individual Messages menu.

This menu displays a list of the currently defined messages with a number by the side of each. Press F2=Next Page to see the next screen of available messages, then press F2 again to see the original screen of messages.

Parent topic: Menus


The Alter Individual Options Menu

Pressing F3=Individual Options or I from the Alter Accept/Display Options menu displays the Alter Individual Options menu.

This menu enables you to change one of the options controlling the use of the ACCEPT and DISPLAY operations (such as the range of data keys enabled during an ACCEPT operation).

Parent topic: Menus


The Alter Message/Indicator Positions Menu

Pressing F7=Positions on the Alter Configuration menu displays the Alter Message/Indicator Positions menu.

This menu enables you to control whether or not the messages and indicators normally displayed by Adis during an ACCEPT operation are displayed. If you choose to display them, this menu also enables you to alter the position on the screen at which they are displayed.

Parent topic: Menus


The Alter Messages Menu

Pressing F6=Messages from the Alter Configuration menu displays the Alter Messages menu.

This menu enables you to alter the text of messages displayed by Adis during an ACCEPT operation, to indicate various error conditions. You can choose to alter all the available messages or individual ones.

Parent topic: Menus


The Alter Tab Stops Menu

Pressing F4=Tab Stops from the Alter Configuration menu displays the Alter Tab Stops menu.

This menu enables you to set up to 96 tab stops to be used at run time. The Tab Stops screen shows a ruler at the top of the screen on which the current positions of tab stops are shown by the letter T. Use the cursor keys <left-arrow> and <right-arrow> to move the cursor along the ruler.

Parent topic: Menus


The Choose Configuration Menu

Pressing F6=Choose from the main menu displays the Choose Configuration menu.

This menu enables you to choose the configuration to be used by Adis when you run your programs.

Parent topic: Menus


The Delete Configuration Menu

Pressing F5=Delete or D from the main menu displays the Delete Configuration menu.

This menu enables you to delete an existing configuration from the ADISCTRL file.

Parent topic: Menus


The Enable/Disable Adis Keys Menu

Pressing F2=Enable/Disable Adis Keys or D from the Adis Key Control menu displays the Enable/Disable Adis Keys menu.

This menu enables you to control which of the functions performed by the Adis keys are enabled.

Parent topic: Menus


The Load Configuration Menu

Pressing F3=Load or L from the main menu displays the Load Configuration menu.

This menu enables you to load an existing configuration into memory. You must load a configuration into memory before you can make any changes to that particular configuration.

Parent topic: Menus


The Save Menu

Pressing F4=Save from the main menu displays the Save menu.

Once you have altered a configuration, using the Alter menu, this menu enables you to save your changes.You must do this if you wish to use the new version of your configuration. If you attempt to leave the Adis Configuration utility without first saving any changes you have made to a configuration, you are asked to confirm that this is what you wish to do.

Parent topic: Menus


Adiscf Functions

Adiscf functions are accessed from menus. The following table lists the available functions in alphabetical order, describes them in detail, and indicates the keys you must press to access them.

Add New Tab Stop
Access keys: F2>F4>F2
Sets a tab stop at the current cursor position. A "T" is displayed to show the position of the new tab stop. During an ACCEPT operation,Tab only moves to the next tab stop if it is mapped to the "Move to next tab stop" function.
Alter ACCEPT/DISPLAY Options
Access keys: F2>F3
Displays the Alter ACCEPT/DISPLAY Options menu.
Alter All ACCEPT/DISPLAY Options
Access keys: F2>F3>F2
Displays a description of each option and its current value in turn, one option per screen.

Press Enter to move from one screen to the next or Escape to return to the Alter Accept/Display Options menu. To alter the value of an option, type the number of the choice you require at the relevant prompt. You can alter as few or as many options as you wish.

Alter All Messages
Access keys: F2>F6>F2
Displays in turn the current text of each message and the conditions under which it is output; one message per screen. Press Enter to cycle from one screen to the next.

To alter a message, type the text of the new message at the prompt on the relevant screen, then press Enter to save the new message and return you to the Alter Messages menu. You can alter as few or as many messages as you wish. Pressing Escape returns you to the Alter Messages menu, abandoning any change made to the current message.

Alter Auto Clear Indicator
Access keys: F2>F5>F4
Displays the current text for the auto clear and clear auto clear indicators. The auto clear indicator is displayed during an ACCEPT operation if the first character entered into a field would cause the field to be cleared before the character is placed into it. The clear auto clear indicator is displayed at the end of an ACCEPT operation to remove the auto clear indicator if it is currently displayed.

Use the cursor keys (cursor-up and cursor-down) to move between the two fields. Press Enter to save your changes, or Escape to leave the Alter Auto Clear Indicator menu without altering either of the indicators.

Alter Configuration
Access key: F2
Displays the Alter Configuration menu.
Alter CRT-UNDER Hightlighting
Access keys: F2>F2
Displays the Alter CRT-UNDER Highlighting menu.
Alter Indicators
Access keys: F2>F5
Displays the Alter Indicators menu.
Alter Individual ACCEPT/DISPLAY Option
Access keys: F2>F3>F3
Displays a screen of ACCEPT/DISPLAY options you can change. The currently selected option is highlighted. Press F2=Next Page to see a page of further options, then press F2 again to return to the page of original options.

Type the number of the option you want to change or position the cursor on the relevant line using the cursor keys ( and ). Press Enter to select that option.

A description of that option and its current value is then displayed. To alter the value of an option, type the number of the choice you require at the relevant prompt and press Enter. Press Escape to return to the Alter Individual Options menu.

Alter Individual Messages
Access keys: F2>F6>F3
Displays a screen of messages you can change. The currently selected message is highlighted. Press F2=Next Page to see a page of further options, then press F2 again to return to the page of original messages.

Type the number of the message you want to change, or position the cursor on the relevant line, using the cursor keys (cursor-up and cursor-down). Press Enter to select that message. The message currently configured for that error condition is displayed. Type the new message at the prompt on the screen. Press Enter to save the message you have typed and return to the list of messages, or press Escape to abandon any change you have made and return to the list of messages.

Alter Insert/Replace Indicator
Access keys: F2>F5>F2
Displays the current text for the insert, replace and clear insert/replace indicators. The insert indicator is displayed when insert mode is active during an ACCEPT operation. The replace indicator is displayed if replace mode is active during an ACCEPT operation. The clear insert/replace indicator is displayed at the end of an ACCEPT operation to remove whichever of the two other indicators is currently displayed.

Use the cursor keys (cursor-up and cursor-down) to move between the three fields. Press Enter to save your changes, or Escape to leave the Alter Insert/Replace Indicator menu without altering any of the indicators.

Alter Key Control
Access keys: F2>F8
Displays the Enhanced ACCEPT/DISPLAY Syntax Key Control menu.
Alter Messages
Access keys: F2>F6
Displays the Alter Messages menu.
Alter Off End of Field Indicator
Access keys: F2>F5>F3
Displays the current text for the off end of field and clear off end of field indicators. The off end of field indicator is displayed during an ACCEPT operation if the next character entered would be beyond the end of the field. The clear off end of field indicator is displayed at the end of an ACCEPT operation to remove the indicator that is currently displayed.

Use the cursor keys (cursor-up and cursor-down) to move between the two fields. Press Enter to save your changes, or Escape to leave the Alter Insert/Replace Indicator menu without altering any of the indicators.

Alter Position of Messages and Indicators
Access keys: F2>F7
Displays the four categories of messages and indicators whose positioning you can alter, along with input fields for you to enter the relevant positioning for each category.

Use the cursor keys (cursor-left, cursor-right, cursor-up and cursor-down) to move around the screen from field to field. If you want error messages or a specific indicator to be displayed during an ACCEPT operation enter Y in the relevant field. Enter N if you do not want them to be displayed. Even if you choose not to display error messages, the abort confirmation message is always displayed when the Abort key is pressed during an ACCEPT operation, unless you use the Alter Messages Menu to specifically alter the text associated with this message.

If you choose to display the messages or any specific indicators, you can alter the default positions at which they are displayed on your screen during an ACCEPT operation. Use the cursor keys to position the cursor in the relevant fields and type the new line and column at which you wish the messages or indicator to be displayed.

Line 1 column 1 is the top left-hand corner of your screen.

If you configure more than one indicator to be displayed at the same position, and more than one needs to be displayed at the same time, the off end of field and auto clear indicators take priority over the insert/replace indicator.

Selecting line 255 for any indicator causes the indicator to be displayed on the bottom line of the screen, regardless of the actual length of the screen.

Press Enter once you have made your entries, to return to the Alter Configuration menu and save your changes. Press Escape to return to the Alter Configuration menu, abandoning any changes you have made.

Alter Tab Stops
Access keys: F2>F4
Displays the Alter Tab Stops menu.
Choose Configuration
Access key: F6
Displays the available configurations, with the one currently active appearing highlighted.

Choose the configuration you require either by entering its number at the prompt, or by positioning the cursor on the relevant configuration name using the cursor keys (cursor-up and cursor-down). This line now appears highlighted.

When you have highlighted the configuration you want to choose, press Enter. The highlighted configuration becomes the active configuration and you are returned to the Adiscf main menu. When you next run a program using your COBOL system, the enhanced ACCEPT/DISPLAY syntax automatically uses the configuration you have just chosen. Alternatively, you can press Escape to return to the Adiscf main menu without choosing a new configuration.

Delete Configuration
Access key: F5
Displays the existing configurations, with the current configuration appearing highlighted. Highlight the configuration you wish to delete by entering its number to the prompt, or by using the cursor keys (cursor-up and cursor-down).

When you have highlighted the configuration you want to delete, press Enter. The configuration is deleted from adisctrl and you are returned to the Adiscf main menu. Alternatively you can press Escape to return to the Adiscf main menu without deleting a configuration.

Important: You cannot delete the configuration which is currently selected. If you wish to delete this you must first use the Choose menu to choose an alternative configuration.
Delete Tab Stop
Access key: F2>F4>F3
Deletes the tab stop (represented by T) at the current cursor position. You should first have used the cursor keys (cursor-left and cursor-right) to position the cursor over the tab stop to be deleted.
Enable/Disable Enhanced ACCEPT/DISPLAY Syntax Keys
Access keys: F2>F8>F2
Displays a list of all functions provided by the enhanced ACCEPT/DISPLAY syntax keys, together with the current status of each key.

You can alter the status of any key to be one of the following:

Status | Description
d | Disabled - the key does not perform its associated function during an ACCEPT operation.
E | Enabled - the key performs its associated function during an ACCEPT operation.
F | Function key - the key acts as a function key during an ACCEPT operation.

Use the cursor keys (cursor-left, cursor-right, cursor-up and cursor-down) to move from field to field on the screen and enter the required letter in the field(s) you wish to alter.

Press Enter once you have made your entries, to return to the Enhanced ACCEPT/DISPLAY Syntax Key Control menu and save your changes. Press Escape to return to the Enhanced ACCEPT/DISPLAY Syntax Key Control menu, abandoning any changes you have made.

Escape
Access key: Esc
Returns to the higher level menu or exits from Adiscf altogether if you are at the Adiscf main menu. Where both Escape and Enter are available options, Escape exits without making the update you have keyed in, whereas Enter makes the update and then exits.
Load Configuration
Access key: F3
Displays a list of available configurations.

The configurations may vary according to the version of the software.

The configuration currently loaded appears highlighted on your screen. To select a configuration, either enter its number at the prompt or use the cursor keys (cursor-up and cursor-down) to position the cursor on the line specifying the required configuration. When you move the cursor to another configuration, that configuration appears highlighted on the screen, and its number appears at the prompt position at the bottom of your screen.

Once you have highlighted the configuration you require, press Enter. Adiscf loads the configuration you have selected into memory from adisctrl.

You are then returned to the Adiscf main menu. The configuration you have just selected appears on the information line. You can now alter this configuration by selecting the Alter menu.

If you do not want to select a configuration to load, pressing Escape returns you to the Adiscf main menu.

Map Adis Keys
Access keys: F2>F8>F3
Displays a page of supported enhanced ACCEPT/DISPLAY syntax functions. Press F2=Next Page to see a page of further functions, then press F2 again to return to the page of original functions.

This function enables you to alter the function normally associated with a key. You can map any function to any key. Each function key has three fields associated with it which you can alter:

Field | Description
Validate | If you set this field to Y, all validation criteria must be satisfied before the cursor can leave a field during an ACCEPT operation. If you enter N, validation criteria are not checked during an ACCEPT operation.
Align | By default this field is set to N. If set to Y, a field is cleared from the current cursor position to the end of the field during an ACCEPT operation. Numeric fields are aligned to the decimal point, if it is to the right of the current cursor position.
Mapped Number | This field contains the number of the function to which the associated key is currently mapped. Enter the number of the required function if you want to alter this.

Press F2=Next Page to display a page of further function mappings.

Move between the fields using the cursor keys (cursor-left, cursor-right, cursor-up and cursor-down). When you have made your changes, press Enter to return to the Enhanced ACCEPT/DISPLAY Syntax Key Control menu and save your changes. Press Escape to return to the Enhanced ACCEPT/DISPLAY Syntax Key Control menu if you do not wish to save your changes, or you have made none.

Overwrite Existing Configuration
Access keys: F4>F3
Saves your configuration in adisctrl with the same name as an existing configuration. Use this option with care as it overwrites the existing configuration with that name. Adiscf displays a numbered list of the existing configurations. Type the number of the configuration you want to overwrite, or position the cursor on the relevant line, using the cursor up and down keys. Press Enter to save the configuration to the name you have specified and to return to the Adiscf main menu. Alternatively, press Escape to return to the Adiscf main menu without saving.

You can store up to 16 configurations in adisctrl. If you try to save more than this number you receive the message:

The configuration file is full - No new entries allowed

If you receive this message you must either delete or overwrite an existing configuration before you can save any others.

Save
Access key: F4
Displays the Save menu.
Save New Configuration
Access Keys: F4>F2
Saves your configuration as a new configuration within adisctrl. You are prompted to type the name of this configuration. Press Enter to save the configuration to the name you have entered and to return to the Adiscf main menu. Alternatively, press Escape to return to the Adiscf main menu without saving.
Save New Tab Stop Settings
Access Keys: F2>F4>F4
Saves the changes you have made to the positions of the tab stops, and returns to the Alter Configuration menu.
Set CRT-UNDER Attribute to Blink
Access Keys: F2>F2>F5
Specifies that the attribute to be used when a DISPLAY ... UPON CRT-UNDER statement is executed is blinking. The word BLINK appears on the information line.
Set CRT-UNDER Attribute to Bold
Access Keys: F2>F2>F2
Specifies that the attribute to be used when a DISPLAY ... UPON CRT-UNDER statement is executed is bold. The word INTENSITY appears on the information line.
Set CRT-UNDER Attribute to Reverse Video
Access Keys: F2>F2>F4
Specifies that the attribute to be used when a DISPLAY ... UPON CRT-UNDER statement is executed is reverse video. The words REVERSE VIDEO appear on the information line in reverse video.
Set CRT-UNDER Attribute to Underscore
Access Keys: F2>F2>F3
Specifies that the attribute to be used when a DISPLAY ... UPON CRT-UNDER statement is executed is underscore. The word UNDERSCORE appears on the information line.
Parent topic: Configuring Enhanced ACCEPT and DISPLAY


Configurable ACCEPT/DISPLAY Options

The following is a list of all the ACCEPT/DISPLAY options you can alter from the Alter All Options menu or the Alter Individual Options menu. The number for each option is the number displayed by the Alter All Options and Alter Individual Options menus.

  1. User function keys enable/disable.

    Enables you to enable or disable the user function keys. These are usually the function keys on your keyboard. You can choose to:

    • Disable all user function keys. If you press a user function key during an ACCEPT operation it is treated as an invalid key. This is the default.
    • Enable all user function keys. If you press a user function key during an ACCEPT operation, the ACCEPT operation is terminated.
  2. Range of data keys accepted.

    You can specify which characters are to be allowed during input to an ACCEPT operation. You are prompted to enter the number of the option you require:

    1 | Characters with ASCII codes in the range 0 to 127 are allowed.
    2 | Characters with ASCII codes in the range 0 to 255 are allowed.
    3 | Characters with ASCII codes in the range 32 to 127 are allowed.
    4 | Characters with ASCII codes in the range 32 to 255 are allowed. This is the default.

    If you enable characters within the range 0 to 31 using options 1 or 2, you may still not be able to enter some of these characters into a field. This is because some of these characters may form the start of some key sequences generated by function or cursor keys. If these keys are enabled they have priority over the data keys.

  3. Prompt character.

    Enables you to specify the character to be displayed in the empty part of the field during an ACCEPT operation of a Screen Section item, or an ACCEPT operation that specifies the PROMPT clause. The system displays the selected character in all portions of the field into which you have not yet entered data. The selected character also serves to indicate the extent of the field.

    This prompt character is used for all picture types except PIC G and PIC N.

  4. Prompt character in PIC G fields.

    Enables you to specify the character to be displayed in the empty part of a PIC G field during an ACCEPT operation of a Screen Section item, or an ACCEPT operation that specifies the PROMPT clause.

  5. Predisplay of fields before an accept.

    Enables you to specify whether you want the contents of data fields to be displayed automatically before an ACCEPT statement. If you do not specify automatic display of data fields before an ACCEPT statement, the screen remains as it is. You can choose between the following options:

    1 | Enables the predisplay of numeric-edited fields with numeric editing when the cursor moves into them. No other predisplay occurs.
    2 | Enables the predisplay of all numeric fields with numeric editing enabled when the cursor moves into them. No other predisplay occurs.
    3 | Enables the predisplay of all fields immediately before data is accepted into the field.
    4 | Predisplay of all fields before any data entry is allowed. This is the default.
  6. Accept in a SECURE field.

    Enables you to specify how you want the cursor to behave, and what you want the field to look like during an ACCEPT into a SECURE field. Possible options are:

    1 | There is no display of characters on the screen as you enter each character, but the cursor advances to the next character position. This is the default.
    2 | An asterisk (*) is displayed as each character is entered, and the cursor advances to the next character position.
    3 | A space is displayed as each character is entered, and the cursor advances to the next character position.
  7. Auto-skip between fields.

    Enables you to specify whether you want the cursor to move to the next field automatically when the current field is full. This applies only to multiple data fields within one ACCEPT statement. The options available to you are:

    1 | No auto-skip. You must press the key set as the tab key, or a cursor key (other than cursor-left) to move to the next field.
    2 | Auto-skip enabled. If the current field is full, any cursor movement, or pressing a character key, causes the cursor to move to the next field. This is the default.

    This option has no effect on ACCEPT operations on Screen Section items. Auto-skip is off by default for these operations. You can turn it on by specifying the AUTO clause in your source program. See the AUTO clause for details.

  8. Termination of an accept.

    Enables you to specify which actions terminate an ACCEPT operation. You can specify the following to terminate an ACCEPT operation:

    1 | Pressing the "terminate accept" key. This is the default.
    2 | Pressing the "next field" key when the cursor is in the last field of an ACCEPT operation.
    3 | Keying or retyping a data character in the last available character position of an ACCEPT operation, provided auto-skip between fields is enabled.

    This option controls only normal termination. Function keys still terminate an ACCEPT operation if they are enabled.

  9. Validation control if accept is terminated by a function key.

    Enables you to specify whether validation clauses need to be satisfied when terminating an ACCEPT using a function key. You can choose between:

    1 | No validation takes place. This is the default.
    2 | Normal validation criteria must be satisfied for the current field.
  10. End of field effects.

    Enables you to specify how you want the cursor to behave, if you attempt to key data once a field is full. You can select one of the following options:

    1 | The cursor moves beyond the end of field, and overtyping is rejected.
    2 | The cursor stays at the end of field, and overtyping is rejected.
    3 | The cursor stays at the end of field, and overtyping is allowed. This is the default.
  11. Field overflow buffers enable/disable.

    Enables you to specify whether data is to be saved in an overflow buffer when displaced from the end of a field. You can choose from the following options:

    1 | Displaced data is saved in an overflow buffer. This is the default.
    2 | Displaced data is not saved in an overflow buffer.
  12. Auto-restore during backspace in replacement editing mode.

    Enables you to specify the action of the Backspace key in free-format fields, when in replacement editing mode. You can choose from the following options:

    1 | Auto-restore is enabled. Previously overtyped characters are restored, as characters are deleted. This is the default.
    2 | Auto-restore is disabled. Deleted characters are replaced by spaces.
  13. Accepts into numeric edited fields.

    Enables you to specify how you want numeric-edited fields to look during an ACCEPT operation. You can choose from the following options:

    a | Input is accepted as for alphanumeric fields and is normalized to remove illegal characters on exit from the field.
    b | As for option a, but you can enter only digits, signs, decimal points and commas.
    c | Numeric fields up to 32 characters long are accepted in formatted mode. This means that characters other than digits, signs and decimal points are rejected. Fields are reformatted to show the editing symbols as data is entered. Fields longer than 32 characters are accepted as in option a. This is the default.
    d | As in option c, with the exception that fields longer than 32 characters are accepted as in option b.
  14. Accepts into non-edited numeric fields.

    Enables you to specify how you want non-edited numeric fields to look during an ACCEPT operation. You can choose from the following options:

    a | Unsigned and embedded signed non-edited numeric fields with PICTURE clauses of the form 9(m)V(n) are treated as though they were a PIC 9(m) field followed by a PIC 9(n) field. Fields with separate signs are treated as though they were PIC S9(m+n). This is the default.
    b | As in option a except that fields with a V in the PIC clause are treated as PIC S9(m+n).
    c | All non-edited numeric fields are treated as alphanumeric fields.

    If you specify a nonzero SIZE clause, all non-edited numeric fields are treated as free-format fields, regardless of the setting of this option.

  15. Enable/Disable auto-clear or pre-clear.

    Enables you to specify how you want a field to appear when the cursor first enters it. You can specify any of the following options:

    a | No pre-clear or auto-clear takes place. This is the default.
    b | Pre-clear mode. The field is cleared to spaces or zeros. Pressing theUndo key restores the original contents of the field.
    c | Auto-clear mode. If the first keystroke is a valid data character, then the field is cleared to spaces or zeros before processing the character. An invalid data character turns auto-clear mode off. Pressing theUndo key restores the original contents of the field.
    d | As in option b, except that pressing the Undo key does not restore the original contents of the field.
  16. Force field to be updated if it is not altered.

    Enables you to specify how you want the contents of a field to appear if you leave it without altering it. You can choose from the following options:

    1 | The data item is not updated if the field is not altered. This is the default.
    2 | The data item is always updated even if the field is not altered. This option has effect only if the field is numeric or numeric-edited and the original data item did not contain any numeric data, or if the field is right justified and the original contents of the field were not.
  17. Remembering where the end of the field is.

    Enables you to specify if the enhanced ACCEPT/DISPLAY syntax is to remember the position of the last character in a field. You can choose from the following options:

    1 | The enhanced ACCEPT/DISPLAY syntax does not note the position of the last character. This is the default.
    2 | The enhanced ACCEPT/DISPLAY syntax notes the position of the last character entered into a field during an ACCEPT operation. This option is required to provide justification of RM-style numeric fields.

    This option applies only if the prompt character is disabled.

  18. RM style numeric data entry.

    Enables you to specify if you want your system to emulate RM/COBOL style entry of numeric data items. You can choose from the following options:

    1 | The COBOL system entry of numeric data items is enabled. This is the default.
    2 | The RM/COBOL style of numeric and numeric-edited data entry is enabled. If this option is selected, all other numeric and numeric-edited options are ignored.
  19. Restricting maximum field size to one line.

    Enables you to specify if the size of fields in ACCEPT operations is restricted to one line. You can choose from the following options:

    1 | Fields are not restricted to one line. This is the default.
    2 | Fields are restricted to one line.
  20. Control of cursor positioning after an accept.

    Enables you to control where the cursor is placed at the end of an ACCEPT operation. You can choose from the following options:

    1 | The cursor is moved to the next character position following the end of the current field. This is the default.
    2 | The cursor is left at its current position.
  21. Control of whether UPDATE clauses perform implicit CONVERTs.

    Enables you to specify if a CONVERT clause is implied if you specify an UPDATE phrase. You can choose from the following options:

    1 | The CONVERT clause is not implied. This is the default.
    2 | The CONVERT clause is implied.

    This option is provided to enable you to emulate the behavior of RM/COBOL V2.0 and V2.1.

  22. Selection of the function key list to be used.

    Enables you to specify which function key list your system is to use to map control codes onto user function keys. You can choose from the following options:

    1 | The standard user function key list is to be used. This is the default.
    2 | The compatibility function key list is to be used. The list supplied with the COBOL system is the RM/COBOL function key list, but you may alter this for compatibility with any dialect of COBOL.
  23. Selection of the action for COLUMN + n clauses.

    Enables you to determine the number of characters advanced by this clause in the Screen Section. You can choose from the following options:

    1 | A COLUMN + 1 clause causes the field to be displayed immediately after the preceding field; there is no gap between the two fields. This is the default.
    2 | A COLUMN + 1 clause leaves a one-character gap between the two fields.
    3 | COLUMN +n clauses, wheren >> 1, are treated accordingly. You should set this option to 2 if DG-style behavior is required.
  24. Selection of the default action if no color specified.

    Enables you to specify the default colors for Screen Section items if no color is specified:

    1 | The default screen color is used; that is, the colors specified in the last BLANK SCREEN clause. The initial colors are white for foreground, and black for background. This is the default.
    2 | Text is displayed with white foreground and black background regardless of the default color.
    3 | Text is displayed with either white foreground and black background, or using the colors set by the last BLANK SCREEN clause.
  25. Control of whether cursor left/right keys can exit a field.

    Enables you to control whether pressing the cursor left/right keys when positioned at the start/end of a field move to the previous/next field respectively. You can choose from the following options:

    1 | The keys move to the previous or next field. This the default.
    2 | The keys cannot exit a field.
  26. Left justification of free-format edited numerics.

    Enables you to control whether free-format edited numeric fields are left-justified as they are entered. You can choose from the following options:

    1 | The field is not left-justified. This is the default.
    2 | The field is left-justified, provided RM-numeric handling is switched off. This is controlled by ACCEPT/DISPLAY option 18.
  27. Validation control on FULL/REQUIRED fields.

    Enables you to control whether all fields with a FULL or REQUIRED clause must have the appropriate conditions satisfied before termination of an ACCEPT operation is possible. You can choose from the following options:

    1 | Any field which has not been changed by the user is not validated. This is the default.
    2 | All fields with a FULL or REQUIRED clause must have valid contents before an ACCEPT operation can be terminated.
  28. Control of the enhanced ACCEPT/DISPLAY syntax keys defined as function keys.

    Enables you to control how an enhanced ACCEPT/DISPLAY syntax key behaves when defined as a function key. You can choose from the following options:

    1 | The mapping associated with the key determines the behavior of the key. This option is provided for compatibility with early Micro Focus products.
    2 | Any enhanced ACCEPT/DISPLAY syntax key set up as a function key terminates the ACCEPT operation regardless of the function mapping. This the default.
  29. Control of the read screen option for an accept.

    Enables you to control the facility that enables the initial contents of an ACCEPT field to be read from the current screen contents. You can choose from the following options:

    1 | No screen READ occurs. The initial contents of the field are unaltered. This is the default.
    2 | The initial contents of the field are read from the screen provided that predisplay of the field is disabled. This is controlled by ACCEPT/DISPLAY option 5.
  30. Control of whether concealed fields are skipped.

    Enables you to control circumstances in which you can skip concealed fields. You can choose from the following options:

    1 | Concealed fields are not skipped. This is the default.
    2 | Concealed fields are skipped.
  31. Control of special action for Kanji modifier characters.

    Enables you to control the behavior of the Kanji modifier characters, daku-on and han-daku-on, if you specify them during an ACCEPT operation. You can choose from the following options:

    1 | The modifier characters are treated the same as all other characters. This is the default.
    2 | If you enter a modifier character, the previous character entered is examined by the enhanced ACCEPT/DISPLAY syntax to see if it can be modified. If it can, it is replaced by the modified character.

    This option is only relevant on Japanese double-byte character set machines.

  32. Selection of the units used when calculating timeout.

    Enables you to specify the timeout in units of seconds or tenths of a second.

    1 | The time specified for the TIMEOUT clause is in seconds. This is the default.
    2 | The time specified for the TIMEOUT clause is in tenths of a second.
  33. Control of whether timeout is reset on each keystroke.

    Enables you to specify that the TIMEOUT timer is reset every time a character is input, or times out after a fixed time irrespective of what is entered. You can choose from the following options:

    1 | The timer is not reset. Timeout occurs at the specified length of time after the ACCEPT operation is initiated. This is the default.
    2 | The timer is reset each time a character is entered.
Parent topic: Configuring Enhanced ACCEPT and DISPLAY


Keyboard Configuration Utility (Keybcf)

  • Overview
  • Invoking the Keyboard Configuration Utility
  • Using the Keyboard Configuration Utility
  • Exiting From the Keyboard Configuration Utility
  • Example of Using the Keyboard Configuration Utility
  • Standard Adis Key Functions
  • Special Mapping Functions in Adis
Parent topic: Command line reference


Overview

Normally, the default keys built into Adis should not need changing. However, you may need to change the keys used to emulate a particular dialect of COBOL.

The default set of keys used by your COBOL system is built into Adis. The Keyboard Configuration utility creates a file called cobkeymp which contains the keystrokes that are to be used for function keys and the keys Adis uses during an ACCEPT operation. At run time, Adis checks for cobkeymp in the current directory. If the file is not found, then the COBOL system directories are searched for cobkeymp. If the file is found the set of keys defined in it are used. If not, the default set of keys are used.

  • The Key Lists
  • cobkeymp Tables
Parent topic: Keyboard Configuration Utility (Keybcf)


The Key Lists

The following lists of keys can be reviewed and altered by the Keyboard Configuration utility:

  • Adis function key list.

    This list defines the keys which carry out specified functions when you are executing an ACCEPT statement in a COBOL program.

  • Animator function key list.

    This list is used by Animator and some other Micro Focus programs.

  • User function key list.

    The user function key list defines the keys that are normally returned to your program when a function key is pressed.

  • Compatibility function key list.

    This list defines an alternative user key list that can be used if you want to set up keys to be compatible with another dialect of COBOL. If the values returned by such keys differ from the standard user key list, you are advised to alter the compatibility function key list rather than the user function key list. By default, the compatibility function key list is configured for compatibility with RM/COBOL V2.0 on UNIX.

    ACCEPT/DISPLAY option 22 in the Adis Configuration utility enables you to choose between using the user or compatibility key lists.

By default, the user function keys are initially disabled. In order to use these function keys during the execution of a program, you must first enable them by calling the x"AF" library routine or by altering the configuration using the Adis Configuration utility.

The CRT STATUS clause allows you to ascertain which function key was used to terminate an ACCEPT operation.

Parent topic: Overview


cobkeymp Tables

Values within the tables found in cobkeymp (or as the internal defaults) which begin with the prefix KEY_ represent values that have been translated using the terminfo database and the UNIX terminal handling library. These values are independent of the terminal you are currently using, and thus you can define keys which are not actually present on your particular keyboard.

You do not need to create a different cobkeymp file for each terminal type on your system. Instead, try to ensure that your cobkeymp is suitable for as many different types of terminal as possible. All terminal specific decoding is done by the run-time system using theterminfo database. However, you may have to supply alternative keystrokes for those terminals which do not have special function keys. Full details on the KEY_ values are given in your UNIX documentation.

If you decide to have multiple cobkeymp files rather than using the above procedure, you can do this by renaming cobkeymp and then setting up a dd_ environment variable at run time. For example:

dd_cobkeymp=newname

causes the run-time system to look for key configuration information in newname.

Parent topic: Overview


Invoking the Keyboard Configuration Utility

To set up your own cobkeymp file using the Keyboard Configuration utility, enter the command line:

keybcf

The Keyboard Configuration utility searches for a file called cobkeymp in the current directory and then the directories specified by the COBDIR environment variable. If the file is found, you are asked if you want to edit it. Answer "Y" if you want to edit the file or "N" if you want to create a new file based on the default set of keys. If the file is not found, one is created.

Parent topic: Keyboard Configuration Utility (Keybcf)


Using the Keyboard Configuration Utility

The Keyboard Configuration utility is menu driven. Once it is invoked, it displays its initial menu.

To select the option of your choice, press its associated number. The menu for that function is then displayed.

  • Reviewing Existing Function Key Definitions
  • Altering Function Key Definitions
  • Saving Function Key Definitions
Parent topic: Keyboard Configuration Utility (Keybcf)


Reviewing Existing Function Key Definitions

Entering 1 from the main menu displays the Review Existing Function Key Definitions menu.

This menu enables you to list all currently defined function keys in one of four sets: Adis, Animator, user or compatibility. To output the list of your choice, press its associated number. For example, press 2 to output the list of Animator function keys, or 4 to output the list of compatibility keys.

Option 5 is a toggle to determine whether a selected list is shown on the screen or written to a file. If you select the screen as the destination, all the currently defined function keys in that list are displayed together with their hexadecimal values. To page from one screen to the next, press any key. Once the end of the list is reached, press any key to return to the Review Existing Function Key Definitions menu.

If you select to output the list to file, the same information is written to a file called KEYLIST.DMP. This happens without further intervention unless the file KEYLIST.DMP already exists, in which case you are asked whether to overwrite it or append this list to the end. Press O to overwrite, E to extend.

Press 6 to return to the main menu.

Parent topic: Using the Keyboard Configuration Utility


Altering Function Key Definitions

Entering 2 from the main menu displays the Alter Function Key Definition menu in which you are prompted to choose the set of function keys you wish to alter.

As with the Review Existing Function Key Definitions menu, you can select the Adis, Animator, user or compatibility function key lists. When you have made your selection, a screen for that selection is displayed. As an example, the figure below shows the screen for Adis key list.
Figure 1. The Alter Menu for the Adis Key List
The Alter Menu for the Adis Key List
Each function in the function key list you select is displayed individually. For example, the function displayed above is Terminate accept. To enter a new function key press the key you want to perform the function, or use X to enter the hexadecimal code for the key. Once you have entered the new key, the program automatically cycles to the next function after a slight pause. The following keys are available on this menu:
Key | Description
Space | Cycles from one function to the next, without altering the key defined for each function.
Insert | Adds another key to perform the displayed function, but retains the currently defined function key. The word Insert is displayed at the bottom right of the screen.
Delete | Deletes a defined function key from a list. The Keyboard Configuration utility automatically cycles to the next function.
HeX | Specifies that you will enter the hexadecimal sequence for the required function key. The word Hex is displayed at the bottom right of the screen. If you enter an invalid hexadecimal sequence you receive an error when you attempt to cycle to the next function and you are prompted to enter a valid sequence. This function allows you to define keys which may not actually appear on the keyboard you are using, but will be available on the one on which your program will run.
Quit | Returns to the Alter menu.

If you attempt to define a large number of keys you may exceed the limit, in which case you receive the warning:

There is not enough room for that sequence

Should this occur, the only way to add additional keys is to delete unwanted key sequences.

Press 5 to return to the main menu.

Your UNIX documentation contains details on the values for the KEY_ mnemonics . These are 16-bit values, but you can enter them as three 8-bit codes by typing: FF, high-byte, low-byte

For example, KEY_DOWN has octal value 0402, or hexadecimal value 102. You can enter a code for KEY_DOWN by typing the three bytes: FF, 01, 02

Alternatively, if you press the down arrow key on your keyboard your system enters these three bytes for you.

Parent topic: Using the Keyboard Configuration Utility


Saving Function Key Definitions

If you want to save any alterations you have made to any of the function lists, press 3 from the main menu. This saves the changed function lists to a file called cobkeymp.

Parent topic: Using the Keyboard Configuration Utility


Exiting From the Keyboard Configuration Utility

To exit from the Keyboard Configuration utility, press 4 from the main menu.

Parent topic: Keyboard Configuration Utility (Keybcf)


Example of Using the Keyboard Configuration Utility

The following example shows how to use the Keyboard Configuration utility to alter the Animator key list. It describes the steps required to insert, delete and change key definitions. The example assumes that the file cobkeymp has not been previously created and hence the values shown by the Keyboard Configuration utility are the defaults.

  1. Invoke the Keyboard Configuration utility.
  2. Press 2 from the main menu to display the Alter Function Key Definition menu.
  3. Press 2 to specify that you want to alter the Animator key list.

    The screen for Animator function key 1 appears.

  4. Press D to delete the definition of this key.

    The screen for function key 2 now shows.

  5. Press Space to skip over the key definition and continue to do so until the screen for Cursor Up appears.
  6. Press Ctrl and U. The hexadecimal value corresponding to Ctrl+U appears as the definition of Cursor Up. This has now replaced the old value of Cursor Up.

    The screen for Cursor Down now appears.

  7. Press I to insert a definition and then press Ctrl +D. The hexadecimal value for Ctrl+D appears. The next screen is then displayed showing the value for Cursor Down which already exists, that is, there are now two definitions available for Cursor Down.
  8. Press Q to quit and return to the Alter Function Key Definition menu.
  9. Press 5 to return to the main menu.
  10. Press 3 to save the new function key definitions. This creates the cobkeymp file.
  11. You can review the changes you have just made by pressing 1. This enters the Review Existing Function Key Definitions menu. Press 2 from this menu to review the Animator key list definitions. This shows the values of all keys in the Animator key list and contains the new values entered.
  12. Press 6 to return to the main menu when you have reviewed all of the Animator function keys.
  13. Press 4 to exit.

In order to demonstrate the changes you have just made using the Keyboard Configuration utility, it is necessary to invoke Animator.

After entering Animator, the Animator screen appears.

When you press:

Key | Description
F1=Help | Nothing happens because the definition of Animator function key 1 was deleted.
<up-arrow> | Nothing happens because the definition of <up-arrow> was changed.
Ctrl+U | The cursor moves up one line. This is because Ctrl+U was mapped onto the function to move the cursor up one line.
<down-arrow> | This still moves the cursor down one line.
Ctrl+D | This also moves the cursor down one line because Ctrl+D was inserted as a new definition, and the old definition (<down-arrow>) was retained.

The defaults can be recovered by either using the Keyboard Configuration utility and returning the key definitions to their old values, or by simply deleting cobkeymp.

Parent topic: Keyboard Configuration Utility (Keybcf)


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
  • Invoking Profiler from the Command Line
  • Profiler Output
  • Time Spent in Called Programs
  • Directives for Profiler
Parent topic: Command line reference


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
Invoking 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=/myipfdir

Profiler cannot be used on programs running multiple threads.

Parent topic: Profiler
Related information
Introduction to Profiler
Invoking Profiler from the Command Line
Profiler Output
Time Spent in Called Programs
Directives for Profiler


Invoking Profiler from the Command Line

To start Profiler from the command prompt, use the following command:

cobprof filenames directives

where the parameters are:

filenames
One or more files containing compact Profiler output. Profiler always searches for a file with the filename extension .ipf; if you specify any other extension, it is ignored.
directives
One or more of the directives that control the operation of Profiler. To specify a directive to Profiler, you must precede it with a plus sign (+). You can precede each directive with a plus sign; alternatively, you can specify one at the start of a list of directives.

Directives must be separated by one or more spaces. Where a Profiler directive takes a parameter, you can enclose the parameter either in quotation marks or in parentheses. If you use either of these, however, you must escape them using the backslash character ( \).

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 submit to the Cob utility the program prog1 with the PROFILE directive set, run the program, and then enter:

cobprof prog1 +LIST

the following output is produced on the console:

* Micro Focus COBOL Profiler
* 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.

Parent topic: Profiler
Related information
Introduction to Profiler
Producing Profiler Statistics
Invoking 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.

If the profile_behavior run-time tunable is set to 0 (the default), then time spent in a profiled called program is recorded both in the called program and in the calling program.

If the profile_behavior run-time tunable is set to 1, then time spent in a profiled called program is recorded only in the called program.

For example, suppose program prog_a calls program prog_c. prog_a is a profiled COBOL program. Then:

  • If prog_c is not COBOL, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL but is not profiled, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL and profiled, time spent in prog_c is recorded in prog_c, and not in prog_a

If prog_a actually calls prog_b, which calls prog_c, and prog_b is not a profiled COBOL program, then time in prog_b is always recorded in prog_a, while time in prog_c is recorded as explained above.

Parent topic: Profiler
Related information
Introduction to Profiler
Producing Profiler Statistics
Invoking 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
Invoking Profiler from the Command Line
Profiler Output
Time Spent in Called Programs


The cobutf8 Utility

The cobutf8 utility enables you to seamlessly run applications that require non-UTF-8 character encodings in an environment that is using a UTF-8 locale.

The required conversion process uses the iconv() API to convert your application's input and output data from the system locale to a target locale specified by the COBUTF8 environment variable. The target locale must be mapped to a character set supported by iconv() using a special configuration file. During the conversion process, any character that does not exist in both the UTF-8 locale and the target locale cannot be mapped, and is substituted for a ? character.

The cobutf8 utility determines the UTF-8 locale as one of the following:

  • If the LANG environment variable is set, its value is used as the UTF-8 encoding. cobutf8 will also inherit any values from the LC_* variables (except LC_ALL); for example, set a different value for LC_MONETARY and that UTF-8 locale value will override the value for LANG where appropriate.
  • If the LC_ALL environment variable is set, only that value is used as the locale in the conversion process.
  • Configuring the cobutf8 Configuration File
  • Running Your Application Through the cobutf8 Utility
  • cobutf8 Error Messages
Parent topic: Command line reference


Configuring the cobutf8 Configuration File

The configuration file is located in the $COBDIR/etc directory, and is named cobutf8.cfg. You must not rename or move this file, otherwise you will receive an error when running the utility.

This file comes pre-configured with the mappings for Japanese Shift-JIS character encodings. You can also add your own mappings, specifying one or more supported locales, and mapping them to character sets supported by the iconv() function.

Add a mapping

Tip: To list the supported locales, use the locale -a command; to list the character sets supported by iconv(), use the iconv -l command.

To add a new mapping, open the configuration file in a text editor, and on a new line, enter at least one target locale - if you are planning to map other locales to the same character set, also enter those locales on the same line, delimited by one or more whitespace characters. Delimited again by whitespace, enter a character set supported by iconv() on the same line.

In the following example configuration file, a new mapping has been added for the Korean locale:

# Additional mappings can be added using the following format:
# <LOCALE> [LOCALE2 ...] <ICONV>\n
# Key:	<...> 	Mandatory#	[...]	Optional
# Values can be delimited using any non-line breaking whitespace.
# <ICONV> must be followed by a newline.
ja_JP.sjis  ja_JP.SJIS   SJIS-OPEN    #Shift-JIS
ja_JP.ujis  ja_JP.UJIS   UJIS         #UJIS
ja_JP.eucJP ja_JP.eucjp  EUCJP-OPEN   #EUC Japanese
ko_KR.euckr              CP949        #Korean
Parent topic: The cobutf8 Utility
Related information
Running Your Application Through the cobutf8 Utility
cobutf8 Error Messages


Running Your Application Through the cobutf8 Utility

Before running your COBOL application through the cobutf8 utility, you must configure the cobutf8.cfg configuration file with a valid mapping, and then set the COBUTF8 environment variable to a valid target locale specified in the mapping.

Once you have set these two pre-requisites, you can run your application from the command line using the following syntax:

cobutf8 <command-line>

where command line is your target program and any command-line arguments it requires. For example, the following command runs the my-shiftjis.int program through cobutf8:

cobutf8 cobrun my-shiftjis.int
Parent topic: The cobutf8 Utility
Related information
Configuring the cobutf8 Configuration File
cobutf8 Error Messages


cobutf8 Error Messages

The following error messages may be generated when running your application through the cobutf8 utility:

Could not execute cmdline <cmdline>
cobutf8 could not execute the program specified. Make sure that the syntax is correct and that the specified program exists.
Internal COBUTF8 Error: <error no>
Internal error; contact SupportLine, quoting <error no>.
Locale is not set to UTF-8
The system locale is not set to a UTF-8 locale; a UTF-8 locale is a pre-requisite of the cobutf8 utility.
COBUTF8 not set
The COBUTF8 environment variable is not set; set this variable to a target locale specified in cobutf8.cfg (e.g. COBUTF8=ja_JP.sjis).
Failed to set locale: <locale>. Please set environment variable COBUTF8 to a valid locale
The locale stored in the COBUTF8 environment variable is not supported by the operating system; ensure that COBUTF8 is set to a valid locale.

A list of valid locales can be found in the cobutf8.cfg configuration file - located in $COBDIR/etc/.

To list the supported locales, use the locale -a command. If the one you require is not listed, you can install it using the following command:

localedef -f <locale-name> -i <file-name>

For example:

localedef -f SHIFT_JIS -i ja_JP ja_JP.SJIS
Invalid conversion mapping between <locale1> -> <locale2>
cobutf8 failed to create a conversion mapping between UTF-8 and the target iconv; ensure that a valid iconv entry exists in the cobutf8.cfg configuration file.
Use the iconv -l command for a list of valid iconvs.
Could not map locale <locale> to iconv encoding

The locale specified by the COBUTF8 environment variable does not have a iconv mapping to a valid character set; either set COBUTF8 to a locale specified in the cobutf8.cfg configuration file, or edit the configuration file to adding your own mapping.

Failed to open mapping file: <path>
The cobutf8 utility failed to open the cobutf8.cfg configuration file; ensure that the file is located in $COBDIR/etc/, and that you have read access to the file.
Parent topic: The cobutf8 Utility
Related information
Configuring the cobutf8 Configuration File
Running Your Application Through the cobutf8 Utility
COBOL


Compiler Directives

Restriction: Some compiler directives can be used only if you have certain features installed, or if you are using them with a particular platform or interface.
  • Language Features
  • Compiler Control
  • Compiling for Debugging and Analysis
  • File Handling
  • Managed COBOL Command Line Compiler Directives
  • Object Code, Size, and Optimization
  • Report Writer
  • Reserved Directives
  • Run-time Behavior
  • Key to Compiler Directives
  • Compiler Directives - Alphabetical List
Parent topic: General Reference
Related concepts
Setting Compiler Directives
Related information
Using Compiler Directives


Language Features

These directives change which language features your Compiler accepts.

  • Language Features - Dialect
  • Language Features - Mainframe Compatibility
  • Language Features - Multi-threading
  • Language Features - Reserved Word Control
  • Language Features - Speed
  • Language Features - Additional Features
Parent topic: Compiler Directives


Language Features - Dialect

  • ACTUAL-PARAMS
    Specifies actual parameters that are substituted for formal parameters in a parameterized class or interface.
  • ACU
    Enables compatibility with ACUCOBOL-GT COBOL.
  • ACU-COMMENT
    Treats lines of code starting with a pipe (|) as comment lines.
  • ACUOPT
    Enables you to set various options specifically for compilation of ACUCOBOL-GT applications.
  • ACUSYNC
    Changes the effect of the SYNC clause so that it matches that used in ACU programs.
  • ACU-UNDERSCORE
    Treats underscores in COBOL words as hyphens.
  • ANS85
    Specifies that words reserved in the ANSI'85 COBOL Standard are to be treated as reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that Standard.
  • BS2000
    Ensures that words reserved under the Siemens BS2000 COBOL dialect are reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that COBOL dialect.
  • DBCHECK
    Makes the Compiler check that any Double-byte Character Set (DBCS) literals only contain valid 16-bit DBCS characters.
  • DBCS
    Makes the Compiler accept characters of the Double-byte Character Set (DBCS) for use in ideographic languages such as Japanese, Chinese and Korean.
  • DBCSSOSI
    Defines the two characters used as the shift-out and shift-in delimiters in DBCS literals.
  • DG
    Changes the behavior of certain features to be compatible with Data General Interactive COBOL rev 1.30.
  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • ENTCOBOL
    Specifies that words reserved in IBM Enterprise COBOL for z/OS and OS/390 are to be treated as reserved words..
  • FLAG
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified dialect of COBOL.
  • FLAGSTD
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified level of the ANSI'85 Standard.
  • IBM-MS
    Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • ISO2002
    Specifies that words reserved in the ISO2002 COBOL Standard are to be treated as reserved words, and changes the behavior of certain features to be compatible with that standard.
  • JAPANESE
    Enables the use of Micro Focus Japanese Language Extension (PIC N, Japanese data-names and Japanese procedure-names).
  • MF, MFLEVEL
    Enables forward compatibility with Micro Focus COBOL systems by selectively enabling Micro Focus-specific reserved words and changing the behavior of certain features to be compatible with particular versions.
  • MS
    Facilitates forward compatibility with Microsoft COBOL systems by selectively enabling Microsoft-specific reserved words and changing the behavior of certain features to be compatible with particular versions.
  • NATIONAL
    Enables you to select the level of NATIONAL support.
  • NCHAR
    Enables the use of Micro Focus Double-byte Language Extension (PIC N, Japanese data-names and Japanese procedure-names).
  • NSYMBOL
    Defines the default USAGE for PIC N clauses and controls the interpretation of national literals.
  • OOCTRL
    Enables you to change language options when compiling OO COBOL classes and interfaces.
  • OSVS
    Specifies that words reserved in IBM OS/VS COBOL are to be treated as reserved words.
  • PC1
    Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • RM
    Specifies that words reserved in RM/COBOL are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • RTNCODE-TYPE
    Defines the numeric type of the RETURN-CODE special register.
  • VSC2
    Specifies that words reserved in IBM VS COBOL II are to be treated as reserved words, and enables selected features for compatibility with a given level of that COBOL system.
  • XOPEN
    Specifies that words reserved under the X/Open definition of COBOL are to be treated as reserved words.
Parent topic: Language Features


ACTUAL-PARAMS

Specifies actual parameters that are substituted for formal parameters in a parameterized class or interface.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----ACTUAL-PARAMS--"parameters"--.-------><
   +-/-+ +-NO-ACTUAL-PARAMS----------------+

Parameters:

parameters A maximum of 32 space-separated parameters. At least one parameter must be specified.

Properties:

Default: | NOACTUAL-PARAMS
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related concepts
The Repository Paragraph
Related reference
REPOSITORY
RDFPATH


ACU

Enables compatibility with ACUCOBOL-GT COBOL.

Syntax:

>>--.---.--.----.--ACU------><
    +-/-+--+-NO-+

Parameters:

None

Properties:

Default: | NOACU
Phase: | Syntax check
$SET: | Initial

Dependencies:

ACU sets ACU-SYNC, ACU-COMMENT, ACU-UNDERSCORE, LOCAL-SOURCEFORMAT, MFSYNC"8", ALIGN"8 OPT", COMP-5"1", COMP-6"3", DISPLAY"CRT", IDENTIFIERLEN"62", NOMFCOMMENT, NORESEQ, SIGN"ACU", TRUNC"ACU"

ACU is set by ACUOPT and DIALECT"ACU".

Comments:

Setting ACU enables some ACU extensions to the language and implements changes of behavior for compatibility with ACUCOBOL-GT COBOL. Refer to ACUCOBOL-GT Syntax Extensions for more information.

ACU also sets acu_library, which in turn enables a library routine (C$RERR) designed to help you obtain extended error information for file operations, and external variables containing other error information.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related reference
C$RERR
acu_library


ACU-COMMENT

Treats lines of code starting with a pipe (|) as comment lines.

Syntax:

 >>-.---.-.----.--ACU-COMMENT---><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOACUCOMMENT
Phase: | Syntax check
$SET: | Any
Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


ACUOPT

Enables you to set various options specifically for compilation of ACUCOBOL-GT applications.

Syntax:

>>--.---.-----ACUOPT--(option)----><
    +-/-+

Parameters:

option
The ACU compiler option in the form -Xx or --option.
Refer to Supported ACUCOBOL-GT Compiler Options for details on the options you can set.

Properties:

Default: | None
Phase: | Syntax check
$SET: | Initial

Comments:

Setting any option using ACUOPT automatically sets the ACU compiler directive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related reference
Supported ACUCOBOL-GT Compiler Options


ACUSYNC

Changes the effect of the SYNC clause so that it matches that used in ACU programs.

Syntax:

>>--.---.---ACUSYNC------><
    +-/-+

Parameters:

None

Properties:

Default: | Standard SYNC clause behavior
Phase: | Syntax check
$SET: | Initial

Comments:

A synchronized elementary item always causes any containing group item to be aligned on the boundary of the most restrictive synchronized elementary item, and that group to be padded at the end to a multiple of that size. e.g. a group containing an elementary data item that was "DOUBLE SYNC" will always be aligned on an 8 byte boundary and will be padded to be a multiple of 8 bytes long.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


ACU-UNDERSCORE

Treats underscores in COBOL words as hyphens.

Syntax:

>>-.---.-.----.-ACU-UNDERSCORE------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOACU-UNDERSCORE
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"ACU" and ACU both set ACU-UNDERSCORE

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


ANS85

Specifies that words reserved in the ANSI'85 COBOL Standard are to be treated as reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that Standard.

Syntax:

>>-.----.-.-------ANS85---"SYNTAX"--.--------><
   +-/--+ +.----.-ANS85-------------+
           +-NO-+

Parameters:

SYNTAX Makes the directive affect syntax only and not behavior.

Properties:

Default: | ANS85
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to ANS85 at end by COBOL370, ENTCOBOL, MVS, OS390, SAA"2", VSC2"3" or VSC2"4".

Comments:

This directive causes the following behavior changes:

  • The I/O status values are those defined in ANSI'85.
  • The ALPHABETIC class test regards lower case as alphabetic.
  • Control variables in PERFORM operations are initialized in the order specified by ANSI'85.
  • Move operations to a variable-length group item use the maximum length of the target if the DEPENDING ON item is in the group.
Parent topic: Language Features - Dialect
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


BS2000

Ensures that words reserved under the Siemens BS2000 COBOL dialect are reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that COBOL dialect.

Syntax:

>>-.---.-.----.--BS2000---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOBS2000
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


DBCHECK

Makes the Compiler check that any Double-byte Character Set (DBCS) literals only contain valid 16-bit DBCS characters.

Syntax:

>>-.---.-.----.--DBCHECK-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | DBCHECK
Phase: | Syntax check
$SET: | Initial

Comments:

If you specify DBCHECK in environments that support validation of DBCS data, any literal that does not contain only valid 16-bit DBCS characters results in syntax error 1048 (DBCS literal includes invalid data).

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


DBCS

Makes the Compiler accept characters of the Double-byte Character Set (DBCS) for use in ideographic languages such as Japanese, Chinese and Korean.

Syntax:

>>-.---.-.-------DBCS-"integer"-.---------><
   A-/-+ +.----.-DBCS-----------+
          +-NO-+

Parameters:

integer
One of:
1
Behavior as in earlier versions of this Compiler.
2
Provides full System Application Architecture (SAA) DBCS support. This directive sets DBSPACE.
3
Includes DBCS support as in IBM COBOL/370. This includes the use of PIC N, PIC G, and DBCS literals specified with "delimiter N".

Properties:

Default: | NODBCS
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to DBCS"2" immediately by SAA, VSC2"2", VSC2"3" or MF"7".

Set to DBCS"3" immediately by COBOL370 or MF"integer" where integer > 7.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


DBCSSOSI

Defines the two characters used as the shift-out and shift-in delimiters in DBCS literals.

Syntax:

 >>-.---.-.----DBCSSOSI-"integer-1"-"integer-2"-.--><
    +-/-+ +-NO-DBCSSOSI-------------------------+

Parameters:

integer-1 | ASCII code of the shift-out character, in decimal.
integer-2 | ASCII code of the shift-in character, in decimal.

Properties:

Default: | NODBCSSOSI
Phase: | Syntax check
$SET: | IAny

Comments:

When shift-out and shift-in characters are specified by this directive, every DBCS literal must have the shift-out character immediately after the opening quotation mark and the shift-in character immediately before the closing quotation mark. They act as additional delimiters to the literal, and are not part of its value. With NODBCSSOSI, no shift-out and shift-in characters are needed or recognized.

Parent topic: Language Features - Dialect
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Mainframe Compatibility
Key to Compiler Directives


DIALECT

Enables check-time and run-time behavior consistent with the specified dialect.

Syntax:

>>--.---.----DIALECT--"dialect"-----------><
    +-/-+

Parameters:

dialect
The dialect to use. Other compiler directives are set depending on the value. Valid values are listed in the Comments section below.

Properties:

Default: | DIALECT"MF"
Phase: | Check
$SET: | Initial

Dependencies:

Depending on the setting of dialect, various other Compiler directives are set by default.

Comments:

The settings SAA1 and SAA2 are also available; use these for backward compatibility purposes only.

Note: Under your COBOL development system, the DIALECT directive does not set the AMODE directive. To provide compatibility with mainframe style pointers, you will need to set AMODE to the appropriate storage format.

Valid dialect values are listed below. Click on a value to see the other compiler directives that are set for each dialect.

Examples

DIALECT"ANS85"
This sets the dialect to emulate the ANS85 COBOL.

Some directives set by DIALECT are the same as those set by default by the Compiler. However, you need to know the setting of a dialect-specific directive as it might overwrite the setting you expect. For example:

ALIGN"2 OPT" DIALECT"ANS85"
This sets ALIGN to ALIGN"8 OPT", since this is the value set by the DIALECT"ANS85".
ALIGN"2 OPT" DIALECT"MF"
This also sets ALIGN to ALIGN"8 OPT", since the MF dialect sets the directives to their default values. For ALIGN, the default is ALIGN"8 OPT".
  • ACU DIALECT setting
  • ANS85 DIALECT setting
  • BS2000 DIALECT setting
  • BS2000-OFFLOAD DIALECT setting
  • COBOL370, COBOL371 and COBOL372 DIALECT settings
  • DOSVS DIALECT setting
  • ENTCOBOL DIALECT setting
  • ISO2002 DIALECT setting
  • MF DIALECT setting
  • MVS DIALECT setting
  • OS390 DIALECT setting
  • OSVS DIALECT setting
  • RM DIALECT setting
  • VSC21 and VSC22 DIALECT settings
  • VSC23 and VSC24 DIALECT settings
Parent topic: Language Features - Dialect
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Control - Directives Control
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
AMODE
Language Features - Dialect


ACU DIALECT setting

If you set DIALECT"ACU", the following Compiler directives are set:

ACU

ACU-COMMENT

ACU-SYNC

ACU-UNDERSCORE

ALIGN"8 OPT"

COMP1"BINARY"

COMP2"DECIMAL"

COMP-5"1"

COMP-6"3"

DISPLAY"CRT"

NOFASTINIT

IDENTIFIERLEN"62"

LOCAL-SOURCEFORMAT

NOMFCOMMENT

MFSYNC"8"

NORESEQ

SIGN"ACU"

TRUNC"ACU"

Parent topic: DIALECT


ANS85 DIALECT setting

If you set DIALECT"ANS85", the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

ANS85

ARITHMETIC"MF"

NOBS2000

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

COPYEXT"cbl,CPY,"

COPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"32"

NODG

DPC-IN-SUBSCRIPT

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFASTINIT

NOFDCLEAR

NOFLAG

NOFLAGAS

NOFLAGMIG

FLAGSTD"H C2 D2 S2 R O"

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

IOCONV

NOISO2002

NOLIBRARIAN

NOMAPNAME

NOMF

NOMFCOMMENT

NOMS

NOODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOLDREADINTO

NOOLDSTRSUB

NOOPTIONAL-FILE

NOPC1

PERFORM-TYPE"MF"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

NORDW

RECMODE"F"

REMAINDER"1"

NORESEQ

NORM

NOSEQCHK

SOURCEFORMAT"FIXED"

NOSPZERO

NOSTICKY-LINKAGE

NOSTICKY-PERFORM

SYMBSTART"1"

TRUNC"ANSI"

TRUNCCALLNAME"8"

NOTRUNCCOPY

WARNING"3"

NOXOPEN

ZEROLENGTHFALSE

NOZEROSEQ

NOZWB

Parent topic: DIALECT


BS2000 DIALECT setting

If you set DIALECT"BS2000", the following Compiler directives are set:

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

ARITHMETIC"MF"

ASSIGN"EXTERNAL"

BS2000

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"ANSI"

NOCOMS85

COPYEXT"cbl,CPY,"

NOCOPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

DPC-IN-SUBSCRIPT

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFASTINIT

NOFDCLEAR

FLAG"BS2000"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

IOCONV

ISO2002

NOLIBRARIAN

NOMAPNAME

NOMF

NOMFCOMMENT

NOMS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOLDREADINTO

NOOLDSTRSUB

NOOPTIONAL-FILE

NOPC1

PERFORM-TYPE"MF"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

NORDW

RECMODE"F"

REMAINDER"1"

NORESEQ

NORM

RTNCODE-TYPE"COMP5"

RTNCODESIZE"4"

NOSEQCHK

SOURCEFORMAT"FIXED"

NOSPZERO

NOSTICKY-LINKAGE

NOSTICKY-PERFORM

SWITCH-TYPE"3"

SYMBSTART"1"

TRUNC

NOTRUNCCOPY

WARNING"3"

NOXOPEN

ZEROLENGTHFALSE

NOZEROSEQ

NOZWB

Parent topic: DIALECT


BS2000-OFFLOAD DIALECT setting

If you set DIALECT"BS2000-OFFLOAD", the following Compiler directives are set:

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

ARITHMETIC"MF"

ASSIGN"EXTERNAL"

BS2000-OFFLOAD

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

NOCOMS85

COPYEXT"cbl,CPY,"

NOCOPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

DPC-IN-SUBSCRIPT

NODG

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFASTINIT

NOFDCLEAR

FLAG"BS2000"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

IOCONV

ISO2002

NOLIBRARIAN

NOMAPNAME

NOMF

NOMFCOMMENT

NOMS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOLDREADINTO

NOOLDSTRSUB

NOOPTIONAL-FILE

NOPC1

PERFORM-TYPE"MF"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

NORDW

RECMODE"F"

REMAINDER"1"

NORESEQ

NORM

RTNCODE-TYPE"COMP5"

RTNCODESIZE"4"

NOSEQCHK

SOURCEFORMAT"FIXED"

NOSPZERO

NOSTICKY-LINKAGE

NOSTICKY-PERFORM

SWITCH-TYPE"2"

SYMBSTART"1"

TRUNC

NOTRUNCCOPY

WARNING"3"

NOXOPEN

ZEROLENGTHFALSE

NOZEROSEQ

NOZWB

Parent topic: DIALECT


COBOL370, COBOL371 and COBOL372 DIALECT settings

If you set DIALECT"COBOL370", DIALECT"COBOL371" or DIALECT"COBOL372", the following Compiler directives are set:

ADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"COBOL370"

COBOL370"2" (for DIALECT"COBOL370")

COBOL370"2" (for DIALECT"COBOL372")

COBOL370"1" (for DIALECT"COBOL371")

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"COBOL370"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"COBOL370"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

RDW

RECMODE"COBOL370"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

NOSTICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

WARNING"3"

NOXOPEN

NOXREF

ZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


DOSVS DIALECT setting

If you set DIALECT"DOSVS" the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

APOST

AREACHECK

ARITHMETIC"OSVS"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"OSVS"

NOCOBOL370

NOCOMS85

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

DOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"DOSVS"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"OSVS"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"OSVS"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OSVS"

REMAINDER"2"

REPORTLINE"132"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

SEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"LINE"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

STICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

TRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

NOVSC2

WARNING"3"

NOXOPEN

NOXREF

NOZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT
Related reference
DOSVS COBOL Support
DOSVS


ENTCOBOL DIALECT setting

If you set DIALECT"ENTCOBOL" the following Compiler directives are set:

ADV

ALIGN"4 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"ENTCOBOL"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"ENTCOBOL"

COBSTATCONV

NOCOBOL370

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

ENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"ENTCOBOL"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"ENTCOBOL"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

NSYMBOL"NATIONAL"

ODOSLIDE

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"ENTCOBOL"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"ENTCOBOL"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

NOSTICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

NOVSC2

WARNING"3"

NOXOPEN

NOXREF

ZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


ISO2002 DIALECT setting

If you set DIALECT"ISO2002" the following Compiler directives are set:

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

ARITHMETIC"MF"

NOBS2000

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

NOCOMS85

COPYEXT"cbl,CPY,"

COPYLBR

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"32"

NODG

DPC-IN-SUBSCRIPT

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

NOFASTINIT

NOFDCLEAR

FLAG"ISO2002"

NOFLAGAS

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

INFORETURN"U"

IOCONV

ISO2002

NOLIBRARIAN

NOMAPNAME

NOMF

NOMFCOMMENT

NOMS

NOODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOLDREADINTO

NOOLDSTRSUB

NOOPTIONAL-FILE

NOPC1

PERFORM-TYPE"MF"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

NORDW

RECMODE"F"

REMAINDER"1"

NORESEQ

NORM

NOSEQCHK

SOURCEFORMAT"FIXED"

NOSPZERO

NOSTICKY-LINKAGE

NOSTICKY-PERFORM

SYMBSTART"1"

TRUNC"ANSI"

NOTRUNCCOPY

WARNING"3"

NOXOPEN

ZEROLENGTHFALSE

NOZEROSEQ

NOZWB

Parent topic: DIALECT


MF DIALECT setting

If you set DIALECT"MF" the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

NOAREACHECK

ARITHMETIC"MF"

ASSIGN"DYNAMIC"

BOUND

NOBYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"ASCII"

CHECKDIV"ANSI"

NOCOBOL370

NOCOBSTATCONV

NOCOMS85

COPYEXT"cbl,CPY,"

NOCOPYLBR

COPYLIST

CURRENT-DATE"MMDDYY"

DATE

DBCHECK

DBCS"3"

NODBCSSOSI

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"32"

NODG

NODOSVS

DYNAM

ECHO

NOENTCOBOL

NOEXTINDEX

FASTINIT

NOFDCLEAR

NOFLAG

NOFLAGAS

NOFLAGCD

NOFLAGMIG

NOFLAGSTD

NOFOLDCALLNAME

NOFOLDCOPYNAME

FORM"60"

NOFP-ROUNDING

NOHOSTNUMCOMPARE

NOHOSTNUMMOVE

NOIBM-MS

NOIBMCOMP

NOINDD

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

NOMAPNAME

MF

MFCOMMENT

NOMS

NOODOOSVS

NOODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOLDREADINTO

NOOLDSTRSUB

OPTIONAL-FILE

NOOS390

NOOSVS

NOOUTDD

NOPANVALET

NOPC1

PERFORM-TYPE"MF"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

QUOTE

NORDW

RECMODE"F"

REMAINDER"1"

REPORTLINE"256"

RESEQ

NORM

RTNCODESIZE"4"

NOSAA

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS

SOURCEFORMAT"FIXED"

NOSPZERO

NOSTICKY-LINKAGE

NOSTICKY-PERFORM

SYMBSTART"1"

NOTRACE

TRUNC"ANSI"

NOTRUNCCOPY

NOVSC2

WARNING"1"

NOXOPEN

NOXREF

NOZEROLENGTHFALSE

NOZEROSEQ

NOZWB

Parent topic: DIALECT


MVS DIALECT setting

If you set DIALECT"MVS" the following Compiler directives are set:

ADV

ALIGN"4 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"COBOL370"

NOCOBOL370

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSOSSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"MVS"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

MVS

NOMF

NOMFCOMMENT

NOMS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"MVS"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"COBOL370"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

NOSTICKY-PERFORM

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

WARNING"3"

NOXOPEN

NOXREF

NOZEROSEQ

ZEROLENGTHFALSE

ZWB

Parent topic: DIALECT


OS390 DIALECT setting

If you set DIALECT"OS390" the following Compiler directives are set:

ADV

ALIGN"4 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"OS390"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"OS390"

NOCOBOL370

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"3"

DBCSOSSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"OS390"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"OS390"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NODYNAM

NOMF

NOMFCOMMENT

NOMS

NOMVS

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOSVS

ODOSLIDE

OUTDD"SYSOUT 121 R"

OS390

NOPANVALET

NOPC1

PERFORM-TYPE"OS390"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OS390"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

NOSTICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

NOVSC2

WARNING"3"

NOXOPEN

NOXREF

NOZEROSEQ

ZEROLENGTHFALSE

ZWB

Parent topic: DIALECT


OSVS DIALECT setting

If you set DIALECT"OSVS" the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

APOST

AREACHECK

ARITHMETIC"OSVS"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"OSVS"

NOCOBOL370

NOCOMS85

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

NODBCHECK

NODBCS

NODBCSSOSI

NODBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"OSVS"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"OSVS"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

OSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"OSVS"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OSVS"

REMAINDER"2"

REPORTLINE"132"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

SEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"LINE"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

STICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

TRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

NOVSC2

WARNING"3"

NOXOPEN

NOXREF

NOZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


RM DIALECT setting

Note: This directive setting should only be used for native COBOL programs.

If you set DIALECT"RM", the following Compiler directives are set:

ALIGN"4 FIXED"

ASSIGN-PRINTER""

COMP"UNPACKED"

COMP1"BINARY"

COMP2"DECIMAL"

COMP-5"1"

COMP-6"3"

COPYSEARCH"RM"

COPYEXT",cbl,CBL"

DEFAULTCALLS"1024"

DISPLAY"CRT"

NOFASTINIT

FILETYPE"21"

FILESHARE

IBMCOMP

IDXFORMAT"21"

NOOLDINDEX

NOOPTIONAL-FILE

PARAMCOUNTCHECK

PERFORM-TYPE"RM"

RECMODE"RMCOBOL"

RETRYLOCK

RM"ANSI"

SEQUENTIAL"RECORD"

SIGN"TRAILING"

SIGN"EBCDIC"

NOTRUNC

Comments:

RM/COBOL does not have COMP-2 usage; the setting listed here is for completeness.

If your RM/COBOL application relies on the EXPANDED-PATH-SEARCH configuration option to locate files specified with a relative path name, you must override COPYSEARCH"RM" with the COPYSEARCH"RM-EXPANDED" Compiler directive for equivalent behavior.

An internal flag is set that supports the RM/COBOL feature of being able to specify any type of data item in the GIVING or RETURNING phrase of a CALL statement.

The LOCKING clause of the SELECT statement is set to LOCK MODE IS AUTOMATIC for all file types.

For IBMCOMP, only the subset of flags that cause word-storage mode for binary items in the same manner as RM/COBOL are set.

Although this directive sets RM"ANSI", it does not have the same effect as setting RM"ANSI" directly. Only when set directly, does RM"ANSI" set the additional directives specified in the RM Compiler directive topic.

If you configured RM/COBOL to use the SEQUENTIAL-FILE-TYPE=LINE option at compile time, you will need to add the SEQUENTIAL"LINE" directive after the DIALECT"RM" directive. Similarly, if you did not configure the RM/COBOL compiler sequential organization file default type but did configure the RM/COBOL runtime sequential organization file type with the DEFAULT-TYPE keyword of the RUN-SEQ-FILES configuration record identifier, you will need to add the SEQUENTIAL"LINE" directive after the DIALECT"RM" directive.

If you used the RM/COBOL compiler S option or the compiler configuration SEPARATE-SIGN=YES, you will need to add the SIGN"SEPARATE" directive after the DIALECT"RM" directive.

Parent topic: DIALECT


VSC21 and VSC22 DIALECT settings

If you set DIALECT"VSC21" or DIALECT"VSC22" the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

NOANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"VSC2"

NOCOBOL370

COBSTATCONV

NOCOMS85

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"2"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"VSC2"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

IBMCOMP

NOIBM-MS

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

ODOSLIDE

NOODOOSVS

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"VSC2"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"OSVS"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

STICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCALLNAME"8"

TRUNCCOPY"8"

VSC2"1" (for VSC21), VSC2"2" (for VSC22)

WARNING"3"

NOXOPEN

NOXREF

ZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


VSC23 and VSC24 DIALECT settings

If you set DIALECT"VSC23" or DIALECT"VSC24" the following Compiler directives are set:

NOADV

ALIGN"8 OPT"

ALPHASTART"1"

ALTER

ANS85

APOST

AREACHECK

ARITHMETIC"VSC2"

ASSIGN"EXTERNAL"

NOBOUND

BYTEMODEMOVE

CALLFH

CALLSORT"EXTSM"

CANCELLBR

CHARSET"EBCDIC"

CHECKDIV"VSC2"

NOCOBOL370

COBSTATCONV

COPYEXT"CPY,CBL"

COPYLBR

COPYLIST

COPYLISTCOMMENT"7"

CURRENT-DATE"MMDDYY"

DBCHECK

DBCS"2"

DBCSSOSI"14""15"

DBSPACE

DE-EDIT"2"

DEFAULTBYTE"00"

NODG

NODOSVS

DPC-IN-SUBSCRIPT

NODYNAM

ECHO

NOENTCOBOL

ERRLIST"VERBOSE"

NOEXTINDEX

NOFASTINIT

FDCLEAR

FLAG"VSC2"

FLAGAS"S"

NOFLAGMIG

NOFLAGSTD

FOLDCALLNAME"UPPER"

FOLDCOPYNAME"UPPER"

FORM"60"

FP-ROUNDING"VSC2"

HOSTCONTZERO

HOSTFD

HOSTNUMCOMPARE"2"

HOSTNUMMOVE"2"

NOIBM-MS

IBMCOMP

INDD"SYSIN 80 R"

INFORETURN"0"

NOLIBRARIAN

LISTWIDTH"80"

MAPNAME

NOMF

NOMFCOMMENT

NOMS

NOMVS

NOODOOSVS

ODOSLIDE

NOOLDCOPY

NOOLDINDEX

NOOLDNEXTSENTENCE

NOOPTIONAL-FILE

NOOS390

NOOSVS

OUTDD"SYSOUT 121 R"

NOPANVALET

NOPC1

PERFORM-TYPE"VSC2"

NOPROGID-COMMENT

NOPROTECT-LINKAGE

QUAL

QUALPROC

RDW

RECMODE"VSC23"

REMAINDER"2"

RESEQ

NORM

RTNCODESIZE"2"

NOSAA

NOSEG

NOSEQCHK

SEQUENTIAL"RECORD"

SETTINGS"COL"

SOURCEFORMAT"FIXED"

NOSPZERO

STICKY-LINKAGE"1"

NOSTICKY-PERFORM

SYMBSTART"1"

SYSPUNCH"80"

NOTRACE

NOTRUNC

TRUNCCOPY"8"

VSC2"3" (for VSC23)

VSC2"4" (for VSC24)

WARNING"3"

NOXOPEN

NOXREF

ZEROLENGTHFALSE

NOZEROSEQ

ZWB

Parent topic: DIALECT


ENTCOBOL

Specifies that words reserved in IBM Enterprise COBOL for z/OS and OS/390 are to be treated as reserved words..

Syntax:

 >>-.---.-.----.--ENTCOBOL-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOENTCOBOL
Phase: | Syntax check
$SET: | Initial

Dependencies:

ENTCOBOL sets DBSPACE and DBCS"3" immediately.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Dialect
Key to Compiler Directives


FLAG

Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified dialect of COBOL.

Syntax:

>>-.---.-.-----FLAG-----"dialect"-.--------><
   +-/-+ +-NO--FLAG---------------+

Parameters:

dialect
A literal identifying the dialect.
ANS74 | ANSI COBOL standard X3.23, 1974
ANS85 | ANSI COBOL standard X3.23, 1985
BS2000 | Siemens BS2000 COBOL
COBOL370 | IBM COBOL/370
DOSVS | IBM DOS/VS COBOL
ENTCOBOL | IBM Enterprise COBOL
ISO2002 | ISO2002 COBOL standard
MVS | IBM MVS COBOL
MF | Micro Focus
OS390 | IBM OS390 COBOL
OSVS | IBM OS/VS COBOL
SAA | Full implementation of IBM's System Application Architecture definition of COBOL
VSC2 | IBM VS COBOL II

Properties:

Default: | NOFLAG
Phase: | Syntax check
$SET: | Any

Comments:

You cannot use DG, RM or MS as a dialect.

When creating a program that is to be fully ANSI'85 or ISO2002 conforming, use:

ANS85 FLAG"ANS85"

or

ISO2002 FLAG"ISO2002"

and correct anything that causes a flagging message to be produced.

Parent topic: Language Features - Dialect
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related concepts
DIALECT
Related reference
FLAGAS
WARNING, WARNINGS


FLAGSTD

Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified level of the ANSI'85 Standard.

Syntax:

>>-.---.-.-----FLAGSTD--"string"-.---------><
   +-/-+ +-NO--FLAGSTD-----------+

Parameters:

string List of language levels

Properties:

Default: | NOFLAGSTD
Phase: | Syntax check
$SET: | Initial

Comments:

string contains a list of parameters, each defining a language level or optional module of the ANSI Standard. A feature is not flagged if it is in one of the specified levels or below, or in one of the specified optional modules. A feature is flagged if it is an extension, in a higher level of the Standard, or in an optional module not specified. In addition, it is possible to flag elements identified as Obsolete by the ANSI Standard.

string consists of a combination of the following parameters:

M | ANSI'85 defined Minimum COBOL subset
I | ANSI'85 defined Intermediate COBOL subset
H | ANSI'85 defined High COBOL subset
C1 | Communications optional module level 1
C2 | Communications optional module level 2
D1 | Debug optional module level 1
D2 | Debug optional module level 2
S1 | Segmentation optional module level 1
S2 | Segmentation optional module level 2
R | Report writer optional module
O | Obsolete language elements

They can appear in any order but must be separated by at least one space. The following combination of flags can be specified:

  • You must choose one of the following: M, I, H
  • You can choose as many of the following as desired: C1 or C2, D1 or D2, S1 or S2, R
  • You can also choose the following flag: O

FLAG and FLAGSTD provide similar functionality and thus only one can be used.

The ANS85 directive must be on.

Parent topic: Language Features - Dialect
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


IBM-MS

Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.

Syntax:

>>-.---.-.----.--IBM-MS--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOIBM-MS
Phase: | Syntax check
$SET: | Initial

Dependencies:

IBM-MS sets DEFAULTBYTE"0" and ACCEPTREFRESH immediately.

Comments:

This directive is synonymous with the PC1 and MS"1" directives.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


ISO2002

Specifies that words reserved in the ISO2002 COBOL Standard are to be treated as reserved words, and changes the behavior of certain features to be compatible with that standard.

Syntax:

>>-.----.-.----.---ISO2002-----------><
   +-/--+ +-NO-+

Parameters:

None

Properties:

Default: | NOISO2002
Phase: | Syntax check
$SET: | Initial

Comments:

For maximum compatibility with the ISO2002 standard, you should also set the DIALECT"ISO2002" directive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


JAPANESE

Enables the use of Micro Focus Japanese Language Extension (PIC N, Japanese data-names and Japanese procedure-names).

Syntax:

>>-.---.-.---------JAPANESE--"integer"-.-----><
   +-/-+ +-.----.--JAPANESE------------+
           +-NO-+

Parameters:

integer
The level of support required.
1
Compatibility with previous versions of Nihongo Micro Focus products.
2
Enhanced PIC N support. This setting enables the DBSPACE directive.

Properties:

Default: | NOJAPANESE
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying JAPANESE with no parameter is the same as specifying JAPANESE"2".

This directive is provided for compatibility purposes only. It has been replaced by the NCHAR directive. JAPANESE and NCHAR are synonymous. The JAPANESE and DBCS directives are mutually exclusive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


MF, MFLEVEL

Enables forward compatibility with Micro Focus COBOL systems by selectively enabling Micro Focus-specific reserved words and changing the behavior of certain features to be compatible with particular versions.

Syntax:

>>-.---.-.-------.-MF------.-"integer"-.---><
   +-/-+ |       +-MFLEVEL-+           |
         +.----.-.-MF------.-----------+
          +-NO-+ +-MFLEVEL-+

Parameters:

integer
The level of Micro Focus COBOL to be compatible with:
1
  • Professional COBOL V1.0, V1.1, and V1.2
  • Level II COBOL V2.5 and V2.6
  • Level II COBOL/ET V1.1
2
  • VS COBOL Workbench V1.2
  • VS COBOL V1.2
3
  • VS COBOL Workbench V1.3
  • VS COBOL Workbench V2.0
  • Professional COBOL V2.0
  • VS COBOL V1.5
4
  • COBOL/2 V1.1
  • Professional COBOL/2
  • COBOL/2 Workbench V2.2
  • Microsoft COBOL V3.0
5
  • COBOL/2 V1.2
  • COBOL/2 Workbench V2.3
6
  • COBOL/2 V2.4
  • COBOL/2 Workbench V2.4
  • Microsoft COBOL V4.0
7
  • COBOL/2 V2.5
  • COBOL/2 Workbench V2.5
  • Microsoft COBOL V4.5
8
  • COBOL V3.0
  • COBOL Workbench V3.0
  • Microsoft COBOL V5.0
9
  • COBOL V3.1
  • COBOL Workbench V3.1
10
  • COBOL V3.1 with Early Release syntax enabled
  • COBOL Workbench V3.1 with Early Release syntax enabled
  • COBOL V3.2 and V3.3
  • COBOL Workbench V3.2 and V3.3
  • Object COBOL V3.2 and V3.3
  • COBOL V4.0 (UNIX)
11
  • Visual Object COBOL 1.0
  • COBOL V3.4 and V4.0 with Early Release syntax enabled
  • COBOL Workbench V3.4 and V4.0 with Early Release syntax enabled
12
  • Mainframe Express 3.0 and 3.1; Net Express 4.0, 5.0, and 5.1; and Server Express 4.0, 5.0, and 5.1
13
  • Net Express 5.1 WS2
14
  • Net Express 6.0
15
  • Net Express 6.0 SP1; Net Express 5.1 WS5
  • Visual COBOL R1
16
  • Visual COBOL R3 or later; Enterprise Developer 2.0
17
  • Visual COBOL and Enterprise Developer 2.2 Update 1 or later.
18
  • Visual COBOL and Enterprise Developer 2.2 Update 2 or later.
19
  • Visual COBOL and Enterprise Developer 3.0 or later.
20
  • Visual COBOL and Enterprise Developer 5.0 or later.

Properties:

Default: | MF"20"
Phase: | Syntax check
$SET: | Initial

Dependencies:

MF"7" sets DBCS"2" immediately.

If integer > 7, sets DBCS"3" and DBSPACE immediately.

Comments:

Behavior of the BLANK LINE phrase in previous versions of this COBOL system can be implemented using the OLDBLANKLINE directive. Behavior of the NEXT SENTENCE phrase in previous versions of this COBOL system can be implemented using the OLDNEXTSENTENCE directive.

If MF"10" or lower is specified, data names are truncated to 30 characters, for compatibility with earlier versions.

MF"11" contains all reserved words that were enabled by the V3.2 and V3.3 MF-OO directive.

MF"12" contains all reserved words in MF"11" together with additional reserved words added at Mainframe Express 3.0, Net Express 4.0 and Server Express 4.0.

Parent topic: Language Features - Dialect
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List
Related reference
Reserved Words
Reserved Words Table
DIALECT
OLDBLANKLINE
OLDNEXTSENTENCE


MS

Facilitates forward compatibility with Microsoft COBOL systems by selectively enabling Microsoft-specific reserved words and changing the behavior of certain features to be compatible with particular versions.

Syntax:

>>-.---.-.-------MS--"version"-.-----------><
   +-/-+ +.----.-MS------------+
          +-NO-+

Parameters:

version
The version:
1
Microsoft COBOL Version 1.
2
Microsoft COBOL Version 2.

Properties:

Default: | NOMS
Phase: | Syntax check
$SET: | Initial

Dependencies:

MS sets DEFAULTBYTE"0" and ACCEPTREFRESH immediately.

Comments:

Specifying MS with no parameters is the same as specifying MS"2". MS"1" is identical to IBM-MS and PC1.

This directive is for compatibility with Microsoft COBOL before version 3.0. For compatibility with V3.0 and later, use:NOMS MF"integer"

The value of integer to use is shown in the description of the MF directive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


NATIONAL

Enables you to select the level of NATIONAL support.

Syntax:

>>-.---.--NATIONAL--"integer"-----------><
   +-/-+

Parameters:

Must be one of:

1
Usage NATIONAL is only supported for PIC N data items.
2
Usage NATIONAL support is extended to numeric, edited, and external floating point items. However, this support is limited to the core COBOL language; for instance, support does not extend to the Data File Tools editor.

Properties:

Default: | NATIONAL"1"
Phase: | Syntax check
$SET: | Initial

Comments:

Any signed numeric data item containing the USAGE NATIONAL clause must also be described with the SIGN IS SEPARATE clause.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


NCHAR

Enables the use of Micro Focus Double-byte Language Extension (PIC N, Japanese data-names and Japanese procedure-names).

Syntax:

>>-.---.-.-------NCHAR--"integer"-.--------><
   +-/-+ +.----.-NCHAR------------+
          +-NO-+

Parameters:

integer
The level of support required.
1
Compatibility with previous versions of Nihongo Micro Focus products
2
Enhanced PIC N support. This setting enables the DBSPACE directive.

Properties:

Default: | NONCHAR
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying NCHAR with no parameter is the same as specifying NCHAR"2".

This directive is synonymous with, and should be used in preference to, the JAPANESE directive.

The NCHAR and DBCS directives are mutually exclusive.

When a PIC X is moved to a PIC N, with NCHAR"2", a space (x"20") is expanded to one double-byte space, and so x"2020" is expanded to two double-byte spaces. With NCHAR"1", x"2020" is expanded to one double-byte space.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


NSYMBOL

Defines the default USAGE for PIC N clauses and controls the interpretation of national literals.

Syntax:

>>-.---.--NSYMBOL--"nsymbol-type"---------><
   +-/-+

Parameters:

nsymbol-type
The meaning of the N symbol. Possible values are:
DBCS
In a PIC N clause with no USAGE clause specified, the USAGE clause is DISPLAY-1, that is, the characters are DBCS characters

An N symbol prefixing a literal identifies a DBCS literal

NATIONAL
In a PIC N clause with no USAGE clause specified, the USAGE clause is NATIONAL, that is, the characters are Unicode characters

An N symbol prefixing a literal identifies a Unicode literal

Properties:

Default: | NSYMBOL"DBCS"
Phase: | Syntax check
$SET: | Yes

Dependencies:

DIALECT"ENTCOBOL" sets NSYMBOL"NATIONAL"

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


OOCTRL

Enables you to change language options when compiling OO COBOL classes and interfaces.

Syntax:

                  +--------+
                  V        |
>>-.---.--OOCTRL--.-option-.-------------><
   +-/-+

Parameters:

+
Turns on an option.
-
Turns off an option.
option
Determines how syntax in OO programs is to be treated:
A | Specifies whether to allow ActiveX controls in your COBOL application to use classes and methods in the OLE class library; set -A to allow.
F | Specifies whether or not to fold method names invoked by the program being compiled to lower case. Use -F if your program calls Java methods, since Java method names are case-sensitive. See your Java and COBOL book for information on using Java and COBOL together.
G | Specifies whether to make class data global for instances. The use of this option is not recommended. It is provided for compatibility with earlier releases.
L | Specifies whether to include directory location comments in .cls and .ins inheritance files.
P | Specifies whether to make parameter type information available to the run-time system. This is needed for messages sent to COM. The number of parameters in any method called or declared is limited to 31, plus an optional return value.
Q Specifies whether to disable the use of:
  • IN and OF any place that could possibly follow a data name in the verb-signature of a method interface definition.
  • Any verb in the verb-signature of a method interface definition.
W | Specifies whether working storage means object storage in instances and factory (class) objects.

Properties:

Default: | OOCTRL(+A+F-G+L-P+Q+W)
Phase: | Syntax check
$SET: | Any

Comments:

When working storage is used to mean object storage, an Object-Storage Section must not be specified.

The +W setting provides compatibility with the ISO 2002 COBOL standard.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


OSVS

Specifies that words reserved in IBM OS/VS COBOL are to be treated as reserved words.

Syntax:

>>-.---.-.----.--OSVS------------------------><
   +-/-+ +-NO-+

Properties:

Default: | NOOSVS
Phase: | Syntax check
$SET: | Initial

Comments:

Set to OSVS immediately by DOSVS.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Dialect
Key to Compiler Directives


PC1

Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--PC1-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPC1
Phase: | Syntax check
$SET: | Initial

Dependencies:

PC1 sets DEFAULTBYTE"0" and ACCEPTREFRESH immediately.

Comments:

This directive is synonymous with the IBM-MS and MS"1" directives.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List


RM

Specifies that words reserved in RM/COBOL are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.

Syntax:

>>-.---.-.-------RM--"parameter"-.--------------><
   +-/-+ +.----.-RM--------------+
          +-NO-+

Parameters:

ANSI
Provides behavior as if you compile your RM/COBOL programs with the ANSI switch set.
BEEP
Stops the beep from sounding when the RM"ANSI" directive is set and you use the ACCEPT statement.

Properties:

Default: | NORM
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets RM"ANSI" immediately.

RM sets COMP-6"1", DISPLAY"CRT", SEQUENTIAL"LINE", NOTRUNC, OLDINDEX, NOOPTIONAL-FILE, RETRYLOCK and ALIGN"2 FIXED" immediately.

RM also behaves as if the following syntax is set:

sign trailing separate

for signed numeric data items, and:

lock mode is automatic

for each file in the program which has no explicit locking syntax declared.

RM"ANSI" sets COMP-6"1", SEQUENTIAL"RECORD", NOTRUNC, OLDINDEX, NOOPTIONAL-FILE, RETRYLOCK and ALIGN"2 FIXED" immediately.

RM"ANSI" also behaves as if the following syntax is set:

sign trailing included

for signed numeric data items, and:

lock mode is automatic

for each file in the program which has no explicit locking syntax declared.

NORM sets COMP-6"2", SEQUENTIAL"RECORD", TRUNC"ANSI", NOOLDINDEX, OPTIONAL-FILE, NORETRYLOCK and ALIGN"8 OPT" immediately.

Comments:

For the fullest RM/COBOL behavior available, set DIALECT"RM", which also sets this directive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
COBOL Language Reference
Key to Compiler Directives


RTNCODE-TYPE

Defines the numeric type of the RETURN-CODE special register.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.—RTNCODE-TYPE--"option"--------------><
   +-/-+

Parameters:

option
Can be one of:
COMP
The return-code is of type COMP.
COMP5
The return-code is of type COMP-5.

Properties:

Default: | RTNCODE-TYPE"COMP"
Phase: | Syntax check
$SET: | Initial

Dependancies:

Set to RTNCODE-TYPE"COMP5" by DIALECT"BS2000" and DIALECT"BS2000-OFFLOAD".

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related reference
Special Registers


VSC2

Specifies that words reserved in IBM VS COBOL II are to be treated as reserved words, and enables selected features for compatibility with a given level of that COBOL system.

Syntax:

 >>-.---.-.-------VSC2--"integer"-.---------><
    +-/-+ +.----.-VSC2------------+
           +-NO-+

Parameters:

integer
The level of IBM VS COBOL II to be compatible with:
1
VS COBOL II release 1.0
2
  • VS COBOL II release 2.0
  • VS COBOL II release 3.x (when compiled with its CMPR2 directive)
  • VS COBOL II release 4.x (when compiled with its CMPR2 directive)
  • COBOL/370 V1R1 (when compiled with its CMPR2 directive)
3
VS COBOL II release 3.x (when compiled with its NOCMPR2 directive).
4
Synonymous with VS COBOL II release 4.x.

Properties:

Default: | NOVSC2
Phase: | Syntax check
$SET: | Initial

Dependencies:

If integer > 1, VSC2"integer" sets DBSPACE and DBCS"2" immediately. VSC2"3" sets ANS85 at end.

Comments:

1 VS COBOL II release 1.0 (Replaces the directives OLDVSC2 VSC2.)

No explicit scope delimiter is allowed in a statement without a conditional phrase (for example, AT END or ON SIZE ERROR).

The word ALSO in an EVALUATE statement must be omitted.

The CLASS and SYMBOLIC CHARACTERS clauses are not allowed.

Conditional phrases with NOT (for example NOT AT END, NOT ON SIZE ERROR) are not allowed.

2
  • VS COBOL II release 2.0
  • VS COBOL II release 3.x (when compiled with its CMPR2 directive)
  • VS COBOL II release 4.x (when compiled with its CMPR2 directive)
  • COBOL/370 V1R1 (when compiled with its CMPR2 directive)

The CLASS and SYMBOLIC CHARACTERS clauses are not allowed.

Conditional phrases with NOT (for example, NOT AT END, NOT ON SIZE ERROR) are not allowed.

When used with FLAG"VSC2" it provides similar functionality to VS COBOL II release 2.

3 VS COBOL II release 3.x (when compiled with its NOCMPR2 directive).

For complete compatibility in this instance, the directive REMOVE"FUNCTION" also should be specified. However, for upward compatibility, we recommend that you do not use FUNCTION as a user-defined word.

When used with FLAG"VSC2" it provides similar functionality to VS COBOL II release 3.

4 Synonymous with VS COBOL II release 4.x.

When VSC2 is specified without integer, VSC2"4" is assumed.

ANSI'85 status codes are used when VSC2"3" is selected.

Do not use the NOANS85 directive after VSC2"3"; it turns off some of the ANSI'85 behavior turned on by VSC2"3".

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Dialect
Key to Compiler Directives


XOPEN

Specifies that words reserved under the X/Open definition of COBOL are to be treated as reserved words.

Syntax:

>>-.---.-.-------XOPEN--"level"-.----------><
   +-/-+ +.----.-XOPEN----------+
          +-NO-+

Parameters:

level
The level of X/Open definition COBOL to be compatible with:
3
Compatible with X/Open Portability Guide 1988 (XPG-3)
4
Compatible with X/Open CAE Specification (XPG-4)

Properties:

Default: | NOXOPEN
Phase: | Syntax check
$SET: | Initial

Dependencies:

XOPEN sets RTNCODE-SIZE"4" immediately.

Comments:

Specifying XOPEN with no parameter is the same as specifying XOPEN"4". If you specify XOPEN"4", National Character Support is enabled using the DBCS"3" directive.

Parent topic: Language Features - Dialect
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
DBCS
RTNCODE-SIZE
Language Features - Dialect
Key to Compiler Directives


Language Features - Mainframe Compatibility

  • APOST
    Makes the Compiler interpret the figurative constant QUOTE as the single-quote character (').
  • AREACHECK
    Causes the Compiler to treat any token which starts in area A in the Procedure Division as a paragraph or section label, regardless of the preceding tokens.
  • ARITH
    Defines the maximum number of digits for numeric data items.
  • CMPR2
    Provides compatibility with the mainframe compiler option of the same name, which returns behavior of the COBOL 370, VS COBOL II version 3 and VS COBOL II version 4 compilers to that of the VS COBOL II version 2 compiler.
  • DBCSSOSI
    Defines the two characters used as the shift-out and shift-in delimiters in DBCS literals.
  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • DISPSIGN
    Determines the display output of numeric fields with included signs, under an IBM mainframe dialect only. (This directive emulates the mainframe option of the same name.)
  • DPC-IN-SUBSCRIPT
    Turns on or off DECIMAL-POINT IS COMMA when processing subscripts.
  • IDENTIFIERLEN
    Specifies the portion of an identifier name that the compiler will consider to be significant.
  • LIBRARIAN
    Allows -INC statements in your program.
  • MAPNAME
    Makes the Compiler alter program-names and entry-point names to make them compatible with OS/VS COBOL, DOS/VS COBOL, VS COBOL II and COBOL/370.
  • NUMPROC
    Provides partial compatibility with the processing of invalid data on some non-IBM mainframe COBOL platforms.
  • OLDCOPY
    Makes COPY statements follow the ANSI'68 standard.
  • PANVALET
    Allows ++INCLUDE statements in your program.
  • PROGID-COMMENT
    Allows comments following the PROGRAM-ID header in the Program-Id paragraph.
  • QUOTE
    Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").
  • RDW
    Enables you to find out the length of a record that has just been read from a variable-length sequential file.
  • TRUNCCALLNAME
    Truncates subprogram names to a specified length.
  • TRUNCCOPY
    Specifies whether to truncate the names of copybooks.
  • TRUNCINC
    Specifies whether to truncate the names of ++INCLUDE files.
Parent topic: Language Features


APOST

Makes the Compiler interpret the figurative constant QUOTE as the single-quote character (').

Syntax:

>>------APOST-----><

Parameters:

None

Properties:

Default: | APOST
Phase: | Syntax check
$SET: | Any

Comments:

The opposite of this directive is the directive QUOTE which causes the double-quote character (") to be used.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related information
QUOTE
Key to Compiler Directives


AREACHECK

Causes the Compiler to treat any token which starts in area A in the Procedure Division as a paragraph or section label, regardless of the preceding tokens.

Syntax:

>>-.---.-.----.---AREACHECK------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOAREACHECK
Phase: | Syntax check
$SET: | Any

Comments:

If AREACHECK is not specified, only tokens which follow a period are treated as possible labels. This directive provides closer compatibility with mainframe error handling, where omitting a period before the label produces a less serious message. We recommend that such erroneous source code is corrected.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Language Features - Mainframe Compatibility
Key to Compiler Directives


ARITH

Defines the maximum number of digits for numeric data items.
Note: This directive emulates the mainframe compiler option of the same name.

Syntax:

>>-.---.--ARITH--"option"---------><
   +-/-+

Parameters:

option
Can be one of:
COMPAT
Numeric items are limited to a maximum of 18 digits.
EXTEND
Numeric item limits are dialect dependent (for example: ENTCOBOL limits them to 31 digits, MF limits them to 38 digits).

Properties:

Default: | ARITH"EXTEND"
Phase: | Syntax check
$SET: | Any
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


CMPR2

Provides compatibility with the mainframe compiler option of the same name, which returns behavior of the COBOL 370, VS COBOL II version 3 and VS COBOL II version 4 compilers to that of the VS COBOL II version 2 compiler.

Syntax:

 >>-.---.-.----.--CMPR2---------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCMPR2
Phase: | Syntax check
$SET: | Initial

Dependencies:

Requires VSC2"3", VSC2"4" or COBOL370 flagging to be selected.

Comments:

Setting this directive is not the same as setting VSC2"2". It emulates the mainframe behavior quite closely, and also causes different run-time behavior in some cases. If you use the CMPR2 directive on the mainframe with one of the specified compilers, use this directive instead of VSC2"2".

The FLAGMIG directive flags the items that give different run-time behavior.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


DISPSIGN

Determines the display output of numeric fields with included signs, under an IBM mainframe dialect only. (This directive emulates the mainframe option of the same name.)

Syntax:

 >>-.---.----DISPSIGN"option"-----><
    +-/-+

Parameters:

option
Can be one of:
COMPAT
Long standing IBM mainframe behavior, in which the display output shows included signs without formatting.
SEP
Display output is always formatted with a leading separate sign.

Properties:

Default: | DISPSIGN"COMPAT"
Phase: | Syntax check
$SET: | Initial

Comments:

This directive has no effect unless using an IBM mainframe dialect.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


DPC-IN-SUBSCRIPT

Turns on or off DECIMAL-POINT IS COMMA when processing subscripts.

Syntax:

 >>-.---.-.----.--.-DPC-IN-SUBSCRIPT-.------------><
    +-/-+ +-NO-+  +--DPCINSUBSCRIPT--+

Parameters:

None

Properties:

Default: | NODPC-IN-SUBSCRIPT
Phase: | Syntax check
$SET: | Initial

Comments:

This directive only has an effect if the DECIMAL-POINT IS COMMA clause is used.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


IDENTIFIERLEN

Specifies the portion of an identifier name that the compiler will consider to be significant.

Syntax:

>>-----IDENTIFIERLEN--"integer"------><

Parameters:

integer
The number of characters or bytes of an identifier name to use as a unique identifier. Valid values are:
30
Use the first 30 characters
31
Use the first 31 characters
62
Use the first 62 bytes
128
Use the first 128 bytes

Properties:

Default: | IDENTIFIERLEN"128"
Phase: | Syntax check
$SET: | Initial

Comments:

The internal space constraints of some multi-byte character sets mean that some integers are expressed in bytes, not characters. A character is considered to be an ASCII, UTF-16, or SHIFT-JIS/EUC character. If the identifiers are UTF-8 encoded, then integer indicates number of bytes.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


LIBRARIAN

Allows -INC statements in your program.

Syntax:

>>-.---.-.---------LIBRARIAN--"integer"-.-----><
   +-/-+ +-.----.--LIBRARIAN------------+
           +-NO-+

Parameters:

integer
The level of support required.
1
-INC statements are ignored; that is, no error message is generated.
2
-INC statements are processed.

Properties:

Default: | NOLIBRARIAN
Phase: | Syntax check
$SET: | Any

Comments:

The -INC statement specifies a file for inclusion in the source program. The string -INC must be written as a contiguous sequence of upper case characters starting in column 1, followed by one or more spaces, and then, on the same line, by the name of a file containing COBOL source. This file is included in the program at the point where the -INC statement appears.

If you set NOLIBRARIAN, -INC statements are not recognized; in this case, an error message is generated.

If you set LIBRARIAN without specifying integer, LIBRARIAN"2" is set.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


MAPNAME

Makes the Compiler alter program-names and entry-point names to make them compatible with OS/VS COBOL, DOS/VS COBOL, VS COBOL II and COBOL/370.
Note: This directive is supported for native COBOL only.

Syntax:

 >>-.---.-.----.--MAPNAME-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOMAPNAME
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying MAPNAME affects program-names and entry-point names defined in the compilation and those referenced by the program as follows:

  • ENTRY statements only in the outermost program
  • CALL literal, but not CALL identifier, statements
  • PROGRAM-ID entries in the outermost program, but not in nested programs

When a name is found to be incompatible a warning message is given and a modified name is used in the object program. The rules enforced and the modifications made are:

  • The first eight characters must be unique among program-names. The name is truncated to the first eight characters.
  • The first character must be alphabetic. If it is numeric it is changed as follows:
    0       becomes    J
1 - 9   become     A - I
  • Hyphen (-) is not allowed. If one appears it is changed to zero (0).
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives


NUMPROC

Provides partial compatibility with the processing of invalid data on some non-IBM mainframe COBOL platforms. 1

Syntax:

>>-.---.-.-NUMPROC"option"----.----------------><
   +-/-+ +-NONUMPROC----------+

Parameters:

option
Can be one of:
AS400
Partial compatibility with the behavior of IBM AS/400 COBOL processing of invalid data in USAGE DISPLAY or COMP-3 data items.
ACOS
Partial compatibility with the behavior of NEC ACOS COBOL processing of invalid data in USAGE DISPLAY data items and invalid sign information in USAGE COMP-3 data items.

Properties:

Default: | NONUMPROC
Phase: | Syntax check
$SET: | Initial

Dependencies:

NUMPROC"ACOS" sets SIGN"EBCDIC" and CHECKNUM.

If NUMPROC"ACOS" is specified with any of CHARSET"EBCDIC", HOSTNUMMOVE, HOSTNUMCOMPARE, SIGNFIXUP, or SPZERO, a severe checker error is produced (COBCH1266).

Comments:

The directives HOSTNUMMOVE, HOSTNUMCOMPARE and SIGN-FIXUP should be used to configure compatibility with the processing of invalid data by IBM Mainframe COBOL.

The CHECKDIV"ACOS" directive provides further ACOS mainframe compatibility.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related reference
CHECKDIV
HOST-NUMCOMPARE
HOST-NUMMOVE
SIGN-FIXUP
1 In the context of this directive, IBM Mainframe COBOL refers to COBOL systems running on the System/360, System/370, System/390, and zSeries mainframe families.


OLDCOPY

Makes COPY statements follow the ANSI'68 standard.

Syntax:

 >>-.---.-.----.--OLDCOPY-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDCOPY
Phase: | Syntax check
$SET: | Any
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - Mainframe Compatibility
Key to Compiler Directives


PANVALET

Allows ++INCLUDE statements in your program.

Syntax:

 >>-.---.------.----PANVALET--.-------------.-.--><
    +-/-+      |              +--"integer"--+ +
               +--NOPANVALET------------------+

Parameters:

integer
Must be either:
1
++INCLUDE statements are ignored; that is, no error message is generated.
2
++INCLUDE statements are processed.

Properties:

Default: | NOPANVALET.
Phase: | Syntax check
$SET: | Any

Comments:

The ++INCLUDE statement specifies a file for inclusion in the source program. The string ++INCLUDE must be written as a contiguous sequence of upper-case characters starting in Area A or Area B, followed by one or more spaces, and then, on the same line, by the name of a file containing COBOL source. This file is included in the program at the point where the ++INCLUDE statement appears.

If you set NOPANVALET, ++INCLUDE statements are not recognized; in this case, an error message is generated.

f you set PANVALET without specifying integer, PANVALET"2" is set.

If you specify PANVALET and LIBRARIAN together, a warning message is given advising that the compiled program might not be mainframe compatible.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Language Features - Mainframe Compatibility
Key to Compiler Directives


PROGID-COMMENT

Allows comments following the PROGRAM-ID header in the Program-Id paragraph.

Syntax:

 >>-.---.-.----.--PROGID-COMMENT------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPROGID-COMMENT
Phase: | Syntax check
$SET: | Initial

Comments:

This directive is provided for compatibility with earlier versions of this COBOL system.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


QUOTE

Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").

Syntax:

>>-.---.--QUOTE----------------------------><
   +-/-+

Parameters:

None

Properties:

Default: | QUOTE
Phase: | Syntax check
$SET: | Any

Comments:

The opposite of this directive is the directive APOST which causes the single-quote character to be used.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


RDW

Enables you to find out the length of a record that has just been read from a variable-length sequential file.

Syntax:

 >>-.---.-.----.--RDW-----------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NORDW
Phase: | Syntax check
$SET: | Any

Comments:

If you specify the RDW directive, a four-byte record-length field is allocated immediately before the record area for the file. After a READ, the length (in binary) of the record just read is put in the first two bytes of this record area. The length returned includes the record-length field itself, so is four bytes longer than the actual record length.

You can access this field by defining the record area as a table, and using negative or zero subscripts

The RDW directive is intended only for mainframe compatibility; for new programs you should use the RECORD IS VARYING DEPENDING ON phrase of the FD statement.

Example:

 fd  file-1.
 01  rec-1           pic x(100).
 01  rec-2.
     03  rdw-table   pic x(4) occurs 25.
 Working-storage section.
 01  rdw-area.
     03  rec-length  pic 9(4) comp.
     03  filler      pic 9(4) comp.
 procedure division.
     ...
     read file-1
     move rdw-table (0) to rdw-area
     ...
Parent topic: Language Features - Mainframe Compatibility
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Mainframe Compatibility
Key to Compiler Directives


TRUNCCALLNAME

Truncates subprogram names to a specified length.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.------TRUNCCALLNAME--"integer"--.------><
   +-/-+ +-NO---TRUNCCALLNAME-------------+

Parameters:

integer The length to which to truncate the name

Properties:

Default: | NOTRUNCCALLNAME
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to TRUNCCALLNAME"8" by DIALECT"ANS85", DIALECT"COBOL370", DIALECT"ENTCOBOL", DIALECT"MVS", DIALECT"OS390", DIALECT"OSVS", and DIALECT"VSC21".

Comments:

This directive truncates the name of a called subprogram to integer characters. Only literal or data names are truncated.

Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


TRUNCCOPY

Specifies whether to truncate the names of copybooks.

Syntax:

 >>-.---.-.----TRUNCCOPY--"integer"-.-------><
    +-/-+ +-NO-TRUNCCOPY------------+

Parameters:

integer
The number of characters to truncate the name of the copybook to. Value between 8 and 255 inclusive.

Properties:

Default: | NOTRUNCCOPY
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Language Features - Mainframe Compatibility
Key to Compiler Directives
TRUNCINC


TRUNCINC

Specifies whether to truncate the names of ++INCLUDE files.

Syntax:

 >>-.---.-.----TRUNCINC--"integer"-.-------><
    +-/-+ +-NO-TRUNCINC------------+

Parameters:

integer The number of characters to truncate the name of the ++INCLUDE to. Value between 8 and 255 inclusive.

Properties:

Default: | TRUNCINC"10"
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


Language Features - Multi-threading

  • REENTRANT
    Controls reentrancy of a multithreading program. Any program that is to be reentrant in a multi-threaded application must be compiled with this directive. If REENTRANT is specified, many program areas are dynamically allocated, so that it is safe to have multiple copies of the program running.
  • SERIAL
    Specifies that the program is to be a serial program.
Parent topic: Language Features


REENTRANT

Controls reentrancy of a multithreading program. Any program that is to be reentrant in a multi-threaded application must be compiled with this directive. If REENTRANT is specified, many program areas are dynamically allocated, so that it is safe to have multiple copies of the program running.

Syntax:

>>-.---.-.-----REENTRANT---"n"--.-------><
   +-/-+ +-NO--REENTRANT--------+

Parameters:

n
One of:
1
All compiler-generated temporary work areas are allocated on a per thread basis. All user data and FD file areas allocated in the Environment and Data Divisions will be shared by all threads. It is the responsibility of the programmer to ensure serialization to the program's data by use of the CBL_ synchronization calls.
2
All user data and FD file areas allocated in the Environment and Data Divisions are allocated on a per thread basis. EXTERNAL data and files will always be shareable by all threads.

Properties:

Default: | NOREENTRANT
Phase: | Syntax check
$SET: | Initial

Comments:

Use REENTRANT"1" wherever possible for any program you wish to be reentrant. Use REENTRANT"2" only as the first step towards converting an existing program to be reentrant.

Note:
  • The Compiler rejects the REENTRANT directive if you use it with programs that use:
    • ALTER statements
    • Debug facility (SOURCE-COMPUTER... WITH DEBUGGING)
    • ON statements
    • Segmentation
    • Any of the following directives:
      • PROTECT-LINKAGE
      • STICKY-LINKAGE
      • STICKY-PERFORM
  • If you are using the PROGRAM-ID. … IS INITIAL statement, you cannot use REENTRANT”1”, and can only use REENTRANT “2” if the program does not contain nested programs.
  • Do not use the REENTRANT directive in a ThreadPool environment such as that used by ASP.NET. You must use the multiple run units model instead.
Parent topic: Language Features - Multi-threading
Parent topic: Compiler Directives - Alphabetical List
Related information
SERIAL
Language Features - Multi-threading
Key to Compiler Directives


SERIAL

Specifies that the program is to be a serial program.

Syntax:

>>-.---.-.----.--SERIAL-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSERIAL
Phase: | Syntax check
$SET: | Initial

Comments:

If you specify this directive the run-time system determines whether the program is active in a thread and prevents any other thread entering the active program. This directive should be used on the first COBOL program to be executed on any given thread.

Note that the code to determine this takes time and is called on every program entry. Programs should be compiled with this directive only if they are going to run in a multi-threaded environment.

Parent topic: Language Features - Multi-threading
Parent topic: Compiler Directives - Alphabetical List


Language Features - Reserved Word Control

  • ADDRSV
    Adds one or more specific reserved words to the reserved word list so that they are recognized as reserved words in your program. The specified reserved words are added, whatever dialect directives are in force.
  • ADDSYN
    Defines a user-defined reserved word to be synonymous with an existing reserved word.
  • COBOL370
    Specifies that words reserved in IBM COBOL/370 are to be treated as reserved words, and allows features selectively for compatibility with a given level of that product.
  • DOSVS
    Specifies that words reserved in IBM DOS/VS COBOL are to be treated as reserved words.
  • MAKESYN
    Makes one reserved word synonymous with another.
  • MVS
    Specifies that words reserved in IBM COBOL for MVS are to be treated as reserved words.
  • OS390
    Specifies that words reserved in IBM COBOL for OS/390 R2V2 are to be treated as reserved words.
  • OVERRIDE
    Replaces a reserved word by a new one.
  • REMOVE
    Removes words from the reserved word list, so that they can be used as user-defined words.
  • SAA
    Specifies that words reserved under the Systems Application Architecture (SAA) definition of COBOL are to be treated as reserved words.
Parent topic: Language Features


ADDRSV

Adds one or more specific reserved words to the reserved word list so that they are recognized as reserved words in your program. The specified reserved words are added, whatever dialect directives are in force.

Syntax:

                   +------------+
                   V            |
>>--.---.--ADDRSV--.-"rsv-word"-.-----><
    +-/-+

Parameters:

rsv-word A reserved word in some dialects of COBOL, but not necessarily in a dialect specified for this compilation

Properties:

Default: | No additional reserved words are created.
Phase: | Syntax check
$SET: | Initial

Comments:

The specified reserved words are added, whatever dialect directives are in force.

This directive does not appear in the list created with the SETTING directive.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List


ADDSYN

Defines a user-defined reserved word to be synonymous with an existing reserved word.

Syntax:

>>-.---.--ADDSYN--"rsv-word" = "user-word"-><
   +-/-+

Parameters:

rsv-word
Existing reserved word.
user-word
Any COBOL word not the same as an existing reserved word.

Properties:

Default: | No reserved word synonyms are created.
Phase: | Syntax check
$SET: | Initial

Comments:

This directive does not appear in the list created with the SETTING directive.

The equals sign must be surrounded by spaces.

You can also leave a space between the directive and its option to improve readability. If you are specifying this directive to the -C option of the Cob command line, you need to ensure that all characters are escaped correctly for the UNIX shell. For example, to specify ADDSYN on the command line:

cob -C 'addsyn "low" == "lowlight"' a.cbl
Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List


COBOL370

Specifies that words reserved in IBM COBOL/370 are to be treated as reserved words, and allows features selectively for compatibility with a given level of that product.

Syntax:

 >>-.---.-.-------COBOL370--"integer"-.-----><
    +-/-+ ++----+-COBOL370------------+
           +-NO-+

Parameters:

integer
The level of IBM COBOL/370 to be compatible with:
1
Specifies compatibility with Version 1 Release 1 of IBM COBOL/370
2
Specifies compatibility with Version 1 Release 2 of IBM COBOL for MVS and VM

Properties:

Default: | NOCOBOL370
Phase: | Syntax check
$SET: | Initial

Dependencies:

COBOL370 sets DBSPACE and DBCS"3" immediately.

Comments:

Specifying COBOL370 without a parameter is the same as specifying COBOL370"2".

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List
Related information
Language Features - Dialect
Key to Compiler Directives


DOSVS

Specifies that words reserved in IBM DOS/VS COBOL are to be treated as reserved words.

Syntax:

 >>-.---.-.----.--DOSVS----------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NODOSVS
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to NODOSVS immediately by OSVS.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List
Related information
DOSVS DIALECT setting
DIALECT
Language Features - Dialect
Key to Compiler Directives


MAKESYN

Makes one reserved word synonymous with another.

Syntax:

>>-.---.-MAKESYN-"rsv-word-1" = "rsv-word-2"---><
   +-/-+

Parameters:

rsv-word-1
A reserved word.
rsv-word-2
The reserved word whose meaning is to be changed.

Properties:

Default: | No reserved word synonyms are created
Phase: | Syntax check
$SET: | Initial

Comments:

The equals sign must be surrounded by spaces.

You can also leave a space between the directive and its option to improve readability. If you are specifying this directive to the -C option of the Cob command line, you need to ensure that all characters are escaped correctly for the UNIX shell. For example, to specify MAKESYN on the command line:
cob demo.cbl -C 'makesyn  "comp-5"  ==  "comp"  '

This directive does not appear in the list created with the SETTING directive.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List


MVS

Specifies that words reserved in IBM COBOL for MVS are to be treated as reserved words.

Syntax:

 >>-.---.-.----.--MVS-----><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOMVS
Phase: | Syntax check
$SET: | Initial

Dependencies:

MVS sets DBSPACE and DBCS"3" immediately.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Dialect
Key to Compiler Directives


OS390

Specifies that words reserved in IBM COBOL for OS/390 R2V2 are to be treated as reserved words.

Syntax:

 >>-.---.-.----.--OS390----><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOS390
Phase: | Syntax check
$SET: | Initial

Dependencies:

OS390 sets DBSPACE and DBCS"3" immediately.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Dialect
Key to Compiler Directives


OVERRIDE

Replaces a reserved word by a new one.

Syntax:

                  +--------------------------+
                  V                          |
>>-.---.-OVERRIDE-.-"rsv-word" = "user-word"-.--><
   +-/-+

Parameters:

rsv-word
Existing reserved word.
user-word
Any COBOL word not the same as an existing reserved word.

Properties:

Default: | No change of reserved words takes place.
Phase: | Syntax check
$SET: | Initial

Comments:

This directive equates an existing reserved word to the specified user-defined word, so that, in the program, user-word is treated as a reserved word, and rsv-word can be used as a user-defined word.

The equals signs must be surrounded by spaces. If the parameters are repeated they must be separated by spaces. You can also leave a space between the directive and its option to improve readability. If you are specifying this directive to the -C option of the Cob command line, you need to ensure that all characters are escaped correctly for the UNIX shell.

This directive does not appear in the list created with the SETTING directive.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List


REMOVE

Removes words from the reserved word list, so that they can be used as user-defined words.

Syntax:

                 +----------------+
                 V                |
>>-.---.--REMOVE-.-"reserved-word".--------------><
   +-/-+

Properties:

Default: | No reserved words are removed.
Phase: | Syntax check
$SET: | Initial

Comments:

This directive does not appear in the list created with the SETTING directive.

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List
Related reference
Reserved Words


SAA

Specifies that words reserved under the Systems Application Architecture (SAA) definition of COBOL are to be treated as reserved words.

Syntax:

 >>-.---.-.-------SAA--"level"-.------------><
    +-/-+ +.----.-SAA----------+
           +-NO-+

Parameters:

level
Must be one of:
1
SAA level 1 supported
2
SAA level 2 supported

Properties:

Default: | NOSAA
Phase: | Syntax check
$SET: | Any

Dependencies:

SAA sets DBSPACE and DBCS"2" immediately.

SAA"2" sets ANS85 at end.

Comments:

Specifying SAA with no parameters is the same as specifying SAA"2".

Parent topic: Language Features - Reserved Word Control
Parent topic: Compiler Directives - Alphabetical List


Language Features - Speed

  • ALTER
    Allows ALTER statements in your program.
  • FASTCALL
    Controls the behavior of a called program. If FASTCALL is specified, the program does not set up information to allow it to determine whether it is a main program. The program always assumes that it is not a main program, and EXIT PROGRAM will always cause an exit to the calling program.
  • FASTLINK
    Tells the Compiler that the parameters in the USING clauses of the Procedure Division statement and each ENTRY statement conform to certain restrictions. This enables it to produce faster code.
  • FIXOPT
    Changes the way in which generated code accesses the Data Division in object (.obj) code.
  • QUAL
    Allows qualified data-names and procedure-names in your program.
  • QUALPROC
    Allows qualified procedure-names in your program.
  • SEG
    Turns on COBOL segmentation.
Parent topic: Language Features


ALTER

Allows ALTER statements in your program.

Syntax:

>>-.---.-.----.--ALTER---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | ALTER
Phase: | Both
$SET: | Initial

Comments:

If you know there are no ALTER statements in your program, specifying NOALTER enables the Compiler to produce slightly more efficient code.

Parent topic: Language Features - Speed
Parent topic: Compiler Directives - Alphabetical List


FASTCALL

Controls the behavior of a called program. If FASTCALL is specified, the program does not set up information to allow it to determine whether it is a main program. The program always assumes that it is not a main program, and EXIT PROGRAM will always cause an exit to the calling program.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--FASTCALL------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFASTCALL
Phase: | Generator
$SET: | Initial

Comments:

Programs compiled with FASTCALL do not set up the information that allows further called programs to determine whether they are main programs. Thus, any program called by a program compiled with FASTCALL should itself be compiled with FASTCALL.

Parent topic: Language Features - Speed
Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List


FASTLINK

Tells the Compiler that the parameters in the USING clauses of the Procedure Division statement and each ENTRY statement conform to certain restrictions. This enables it to produce faster code.
Restriction:

This directive is supported in native COBOL only.

This directive can be used with 32-bit x86 platforms only.

Syntax:

>>-.---.-.----.--FASTLINK------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFASTLINK
Phase: | Generate
$SET: | Initial

Comments:

  • The parameters must be in the same order on every entry point. This order does not have to be the same order as the order in which they appear as 01-level items in the Linkage Section.
  • The program must be compiled with the NOFIXOPT and NOTYPECHECK Compiler directives
Parent topic: Language Features - Speed
Parent topic: Compiler Directives - Alphabetical List
Related information
Language Features - Speed
FIXOPT
Screen Section Entry Skeleton
The USING Clause
Procedure Division General Description
The PROCEDURE DIVISION Header
The CALL Statement
The CHAIN Statement
The ENTRY Statement
The INVOKE Statement
The MERGE Statement
The SORT Statement
The START Statement
The Class-ID Paragraph
The Interface-ID Paragraph
The SET Statement
ENTRY Statement Restrictions


FIXOPT

Changes the way in which generated code accesses the Data Division in object (.obj) code.
Restriction:

This directive is supported for native COBOL only.

This directive is supported for 32-bit x86 platforms only.

Syntax:

>>-.---.-.----.--FIXOPT-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFIXOPT
Phase: | Generate
$SET: | Initial

Comments:

FIXOPT is supported only on Intel x86 processors.

If you receive code generation error 78 ("Too many code relocations (limit=limit, actual=actual-relocations)") when creating object code, you must recompile specifying FIXOPT.

Parent topic: Language Features - Speed
Parent topic: Object Code - Size and Speed
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


QUAL

Allows qualified data-names and procedure-names in your program.

Syntax:

>>-.---.-.----.--QUAL----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | QUAL
Phase: | Syntax check
$SET: | Any

Comments:

If you have no qualified data-names or procedure-names in your source code, you can specify NOQUAL. This improves compilation speed.

Parent topic: Language Features - Speed
Parent topic: Compiler Directives - Alphabetical List


QUALPROC

Allows qualified procedure-names in your program.

Syntax:

>>-.---.-.----.--QUALPROC------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | QUALPROC
Phase: | Syntax check
$SET: | Any

Comments:

If you have no qualified procedure-names in your source code, you can specify NOQUALPROC. This improves compilation speed. If you have qualified data-names but no qualified procedure-names, you should specify QUAL and NOQUALPROC.

Parent topic: Language Features - Speed
Parent topic: Compiler Directives - Alphabetical List


SEG

Turns on COBOL segmentation.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--SEG-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | SEG
Phase: | Syntax check
$SET: | Initial

Comments:

With NOSEG, the Compiler treats all section numbers in the code as if they were zero. This means that the Compiler ignores segmentation and creates one program with no overlays.

Parent topic: Language Features - Speed
Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List
Related information
Object Code - Size and Speed
Language Features - Speed
Key to Compiler Directives


Language Features - Additional Features

  • CONSTANT
    Declares a constant for use in the program.
  • DB2
    Causes EXEC SQL statements in your program to be replaced with DB2 LUW API calls.
  • FCDREG
    Makes the Compiler define special registers giving access to File Control Descriptions (FCD) and Key Definition Blocks.
  • PREPROCESS, P
    Makes the Compiler take the source program from a preprocessor instead of a source file.
  • REWRITE-LS
    Allows REWRITE statements on line sequential files.
  • SEQCHK
    Makes the Compiler check the sequence numbers in columns 1 through 6 and identify source lines that are out of sequence.
  • SOURCEFORMAT
    Sets the layout format for your COBOL source.
  • LOCALSOURCEFORMAT
    Specifies that any setting of the SOURCEFORMAT directive in a source file is maintained for that file. This means that if a file with a different SOURCEFORMAT setting is copied into the source file, when processing exits the copied code, the SOURCEFORMAT setting returns to that originally specified in the source file.
  • SQL
    Causes EXEC SQL statements in your program to be replaced by ODBC run-time calls, depending on the options you specify.
  • XMLPARSE
    Determines the behavior of the XML PARSE statement and special registers relating to XML events.
Parent topic: Language Features


CONSTANT

Declares a constant for use in the program.

Syntax:

>>-.---.-CONSTANT-const-name-.-(numeric-lit)--.-><
   +-/-+                     +-"alphanum-lit"-+

Parameters:

const-name | Data-name. The constant's name.
numeric-lit | Numeric literal. The constant's value. Must be zero or a positive integer.
alphanum-lit | Alphanumeric literal. The constant's value.

Properties:

Default: | Not set
Phase: | Syntax check
$SET: | Any

Comments:

The effect is as if the constant const-name had been defined in the program in a level-78. Its value is that given in the parentheses or quotation marks. If parentheses are used, the constant is of category numeric; if quotation marks are used it is of category alphanumeric. It is permissible to enclose the const-name and numeric-lit or alphanum-lit pairing in parentheses.

To declare several figurative constants using this feature, use the CONSTANT directive repeatedly.

Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List


DB2

Causes EXEC SQL statements in your program to be replaced with DB2 LUW API calls.
Note: This directive is supported for native COBOL only.

Syntax:

 >>-.---.-.----DB2-.----------------------.-.--><
    +-/-+ |        |   +-----.---.-----.  | |
          |        |   |     +-,-+     |  | |
          |        |   v               |  | |
          |        +-(.-option=setting-.)-+ |
          |           |                |    |
          |           +-NO-option------+    |
          +-NO-DB2--------------------------+

Parameters:

option | One of the DB2 options.
setting | The setting for the option

Comment:

To avoid a compiler error with the DB2 directive you must have DB2 LUW Data Server Client installed.

Properties:

Default: | NODB2
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
DB2 Compiler Directive Options
Language Features - Additional Features
Key to Compiler Directives


FCDREG

Makes the Compiler define special registers giving access to File Control Descriptions (FCD) and Key Definition Blocks.

Syntax:

>>-.---.-.----.--FCDREG--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFCDREG
Phase: | Syntax check
$SET: | Initial

Comments:

FCDREG causes a special register, FH--FCD, to be created for each File Definition (FD) in the program. This register points to the File Control Description (FCD) for the file. Thus the program can read or change information in the FCD.

For each indexed file, an additional special register, FH--KEYDEF, is created. This register points to the Key Definitions Block for the file.

Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
File Description Entry Skeleton
The File Control Entry
The I-O-Control Paragraph
The DELETE FILE Statement
The USE Statement
XML Syntax - SELECT Clause


PREPROCESS, P

Makes the Compiler take the source program from a preprocessor instead of a source file.

Syntax:

>>-.---.-.----.-PREPROCESS-.-"name".----------------..------..><
   +-/-+ |    +-P----------+       +-preproc-params-++-ENDP-+|
         +-NO-.-PREPROCESS-.---------------------------------+
              +-P----------+

Parameters:

name
The preprocessor to use.
preproc-params
Parameters to be passed directly to the preprocessor.

Properties:

Default: | NOPREPROCESS
Phase: | Syntax check
$SET: | On very first source line only
 | No (with NOPREPROCESS)

Comments:

This directive informs the Compiler that an integrated preprocessor is to be used.

A $SET statement is processed by both the Compiler and the preprocessor. Furthermore, if the PREPROCESS directive is set in a $SET statement, the directive only takes effect after the entire $SET statement has been processed. If the $SET statement contains other directives there might be incompatibilities when the preprocessor parses the source a second time. In particular, the SOURCEFORMAT directive might cause the Compiler to interpret the source as fixed format while the preprocessor might view it as free format, or vice-versa. If you specify the PREPROCESS Compiler directive in a $SET statement, you should, therefore, ensure that the $SET statement only contains the PREPROCESS directive. If you want to set other directives, use separate $SET statements on following lines.

You are advised to use the ENDP COBOL directive to terminate the directives to pass to the preprocessor. Directives placed after ENDP pass to the COBOL Compiler. Therefore, without the ENDP directive, Compiler directives might continue to pass to the preprocessor rather than to the COBOL compiler.

If you are sending directives to the COBSQL preprocessor, use END-C to distinguish the directives to pass to COBSQL and the directives to pass to the precompiler. For example, in the command line below directives placed before END-C pass to COBSQL while directives placed between END-C and ENDP pass via COBSQL to the precompiler:

preprocess(cobsql) cobsqltype=oracle end-c comp5=yes endp;
Parent topic: Language Features - Additional Features
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List
Related information
Compiler Control - Compile/Link Files
Language Features - Additional Features
Key to Compiler Directives


REWRITE-LS

Allows REWRITE statements on line sequential files.

Syntax:

>>-.---.-.----.--REWRITE-LS----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | REWRITE-LS
Phase: | Syntax check
$SET: | No

Comments:

You must make sure that the record you write is the same size as the one it replaces.

Parent topic: Language Features - Additional Features
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


SEQCHK

Makes the Compiler check the sequence numbers in columns 1 through 6 and identify source lines that are out of sequence.

Syntax:

>>-.---.-.----.--SEQCHK--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSEQCHK
Phase: | Syntax check
$SET: | Any

Dependencies:

SEQCHK sets NORESEQ immediately.

Set to NOSEQCHK at end by SOURCEFORMAT"FREE".

Parent topic: Language Features - Additional Features
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


SOURCEFORMAT

Sets the layout format for your COBOL source.

Syntax:

>>-.---.--SOURCEFORMAT--"format-type"------><
   +-/-+

Parameters:

format-type
The format of COBOL source. One of:
  • FIXED
  • FREE
  • VARIABLE
  • TERMINAL

Properties:

Default: | SOURCEFORMAT"VARIABLE" for managed code and SOURCEFORMAT"FIXED" for native code and from the command line
Phase: | Syntax check
$SET: | Any

Dependencies:

SOURCEFORMAT"FREE" sets NOMFCOMMENT, NORESEQ and NOSEQCHK at end.

SOURCEFORMAT"FIXED" is set by DIALECT"ENTCOBOL".

Comments:

Generically, the COBSQL preprocessor supports SOURCEFORMAT"FIXED" only.

For Pro*COBOL applications, COBSQL also supports SOURCEFORMAT"TERMINAL" and SOURCEFORMAT"VARIABLE".

Comments:

Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related concepts
COBSQL
Setting the COBSQL Preprocessor and Compiler Directive Options
Related reference
Source Format
Source Formats (ACU)
Related information
DIALECT
MFCOMMENT
RESEQ
SEQCHK
Key to Compiler Directives


LOCALSOURCEFORMAT

Specifies that any setting of the SOURCEFORMAT directive in a source file is maintained for that file. This means that if a file with a different SOURCEFORMAT setting is copied into the source file, when processing exits the copied code, the SOURCEFORMAT setting returns to that originally specified in the source file.

Syntax:

>>-.---.-.----.--LOCALSOURCEFORMAT-------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOLOCALSOURCEFORMAT
Phase: | Check
$SET: | Any
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
SOURCEFORMAT


SQL

Causes EXEC SQL statements in your program to be replaced by ODBC run-time calls, depending on the options you specify.

Syntax:

>>-.---.-.----SQL-.----------------------.-.><
   +-/-+ |        |   +-----.---.-----+  | |
         |        |   |     +-,-+     |  | |
         |        |   V               |  | |
         |        +-(.-option=setting-.)-+ |
         |           |                |    |
         |           +-NO-option------+    |
         +-NO-SQL--------------------------+

Parameters:

option
One of the SQL options listed in the topic SQL Compiler Directive Options
setting
The setting for the option

Properties:

Default: | NOSQL
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related reference
Embedded SQL Statements
Related information
Language Features - Additional Features
Key to Compiler Directives


XMLPARSE

Determines the behavior of the XML PARSE statement and special registers relating to XML events.

Syntax:

>>-.---.----XMLPARSE--"version"---><
   +-/-+

Parameters:

version
The version of Enterprise COBOL that the XML PARSE statement emulates.
COMPAT
The operational behaviors and results of XML PARSE statements are compatible with those of Version 3 of Enterprise COBOL.
XMLSS
XML PARSE statements are processed as for Enterprise COBOL version 4. The following XML parsing capabilities are available only when this option is in effect:
  • Enhanced namespace processing
  • ENCODING and RETURNING NATIONAL phrases of the XML PARSE statement
  • Support for the VALIDATING phrase to enable checking against an XML schema in text format.

Properties:

Default: | XMLPARSE"XMLSS"
Phase: | Syntax Check
$SET: | Initial

Comments:

When XMLPARSE"COMPAT" is set and when running under native COBOL, XML character entities, for example &apos;, are output as individual events. Using <elem attr="baker&apos;s dozen"/> as an example, generates the following three elements:

  • CONTENT_CHARACTERS(with text "baker")
  • CONTENT_CHARACTERS(with text " ' ")
  • CONTENT_CHARACTERS(with text "dozen")

When XMLPARSE"XMLSS" is set or when running under managed COBOL, XML entities are converted to the single character in which they represent and included in the general text that surrounds them, generating a single event :

  • CONTENT_CHARACTERS(with text "baker's dozen")
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List


Compiler Control

  • Compiler Control - Compile/Link Files
  • Compiler Control - Directives Control
  • Compiler Control - Error and Flag Messages
  • Compiler Control - Listing
  • Compiler Control - Screen
Parent topic: Compiler Directives


Compiler Control - Compile/Link Files

  • CANCELLBR
    Makes the Compiler close an .lbr file used as a library in a COPY statement once that copy operation is complete.
  • CONVSPACE
    Converts double-byte space characters in COBOL source files to single-byte spaces on input.
  • COPYEXT
    Specifies the filename extension of the copybook that the Compiler is to look for if a filename in a COPY statement is specified without an extension.
  • COPYLBR
    Makes the Compiler treat the library specified in a COPY statement as an .lbr file.
  • COPYPATH
    Specifies a list of directories for the Compiler to search for copy files.
  • DATA-CONTEXT
    Enables you to specify how a program's Data Division is to be maintained between CICS link levels.
  • EOF-1A
    Treats a 0x1a character in the source file as the end of file.
  • GNTLITLINKSTD
    In an Intel x86 32-bit environment, a CALL statement from a .gnt file that has both call-convention 2 and call-convention 8 in effect, suppresses call-convention 8 by default. Set this directive to prevent the suppression.
  • IDYSRCPATH (deprecated)
    Controls the paths stored in .idy files for main source files.
  • IGNOREEXEC
    Specifies that procedural EXEC statements are to be treated as documentary only.
  • INT
    Specifies the name of the intermediate code file.
  • INTLEVEL
    When intermediate code is being created by the Compiler, this directive controls the level of portability of the code created to different versions of Micro Focus COBOL systems in other environments.
  • JVMGEN
    Generates Java bytecode.
  • KEYCHECK
    Specifies whether the File Handler checks that all the keys belonging to the indexed file you are opening are defined in your application.
  • NULL-ESCAPE
    Treats a 0x00 character in the source file as an escape character for other non-printable characters in the source code.
  • OBJ
    Specifies the name and format of the object code file and generated code file.
  • OSEXT
    Tells the Compiler what extension to expect by default on the names of source files.
  • P64
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • PREPROCESS, P
    Makes the Compiler take the source program from a preprocessor instead of a source file.
  • PROGID-INT-NAME
    Causes the name of the intermediate code file to be taken from the PROGRAM-ID clause, rather than the name of the source file.
  • PROTOTYPE
    Enables relaxed or strict checking of call prototypes for COMP, BINARY, COMP-4, COMP-5 and COMP-X data items when used in the BY VALUE or RETURNING clauses of a CALL statement. It also inhibits or enables the implicit copying of parameter types from the prototype.
  • RDFPATH
    Specifies a location for a repository file.
  • REPOSITORY
    Creates a repository file or requests that the program being compiled is checked against the repository file.
  • SOURCETABSTOP
    Sets the tab stop boundary in effect. When the Tab key is pressed, the cursor advances n spaces to position itself on the next specified tab position.
  • UNICODE
    Specifies the encoding to be used for Unicode characters.
Parent topic: Compiler Control


CANCELLBR

Makes the Compiler close an .lbr file used as a library in a COPY statement once that copy operation is complete.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Syntax:

>>-.---.-.----.--CANCELLBR-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | CANCELLBR
Phase: | Syntax check
$SET: | Any

Comments:

NOCANCELLBR causes such .lbr files to be left open until the end of the compilation. Subsequent COPY statements that do not specify a library, search for the copybook in all open .lbr libraries (last one opened is searched first) before the current directory.

This directive is only relevant if COPYLBR is on.

[NO]CANCELLBR can be used on any $SET statement. Only .lbr libraries referenced in COPY statements after the $SET statement are affected. Any left open from previous COPY statements are only closed if specified again on a COPY statement following a CANCELLBR directive.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


CONVSPACE

Converts double-byte space characters in COBOL source files to single-byte spaces on input.

Syntax:

>>-.---.-.----.--CONVSPACE-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | CONVSPACE
Phase: | Syntax check
$SET: | Initial

Comments:

CONVSPACE only has an effect when the DBSPACE Compiler directive is off.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


COPYEXT

Specifies the filename extension of the copybook that the Compiler is to look for if a filename in a COPY statement is specified without an extension.

Syntax:

                             +-----------------+
                             V                 |
>>-.---.--COPYEXT-"extension-.-.-------------.-.--"--><
   +-/-+                       +-,-extension-+

Parameters:

extension A filename extension.

Properties:

Default: | COPYEXT",cbl,cpy"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets COPYEXT",cbl,CBL" immediately.

Comments:

Up to 25 extensions can be specified, each extension being up to 10 characters long. A null extension is used to represent an extension of spaces; for example:

COPYEXT"src,,txt"
COPYEXT"cpy,cbl,cob,abc,"

If the filename specified in a COPY statement has no extension or trailing period, the list of possible extensions is tried in turn until a file is successfully found or the list is exhausted (and an error reported).

If you have many COPY statements that do not specify an extension, using COPYEXT can improve the compilation speed of your program. For example, if all of your copybooks have the filename extension .cpy, specifying COPYEXT"CPY,CBL" would avoid unnecessary file access attempts.

If you are running programs migrated from the mainframe, make sure that you set COPYEXT to find upper-case extensions as well as lower-case.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


COPYLBR

Makes the Compiler treat the library specified in a COPY statement as an .lbr file.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Syntax:

>>-.---.-.----.--COPYLBR-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCOPYLBR
Phase: | Syntax check
$SET: | No

Comments:

With NOCOPYLBR, the Compiler assumes that the library is a path-name.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Compiler Control - Compile/Link Files
The COPY Statement
Key to Compiler Directives


COPYPATH

Specifies a list of directories for the Compiler to search for copy files.

Syntax:

>>----.--COPYPATH---"list-of-directories"--.--><
      +-----NOCOPYPATH---------------------+

Parameters:

list-of-directories The directories to search. Use semicolons to separate the directories. Use quotes to surround the path if it contains spaces.

Properties:

Default: | COPYPATH($COBCPY), which means use the COBCPY environment variable to search for copy files
IDE equivalent: |
Phase | Syntax check
$SET | None

Comments:

You should only use the COPYPATH directive when compiling using the cob command line utility, and not when building programs from within the IDE.

When you use this directive, the Compiler does not search the COBCPY environment variable. Note that some of your COBOL development system's components rely on COBCPY being set to find copy files.

You cannot specify environment variables as a parameter for this directive.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


DATA-CONTEXT

Enables you to specify how a program's Data Division is to be maintained between CICS link levels.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.---------DATA-CONTEXT------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NODATA-CONTEXT
Phase: | Syntax check
$SET: | Any

Comments:

If a program is compiled with DATA-CONTEXT and is invoked in link level 1 then invoked again in link level 2, its Data Division contents in link level 2 will be in an initial state. On return to link level 1, the program's Data Division contents will be the same as they were before link level 2 was invoked.

If a program is compiled with NODATA-CONTEXT and is invoked in link level 1 then invoked again in link level 2, its Data Division contents in link level 2 will be whatever the link level 1 invocation had set them to. On return to link level 1, the program's Data Division contents will be in whatever state link level 2 had left them.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


EOF-1A

Treats a 0x1a character in the source file as the end of file.

Syntax:

>>-.---.-.----.—EOF-1A---><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOEOF-1A
Phase: | Syntax check
$SET: | Any

Comments:

Use NOEOF-1A if you embed 0x1A characters in literals in your source code. Alternatively, use the x"1A" literal format to represent 0x1A characters in your literals.

Using x'1A' is a historical method of indicating an end of file on old PC operating systems.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


GNTLITLINKSTD

In an Intel x86 32-bit environment, a CALL statement from a .gnt file that has both call-convention 2 and call-convention 8 in effect, suppresses call-convention 8 by default. Set this directive to prevent the suppression.
Restriction: This directive is only supported for Intel x86 32-bit, and only has any effect on .gnt files.

Syntax:

>>-.---.-.----.--GNTLITLINKSTD---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOGNTLITLINKSTD
Phase: | Generate
$SET: | Initial
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


IDYSRCPATH (deprecated)

Controls the paths stored in .idy files for main source files.

Syntax:

>>-.---.-.----IDYSRCPATH-(-.----------.-)---.-.><
   +-/-+ |                 +-src-path-+       |
         |                                    |
         +----NOIDYSRCPATH--------------------+

Parameters:

src-path The path to insert into .idy files to override the actual paths of main source files.

Properties:

Default: | NOIDYSRCPATH
Phase: | Syntax check
$SET: | No

Comments:

NOIDYSRCPATH causes the names of main source files to be stored in .idy files with their actual paths.

IDYSRCPATH(src-path) causes the names of main source files to be stored in .idy files with their actual paths replaced by src-path.

IDYSRCPATH() causes the names of main source files to be stored in .idy files with no paths.

Changing the main source file paths stored in .idy files enables you to compile files on one machine then move them to another machine and still have the debugger find all the files it needs. To do this you would also need to set the COBIDY, GNT and INT directives.

Note: IDYSRCPATH only affects the paths used for main source files; it does not affect the paths used for copy books.
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


IGNOREEXEC

Specifies that procedural EXEC statements are to be treated as documentary only.

Syntax:

>>-.---.-.----.--IGNOREEXEC------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOIGNOREEXEC
Phase: | Check
$SET: | Any
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


INT

Specifies the name of the intermediate code file.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Syntax:

>>-.---.-.-----INT-.-"path-name\filename"--.-.--><
   +-/-+ |         +-"path-name/filename"--+ |
         |         +-"path-name\"----------+ |
         |         +-"path-name/"----------+ |
         |         +-"filename"------------+ |
         |         +-()--------------------+ |
         +-NO--INT---------------------------+

Parameters:

path-name | Path or environment variable specifying the path.
filename | A full file specification.

Properties:

Default: | NOINT for managed code and INT"source-name.int" for native code.
Phase: | Syntax check
$SET: | No

Dependencies:

NOINT sets NOANIM immediately.

Comments:

When the INT() directive is implied because it is set by default, its behavior is to produce a temporary intermediate code file during the . This file is deleted when an .obj or .gnt file is successfully created. If you want to keep the .int file after the Compiler has produced the .obj or .gnt file, you need to explicitly set the INT() directive, and not rely on its being set by default.

Specifying NOINT prevents the intermediate code file being produced.

If you specify an existing file, it is overwritten.

If filename is not specified, the Compiler uses source-name.int, where source-name is the basename of the source filename. If you specify path-name but no filename, the Compiler uses the path-name, with the filename source-name.int attached.

INT() causes intermediate code to be put in the standard file source-name.int. With this format you must use parentheses not quotation marks. So, INT"" does not give this result.

Use the INT directive with caution. Incorrect use can abort the compilation process.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


INTLEVEL

When intermediate code is being created by the Compiler, this directive controls the level of portability of the code created to different versions of Micro Focus COBOL systems in other environments.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


JVMGEN

Generates Java bytecode.

Syntax:

>>-.--JVMGEN-.-----.--.---><
   |         +-SUB-+  |
   +----NOJVMGEN------+

Parameters:

SUB
Indicates that a library is being compiled which doesn't require a main program entry point

Properties:

Default: | NOJVMGEN
IDE equivalent: | None. This directive is always used from the IDE.

Comments:

Instructs the compiler to generate Java bytecode. If a program doesn't require a main program entry point, use the SUB parameter.

This directive is not allowed in the $SET statement. You must specify JVMGEN on the command line.

If a .cbldat file is also generated during compilation, it must be deployed with the application or located on the classpath.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List
Related concepts
Compiling JDBC Applications from the Command Line


KEYCHECK

Specifies whether the File Handler checks that all the keys belonging to the indexed file you are opening are defined in your application.

Syntax:

>>-.---.-.----.--KEYCHECK-------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | KEYCHECK
Phase: | Syntax check
$SET: | Any

Comments:

If you specify KEYCHECK, all key definitions must be specified and must match, otherwise a 3/9 error is returned. If you specify NOKEYCHECK, the File Handler opens the file without any checks on key definitions. If the file is opened with NOKEYCHECK set, and if one or more of the keys does not match, then any I/O operation that explicitly references a non-matching key (for example, a READ or START with the KEY phrase) will result in a 3/9 error.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


NULL-ESCAPE

Treats a 0x00 character in the source file as an escape character for other non-printable characters in the source code.

Syntax:

>>-.---.-.----.—NULL-ESCAPE---><
   +-/-+ +-NO-+

Parameters:

None.

Properties

Default: | NULL-ESCAPE
Phase: | Syntax check
$SET: | Any

Comments:

Some systems allowed you to embed control characters in the source as if they were escaped by a null character. Use NONULL-ESCAPE if you embed single 0x00 characters in literals in your source code. This replaces the previous option of COBSW=-N.

Alternatively, use x"00" syntax to represent null characters in your literals or z" literal syntax to end a literal in a null character.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


OBJ

Specifies the name and format of the object code file and generated code file.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.-----OBJ-.-------------..--------><
   +-/-+ |         +-"filename"--+|
         +-NO--OBJ----------------+

Parameters:

filename A full file specification.

Properties:

Default: | OBJ"source-name.obj"
Phase: | Generate
$SET: | Any

Comments:

This directive creates a file in the format specified, with the name specified. For example, if you specify OBJ"myprog.obj", then a file myprog.obj is produced that contains object code.

With NOOBJ, no object code file is produced. If this directive is not specified, the name of the object code file is the basename of the source code file with an extension of .obj.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


OSEXT

Tells the Compiler what extension to expect by default on the names of source files.

Syntax:

>>-.---.--OSEXT--"ext"---------------------><
   +-/-+

Parameters:

ext The extension.

Properties:

Default: | OSEXT"cbl"
Phase: | Syntax check
$SET: | Any

Comments:

If the source filename used in the command or prompt does not have an extension or a trailing period the value in this directive is added.

Specifying a null extension (OSEXT"") indicates that the filename has no extension.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


P64

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Compiles a program for execution in a 64-bit run-time environment.

Syntax:

 >>-.---.-.----.--P64--------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default
NOP64 compiling with the cob32 command, or if COBMODE is set to 32. P64 compiling with the cob64 command or if COBMODE is set to 64.
IDE equivalent
Phase
Syntax check
$SET
Any

Dependencies:

P64 immediately sets: RTNCODE-SIZE"8"

NOP64 immediately sets: RTNCODE-SIZE"4"

Comments:

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


PROGID-INT-NAME

Causes the name of the intermediate code file to be taken from the PROGRAM-ID clause, rather than the name of the source file.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Syntax:

>>-.---.-.----.--PROGID-INT-NAME------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPROGID-INT-NAME
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


PROTOTYPE

Enables relaxed or strict checking of call prototypes for COMP, BINARY, COMP-4, COMP-5 and COMP-X data items when used in the BY VALUE or RETURNING clauses of a CALL statement. It also inhibits or enables the implicit copying of parameter types from the prototype.

Syntax:

>>----.---.-----PROTOTYPE----"level"---------------------><
      +-/-+

Parameters:

level
One of:
RELAXED
Data items and parameter attributes are loosely checked against the prototype
NORMAL
Data items are strictly checked against the protoype, while parameter attributes are loosely checked
STRICT
Data items and parameter attributes are strictly checked against the proto

Properties:

Default: | PROTOTYPE"RELAXED
Phase: | Syntax check
$SET: | Any

Comments:

The PROTOTYPE directive gives you control over how calls to call prototypes are handled.

PROTOTYPE"RELAXED" can be particularly useful when you compile programs written on 32-bit systems that use call prototypes written on 64-bit systems.

By default, BY VALUE binary data-items are loosely type-checked (that is PROTOTYPE"RELAXED" is set). For example, a CALL statement can provide a PIC X(2) COMP data-item in its USING list, and that item can correspond to a PIC X(n) COMP data-item in a call prototype, where n can be from 1 to 4 on a 32-bit system, and 1 to 8 on a 64-bit system. If the value passed was larger than that specified for the receiving data item, truncation occurs. If you want to avoid truncation due to this loose type-checking, set PROTOTYPE"NORMAL"or PROTOTYPE"STRICT" when compiling your program.

If you set PROTOYPE"NORMAL" or PROTOTYPE"RELAXED", the attributes for the parameters of a call are copied from the prototype. If you set PROTOYPE"STRICT", this does not happen. For example, suppose you have the program:

program-id. prog1 is external.
entry call-conv "my_api" by value x1
                         by reference x2
end program prog1.

program-id. prog2.
call "my_api" by x1 x2

If you set PROTOYPE"NORMAL", the call to my_api is converted by the Compiler to:

call call-conv "my_api" by value x1
                        by reference x2

If you set PROTOTYPE"STRICT", the call to my_api is treated as if the parameters followed the normal rules. The call is therefore is converted to:

call "my_api" by reference x1
              by reference x2

and the Compiler issues appropriate error messages. Similarly, if the call convention does not match that specified in the prototype, or is not specified to the CALL statement, error messages are issued.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


RDFPATH

Specifies a location for a repository file.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.--.----RDFPATH-"path"---.--------><
   +-/-+  +-NO-RDFPATH----------+

Parameters:

path The pathname in which the repository file is stored.

Properties:

Default: | NORDFPATH
Phase: | Syntax check
$SET: | Initial

Comments:

Repository files are searched for in the order:

  1. Source folder if NORDFPATH, or the path specified by RDFPATH
  2. The location specified by the COBCPY environment variable

Repository files are stored in the source folder if you specify NORDFPATH.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List
Related concepts
The Repository Paragraph
Related reference
ACTUAL-PARAMS
REPOSITORY


REPOSITORY

Creates a repository file or requests that the program being compiled is checked against the repository file.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-------REPOSITORY--"option"------><
   +-/-+

Parameters:

option
One of:
UPDATE ON
A repository file is created for the class, program, function or interface being compiled.
UPDATE OFF
No repository file is created.
CHECKING ON
A repository is used for conformance checking of parameters in CALL and INVOKE statements.
CHECKING OFF
No conformance checking takes place.

Properties:

Default: | REPOSITORY "UPDATE OFF CHECKING OFF"
Phase: | Syntax check
$SET: | Initial

Comments:

The repository file is created in the directory specified by the RDFPATH directive.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List
Related concepts
The Repository Paragraph
Related reference
ACTUAL-PARAMS
RDFPATH


SOURCETABSTOP

Sets the tab stop boundary in effect. When the Tab key is pressed, the cursor advances n spaces to position itself on the next specified tab position.

Syntax:

>>-.---.----.----SOURCETABSTOP-"number"-.----><
   +-/-+    +-NO-SOURCETABSTOP----------+

Parameters:

number A number between 1-255

Properties:

Default: | SOURCETABSTOP"4" (IDE default) or SOURCETABSTOP"8" (command line default)
Phase: | Syntax check
$SET: | Initial

Comments:

Setting NO-SOURCETABSTOP stops spaces being inserted when a tab is encountered. This is useful if you have embedded a tab in a literal and require the literal to retain the value x"09".

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


UNICODE

Specifies the encoding to be used for Unicode characters.

Syntax:

>>-.---.--UNICODE--"unicode-type"---------><
   +-/-+

Parameters:

unicode-type
The encoding of Unicode characters. Possible values are:
NATIVE
A Unicode character is represented as the native UTF-16 encoding on the platform on which the program is being executed
PORTABLE
A Unicode character is represented as a big-endian UTF-16 encoding irrespective of the platform on which the program is being run

Properties:

Default: | UNICODE"NATIVE"
Phase: | Syntax check
$SET: | Yes
Parent topic: Compiler Control - Compile/Link Files
Parent topic: Compiler Directives - Alphabetical List


Compiler Control - Directives Control

  • COBOLDIR
    Specifies whether the Compiler should process the directives in a cobol.dir file or ignore it.
  • CONFIRM
    Makes the Compiler echo all subsequent directives to the screen.
  • DEFINE
    Declares a compilation variable to be used in ISO2002 conditional compilation.
  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • DIRECTIVES, DIR
    Makes the Compiler read directives from a file.
  • DIRECTIVES-IN-COMMENTS
    Makes the Compiler process $SET statements held in comment lines.
  • SETTING, SETTINGS
    Makes the Compiler include in the source listing a list of the settings of directives.
  • SHOW-DIR
    Makes the Compiler show the contents of directives files in the source listing.
  • USE
    Makes the Compiler read directives from a file.
Parent topic: Compiler Control


COBOLDIR

Specifies whether the Compiler should process the directives in a cobol.dir file or ignore it.

Syntax:

>>-.---.-.----.--COBOLDIR------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | COBOLDIR
Phase: | Syntax check
$SET: | No
Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List


CONFIRM

Makes the Compiler echo all subsequent directives to the screen.

Syntax:

>>-.---.-.----.--CONFIRM-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCONFIRM
Phase: | Both
$SET: | No

Dependencies:

Set to CONFIRM immediately by VERBOSE.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBOL Directives


DEFINE

Declares a compilation variable to be used in ISO2002 conditional compilation.

Syntax:

>>---DEFINE-define-name-.-(numeric-lit)--.----><
                        +-(true)---------+
                        +-(false)--------+
                        +-"alphanum-lit"-+

Parameters:

Parameter | Definition
define-name | The name of a compilation variable
numeric-lit | A numeric literal; the assigned value must be an integer
true | Equivalent of Boolean literal B'1'
false | Equivalent of Boolean literal B'0'
alphanum-lit | An alphanumeric literal

Properties:

Default: | Not set
Phase: | Syntax check
$SET: | Any

Comments:

If a true or false parameter is specified, the category is Boolean; otherwise parentheses indicate a category of numeric, and quotation marks indicate a category of alphanumeric.

To define several compilation variables, use the DEFINE option repeatedly (that is, one compilation variable per DEFINE directive).

Values assigned to compilation variables by this option need to be activated in the source code, using the ISO2002 conditional compilation syntax >>DEFINE define-name AS PARAMETER; see ISO2002 Conditional Compilation for more details.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List
Related concepts
The DEFINE Directive
Appendix A - Examples of Conditional Compilation


DIRECTIVES, DIR

Makes the Compiler read directives from a file.

Syntax:

>>-.---.-.-DIRECTIVES-.-.-"filename"-.-------><
   +-/-+ +-DIR--------+ +-"$env-var"-+

Parameters:

filename | A full file specification of the directives file. This can be any valid filename except cobol.dir or $COBDIR/etc/cobopt.
$env-var | An environment variable that is set to the full file specification of the directives file.

Properties:

Default: | None
Phase: | Syntax check
$SET: | Any

Comments:

A directives file is a text file containing directives. Directives are separated by a space or the end of line. A directive cannot be broken across two lines.

You can include a comment in the file by placing an ampersand (in column 1 of the comment line, followed by a space. If you omit the space the comment is treated as a directive, and the syntax check on that file fails.

The directives are read from the file until the end of file is reached or another DIRECTIVES directive is encountered. The maximum length of a line is 128 characters.

You can specify more than one directives file in a program by specifying DIRECTIVES"filename" several times. If you specify the DIRECTIVES directive in a directives file, the Compiler switches to the new directives file, reads all the directives in it, returns to the original directives file, and continues to read the directives specified after the DIRECTIVES directive. You can nest directives files to any depth.

The directives file is searched for in the current and COBOL system directories. If no extension is specified, a file extension of .dir is added before the search is made. If no file is found, the search is repeated with no extension.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List
Related reference
USE
User Directives File


DIRECTIVES-IN-COMMENTS

Makes the Compiler process $SET statements held in comment lines.

Syntax:

>>-.---.-.----.--DIRECTIVES-IN-COMMENTS----><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NODIRECTIVES-IN-COMMENTS
Phase: | Syntax check
$SET: | Any

Comments:

This directive enables sources to contain directives used when compiling with the Micro Focus Compiler, but ignored (as comment lines) by any other compiler.

$SET can appear anywhere on a line, provided it is the first thing on the line. However, if this directive is set, the $SET statement is processed even if the line is a comment line (asterisk in column 7).

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List


SETTING, SETTINGS

Makes the Compiler include in the source listing a list of the settings of directives.

Syntax:

>>-.---.-.-------.-SETTING--.-.----------.-.-><
   +-/-+ |       +-SETTINGS-+ +-"format"-+ |
         +.----.-.-SETTING--.--------------+
          +-NO-+ +-SETTINGS-+

Parameters:

format
The layout of the listing. Only affects the listing given during the syntax check phase. One of:
LINE
Lines of directives, each separated from the next by a space.
COL
One directive per line.
COL3
Three directives per line in columns.

Properties:

Default: | NOSETTING
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to NOSETTING by NOLIST at end.

Comments:

If format is not specified, LINE is assumed.

A few directives provided only for compatibility with other COBOL systems are not shown. Also not shown are directives that control code generation, make specific changes to the reserved word list, or are synonymous with other directives.

If the directive is specified other than on a $SET statement, the directives list is produced before processing the program source. If the directive is specified on a $SET statement, the list is produced once all the directives on that statement have been processed. In each case, the list contains the state of each directive at that point.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
LIST
Compiler Control - Directives Control
Compiler Control - Listing
Key to Compiler Directives


SHOW-DIR

Makes the Compiler show the contents of directives files in the source listing.

Syntax:

>>-.---.-.----.--SHOW-DIR------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSHOW-DIR
Phase: | Syntax check
$SET: | Any

Comments:

A directives file means cobol.dir or a file that appears in a DIRECTIVES or USE directive. For the contents of cobol.dir to appear in the source listing, SHOW-DIR must be specified at the start of cobol.dir, as this file is processed before any other directive.

You can use SHOW-DIR and NOSHOW-DIR selectively so that only parts of the directives file are output to the listing.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


USE

Makes the Compiler read directives from a file.

Syntax:

>>-.---.--USE---.-"filename"-.----------------><
   +-/-+        +-"$env-var"-+

Parameters:

filename | A full file specification of the directives file. This can be any valid filename except cobol.dir .
$env-var | An environment variable that is set to the full file specification of the directives file.

Properties:

Default: | Not set
Phase: | Syntax check
$SET: | Any

Comments:

USE is synonymous with the DIRECTIVES Compiler directive. See DIRECTIVES for more information.

Parent topic: Compiler Control - Directives Control
Parent topic: Compiler Directives - Alphabetical List
Related reference
DIRECTIVES, DIR
User Directives File


Compiler Control - Error and Flag Messages

  • BRIEF
    Enables the Compiler to produce only error numbers, and no message texts.
  • CHANGE-MESSAGE
    Changes the severity of errors/messages. Messages can also be suppressed or returned to their original severity.
  • ERRFORMAT
    Specifies the type of error message format to be used for command-line compilations and to appear in the list file.
  • ERRLIST
    Specifies the format of error messages in a list file.
  • ERRQ
    Enables the Compiler to prompt you to stop compiling each time it gives an error message.
  • FLAG
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified dialect of COBOL.
  • FLAGAS
    Makes the Compiler output flagging messages as error messages, warning messages or informational messages.
  • FLAGEUC
    Flags occurences of SBCS (8-bit codes) and certain occurences of DBCS (16-bit codes) in the source code.
  • FLAGMIG
    Causes the Compiler to flag any syntax that behaves differently at run time depending on the setting of CMPR2.
  • FLAGQ
    Enables the Compiler prompt you to stop compiling each time it gives a flagging message.
  • FLAGSINEDIT
    Specifies whether flagging messages are to be included in an error file.
  • FLAGSTD
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified level of the ANSI'85 Standard.
  • HIDE-MESSAGE
    Registers an error message to hide so that if the error is encountered, it is ignored.
  • IMPLICITSCOPE
    Enables the syntax checker to produce warning messages for cases where scope has been implicitly ended. This usually occurs where the scope terminator (END-VERB) could have been used.
  • INFORETURN
    Specifies the return-code value returned by the Compiler when it produces only informational messages.
  • MAX-ERROR
    Causes the Compiler to abort when the specified number of errors have been produced.
  • MOVE-LEN-CHECK
    Causes the Compiler to check source and target lengths for alphanumeric MOVE operations, and produces a warning message if they are different.
  • QUERY
    Each time the Compiler is unable to find a copybook, it prompts you for an action.
  • RESTRICT-GOTO
    Generates a syntax error for GO TO statements that transfer control to outside of the current section.
  • STDERR
    Causes error messages to be echoed to STDERR rather than to the console (STDOUT).
  • WARNING, WARNINGS
    Specifies the lowest severity level of errors to report.
Parent topic: Compiler Control
Related information
COBOL


BRIEF

Enables the Compiler to produce only error numbers, and no message texts.

Syntax:

>>-.---.-.----.--BRIEF---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOBRIEF
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBOL Directives


CHANGE-MESSAGE

Changes the severity of errors/messages. Messages can also be suppressed or returned to their original severity.

Syntax:

                              +---------------+
                              V               |
>>-.---.-.-----CHANGE-MESSAGE--"error svrty"--.-><
   +-/-+ +-NO--CHANGE-MESSAGE-----------------+

Parameters:

error Prefix and number of the message to be changed, or ALL for all messages.
Note: You can use the following prefixes to affect their corresponding error types: CH, DB, EC, ES, SQ. If the prefix is not specified, CH is assumed.
svrty New severity:
S
Serious
E
Error
W
Warning
I
Informational
N
Do not produce this message
R
Reset to normal severity

Properties:

Default: | NOCHANGE-MESSAGE
Phase: | Syntax check
$SET: | Any

Dependencies:

CHANGE-MESSAGE overrides the general settings of directives such as FLAGAS.

Comments:

CHANGE-MESSAGE can take as many parameter pairs as required. If CHANGE-MESSAGE is specified multiple times, the effects are cumulative.

CHANGE-MESSAGE replaces the HIDE-MESSAGE Compiler directive. However, if you use HIDE-MESSAGE in conjunction with CHANGE-MESSAGE, the effects are also cumulative.

Serious errors cannot have their severity reduced unless they were changed to serious (from a lower severity) by another CHANGE-MESSAGE directive or the FLAGAS directive.

Example:

CHANGE-MESSAGE"ALL R"

CHANGE-MESSAGE"CH100 N ES135 E 10 S"

The messages affected in the last example would be COBCH0100, COBES0135 and COBCH0010.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related reference
FLAGAS
HIDE-MESSAGE


ERRFORMAT

Specifies the type of error message format to be used for command-line compilations and to appear in the list file.

Syntax:

>>---ERRFORMAT(integer)------><

Parameters:

integer
Can be one of two values:
1
Traditional format, which has been used for previous products
2
New 'COBCH' format, which is used for compilations from the IDEs

Properties:

Default: | ERRFORMAT(1)
Phase: | Syntax Check
$SET: | Any
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related information
ERRLIST
ERRQ


ERRLIST

Specifies the format of error messages in a list file.

Syntax:

>>-.---.-.------ERRLIST-------"option"----.-------><
   +-/-+ +----NOERRLIST-------------------+

Parameters:

option
A literal specifying the option required, as follows:
TERSE
Only lines containing errors are shown in the list file. Both source line and error are shown.
EMBED
The list file contains a source listing that has error messages embedded within it at the point they occur.
END
The list file contains a source listing, followed by a list of error messages. In a batch compile, no error messages are echoed to screen unless a screen listing is selected.
VERBOSE
The list file contains a source listing that has error messages embedded within it at the point they occur, followed by a separate listing of the error messages.

Properties:

Default: | ERRLIST"EMBED"
Phase: | Syntax check
$SET: | No

Dependencies:

If FLAGQ or ERRQ is set, ERRLIST"END" is switched to ERRLIST"VERBOSE".

Comments:

Mainframe compatible listings are obtained by using ERRLIST"END" for the majority of mainframe compilers. Particularly with a batch compile generating a list file, use of this directive has the following effects:

  • If the program contains errors, the only indication of this will be the message on screen:
    Compilation completed with errors
  • The list file will contain these errors in a block at the end. For each error the line and column will be shown along with the error number and description, and the description might be reformatted and split over several lines if it does not fit into the line as controlled by the LISTWIDTH directive.

Fatal errors cause the format to revert to ERRLIST(EMBED). These errors cause the syntax-check phase of the Compiler to terminate immediately. If ERRLIST(END) were still in force the errors would not be shown, as the end of the listing would not be reached.

If either the ERRQ or FLAGQ directives are set, then, to ensure these are actioned correctly, the Compiler will set ERRLIST(END) to ERRLIST(EMBED).

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


ERRQ

Enables the Compiler to prompt you to stop compiling each time it gives an error message.

Syntax:

>>-.---.-.----.--ERRQ----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOERRQ
Phase: | Syntax check
$SET: | Any

Comments:

This directive should not be used within the IDE.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


FLAGAS

Makes the Compiler output flagging messages as error messages, warning messages or informational messages.

Syntax:

>>-.---.-.-----FLAGAS--"severity"-.--------><
   +-/-+ +-NO--FLAGAS-------------+

Parameters:

severity
A literal showing the severity to assign to flag messages.
S
Severe error
E
Error
W
Warning
I
Informational

Properties:

Default: | NOFLAGAS
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related concepts
DIALECT
Related reference
FLAG
WARNING, WARNINGS
CHANGE-MESSAGE
HIDE-MESSAGE


FLAGEUC

Flags occurences of SBCS (8-bit codes) and certain occurences of DBCS (16-bit codes) in the source code.

Syntax:

>>-.---.-.----.-FLAGEUC----><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOFLAGEUC
Phase: | Syntax check
$SET: | Any

Comments:

This directive adds 3 new flag messages.

  • 1090 Literal contains SBCS Katakana characters.

    Alphanumeric literals contain 8-bit Shift-JIS Hankaku Katakana characters which will expand into 16-bit codes on EUC.

  • 1091 Literal contains DBCS or SBCS Katakana characters.

    Hexadecimal literals contain either or both DBCS Shift-JIS or EUC characters.

  • 1092 SBCS Katakana character usage in source is not portable.

    Source code contains SHIFT-JIS Katakana characters which will not compile on the target machine due to codes expanding to two bytes and moving source code.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


FLAGMIG

Causes the Compiler to flag any syntax that behaves differently at run time depending on the setting of CMPR2.

Syntax:

 >>-.---.-.----.--FLAGMIG----------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFLAGMIG
Phase: | Syntax check
$SET: | Any

Comments:

Such syntax receives W-level messages, with the additional text "MIGR" appearing in the message line to indicate that the warning results from specifying the FLAGMIG directive.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


FLAGQ

Enables the Compiler prompt you to stop compiling each time it gives a flagging message.

Syntax:

>>-.---.-.----.--FLAGQ---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFLAGQ
Phase: | Syntax check
$SET: | Any

Comments:

This directive should not be used within the IDE.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


FLAGSINEDIT

Specifies whether flagging messages are to be included in an error file.

Syntax:

>>-.---.-.----.--FLAGSINEDIT---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | FLAGSINEDIT
Phase: | Both
$SET: | No

Comments:

This directive has no effect if NOEDITOR is specified. If EDITOR and FLAGSINEDIT are specified, the error file produced contains all flagging messages produced by the Compiler.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


HIDE-MESSAGE

Registers an error message to hide so that if the error is encountered, it is ignored.
Note: This directive has been replaced by the directive CHANGE-MESSAGE. It remains for compatibility only, and will be removed in a future release.

Syntax:

>>-.---.-.-----HIDE-MESSAGE--"error"-----.----><
   +-/-+ |                               |
         +-NO--HIDE-MESSAGE--.---------.-+
                             +-"error"-+

Parameters:

error Prefix and number of the message to hide.

You can use the following prefixes to affect their corresponding error types: CH, DB, EC, ES, SQ. If the prefix is not specified, CH is assumed.

Properties:

Default: | NOHIDE-MESSAGE
Phase: | Syntax check
$SET: | Any

Comments:

The Compiler also accepts the directive-name without a hyphen; that is, HIDEMESSAGE.

HIDE-MESSAGE"error" adds error to a list of error message numbers. To hide several error message numbers using this feature, you must use the HIDE-MESSAGE directive repeatedly.

When the program is being syntax checked, any message with severity E, W, I, or flagged with this directive is not shown in any listing. It is not included in the error summary at the end of the compilation.

Messages with severity S can be hidden only if they were made severity S by the CHANGE-MESSAGE or FLAGAS directives.

NOHIDE-MESSAGE clears the list of errors currently hidden.

NOHIDE-MESSAGE"error" removes only the specified error message from the list of hidden messages.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related reference
FLAGAS
CHANGE-MESSAGE


IMPLICITSCOPE

Enables the syntax checker to produce warning messages for cases where scope has been implicitly ended. This usually occurs where the scope terminator (END-VERB) could have been used.

Certain syntax conditions end the scope of verbs automatically. This might not be what was intended. NOIMPLICITSCOPE causes the syntax checker to produce warning messages for cases where scope has been implicitly ended. This usually occurs where the scope terminator (END-VERB) could have been used.

Syntax:

>>-.---.--IMPLICITSCOPE------------><
   +-/-+

Parameters:

None

Properties:

Default: | IMPLICITSCOPE
Phase: | Syntax check
$SET: | Any

Dependencies:

None

Comments:

You will need to set WARNINGS(3) to make the messages appear.

Example:

IF ITEM-1 > 10
    MOVE 10 TO ITEM-2
    PERFORM ITEM-3 TIMES
        ADD 1 TO ITEM-3
ELSE
    IF ITEM-1 > 20
        MOVE 20 TO ITEM-2
    ELSE
        MOVE 0 TO ITEM-2.
    MOVE 4 TO ITEM-3

The ELSE ends the scope of the inline PERFORM, and the period ends the scope of all statements, which in this case is the two IF statements.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related information
Concepts of the COBOL Language


INFORETURN

Specifies the return-code value returned by the Compiler when it produces only informational messages.

Syntax:

>>-.---.--INFORETURN--"integer"------------><
   +-/-+

Parameters:

integer Must be between 0 and 4.

Properties:

Default: | INFORETURN"0"
Phase: | Syntax check
$SET: | Any

Comments:

When the Compiler terminates it returns a value that can be tested by an operating system command to determine the success or otherwise of the compilation. This directive enables you to set the value to be returned if the Compiler only outputs informational messages.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related reference
DIALECT
Related information
Compiler Control - Error & Flag Messages
Key to Compiler Directives


MAX-ERROR

Causes the Compiler to abort when the specified number of errors have been produced.

Syntax:

>>-.---.-.-----MAX-ERROR--"err-cnt -.-------.-"-.-><
   +-/-+ |                          +-svrty-+   |
         +-NOMAX-ERROR--------------------------+

Parameters:

err-cnt
The maximum number of errors
svrty
The minimum level of severity to be counted. Only messages of the severity specified and greater are counted. One of:
F
Flag
I
Informational
W
Warning
E
Error
S
Severe
If omitted, assumes F.

Properties:

Default: | NOMAX-ERROR
Phase: | Syntax check
$SET: | Any

Comments:

The Compiler also accepts the directive-name without a hyphen; that is MAXERROR.

If the maximum number of messages of at least the specified severity is reached then the compilation stops. The messages are only counted if produced and after any modification to the severity of the message.

Example:

Specifying the directive:

MAX-ERROR"100 E"

causes the compilation to terminate when 101 messages of severity E or S have been produced.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


MOVE-LEN-CHECK

Causes the Compiler to check source and target lengths for alphanumeric MOVE operations, and produces a warning message if they are different.

Syntax:

>>-.---.------.-MOVE-LEN-CHECK--.---------------.--.---><
   +-/-+      |                 +--"parameter"--+  |
              +-NOMOVE-LEN-CHECK-------------------+

Parameters:

Can be one of the following:
ALL
A warning message (COBCH0166) is produced if the source and target lengths are different. The same behavior is produced if you do not specify a parameter.
TRUNC

A warning message (COBCH1247) is produced when the source length is greater than the target length.

Properties:

Default: | NOMOVE-LEN-CHECK
Phase: | Syntax check
$SET: | Any

Comments:

This check is only performed for any operations that include a reference modified source or target item if the length specified is a literal value.

The warning messages produced by enabling this directive are only visible if WARNINGS"2" or WARNINGS"3" is also enabled.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


QUERY

Each time the Compiler is unable to find a copybook, it prompts you for an action.

Syntax:

>>-.---.-.----.--QUERY---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | QUERY
Phase: | Syntax check
$SET: | Any

Comments:

With QUERY, if the Compiler cannot find a copybook, it asks you whether to terminate the compilation, try the search again, produce an error message and continue, or try again with an alternative path specified by you.

With NOQUERY, the Compiler simply produces an error message and continues.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


RESTRICT-GOTO

Generates a syntax error for GO TO statements that transfer control to outside of the current section.

Syntax:

 >>-.---.-.----.--RESTRICT-GOTO------><
    +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NORESTRICT-GOTO
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBCH1259 GO TO target outside current section


STDERR

Causes error messages to be echoed to STDERR rather than to the console (STDOUT).

Syntax:

>>-.---.-.----.--STDERR--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSTDERR
Phase: | Syntax check
$SET: | Any

Comments:

This directive should only be used if you are compiling from the command line.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List


WARNING, WARNINGS

Specifies the lowest severity level of errors to report.

Syntax:

>>-.---.-.----.-WARNING--.-"integer"-.-----><
   +-/-+ |    +-WARNINGS-+           |
         +-NO-.-WARNING--.-----------+
              +-WARNINGS-+

Parameters:

integer
One of:
1
Only those of level U, S, or E.
2
Only those of level U, S, E, or W.
3
All levels, that is, levels U, S, E, W, and I.

Properties:

Default: | WARNING"1"
Phase: | Syntax check
$SET: | Any

Comments:

With NOWARNING only those of level U or S are reported.

Parent topic: Compiler Control - Error and Flag Messages
Parent topic: Compiler Directives - Alphabetical List
Related concepts
DIALECT
Related reference
FLAG
FLAGAS
COBOL Directives


Compiler Control - Listing

  • COPYLIST
    Makes the Compiler list the contents of files named in COPY statements.
  • COPYLISTCOMMENT
    Specifies the type of comment to be used on COPY statements in .lst files when the COPYLIST directive is specified.
  • DATAMAP
    Causes the Compiler to output information on data items.
  • DATE
    Puts the date in the Date-Compiled paragraph and at the top of each page of the listing.
  • ERRLIST
    Specifies the format of error messages in a list file.
  • FORM
    Specifies the number of lines on each page of the listing.
  • LINE-COUNT
    Controls the detail of information displayed at the end of a source listing.
  • LIST
    Specifies the destination of the source listing file.
  • LISTPATH
    Specifies a path on which the list file is to be written. The name of the list file is source-name.lst.
  • LISTWIDTH, LW
    Sets the width of the listing.
  • MFCOMMENT
    Treats lines with an asterisk (*) in column 1 the same as comment lines but does not show them in the source listing.
  • PREPLIST
    Causes the list file produced during a compilation to show both the original and modified source created by the preprocessor. It shows all data passed to the Compiler by a preprocessor and any resultant messages on the preprocessor-inserted code.
  • PRINT
    Specifies the destination of the source listing file.
  • RAWLIST
    Prevents changeable information, such as page headers, date, time, Compiler release level, from being included in any listing file produced.
  • REF
    Makes the Compiler include in the source listing the intermediate code address of each Procedure Division statement.
  • REFNO
    Makes the Compiler display its internal reference number at the start of a compilation as well as at the bottom of every listing.
  • RESEQ
    Makes the Compiler produce line numbers.
  • SEQCHK
    Makes the Compiler check the sequence numbers in columns 1 through 6 and identify source lines that are out of sequence.
  • SETTING, SETTINGS
    Makes the Compiler include in the source listing a list of the settings of directives.
  • SHOW-DIR
    Makes the Compiler show the contents of directives files in the source listing.
  • TIME
    Puts the time at the top of each page of the listing.
  • VERBOSE
    Sends messages from the Compiler to the screen.
  • XREF
    Makes the Compiler produce a cross-reference listing.
  • ZEROSEQ
    Causes leading zeros to appear in the sequence numbers in columns 1 through 6.
Parent topic: Compiler Control


COPYLIST

Makes the Compiler list the contents of files named in COPY statements.

Syntax:

>>-.---.-.----.--COPYLIST-.-----------.----><
   +-/-+ +-NO-+           +-"integer"-+
                          +---"ALL"---+

Parameters:

integer Must be 0 or between 50 and 99.

Properties:

Default: | COPYLIST
Phase: | Syntax check
$SET: | Any

Comments:

integer is the number of a COBOL segment. It must be 0 or in the range 50 through 99. If it is not specified, the contents of all copybooks are listed. If it is specified, the contents of all copybooks in the first three divisions (that is, the Identification, Environment and Data Divisions), the root, and the given segment are listed. An integer of 0 refers to the first three divisions and all root segments.

COPYLIST "ALL" causes all copybook contents to be listed, including those that have the SUPPRESS clause on the COPY statement in the source.

NOCOPYLIST prevents the listing of the contents of any copybooks. If a segment-number is specified with NOCOPYLIST, only copybooks in that segment are listed. For example:

COPYLIST"53" | List all copybooks in the first three divisions, the root segment, and segment 53.
NOCOPYLIST"53" | List only copybooks that are in segment 53.

Whatever the state of this directive, the name of any copybook open when a page heading is output is given in that heading.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


COPYLISTCOMMENT

Specifies the type of comment to be used on COPY statements in .lst files when the COPYLIST directive is specified.

Syntax:

>>-----COPYLISTCOMMENT-"integer"---><

Parameters:

integer
The type of comment used. The possible values are:
1
Specifies an MFCOMMENT with the asterisk in column 1
7
Specifies a standard comment with the asterisk in column 7

Properties:

Default: | COPYLISTCOMMENT(1)
Phase: | Syntax check
$SET: | Any

Dependencies:

This directive has no effect unless the COPYLIST directive is on.

Comments:

This directive controls whether the MFCOMMENT directive is required when recompiling the .lst file.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


DATAMAP

Causes the Compiler to output information on data items.

Syntax:

>>-.---.-.--------DATAMAP-.----------.--.---><
   +-/-+ |                +-(option)-+  |
         +-NO-DATAMAP-------------------+

Parameters:

option
Displays the Address column or the Offset column as part of the data item information.
ADDR
Displays the Address column, which shows the address of the data item, as an offset from the beginning of the program's data area. This option is only applicable to native code.
OFFSET
Displays the Offset column, which shows the offset value of each data item from the beginning of its 01 level group.

Properties:

Default: | NODATAMAP
Phase: | Syntax check
$SET: | Initial

Dependencies:

DATAMAP(OFFSET) is automatically set when compiling to managed code when you specify DATAMAP without any parameters.

DATAMAP(ADDR) is automatically set when compiling to native code when you specify DATAMAP without any parameters.

Comments:

This directive causes the check phase of the Compiler to output information on the data items; both those that you have specified, and those automatically generated by the Compiler, such as the data area for the RETURN-CODE special register.

The information is output at the end of the list file. The information on the data items is output in the same order as the items are encountered in your program by the Compiler. The first line is the program-id of the program to which the data items belong. For each data item, the following information is listed:

  • The line number
  • The data name
  • The address or offset of the data item; see the option parameters
  • The size of the data item in bytes
  • The attributes of the data item. This consists of a string in the following format:

    ss xxxx cccccccccc R E G

    where the variables are:

    ss
    Location of data item. This can be:
    IO | Input-Output Section
    FD | File Description
    WS | Working-Storage Section
    TL | Thread-Local-Storage Section
    OS | Object-Storage Section
    LC | Local-Storage Section
    LS | Linkage Section
    RD | Report Section
    SS | Screen Section
    PG | Variables, such as special registers, generated by the Compiler check phase
    PD | Temporary variables, such as those used in search statements, generated by the Procedure Division
    xxxx
    Can be:
    G | Group item
    GO | Group occurs item
    GSO | Group sub occurs item
    E | Elementary item
    EO | Elementary occurs item
    ESO | Elementary sub occurs item
    ESOO | Elementary sub occurs occurs item
    cccccccccc
    A description of the data type; for example, Display, Comp, Comp-3, Numeric E (for Numeric Edited), AlphNum J (for AlphaNumeric Justified), and so on
    R
    The item is a Redefinition of some other data item
    E
    The data item is an External data item
    G
    The data item is a Global data item
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


DATE

Puts the date in the Date-Compiled paragraph and at the top of each page of the listing.

Syntax:

>>-.---.-.-------DATE--"string"-.----------><
   +-/-+ +.----.-DATE-----------+
          +-NO-+

Parameters:

string An alphanumeric literal.

Properties:

Default: | DATE
Phase: | Syntax check
$SET: | No

Comments:

The date and time, available from the operating system, are automatically inserted when you specify DATE. You can, however, enter the date yourself as the parameter. With NODATE, the paragraph is left unaltered.

With DATE, the operating system date or the string you enter appears at the top of each page of the listing. With NODATE, spaces are used instead.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


FORM

Specifies the number of lines on each page of the listing.

Syntax:

>>-.---.-.-----FORM--"integer"-.-----------><
   +-/-+ +-NO--FORM------------+

Parameters:

integer Must be greater than 3.

Properties:

Default: | FORM"60"
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to NOFORM at end by NOLIST.

Set to FORM"60" immediately by LIST.

Comments:

With FORM"integer", a form-feed character is always produced at the head of the listing file. With NOFORM, no form-feed characters or page headings are produced anywhere in the listing.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


LINE-COUNT

Controls the detail of information displayed at the end of a source listing.

Syntax:

>>-.---.-.-------LINE-COUNT--"integer"-.----><
   +-/-+ +.----.-LINE-COUNT------------+
          +-NO-+

Parameters:

integer
Controls the detail displayed:
1
The number of source lines checked, excluding blank lines and comments, is displayed at the end of the source listing.
2
As well as number of source lines checked, many additional details are displayed at the end of the source listing. These include the number of calls, number of sections and number of conditions in the program.

Properties:

Default: | NOLINE-COUNT
Phase: | Syntax check
$SET: | Initial

Dependencies:

LINE-COUNT"2" sets ANIM immediately.

Comments:

Specifying LINE-COUNT with no integer is the same as specifying LINE-COUNT"2".

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


LIST

Specifies the destination of the source listing file.

Syntax:

>>-.---.-.-------LIST-.-"Destination"-..---><
   +-/-+ |            +-()------------+|
         +.----.-LIST------------------+
          +-NO-+

Parameters:

destination
A full file specification or a device-name.

Properties:

Default: | NOLIST
Phase: | Syntax check
$SET: | Any (for LIST and NOLIST)
 | None (for LIST"filename" and LIST())

Dependencies:

NOLIST sets NOFORM, NOSETTING and NOXREF at end.

LIST sets FORM"60" immediately.

Comments:

If you specify an existing file, it is overwritten.

When NOLIST is specified, no source listing is produced. If you specify LIST with no destination, the source listing is sent to the screen. If you specify either destination or (), you cannot use this directive in a $SET statement.

destination can be the name of any suitable device. Use CON: for the screen.

NOLIST and LIST with no parameter can be used in $SET statements in a program to list selected parts of the program. The destination of the listing cannot be changed in this way.

LIST() causes the source listing to be put in the file source-name.lst, where source-name is the basename of the filename of the program being compiled.

If you want to list the source to a file for every compilation you do, place the LIST() directive in the cobol.dir file. This overrides the default NOLIST.

Alternatively, if you already have a LIST directive in your cobol.dir, making every listing go to the screen, you can override it by using LIST() on the command line.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBOL Directives
Related information
Compiler Control - Listing
FORM
SETTING, SETTINGS
XREF
Key to Compiler Directives


LISTPATH

Specifies a path on which the list file is to be written. The name of the list file is source-name.lst.

Syntax:

>>-.---.---.--LISTPATH--"list-path"--.--><
   +-/-+   +---NOLISTPATH------------+

Parameters:

list-path Path to which the list file is written, or an environment variable specifying the path to which the list file is written.

Properties:

Default: | NOLISTPATH
Phase: | Syntax check
$SET: | Initial

Comments:

In order to point list-path to an environment variable, suffix it with a $ (dollar) sign (for example, listpath"$listdir") to indicate that the value is not a directory name.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


LISTWIDTH, LW

Sets the width of the listing.

Syntax:

>>-.---.--.-LISTWIDTH-.-"width"------------><
   +-/-+  +-LW--------+

Parameters:

width Width in characters. It must be between 72 and 132.

Properties:

Default: | LISTWIDTH"80"
Phase: | Syntax check
$SET: | Any

Comments:

LISTWIDTH"132" causes additional information to be displayed for each line listed. This includes the first eight characters of the current copybook-name (spaces for the main file) together with the number of the line relative to the start of that file.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


MFCOMMENT

Treats lines with an asterisk (*) in column 1 the same as comment lines but does not show them in the source listing.

Syntax:

>>-.---.-.----.--MFCOMMENT-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | MFCOMMENT
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to NOMFCOMMENT at end by SOURCEFORMAT"FREE".

Comments:

With MFCOMMENT, lines with an asterisk in column 1 are ignored by the Compiler and do not appear in the source listing (though they do appear in Animator). With NOMFCOMMENT, the asterisk forms part of the sequence number and has no special significance.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


PREPLIST

Causes the list file produced during a compilation to show both the original and modified source created by the preprocessor. It shows all data passed to the Compiler by a preprocessor and any resultant messages on the preprocessor-inserted code.

Syntax:

>>-.---.-.----.--PREPLIST------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPREPLIST
Phase: | Syntax check
$SET: | No

Comments:

This directive only affects the contents of a listing file. It does not determine if a listing file is produced, or the name of the file.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


PRINT

Specifies the destination of the source listing file.

Syntax:

>>-.---.-.-------PRINT-.-"destination"-..--><
   +-/-+ |             +-()------------+|
         +.----.-PRINT------------------+
          +-NO-+

Parameters:

destination A full file specification, or a device-name.

Properties:

Default: | NOPRINT
Phase: | Syntax check
$SET: | Any

Comments:

PRINT is synonymous with LIST.

If you specify an existing file, it is overwritten.

When NOPRINT is specified, no source listing is produced. If you specify PRINT with no destination, the source listing is sent to the screen. If you specify either destination or (), you cannot use this directive in a $SET statement.

destination can be the name of any suitable device. Use CON: for the screen.

NOPRINT and PRINT with no parameter can be used in $SET statements in a program to list selected parts of the program. The destination of the listing cannot be changed in this way.

PRINT() causes the source listing to be put in the file source-name.lst, where source-name is the basename of the filename of the program being compiled.

If you want to list the source to a file for every compilation you do, place the PRINT() directive in the cobol.dir file. This overrides the default NOPRINT.

Alternatively, if you already have a PRINT directive in your cobol.dir, making every listing go to the screen, you can override it by using PRINT() on the command line.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


RAWLIST

Prevents changeable information, such as page headers, date, time, Compiler release level, from being included in any listing file produced.

Syntax:

>>-.---.-.----.--RAWLIST-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NORAWLIST
Phase: | Syntax check
$SET: | Any

Comments:

Specifying this directive does not affect whether a listing is produced or the name of the listing file.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


REF

Makes the Compiler include in the source listing the intermediate code address of each Procedure Division statement.
Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Syntax:

>>-.---.-.----.--REF---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOREF
Phase: | Both
$SET: | Any

Dependencies:

None.

Comments:

A table is placed at the end of the listing, in the format:

Address | Line No | Address | Line No | Address | Line No | Address | Line No
000000FD | 16161 | 00000101 | 16162 | 00000109 | 16163 | 00000121 | 16165
0000012A | 16166 | 00000133 | 16169 | 00000138 | 16170 | 0000013C | ...
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


REFNO

Makes the Compiler display its internal reference number at the start of a compilation as well as at the bottom of every listing.

Syntax:

>>-.---.-.----.--REFNO---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOREFNO
Phase: | Syntax check
$SET: | No
Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


RESEQ

Makes the Compiler produce line numbers.

Syntax:

>>-.---.-.----.--RESEQ---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | RESEQ
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to RESEQ immediately by XREF.

Set to NORESEQ immediately by SEQCHK.

Set to NORESEQ at end by SOURCEFORMAT"FREE".

Comments:

These are COBOL line sequence numbers, starting at 1 and increasing in increments of 1.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


TIME

Puts the time at the top of each page of the listing.

Syntax:

>>-.---.-.----.--TIME----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | TIME
Phase: | Syntax check
$SET: | No

Comments:

This directive has no effect if NODATE is specified.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


VERBOSE

Sends messages from the Compiler to the screen.

Syntax:

>>-.---.-.----.--VERBOSE-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOVERBOSE
Phase: | Syntax check
$SET: | No

Dependencies:

VERBOSE sets CONFIRM immediately.

Comments:

When VERBOSE is specified, messages concerning accepted directives and the size of code and data areas are displayed on the screen.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List


XREF

Makes the Compiler produce a cross-reference listing.

Syntax:

>>-.---.-.----.--XREF----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOXREF
Phase: | Syntax check
$SET: | Initial

Dependencies:

XREF sets RESEQ immediately.

Set to NOXREF at end by NOLIST.

Comments:

This directive has no effect if the LIST directive is not specified.

To produce the cross-reference listing the Compiler needs extra work space on the disk. The space needed depends on the number of data items and procedure-names and the number of times they are referenced.

On UNIX, to produce the message "*End of cross reference listing" in the cross reference listing you must also specify the verbose compiler option, -v.

When the XREF directive is specified, extra information is added to the end of the .lst file produced:

  • Name of the data item
  • Type of the data item
  • Line number where the data item was defined, shown as n#
  • Line numbers where the data item was updated, shown as n*
  • Line numbers where the data item was tested, shown as n?
  • Number of times the data item appeared in the cross-reference listing, shown as (X n)
  • Procedure-name
  • Type of procedure

Example:

The following is an extract from a .lst file for a simple program:

     1 working-storage section.
     2 01 a  pic 9(2).
     3
     4 procedure division.
     5 main section.
     6     move 1 to a
     7     if a = 1 display "HELLO" end-if
     8     stop run.
     ...
* A                              Numeric DISPLAY
*          2#      6*      7?                           (X    3)
*
*               1 data-names
*
* MAIN                           Section
*          5#                                           (X    1)
*
*
*               1 procedure-names
* End of cross reference listing

The cross-referencing information shows that there is one data item, a, of type numeric display, which is defined on line 2, updated on line 6, and tested on line 7. The (X 3) at the end of the line refers to the number of times the data item appears in the cross-reference listing. The procedure-name main also appears in the listing, as a section which is referenced only once.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related information
RESEQ
Compiler Control - Listing
LIST
Key to Compiler Directives


ZEROSEQ

Causes leading zeros to appear in the sequence numbers in columns 1 through 6.

Syntax:

>>-.---.-.----.--ZEROSEQ-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOZEROSEQ
Phase: | Syntax check
$SET: | Any

Comments:

NOZEROSEQ suppresses these leading zeros.

Parent topic: Compiler Control - Listing
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Compiler Control - Listing
Key to Compiler Directives


Compiler Control - Screen

  • BELL
    Makes the bell sound at points such as when compilation stops, either because of an error or because it has finished.
  • CONFIRM
    Makes the Compiler echo all subsequent directives to the screen.
  • ECHO
    Makes the Compiler display error lines and error messages on the screen.
  • ECHOALL
    Sends a full listing to the screen as well as to a printer or other device specified with the LIST or PRINT directive.
  • SUPFF
    Suppresses form-feed characters on the compilation listing if it is sent to the screen.
Parent topic: Compiler Control


BELL

Makes the bell sound at points such as when compilation stops, either because of an error or because it has finished.

Syntax:

>>-.---.-.----.--BELL----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOBELL
Phase: | Syntax check
$SET: | Initial
Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBOL Directives


ECHO

Makes the Compiler display error lines and error messages on the screen.

Syntax:

>>-.---.-.----.--ECHO----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | ECHO
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to NOECHO immediately by ECHOALL.

Comments:

For each error, the source line is displayed together with an error number and (unless BRIEF is set) an explanatory message.

Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List


ECHOALL

Sends a full listing to the screen as well as to a printer or other device specified with the LIST or PRINT directive.

Syntax:

>>-.---.-.----.--ECHOALL-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOECHOALL
Phase: | Syntax check
$SET: | No

Dependencies:

ECHOALL sets NOECHO immediately.

Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List


SUPFF

Suppresses form-feed characters on the compilation listing if it is sent to the screen.

Syntax:

>>-.---.-.----.--SUPFF---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | SUPFF
Phase: | Syntax check
$SET: | Any
Parent topic: Compiler Control - Screen
Parent topic: Compiler Directives - Alphabetical List


Compiling for Debugging and Analysis

These directives make the Compiler create files containing extra information about the program, for input to software used for debugging and analysis.

  • ANIM
    Makes the Compiler produce extra information so that you can debug your program.
  • COBIDY
    Specifies the path where the .idy file is to be written.
  • COLLECTION
    Provides a mechanism for code coverage to identify unexecuted programs.
  • FLAGSINEDIT
    Specifies whether flagging messages are to be included in an error file.
  • PROFILE
    Includes code in your program to produce detailed performance statistics each time you run the program.
  • TESTCOVER
    Enables you to use the test coverage tool, which creates a statistical execution profile of a program.
  • TRACE
    Enables READY TRACE and RESET TRACE statements.
Parent topic: Compiler Directives


ANIM

Makes the Compiler produce extra information so that you can debug your program.

Syntax:

>>-.---.-.----.--ANIM----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | On the command line, when building for native code, NOANIM for generated code, and ANIM for intermediate code. Be aware that the Eclipse IDE overrides these defaults, and sets ANIM or NOANIM depending on the setting of the Compile for debugging COBOL property (Yes or No respectively).
Phase: | Both
$SET: | Initial

Dependencies:

ANIM sets RECURSECHECK

Comments:

The ANIM directive causes a file with extension .idy to be created. This contains the additional information needed to debug the program. The location of the .idy file is controlled by the COBIDY directive. In native code, if you set ANIM on in the syntax check phase and do not delete the .idy file, the Compiler includes source filename and line number information, which is output in a number of error messages, so that you can more easily debug your program.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


COBIDY

Specifies the path where the .idy file is to be written.

Syntax:

>>-.---.-.-------COBIDY-"path-name"-.-----><
   +-/-+ +.----.-COBIDY-------------+
          +-NO-+

Parameters:

path-name Path specification.

Properties:

Default: | NOCOBIDY
Phase: | Syntax check
$SET: | No

Comments:

If you do not specify path-name, the path-name in the COBIDY environment variable is used; if the environment variable contains multiple path-names the first of them is used. With NOCOBIDY, the .idy is written to the same path as the .o file.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


COLLECTION Compiler directive

COLLECTION

Provides a mechanism for code coverage to identify unexecuted programs.

Syntax:

>>-.---.-.----.--COLLECTION(CollectionName)-------------------><
   +-/-+ +-NO-+

Parameters:

CollectionName
The name of the collection the program belongs to.
This can be any string if you are setting the directive from the command line. Inside the IDE, CollectionName is automatically set to the project name.

Properties:

Default: | NOCOLLECTION
Phase: | Syntax
$SET: | Initial
Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List
Related reference
TESTCOVER


PROFILE

Includes code in your program to produce detailed performance statistics each time you run the program.

Syntax:

>>-.---.-.----.--PROFILE-----------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOPROFILE
Phase: | Syntax check
$SET: | No

Comments:

You need to use the Profiler utility to view the statistics.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List


TESTCOVER

Enables you to use the test coverage tool, which creates a statistical execution profile of a program.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--TESTCOVER------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOTESTCOVER
Phase: | Syntax check
$SET: | Any

Comments:

In order to create a program profile, you need to specify this directive and run your programs under test coverage mode.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List
Related reference
COLLECTION
Related information
To use test coverage from the command line
To create test coverage reports
To use test coverage from the command line
To report on tagged lines
Run-time Behavior - General
Key to Compiler Directives


TRACE

Enables READY TRACE and RESET TRACE statements.

Syntax:

>>-.---.-.----.--TRACE----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOTRACE
Phase: | Syntax check
$SET: | Initial

Comments:

When TRACE is set, the READY TRACE statement turns on the trace facility at run time. With this facility on, the name of each paragraph or section heading is displayed as it is executed. RESET TRACE turns this facility off. With NOTRACE, the READY TRACE and RESET TRACE statements have no effect.

Parent topic: Compiling for Debugging and Analysis
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
Compiling for Debugging and Analysis
Key to Compiler Directives


File Handling

These directives affect the way files are handled.

  • ANS85
    Specifies that words reserved in the ANSI'85 COBOL Standard are to be treated as reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that Standard.
  • ASSIGN-PRINTER
    Specifies how to assign the output from an ASSIGN TO PRINTER clause when the clause does not specify a filename.
  • ASSIGN
    Specifies how to assign a filename when neither EXTERNAL nor DYNAMIC appear in the SELECT statement.
  • AUTOLOCK
    Makes the default locking AUTOMATIC rather than EXCLUSIVE for files opened for INPUT, I-O, or EXTEND in a multi-user environment.
  • CALLFH
    Makes the Compiler generate direct calls for all file I/O operations, using the Callable File Handler interface.
  • CALL-RECOVERY
    Specifies the behavior when control is returned to a program.
  • CALLSORT
    Defines the program to be called to handle all SORT and MERGE operations.
  • COBFSTATCONV
    Causes the Callable File Handler to use the user-supplied module specified in the COBFSTATCONV environment variable to convert the file status codes if an I/O error is encountered on a file.
  • DATACOMPRESS
    Specifies the type of data compression to be done on sequential and indexed files.
  • DETECT-LOCK
    Makes READ statements detect when a record is locked by another program.
  • FCDCAT
    Specifies whether the catalogued file information for a file is used when accessing that file.
  • FDCLEAR
    Specifies that the record buffer for a file should be cleared after every write operation.
  • FILESHARE
    Causes the default locking to become AUTOMATIC rather than EXCLUSIVE for files in a multi-user environment, and automatically locks records on a WRITE or REWRITE statement when the program is locking multiple records.
  • FILETYPE
    Specifies the file format to use when creating files.
  • HOSTCONTZERO
    For files defined with the RECORD CONTAINS"0" clause, this directive instructs the File Handler to take the record length from the catalog rather than the file description entry.
  • HOSTFD
    Specifies that the record area associated with a file should only be allocated at the time of an OPEN statement and not before.
  • IDXFORMAT
    Specifies the format to use when creating or opening indexed files.
  • IXNLSKEY
    Specifies that the File Handler should sort index file keys according to the local collating sequence rather than the ASCII collating sequence.
  • IXNUMKEY
    Enables true numeric sorting on index keys.
  • KEYCHECK
    Specifies whether the File Handler checks that all the keys belonging to the indexed file you are opening are defined in your application.
  • KEYCOMPRESS
    Specifies the type of key compression to be done on indexed files.
  • LOCKTYPE
    Specifies the type of record locking.
  • OLDREADINTO
    Changes the behavior of the READ ... INTO statement.
  • OPTIONAL-FILE
    Makes the Compiler treat all files opened for I-O or EXTEND as optional.
  • PRESERVECASE
    Ensures that COBOL items declared in the current program retain their case and are not converted to uppercase as is usual in COBOL. This enables the items to be found from outside the program.
  • PRINT-EXT
    Specifies the extension to be added to the filename associated with the ASSIGN TO PRINTER clause.
  • RDW
    Enables you to find out the length of a record that has just been read from a variable-length sequential file.
  • RECMODE
    Specifies the default format of files.
  • RETRYLOCK
    Specifies that when a READ statement finds that a record is locked, the READ operation is to be retried repeatedly until the record is available.
  • REWRITE-LS
    Allows REWRITE statements on line sequential files.
  • SEQUENTIAL
    Specifies the default file type for files defined (implicitly or explicitly) as ORGANIZATION SEQUENTIAL.
  • SORTTYPE
    Selects which mainframe SORT module to emulate.
  • WRITELOCK, WRITE-LOCK
    Makes the WRITE and REWRITE statements acquire a record lock when the program is locking multiple records in a shared data file in a multi-user environment.
  • WRITETHROUGH, WRITETHRU
    Specifies that disk writes are not to be buffered.
Parent topic: Compiler Directives


ASSIGN-PRINTER

Specifies how to assign the output from an ASSIGN TO PRINTER clause when the clause does not specify a filename.

Syntax:

>>-.---.-.----ASSIGN-PRINTER.-"filename"-.-.-><
   +-/-+ |                  +-""---------+ |
         +--NOASSIGN-PRINTER---------------+

Parameters:

filename
The file to be associated with the ASSIGN TO PRINTER clause.

Properties:

Default: | NOASSIGN-PRINTER
Phase: | Syntax check
$SET: | Any

Dependencies:

DIALECT"RM" sets ASSIGN-PRINTER"" immediately.

Comments:

This directive has no effect if you specify a filename as part of the ASSIGN TO PRINTER clause.

ASSIGN-PRINTER"filename" causes the output to be directed to the filename specified. The filename can be fully specified, including a path-name, base-name, and extension.

ASSIGN-PRINTER() results in the same behavior as including the following COBOL statement:

 select filename-1 assign to printer filename-1

That is, the filename used in your COBOL program is also used as the filename for your output. If the internal filename is too long for your operating system to handle, it is truncated to the maximum length the operating system allows.

By default, the filename does not include an extension, but you can specify an extension by using the PRINT-EXT directive.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


ASSIGN

Specifies how to assign a filename when neither EXTERNAL nor DYNAMIC appear in the SELECT statement.

Syntax:

>>-.---.--ASSIGN--"assign-type"------------><
   +-/-+

Parameters:

assign-type
Must be one of:
EXTERNAL The ASSIGN clause contains a data name or literal that specifies the file's name in the external file-storage environment.
DYNAMIC

the ASSIGN clause contains an external-file-reference that specifies the file to the external environment for possible further mapping to an external file-storage environment-name.

Properties:

Default: | ASSIGN"DYNAMIC"
Phase: | Syntax check
$SET: | Any

Comments:

For any indexed files, or for all files if the program is compiled using the CALLFH directive, filename mapping overrides any syntax definition or use of the ASSIGN directive.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
CALLFH
Key to Compiler Directives
Assigning Filenames


AUTOLOCK

Makes the default locking AUTOMATIC rather than EXCLUSIVE for files opened for INPUT, I-O, or EXTEND in a multi-user environment.

Syntax:

>>-.---.-.----.--AUTOLOCK------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOAUTOLOCK
Phase: | Syntax check
$SET: | Initial

Comments:

This directive does not appear in the SETTING list if its state is the same as WRITELOCK. In this case, the state of the two directives is indicated by the FILESHARE directive.

This directive is included for compatibility with earlier file-sharing products. When writing new programs you should use the locking syntax rather than this directive.

Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


CALLFH

Makes the Compiler generate direct calls for all file I/O operations, using the Callable File Handler interface.

Syntax:

>>-.---.--.------CALLFH--"handler-name"--.--><
   +-/-+  +------CALLFH------------------+

Parameters:

handler-name
Root-name of a program to be called to act as the file handler. One of:
EXTFH
The file handler supplied with this COBOL system
ACUFH
Not supported - see comments.
FHREDIR
For use with Fileshare Version 2
fhname
Name of your own file handler

Properties:

Default: | CALLFH"EXTFH"
Phase: | Syntax check
$SET: | Initial

Comments:

When CALLFH is specified, all file I/O statements are converted to calls to the file handler specified by the parameter.

If handler-name is not specified, the module EXTFH is assumed.

This directive is also used to direct all file handling calls through converter modules, to make use of non-COBOL file handlers.

If your code specifies the ACUFH parameter, it may now produce adverse effects when used. You should replace it with the methods described in Configuring Access to Vision Data Files or Configuring Access to RM/COBOL Data Files. Both of these methods offer a fuller-functioning solution to handling these types of data files.

Parent topic: File Handling
Parent topic: Object Code - External Handlers
Parent topic: Compiler Directives - Alphabetical List
Related reference
Configuring Access to Vision Files
Configuring Access to RM/COBOL Indexed Data Files


CALL-RECOVERY

Specifies the behavior when control is returned to a program.
Note: Use this directive in CICS execution environments only.

Syntax:

>>-.---.-.-------CALL-RECOVERY--"integer"--.-----><
   +-/-+ +.----.-CALL-RECOVERY-------------+
          +-NO-+

Description:

When a CICS transaction has installed an ABEND handler at a given link level, if an ABEND occurs lower down the call chain where non-CICS programs have been called between the owner of the handler and the abending program, the CALL-RECOVERY directive ensures that control is passed directly back to the higher level without executing application code after the call(s) in the intervening programs.

Parameters:

integer
Must be one of:
1
Makes the program check the current call recovery state every time control is returned to it following a call. If there is a controlled exit in force the program performs a GOBACK, that is, passes control back up the COBOL call chain rather than continuing with the next statement.
2
As for 1, but also catches exceptions on CALL dataname statements and sets the call recovery state before performing a GOBACK to pass control back up the COBOL call chain.

Properties:

Default: | NOCALL-RECOVERY
Phase: | Syntax check
$SET: | Initial
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - General
Key to Compiler Directives


CALLSORT

Defines the program to be called to handle all SORT and MERGE operations.

Syntax:

>>-.---.--CALLSORT-"sort-name"--------------><
   +-/-+

Parameters:

sort-name Root-name of a program to be called to process sorts and merges.

Properties:

Default: | CALLSORT"EXTSM"
Phase: | Syntax check
$SET: | Initial
Parent topic: File Handling
Parent topic: Object Code - External Handlers
Parent topic: Compiler Directives - Alphabetical List


COBFSTATCONV

Causes the Callable File Handler to use the user-supplied module specified in the COBFSTATCONV environment variable to convert the file status codes if an I/O error is encountered on a file.

Syntax:

>>-.---.-.----.--COBFSTATCONV--------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCOBFSTATCONV .
Phase: | Syntax check
$SET: | Initial

Comments:

This directive is provided for compatibility with previous versions of Micro Focus COBOL only.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - General
Key to Compiler Directives


DATACOMPRESS

Specifies the type of data compression to be done on sequential and indexed files.

Syntax:

>>-.---.-.-----DATACOMPRESS--"integer"-.---><
   +-/-+ +-NO--DATACOMPRESS------------+

Parameters:

integer
Must be one of:
0
Equivalent to NODATACOMPRESS
1
Specifies run-length encoding.
3
Specifies run-length encoding for double-byte (DBCS) characters
128 through 255
User-defined compression routines

Properties:

Default: | DATACOMPRESS"0"
Phase: | Syntax check
$SET: | Any

Comments:

The only values that can be specified for data compression supported by this system are 0, 1 and 3. Values in the range 128 through 255 indicate user-defined compression routines.

You need to specify data compression only when creating the file. Subsequently, the data compression is detected when the file is opened.

To get data compression on an individual file, use $SET statements in your source so that this directive is in effect only for the part of the source containing the file's SELECT statement.

Data compression is supported only by the Callable File Handler. All indexed files are processed by the Callable File Handler. However, if you want to use data compression with sequential files, every program referencing those files must be compiled with the directive CALLFH"EXTFH".

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
CALLFH
File Handling
Key to Compiler Directives


DETECT-LOCK

Makes READ statements detect when a record is locked by another program.

Syntax:

>>-.---.-.----.--DETECT-LOCK---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | DETECT-LOCK
Phase: | Syntax check
$SET: | Initial

Comments:

The Compiler also accepts the name without a hyphen; that is, DETECTLOCK.

With DETECT-LOCK, if a READ statement reads a record locked by another program, it returns an I/O status of 9/068. With NODETECT-LOCK, it returns 0/000. In both cases it reads the record successfully.

If a READ statement attempts to lock a record (that is, if the statement LOCK MODE IS AUTOMATIC has been specified, or a WITH LOCK phrase is used on the READ statement), and the record is locked by another program, an I/O status of 9/068 is returned. If NODETECT-LOCK is specified, and the READ statement is not attempting to lock a record an I/O status of 0/000 is returned.

When DETECT-LOCK is specified, individual READ statements can be made to ignore locks by using the READ ... IGNORE LOCK syntax.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


FCDCAT

Specifies whether the catalogued file information for a file is used when accessing that file.

Syntax:

>>-.---.--.----.-FCDCAT-----><
   +-/-+  +-NO-+

Parameters:

None

Properties:

Default: | FCDCAT for mainframe dialects; NOFCDCAT for non-mainframe dialects
Phase: | Syntax check
$SET: | Any

Comments:

To enable this behavior for an individual file, use a $SET statement in your source code before the file's SELECT statement.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


FDCLEAR

Specifies that the record buffer for a file should be cleared after every write operation.

Syntax:

>>-.---.-.-------FDCLEAR--"integer"--.-----><
   +-/-+ +.----.-FDCLEAR-------------+
          +-NO-+

Parameters:

integer
Must be one of:
1
Specifies that the record buffer for a file should be cleared after every write operation. The buffer is cleared to the value specified by the DEFAULTBYTE directive.
2
As for 1, but the record buffer is also cleared after the initial OPEN statement.

Properties:

Default: | NOFDCLEAR
Phase: | Syntax check
$SET: | Any

Comments:

The FDCLEAR directive is effective while the SELECT clauses are being processed. Use $SET statements before and after each SELECT clause to apply this feature to selected files. Alternatively, use it once before processing any SELECT statements to apply it to all files in a program.

The FDCLEAR directive is ignored for files subject to a SAME RECORD AREA clause in the I-O-Control paragraph.

Specifying FDCLEAR with no parameter has the same effect as specifying FDCLEAR "1".

Example:

In the following code, FDCLEAR is applied only to file-2:

 file-control.
     select file-1 ...
$set fdclear
     select file-2 ...
$set nofdclear
     select file-3 ...
Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


FILESHARE

Causes the default locking to become AUTOMATIC rather than EXCLUSIVE for files in a multi-user environment, and automatically locks records on a WRITE or REWRITE statement when the program is locking multiple records.
Note: This directive is included for compatibility with earlier file-sharing products. When writing new programs you should use the locking syntax mentioned below rather than this directive.

Syntax:

>>-.---.-.----.--FILESHARE-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFILESHARE
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets FILESHARE immediately.

Comments:

FILESHARE is equivalent to WRITELOCK and AUTOLOCK together. NOFILESHARE is equivalent to NOAUTOLOCK and NOWRITELOCK together.

Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


FILETYPE

Specifies the file format to use when creating files.

Syntax:

>>-.---.--FILETYPE--"integer"--------------><
   +-/-+

Parameters:

integer
An integer representing the type to use.
0
Default format for the operating system (identical to 8)
1
C-ISAM
3
Micro Focus default indexed file format
4
Optimized format for fast duplicate key handling
5
Reserved
6
Reserved
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
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: | FILETYPE"0"
Phase: | Syntax check
$SET: | Any

Dependencies:

FILETYPE"integer" sets IDXFORMAT"integer" immediately.

DIALECT"RM" sets FILETYPE"21" immediately.

Comments:

This directive only works on files processed by the Micro Focus File Handler. Use the CALLFH directive if you are processing files other than indexed files.

To produce print files in the style of an IBM mainframe using FILETYPE"11", you must also:

  • Set the directive OSVS or VCS2
  • Use WRITE AFTER ADVANCING syntax
  • Set the CALLFH directive (so your program uses the Micro Focus File Handler)
  • Use a SELECT statement in the form:
    select printfile assign "print" organization is sequential.

    (Print files in the style of an IBM mainframe have a print control character in the first column.)

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


HOSTCONTZERO

For files defined with the RECORD CONTAINS"0" clause, this directive instructs the File Handler to take the record length from the catalog rather than the file description entry.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--HOSTCONTZERO-------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | HOSTCONTZERO for mainframe dialects; NOHOSTCONTZERO for Micro Focus and non-mainframe dialects
Phase: | Syntax Check
$SET: | Initial
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


HOSTFD

Specifies that the record area associated with a file should only be allocated at the time of an OPEN statement and not before.

Syntax:

 >>-.---.-.----.--HOSTFD-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOHOSTFD
Phase: | Syntax check
$SET: | Initial

Comments:

If you specify this directive, operations on the record area associated with a file are only possible while the file is open. HOSTFD does not affect EXTERNAL or SORT files. Nor does it affect files defined in a SAME RECORD AREA clause in the I-O CONTROL paragraph.

Access to the record area before an OPEN or after a CLOSE may result in a COBRT203 or a COBRT114 error, indicating that the memory has not been or is no longer allocated for the record area.

Specify NOHOSTFD if you need to access a file's record area after a FILE CLOSE has been performed on it.

This directive is for mainframe compatibility.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - Mainframe Compatibility
Key to Compiler Directives


IDXFORMAT

Specifies the format to use when creating or opening indexed files.

Syntax:

>>-.---.--IDXFORMAT--"integer"-------------><
   +-/-+

Parameters:

0
Default format for the operating system (identical to 8)
1
C-ISAM
3
Micro Focus default indexed file format
4
Optimized format for fast duplicate key handling
5
Reserved
6
Reserved
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
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: | IDXFORMAT"0"
Phase: | Syntax check
$SET: | Any

Dependencies:

Set to IDXFORMAT"integer" immediately by FILETYPE"integer".

DIALECT"RM" sets IDXFORMAT"21" immediately.

Comments:

By default, IDXFORMATs 17-21 are unavailable under Enterprise Server. You must ensure the ACUFH and ESACUFH configuration options are both set to ON to use these formats.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override the IDXFORMAT setting.

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

Setting the IDXFORMAT using this Compiler directive overrides the index format setting specified in the file handler configuration file.

Specifying 4 might make the files larger than their IDXFORMAT"3" equivalents.

Micro Focus Level II format files are compatible with Micro Focus products such as Level II COBOL, Professional COBOL V1.2, and VS COBOL Workbench versions up to and including V1.3.

You must not use the ANS85 directive to enable ANSI'85 behavior when using IDXFORMAT"2". However, you can use ANS85"SYNTAX" to enable ANSI'85 syntax.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related reference
ACUFH
ESACUFH


IXNLSKEY

Specifies that the File Handler should sort index file keys according to the local collating sequence rather than the ASCII collating sequence.

Syntax:

>>-.---.-.----.----IXNLSKEY---------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOIXNLSKEY
Phase: | Syntax check
$SET: | Any

Comments:

If you set IXNLSKEY, then move the index file to a different locale, the index keys will no longer be found.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


IXNUMKEY

Enables true numeric sorting on index keys.

Syntax:

>>-.---.-.----.-IXNUMKEY-------------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOIXNUMKEY
Phase: | Syntax check
$SET: | Any

Comments:

Index keys are are normally treated as alphanumeric even if they contain numeric data. Therefore, the results of READ NEXT operations might be unexpected. This directive should be used when the true numeric order is required. In general it will only have an effect for keys defined as signed numeric, but some kinds of unsigned data (for instance COMP-5) may also be affected.

For example, say you have a key defined as pic s9(5), and you had four records for which the key values were 1, -2, 3, -4, stored as:

  • 00001+
  • 00002-
  • 00003+
  • 00004-

If these keys are treated as alphanumeric, they will be retrieved in the above order. However if they are treated as numeric (which is the case when IXNUMKEY is specified), they will be stored (and therefore retrieved when using READ NEXT) in numeric order:

  • 00004-
  • 00002-
  • 00001+
  • 00003+
Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


KEYCOMPRESS

Specifies the type of key compression to be done on indexed files.

Syntax:

>>-.---.-.-----KEYCOMPRESS--"integer"-.----><
   +-/-+ +-NO--KEYCOMPRESS------------+

Parameters:

integer
Must be between 0 and 7, combining the following values
1
Suppress repetitions of duplicate keys.
2
Suppress leading characters that are the same as in the previous key.
4
Suppress trailing spaces.

You can specify any combination of these numbers by adding these values together.

Properties:

Default: | KEYCOMPRESS"0"
Phase: | Syntax check
$SET: | Any

Comments:

KEYCOMPRESS"0" is equivalent to NOKEYCOMPRESS.

You need specify key compression only when creating the file. Subsequently, key compression is detected when the file is opened.

To get key compression on an individual file, use $SET statements in your source code so that this directive is in effect only for the part of the source containing the relevant KEY clause in the file's SELECT statement.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
File Handling
The File Control Entry
Data Description Entry Skeleton
The OCCURS Clause
The INVALID KEY Condition
The ACCEPT Statement
The DELETE Statement
The MERGE Statement
The READ Statement
The REWRITE Statement
The SORT Statement
The START Statement
The WRITE Statement
XML Syntax - DELETE Statement
XML Syntax - READ Statement
XML Syntax - REWRITE Statement
XML Syntax - START Statement
XML Syntax - WRITE Statement
XML Syntax - SELECT Clause
Index Files - Overview
Key to Compiler Directives


LOCKTYPE

Specifies the type of record locking.

Syntax:

>>-.---.--LOCKTYPE--"integer"--------------><
   +-/-+

Parameters:

integer
The type of locking.
0 | Programs can read locked records, but not 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 basename as the file being opened but with a .lck extension. Any record locks are recorded in this file. This enables the File Handler to read and write to files up to 4 gigabytes in size regardless of whether the file is shared or locked. You cannot set this value for striped files.

Properties:

Default: | LOCKTYPE"0"
Phase: | Syntax check
$SET: | Initial

Comments:

This directive only has an effect if the CALLFH directive is used.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


OLDREADINTO

Changes the behavior of the READ ... INTO statement.

Syntax:

>>-.---.-.----.--OLDREADINTO---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDREADINTO
Phase: | Syntax check
$SET: | Any

Comments:

When OLDREADINTO is specified, the implicit move from the file's record area to the data item specified in the INTO phrase is executed even when the READ is not successful. If NOOLDREADINTO is specified, the MOVE only happens if the READ is successful.

Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


OPTIONAL-FILE

Makes the Compiler treat all files opened for I-O or EXTEND as optional.

Syntax:

>>-.---.-.----.--OPTIONAL-FILE-------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | OPTIONAL-FILE
Phase: | Syntax check
$SET: | Initial

Dependencies:

NORM sets OPTIONAL-FILE immediately.

DIALECT"RM", RM, or RM"ANSI" sets NOOPTIONAL-FILE immediately.

Comments:

Under ANSI'85 Standard COBOL, a file is treated as optional only if it has the OPTIONAL phrase in its SELECT statement. For compatibility with the ANSI'85 Standard you must specify the NOOPTIONAL-FILE directive.

Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related reference
Open EXTEND of Nonexistent File
Related information
DIALECT
Run-time Behavior - Compatibility with Other COBOL Dialects
The File Control Entry
XML Syntax - OPEN Statement
XML Syntax - SELECT Clause
RM
The OPEN Statement
The USE Statement
Key to Compiler Directives


PRESERVECASE

Ensures that COBOL items declared in the current program retain their case and are not converted to uppercase as is usual in COBOL. This enables the items to be found from outside the program.

Syntax:

>>-.----.--PRESERVECASE---------><
   +-NO-+

Parameters:

None

Properties:

Default: | PRESERVECASE
Phase: | Syntax check
$SET: | Any

Comments:

PRESERVECASE preserves the case of those items for which the COBOL name determines a name that is visible externally (such as PROPERTY names specified without the AS clause). The exact case of the COBOL name used in the declaration is the case used for the external name. References to the item from within the same COBOL program can still use any case combination.

The directive also preserves the case of data-names in output from the XML GENERATE statement.

Example:

$set preservecase
01 Fred property binary-long.
*> Sets up a property with external name "Fred"

procedure division.
    Move 999 to fred
*> fred is a normal COBOL data name and can therefore be accessed using any case
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


PRINT-EXT

Specifies the extension to be added to the filename associated with the ASSIGN TO PRINTER clause.

Syntax:

>>-.---.-.----PRINT-EXT--"extension"---.-------><
   +-/-+ +-------NOPRINT-EXT-----------+

Parameters:

extension The extension to be added.

Properties:

Default: | NOPRINT-EXT
Phase: | Syntax check
$SET: | Any

Comments:

This directive is ignored unless ASSIGN-PRINTER() is specified with no filename.

Parent topic: File Handling
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


RECMODE

Specifies the default format of files.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.--RECMODE--"format"----------------><
   +-/-+

Parameters:

format
One of:
F
Fixed-length record format.
V
Variable-length record format.
OSVS, VSC21, VSC22
Fixed or variable depending on a file's record definitions. If all record definitions for the file have the same length and are fixed length, the file is fixed-length record format. Otherwise it is variable-length record format.
COBOL370, ENTCOBOL, MVS, OS390, VSC23, VSC24
Fixed or variable length depending on the file's record definitions. If all record definitions for the file are the same length, and are fixed length and/or the FD entry has a RECORD CONTAINS x CHARACTERS clause, the file is fixed-length record format. Otherwise it is variable-length record format.
RMCOBOL
Fixed or variable depending on a file's record definitions and RECORD CONTAINS clause. If all record definitions for the file have the same length and are fixed length (that is, are not described with an OCCURS DEPENDING ON clause) and the RECORD CONTAINS clause does not specify a range of lengths, the file is fixed-length record format; otherwise, the file is variable-length record format.
For fixed length records, because of a RECORD CONTAINS n CHARACTERS clause, the minimum record length will be set to n even if there are record descriptions for the same file that describe fewer than n character positions.

Properties:

Default: | RECMODE"F"
Phase: | Syntax check
$SET: | Initial

Dependencies:

RECMODE"VSC22" set at end by CMPR2.

DIALECT"RM" sets RECMODE"RMCOBOL" immediately.

Comments:

For an individual file this directive is overridden if the FD contains either a RECORD IS VARYING phrase (which specifies variable format) or a RECORDING MODE clause.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
File Description Entry Skeleton
The RECORDING MODE Clause
The RECORD Clause
The PERFORM Statement
The SEARCH Statement
File Organizations
Key to Compiler Directives


RETRYLOCK

Specifies that when a READ statement finds that a record is locked, the READ operation is to be retried repeatedly until the record is available.

Syntax:

>>-.---.-.----.--RETRYLOCK-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NORETRYLOCK
Phase: | Syntax check
$SET: | Any

Dependencies:

NORM sets NORETRYLOCK immediately.

DIALECT"RM" sets RETRYLOCK immediately.

Comments:

This directive has no effect if all of the following are true:
  • The file has a FILE STATUS.
  • The file has a declarative.
  • The RM Compiler directive is set.
Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


SEQUENTIAL

Specifies the default file type for files defined (implicitly or explicitly) as ORGANIZATION SEQUENTIAL.

Syntax:

>>-.---.--SEQUENTIAL--"type"---------------><
   +-/-+

Parameters:

type
One of:
ADVANCING
RECORD SEQUENTIAL with LINE ADVANCING.
ANSI
ANSI-conforming RECORD SEQUENTIAL.
LINE
LINE SEQUENTIAL.
RECORD
RECORD SEQUENTIAL (a standard SEQUENTIAL file).

Properties:

Default: | SEQUENTIAL"RECORD"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM", NORM, or RM"ANSI" sets SEQUENTIAL"RECORD" immediately.

RM sets SEQUENTIAL"LINE" immediately.

Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List


SORTTYPE

Selects which mainframe SORT module to emulate.

Syntax:

>>-.---.-.----.--SORTTYPE--"module-type"----------><
   +-/-+

Parameters:

module-type
DFSORT
Compatibility with DFSORT
SYNCSORT
Compatibility with SYNCSORT

Properties:

Default: | SORTTYPE(DFSORT)
Phase: | Check
$SET: | Initial
Parent topic: File Handling
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
Mfsort Utility


WRITELOCK, WRITE-LOCK

Makes the WRITE and REWRITE statements acquire a record lock when the program is locking multiple records in a shared data file in a multi-user environment.

Syntax:

>>-.---.-.----.-.-WRITELOCK--.-------------><
   +-/-+ +-NO-+ +-WRITE-LOCK-+

Parameters:

None

Properties:

Default: | NOWRITELOCK
Phase: | Syntax check
$SET: | Initial

Comments:

This directive is included for compatibility with earlier file-sharing products. When writing new programs you should use the relevant locking syntax rather than this directive.

Parent topic: File Handling
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


WRITETHROUGH, WRITETHRU

Specifies that disk writes are not to be buffered.

Syntax:

>>-.---.-.----.-.-WRITETHROUGH-.-----------><
   +-/-+ +-NO-+ +-WRITETHRU----+

Parameters:

None

Properties:

Default: | NOWRITETHROUGH
Phase: | Syntax check
$SET: | Any

Dependencies:

Requires CALLFH to be set.

Comments:

When WRITETHROUGH is specified, the system does not buffer disk writes.

To specify this directive for an individual file, use $SET statements in your source so that the directive is in effect only for the part of the source containing the file's SELECT statement.

Using WRITETHROUGH helps improve the integrity of data files by ensuring that every write operation goes to the disk file straight away, reducing the possibility of losing data if your computer crashes. However, it also bypasses all cacheing and blocking methods, resulting in poorer performance.

Parent topic: File Handling
Parent topic: Object Code - File Handling
Parent topic: Compiler Directives - Alphabetical List


Managed COBOL Command Line Compiler Directives

When you build a project, the Compiler directives for managed COBOL are generated according to the project structure and properties. We recommend that you compile programs using the IDE, so that the directives are automatically set.

If you want to compile at the command line, the following directives are available:

  • Application Directives
  • Code Generation Directives
  • Reference, Resource and Namespace Directives
  • Strong Naming Directives
  • Identity, Information and Manifest Directives
Parent topic: Compiler Directives


Application Directives

  • DOTNET
    Sets the reserved words needed for the .NET COBOL language.
  • ILASSEMBLY
    Specifies the name of the assembly created.
  • ILGEN
    Generates the IL for a program with a main program entry point or for a library without one.
  • ILMAIN
    Specifies the entry method for the executable program being compiled.
  • ILNAMESPACE
    Specifies the default namespace for items such as classes when building a project.
  • ILOUTPUT
    Sets the path of the output assembly file or Java class file.
Parent topic: Managed COBOL Command Line Compiler Directives


DOTNET

Sets the reserved words needed for the .NET COBOL language.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-.----.--DOTNET------------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | NODOTNET
IDE equivalent: | None.

Dependencies:

ILGEN sets DOTNET.

Comments:

This directive is not allowed in the $SET statement. You must specify DOTNET on the command line.

Parent topic: Application Directives
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILASSEMBLY

Specifies the name of the assembly created.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.----ILASSEMBLY"assembly-name"--.------------><
       +--NOILASSEMBLY-----------------+

Parameters:

assembly-name
The name of the assembly created. The default name is the same as the name of the file being compiled. The output file has this name with the extension .dll if the directive ILGEN(SUB) is specified, or the extension .exe if ILGEN is specified.

Properties:

Default: | NOILASSEMBLY
IDE equivalent: | Not applicable

Comments:

If you need to specify the path of the output assembly file, you do this using the ILOUTPUT directive.

Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILOUTPUT
Key to Compiler Directives


ILGEN

Generates the IL for a program with a main program entry point or for a library without one.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>------.--ILGEN-.-MAIN--.-----><
        |        +-SUB---+
        +--NOILGEN-------+

Parameters:

MAIN
Indicates that a program with a main entry point is being compiled
SUB
Indicates that a library is being compiled, which doesn't require a main program entry point

Properties:

Default: | ILGEN"MAIN"
IDE equivalent: | Click Project> Properties> Application and then fill in Output Type.

Dependencies:

ILGEN sets DOTNET.

Comments:

This directive is always used when you build a project from the IDE. If a program doesn't require a main program entry point, use the SUB parameter.

This directive is comparable to the ILMAIN directive: ILGEN"SUB" is equivalent to NOILMAIN.

This directive is not allowed in the $SET statement. You must specify ILGEN on the command line.

Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILMAIN

Specifies the entry method for the executable program being compiled.

Syntax:

>>-----.---ILMAIN--"entry-point"--.---><
       +-NOILMAIN-----------------+

Parameters:

entry-point

The name of the main entry point for the executable program, which must be specified either as class-name::method-name, or just as method-name. For example, ILMAIN"classA::methodB" or ILMAIN"methodB". The first format can be used to distinguish between multiple methods with the same name in different classes.

For procedural managed COBOL, the main entry point is denoted by the Procedure Division Using clause, and the name specified in the ILMAIN directive is the program name.

This parameter cannot be zero-length.

Properties:

Default: | NOILMAIN
IDE equivalent: | None
Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILNAMESPACE

Specifies the default namespace for items such as classes when building a project.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-----.---ILNAMESPACE--"namespace"---.--><
       +-NOILNAMESPACE----------------+

Parameters:

namespace The default namespace

Properties:

Default: | NOILNAMESPACE
IDE equivalent: | Click Project > Properties > Micro Focus > Build Configuration > Additional Directives

Comments:

If you set the directive using the $set command, its effect is to only set the default namespace for the current program; other source modules compiled in the same compilation unit are not affected. You include other source modules by using the ILSOURCE directive.

ILNAMESPACE applies only when the given type name itself has no namespace and has no effect on types which specify a namespace name explicitly in the source code.

Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSOURCE


ILOUTPUT

Sets the path of the output assembly file or Java class file.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-----.---ILOUTPUT -"output-path"----.----><
       +-NOILOUTPUT-------------------+

Parameters:

output-path
The path of the output assembly file or Java class file.

Properties:

Default
ILOUTPUT"output-path" (IDE default) or NOILOUTPUT (command line default)
IDE equivalent
Click Project > Properties > Micro Focus > Build Configuration > Output Directory Name (managed projects) or Project > Properties > Micro Focus > Build Configurations > select configuration > COBOL > Output Path (native projects).
Parent topic: Application Directives
Parent topic: Compiler Directives - Alphabetical List


Code Generation Directives

  • ILARRAYPROPERTY
    Controls the way in which the Compiler generates code for data items that include the PROPERTY phrase, and which either include the OCCURS phrase or are subsidiary to a group item with the OCCURS clause.
  • ILCLR
    Allows a managed program to be compiled for Microsoft's Common Language Runtime (CLR) version 2.0 or 4.0.
  • ILCUTPREFIX
    Removes a specified prefix from the names of the COBOL data items in your source code.
  • ILDOC
    Generates documentation in xml format using comments in the code, and puts the documentation in the specified file.
  • ILDYNCALL
    Specifies that CALL literal statements are resolved at run time rather than being resolved at compile time.
  • ILEXPONENTIATION
    Enables you to optimize exponential arithmetic operations by specifying the calculation method used.
  • ILNATIVE
    Exposes COBOL 01 level data items as managed primitives where possible.
  • ILNORMALIZENAMES
    Determines the program elements that are normalized when a procedural COBOL program is compiled to managed code. Normalization in this context results in replacing all $ and - (hypen) characters in the name with _ (underscore) characters.
  • ILOBJECTIFY (deprecated)
    ILOBJECTIFY is deprecated, and supported for backward compatibility only.
  • ILOPTIMIZEDATA
    Causes the Compiler to optimize any numeric data item to a native managed type (typically a 32-bit or 64-bit integer) when it determines that it is safe to do so.
  • ILPARAMS
    Determines the way in which you call a method that contains an array as its last receiving parameter.
  • ILREF
    This directive permits the definition of extension methods and extension operators that are outside of the current compilation unit.
  • ILSHOWPERFORMOVERLAP
    Generates a warning when an overlapping PERFORM range is detected in the program.
  • ILSMARTLINKAGE
    Exposes the linkage section and entry points in procedural COBOL programs to managed code, by creating types.
  • ILSMARTNEST
    Use in conjunction with ILSMARTLINKAGE, to expose the Linkage Section items and entry points to managed code as nested classes of the program class in which they are defined.
  • ILSMARTRESTRICT
    Limits the generation of properties in ILSMARTLINKAGE classes to non-redefining elementary items.
  • ILSMARTSERIAL
    Use in conjunction with ILSMARTLINKAGE. Makes the classes generated with ILSMARTLINKAGE serializable.
  • ILSMARTTRIM
    This directive works in conjunction with ILSMARTLINKAGE, where it trims any trailing spaces from a string item returned by the get property associated with an alphanumeric item processed by ILSMARTLINKAGE.
  • ILSTATIC
    Exposes the entry points of a COBOL program as static methods for compatibility with previous releases.
  • ILTARGET
    Enables an application to target a specified CPU type.
  • ILVERIFY
    Ensures that the compiled IL code is verifiable.
  • JVMDECIMAL
    Determines the type in which certain items are exposed. This directive affects COBOL data items of type 'decimal' and non-integral numeric items exposed as a result of either ILSMARTLINKAGE usage or the PROPERTY keyword.
Parent topic: Managed COBOL Command Line Compiler Directives


ILARRAYPROPERTY

Controls the way in which the Compiler generates code for data items that include the PROPERTY phrase, and which either include the OCCURS phrase or are subsidiary to a group item with the OCCURS clause.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>----ILARRAYPROPERTY(integer)-----------><

Parameters:

integer
0

The property is generated with a type determined by that of the data element. The property will have a number of parameters equal to the dimensionality of the data item. You can only access these properties using COBOL. Other languages such as C# and Visual Basic will not permit access to such properties with parameters. Use this setting to produce the code generated by earlier versions of this product.

1
01 level arrays of native managed types will be generated as simple properties whose type is that of the array type (not the element type). You can access these properties using other languages. Other data items with OCCURS, or subsidiary to OCCURS, will be generated as for ILARRAYPROPERTY(0).
2
As ILARRAYPROPERTY(1), except that non-native array properties will cause the GET and SET accessors to be generated for the property, but not the property itself. This enables Visual Basic programs to access the property (via the accessor methods).

Properties:

Default: ILARRAYPROPERTY(1)

Example:

Consider the following data structures:
data division.
working-storage section.
01 n1 string OCCURS 10 PROPERTY.
01 group1.
    03 n2 PIC X(9) OCCURS 10 PROPERTY.
  • With ILARRAYPROPERTY(0), n1 and n2 are both exposed as properties of type string, with an int parameter to indicate the occurrence required.
  • With ILARRAYPROPERTY(1), n2 is exposed, as above, but n1 is exposed as a property of type string[ ] (in C# notation).
  • With ILARRAYPROPERTY(2), n1 is exposed, as for ILARRAYPROPERTY(1), but for n2, the Compiler will generate accessor methods get_n2(int) (returning string) and set_n2(string, int), but no actual property.
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


ILCLR

Allows a managed program to be compiled for Microsoft's Common Language Runtime (CLR) version 2.0 or 4.0.

Using 2.0 allows the application to be deployed to an environment where only CLR 2.0 is present.

Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-------ILCLR-"number"-----><

Parameters:

number
The version of CLR that can support the compiled program.
2 | Compiles the program for CLR 2.0. Use ILCRL(2) for .NET Framework 3.5 or earlier.
4 | Compiles the program for CLR 4.0. Use ILCLR(4) for .NET Framework 4.

Properties:

Default: | 4
$SET | INITIAL
IDE equivalent: | Click Project > Properties > Application > Target Framework
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILCUTPREFIX

Removes a specified prefix from the names of the COBOL data items in your source code.
Restriction: This directive is supported for managed code only.

Syntax:

>>-.---.-.------ILCUTPREFIX(prefix)--.-------><
   +-/-+ +-NOILCUTPREFIX---------------+

Parameters:

prefix
The prefix used for one or more of the data names in the source code.

Properties:

Default: | NOILCUTPREFIX
Phase: | Syntax check
$SET: | Initial

Example:

A number of the COBOL data items in your code might use a common prefix such as lnk-; for example lnk-name and so on. To make your code more readable, compile with the ILCUTPREFIX(lnk-) directive to remove all lnk- prefixes from your data items. In the compiled code, the data items will appear as name.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


ILDOC

Generates documentation in xml format using comments in the code, and puts the documentation in the specified file.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.--ILDOC--"filename"--.---><
       +-NOILDOC-------------+

Parameters:

filename The name of the file to contain the documentation comments

Properties:

Default: | ILDOC
IDE equivalent: | Click Project > Properties > COBOL > Advanced > XML documentation file, and the type the filename
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILDYNCALL

Specifies that CALL literal statements are resolved at run time rather than being resolved at compile time.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-.----.---ILDYNCALL---------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | NOILDYNCALL
IDE equivalent: | None. You can specify ILDYNCALL as an additional Compiler directive under Project > Properties > COBOL

Comments:

When ILDYNCALL is specified, all calls in the assembly are resolved at run time. This enables you to use an alias for an entry point in a call, using the entry point mapper. However, if you are calling a literal or entry point that is prefixed 'CBL_', that call is statically linked to the run-time system regardless of whether ILDYNCALL is set or not.

If you do not need to map any entry points to aliases or use this directive for incremental builds, we recommend that you turn it off, as it can adversely affect performance.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related concepts
Compiling JVM COBOL
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILEXPONENTIATION

Enables you to optimize exponential arithmetic operations by specifying the calculation method used.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>--.---.--ILEXPONENTIATION-"option"----><
    +-/-+

Parameters:

option
One of:
DECIMAL
Floating point arithmetic is only used when at least one of the operands is floating point. This method is accurate up to 38 significant decimal digits.
FLOAT
Floating point arithmetic is used for exponential arithmetic operations, even when none of the operands are floating point. This method is faster, but is only accurate to 15 significant decimal digits.

Properties:

Default: | ILEXPONENTIATION"DECIMAL"
IDE equivalent | None
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


ILNATIVE

Exposes COBOL 01 level data items as managed primitives where possible.
Restriction: This directive is supported for managed COBOL only.

In general:

  • Any COBOL level-01 data item that is equivalent to a managed COBOL data type is handled internally as that native type, where possible (see COBOL Type Compatibility)
  • Other numeric items will either be handled as native managed types or will be stored within a byte array, according to the setting of the ILOPTIMIZEDATA directive, and according to their usage within the program.
  • If a parameter of a PROCEDURE DIVISION USING or ENTRY … USING statement corresponds to a .NET native type, the parameter is exposed as a data item of that type in the method signature for the entry point.
  • BY REFERENCE parameters that don't correspond to a managed COBOL data type are exposed as internal type-neutral objects representing the byte array/offset pair of the data item.

The compiler usually converts parameters in the calling program to the appropriate type, by examining the target method signature. This signature is available if the method is in the same source module as the calling program or in a module identified by the ILSOURCE directive or in an assembly identified by an ILREF directive.

Where the called program is not known at compile time or not available until run time, the calling program sets up parameter types based on only the data items in the CALL statement. At run time the types of the parameters might not match those in the target method and this causes the .NET CLR or JVM to raise an exception because it can't convert the data. You can avoid this by specifying the NOILNATIVE directive for both the calling and the called program.

Syntax:

>>-.----.---ILNATIVE----------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | ILNATIVE
IDE equivalent: | None. You can specify ILNATIVE as an additional Compiler directive under Project > Properties > COBOL

Comments:

A COBOL data item that is represented as a managed primitive performs significantly better than one that isn't. However, there are some situations where using IL native types is not suitable, such as when the call arguments do not match in dynamic calls, or when your program relies on the DEFAULTBYTE Compiler directive initializing an item that will be exposed as an IL native type.

You can avoid these problems by specifying the NOILNATIVE directive when compiling your program.

Example:

The following programs demonstrate a case for compiling with NOILNATIVE:

cmain.cbl

      01 ws-data pic 9(4) comp-5.
       procedure division.
       call “csub” using ws-data.

csub.cbl

       linkage section.
       01 ls-data.
          03 ls-value pic 9(4) comp-5.

       procedure division using ls-data.
          move 100 to ls-value.
          exit program.

Compile the two programs independently, with the default setting of ILNATIVE, using commands such as:

cobol cmain jvmgen;
cobol csub jvmgen(sub);

When you run the program cmain, an exception is raised at run time due to the different types of the ws-data and ls-data data items.

However, if you specify NOILNATIVE directive for both programs, as follows, both data items will be represented with the same type and so the argument will be successfully passed to the subprogram.

cobol cmain jvmgen noilnative;
cobol csub jvmgen(sub) noilnative;
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
DEFAULTBYTE
ILOPTIMIZEDATA
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILNORMALIZENAMES

Determines the program elements that are normalized when a procedural COBOL program is compiled to managed code. Normalization in this context results in replacing all $ and - (hypen) characters in the name with _ (underscore) characters.

Syntax:

>>-----.--ILNORMALIZENAMES-----------.------------><
       +--ILNORMALIZENAMES"<scope>"--+

Parameters:

<scope>
Determines which program element names are normalized when a procedural COBOL program is compiled to managed code. <scope> can be one of:
MEMBERS
Normalizes the names of the methods representing the entry points to the program. This is the same as specifying the directive with no parameter.
ALL
As MEMBERS, but also normalizes the name of the class representing that program.

Properties:

Default: | ILNORMALIZENAMES
IDE equivalent: | Not applicable
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


ILOBJECTIFY (deprecated)

ILOBJECTIFY is deprecated, and supported for backward compatibility only.
Restriction: This directive is supported for .NET COBOL only.
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILOPTIMIZEDATA

Causes the Compiler to optimize any numeric data item to a native managed type (typically a 32-bit or 64-bit integer) when it determines that it is safe to do so.
Restriction: This directive is supported for managed COBOL only.

It is not safe to optimize, and therefore no optimization is made, when the data item:

  • Is defined as subsidiary to some group item, and that group item is explicitly referenced somewhere in the program.
  • Redefines another item or is itself redefined.
  • Is accessed somewhere in the program using reference modification syntax.
  • Is passed BY REFERENCE to another program.
  • Is moved to or from a group item.

Syntax:

>>-----.-------ILOPTIMIZEDATA---.--------><
       +-----NOILOPTIMIZEDATA---+

Properties:

Default: | ILOPTIMIZEDATA
Phase: | Syntax check
$SET: | Initial

Comments:

Whether or not ILOPTIMIZEDATA is specified, level-01 numeric items with a usage and picture that is equivalent to a native managed type (for example, 4 or 8 byte comp-5 data), and which are not redefined, will be treated as that native managed type. This may apply even if the item is passed by reference to another program, but this depends on the setting of the ILNATIVE directive.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILNATIVE


ILPARAMS

Determines the way in which you call a method that contains an array as its last receiving parameter.

Syntax:

>>------.----ILPARAMS--.---><
        +--NOILPARAMS--+

Parameters:

None.

Properties:

Default: | ILPARAMS
IDE equivalent: | None

Comments:

When set at its default (ILPARAMS), you can specify a list of 0 or more arguments of the array element type instead of a single array argument, for any method that has an array as its last parameter. When NOILPARAMS is set, you can specify a list only when the target method specifies the PARAMS attribute.

Example:

$set ilparams  *> you need this set if params is omitted
 class-id myClass.
 method-id main static.
   declare i as binary-long
   set i to self::Sum(1 2 3 4 5 6 7 8 9 10)
            display i
 end method.

 method-id Sum static.
 procedure division using params opds as binary-long occurs any
                        returning ret as binary-long.
   set ret to 0
   perform varying i as binary-long through opds
     add i to ret
   end-perform
 end method.
 end class.
Note: Instead of the first set statement, the following syntax will work whether or not the target method contains the params keyword: Set i to self::Sum(table of binary-long(1 2 3 4 5 6 7 8 9 10))
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
Procedure Division Header


ILREF

This directive permits the definition of extension methods and extension operators that are outside of the current compilation unit.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-----.---ILREF--"parameter"---.--><
       +-NOILREF----------------+

Parameters:

.class filename
The .class file that contains the required extension methods and extension operators

Properties:

Default: | NOILREF
IDE equivalent: | Add a reference in the References folder of the project
$SET: | Initial

Example:

The following example, run from the command line, loads the class defined within the class2.class file:
Note: The path and extension are not required, as the classpath is used to resolve these details. The name and package of the class defined in class2.class does not need to be the same as the name and directory of the class file, as it does with normal class loading.

On Windows:

cobol class1.cbl jvmgen ilref(class2);

On UNIX:

cob class1.cbl -C jvmgen -C ilref(class2)

Comments:

If the required class is within a .jar file, the .jar file must be on the classpath or specified in the JVMCLASSPATH Compiler directive. For example:

On Windows:

cobol -j class1.cbl jvmclasspath(myclasses.jar) ilref(class2.class);

On UNIX:

cob -j class1.cbl -C jvmclasspath(myclasses.jar -C ilref(class2.class)
Parent topic: Code Generation Directives
Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILSHOWPERFORMOVERLAP

Generates a warning when an overlapping PERFORM range is detected in the program.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>--.---.-.----.-ILSHOWPERFORMOVERLAP---><
    +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | Not set
Phase: | Any
IDE equivalent | None

Example:

In the example below, the PERFORM ranges a thru c, c thru f and f [thru f] overlap each other. By setting ILSHOWPERFORMOVERLAP, two warnings are produced: COBCH1663 to indicate the start of the first affected range and the number of overlapping PERFORM ranges, and COBCH1664 to indicate the start of each range affected.

$set ilshowperformoverlap
 ...
 perform a thru c.
 perform c thru f.
 perform f.
 goback.
                               *> errors are displayed as follows:
 a section.
 display "Running section a.". *> COBCH1663E Overlapping perform range: 3 entries
                               *> COBCH1664E    perform range: a thru c
 b section.
 display "Running section b.".
 c section.                    *> COBCH1664E    perform range: c thru f
 display "Running section c.".
 d section.
 display "Running section d.".
 e section.
 display "Running section e.".
 f section.                    *> COBCH1664E    perform range: f thru f
 display "Running section f.".
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
COBCH1663 Overlapping Perform Range <n> Entries
COBCH1664 Overlapping Perform Start <section name>
COBCH1667 Perform range end before start
COBCH1668 Paragraph procedure-name-1 in perform range contains a GO TO procedure-name2 which causes overlap


ILSMARTLINKAGE

Exposes the linkage section and entry points in procedural COBOL programs to managed code, by creating types.

Syntax:

Restriction: This directive is supported for managed COBOL only.
>>-.---.-.-------ILSMARTLINKAGE---.-------------.--.--------><
   +-/-+ |                        +-"namespace"-+  |
         +-----NOILSMARTLINKAGE--------------------+

Parameters:

namespace
The namespace in which each generated class is grouped

Properties:

Default: | ILSMARTLINKAGE
Phase: | Syntax check
$SET: | Initial
IDE Equivalent: |

Comments:

This directive exposes group linkage items to managed code. In addition to the class generated as usual for the COBOL program, this directive effectively generates one class for every 01 level group item in the linkage section. Each data item in the group is exposed as a property of this class, where the property is of a standard managed type.

COBOL group items are exposed as string properties. If the group contains non-DISPLAY data (e.g. numeric COMP items), it will not be possible to use the property associated with the group to populate these non-DISPLAY items. In this case, these non-DISPLAY items must be populated using the individual properties associated with these non-DISPLAY items. Use of the ILSMARTRESTRICT directive suppresses generation of properties for group items, meaning that properties are only generated for elementary items.

Hyphens are removed from data item names and the letter following a removed hyphen is folded to upper case. For example a data item author-name is renamed to AuthorName. You can also use the ILCUTPREFIX directive to remove initial portions of the name.

If the original, untransformed, COBOL names are duplicates (and can be made unique in COBOL by the use of qualification), then the property name generated is prefixed with a minimal set of qualifying names to make the resulting name unique, for example, in the case of:

01 link-rec.
   03 a1.
      05 b pic x.
   03 b1.
      05 b pic x.

The property names generated for the two elementary items b are a1_b' and a2_b.

However, if the original COBOL names differed, but only by the presence or absence of a'-' character, or by the presence of a prefix removed by the ILCUTPREFIX directive, then an error message is displayed during compilation (COBCH0842). If you receive such a message, modify the item names to ensure that they will be unique following transformation. For instance the following record layout will result in an error:

01 link-rec.
   03 a-b pic x.
   03 ab  pic x.

If a namespace is specified, all classes generated as a result of this directive are grouped under that namespace.

Compiling with ILSMARTLINKAGE generates classes and types that includes an extra method or a property called get_Reference(). If you pass such a class or type as a parameter to a program that receives it “by reference”, you need to use the “by reference” object by specifying the get_Reference() method. This returns an object that encapsulates the SmartLinkage parameter so it is used with a method that is declared "by reference”.

You also need to use get_Reference() with the RunUnit:Call() method – for example:

myRunUnit.Call("myprogram", myByRefParam.get_Reference());

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, ILCUTPREFIX(lnk-b-), ILCUTPREFIX(lnk-), and ILSMARTTRIM:

       program-id. BookLegacy.
                         ...
       linkage section.
       01 lnk-function            pic x.
       01 lnk-b-details.
          03 lnk-b-text-details.
             05 lnk-b-title       pic x(50).
             05 lnk-b-type        pic x(20).
             05 lnk-b-author      pic x(50).
          03 lnk-b-stockno        pic x(4).
          03 lnk-b-retail         pic 99v99.
          03 lnk-b-onhand         pic 9(5).
          03 lnk-b-sold           pic 9(5) comp-3.
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In Java, you can access the data in BookLegacy program in JVM COBOL as follows:

    BookLegacy myBook = new BookLegacy();
       //creates an object corresponding to the BookLegacy program
    Details myDetails = new Details();
       //creates an instance corresponding to the group lnk-bdetails
    . . .
       myDetails.setStockno("6666");
       myDetails.setTitle("Managed COBOL");
       myDetails.setAuthor("Mike Focus");
       myDetails.setType("Reference");
       myDetails.setRetail(new ScaledInteger(155, 5));
       myDetails.setOnhand(20);
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTNEST
ILSMARTRESTRICT
ILSMARTTRIM


ILSMARTNEST

Use in conjunction with ILSMARTLINKAGE, to expose the Linkage Section items and entry points to managed code as nested classes of the program class in which they are defined.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-.---.-.----.-ILSMARTNEST------><
   +-\-+ +-NO-+

Properties:

Default: | NOILSMARTNEST
Phase: | Syntax check
$SET: | Any
IDE Equivalent: |

Comments:

By creating nested classes, programs within the same compilation unit can have linkage records with the same name.

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, ILSMARTNEST, ILCUTPREFIX(lnk-b-) and ILCUTPREFIX(lnk-):

       program-id. BookLegacy.
                         ...
       linkage section.
       01 lnk-function            pic x.
       01 lnk-b-details.
          03 lnk-b-text-details.
             05 lnk-b-title       pic x(50).
             05 lnk-b-type        pic x(20).
             05 lnk-b-author      pic x(50).
          03 lnk-b-stockno        pic x(4).
          03 lnk-b-retail         pic 99v99.
          03 lnk-b-onhand         pic 9(5).
          03 lnk-b-sold           pic 9(5).
       procedure division using by value lnk-function
                                by reference lnk-b-details.

In Java, you can access the data in BookLegacy program in JVM COBOL as follows:

    BookLegacy myBook = new BookLegacy();
       //creates an object corresponding to the BookLegacy program
    BookLegacy.Details myDetails = new BookLegacy.Details();
       //creates an instance corresponding to the group lnk-bdetails
    . . .
       myDetails.setStockno("6666");
       myDetails.setTitle("Managed COBOL");
       myDetails.setAuthor("Mike Focus");
       myDetails.setType("Reference");
       myDetails.setRetail(new ScaledInteger(155, 5));
       myDetails.setOnhand(20);
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTLINKAGE
ILSMARTRESTRICT
ILSMARTTRIM


ILSMARTRESTRICT

Limits the generation of properties in ILSMARTLINKAGE classes to non-redefining elementary items.

Syntax:

Restriction: This directive is supported for managed COBOL only.
>>-.---.---.----.-ILSMARTRESTRICT-------><
   +-/-+   +-NO-+

Properties:

Default: | NOILSMARTRESTRICT
Phase: | Syntax check
$SET: | Initial
IDE equivalent: |

Example:

The following COBOL program is compiled with ILSMARTLINKAGE, ILSMARTRESTRICT, ILCUTPREFIX(lnk-b-) and ILCUTPREFIX(lnk-):

       program-id. BookLegacy.
                         ...
       linkage section.
       01 lnk-function            pic x.
       01 lnk-b-details.
          03 lnk-b-text-details.
             05 lnk-b-title       pic x(50).
             05 lnk-b-type        pic x(20).
             05 lnk-b-author      pic x(50).
       01 lnk-b-reprint-details redefines lnk-b-details.
          03 lnk-b-invisible      pic x(20).

       procedure division using by value lnk-function
                                by reference lnk-b-details.

In Java, you can access the data in BookLegacy program in JVM COBOL as follows:

    BookLegacy myBook = new BookLegacy();
       //creates an object corresponding to the BookLegacy program
    Details myDetails = new Details();
       //creates an instance corresponding to the group lnk-b-details
    . . .
       myDetails.setTitle("Great Expectations");

Without ILSMARTRESTRICT set, you can also access other properties, such as group items and redefining elementary items:

...
myDetails.setDetails("Great Expectations     Novel       Dickens");
myDetails.setInvisible("can't see this");
...
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTNEST
ILSMARTLINKAGE
ILSMARTTRIM


ILSMARTSERIAL

Use in conjunction with ILSMARTLINKAGE. Makes the classes generated with ILSMARTLINKAGE serializable.

Syntax:

Restriction: This directive is supported for managed COBOL only.
>>-.---.-.-------ILSMARTSERIAL---.-------------.--.--------><
         +-----NOILSMARTSERIAL--------------------+

Properties:

Default: | NOILSMARTSERIAL
Phase: | Syntax check
$SET: | Initial
IDE Equivalent: |
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


ILSMARTTRIM

This directive works in conjunction with ILSMARTLINKAGE, where it trims any trailing spaces from a string item returned by the get property associated with an alphanumeric item processed by ILSMARTLINKAGE.

Syntax:

>>-.----.---ILSMARTTRIM----------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | NOILSMARTTRIM
IDE equivalent: | None. You can specify ILSMARTTRIM as an additional Compiler directive under Project > Properties > COBOL

Comments:

This directive has no effect on items that are not processed by the ILSMARTLINKAGE directive.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILSMARTNEST
ILSMARTLINKAGE
ILSMARTRESTRICT


ILSTATIC

Exposes the entry points of a COBOL program as static methods for compatibility with previous releases.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-.----.---ILSTATIC----------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | NOILSTATIC
IDE equivalent: | None. You can specify ILSTATIC as an additional Compiler directive under Project > Properties > COBOL

Comments:

When NOILSTATIC is specified, the compiled program is represented as a class with instance methods and instance data. The run-time system maintains a singleton instance of the program in a run unit. A program written in a non-COBOL .NET language can fetch this instance using the CobLoad method in the Interop class of the MicroFocus.COBOL.RuntimeServices assembly and can then invoke methods on the instance directly.

When ILSTATIC is specified, the compiled program is represented as a class with static methods and static data. A program written in a non-COBOL .NET language can call COBOL by invoking the static methods directly. ILSTATIC provides compatibility with a previous release of this product, and should be used only on COBOL programs that are called using static method calls from an existing program written in a non-COBOL .NET language.

Parent topic: Code Generation Directives
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILTARGET

Enables an application to target a specified CPU type.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILTARGET--"CPU-type"--.---><
       +-NOILTARGET--------------+

Parameters:

CPU-type
Indicates the type of CPU and can be:
  • ANYCPU
  • Itanium
  • X64
  • X86

Properties:

Default: | ILTARGET"ANYCPU"
IDE equivalent: | Click Project > Properties > COBOL > Platform Target
$SET: | Initial

Comments:

The main uses of this directive are for performance and for integrating with components that use native platform invokes to access unmanaged code.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILVERIFY

Ensures that the compiled IL code is verifiable.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILVERIFY--"check"---.--><
       +-NOILVERIFY------------+

Parameters:

check
Indicates that the resultant assembly is to be checked as verifiable, by running the Microsoft tool PEVERIFY.

Properties:

Default: | NOILVERIFY
IDE equivalent: | Click Project > Properties > COBOL > Generate Verifiable Code

Comments:

When NOILVERIFY is specified, the IL code produced by the Compiler is not guaranteed to be verifiable. Non-verifiable code is produced for certain COBOL statements where significant performance benefits can be gained by doing so. In particular, this covers some statements involving non-01 level COMP-5 data items, alphanumeric moves, and the setting and use of COBOL POINTERs.

When ILVERIFY is specified, the IL code produced by the Compiler is verifiable. If the “check” option is also specified, the Microsoft tool PEVERIFY.EXE is automatically run on the resultant assembly to confirm the code is verifiable.

If PEVERIFY.EXE is not installed, a COBCH1585 Could not find peverify.exe, required for ILVERIFY(CHECK) error is produced. You can download and install this tool as part of the .NET Framework Tools package.

Verifiable code is a requirement for certain kinds of .NET applications, such as SQL stored procedures.

Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


JVMDECIMAL

Determines the type in which certain items are exposed. This directive affects COBOL data items of type 'decimal' and non-integral numeric items exposed as a result of either ILSMARTLINKAGE usage or the PROPERTY keyword.
Restriction: This directive is supported for JVM COBOL only.

Syntax:

>>-.---.---JVMDECIMAL"-type-"---><
   +-/-+

Parameters:

type
The type in which affected items are exposed. Can be one of:
BIGDECIMAL
Numerics are exposed as java.math.BigDecimal.
SCALEDINTEGER
Numerics are exposed as com.microfocus.cobol.program.ScaledInteger.

Properties:

Default: | JVMDECIMAL"BIGDECIMAL"
Phase: | Syntax check
$SET: | Initial
Parent topic: Code Generation Directives
Parent topic: Compiler Directives - Alphabetical List


Reference, Resource and Namespace Directives

  • ILICON
    Adds the specified icon to the output program.
  • ILNATIVERESOURCE
    The resource file you specify will be included in the resulting output file.
  • ILPINVOKE
    Makes the specified unmanaged code available, so that the entry points in the unmanaged code are available to the program being compiled.
  • ILREF
    This directive permits the definition of extension methods and extension operators that are outside of the current compilation unit.
  • ILRESOURCE
    Specifies a resource file to embed in the assembly file when it is culture neutral.
  • ILSOURCE
    Specifies an additional COBOL source file to be compiled together with the current program into a single .NET assembly or Java class file.
  • ILSTACKSIZE
    Sets the size of the stack when the program is run.
  • ILUSING
    Specifies the namespace for a class to be imported. This directive enables you to write just the class name in the program code, without its namespace, potentially making the code shorter and simpler.
  • JVMCLASSPATH
    Adds directories to the CLASSPATH, enabling classes located within those directories to be utilized.
  • JVMTARGET
    Specifies the JVM version number targeted by the class files generated in this compilation unit. The resulting class files can be run on any JVM version greater than or equal to the specified number.
Parent topic: Managed COBOL Command Line Compiler Directives


ILICON

Adds the specified icon to the output program.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILICON---"icon-filename"--.---><
       +-NOILICON--------------------+

Parameters:

icon filename
Name of the icon file with the extension .ico.

Properties:

Default: | NOILICON
IDE equivalent: | Click Project > Properties > Resources > Add Resource, and then either select an existing file or create a new icon.

Comments:

The icon represents the output file in Windows Explorer.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILNATIVERESOURCE

The resource file you specify will be included in the resulting output file.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILNATIVERESOURCE---"resource-file"----.--><
       +-NOILNATIVERESOURCE----------------------+

Parameters:

resource-file Name of the native resource file, with file extension .res, to be used as part of the compilation process.

Properties:

Default | NOILNATIVERESOURCE
IDE equivalent | Click Project > Properties > Application > Resource File and enter the name of the resource file.

Comments:

You can specify only one resource file.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILPINVOKE

Makes the specified unmanaged code available, so that the entry points in the unmanaged code are available to the program being compiled.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>------.----ILPINVOKE--"unmanaged-dll"--.---><
        +--NOILPINVOKE-------------------+

Parameters:

unmanaged-dll
The name of the .dll containing the unmanaged code that is required

Properties:

Default: | NOILPINVOKE
IDE equivalent: | Add a reference to the unmanaged .dll to the References folder of the solution
$SET: | Initial
Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILREF
Key to Compiler Directives


ILRESOURCE

Specifies a resource file to embed in the assembly file when it is culture neutral.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILRESOURCE--"resource-file"---.--><
       +-NOILRESOURCE-------------------+

Parameters:

resource-file
The filename of the resource file to embed in the assembly

Properties:

Default: | NOILRESOURCE
IDE equivalent: | Add a reference to the resources file in the References folder of the solution

Comments:

You can use resource files in culture neutral assemblies to contain such data as graphics (icons and cursors) or text strings.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
ILREF
Key to Compiler Directives


ILSOURCE

Specifies an additional COBOL source file to be compiled together with the current program into a single .NET assembly or Java class file.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-----.---ILSOURCE---"cobolsourcefile"---.--><
       +-NOILSOURCE-----------------------+

Parameters:

cobolsourcefile
The filename of the additional COBOL source file to be compiled

Properties:

Default: | NOILSOURCE
IDE equivalent: | Add the additional source file to the project

Comments:

Each program specified in an ILSOURCE directive is treated as a separate COBOL program, but the compilation results in a single .exe or .dll file.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILNAMESPACE
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILSTACKSIZE

Sets the size of the stack when the program is run.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>----.---ILSTACKSIZE"size"---.------><
      +-NOILSTACKSIZE---------+

Parameters:

size
The size, in bytes, allocated to the stack.

Properties:

Default: | NOILSTACKSIZE
IDE equivalent: | None

Comments:

If no size is set using this directive, the default stack size under the .NET framework is 1MB.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILUSING

Specifies the namespace for a class to be imported. This directive enables you to write just the class name in the program code, without its namespace, potentially making the code shorter and simpler.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>---.---ILUSING---"namespace"--.---><
     +-NOILUSING----------------+

Parameters:

namespace
The name of a namespace to be imported into the program.

Properties:

Default: | NOILUSING. The command line default is NOILUSING . Note: Specifying NOILUSING clears any settings that are in effect as a result of previous ILUSING directives.
IDE equivalent: | Click Project > Properties > Micro Focus > Build Configuration and add the directive in the Additional Directives sections of the options within it.
$SET: | Initial.

Examples:

When referring to a class whose name begins with the specified namespace (or one of the specified namespaces if there are multiple ILUSING directives), the namespace may be omitted. For example:

01 d1 type java.util.Date.

Is equivalent to:

$set ilusing"java.util"
01 d1 type Date.

Note that the complete namespace must be specified in an ILUSING directive for it to be effective.

For example:

$set ilusing"java"
01 f1 type java.util.date. 		   *> this is OK
01 f2 type util.date.			   *> this does not work

However, this does work:

$set ilusing"java.util"
01 f3 type date.
Note: This has the same effect as the import java.util.* statement in Java.

Comments:

You can add this directive more than once, to add multiple namespaces to your programs.

If you set the directive in a file, using the $set command, the imported namespace is only applicable to programs, classes and referenced copybooks in that file. If you set the directive through the IDE or from the command line, the imported namespace is applicable to all programs and classes in the project or specified on the command line.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List


JVMCLASSPATH

Adds directories to the CLASSPATH, enabling classes located within those directories to be utilized.
Restriction: This directive is supported for JVM COBOL only.
>>---JVMCLASSPATH-"directory"--------><

Parameters

directory
The name of a directory containing classes referenced in the source code. If you specify a relative directory path, it is relative to the working directory.

Properties

Default: | None
IDE equivalent: | Project properties > Micro Focus > JVM Build Path > Libraries > Add (External) Class Folder.
$set | Initial

Examples

The following examples enable a.cbl to utilize any classes found in the myclasses directory:

cob a.cbl -C list -C jvmgen -C "jvmclasspath(myclasses)"

Comments

This directive can be used as an alternative to altering the CLASSPATH environment variable.

Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List


JVMTARGET

Specifies the JVM version number targeted by the class files generated in this compilation unit. The resulting class files can be run on any JVM version greater than or equal to the specified number.
Restriction: This directive is supported for JVM COBOL only.

Syntax:

>>-.---.---JVMTARGET"-integer-"---><
   +-/-+

Parameters:

integer
The Java version number of the JVM being targeted in the compilation unit; for example, JVMTARGET"9" targets JVM version 9. (Current permissible range is 5-10.)

Properties:

Default: | JVMTARGET"7"
Phase: | Syntax check
$SET: | Initial
Parent topic: Reference, Resource and Namespace Directives
Parent topic: Compiler Directives - Alphabetical List


Strong Naming Directives

  • ILDELAYSIGN
    Indicates whether to reserve space in the assembly for the strong name signature, or to defer the actual signing until later.
  • ILKEYFILE
    Specifies a key file, which contains a key or public/private key pair for strong naming an assembly.
  • ILKEYNAME
    Specifies the container of a key or key pair that has been installed in the Crypto Service Provider (CSP).
Parent topic: Managed COBOL Command Line Compiler Directives


ILDELAYSIGN

Indicates whether to reserve space in the assembly for the strong name signature, or to defer the actual signing until later.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-.----.--ILDELAYSIGN--------><
   +-NO-+

Parameters:

None

Properties:

Default: | NOILDELAYSIGN
IDE equivalent: | Click Project > Properties > Application > Assembly Information and check Delay Sign
Assembly manifest attribute: | System.Reflection.AssemblyDelaySign

Comments:

When signing is delayed, only the public key is set.

You can specify the keys for signing the assembly using the ILKEYFILE or ILKEYNAME directive.

Parent topic: Strong Naming Directives
Parent topic: Compiler Directives - Alphabetical List


ILKEYFILE

Specifies a key file, which contains a key or public/private key pair for strong naming an assembly.

Syntax:

Restriction: This directive is supported for .NET COBOL only.
>>-----.---ILKEYFILE--"keyfile"--.---><
       +-NOILKEYFILE-------------+

Parameters:

keyfile
The name of the key file

Properties:

Default: | NOILKEYFILE
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Key File
Assembly manifest attribute: | System.Reflection.AssemblyKeyFile

Comments:

The Compiler sets the public key in the assembly manifest and signs the final assembly with the private key.

To generate the key file, use the .NET sn.exe utility.

You can alternatively specify the keys using the ILKEYNAME directive. You can also partially sign the assembly using the ILDELAYSIGN directive.

Parent topic: Strong Naming Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILKEYNAME

Specifies the container of a key or key pair that has been installed in the Crypto Service Provider (CSP).
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>------.---ILKEYNAME--"keycontainer"--.---><
        +-NOILKEYNAME------------------+

Parameters:

keycontainer
The name of the container that contains the key

Properties:

Default: | NOILKEYNAME
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Key Name
Assembly manifest attribute | System.Reflection.AssemblyKeyName

Comments:

The key or key pair in the key container is used for strong naming an assembly. The Compiler sets the public key in the assembly manifest and signs the final assembly with the private key.

You can alternatively specify the keys using the ILKEYFILE directive. You can also partially sign the assembly using the ILDELAYSIGN directive.

Parent topic: Strong Naming Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


Identity, Information and Manifest Directives

  • ILCOMPANY
    Defines the company name custom attribute in the assembly manifest.
  • ILCOPYRIGHT
    Defines the copyright custom attribute in the assembly manifest.
  • ILCULTURE
    Defines the culture custom attribute in the assembly manifest.
  • ILDESCRIPTION
    Defines the description attribute in the assembly manifest.
  • ILFILEVERSION
    Instructs the compiler to use a specific version number for the Win32 file version.
  • ILMANIFEST
    Selects a manifest generation option when the application runs on Windows Vista under User Account Control (UAC).
  • ILPRODUCT
    Defines the product name custom attribute in the assembly manifest.
  • ILPRODUCTVERSION
    Instructs the compiler to use a specific version number for the Win32 product file version.
  • ILTITLE
    Defines the title custom attribute in the assembly manifest.
  • ILTRADEMARK
    Defines the trademark custom attribute in the assembly manifest.
  • ILVERSION
    Specifies the version of the assembly.
Parent topic: Managed COBOL Command Line Compiler Directives


ILCOMPANY

Defines the company name custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>------.---ILCOMPANY--"companyname"--.---><
        +-NOILCOMPANY-----------------+

Parameters:

companyname The name of your company for the assembly

Properties:

Default: | NOILCOMPANY
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Company
Assembly manifest attribute: | System.Reflection.AssemblyCompany
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILCOPYRIGHT

Defines the copyright custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.-----ILCOPYRIGHT--"copyright"--.---><
       +---NOILCOPYRIGHT---------------+

Parameters:

copyright The copyright statement for the assembly

Properties:

Default: | NOILCOPYRIGHT
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Copyright
Assembly manifest attribute: | System.Reflection.AssemblyCopyright
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List


ILCULTURE

Defines the culture custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.----ILCULTURE--"culture"--.---><
       +--NOILCULTURE-------------+

Parameters:

culture The culture statement for the assembly

Properties:

Default: | NOILCULTURE
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Culture
Assembly manifest attribute: | System.Reflection.AssemblyCulture
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List


ILDESCRIPTION

Defines the description attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILDESCRIPTION--"descriptiontext"--.---><
       +-NOILDESCRIPTION---------------------+

Parameters:

descriptiontext The text of the description for the assembly

Properties:

Default: | NOILDESCRIPTION
IDE equivalent: | Click Project > Properties > Application > Assembly Information and under Assembly Manifest Attributes, fill in Description
Assembly manifest attribute: | System.Reflection.AssemblyDescription
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List


ILFILEVERSION

Instructs the compiler to use a specific version number for the Win32 file version.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILFILEVERSION---"version"--.---><
       +-NOILFILEVERSION--------------+

Parameters:

version
The version number to be assigned to the output file.

Properties:

Default | NOILFILEVERSION
IDE equivalent | Click Project > Properties > Application > Assembly Information and fill in the File Version.

Comments:

The version number should be expressed as four integers separated by . (periods). For example:

 2.0.0.0.

This directive instructs the compiler to use a specific version number for the Win32 file version. The file version is not required to be the same as the assembly version number, which is set by the ILVERSION directive.

This directive also has the effect of setting up the assembly attribute System.Reflection.AssemblyFileVersionAttribute with the given value.

Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives
ILVERSION


ILMANIFEST

Selects a manifest generation option when the application runs on Windows Vista under User Account Control (UAC).
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.--ILMANIFEST--"filename"--.---><
       +-NOILMANIFEST-------------+

Parameters:

filename
The name of a manifest file with extension .manifest.

Properties:

Default: | ILMANIFEST
IDE equivalent: | Click Project > Properties >Application and under Resources, select the Manifest.

Comments:

The default option is to use ILMANIFEST without a file name to support the typical manner in which an application operates on Windows Vista. This will embed security information in the application’s executable file, specifying that requestedExecutionLevel be AsInvoker.

Use NOILMANIFEST for compatibility with earlier applications. Use ILMANFEST”filename” if you want to specify your own application manifest.

Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILPRODUCT

Defines the product name custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILPRODUCT--"product-text"--.---><
       +-NOILPRODUCT------------------+

Parameters:

producttext
The name of the product

Properties:

Default: | NOILPRODUCT
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Product
Assembly manifest attribute: | System.Reflection.AssemblyProduct
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILPRODUCTVERSION

Instructs the compiler to use a specific version number for the Win32 product file version.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILPRODUCTVERSION---"version"--.---><
       +-NOILPRODUCTVERSION--------------+

Parameters:

version
The product version number to be assigned to the output file.

Properties:

Default | NOILPRODUCTVERSION
IDE equivalent | None

Comments:

The version number should be expressed as four integers separated by .(periods). For example:

 2.0.0.0.

If ILPRODUCTVERSION is not specified, the product file version will be the same as the file version (see ILFILEVERSION directive).

This directive has the effect of setting up the assembly attribute System.Reflection.InformationalVersionAttribute with the given value.

This directive also has the effect of:

  1. setting the product file version string
  2. setting the binary product file version
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILTITLE

Defines the title custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-.----.----ILTITLE--"titletext"--.---><
        +--NOILTITLE---------------+

Parameters:

titletext
The title of the assembly

Properties:

Default: | NOILTITLE
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Title
Assembly manifest attribute: | System.Reflection.AssemblyTitle
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILTRADEMARK

Defines the trademark custom attribute in the assembly manifest.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILTRADEMARK--"trademarktext"---.--><
       +-NOILTRADEMARK--------------------+

Parameters:

trademarktext
Text of the trademark information for the assembly.

Properties:

Default: | NOILTRADEMARK
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Trademark
Assembly manifest attribute: | System.Reflection.AssemblyTrademark
Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


ILVERSION

Specifies the version of the assembly.
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.---ILVERSION--"version"---.--><
       +-NOILVERSION--------------+

Parameters:

version
The version of the assembly.

Properties:

Default: | NOILVERSION
IDE equivalent: | Click Project > Properties > Application > Assembly Information and fill in Assembly Version

Comments:

The version numbers should be expressed as four integers separated by . (periods) for example:

2.0.0.0

You can use wildcards for the third and fourth component of the version number.

Parent topic: Identity, Information and Manifest Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


Object Code, Size, and Optimization

These directives change the object code produced without changing the logic of your program.

  • Object Code - External Handlers
  • Object Code - File Handling
  • Object Code - Interprogram Communication
  • Object Code - Size and Speed
Parent topic: Compiler Directives


Object Code - External Handlers

  • CALLFH
    Makes the Compiler generate direct calls for all file I/O operations, using the Callable File Handler interface.
  • CALLSORT
    Defines the program to be called to handle all SORT and MERGE operations.
Parent topic: Object Code, Size, and Optimization


Object Code - File Handling

  • WRITETHROUGH, WRITETHRU
    Specifies that disk writes are not to be buffered.
Parent topic: Object Code, Size, and Optimization


Object Code - Interprogram Communication

  • LITLINK
    Makes the Compiler declare the literals in CALL literal statements as public symbols, so they are resolved at link time rather than run time. (Calls generated in this way are referred to as litlinked.)
  • LITVAL-SIZE
    Specifies the number of bytes to pass if the SIZE clause is omitted when passing numeric literals BY VALUE.
  • RTNCODE-SIZE
    Specifies the size of the RETURN-CODE special register and its alignment in memory.
  • PPLITLINK
    Makes the Compiler declare literals as public symbols, in a SET statement using a data item defined as USAGE IS PROCEDURE-POINTER. This means literals are resolved at link time rather than run time. (Symbol references defined in this way are referred to as litlinked.)
Parent topic: Object Code, Size, and Optimization


LITLINK

Makes the Compiler declare the literals in CALL literal statements as public symbols, so they are resolved at link time rather than run time. (Calls generated in this way are referred to as litlinked.)
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.-----LITLINK-.-----------.-.-----><
   +-/-+ |             +-"integer"-+ |
         +-NOLITLINK-----------------+

Parameters:

integer
Must be 1 or 2.
1
All CALL literal statements generate litlinked calls, regardless of the inclusion of underscores at the start of the literal.
Note: Specifying LITLINK without a parameters has the same effect as LITLINK"1".
2
If the name in a CALL literal statement starts with a single underscore - "_name" - a litlinked call to entry-name _name is generated. If it starts with a double underscore - "__name", a litlinked call to entry-name name is generated. (That is the entry-names are declared as public symbols.)

Properties:

Default: | LITLINK for .o files
Phase: | Generate
$SET: | Initial

Comments:

This directive only affects object code files.

With NOLITLINK, no CALL literal statements generate litlinked calls, regardless of the inclusion of underscores at the start of the literal.

LITLINK"2" is only intended to provide backward compatibility with code written for the 16-bit COBOL system. You should use call-convention 8 for new programs.

Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List


LITVAL-SIZE

Specifies the number of bytes to pass if the SIZE clause is omitted when passing numeric literals BY VALUE.

Syntax:

>>-.---.--LITVAL-SIZE--"integer"-----------><
   +-/-+

Parameters:

integer A number up to 4. The number of bytes to pass.

Properties:

Default: | LITVAL-SIZE"4"
Phase: | Syntax check
$SET: | Any
Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List
Related information
Object Code - Interprogram Communication
The Object-Computer Paragraph
File Description Entry Skeleton
The RECORD Clause
Screen Section Entry Skeleton
The SIZE Clause
The ACCEPT Statement
The ADD Statement
The CALL Statement
The CHAIN Statement
The COMPUTE Statement
The DISPLAY Statement
The DIVIDE Statement
The ENTRY Statement
The INVOKE Statement
The MULTIPLY Statement
The SET Statement
The START Statement
The STOP Statement
The STRING Statement
The SUBTRACT Statement
The COPY Statement
The REPLACE Statement
Data Description Entry Skeleton
The EXTERNAL Clause
The OCCURS Clause
The PROCEDURE DIVISION Header
The EXAMINE Statement
The INITIALIZE Statement
The INSPECT Statement
The PERFORM Statement
The UNSTRING Statement
XML Syntax - IDENTIFIED BY Clause
The VALUE Clause
The VALUE OF Clause
The VALUE Clause in the Screen Section
The VALUE Clause (Report Writer)
Key to Compiler Directives


RTNCODE-SIZE

Specifies the size of the RETURN-CODE special register and its alignment in memory.

Syntax:

>>-.---.--RTNCODE-SIZE--"integer"----------><
   +-/-+

Parameters:

integer
One of:
2
PIC S9(4) COMP: size 2 bytes, aligned on a two-byte boundary.
4
PIC S9(9) COMP: size 4 bytes, aligned on a four-byte boundary.
8
PIC S9(18) COMP: size 8 bytes, aligned on an eight-byte boundary.

Properties:

Default: | RTNCODE-SIZE"4"
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to RTNCODE-SIZE"4" immediately by XOPEN.

Set to RTNCODE-SIZE"8" immediately by P64.

If a program calls a program with a smaller RETURN-CODE set, on return the value from the called program is in the lower bytes of the RETURN-CODE, with the other bytes undefined. For example, if a program with a 4-byte RETURN-CODE calls a program with a 2-byte RETURN-CODE, the lower two bytes of the 8-byte RETURN-CODE are set, while the content of the other bytes is undefined.

If a program calls a program with a larger RETURN-CODE set, on return the lower bytes of the value from the called program are in the RETURN-CODE, with the content of the upper bytes lost. For example, if a program with a 4-byte RETURN-CODE calls a program with an 8-byte RETURN-CODE, the lower four bytes of the 8-byte RETURN-CODE are set, while the content of the other bytes is lost.

Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List


PPLITLINK

Makes the Compiler declare literals as public symbols, in a SET statement using a data item defined as USAGE IS PROCEDURE-POINTER. This means literals are resolved at link time rather than run time. (Symbol references defined in this way are referred to as litlinked.)
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.------PPLITLINK-------.-----><
   +-/-+ +-----NOPPLITLINK------+

Parameters:

None.

Properties:

Default: | Current PPLITLINK setting
Phase: | Generate
$SET: | Initial

Comments:

This directive only affects object code files.

With NOPPLITLINK, literals are not declared as public symbols for SET statements that use a data item defined as USAGE IS PROCEDURE-POINTER.

Parent topic: Object Code - Interprogram Communication
Parent topic: Compiler Directives - Alphabetical List


Object Code - Size and Speed

  • CHECK
    Turns on all run-time checks in generated code.
  • FASTCALL
    Controls the behavior of a called program. If FASTCALL is specified, the program does not set up information to allow it to determine whether it is a main program. The program always assumes that it is not a main program, and EXIT PROGRAM will always cause an exit to the calling program.
  • FASTINIT
    Turns on fast INITIALIZE of tables. FASTINIT renders as undefined any table contents that a normal INITIALIZE statement would not change.
  • FIXOPT
    Changes the way in which generated code accesses the Data Division in object (.obj) code.
  • LINKCHECK
    Specifies that each time a Linkage Section item is referenced a check is to be made that it exists.
  • LNKALIGN
    Indicates that level-01 and level-77 Linkage Section items are always aligned on a machine-dependent favorable boundary.
  • OPT (Intel x86 platforms)
    Specifies the level of optimization of the code produced by the compiler.
  • OPT (Non-Intel x86 platforms)
    Specifies the level of optimization of the code produced in the object code file. Use this version of the OPT directive on operating systems that use chips other than the Intel x86 chip, for example, AIX, Solaris Sparc, HP-UX, IA64 (this list is not exhaustive).
  • PARAMCOUNTCHECK
    Enables the program to be called with fewer parameters than are specified in the relevant entry point's USING clause.
  • RECURSECHECK
    Turns on checking for recursion in generated code.
  • SCHEDULER
    Controls the invocation of the Intel COBOL Optimizer.
  • SEG
    Turns on COBOL segmentation.
Parent topic: Object Code, Size, and Optimization


CHECK

Turns on all run-time checks in generated code.
Note: This directive is supported for native COBOL only.

Syntax:

>>--.----.---CHECK------------------><
    +-NO-+

Parameters:

None

Properties:

Default: | None
Phase: | Generator
$SET: | Initial

Dependencies:

CHECK sets BOUND, LINKCHECK, PARAMCOUNTCHECK and RECURSECHECK immediately. NOCHECK sets NOBOUND, NOLINKCHECK, NOPARAMCOUNTCHECK and NORECURSECHECK immediately.

Comments:

CHECK turns on all run-time checks in generated code. The run-time checks include checks for:

  • Divide-by-zero
  • Calling invalid (that is NULL) procedure-pointers
  • Recursion of non-recursive programs

NOCHECK turns off all run-time checks in generated code.

Parent topic: Object Code - Size and Speed
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


FASTINIT

Turns on fast INITIALIZE of tables. FASTINIT renders as undefined any table contents that a normal INITIALIZE statement would not change.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--FASTINIT------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | FASTINIT
Phase: | Check
$SET: | Initial
Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
INITIALIZE Statement


LINKCHECK

Specifies that each time a Linkage Section item is referenced a check is to be made that it exists.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--LINKCHECK-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOLINKCHECK
Phase: | Generate
$SET: | Initial

Dependencies:

Set to LINKCHECK by CHECK.

Comments:

If you set this directive, then for any reference to a Linkage Section item that does not exist a run-time error 203 (CALL parameter not supplied) is generated.

Parent topic: Object Code - Size and Speed
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


LNKALIGN

Indicates that level-01 and level-77 Linkage Section items are always aligned on a machine-dependent favorable boundary.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--LNKALIGN------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOLNKALIGN
Phase: | Generate
$SET: | No

Comments:

Using LNKALIGN can reduce the time needed to access a linkage item at run time. However, take care when using it. You must use the correct ALIGN directive setting when compiling your program. No checks are made to ensure that the items are aligned.

The results of using this directive are machine-dependent, and you should not use it if you are in any doubt as to its effect. Unpredictable results might occur if you pass linkage items that are not aligned.

Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List


OPT (Intel x86 platforms)

Specifies the level of optimization of the code produced by the compiler.
Note: This directive is supported for native COBOL only.

Use this version of the OPT directive on operating systems that use the Intel x86 chip, for example, Solaris Intel and Unix Ware (this list is not exhaustive).

Syntax:

>>-.---.--OPT--"integer"-------------------><
   +-/-+

Parameters:

integer
The level of optimization; one of:
1
Minimal optimization.
2
Default optimization.
3
Additional optimization - particularly of STRING, UNSTRING and INSPECT. This option increases the time taken to generate a program in comparison to the default optimization.
4
Optimized as for option 3, but in addition the code is scheduled. This option increases the time taken to generate a program in comparison to option 3.

Properties:

Default: | OPT"2"
Phase: | Generate
$SET: | Any

Dependencies:

If no other OPT level is specified, set to OPT"1" at end by ANIM.

Comments:

OPT is the equivalent of OPT"3".

Debugging code compiled with an OPT level greater than 1 can be difficult, as compiler optimizations reorganize instructions derived from your source in such a way that, for example, Step might appear to jump statements or execute statements out of order, and Query and Modify might not work as expected.

Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List
Related information
ANIM
Object Code - Size and Speed
Key to Compiler Directives


OPT (Non-Intel x86 platforms)

Specifies the level of optimization of the code produced in the object code file. Use this version of the OPT directive on operating systems that use chips other than the Intel x86 chip, for example, AIX, Solaris Sparc, HP-UX, IA64 (this list is not exhaustive).

Syntax:

>>-.---.--OPT--"integer"-------------------><
   +-/-+

Parameters:

integer
The level of optimization; one of:
1 | Minimal optimization.
2 | Default optimization.
3 | Additional optimization - particularly of STRING, UNSTRING and INSPECT. This option increases the time taken to generate a program in comparison to the default optimization.

Properties:

Default: | OPT"2"
Phase: | Generate
$SET: | Any

Dependencies:

Set to OPT"1" at end by ANIM.

Comments:

OPT"3" provides global optimisation; this means that the entire program is examined as a whole during optimisation, rather than successive small portions of it.

Compiling with OPT"3" can take considerably longer than with OPT"2".

If you request optimization of a large program, compilation might fail because there is insufficient memory. If this happens, repeat the compilation with OPT"2" specified.

OPT is the equivalent of OPT"3".

Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List
Related information
ANIM
Object Code - Size and Speed
Key to Compiler Directives


PARAMCOUNTCHECK

Enables the program to be called with fewer parameters than are specified in the relevant entry point's USING clause.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--PARAMCOUNTCHECK-----------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | PARAMCOUNTCHECK
Phase: | Generate
$SET: | Initial

Dependencies:

DIALECT"RM" sets PARAMCOUNTCHECK immediately.

Comments:

You must use this directive if any of the following apply:

  • The program is called with a variable number of parameters.
  • The program contains a Linkage Section, and is to be used both as a main program run from the command line and as a subprogram called from another program.
  • The program is compiled with STICKY-LINKAGE"2" specified.

Otherwise the program can be compiled with NOPARAMCOUNTCHECK for efficiency. A program to be called from a language other than COBOL must be compiled with NOPARAMCOUNTCHECK.

Parent topic: Object Code - Size and Speed
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
LINKCHECK
STICKY-LINKAGE
Run-time Behavior - Speed or Size
The ENTRY Statement
The SET Statement
ENTRY Statement Restrictions
The INVOKE Statement
The PROCEDURE DIVISION Header
The MERGE Statement
The SORT Statement
The USE Statement
The XML PARSE Statement
The CALL Statement
The CHAIN Statement
General Description
Linkage Section


RECURSECHECK

Turns on checking for recursion in generated code.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--RECURSECHECK------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | See Comments.
Phase: | Generate
$SET: | Initial

Comments:

Programs that are compiled reentrant, or are marked recursive by having a local-storage section, always set NORECURSECHECK. Otherwise, unless explicitly set by [NO]CHECK or [NO]RECURSECHECK, this directive defaults to RECURSECHECK for programs generated for debug, and NORECURSECHECK otherwise.

When this directive is turned on, recursion will generate a COBRT166 Recursive COBOL CALL is illegal error at run-time.

Parent topic: Object Code - Size and Speed
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


SCHEDULER

Controls the invocation of the Intel COBOL Optimizer.
Restriction:

This directive is supported for native COBOL only.

This directive is supported for 32-bit x86 platforms only.

Syntax:

>>-.---.-.----.--SCHEDULER-----------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOSCHEDULER
Phase: | Generate
$SET: | Initial

Dependencies:

Set to NOSCHEDULER immediately by ANIM.

Comments:

This directive controls the invocation of the Intel COBOL Optimizer (Copyright Intel 1994-1996) which applies further optimizations to the generated code produced by the Micro Focus compiler. Use this directive if you want to further improve the performance of your applications.

The use of the SCHEDULER directive produces code that cannot be debugged using the debugger. As a result, selecting the ANIM directive during code generation results in SCHEDULER being switched off.

Parent topic: Object Code - Size and Speed
Parent topic: Compiler Directives - Alphabetical List


Report Writer

This directive affects the way the Report Writer control module behaves:

  • REPORT-LINE
    Specifies the maximum length of a Report Writer line.
  • RWHARDPAGE
    Causes the Report Writer control module to execute a form feed after the last item has been printed on a page, instead of the usual multiple blank lines. This ensures that the paper is positioned correctly ready for a new page.
Parent topic: Compiler Directives


REPORT-LINE

Specifies the maximum length of a Report Writer line.

Syntax:

>>-.---.-.-----REPORT-LINE--"integer"-.----><
   +-/-+ +-NO--REPORT-LINE------------+

Parameters:

integer The maximum length, in characters.

Properties:

Default: | REPORT-LINE"256"
Phase: | Syntax check
$SET: | Initial
Parent topic: Report Writer
Parent topic: Compiler Directives - Alphabetical List


RWHARDPAGE

Causes the Report Writer control module to execute a form feed after the last item has been printed on a page, instead of the usual multiple blank lines. This ensures that the paper is positioned correctly ready for a new page.

Syntax:

>>-.---.-.----.--RWHARDPAGE-----------------><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NORWHARDPAGE
Phase: | Syntax check
$SET: | Initial

Comments:

If you use the CODE IS clause with this directive, the 2-character code does not extend all the way to the end of the page.

Parent topic: Report Writer
Parent topic: Compiler Directives - Alphabetical List


Reserved Directives

These directives are reserved or are maintained for compatibility with earlier products and have no effect. Do not use them.

  • CANCEL
    This directive may appear in source code supplied by Micro Focus. NOCANCEL stops sub-programs being canceled by the RTS for CANCEL and CHAIN statements and other circumstances when the main user application is canceled.
  • CSI
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • FASTSORT
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • FCD3
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • LOCALCOUNT
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • P64
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WB
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WB2
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WB3
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
Parent topic: Compiler Directives


CANCEL

This directive may appear in source code supplied by Micro Focus. NOCANCEL stops sub-programs being canceled by the RTS for CANCEL and CHAIN statements and other circumstances when the main user application is canceled.

Syntax:

>>-.---.-.----.--CANCEL-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | CANCEL
Phase: | Syntax check
$SET: | Any

Comments:

NOCANCEL stops programs being canceled.

This directive is reserved for Micro Focus internal use.

Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List
Related information
Creating Your Own File Handler
Dynamic Redirection to a Custom File Handler


CSI

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.-.----.--CSI-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | CSI
Phase: | Syntax check
$SET: | Initial

Dependencies:

CSI sets ANIM at end.

Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


FASTSORT

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.-.----.--FASTSORT------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | FASTSORT
Phase: | Syntax check
$SET: | Initial
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


FCD3

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

 >>-.---.-.----.--FCD3----------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | FCD3
Phase: | Syntax check
$SET: | No

Dependencies:

Set to FCD3 immediately by the P64 Compiler directive.

Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


LOCALCOUNT

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.--LOCALCOUNT--"integer"------------><
   +-/-+

Parameters:

integer Must be in the range 0 to 65536

Properties:

Default: | LOCALCOUNT"0"
Phase: | Syntax check
$SET: | Initial
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


WB

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.-.----.--WB------------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOWB
Phase: | Syntax check
$SET: | No

Dependencies:

WB sets ANIM immediately.

Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


WB2

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.-.----.--WB2-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOWB2
Phase: | Syntax check
$SET: | No
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


WB3

This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.

Syntax:

>>-.---.-.----.--WB3-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOWB3
Phase: | Syntax check
$SET: | No
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


Run-time Behavior

These directives change the definition of language features and so change the logic of your program.

Some directives listed underLanguage features - dialect also affect behavior.

  • Run-time Behavior - General
  • Run-time Behavior - Arithmetic
  • Run-time Behavior - Mainframe Compatibility
  • Run-time Behavior - Compatibility with Older Micro Focus Products
  • Run-time Behavior - Compatibility with Other COBOL Dialects
  • Run-time Behavior - Speed or Size
Parent topic: Compiler Directives


Run-time Behavior - General

  • ACCEPTREFRESH
    Specifies whether the data areas associated with Screen Section data are updated from their corresponding Working-Storage Section items before an ACCEPT statement.
  • ASSIGN-PRINTER
    Specifies how to assign the output from an ASSIGN TO PRINTER clause when the clause does not specify a filename.
  • ASSIGN
    Specifies how to assign a filename when neither EXTERNAL nor DYNAMIC appear in the SELECT statement.
  • BWZSTAR
    Determines whether the BLANK WHEN ZERO clause is allowed in the Data Division for those fields defined with the "*" PICTURE symbol.
  • CHARSET
    Defines the character set of the environment.
  • CHECKDIV
    Controls the behavior of your program if it tries to divide by zero in a statement that has no ON SIZE ERROR phrase.
  • CHECKNUM
    Checks whether numeric fields contain valid data before performing operations on them.
  • COBFSTATCONV
    Causes the Callable File Handler to use the user-supplied module specified in the COBFSTATCONV environment variable to convert the file status codes if an I/O error is encountered on a file.
  • 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.
  • CONVERTRET (deprecated)
    Causes COMP and COMP-X items specified in CALL ... RETURNING and EXIT PROGRAM ... RETURNING phrases to be converted to COMP-5.
  • CURRENCY-SIGN
    Specifies the currency sign to be recognized in the PICTURE clause.
  • CURRENT-DATE
    Specifies the format of the date stored in the CURRENT-DATE special register.
  • DATA
    Enables AMODE"24" programs to access pointers to Data Division items passed to them by AMODE"31" programs.
  • DEFAULTBYTE
    Initializes each otherwise undefined byte of the Working-Storage Section to the character given.
  • DEFAULTCALLS
    Specifies the default calling convention.
  • DETECT-LOCK
    Makes READ statements detect when a record is locked by another program.
  • DISPLAY
    Defines the default behavior of standard DISPLAY statements.
  • EBC-COL-SEQ
    Determines the EBCDIC collating sequence activated by the NATIVE"EBCDIC" option.
  • EXITPROGRAM
    Determines how the EXIT PROGRAM statement is executed.
  • FOLD-CALL-NAME
    Folds the identifier/literal associated with CALL, CANCEL, ENTRY, and CHAIN statements and the program-name in the PROGRAM-ID paragraph to upper or lower case.
  • FOLD-COPY-NAME
    Determines whether copybook names should be converted to upper case or lower case.
  • HOSTARITHMETIC
    Controls whether or not decimal truncation of arithmetic results occurs following a size error condition.
  • INDD
    Causes ACCEPT statements to be read from a specified file.
  • INIT-BY-TYPE
    Initializes Working-Storage data items to a default value, according to their type.
  • INITCALL
    Specifies modules to be called immediately before the first statement of the program is executed.
  • INITPTR
    Enables the INITIALIZE statement to initialize DATA-POINTER, OBJECT-REFERENCE, and PROGRAM-POINTER data types.
  • INTDATE
    Selects the starting date for integer format dates used with date intrinsic functions.
  • IXNLSKEY
    Specifies that the File Handler should sort index file keys according to the local collating sequence rather than the ASCII collating sequence.
  • IXNUMKEY
    Enables true numeric sorting on index keys.
  • LOCKTYPE
    Specifies the type of record locking.
  • METHODDEFAULT
    Sets the default method for passing parameters.
  • NATIVE
    Specifies the default collating sequence for comparisons.
  • NLS
    Enables the National Locale Support facility.
  • NLS CURRENCY LENGTH
    Specifies the number of bytes to allocate for the currency symbol in a PIC field.
  • OUTDD
    Causes DISPLAY and EXHIBIT statements to be written to a specified output file.
  • PRINT-EXT
    Specifies the extension to be added to the filename associated with the ASSIGN TO PRINTER clause.
  • PROTECT-LINKAGE
    Extends the standard COBOL semantics so that the lengths of parameters can differ between the calling and the called program.
  • SHARE-OUTDD
    When set, multiple threads can write to the same SYSOUT or OUTDD file. When not set, a file locking error occurs in this situation.
  • STICKY-LINKAGE
    Makes parameters to the program remain linked during subsequent calls of the program.
  • TERMPAGE
    Determines whether the last page of a report file is to be padded with blank lines until it is a full page in length.
  • ZEROLENGTHFALSE
    Changes the way that class tests involving zero-length items are carried out.
  • ZWB
    This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.
Parent topic: Run-time Behavior


ACCEPTREFRESH

Specifies whether the data areas associated with Screen Section data are updated from their corresponding Working-Storage Section items before an ACCEPT statement.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--ACCEPTREFRESH-------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOACCEPTREFRESH
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to ACCEPTREFRESH immediately by MS, IBM-MS or PC1.

Comments:

With ACCEPTREFRESH specified, before an ACCEPT statement that references a Screen Section data item, all data areas associated with Screen Section items subsidiary to the item being accepted are modified as follows:

  • If the Screen Section item includes the USING phrase, an implicit MOVE is generated from the corresponding Working-Storage Section item
  • If the Screen Section item includes the TO phrase the data area is initialized to spaces.

With NOACCEPTREFRESH specified, the Screen Section data area is left as it was following the last ACCEPT or DISPLAY.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


BWZSTAR

Determines whether the BLANK WHEN ZERO clause is allowed in the Data Division for those fields defined with the "*" PICTURE symbol.

Syntax:

>>-.---.-.----.--BWZSTAR-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | BWZSTAR
Phase: | Syntax check
$SET: | Any

Comments:

If BWZSTAR is specified, the BLANK WHEN ZERO clause is allowed with fields defined using the "*" PICTURE symbol, and BLANK WHEN ZERO is effective when the field is the target of an editing operation and the result is zero. If NOBWZSTAR is specified, a BLANK WHEN ZERO clause associated with a PIC * field is rejected.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


CHARSET

Defines the character set of the environment.

Syntax:

>>-.---.--CHARSET--"char-set"--------------><
   +-/-+

Parameters:

char-set
ASCII or EBCDIC.

Properties:

Default: | CHARSET"ASCII"
Phase: | Syntax check
$SET: | Initial

Dependencies:

CHARSET"ASCII" sets DEFAULTBYTE"32", SIGN"ASCII" and NATIVE"ASCII" immediately.

CHARSET"EBCDIC" sets DEFAULTBYTE"0" immediately and SIGN"EBCDIC" and NATIVE"EBCDIC" at end.

Comments:

All literals and collating sequences are handled in the character set specified.

With CHARSET"EBCDIC" set, COBOL system library routines that receive or return alphanumeric data in any parameters do not work. The alphanumeric data must be in ASCII.

For managed COBOL, SIGN"EBCDIC", along with one of HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
DEFAULTBYTE
SIGN
NATIVE
Key to Compiler Directives


CHECKDIV

Controls the behavior of your program if it tries to divide by zero in a statement that has no ON SIZE ERROR phrase.

Syntax:

>>-.---.-.-------CHECKDIV-"dialect"-.-----><
   +-/-+ +.----.-CHECKDIV-----------+
          +-NO-+

Parameters:

dialect
One of ACOS, ANSI, ISO2002, COBOL370, ENTCOBOL, MVS, OS390, OSVS, VSC2 .

Properties:

Default: | CHECKDIV"ANSI"
Phase: | Syntax check
$SET: | Initial

Comments:

This directive has no effect on arithmetic statements that use the ON SIZE ERROR phrase.

With CHECKDIV, CHECKDIV"ANSI" or CHECKDIV"ISO2002" specified, the program continues with an undefined result if it tries to divide by zero. With NOCHECKDIV set, the behavior is undefined.

Specifying CHECKDIV"COBOL370", CHECKDIV"ENTCOBOL", CHECKDIV"MVS", CHECKDIV"OS390", CHECKDIV"OSVS" or CHECKDIV"VSC2" has the same effect; trying to divide by zero produces run-time error 048 (Attempt to divide by zero). This error can be disabled using the -O run-time system switch.

With CHECKDIV"ACOS" specified, both the quotient and the remainder are assigned the value of the dividend. The NUMPROC"ACOS" directive provides further ACOS mainframe compatibility.

Setting NOCHECKDIV results in optimal code for divides.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
NUMPROC


CHECKNUM

Checks whether numeric fields contain valid data before performing operations on them.

Syntax:

>>-.---.-.----.--CHECKNUM------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCHECKNUM
Phase: | Generate
$SET: | Initial

Comments:

Specifying this directive causes extra code to be generated to ensure that numeric fields contain valid data before any operations are performed on them. With CHECKNUM set, run-time error message 163 (Illegal character in numeric field (fatal)) is displayed if any numeric field is found to contain nonnumeric data. This error can be disabled using the -F RTS switch.

The extra code produced when you specify CHECKNUM reduces the efficiency of your programs. For smaller, faster code you should not specify CHECKNUM.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


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.

Syntax:

>>-.---.--.----.-COMMAND-LINE-LINKAGE-----------><
   +-/-+  +-NO-+

Parameters:

None.

Properties:

Default: | NOCOMMAND-LINE-LINKAGE
Phase: | Syntax check
$SET: | Initial
IDE equivalent | None

Example:

When using this directive, 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. The following is a simple example of it in use:

...
Procedure Division Using CommandLinePass.
Display "Command Line = " CommandLine(1:CommandLineLen).
...

Comments:

This directive can only be used on the top-level program in a COBOL run-unit; it will have no effect in cases where it is not specified in the top-level program.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


CONVERTRET (deprecated)

Causes COMP and COMP-X items specified in CALL ... RETURNING and EXIT PROGRAM ... RETURNING phrases to be converted to COMP-5.
Note: CONVERTRET is deprecated, and provided for backward compatibility only.

Syntax:

>>-.---.-.----.--CONVERTRET----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCONVERTRET
Phase: | Syntax check
$SET: | Initial
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


CURRENCY-SIGN

Specifies the currency sign to be recognized in the PICTURE clause.

Syntax:

>>-.---.--CURRENCY-SIGN--"integer"---------><
   +-/-+

Parameters:

integer
The ASCII code of the character, in decimal.

Properties:

Default: | CURRENCY-SIGN"36" (that is, "$")
Phase: | Syntax check
$SET: | Initial

Comments:

You cannot specify a valid PICTURE clause symbol.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


CURRENT-DATE

Specifies the format of the date stored in the CURRENT-DATE special register.

Syntax:

>>-.---.--CURRENT-DATE--"date-format"------><
   +-/-+

Parameters:

date-format Either DDMMYY or MMDDYY.

Properties:

Default: | CURRENT-DATE"MMDDYY"
Phase: | Syntax check
$SET: | Any

Comments:

The DDMMYY parameter causes CURRENT-DATE to be stored in European format. The parameter can be specified in either upper case or lower case.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - General
Concepts of the COBOL Language
The CURRENT-DATE Function


DATA

Enables AMODE"24" programs to access pointers to Data Division items passed to them by AMODE"31" programs.

Syntax:

 >>-.---.--------DATA--"format"-------------><
    +-/-+

Parameters:

format
The method of loading of the Data Division:
24
Forces the Data Division to be loaded "below-the-line"
31
Forces the Data Division to be loaded "above-the-line"

Properties:

Default: | DATA"31" if AMODE"31" is set
Phase: | Syntax check
$SET: | Initial

Dependencies:

AMODE"31" sets DATA"31" immediately.

Comments:

The DATA directive enables you to control where the Data Division of a program compiled using AMODE(31) program is loaded.

When the COBOL run-time system loads a program compiled with the AMODE directive, it registers the program's Data Division with the Mainframe Pointer Manager (MFPM) as "above-the-line" or "below-the-line". If you specified AMODE"31", the program is registered as "above-the-line"; if you specified AMODE"24", the program is registered as "below-the-line". All POINTER variable operations subsequently performed by AMODE programs use mainframe addresses assigned by MFPM.

As long as POINTER variables that address items in the Data Division of a program compiled with AMODE"31" are not passed to an AMODE"24" program, programs compiled with AMODE"31" and AMODE"24" can safely coexist in the same run-unit. However, if such POINTERs are passed, an error 114 (at best), or unexpected execution behavior (at worst), will occur.

On the mainframe, the VS COBOL II and COBOL MVS compilers provide the DATA compiler option that controls the location of the Data Division for AMODE"31" programs. By default DATA"31" is set, which causes the Data Division to be allocated above the 16Mb line. However, if you need a program compiled using AMODE"31" to pass data to an AMODE"24" program, you can specify DATA"24" to force the Data Division to be allocated below the 16Mb line. See your VS COBOL II Application Programming Guide and COBOL MVS & VM V1R2 Programming Guide for further details of the DATA(24|31) compiler option and mixed AMODE applications.

You can specify DATA"24" with AMODE"31" to force the Data Division to be loaded below the 16 Mb line.

You cannot use the DATA directive with AMODE"24".

The DATA directive cannot be used for programs that need to call a Micro Focus library routine or an external API that expects pointer items to be in the native machine format.

Parent topic: Run-time Behavior - General
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Mainframe Compatibility
AMODE
Key to Compiler Directives


DEFAULTBYTE

Initializes each otherwise undefined byte of the Working-Storage Section to the character given.

Syntax:

>>-.---.--DEFAULTBYTE--"integer"-----------><
   +-/-+

Parameters:

integer Decimal ASCII code between 0-254.

Properties:

Default: | DEFAULTBYTE"32"
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to DEFAULTBYTE"32" immediately by CHARSET"ASCII".

Set to DEFAULTBYTE"00" immediately by CHARSET"EBCDIC", DIALECT"SAA1", DIALECT"SAA2", DIALECT"OSVS", DIALECT"DOSVS", DIALECT"VSC2", DIALECT"COBOL37[012]", DIALECT"BS2000", DIALECT"SNI", MS, IBM-MS or PC1.

Comments:

integer is a decimal value. For example, if you want to specify an EBCDIC space use DEFAULTBYTE"64"; to specify an ASCII space use DEFAULTBYTE"32".

Decimal value 255 is not permitted.

If you compile with the ILNATIVE Compiler directive, items that will be exposed as IL native types are not initialized according to DEFAULTBYTE. Compile with the NOILNATIVE directive to ensure appropriate items are initialized according to DEFAULTBYTE.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
ILNATIVE
DIALECT
IBM-MS
MS
PC1
CHARSET
INIT-BY-TYPE


DEFAULTCALLS

Specifies the default calling convention.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.-------DEFAULTCALLS--"integer"-.-><
   +-/-+ +.----.-DEFAULTCALLS------------+
          +-NO-+

Parameters:

integer Default calling convention

Properties:

Default: | NODEFAULTCALLS
Phase: | Syntax check
$SET: | Any

Dependencies:

DIALECT"RM" sets DEFAULTCALLS"1024" immediately.

Comments:

DEFAULTCALLS without the optional parameter specifies that the calling convention specified in the PROCEDURE DIVISION USING statement is to be used as the default calling convention.

DEFAULTCALLS"integer" specifies that the calling convention indicated by integer is to be used as the default calling convention.

NODEFAULTCALLS is equivalent to DEFAULTCALLS"0".

Individual CALL statements can override these defaults.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


DISPLAY (Compiler directive)

DISPLAY

Defines the default behavior of standard DISPLAY statements.

Syntax:

>>-.---.-DISPLAY-"device"----><
   +-/-+

Parameters:

device
Must be one of:
CONSOLE
Sets standard ANSI behavior, which is as if the UPON CONSOLE clause has been set.
Note: In situations where extended DISPLAY statements are used or the UPON CRT clause is explicitly set, CRT behavior is used.
CRT
Sets behavior as if the UPON CRT clause has been set.

Properties:

Default: | DISPLAY"CONSOLE"
Phase: | Syntax check
$SET: | Any

Dependencies:

DIALECT"RM", RM, DIALECT"ACU", or ACU sets DISPLAY"CRT" immediately.

Comments:

Use this directive to override DISPLAY behavior set by the ACU and RM directives. These directives set DISPLAY"CRT" behavior immediately, but by setting DISPLAY"CONSOLE" after these directives, you can achieve standard ANSI display behavior.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


EBC-COL-SEQ

Determines the EBCDIC collating sequence activated by the NATIVE"EBCDIC" option.

Syntax:

>>-.---.--EBC-COL-SEQ--"coll-seq-type"---------------><
   +-/-+

Parameters:

coll-seq-type
The type of collating sequence in effect.
1
Uses a fixed EBCDIC collating sequence; this is platform independent.
2
Uses a collating sequence according to the CODESET table in effect, as set by the MFCODESET environment variable.

Properties:

Default: | EBC-COL-SEQ"1"
Phase: | Syntax check
$SET: | Initial

Comments:

Codeset mappings can differ between UNIX and Windows; therefore, when EBC-COL-SEQ"2" is in effect, the collating sequence may differ between the two platforms.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
NATIVE


EXITPROGRAM

Determines how the EXIT PROGRAM statement is executed.

Syntax:

>>-.---.---EXIT-PROGRAM--"option"---><
   +-/-+

Parameters:

One of:
ANSI
If an EXIT PROGRAM statement is executed in a program that is not under the control of a calling program, it causes execution of the program to continue with the next executable statement.
GOBACK
If an EXIT PROGRAM statement is executed, it behaves like a GOBACK statement, that is, it causes a STOP RUN if executed in a main program.

Properties:

Default: | EXITPROGRAM"ANSI"
Phase: | Syntax check
$SET: | Any
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


FOLD-CALL-NAME

Folds the identifier/literal associated with CALL, CANCEL, ENTRY, and CHAIN statements and the program-name in the PROGRAM-ID paragraph to upper or lower case.

Syntax:

>>-.---.-.-----FOLD-CALL-NAME--"case"-.----><
   +-/-+ +---NOFOLD-CALL-NAME---------+

Parameters:

case
UPPER or LOWER

Properties:

Default: | NOFOLD-CALL-NAME
Phase: | Syntax check
$SET: | Initial

Comments:

The Compiler also accepts the directive name without hyphens; that is FOLDCALLNAME.

In a CALL identifier statement, the name called is given the case specified by this directive, but the actual contents of identifier are not changed.

The FOLD-CALL-NAME directive can help in the transfer of COBOL code from an environment with filenames which are not case specific to one which is.

It also makes the Compiler conform with the ANSI'85 standard interprogram communications module, in which the case of a program-name in a CALL statement does not matter.

With NOFOLD-CALL-NAME, by normal COBOL convention the program-name is folded to upper case unless enclosed in quotes. This also applies to the root program of a nested program. All the subprogram-names are folded to upper case even when in quotes. (Enclosing program-names in quotes is a Micro Focus extension.)

The program-name is also accessible as an entry point in a fully linked executable.

You need to specify the CASE directive if you are going to compile .obj code.

FOLD-CALL-NAME does not affect SET statements in the format SET procedure-pointer-name-1 TO ENTRY procedure-pointer-name-1.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
CASE
The CALL Statement
Key to Compiler Directives


FOLD-COPY-NAME

Determines whether copybook names should be converted to upper case or lower case.

Syntax:

>>-.---.-.-----FOLD-COPY-NAME--"case"-.----><
   +-/-+ +---NOFOLD-COPY-NAME---------+

Parameters:

case
"UPPER" or "LOWER".

Properties:

Default: | NOFOLD-COPY-NAME
Phase: | Syntax check
$SET: | Any

Comments:

The Compiler also accepts the directive-name without hyphens; that is FOLDCOPYNAME.

The FOLD-COPY-NAME directive affects both text and library-names regardless of whether they are specified as user-defined words or literals.

Example:

Specifying FOLD-COPY-NAME"UPPER" converts copybook names to upper case (also known as folding to upper case).

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
DIALECT
Related information
Run-time Behavior - General
Key to Compiler Directives


HOSTARITHMETIC

Controls whether or not decimal truncation of arithmetic results occurs following a size error condition.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--HOSTARITHMETIC----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOHOSTARITHMETIC
Phase: | Syntax check
$SET: | Yes

Comments:

The effect of specifying HOSTARITHMETIC is as follows:

  • If the result of an arithmetic operation (ADD, SUBTRACT, MULTIPLY, DIVIDE, COMPUTE) with no ON SIZE ERROR clause exceeds the maximum value that the target item can hold, decimal truncation will be performed on the result, provided that:
    • The target item is a decimal type, that is DISPLAY, COMP-3 or COMP-6
    • None of the source items are floating-point items
    • No exponentiation or intrinsic functions are used in the calculation
    • Neither the composite of operands nor any intermediate result has more than 31 decimal digits
  • If the result of an arithmetic operation (ADD, SUBTRACT, MULTIPLY, DIVIDE, COMPUTE) with an ON SIZE ERROR clause exceeds the maximum value that the target item can hold, the ON SIZE ERROR clause will be executed as normal, and the value of the target item will not be altered.

If you specify this directive in a $SET statement it will affect the run-time behavior of the whole program regardless of where it is placed.

Important: This directive can adversely affect the performance of generated code.
Parent topic: Run-time Behavior - General
Parent topic: Run-time Behavior - Arithmetic
Parent topic: Compiler Directives - Alphabetical List


INDD

Causes ACCEPT statements to be read from a specified file.

Syntax:

>>-.---.-.-------INDD--"fname rsize rtype"----.---><
   +-/-+ +-------INDD--"fname rsize"----------+
         +-------INDD--"fname"----------------+
         +.----.-INDD-------------------------+
          +-NO-+

Parameters:

fname
Name of file to be read for the specified ACCEPT statements. When this parameter is not specified the name used is SYSIN.
rsize
Size of the data records in the file. When this parameter is not specified the size used is 80 bytes is used.
rtype
Either L for Line Sequential (Micro Focus dialect) or R for Record Sequential (mainframe dialects). When this parameter is not specified, L is used.

Properties:

Default: | NOINDD
Phase: | Syntax check
$SET: | Initial

Comments:

When INDD is specified, all format 1 ACCEPT statements which either have no FROM option or specify FROM SYSIN (or the mnemonic-name associated with SYSIN) are transformed into READ statements, reading from a file with the specified external filename.

The filename can be mapped onto physical filenames in the same way as other files with external filenames; that is, by using environment variables or the External File Mapper.

If you specify this directive in an enterprise server environment, any corresponding catalog attributes will override the rsize and rtype parameters; therefore, you will also need to update the catalog attributes to preserve the behavior set by the directive.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
The ACCEPT Statement
ALTER and ACCEPT Statement Restrictions
The File Control Entry
The OPEN Statement
The READ Statement
XML Syntax - READ Statement
OUTDD
Run-time Behavior - General
Key to Compiler Directives


INIT-BY-TYPE

Initializes Working-Storage data items to a default value, according to their type.

Syntax:

>>-.---.-.----.--INIT-BY-TYPE---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOINITBYTYPE
Phase: | Syntax check
$SET: | Initial

Comments:

Normally, the compiler will initialize all data items to spaces or the value specified by the DEFAULTBYTE directive, except for those items given a VALUE clause. If this option is specified, data items are initialized according to their type:

  • Alphabetic, alphanumeric, alphanumeric edited, and numeric edited items are initialized to spaces.
  • Numeric items are initialized to zero.
  • Pointer items are initialized to null.
  • Index items are initialized to the value 1.

Automatic initialization applies only to Working-Storage, and does not apply to any item that (a) is given a VALUE clause (including via a higher group level) (b) is EXTERNAL, or (c) is subordinate to a REDEFINES phrase.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related tasks
DEFAULTBYTE


INITCALL

Specifies modules to be called immediately before the first statement of the program is executed.

Syntax:

>>-.---..-----INITCALL--"module"-.------------..><
   +-/-+|                        +-"priority"-+|
        +-NO--INITCALL-------------------------+

Parameters:

module
The module to be called.
priority
The priority to assign to the execution of the module.
H
High priority (the default if no priority is specified)
L
Low priority

Properties:

Default: | NOINITCALL
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying INITCALL causes the Compiler to insert a call to the named module. At run time, the module specified is called before any procedural code is executed. You cannot pass parameters to the called module.

To call several modules using this feature, you must use the INITCALL directive repeatedly. NOINITCALL clears the list of modules to be called.

Calls specified with a high priority are placed before all calls with a low priority, as well as other calls made by the Compiler. Low priority calls are placed after other calls made by the Compiler. Calls with the same priority are executed in the order they are specified.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


INITPTR

Enables the INITIALIZE statement to initialize DATA-POINTER, OBJECT-REFERENCE, and PROGRAM-POINTER data types.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--INITPTR---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | INITPTR
Phase: | Syntax check
$SET: | Initial

Comments:

When INITPTR is set, an INITIALIZE statement will move specified values to DATA-POINTER, OBJECT-REFERENCE, and PROGRAM-POINTER data types.

If NOINITPTR is set, an INITIALIZE statement will not change the values of these data types.

INITPTR is on by default for MF15 and ISO2002 and off by default for mainframe dialects

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


INTDATE

Selects the starting date for integer format dates used with date intrinsic functions.

Syntax:

>>-.---.-----INTDATE--"type"-------------><
   +-/-+

Parameters:

type
The type of starting-date:
ANSI
Instructs the compiler to use the ANSI COBOL Standard starting date (where Day 1 = Jan 1, 1601).
LILIAN
Instructs the compiler to use the Lilian starting date (where Day 1 = Oct 15, 1582).

Properties:

Default: | INTDATE"ANSI"
Phase: | Syntax check
$SET: | Any

Comments:

This directive selects the starting date for integer format dates used with date intrinsic functions (that is, DATE-OF-INTEGER, DAY-OF-INTEGER, INTEGER-OF-DATE, INTEGER-OF-DAY)

For more details on the date intrinsic functions, see your Language Reference.

Parent topic: Run-time Behavior - General
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


METHODDEFAULT

Sets the default method for passing parameters.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-.---.--METHOD-DEFAULT"pass-method"---------><
   +-/-+

Parameters:

pass-method
One of:
value
By default, pass parameters by value, unless BY REFERENCE is explicitly stated.
reference
By default, pass parameters by reference, unless BY VALUE is explicitly stated.

Properties:

Default: | METHODDEFAULT"reference"
Phase: | Both
$SET: | Initial

Comments:

Parameters are passed by reference by default, except in extension methods where they are passed by value.

When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters. In the following example, v and vv are passed by value, and the others are passed by reference:

procedure division using a as binary-long
                   value v as binary-long
                         vv as binary-long
                   reference r as binary-long
                         rr as binary-long.
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


NATIVE

Specifies the default collating sequence for comparisons.

Syntax:

>>-.---.--NATIVE--"coll-seq"---------------><
   +-/-+

Parameters:

coll-seq Either "ASCII" or "EBCDIC".

Properties:

Default: | NATIVE"ASCII"
Phase: | Syntax check
$SET: | Initial

Dependencies:

Set to NATIVE"ASCII" immediately by CHARSET"ASCII".

Set to NATIVE"EBCDIC" at end by CHARSET"EBCDIC".

Comments:

The keys in an indexed file are always ordered by the ASCII collating sequence.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


NLS

Enables the National Locale Support facility.

Syntax:

>>-.---.-.----.--NLS-----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NONLS
Phase: | Syntax check
$SET: | Initial

Comments:

NLS enables your program to adapt itself automatically at run time to the character set, currency symbol and editing symbols appropriate to your user's country.

If you want to sort index files according to the local collating sequence rather than the ASCII collating sequence, you must specify the IXNLSKEY directive.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
NLS CURRENCY LENGTH


NLS CURRENCY LENGTH

Specifies the number of bytes to allocate for the currency symbol in a PIC field.

Syntax:

>>-.---.--NLS-CURRENCY-LENGTH-"length"------><
   +-/-+

Parameters:

length
The size (in bytes) of currency symbol to use, between 1 and 32 (inclusive).

Properties:

Default: | NLS-CURRENCY-LENGTH"1"
Phase: | Syntax check
$SET: | Initial

Dependencies:

The NLS directive must be set for this directive to take effect.

Comments:

The currency symbol will be truncated or padded with spaces if the length of the current locale's currency symbol differs from the specified length.

Example:

The currency sign for the Albanian locale is "Lek". For a data item of PIC $999, value 123, the directive will have the following results:

Directive setting | Result
Unspecified, or NLS-CURRENCY-LENGTH"1" | "L123"
NLS-CURRENCY-LENGTH"2" | "Le123"
NLS-CURRENCY-LENGTH"3" | "Lek123"
NLS-CURRENCY-LENGTH"4" | " Lek123"
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related reference
NLS
Related information
Key to Compiler Directives


OUTDD

Causes DISPLAY and EXHIBIT statements to be written to a specified output file.

Syntax:

>>-.---.-.-------OUTDD--"fname rsize rtype"----.---><
   +-/-+ +-------OUTDD--"fname rsize"----------+
         +-------OUTDD--"fname"----------------+
         +.----.-OUTDD-------------------------+
          +-NO-+

Parameters:

fname
Name of file to be written for the specified DISPLAY statements and EXHIBIT statements and for the TRACE output. When this parameter is not specified the name used is SYSOUT.
rsize
Size of the data records in the file. When this parameter is not specified the size used is 132 for Micro Focus dialects (rtype = L), or 121 for mainframe dialects (rtype = R).
rtype
Either L for Line Sequential (Micro Focus dialect) or R for Record Sequential (mainframe dialects). When this parameter is not specified, L is used.

Properties:

Default: | NOOUTDD
Phase: | Syntax check
$SET: | Initial

Comments:

When OUTDD is specified, all format 1 DISPLAY statements that either have no UPON option or specify UPON SYSOUT, and all EXHIBIT statements and the output from TRACE, are transformed into WRITE statements, writing to a file with the specified external filename.

The filename can be mapped onto physical filenames in the same way as other files with external filenames; that is, by using environment variables or the External File Mapper.

If you specify this directive in an enterprise server environment, any corresponding catalog attributes will override the rsize and rtype parameters; therefore, you will also need to update the catalog attributes to preserve the behavior set by the directive.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


PROTECT-LINKAGE

Extends the standard COBOL semantics so that the lengths of parameters can differ between the calling and the called program.
Note: This directive is supported for native COBOL only.
Note: This directive is not supported under UNIX.

Normally, the result of ignoring the constraints would give undefined results, possibly including severe errors such as protection violations or memory access faults.

Syntax:

>>-.---.-.----.--PROTECT-LINKAGE-----------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOPROTECT-LINKAGE
Phase: | Syntax check
$SET: | Initial

Comments:

The ANSI COBOL standard states in the general rules for each parameter passed by the CALL statement that "The description of the data item in the called program must describe the same number of character positions as described by the description of the corresponding data item in the calling program.". This restriction must be observed when using this COBOL system unless the program is compiled with the PROTECT-LINKAGE directive.

The restriction is lifted when the PROTECT-LINKAGE directive is set, for all items except when they are used in STRING statements. The called program only uses mismatched parameters as sending items in a statement and does not use them as receiving items.

Any character positions in a parameter for which there is no correspondence in the called and calling programs is a mismatched character. The contents of any mismatched character is undefined for a parameter used as a sending item in a called program.

Don’t set PROTECT-LINKAGE and use CBL_ALLOC_MEM to allocate memory for linkage items at the same time.

Attention: This directive can adversely affect the performance of generated code.

Example:

Calling program:

     ...
     03 x1  pic x.
     03 x2  pic x(100).
 procedure division.
      ...
     call subprog using x1
      ...

Subprogram:

 working-storage section.
 01  y1       pic x(1000).

 linkage section.
 01  z1       pic x(1000).

 procedure division using z1.

     move z1 to y1
* This operation works, and transfers the contents of x1. It
* also transfers any data following x1 in the calling program,
* up to 1000 bytes or the end of allocated memory, whichever
* occurs first. If less than 1000 bytes is transferred, the
* remainder of y1 is space filled.

     move y1 to z1.
* This operation is not protected and fails, either by
* corrupting data beyond x1 in the calling program, or
* trying to write beyond allocated memory, which might
* result in a protection violation.
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Key to Compiler Directives
CBL_ALLOC_MEM


SHARE-OUTDD

When set, multiple threads can write to the same SYSOUT or OUTDD file. When not set, a file locking error occurs in this situation.

Syntax:

 >>-.---.-.----.--SHARE-OUTDD-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSHARE-OUTDD
Phase: | Syntax check
$SET: | Initial
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


STICKY-LINKAGE

Makes parameters to the program remain linked during subsequent calls of the program.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.------STICKY-LINKAGE--"integer"-.-><
   +-/-+ +----NO-STICKY-LINKAGE-----------+

Parameters:

integer Either 1 or 2

Properties:

Default: | NOSTICKY-LINKAGE
Phase: | Syntax check
$SET: | Initial

Comments:

The purpose of the COBOL Linkage Section is to provide a linkage between a level 01 or level 77 data item declared in the Linkage Section (a linkage item) and some dynamically specified data item so that they appear to share the same storage area. The linkage is established by one of three means: a CALL program-name USING statement, a CALL entry-name USING statement, or a SET statement. The first mechanism is the standard one specified by ANSI. The other two are COBOL language extensions that are supported by this COBOL system.

In ANSI COBOL, the Linkage Section enables a called program to access the parameters passed to it by a CALL statement. The number of parameters in the USING phrase of the CALL statement must equal the number of parameters in the USING phrase of the PROCEDURE DIVISION header. Any level 01 or level 77 data item in the Linkage Section that does not appear in the USING phrase of the PROCEDURE DIVISION header must not be referenced.

The ENTRY statement is a COBOL language extension that provides an alternative entry point into a program. The ENTRY statement takes a USING phrase in the same way as the PROCEDURE DIVISION header, and, in a similar fashion, linkage items must not be referenced if they do not appear in the USING phrase associated with the entry-name by which the program was invoked.

The SET statement enables a POINTER value that identifies a storage location to be used to link a linkage item. Such a linkage item can then be referenced in order to reference the data held at that storage location.

The following details explain in conceptual terms when linkage items are linked and unlinked.

This COBOL system checks at run time when a linkage item is referenced, to ensure it is linked to a data item. It gives a run-time error if it is not linked to any storage location. To facilitate this check, on each invocation immediately before executing the first statement in the program, all linkage items are first unlinked and then linkage items that have corresponding parameters passed by the calling program are linked. This means that a linkage item in a called program that is linked to a data item by the SET statement does not remain linked on subsequent invocations of the program; the SET statement needs to be executed in each invocation.

Many other COBOL implementations are less rigorous in enforcing the ANSI rules and the STICKY-LINKAGE directive takes a parameter to specify two alternative and less rigorous regimes.

STICKY-LINKAGE"1" specifies that only the linkage items that appear in the USING phrase of the called program are unlinked; other linkage items retain any previous linkage. If the program was called using the program-name this is the USING phrase of the PROCEDURE DIVISION header. Otherwise, this is the USING phrase associated with the entry-point by which the program was invoked.

Under this regime, if the calling program provides insufficient parameters and a reference is made to a linkage item that appears in the USING phrase but has no corresponding parameter in the USING phrase of the CALL statement, a run-time error is still given.

STICKY-LINKAGE"2" specifies that, except when the program is in its initial state at startup or after it is referenced in a CANCEL statement, no linkage items are unlinked when the program is called. All linkage items retain any linkage established during previous invocations unless the calling program provides a parameter or a SET statement is used to change the linkage.

No particular implementation method is implied by this and indeed, on this COBOL system, emulating the non-ANSI conformant behavior using this directive can have a detrimental effect on program size and execution speed.

Example:

If the following program is compiled without the STICKY-LINKAGE directive and run, a run-time error 203, CALL parameter not supplied, is given after the second CALL statement passes control to "ent" and the DISPLAY statement references two linkage items that do not appear in the USING phrase of ENTRY "ent".

If the program is then compiled with STICKY-LINKAGE"1" and run, execution progresses until it fails again after the third CALL statement passes control to "sub" and the DISPLAY statement references a linkage item that does appear in the USING phrase of the PROCEDURE DIVISION header but has no corresponding parameter passed by the CALL statement.

If the program is compiled with STICKY-LINKAGE"2" and run, the program successfully executes to completion.

 program-id. main.
 working-storage section.
 01 param pic x value "a".
 procedure division.
     call "sub" using param
     call "ent"
     call "sub"
     stop run.
 end program main.

 program-id. sub.
 linkage section.
 01 link-1 pic x.
 01 link-2 pic x.
 procedure division using link-1.
     set address of link-2 to address of link-1
     display link-1 link-2
     exit program.

   entry "ent"
     display link-1 link-2
     exit program.

If STICKY-LINKAGE"2" is used for a called program, it can be called only by a COBOL program.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
PARAMCOUNTCHECK
Configuration Section
Input-Output Section
General Description
Working-Storage Section
Thread-Local-Storage Section
Object-Storage Section
Local-Storage Section
Linkage Section
Screen Section
Procedure Division General Description
The EXIT Statement
Input-Output Section
Report Section
The ENTRY Statement
The SET Statement
ENTRY Statement Restrictions
The Repository Paragraph
Screen Section Entry Skeleton
The USING Clause
The PROCEDURE DIVISION Header
The CALL Statement
The CHAIN Statement
The INVOKE Statement
The MERGE Statement
The SORT Statement
The START Statement
The Class-ID Paragraph
The Interface-ID Paragraph
The File Control Entry
Data Description Entry Skeleton
The USAGE Clause
The USAGE Clause in the Screen Section
The DISPLAY Statement
The CANCEL Statement
$IF Statement
The PROPERTY Clause
The VALUE Clause
The Method-ID Paragraph
Key to Compiler Directives


TERMPAGE

Determines whether the last page of a report file is to be padded with blank lines until it is a full page in length.

Syntax:

>>-.---.-.----.--TERMPAGE------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | TERMPAGE
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying TERMPAGE causes the last page of a report to be padded with blank lines until it is a full page in length.

This directive affects any report file for which the PAGE phrase is specified in its Report Description (RD) entry.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


ZEROLENGTHFALSE

Changes the way that class tests involving zero-length items are carried out.

Syntax:

>>-.---.-.----.--ZEROLENGTHFALSE-----------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOZEROLENGTHFALSE
Phase: | Syntax check
$SET: | Any

Comments:

When ZEROLENGTHFALSE is set, all comparisons between zero-length group items, and between zero-length items and figurative constants, return false; when it is not set, they all return true.

For conformance to ANSI you must set ZEROLENGTHFALSE.

Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
Key to Compiler Directives


ZWB

This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.

Note: This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.
Parent topic: Run-time Behavior - General
Parent topic: Compiler Directives - Alphabetical List


Run-time Behavior - Arithmetic

  • ARITHMETIC
    Specifies how arithmetic expressions are to be evaluated.
  • BINLIT
    Controls whether binary b"" literals are interpreted as numeric values, or Boolean values for use with PIC 1 data items.
  • COMP-5
    Specifies whether the sign is to be dropped when a value is stored in an unsigned COMP-5 data item.
  • COMP-6
    Specifies whether COMP-6 data is to be held in binary or packed decimal format, or emulates ACUCOBOL-GT or RM/COBOL COMP-6 behavior.
  • HOSTARITHMETIC
    Controls whether or not decimal truncation of arithmetic results occurs following a size error condition.
  • NATIVE-FLOATING-POINT
    Determines whether a program's floating point data items are to use IBM hexadecimal format.
  • SIGNDISCARD
    Specifies that a MOVE of a signed numeric DISPLAY field to a group item should discard the sign, and treat the group as an elementary alphanumeric field.
  • TRUNC
    Specifies whether data being stored into a USAGE COMP, USAGE BINARY or USAGE COMP-4 item is to be truncated to the size given by the item's PICTURE clause or to the maximum size the item can hold.
Parent topic: Run-time Behavior


ARITHMETIC

Specifies how arithmetic expressions are to be evaluated.

Syntax:

>>-.---.--ARITHMETIC--"arith-type"---------><
   +-/-+

Parameters:

arith-type
The behavior to adopt:
ENTCOBOL
Truncate according to the rules of Enterprise COBOL for z/OS and OS/390.
MF, ISO2002 or ANSI
Do not truncate intermediate results. With ARITHMETIC"MF", ARITHMETIC"ISO2002" or ARITHMETIC"ANSI" specified, expressions are calculated as accurately as possible because no truncation takes place.
OS390
Truncate according to the rules of COBOL for OS/390.
OSVS
Truncate according to the rules of OS/VS COBOL.
VSC2
Truncate according to the rules of VS COBOL II and COBOL/370.

Properties:

Default: | ARITHMETIC"MF"
Phase: | Syntax check
$SET: | Initial
Parent topic: Run-time Behavior - Arithmetic
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - General
Key to Compiler Directives


BINLIT

Controls whether binary b"" literals are interpreted as numeric values, or Boolean values for use with PIC 1 data items.

Syntax:

 >>-.---.-.----.--BINLIT--"literal-type"-------------><
    +-/-+

Parameters:

literal-type
NUMERIC
Treat binary literals as numeric values
BOOLEAN
Treat binary literals as Boolean values.

Properties:

Default: | BINLIT(NUMERIC)
Phase: | Check
$SET: | Any

Comments:

A program containing a PIC 1 data item will automatically have BINLIT(BOOLEAN) set at that point.

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
The PICTURE Clause


COMP-5

Specifies whether the sign is to be dropped when a value is stored in an unsigned COMP-5 data item.

Syntax:

>>-.---.--COMP-5--"integer"----------------><
   +-/-+

Parameters:

integer
Must be one of:
1
Behavior as in earlier versions of this Compiler. The sign is dropped.
2
The sign is not dropped. Negative numbers are stored in two's complement form, so that, except for their byte-order being machine dependent, unsigned COMP-5 items behave like COMP-X. This results in highly efficient arithmetic on unsigned COMP-5 items.

Properties:

Default: | COMP-5"2"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" or DIALECT"ACU" set COMP-5"1" immediately.

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


COMP-6

Specifies whether COMP-6 data is to be held in binary or packed decimal format, or emulates ACUCOBOL-GT or RM/COBOL COMP-6 behavior.

Syntax:

>>-.---.--COMP-6--"integer"----------------><
   +-/-+

Parameters:

integer
Must be one of the following:
1
A binary format is used for COMP-6 data
2
Packed decimal format is used. If the item is signed, the format is identical to COMP-3. If the item is unsigned, no sign field is present.
3
Unsigned packed decimal format is used, with no sign field.

Properties:

Default: | COMP-6"2"
Phase: | Syntax check
$SET: | Initial

Dependencies:

ADDRSV"COMP-6" must be set.

DIALECT"RM", DIALECT"ACU", or ACU set COMP-6"3" immediately.

Comments:

The binary format used when you set COMP-6"1" is as described in the chapter RM/COBOL Syntax Support in your Language Reference .

Even if you specify the COMP-6 directive, the reserved word COMP-6 is recognized only if it belongs to the chosen dialect or the directive ADDRSV"COMP-6" is specified.

Example:

With COMP-6"2" specified:

PIC 99 COMP-6 VALUE 87

is stored in one byte as x"87"

PIC S99 COMP-6 VALUE 87

is stored in two bytes as x"087C"

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


NATIVE-FLOATING-POINT

Determines whether a program's floating point data items are to use IBM hexadecimal format.
Note: This directive is supported for native COBOL only.

Syntax:

 >>-.---.-.----.--NATIVE-FLOATING-POINT-----><
    .-/-+ .-NO-+

Parameters:

None

Properties:

Default: | NONATIVE-FLOATING-POINT
Phase: | Syntax check
$SET: | Initial

Comments:

Specifying NATIVE-FLOATING-POINT causes all floating point data items to use IEEE. Specifying NONATIVE-FLOATING-POINT causes the format used to be determined by the MAINFRAME_FLOATING_POINT environment variable.

For equivalent functionality for managed COBOL, see MAINFRAME-FLOATING-POINT.

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related reference
MAINFRAME-FLOATING-POINT


SIGNDISCARD

Specifies that a MOVE of a signed numeric DISPLAY field to a group item should discard the sign, and treat the group as an elementary alphanumeric field.

Restriction: This directive is supported in native COBOL only.

Syntax:

>>-.---.-.----.--SIGNDISCARD------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSIGNDISCARD
Phase: | Check
$SET: | Initial
Parent topic: Run-time Behavior - Arithmetic
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
The MOVE Statement


TRUNC

Specifies whether data being stored into a USAGE COMP, USAGE BINARY or USAGE COMP-4 item is to be truncated to the size given by the item's PICTURE clause or to the maximum size the item can hold.

Syntax:

>>-.---.-.-------TRUNC--"method"-.---------><
   +-/-+ +.----.-TRUNC-----------+
          +-NO-+

Parameters:

method
One of:
TRUNC
Truncate in decimal to the number of digits given by the PICTURE clause, on all stores into COMP, BINARY and COMP-4 items.
NOTRUNC
Truncate in binary to the capacity of the allocated storage, on all nonarithmetic stores into COMP, BINARY and COMP-4 items.
TRUNC"ANSI"
Truncate in decimal to the number of digits given by the PICTURE clause, on nonarithmetic stores into COMP, BINARY and COMP-4 items. On arithmetic statements that cause the size error condition and that have no ON SIZE ERROR phrase, the result is undefined.

Properties:

Default: | TRUNC"ANSI"
Phase: | Syntax check
$SET: | Initial

Dependencies:

NORM sets TRUNC"ANSI" immediately.

DIALECT"RM", RM, or RM"ANSI" sets NOTRUNC immediately.

Parent topic: Run-time Behavior - Arithmetic
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - Compatibility with Other COBOL Dialects
Key to Compiler Directives


Run-time Behavior - Mainframe Compatibility

  • ADV
    Causes a control character to be inserted at the start of each line in a print file. This is for compatibility with mainframe operation.
  • AMODE
    Provides support when performing arithmetic on mainframe-style pointers.
  • BYTE-MODE-MOVE
    Controls behavior for alphanumeric moves between overlapping data items.
  • DATA
    Enables AMODE"24" programs to access pointers to Data Division items passed to them by AMODE"31" programs.
  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • DYNAM
    Specifies that CANCEL statements are not to be ignored.
  • FP-ROUNDING
    Determines whether one floating-point receiving item can affect the results of other, nonfloating-point receiving items.
  • HOST-NUMCOMPARE
    Controls the operation of comparisons involving numeric data items.
  • HOST-NUMMOVE
    Ensures that run-time error 163 (illegal characters in numeric fields) does not occur when certain MOVE statements are executed on numeric display data items or numeric operands.
  • HOSTRW
    Causes Report Writer to produce mainframe print files with the full range of ASA characters.
  • IBMCOMP
    Turns on word-storage mode.
  • MAINFRAME-FLOATING-POINT
    Specifies the format of the program's floating point data items.
  • MAPNAME
    Makes the Compiler alter program-names and entry-point names to make them compatible with OS/VS COBOL, DOS/VS COBOL, VS COBOL II and COBOL/370.
  • NATIVE-FLOATING-POINT
    Determines whether a program's floating point data items are to use IBM hexadecimal format.
  • ODOOSVS
    Makes the evaluation of OCCURS DEPENDING ON items more compatible with the OS/VS COBOL compiler.
  • PERFORM-TYPE
    Specifies the behavior of return jumps from nested PERFORM statements.
  • REMAINDER
    Enables you to select how the remainder is calculated in a DIVIDE statement.
  • SIGN-FIXUP
    Provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements.
  • SYSPUNCH
    Specifies the SYSPUNCH record length to be used.
Parent topic: Run-time Behavior


ADV

Causes a control character to be inserted at the start of each line in a print file. This is for compatibility with mainframe operation.

Syntax:

>>-.---.-.----.--ADV---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOADV
Phase: | Syntax check
$SET: | Any

Dependencies:

ADV has no effect unless FILETYPE"11" is set.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
FILETYPE
Key to Compiler Directives


AMODE

Provides support when performing arithmetic on mainframe-style pointers.

Syntax:

 >>-.---.-.-------AMODE--"format"---.---------><
    +-/-+ +---NO--AMODE-------------+

Parameters:

format
The storage format of pointers:
24
All pointers are stored in a 24-bit format. This format is compatible with "below-the-line" storage on the mainframe. The top 8 bits of the pointer are masked off when the address of a linkage item is set from the pointer. This means that, as on the mainframe, the top 8 bits can be manipulated directly by the user's code.
31
All pointers are stored in a 31-bit format. This format is compatible with "above-the-line" storage on the mainframe. The top bit of the pointer is masked off when the address of a linkage item is set from the pointer. This means that, as on the mainframe, the top bit can be manipulated directly by the user's code.

Properties:

Default: | NOAMODE
Phase: | Syntax check
$SET: | Initial

Dependencies:

AMODE"31" sets DATA"31" immediately.

Comments:

You need the AMODE directive for any program module that uses arithmetic containing mainframe-style pointers. For example:
01 ptr pointer.
01 ptr-comp pic 9(9) comp redefines ptr.

add 24 to ptr-comp.

In general, to eliminate potential problems that might occur when trying to be selective about which programs are compiled with this directive, we strongly recommended that you use the AMODE directive on all programs in the application, and that you use the same value for format for each subprogram.

The AMODE directive cannot be used for programs that need to call a Micro Focus library routine or an external API that expects pointer items to be in the native machine format.

AMODE is required when compiling applications that call assembler programs.

Parent topic: Run-time Behavior - Mainframe Compatibility
Related information
Language Features - Mainframe Compatibility
DATA
Key to Compiler Directives


BYTE-MODE-MOVE

Controls behavior for alphanumeric moves between overlapping data items.

Syntax:

>>-.---.-.----.---BYTE-MODE-MOVE------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOBYTE-MODE-MOVE
Phase: | Syntax check
$SET: | Initial

Comments:

The Compiler also accepts the directive-name without hyphens; that is BYTEMODEMOVE.

This directive is provided for compatibility with IBM mainframe compilers in the handling of forward overlapping alphanumeric moves - that is, where the start of the target data item overlaps the end of the source data item.

If BYTE-MODE-MOVE is specified, data is moved one byte at a time from the source to the target.

If NOBYTE-MODE-MOVE is specified, the data is moved in granules of two, four or more bytes at a time (depending on environment) from the source to the target. Consequently, if the overlap is less than the size of the granule, each granule moved overwrites part of the next granule to be moved.

NO-BYTE-MODE-MOVE gives better performance.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


DYNAM

Specifies that CANCEL statements are not to be ignored.

Syntax:

 >>-.---.-.----.--DYNAM---------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | DYNAM
Phase: | Syntax check
$SET: | Initial

Comments:

With NODYNAM, CANCEL statements in the program are ignored.

Note: The mainframe DYNAM option only affects the CANCEL statements for programs invoked by CALL literal statements; CANCEL statements for programs invoked by CALL identifier statements are not affected. In this COBOL system, the DYNAM Compiler directive affects CANCEL statements for programs invoked by both CALL literal and CALL identifier statements.
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Language Features - Mainframe Compatibility
Key to Compiler Directives


FP-ROUNDING

Determines whether one floating-point receiving item can affect the results of other, nonfloating-point receiving items.
Note: This directive is supported for native COBOL only.

Syntax:

 >>-.---.-.---FP-ROUNDING--"dialect"----.--------><
    +-/-+ +-NOFP-ROUNDING---------------+

Parameters:

dialect COBOL370, ISO2002, ENTCOBOL, MVS, OS390, OSVS or VSC2 .

Properties:

Default: | NOFP-ROUNDING
Phase: | Syntax check
$SET: | Any

Comments:

FP-ROUNDING"ISO2002" is the equivalent of NOFP-ROUNDING.

With all possible values of dialect except ISO2002, if any of the sending data items of an arithmetic statement are floating-point, all receiving fields are rounded, regardless of the presence or absence of the ROUNDED phrase and regardless of whether or not the receiving fields are floating-point.

With all possible values of dialect except ISO2002 and OSVS, if any receiving data item is defined as floating-point, rounding takes place for all receiving data items regardless of the presence or absence of the ROUNDED phrase, of whether or not the receiving field is floating-point, and of whether or not there are any sending items which are floating-point.

With NOFP-ROUNDING or FP-ROUNDING"ISO2002", no rounding takes place for fixed-point targets in calculations involving floating-point operands unless the ROUNDED phrase is explicitly used in the source.

Example:

If two data items are defined as follows:

     05 numeric-field    pic 999.
     05 floating-field   comp-1.

and the following statement is executed:

     compute numeric-field floating-field = 7.7 + 1

specifying FP-ROUNDING"VSC2" or FP-ROUNDING"COBOL370" results in numeric-field containing 9 (rounded), whereas specifying NOFP-ROUNDING, FP-ROUNDING"ISO2002" or FP-ROUNDING"OSVS" would result in numeric-field containing 8 (truncated).

If, using the same two data items, the following statement is executed:

compute numeric-field = +7.6E0

specifying FP-ROUNDING"VSC2", FP-ROUNDING"COBOL370" or FP-ROUNDING"OSVS" results in numeric-field containing 8 (rounded), whereas specifying NOFP-ROUNDING or FP-ROUNDING"ISO2002" results in numeric-field containing 7 (truncated).

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - Compatibility with Other COBOL Dialects
Key to Compiler Directives


HOST-NUMCOMPARE

Controls the operation of comparisons involving numeric data items.
CAUTION:
This directive can adversely affect the performance of generated code.

Syntax:

>>--.---.--.----.--HOST-NUMCOMPARE------><
    +-/-+  +-NO-+

Parameters:

None

Properties:

Default: | NOHOST-NUMCOMPARE
Phase: | Syntax check
$SET: | Any

Comments:

This directive is provided to improve compatibility with IBM mainframe compilers, resulting in a run-time error 163 ("Illegal character in numeric field") in cases where a S0C7 would have occurred on the mainframe.

Setting HOST-NUMCOMPARE improves compatibility with IBM mainframe compilers for a subset of IF statements when comparing numeric data items with other operands.

It is not possible to guarantee 100% compatibility with the IBM mainframe behavior, but setting HOST-NUMCOMPARE does provide emulation for the most common cases.

HOST-NUMCOMPARE is only supported for SIGN settings of ASCII, MF, EBCDIC, and IBM.

For managed COBOL, SIGN"EBCDIC", along with one of HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

Use HOST-NUMCOMPARE with CHARSET(EBCDIC) for maximum compatibility with IBM mainframe behavior. If CHARSET(ASCII) is used, then some compatibility may be lost due to character encoding differences.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


HOST-NUMMOVE

Ensures that run-time error 163 (illegal characters in numeric fields) does not occur when certain MOVE statements are executed on numeric display data items or numeric operands.

Syntax:

>>--.---.--.----.--HOST-NUMMOVE------><
    +-/-+  +-NO-+

Parameters:

None

Properties:

Default: | NOHOST-NUMMOVE
Phase: | Syntax check
$SET: | Any

Comments:

This directive improves compatibility with IBM mainframe compilers, resulting in a run-time error 163 ("Illegal character in numeric field") in cases where a S0C7 would have occurred on the mainframe.

Setting HOST-NUMMOVE improves compatibility with IBM mainframe compilers for a subset of MOVE statements involving numeric/alphanumeric data types and numeric/numeric data types.

It is not possible to guarantee 100% compatibility with the IBM mainframe behavior, but setting HOST-NUMMOVE does provide emulation for the most common cases.

HOST-NUMMOVE is only supported for SIGN settings of ASCII, MF, EBCDIC, and IBM.

For managed COBOL, SIGN"EBCDIC", along with one of HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

Use HOST-NUMMOVE with CHARSET(EBCDIC) for maximum compatibility with IBM mainframe behavior. If CHARSET(ASCII) is used, then some compatibility may be lost due to character encoding differences.

CAUTION:
This directive can adversely affect the performance of generated code.
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


HOSTRW

Causes Report Writer to produce mainframe print files with the full range of ASA characters.

As per the mainframe, the record length used is exactly as specified in the FD if the RECORD CONTAINS clause is specified; consequently, the last byte of a record may be lost depending on the size of the biggest report group, since the record contents are shifted one byte to provide space for the ASA character as the first byte of a record. If no RECORD CONTAINS clause is specified, the record length used is the size of the biggest report group plus 1 (to incorporate the ASA character).

You no longer need to specify the options MAINFRAMEPRINT=ON or FILETYPE(11) as they are turned on for the Report Writer file by HOSTRW.

Syntax:

>>-.---.-.----.--HOSTRW------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOHOSTRW
Phase: | Check
$SET: | Initial
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related reference
The WRITE Statement
Related information
Key to Compiler Directives
MAINFRAMEPRINT


IBMCOMP

Turns on word-storage mode.

Syntax:

>>-.---.-.----.--IBMCOMP-------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOIBMCOMP
Phase: | Syntax check
$SET: | Initial

Dependencies:

IBMCOMP sets ALIGN"8 OPT" immediately.

DIALECT"RM" sets IBMCOMP immediately.

Comments:

In word-storage mode every data item of USAGE COMP or COMP-5 occupies either two bytes or a multiple of four bytes. If you specify IBMCOMP and you use the SYNCHRONIZED clause on any items defined as USAGE COMP or COMP-5 in your program, do not specify ALIGN"1".

If you are calling any Micro Focus systems routines directly, use IBMCOMP with great care. It might cause the parameters you specify to these routines to be incorrectly aligned and sized, causing the routines to give incorrect results. This includes parameters for the CBL_ library routines, calls to Adis and direct calls to the Callable File Handler, Extfh.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related reference
DIALECT
ALIGN
Related information
Run-time Behavior - Mainframe Compatibility
Data Description Entry Skeleton
The USAGE Clause
Screen Section Entry Skeleton
The USAGE Clause in the Screen Section
The USAGE Clause
The SYNCHRONIZED Clause
Key to Compiler Directives


MAINFRAME-FLOATING-POINT

Specifies the format of the program's floating point data items.
Restriction: This directive is supported for managed code only.

When this directive is set, the IBM hexadecimal format is used; when not set, the IEEE format is used.

Syntax:

>>-.---.-.----.--MAINFRAME-FLOATING-POINT---><
   +-/-+ +-NO-+

Parameters:

None.

Properties:

Default: | NOMAINFRAME-FLOATING-POINT
Phase: | Syntax check
$SET: | Initial

Comments:

The native COBOL equivalent is when the NONATIVE-FLOATING-POINT directive and the MAINFRAME_FLOATING_POINT environment variable are both in effect.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related reference
NATIVE-FLOATING-POINT


ODOOSVS

Makes the evaluation of OCCURS DEPENDING ON items more compatible with the OS/VS COBOL compiler.
Note: This directive is supported for native COBOL only.

Syntax:

 >>-.---.-.----.--ODOOSVS-------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOODOSVS
Phase: | Syntax check
$SET: | Initial

Dependencies:

ODOOSVS sets the ODOSLIDE Compiler directive at the end.

Comments:

When ODOOSVS is specified, the length of variable-length groups and the address of items following variable-length tables is evaluated at the time when the OCCURS DEPENDING ON item is modified, rather than at the time when the variable-length group or sliding data item is referenced.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Key to Compiler Directives


PERFORM-TYPE

Specifies the behavior of return jumps from nested PERFORM statements.

Syntax:

>>-.---.--PERFORM-TYPE--"dialect"----------><
   +-/-+

Parameters:

dialect
One of:
MF
Only the exit point of the innermost PERFORM currently being executed is recognized and its return jump taken.
RM
The exit point of any PERFORM statement currently being executed is recognized if reached; the return jump taken is the first reached. PERFORM statements with the same exit point cannot be nested; if they are they do not return correctly. The end of a section is regarded as a separate point from the end of its last paragraph.
COBOL370, ENTCOBOL, OS390, OSVS, VSC2
The exit point of any PERFORM statement currently being executed is recognized if reached; the return jump taken is the first reached. PERFORM statements with the same exit point can be nested to a depth of two (one inner and one outer). If they are nested deeper, they do not return correctly. The end of a section is regarded as a separate point from the end of its last paragraph.
  • PERFORM-TYPE"COBOL370" provides compatibility with the mainframe behavior of COBOL/370.
  • PERFORM-TYPE"ENTCOBOL" provides compatibility with the mainframe behavior of Enterprise COBOL.
  • PERFORM-TYPE"OS390" provides compatibility with the mainframe behavior of OS/390 COBOL.
  • PERFORM-TYPE"OSVS" provides compatibility with the mainframe behavior of OS/VS COBOL and DOS/VS COBOL.
  • PERFORM-TYPE"VSC2" provides compatibility with the mainframe behavior of VS COBOL II.

Properties:

Default: | PERFORM-TYPE"MF" (All mainframe dialects)
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets PERFORM-TYPE"RM" immediately.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
Perform Statements
STICKY-PERFORM
Run-time Behavior - Compatibility with Other COBOL Dialects
Key to Compiler Directives


REMAINDER

Enables you to select how the remainder is calculated in a DIVIDE statement.
Note: This directive is supported for native COBOL only.

Syntax:

 >>------REMAINDER---"integer"-----------><

Parameters:

integer
Must be one of:
1
The Compiler uses the ANSI 85 algorithm.
2
The Compiler uses an algorithm employing a subsidiary quotient. This subsidiary quotient is signed and is of sufficient size to hold any valid value. This method is compatible with all IBM compilers and the ANSI 2002 standard.

Properties:

Default: | REMAINDER"1"
Phase: | Syntax check
$SET: | Any
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Key to Compiler Directives


SIGN-FIXUP

Provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements.
Attention: This directive can adversely affect the performance of generated code.

Syntax:

 >>-.---.-.----.--SIGN-FIXUP------------------><
    +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSIGN-FIXUP
Phase: | Syntax check
$SET: | Initial

Comments:

The effect of this directive is as follows:

  • SIGN-FIXUP provides a limited emulation of the mainframe compiler option NUMPROC(NOPFD) when using the HOST-NUMCOMPARE and HOST-NUMMOVE directives. It is not possible to provide a complete emulation of NUMPROC(NOPFD) behavior.
  • NOSIGN-FIXUP provides emulation of the mainframe compiler option NUMPROC(PFD) when using the HOST-NUMCOMPARE and HOST-NUMMOVE directives.

SIGN-FIXUP is only supported for SIGN settings of ASCII, MF, EBCDIC, and IBM.

For managed COBOL, SIGN"EBCDIC", along with one of HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List


SYSPUNCH

Specifies the SYSPUNCH record length to be used.

Syntax:

>>-.---.--SYSPUNCH--"integer"-------------><
   +-/-+

Parameters:

integer
The record length to be used.

Properties:

Default: | SYSPUNCH"132"
Phase: | Syntax check
$SET: | Any
Parent topic: Run-time Behavior - Mainframe Compatibility
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Run-time Behavior - Mainframe Compatibility
Key to Compiler Directives


Run-time Behavior - Compatibility with Older Micro Focus Products

  • AUTOLOCK
    Makes the default locking AUTOMATIC rather than EXCLUSIVE for files opened for INPUT, I-O, or EXTEND in a multi-user environment.
  • COMP-5
    Specifies whether the sign is to be dropped when a value is stored in an unsigned COMP-5 data item.
  • COMP
    Makes the compiler produce very compact and efficient code for some statements involving COMP data items, by treating COMP items as COMP-X or sets the representation meant by COMP usage in a data description entry.
  • DE-EDIT
    Specifies the behavior of de-editing moves from numeric-edited items to other numeric-edited items or to numeric items.
  • FILESHARE
    Causes the default locking to become AUTOMATIC rather than EXCLUSIVE for files in a multi-user environment, and automatically locks records on a WRITE or REWRITE statement when the program is locking multiple records.
  • IOCONV
    Selects between a straight group move and conversion of elementary record descriptions (ANSI behavior) when processing READ ... INTO and WRITE ... FROM statements.
  • MF, MFLEVEL
    Enables forward compatibility with Micro Focus COBOL systems by selectively enabling Micro Focus-specific reserved words and changing the behavior of certain features to be compatible with particular versions.
  • OLDBLANKLINE
    Changes the behavior of the BLANK LINE clause in the Screen Section.
  • OLDINDEX
    Causes indexes to be compiled as 16-bit binary integer subscripts.
  • OLDNEXTSENTENCE
    Changes the behavior of the NEXT SENTENCE statement.
  • OLDREADINTO
    Changes the behavior of the READ ... INTO statement.
  • OLDSTRMIX
    Allows PIC X and PIC N fields to be specified in the same STRING, UNSTRING or INSPECT statement
  • SPZERO (deprecated)
    Causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros.
  • WRITELOCK, WRITE-LOCK
    Makes the WRITE and REWRITE statements acquire a record lock when the program is locking multiple records in a shared data file in a multi-user environment.
Parent topic: Run-time Behavior


COMP

Makes the compiler produce very compact and efficient code for some statements involving COMP data items, by treating COMP items as COMP-X or sets the representation meant by COMP usage in a data description entry.

Syntax:

>>-.---.--.--------COMP"opt"--.--------><
   +-/-+  +-.----.-COMP-------+
            +-NO-+

Parameters:

opt can be one of:

BINARY
COMP usage in a data description entry specifies binary two's complement representation of the numeric value.
DISPLAY
COMP usage in a data description entry specifies display representation of the numeric value.
PACKED
COMP usage in a data description entry specifies packed-decimal representation of the numeric value, that is, two decimal digits per byte with a trailing sign nibble if the data item is signed.
UNPACKED
COMP usage in a data description entry specifies display representation of the numeric value, that is, one decimal digit per byte with a trailing sign byte if the data item is signed.

Properties:

Default: | NOCOMP and COMP"BINARY"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets COMP"UNPACKED" immediately.

Comments:

When the COMP directive, without a parameter, is in effect, the code for COMP usage data items represented in binary two's complement produced by the compiler behaves in a way that is not the ANSI standard in cases of numeric overflow for such items. You should use this directive only if you know that your program does not lead to numeric overflow, or if you want to use the defined (but nonstandard) behavior on overflow.

The COMP directive with a parameter causes the interpretation of COMP usage in a data description entry to be as described for the parameter above. COMP and COMP"BINARY" may be used together. COMP has no effect if COMP"DISPLAY", COMP"PACKED" or COMP"UNPACKED" is in effect.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


DE-EDIT

Specifies the behavior of de-editing moves from numeric-edited items to other numeric-edited items or to numeric items.

Syntax:

>>-.---.--DE-EDIT--"integer"---------------><
   +-/-+

Parameters:

integer
Indicates which compatibility required.
1
Behavior as in earlier versions of this Compiler. Ignores the PICTURE clause of the sending field.
2
De-edits according to the PICTURE clause of the sending field. This provides ANSI'85 conformance.

Properties:

Default: | DE-EDIT"2"
Phase: | Syntax check
$SET: | Any

Example:

 01 a  pic 909V99 value "30456".
 01 b  pic 9(5).
        ...
     move a to b

With DE-EDIT"1", b contains 30456. With DE-EDIT"2", b contains 00034; the 0 after the 3 is dropped because it corresponds to the insertion character 0 in the picture-string of a, and the .56 is dropped because B has no decimal places.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List
Related reference
DIALECT
Related information
Run-time Behavior - Compatibility with Older Micro Focus Products
The Special-Names Paragraph
The INITIALIZE Statement
Key to Compiler Directives


IOCONV

Selects between a straight group move and conversion of elementary record descriptions (ANSI behavior) when processing READ ... INTO and WRITE ... FROM statements.

Syntax:

>>-.---.-.----.--IOCONV--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | IOCONV
Phase: | Syntax check
$SET: | Any

Comments:

NOIOCONV causes a straight group move for READ ... INTO and WRITE ... FROM operations. This is for backward compatibility.

IOCONV causes conversion of elementary record descriptions when required. This is normal ANSI behavior, and the default.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


OLDBLANKLINE

Changes the behavior of the BLANK LINE clause in the Screen Section.

Syntax:

>>-.---.-.----.--OLDBLANKLINE--------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDBLANKLINE
Phase: | Syntax check
$SET: | Any

Comments:

When OLDBLANKLINE is specified, the BLANK LINE clause behaves exactly the same as ERASE EOL; that is all characters to the right of the cursor are deleted.

With NOOLDBLANKLINE specified, the BLANK LINE clause causes the whole line to be deleted.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


OLDINDEX

Causes indexes to be compiled as 16-bit binary integer subscripts.

This limits the maximum number of occurrences that can be accessed with an index to 65535. Therefore, you should not use this directive when compiling any program that declares a table with more than 65535 occurrences.

Syntax:

>>-.---.-.----.--OLDINDEX------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDINDEX
Phase: | Syntax check
$SET: | Initial

Dependencies:

NORM or DIALECT"RM" sets NOOLDINDEX immediately.

RM or RM"ANSI" sets OLDINDEX immediately.

Comments:

This directive is for compatibility with earlier products.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


OLDNEXTSENTENCE

Changes the behavior of the NEXT SENTENCE statement.

Syntax:

>>-.---.-.----.--OLDNEXTSENTENCE-----------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDNEXTSENTENCE
Phase: | Syntax check
$SET: | Any

Comments:

When OLDNEXTSENTENCE is specified, the NEXT SENTENCE statement behaves like a CONTINUE statement.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


OLDSTRMIX

Allows PIC X and PIC N fields to be specified in the same STRING, UNSTRING or INSPECT statement

Syntax:

>>-.---.-.----.--OLDSTRMIX---------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOOLDSTRMIX
Phase: | Syntax check
$SET: | Any

Comments:

This directive is provided for backward compatibility only.

We recommend that you do not use it as it can lead to unexpected results and the corruption of double-byte data.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List


SPZERO (deprecated)

Causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros.
Note:
  • SPZERO is deprecated, and provided for backward compatibility only; use SIGN-FIXUP instead.
  • This directive can adversely affect the performance of generated code.

Syntax:

>>-.---.-.----.--SPZERO--------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSPZERO
Phase: | Both
$SET: | Any

Comments:

With NOSPZERO, space characters in numeric data items give unpredictable results.

For managed COBOL, SPZERO combined with either HOST-NUMMOVE or HOST-NUMCOMPARE is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

Parent topic: Run-time Behavior - Compatibility with Older Micro Focus Products
Parent topic: Compiler Directives - Alphabetical List
Related reference
SIGN-FIXUP


Run-time Behavior - Compatibility with Other COBOL Dialects

  • ALPHASTART
    Sets the number from which the Compiler counts positions in the collating sequence when compiling the ALPHABET clause.
  • APOST
    Makes the Compiler interpret the figurative constant QUOTE as the single-quote character (').
  • CASE
    Prevents external symbols (such as Program-ID and names of called programs) being converted to upper case.
  • COMP1
    Specifies the behavior of a COMP-1 data item.
  • COMP2
    Specifies the behavior of a COMP-2 data item.
  • COMP-6
    Specifies whether COMP-6 data is to be held in binary or packed decimal format, or emulates ACUCOBOL-GT or RM/COBOL COMP-6 behavior.
  • COPYSEARCH
    Specifies how copybooks are located.
  • DBSPACE
    Makes the Compiler interpret the figurative constant SPACE, when used as a DBCS figurative constant, as the double-byte space character supplied by the system.
  • FDCLEAR
    Specifies that the record buffer for a file should be cleared after every write operation.
  • IBMCOMP
    Turns on word-storage mode.
  • INTDATE
    Selects the starting date for integer format dates used with date intrinsic functions.
  • ODOSLIDE
    Moves data items that follow a variable-length table in the same record as the table's length changes.
  • OPTIONAL-FILE
    Makes the Compiler treat all files opened for I-O or EXTEND as optional.
  • QUOTE
    Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").
  • RETRYLOCK
    Specifies that when a READ statement finds that a record is locked, the READ operation is to be retried repeatedly until the record is available.
  • RUNTIME-ENCODING
    Determines the run-time encoding.
  • SIGN
    Specifies the default convention for signs in signed numeric DISPLAY data items.
  • SOURCE-ENCODING
    Passes the encoding of the source program to the compiler.
  • SSRANGE
    Turns on bounds checking for reference modifications, subscripting and indexes.
  • STICKY-PERFORM
    Specifies the behavior of PERFORM statements when a program is reentered.
  • SWITCH-TYPE
    Makes programmable switches behave in the same way as in the ISO 2002 standard.
  • SYMBSTART
    Sets the number from which the Compiler counts positions in the collating sequence when compiling the SYMBOLIC CHARACTERS clause.
  • TRUNC
    Specifies whether data being stored into a USAGE COMP, USAGE BINARY or USAGE COMP-4 item is to be truncated to the size given by the item's PICTURE clause or to the maximum size the item can hold.
Parent topic: Run-time Behavior


ALPHASTART

Sets the number from which the Compiler counts positions in the collating sequence when compiling the ALPHABET clause.

Syntax:

>>-.---.--ALPHASTART--"integer"------------><
   +-/-+

Parameters:

integer The number to be used.

Properties:

Default: | ALPHASTART"1"
Phase: | Syntax check
$SET: | Initial

Comments:

For ANSI conformance use ALPHASTART"1".

Example:

With ALPHASTART"1", the COBOL statement:

alphabet myalpha is 66,  67

declares an alphabet consisting of "A" and "B" since, counting from 1, these are the 66th and 67th characters in the ASCII collating sequence. With ALPHASTART"0", MYALPHA consists of "B" and "C".

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


CASE

Prevents external symbols (such as Program-ID and names of called programs) being converted to upper case.

Syntax:

>>-.---.-.----.--CASE----------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | CASE
Phase: | Generate
$SET: | Any

Comments:

CASE leaves the case of external symbols as is. This is useful if you are calling a program written in C, where names are case dependent.

NOCASE folds external symbols to upper case.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


COMP1

Specifies the behavior of a COMP-1 data item.

Syntax:

>>--.---.-----COMP1"type"--------><
    +-\-+

Parameters:

type
The behavior of a data item of COMP-1 usage:
FLOAT
Micro Focus and IBM mainframe behavior, which is as a single precision floating point item.
BINARY
ACUCOBOL-GT and RM/COBOL behavior, which is as s9(4) COMP usage.

Properties:

Default: | COMP1"FLOAT"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM", RM"ANSI", or DIALECT"ACU" sets COMP1"BINARY" immediately.

Comments:

You can also default to COMP1"BINARY" behavior by setting the ACU compatible Compiler option ACUOPT(-Cv).

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


COMP2

Specifies the behavior of a COMP-2 data item.

Syntax:

>>--.---.-----COMP2"type"-------><
    +-\-+

Parameters:

type
The behavior of a data item of COMP-2 usage:
FLOAT
Micro Focus and IBM mainframe behavior, which is as a double precision floating point item.
DECIMAL
ACUCOBOL-GT COBOL behavior, which is that each digit is stored in one byte in binary format. If the value is signed, then an additional trailing byte is allocated for the sign. The storage of COMP-2 is identical with USAGE DISPLAY with the high-order four bits stripped from each byte.

Properties:

Default: | COMP2"FLOAT"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets COMP2"DECIMAL" immediately.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


COPYSEARCH

Specifies how copybooks are located.

Syntax:

>>-.---.--COPYSEARCH--"parameter"-----------------><
   +-/-+

Parameters:

MF
Sets standard copybook search behavior, which is that if you specify only the copybook name, for example, COPY "mycopyfbook.cpy", the Compiler looks in the same directory as the source file and any locations specified by the COBCPY directive to locate the copybook.
RM
Emulates the standard RM copybook search behavior:
  • If you specify only the copybook name, for example, COPY "mycopyfbook.cpy", the Compiler looks in the current COBOL working directory (i.e. where the program is run from), not the same directory as the source file, to locate the copybook.
  • If you specify the full path to the copybook, for example COPY "c:\mydir\mycopybook.cpy", the Compiler will only search for the copybook of that name and in that location.
RM-EXPANDED
Emulates RM/COBOL's EXPANDED-PATH-SEARCH behavior, which is the same as COPYSEARCH"RM" and additionally, if a copybook cannot be located when you use a relative path, the path is appended to the value(s) set by COBCPY to try and locate the copybook.

Properties:

Default: | COPYSEARCH"MF"
Phase: | Syntax check
$SET: | Initial

Dependencies:

DIALECT"RM" sets COPYSEARCH"RM" immediately.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


DBSPACE

Makes the Compiler interpret the figurative constant SPACE, when used as a DBCS figurative constant, as the double-byte space character supplied by the system.

Syntax:

>>-.---.-.--.----.--DBSPACE---------.---------><
   +-/-+ |  +-NO-+                  |
         |                          |
         +----------DBSPACE"MIXED"--+

Parameters:

none
With DBSPACE set (without any parameters), the Compiler uses the system-supplied double-byte space character. NODBSPACE provides compatibility with previous versions of this Compiler, where the double-byte space character was two ASCII space characters (x"2020").
MIXED
If a data item is compared for equality or inequality with the figurative constant SPACE by an IF, EVALUATE or PERFORM UNTIL statement, the following occurs:
  • If the data item is defined as PIC G or PIC N USAGE DISPLAY, it is equal to SPACE if each double-byte pair contains either a double-byte space or two single-byte spaces.
  • If the data item is alphanumeric, it is equal to SPACE if it contains any combination of single- and double-byte spaces. A double-byte space need not be aligned on a 2-byte boundary but must be complete and contained within the length of the data item.
  • If two data items of different lengths are compared for equality or inequality and no difference is found within the length of the shorter item, the remainder of the longer item will be compared to SPACE using the above semantics to provide the result.
The behavior of a program compiled with DBSPACE(MIXED) and CHARSET(EBCDIC) is undefined.

Properties:

Default: | Depends on the setting of MF"integer". If integer is greater than 7, the default is DBSPACE. Otherwise, it is NODBSPACE. (Dialect)
Phase: | Syntax check
$SET: | Initial

Dependencies:

DBSPACE set immediately by COBOL370, NCHAR"2", SAA, VSC2"2" or VSC2"3".

DBSPACE set immediately by MF"integer". If integer is greater than 7.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


ODOSLIDE

Moves data items that follow a variable-length table in the same record as the table's length changes.

Syntax:

>>-.---.-.----.--ODOSLIDE------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOODOSLIDE
Phase: | Syntax check
$SET: | Initial

Dependencies:

The ODOSLIDE directive is set at the end by the ODOOSVS Compiler directive.

Comments:

This affects data items that appear after a variable-length table in the same record; that is, after an item with an OCCURS DEPENDING clause, but not subordinate to it.

With ODOSLIDE, these items always immediately follow the table, whatever its current size; this means their addresses change as the table's size changes. With NOODOSLIDE, these items have fixed addresses, and begin after the end of the space allocated for the table at its maximum length.

Note: You cannot have boolean data items following a variable-length table in the same record. Also, you cannot have boolean data items after a variable-length table in the same record.
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related concepts
Nested OCCURS DEPENDING Clauses
Related information
Run-time Behavior - Compatibility with Other COBOL Dialects
File Description Entry Skeleton
Data Description Entry Skeleton
The OCCURS Clause
The RECORD Clause
The GO TO Statement
Key to Compiler Directives


RUNTIME-ENCODING

Determines the run-time encoding.

Syntax:

>>--.---.----RUNTIME-ENCODING--"encoding"-.-><

Parameters:

encoding
Possible values are:
ANSI
OEM
UTF8

Properties:

Default: | OEM
Phase: | Syntax check
$SET | Initial

Dependencies:

If this directive is not specified, the run-time encoding is determined by the SOURCE-ENCODING directive. In this case, if the source encoding is any of the possible UTF variants, the run-time encoding of PIC X data is always set to UTF-8.

Comments:

RUNTIME-ENCODING determines how strings are encoded into PIC X data and therefore does not include UTF-16 options.

Example:

$set RUNTIME-ENCODING"ANSI"
Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related reference
SOURCE-ENCODING


SIGN

Specifies the default convention for signs in signed numeric DISPLAY data items.

Syntax:

>>-.---.--SIGN--"convention"---------------><
   +-/-+

Parameters:

convention

For included signs, the sign storage convention must be one of:

  • ASCII
  • MF (identical to ASCII)
  • EBCDIC
  • IBM (identical to EBCDIC)
  • acu
  • mbp
  • ncr
  • realia
  • vax

or, for the default sign mode:

  • INCLUDED
  • TRAILING
  • SEPARATE
  • TRAILING-SEPARATE
  • LEADING
  • LEADING-SEPARATE

See Comments for more details.

Properties:

Default: | SIGN"ASCII" and SIGN"TRAILING"
Phase: | Syntax check
$SET: | Initial

Dependencies:

CHARSET"ASCII" sets SIGN"ASCII" immediately.

CHARSET"EBCDIC" sets SIGN"EBCDIC" immediately.

DIALECT"RM" sets SIGN"EBCDIC" and SIGN"TRAILING" immediately.

Comments:

The convention parameter options have the following meanings:

ASCII, MF
The Micro Focus storage convention.
EBCDIC, IBM
The IBM storage convention. It is compatible with IBM COBOL, RM/COBOL-85, and the X/Open COBOL standard.

For managed COBOL, SIGN"EBCDIC", along with one of HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP is an invalid combination of directives, and is rejected during compilation. For native COBOL, the combination is permitted.

acu
The ACUCOBOL-GT storage convention. This convention is also compatible with data produced by RM/COBOL (not RM/COBOL-85) and previous versions of ACUCOBOL-GT.
mbp
The MBP COBOL sign storage convention.
Important: The MBP COBOL sign storage convention for USAGE DISPLAY directly conflicts with that used by IBM COBOL and some other COBOLs. As a result, signed USAGE DISPLAY items in the MBP format are correctly understood only when the program is compiled the mbp option. This is unlike the other sign conventions in which the runtime can usually extract the correct value even when a mismatched sign convention is specified at compile time.
Restriction: MBP COBOL does not have the COMP-2 storage type.
ncr
This causes a different numeric format to be used. The format is the same as the one used when the EBCDIC or IBM option is used, except that positive COMP-3 items use x0B as the positive sign value instead of x0C. This option is compatible with NCR COBOL.
realia
The Realia sign storage convention. Sign information for S9(n) variables is stored using the conventions for Realia COBOL, and their conversion to binary decimal is the same as that performed by the Realia compiler.
vax
This creates numeric sign formats that are compatible with VAX COBOL. These are identical to the IBM formats, except that unsigned COMP-3 fields place x0C in the sign position instead of x0F.

The SIGN directive may be repeated to specify the sign storage convention for included signs and the default sign mode.

The sign modes INCLUDED and TRAILING both indicate a trailing included sign. The sign modes SEPARATE and TRAILING-SEPARATE indicate a trailing separate sign. The sign mode LEADING indicates a leading included sign. The sign mode LEADING-SEPARATE indicates a leading separate sign. The hyphen in the TRAILING-SEPARATE or LEADING-SEPARATE is optional.

If the hexadecimal value B is used as the internal sign representation, SIGN"ASCII" treats the data item as negative; some other COBOL systems (such as RM/COBOL) treat items represented this way as positive.

The default sign mode can be overridden by the NUMERIC SIGN clause in the special-names paragraph or the SIGN clause in a data description entry.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


SOURCE-ENCODING

Passes the encoding of the source program to the compiler.

Syntax:

>>------SOURCE-ENCODING--"encoding"--><

Parameters:

encoding
Possible values are:
ANSI
OEM
UTF8
Sets a UTF-8 runtime encoding of PIC X data unless RUNTIME-ENCODING is set explicitly.
UTF16 (UTF-16 native)
Sets a UTF-8 runtime encoding of PIC X data unless RUNTIME-ENCODING is set explicitly.
UTF16P (UTF-16 portable)
Sets a UTF-8 runtime encoding of PIC X data unless RUNTIME-ENCODING is set explicitly.

Properties:

Default: | SOURCE-ENCODING"ANSI"
Phase: | Syntax check
$SET | No

Dependencies:

This directive also sets the runtime encoding unless the RUNTIME-ENCODING directive is specified.

Comments:

SOURCE-ENCODING passes the encoding of the source program to the compiler. It is then used to determine the runtime encoding, unless the RUNTIME-ENCODING directive is specified.

SOURCE-ENCODING can be overridden if the source file includes a Unicode byte order mark (BOM) for UTF-8, UTF-16, portable or native.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related reference
RUNTIME-ENCODING


SSRANGE

Turns on bounds checking for reference modifications, subscripting and indexes.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.-SSRANGE-.----------.--.-------><
   +-/-+ |         +-"integer"+  |
         +-NOSSRANGE-------------+

Parameter:

integer
The level of SSRANGE support required. The possible values are:
1
At run-time, subscripts and indexes are checked to ensure they are not referencing an area outside the table, and reference modified items are checked for negative or zero value.
2
At both compile time and run time, subscripts, reference modified items, and indexes are checked to ensure they are not referencing an area outside the table.
3
As SSRANGE"2", except that reference modifies lengths of zero are permitted at run time. However, if a reference modified length is known to be zero at compile time, an error is generated.

Properties:

Default: | NOSSRANGE
Phase: | Syntax check
$SET: | Initial

Dependencies:

Sets BOUND immediately

Comments:

This directive is provided for emulation of the IBM mainframe compiler of the same name; because of this, its scope is limited to the syntax permissible in a mainframe dialect.

If you set SSRANGE without an integer, the behavior is the same as SSRANGE"2".

For unbounded groups or their subordinate items, checking is done only for reference modification expressions. Subscripted or indexed references to tables subordinate to an unbounded group are not checked.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related information
BOUND
Key to Compiler Directives


STICKY-PERFORM

Specifies the behavior of PERFORM statements when a program is reentered.

Syntax:

>>-.---.-.----.--STICKY-PERFORM------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSTICKY-PERFORM
Phase: | Syntax check
$SET: | Initial

Comments:

This directive has an effect only if your program was compiled with either PERFORM-TYPE"OSVS" or PERFORM-TYPE"RM" specified.

If you specified PERFORM-TYPE"OSVS" or PERFORM-TYPE"RM" when compiling, PERFORM statements are implemented by having a storage area, or bucket, associated with each place in the program that can be the end of a PERFORM statement's range. When a PERFORM statement is executed the return address is stored in the bucket, and at the end of the PERFORM statement's range the bucket is read to determine where control should return to and then cleared.

By default, an EXIT PROGRAM statement clears these buckets, so that if the program is reentered, none of the return addresses of the previously executed PERFORM statements remains. Specifying STICKY-PERFORM stops the buckets from being cleared by an EXIT PROGRAM statement. This means that on reentry, the return addresses of all previously executed PERFORM statements remain.

A STOP RUN or CANCEL statement clears the buckets regardless of the setting of this directive.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


SWITCH-TYPE

Makes programmable switches behave in the same way as in the ISO 2002 standard.

Syntax:

>>-.---.-.----.--SWITCH-TYPE--"integer"-------------------><
   +-/-+ +-NO-+

Parameters:

integer
One of:
1
Behavior of this COBOL system
2
ISO 2002 behavior
3
Siemens BS2000 COBOL behavior

Properties:

Default: | SWITCH-TYPE"1"
Phase: | Syntax check
$SET: | Any

Comments:

In the ISO 2002 standard, and the Siemens BS2000 COBOL dialect, switches persist and are visible throughout a run unit. For example, if program A calls program B then any changes to the switches in A are visible when B is called, and any changes made in B are visible in A when control returns to A. If, however, A terminates and B is called, then the changes made by A are lost. The space in which the switches are stored can be regarded as common to all programs in a run unit; hence changes to the switches are visible to all programs.

In this COBOL system, and older versions of Micro Focus COBOL, any called subprogram (in this case B) has its own set of COBOL switches independent of any other program. If program A calls program B, program B's switches are set to the same values as A's were at program start - ignoring any changes A might have made to the switches. When control returns to program A, A's switches are exactly the same as they were before program control changed - ignoring any changes B might have made to the switches. B's switches are preserved (unless it is canceled), so that if invoked again its own switches are set as when it called A. In this case, the space in which switches are stored can be regarded as unique to each program.

SWITCH-TYPE"3" supports the Siemens BS2000 COBOL TSW-n and USW-n switches.

You should only use SWITCH-TYPE"3" when the BS/2000 add-on is present to provide the necessary run-time support.

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - Compatibility with Other COBOL Dialects
DIALECT
BS2000
Key to Compiler Directives


SYMBSTART

Sets the number from which the Compiler counts positions in the collating sequence when compiling the SYMBOLIC CHARACTERS clause.

Syntax:

>>-.---.--SYMBSTART--"integer"-------------><
   +-/-+

Parameters:

integer The number to be used.

Properties:

Default: | SYMBSTART"1"
Phase: | Syntax check
$SET: | Initial

Comments:

For ANSI conformance use SYMBSTART"1"; for compatibility with previous products use SYMBSTART"0".

Example:

With SYMBSTART"1", the COBOL statement:

symbolic characters bee is 67

declares a symbolic character bee representing "B" since, counting from 1, "B" is the 67th character in the ASCII collating sequence. With SYMBSTART"0", bee represents "C".

Parent topic: Run-time Behavior - Compatibility with Other COBOL Dialects
Parent topic: Compiler Directives - Alphabetical List


Run-time Behavior - Speed or Size

  • ALIGN
    Specifies the memory boundaries on which data items of level-01 or level-77 are aligned.
  • BOUND
    Specifies that subscript or index values are to be checked to ensure they are within the limits defined by their OCCURS clause.
  • BOUNDOPT
    Optimizes the code generated for subscripts.
  • CHECK
    Turns on all run-time checks in generated code.
  • CHECKREFMOD
    Turns on bounds checking for reference modification in managed COBOL.
  • FCDALIGN
    Ensures the memory boundaries of the file control descriptions (FCDs) associated with SYSIN, SYSOUT and SYSPUNCH files are aligned in the same way as other FCDs and internal structures.
  • FIXOPT
    Changes the way in which generated code accesses the Data Division in object (.obj) code.
  • LINKALIAS
    Lets the user provide assurances to the compiler about how linkage items will be used, to aid optimization.
  • LINKCHECK
    Specifies that each time a Linkage Section item is referenced a check is to be made that it exists.
  • MFSYNC
    Synchronizes items based on their size.
  • PARAMCOUNTCHECK
    Enables the program to be called with fewer parameters than are specified in the relevant entry point's USING clause.
  • PERFORMOPT
    Determines if the Compiler should optimize out code to PERFORM empty paragraphs in generated native code.
  • RECURSECHECK
    Turns on checking for recursion in generated code.
Parent topic: Run-time Behavior


ALIGN

Specifies the memory boundaries on which data items of level-01 or level-77 are aligned.

Syntax:

>>-.---.--ALIGN--"integer-.-------.-"-----------------><
   +-/-+                  +-FIXED-+
                          +--OPT--+

Parameters:

integer | The distance from the start of one level-01 to the start of the next is a multiple of this. Can take any value from 1 to 255.
OPT | FIXED | OPT aligns the 01 level item on a multiple of integer best suited for its size (see table below). This allows more optimal instructions to be used at machine code level for such data items. Note: For managed COBOL code, OPT behaves as if FIXED is set. FIXED aligns the 01 level item on the next multiple of integer.

Properties:

Default: | ALIGN"8 OPT"
Phase: | Syntax check
$SET: | Initial

Dependencies:

IBMCOMP or NORM sets ALIGN"8 OPT" immediately.

DIALECT"RM" sets ALIGN"4 FIXED" immediately.

RM"ANSI" or RM sets ALIGN"2 FIXED" immediately.

Comments:

Data items of level-01 are aligned on byte boundaries that are multiples of the value given.

This can help produce more efficient execution results but does mean more memory might be used.

The following table show the boundary on which an item will be aligned depending on their size and the directive setting

01 level item size | ALIGN"1 OPT" | ALIGN"2 OPT" | ALIGN"4 OPT" | ALIGN"8 OPT" | ALIGN"16 OPT"
1 | 1 | 2 | 4 | 8 | 16
2-3 | 2 | 2 | 4 | 8 | 16
4-7 | 4 | 4 | 4 | 8 | 16
8-15 | 8 | 8 | 8 | 8 | 16
>=16 | 16 | 16 | 16 | 16 | 16

Setting integer to a number that is not a multiple of four could impair the efficiency of the generated code. Under ALIGN(integer OPT), integer should be a power of 2, and will be increased to the next power of 2 if not (to a max value of 16).

If your program accesses data beyond the size of the 01-level item into the next or previous 01-level group, then you will need to use ALIGN(integer FIXED) to preserve the fixed alignment between 01-level items. However, such code is not ANSI Standard compliant, is not guaranteed to work in all circumstances, may interfere with some optimizations, and won't work in managed COBOL.

Limitations:

If the 01-level group contains the following level-78 syntax, then the 01-level item will only be aligned according to the value of the ALIGN directive and not its size:

01 grp1.
78 constant-01 value next.
78 constant-01 value start grp1.

This is because the next/start record the data address before items are aligned according to their size.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
DIALECT
Key to Compiler Directives


BOUND

Specifies that subscript or index values are to be checked to ensure they are within the limits defined by their OCCURS clause.

Syntax:

>>-.---.-.----.--BOUND---------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | BOUND
Phase: | Both
$SET: | Initial

Dependencies:

BOUND sets NOBOUNDOPT at end.

Set to BOUND by CHECK.

Comments:

For multi-dimensional tables, only the composite subscript is checked. If any of the individual subscripts or indices is beyond its limit, but the reference remains within the table, no error is produced.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
Table Bound Checking
DIALECT
Run-time Behavior - Speed or Size
BOUNDOPT
Data Description Entry Skeleton
The OCCURS Clause
Screen Section Entry Skeleton
The OCCURS Clause in the Screen Section
Key to Compiler Directives


BOUNDOPT

Optimizes the code generated for subscripts.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--BOUNDOPT------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | BOUNDOPT
Phase: | Generate
$SET: | Initial

Dependencies:

Set to NOBOUNDOPT at end by BOUND.

Comments:

If BOUNDOPT is used, subscripts can be optimized on the assumption that they do not exceed the bounds of the table. In particular, any digits in a subscript above the size of the table may be ignored.

Can only be used when NOBOUND is specified. NOBOUNDOPT must be specified if a program references beyond the end of a table.

Example:

For a table with 50 entries, a PIC 9(3) subscript is treated as PIC 9(2), with the most significant digit ignored.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
Table Bound Checking


CHECKREFMOD

Turns on bounds checking for reference modification in managed COBOL.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-.---.-.----.--CHECKREFMOD-------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOCHECKREFMOD
Phase: | Check
$SET: | Initial
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives


FCDALIGN

Ensures the memory boundaries of the file control descriptions (FCDs) associated with SYSIN, SYSOUT and SYSPUNCH files are aligned in the same way as other FCDs and internal structures.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--FCDALIGN------------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOFCDALIGN
Phase: | Check
$SET: | Any
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
Key to Compiler Directives
File Control Description (FCD)
ALIGN


LINKALIAS

Lets the user provide assurances to the compiler about how linkage items will be used, to aid optimization.

Syntax:

>>-.---.---LINKALIAS-"type"---><
   +-/-+

Parameters:

One of:
all
No assurances.
paramdisjoint
Parameters are assumed to be disjoint.
none
Linkage items will not be used to reference local-, thread-local- or working-storage, and incoming parameters are disjoint

Properties:

Default: | LINKALIAS"ALL"
Phase: | Generate
$SET: | Initial
Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List
Related information
Run-time Behavior - Speed or Size
Configuration Section
Input-Output Section
General Description
Working-Storage Section
Thread-Local-Storage Section
Object-Storage Section
Local-Storage Section
Linkage Section
Screen Section
Procedure Division General Description
The EXIT Statement
Input-Output Section
Report Section
Key to Compiler Directives


MFSYNC

Synchronizes items based on their size.

Syntax:

>>-.---.-.----.--MFSYNC-"integer"---------><
   +-/-+ +-NO-+

Parameters:

integer
The synchronization value defines the maximum synchronization boundary on which items will by synchronized (based on their size):
2 will synchronize:
2 byte comp/comp-x/comp-5 sync
pic x(4) comp/comp-x/comp-5 sync
pic x(8) comp/comp-x/comp-5 sync
 on boundary:
 2
 2
 2
4 will synchronize:
2 byte comp/comp-x/comp-5 sync
pic x(4) comp/comp-x/comp-5 sync
pic x(8) comp/comp-x/comp-5 sync
 on boundary:
 2
 4
 4
8 will synchronize:
2 byte comp/comp-x/comp-5 sync
pic x(4) comp/comp-x/comp-5 sync
pic x(8) comp/comp-x/comp-5 sync
 on boundary:
 2
 4
 8

Properties:

Default: | NOMFSYNC
Phase: | Syntax check
$SET: | Initial

Dependencies:

If MFSYNC is specified alone (that is, without a qualifier) the effect will be as if MFSYNC"4" was specified.

Comments:

Applying the MFSYNC directive on a compilation unit can improve code generation and execution speed considerably. However, applying MFSYNC to a program that was developed without consideration for the MFSYNC effect on Data Division and record layout could have a detrimental effect on the program’s semantics.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


PERFORMOPT

Determines if the Compiler should optimize out code to PERFORM empty paragraphs in generated native code.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.--PERFORMOPT---------------------><
   +-/-+

Parameters:

None

Properties:

Default: | PERFORMOPT
Phase: | Generate
$SET: | Initial

Comments:

For greatest efficiency the Compiler normally does not generate code for a PERFORM statement that references an empty paragraph. If you require the code to be left in, for example for timing purposes, specify NOPERFORMOPT.

Parent topic: Run-time Behavior - Speed or Size
Parent topic: Compiler Directives - Alphabetical List


Key to Compiler Directives

Descriptions for all of the Compiler directives appear alphabetically. Each description contains the following entries.

DIRECTIVE-NAME
A brief description of the function of DIRECTIVE-NAME.
Syntax
Syntax in the form:
                                +--------------+
                                V              |
>>-.---.-.-------DIRECTIVE-NAME--"parameter(s)"-.-><
   +-/-+ +.----.-DIRECTIVE-NAME-----------------+
          +-NO-+

The syntax of the directives is shown using diagrams called "railroad tracks", in which a directive and its parameters are shown joined by lines indicating the order in which they should be written. You read these diagrams from left-to-right. Each diagram starts with >> and ends with ><. Sometimes the track forks to show alternatives and then joins up again. The length of a track has no significance.

The loop over the parameter in the above example indicates that it can be repeated one or more times.

Parameters for directives are shown in quotation marks (" "), although you can use parentheses instead unless otherwise stated.

If a parameter is specified after a comma, but the filename is omitted, the directive must be preceded by a slash (/). Otherwise, the directive is incorrectly assumed to be a filename.

When writing the names of Compiler directives, you can use hyphens to improve their readability. A directive that contains hyphens is handled in exactly the same way as a directive that does not; for example, DPC-IN-SUBSCRIPT is the same as DPCINSUBSCRIPT.

Parameters
Lists and describes valid parameter(s), if any, for the directive.
Properties
Default: Indicates the directive's default setting. If you set the DIALECT directive to a particular value, some other directives are set to a value that overrides either the default, or any value to which you have the directives. Directives that are set by DIALECT are indicated by (DIALECT ). Click the link to display the DIALECT page to check the dialect-specific setting. For more information on using the DIALECT directive to set directives, see The DIALECT Directive.
Phase: Shows the phase controlled by this directive. One of:
  • Syntax check
  • Generate
  • Both
$SET: Shows whether you can put the directive on a $SET statement in your source program; "Initial" in this entry means it is only allowed on a $SET statement before the first line of COBOL code. The directives specified by a $SET statement in the source code must not exceed column 72.
Dependencies
Shows if the setting of this directive changes the setting of any other directives, or if any other directives affect the setting of this directive.
There are a number of different cases, identified under this heading by the following keywords:
immediately | The change specified is done immediately, as a part of the processing of this directive. This enables you to reset the value by specifying the second directive after the first. Don't do this unless you know what you are doing.
at end | The change specified takes place when all the directives have been processed. This prevents you from overriding the new value.
Comments
Contains any additional information about the directive.
Parent topic: Compiler Directives


Compiler Directives - Alphabetical List

  • ACCEPTREFRESH
    Specifies whether the data areas associated with Screen Section data are updated from their corresponding Working-Storage Section items before an ACCEPT statement.
  • ACTUAL-PARAMS
    Specifies actual parameters that are substituted for formal parameters in a parameterized class or interface.
  • ACU
    Enables compatibility with ACUCOBOL-GT COBOL.
  • ACUOPT
    Enables you to set various options specifically for compilation of ACUCOBOL-GT applications.
  • ACU-COMMENT
    Treats lines of code starting with a pipe (|) as comment lines.
  • ACUSYNC
    Changes the effect of the SYNC clause so that it matches that used in ACU programs.
  • ACU-UNDERSCORE
    Treats underscores in COBOL words as hyphens.
  • ADDRSV
    Adds one or more specific reserved words to the reserved word list so that they are recognized as reserved words in your program. The specified reserved words are added, whatever dialect directives are in force.
  • ADDSYN
    Defines a user-defined reserved word to be synonymous with an existing reserved word.
  • ADV
    Causes a control character to be inserted at the start of each line in a print file. This is for compatibility with mainframe operation.
  • ALIGN
    Specifies the memory boundaries on which data items of level-01 or level-77 are aligned.
  • ALPHASTART
    Sets the number from which the Compiler counts positions in the collating sequence when compiling the ALPHABET clause.
  • ALTER
    Allows ALTER statements in your program.
  • ANIM
    Makes the Compiler produce extra information so that you can debug your program.
  • ANS85
    Specifies that words reserved in the ANSI'85 COBOL Standard are to be treated as reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that Standard.
  • APOST
    Makes the Compiler interpret the figurative constant QUOTE as the single-quote character (').
  • AREACHECK
    Causes the Compiler to treat any token which starts in area A in the Procedure Division as a paragraph or section label, regardless of the preceding tokens.
  • ARITH
    Defines the maximum number of digits for numeric data items.
  • ARITHMETIC
    Specifies how arithmetic expressions are to be evaluated.
  • ASSIGN
    Specifies how to assign a filename when neither EXTERNAL nor DYNAMIC appear in the SELECT statement.
  • ASSIGN-PRINTER
    Specifies how to assign the output from an ASSIGN TO PRINTER clause when the clause does not specify a filename.
  • AUTOLOCK
    Makes the default locking AUTOMATIC rather than EXCLUSIVE for files opened for INPUT, I-O, or EXTEND in a multi-user environment.
  • BELL
    Makes the bell sound at points such as when compilation stops, either because of an error or because it has finished.
  • BINLIT
    Controls whether binary b"" literals are interpreted as numeric values, or Boolean values for use with PIC 1 data items.
  • BOUND
    Specifies that subscript or index values are to be checked to ensure they are within the limits defined by their OCCURS clause.
  • BOUNDOPT
    Optimizes the code generated for subscripts.
  • BRIEF
    Enables the Compiler to produce only error numbers, and no message texts.
  • BS2000
    Ensures that words reserved under the Siemens BS2000 COBOL dialect are reserved words in this COBOL system, and changes the behavior of certain features to be compatible with that COBOL dialect.
  • BWZSTAR
    Determines whether the BLANK WHEN ZERO clause is allowed in the Data Division for those fields defined with the "*" PICTURE symbol.
  • BYTE-MODE-MOVE
    Controls behavior for alphanumeric moves between overlapping data items.
  • CALL-RECOVERY
    Specifies the behavior when control is returned to a program.
  • CALLFH
    Makes the Compiler generate direct calls for all file I/O operations, using the Callable File Handler interface.
  • CALLSORT
    Defines the program to be called to handle all SORT and MERGE operations.
  • CANCEL
    This directive may appear in source code supplied by Micro Focus. NOCANCEL stops sub-programs being canceled by the RTS for CANCEL and CHAIN statements and other circumstances when the main user application is canceled.
  • CANCELLBR
    Makes the Compiler close an .lbr file used as a library in a COPY statement once that copy operation is complete.
  • CASE
    Prevents external symbols (such as Program-ID and names of called programs) being converted to upper case.
  • CHANGE-MESSAGE
    Changes the severity of errors/messages. Messages can also be suppressed or returned to their original severity.
  • CHARSET
    Defines the character set of the environment.
  • CHECK
    Turns on all run-time checks in generated code.
  • CHECKDIV
    Controls the behavior of your program if it tries to divide by zero in a statement that has no ON SIZE ERROR phrase.
  • CHECKNUM
    Checks whether numeric fields contain valid data before performing operations on them.
  • CHECKREFMOD
    Turns on bounds checking for reference modification in managed COBOL.
  • CMPR2
    Provides compatibility with the mainframe compiler option of the same name, which returns behavior of the COBOL 370, VS COBOL II version 3 and VS COBOL II version 4 compilers to that of the VS COBOL II version 2 compiler.
  • COBFSTATCONV
    Causes the Callable File Handler to use the user-supplied module specified in the COBFSTATCONV environment variable to convert the file status codes if an I/O error is encountered on a file.
  • COBIDY
    Specifies the path where the .idy file is to be written.
  • COBOL370
    Specifies that words reserved in IBM COBOL/370 are to be treated as reserved words, and allows features selectively for compatibility with a given level of that product.
  • COBOLDIR
    Specifies whether the Compiler should process the directives in a cobol.dir file or ignore it.
  • COLLECTION
    Provides a mechanism for code coverage to identify unexecuted programs.
  • 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.
  • COMP
    Makes the compiler produce very compact and efficient code for some statements involving COMP data items, by treating COMP items as COMP-X or sets the representation meant by COMP usage in a data description entry.
  • COMP1
    Specifies the behavior of a COMP-1 data item.
  • COMP2
    Specifies the behavior of a COMP-2 data item.
  • COMP-5
    Specifies whether the sign is to be dropped when a value is stored in an unsigned COMP-5 data item.
  • COMP-6
    Specifies whether COMP-6 data is to be held in binary or packed decimal format, or emulates ACUCOBOL-GT or RM/COBOL COMP-6 behavior.
  • CONFIRM
    Makes the Compiler echo all subsequent directives to the screen.
  • CONSTANT
    Declares a constant for use in the program.
  • CONVERTRET (deprecated)
    Causes COMP and COMP-X items specified in CALL ... RETURNING and EXIT PROGRAM ... RETURNING phrases to be converted to COMP-5.
  • CONVSPACE
    Converts double-byte space characters in COBOL source files to single-byte spaces on input.
  • COPYEXT
    Specifies the filename extension of the copybook that the Compiler is to look for if a filename in a COPY statement is specified without an extension.
  • COPYLBR
    Makes the Compiler treat the library specified in a COPY statement as an .lbr file.
  • COPYLIST
    Makes the Compiler list the contents of files named in COPY statements.
  • COPYLISTCOMMENT
    Specifies the type of comment to be used on COPY statements in .lst files when the COPYLIST directive is specified.
  • COPYPATH
    Specifies a list of directories for the Compiler to search for copy files.
  • COPYSEARCH
    Specifies how copybooks are located.
  • CSI
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • CURRENCY-SIGN
    Specifies the currency sign to be recognized in the PICTURE clause.
  • CURRENT-DATE
    Specifies the format of the date stored in the CURRENT-DATE special register.
  • DATA
    Enables AMODE"24" programs to access pointers to Data Division items passed to them by AMODE"31" programs.
  • DATACOMPRESS
    Specifies the type of data compression to be done on sequential and indexed files.
  • DATA-CONTEXT
    Enables you to specify how a program's Data Division is to be maintained between CICS link levels.
  • DATAMAP
    Causes the Compiler to output information on data items.
  • DATE
    Puts the date in the Date-Compiled paragraph and at the top of each page of the listing.
  • DB2
    Causes EXEC SQL statements in your program to be replaced with DB2 LUW API calls.
  • DBCHECK
    Makes the Compiler check that any Double-byte Character Set (DBCS) literals only contain valid 16-bit DBCS characters.
  • DBCS
    Makes the Compiler accept characters of the Double-byte Character Set (DBCS) for use in ideographic languages such as Japanese, Chinese and Korean.
  • DBCSSOSI
    Defines the two characters used as the shift-out and shift-in delimiters in DBCS literals.
  • DBSPACE
    Makes the Compiler interpret the figurative constant SPACE, when used as a DBCS figurative constant, as the double-byte space character supplied by the system.
  • DE-EDIT
    Specifies the behavior of de-editing moves from numeric-edited items to other numeric-edited items or to numeric items.
  • DEFAULTBYTE
    Initializes each otherwise undefined byte of the Working-Storage Section to the character given.
  • DEFAULTCALLS
    Specifies the default calling convention.
  • DEFINE
    Declares a compilation variable to be used in ISO2002 conditional compilation.
  • DETECT-LOCK
    Makes READ statements detect when a record is locked by another program.
  • DG
    Changes the behavior of certain features to be compatible with Data General Interactive COBOL rev 1.30.
  • DIALECT
    Enables check-time and run-time behavior consistent with the specified dialect.
  • DIRECTIVES, DIR
    Makes the Compiler read directives from a file.
  • DIRECTIVES-IN-COMMENTS
    Makes the Compiler process $SET statements held in comment lines.
  • DISPLAY
    Defines the default behavior of standard DISPLAY statements.
  • DISPSIGN
    Determines the display output of numeric fields with included signs, under an IBM mainframe dialect only. (This directive emulates the mainframe option of the same name.)
  • DOSVS
    Specifies that words reserved in IBM DOS/VS COBOL are to be treated as reserved words.
  • DPC-IN-SUBSCRIPT
    Turns on or off DECIMAL-POINT IS COMMA when processing subscripts.
  • DYNAM
    Specifies that CANCEL statements are not to be ignored.
  • EBC-COL-SEQ
    Determines the EBCDIC collating sequence activated by the NATIVE"EBCDIC" option.
  • ECHO
    Makes the Compiler display error lines and error messages on the screen.
  • ECHOALL
    Sends a full listing to the screen as well as to a printer or other device specified with the LIST or PRINT directive.
  • ENTCOBOL
    Specifies that words reserved in IBM Enterprise COBOL for z/OS and OS/390 are to be treated as reserved words..
  • EOF-1A
    Treats a 0x1a character in the source file as the end of file.
  • ERRFORMAT
    Specifies the type of error message format to be used for command-line compilations and to appear in the list file.
  • ERRLIST
    Specifies the format of error messages in a list file.
  • ERRQ
    Enables the Compiler to prompt you to stop compiling each time it gives an error message.
  • EXITPROGRAM
    Determines how the EXIT PROGRAM statement is executed.
  • FASTCALL
    Controls the behavior of a called program. If FASTCALL is specified, the program does not set up information to allow it to determine whether it is a main program. The program always assumes that it is not a main program, and EXIT PROGRAM will always cause an exit to the calling program.
  • FASTINIT
    Turns on fast INITIALIZE of tables. FASTINIT renders as undefined any table contents that a normal INITIALIZE statement would not change.
  • FASTLINK
    Tells the Compiler that the parameters in the USING clauses of the Procedure Division statement and each ENTRY statement conform to certain restrictions. This enables it to produce faster code.
  • FASTSORT
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • FCD3
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • FCDALIGN
    Ensures the memory boundaries of the file control descriptions (FCDs) associated with SYSIN, SYSOUT and SYSPUNCH files are aligned in the same way as other FCDs and internal structures.
  • FCDCAT
    Specifies whether the catalogued file information for a file is used when accessing that file.
  • FDCLEAR
    Specifies that the record buffer for a file should be cleared after every write operation.
  • FCDREG
    Makes the Compiler define special registers giving access to File Control Descriptions (FCD) and Key Definition Blocks.
  • FILESHARE
    Causes the default locking to become AUTOMATIC rather than EXCLUSIVE for files in a multi-user environment, and automatically locks records on a WRITE or REWRITE statement when the program is locking multiple records.
  • FILETYPE
    Specifies the file format to use when creating files.
  • FIXOPT
    Changes the way in which generated code accesses the Data Division in object (.obj) code.
  • FLAG
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified dialect of COBOL.
  • FLAGAS
    Makes the Compiler output flagging messages as error messages, warning messages or informational messages.
  • FLAGEUC
    Flags occurences of SBCS (8-bit codes) and certain occurences of DBCS (16-bit codes) in the source code.
  • FLAGMIG
    Causes the Compiler to flag any syntax that behaves differently at run time depending on the setting of CMPR2.
  • FLAGQ
    Enables the Compiler prompt you to stop compiling each time it gives a flagging message.
  • FLAGSINEDIT
    Specifies whether flagging messages are to be included in an error file.
  • FLAGSTD
    Makes the Compiler produce language-level certification flags when it finds syntax that is not part of a specified level of the ANSI'85 Standard.
  • FOLD-CALL-NAME
    Folds the identifier/literal associated with CALL, CANCEL, ENTRY, and CHAIN statements and the program-name in the PROGRAM-ID paragraph to upper or lower case.
  • FOLD-COPY-NAME
    Determines whether copybook names should be converted to upper case or lower case.
  • FORM
    Specifies the number of lines on each page of the listing.
  • FP-ROUNDING
    Determines whether one floating-point receiving item can affect the results of other, nonfloating-point receiving items.
  • GNTLITLINKSTD
    In an Intel x86 32-bit environment, a CALL statement from a .gnt file that has both call-convention 2 and call-convention 8 in effect, suppresses call-convention 8 by default. Set this directive to prevent the suppression.
  • HIDE-MESSAGE
    Registers an error message to hide so that if the error is encountered, it is ignored.
  • HOSTARITHMETIC
    Controls whether or not decimal truncation of arithmetic results occurs following a size error condition.
  • HOSTCONTZERO
    For files defined with the RECORD CONTAINS"0" clause, this directive instructs the File Handler to take the record length from the catalog rather than the file description entry.
  • HOSTFD
    Specifies that the record area associated with a file should only be allocated at the time of an OPEN statement and not before.
  • HOST-NUMCOMPARE
    Controls the operation of comparisons involving numeric data items.
  • HOST-NUMMOVE
    Ensures that run-time error 163 (illegal characters in numeric fields) does not occur when certain MOVE statements are executed on numeric display data items or numeric operands.
  • HOSTRW
    Causes Report Writer to produce mainframe print files with the full range of ASA characters.
  • IBM-MS
    Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • IBMCOMP
    Turns on word-storage mode.
  • IDENTIFIERLEN
    Specifies the portion of an identifier name that the compiler will consider to be significant.
  • IDXFORMAT
    Specifies the format to use when creating or opening indexed files.
  • IDYSRCPATH (deprecated)
    Controls the paths stored in .idy files for main source files.
  • IGNOREEXEC
    Specifies that procedural EXEC statements are to be treated as documentary only.
  • ILARRAYPROPERTY
    Controls the way in which the Compiler generates code for data items that include the PROPERTY phrase, and which either include the OCCURS phrase or are subsidiary to a group item with the OCCURS clause.
  • ILASSEMBLY
    Specifies the name of the assembly created.
  • ILCLR
    Allows a managed program to be compiled for Microsoft's Common Language Runtime (CLR) version 2.0 or 4.0.
  • ILCOMPANY
    Defines the company name custom attribute in the assembly manifest.
  • ILCOPYRIGHT
    Defines the copyright custom attribute in the assembly manifest.
  • ILCULTURE
    Defines the culture custom attribute in the assembly manifest.
  • ILCUTPREFIX
    Removes a specified prefix from the names of the COBOL data items in your source code.
  • ILDELAYSIGN
    Indicates whether to reserve space in the assembly for the strong name signature, or to defer the actual signing until later.
  • ILDESCRIPTION
    Defines the description attribute in the assembly manifest.
  • ILDOC
    Generates documentation in xml format using comments in the code, and puts the documentation in the specified file.
  • ILDYNCALL
    Specifies that CALL literal statements are resolved at run time rather than being resolved at compile time.
  • ILEXPONENTIATION
    Enables you to optimize exponential arithmetic operations by specifying the calculation method used.
  • ILFILEVERSION
    Instructs the compiler to use a specific version number for the Win32 file version.
  • ILGEN
    Generates the IL for a program with a main program entry point or for a library without one.
  • ILICON
    Adds the specified icon to the output program.
  • ILINCREMENTALBUILD
    Identifies and compiles only the programs that have changed since the previous compilation.
  • ILKEYFILE
    Specifies a key file, which contains a key or public/private key pair for strong naming an assembly.
  • ILKEYNAME
    Specifies the container of a key or key pair that has been installed in the Crypto Service Provider (CSP).
  • ILMAIN
    Specifies the entry method for the executable program being compiled.
  • ILMANIFEST
    Selects a manifest generation option when the application runs on Windows Vista under User Account Control (UAC).
  • ILNAMESPACE
    Specifies the default namespace for items such as classes when building a project.
  • ILNATIVE
    Exposes COBOL 01 level data items as managed primitives where possible.
  • ILNATIVERESOURCE
    The resource file you specify will be included in the resulting output file.
  • ILNORMALIZENAMES
    Determines the program elements that are normalized when a procedural COBOL program is compiled to managed code. Normalization in this context results in replacing all $ and - (hypen) characters in the name with _ (underscore) characters.
  • ILOBJECTIFY (deprecated)
    ILOBJECTIFY is deprecated, and supported for backward compatibility only.
  • ILOPTIMIZEDATA
    Causes the Compiler to optimize any numeric data item to a native managed type (typically a 32-bit or 64-bit integer) when it determines that it is safe to do so.
  • ILOUTPUT
    Sets the path of the output assembly file or Java class file.
  • ILPARAMS
    Determines the way in which you call a method that contains an array as its last receiving parameter.
  • ILPINVOKE
    Makes the specified unmanaged code available, so that the entry points in the unmanaged code are available to the program being compiled.
  • ILPRODUCT
    Defines the product name custom attribute in the assembly manifest.
  • ILPRODUCTVERSION
    Instructs the compiler to use a specific version number for the Win32 product file version.
  • ILREF
    This directive permits the definition of extension methods and extension operators that are outside of the current compilation unit.
  • ILRESOURCE
    Specifies a resource file to embed in the assembly file when it is culture neutral.
  • ILSHOWPERFORMOVERLAP
    Generates a warning when an overlapping PERFORM range is detected in the program.
  • ILSMARTLINKAGE
    Exposes the linkage section and entry points in procedural COBOL programs to managed code, by creating types.
  • ILSMARTNEST
    Use in conjunction with ILSMARTLINKAGE, to expose the Linkage Section items and entry points to managed code as nested classes of the program class in which they are defined.
  • ILSMARTRESTRICT
    Limits the generation of properties in ILSMARTLINKAGE classes to non-redefining elementary items.
  • ILSMARTSERIAL
    Use in conjunction with ILSMARTLINKAGE. Makes the classes generated with ILSMARTLINKAGE serializable.
  • ILSMARTTRIM
    This directive works in conjunction with ILSMARTLINKAGE, where it trims any trailing spaces from a string item returned by the get property associated with an alphanumeric item processed by ILSMARTLINKAGE.
  • ILSOURCE
    Specifies an additional COBOL source file to be compiled together with the current program into a single .NET assembly or Java class file.
  • ILSTACKSIZE
    Sets the size of the stack when the program is run.
  • ILTARGET
    Enables an application to target a specified CPU type.
  • ILTITLE
    Defines the title custom attribute in the assembly manifest.
  • ILTRADEMARK
    Defines the trademark custom attribute in the assembly manifest.
  • ILUSING
    Specifies the namespace for a class to be imported. This directive enables you to write just the class name in the program code, without its namespace, potentially making the code shorter and simpler.
  • ILVERIFY
    Ensures that the compiled IL code is verifiable.
  • ILVERSION
    Specifies the version of the assembly.
  • IMPLICITSCOPE
    Enables the syntax checker to produce warning messages for cases where scope has been implicitly ended. This usually occurs where the scope terminator (END-VERB) could have been used.
  • INDD
    Causes ACCEPT statements to be read from a specified file.
  • INFORETURN
    Specifies the return-code value returned by the Compiler when it produces only informational messages.
  • INIT-BY-TYPE
    Initializes Working-Storage data items to a default value, according to their type.
  • INITCALL
    Specifies modules to be called immediately before the first statement of the program is executed.
  • INITPTR
    Enables the INITIALIZE statement to initialize DATA-POINTER, OBJECT-REFERENCE, and PROGRAM-POINTER data types.
  • INT
    Specifies the name of the intermediate code file.
  • INTDATE
    Selects the starting date for integer format dates used with date intrinsic functions.
  • INTLEVEL
    When intermediate code is being created by the Compiler, this directive controls the level of portability of the code created to different versions of Micro Focus COBOL systems in other environments.
  • IOCONV
    Selects between a straight group move and conversion of elementary record descriptions (ANSI behavior) when processing READ ... INTO and WRITE ... FROM statements.
  • ISO2002
    Specifies that words reserved in the ISO2002 COBOL Standard are to be treated as reserved words, and changes the behavior of certain features to be compatible with that standard.
  • IXNLSKEY
    Specifies that the File Handler should sort index file keys according to the local collating sequence rather than the ASCII collating sequence.
  • IXNUMKEY
    Enables true numeric sorting on index keys.
  • JAPANESE
    Enables the use of Micro Focus Japanese Language Extension (PIC N, Japanese data-names and Japanese procedure-names).
  • JVMCLASSPATH
    Adds directories to the CLASSPATH, enabling classes located within those directories to be utilized.
  • JVMDECIMAL
    Determines the type in which certain items are exposed. This directive affects COBOL data items of type 'decimal' and non-integral numeric items exposed as a result of either ILSMARTLINKAGE usage or the PROPERTY keyword.
  • JVMGEN
    Generates Java bytecode.
  • JVMSOURCEBASE (IDE Only)
    Specifies the absolute path to a source folder containing COBOL JVM source files.
  • JVMTARGET
    Specifies the JVM version number targeted by the class files generated in this compilation unit. The resulting class files can be run on any JVM version greater than or equal to the specified number.
  • KEYCHECK
    Specifies whether the File Handler checks that all the keys belonging to the indexed file you are opening are defined in your application.
  • KEYCOMPRESS
    Specifies the type of key compression to be done on indexed files.
  • LIBRARIAN
    Allows -INC statements in your program.
  • LINE-COUNT
    Controls the detail of information displayed at the end of a source listing.
  • LINKALIAS
    Lets the user provide assurances to the compiler about how linkage items will be used, to aid optimization.
  • LINKCHECK
    Specifies that each time a Linkage Section item is referenced a check is to be made that it exists.
  • LIST
    Specifies the destination of the source listing file.
  • LISTPATH
    Specifies a path on which the list file is to be written. The name of the list file is source-name.lst.
  • LISTWIDTH, LW
    Sets the width of the listing.
  • LITLINK
    Makes the Compiler declare the literals in CALL literal statements as public symbols, so they are resolved at link time rather than run time. (Calls generated in this way are referred to as litlinked.)
  • LITVAL-SIZE
    Specifies the number of bytes to pass if the SIZE clause is omitted when passing numeric literals BY VALUE.
  • LNKALIGN
    Indicates that level-01 and level-77 Linkage Section items are always aligned on a machine-dependent favorable boundary.
  • LOCALCOUNT
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • LOCALSOURCEFORMAT
    Specifies that any setting of the SOURCEFORMAT directive in a source file is maintained for that file. This means that if a file with a different SOURCEFORMAT setting is copied into the source file, when processing exits the copied code, the SOURCEFORMAT setting returns to that originally specified in the source file.
  • LOCKTYPE
    Specifies the type of record locking.
  • MAINFRAME-FLOATING-POINT
    Specifies the format of the program's floating point data items.
  • MAKESYN
    Makes one reserved word synonymous with another.
  • MAPNAME
    Makes the Compiler alter program-names and entry-point names to make them compatible with OS/VS COBOL, DOS/VS COBOL, VS COBOL II and COBOL/370.
  • MAX-ERROR
    Causes the Compiler to abort when the specified number of errors have been produced.
  • METHODDEFAULT
    Sets the default method for passing parameters.
  • MF, MFLEVEL
    Enables forward compatibility with Micro Focus COBOL systems by selectively enabling Micro Focus-specific reserved words and changing the behavior of certain features to be compatible with particular versions.
  • MFCOMMENT
    Treats lines with an asterisk (*) in column 1 the same as comment lines but does not show them in the source listing.
  • MFSYNC
    Synchronizes items based on their size.
  • MOVE-LEN-CHECK
    Causes the Compiler to check source and target lengths for alphanumeric MOVE operations, and produces a warning message if they are different.
  • MS
    Facilitates forward compatibility with Microsoft COBOL systems by selectively enabling Microsoft-specific reserved words and changing the behavior of certain features to be compatible with particular versions.
  • MVS
    Specifies that words reserved in IBM COBOL for MVS are to be treated as reserved words.
  • NATIONAL
    Enables you to select the level of NATIONAL support.
  • NATIVE
    Specifies the default collating sequence for comparisons.
  • NATIVE-FLOATING-POINT
    Determines whether a program's floating point data items are to use IBM hexadecimal format.
  • NCHAR
    Enables the use of Micro Focus Double-byte Language Extension (PIC N, Japanese data-names and Japanese procedure-names).
  • NLS
    Enables the National Locale Support facility.
  • NLS CURRENCY LENGTH
    Specifies the number of bytes to allocate for the currency symbol in a PIC field.
  • NSYMBOL
    Defines the default USAGE for PIC N clauses and controls the interpretation of national literals.
  • NULL-ESCAPE
    Treats a 0x00 character in the source file as an escape character for other non-printable characters in the source code.
  • NUMPROC
    Provides partial compatibility with the processing of invalid data on some non-IBM mainframe COBOL platforms.
  • OBJ
    Specifies the name and format of the object code file and generated code file.
  • ODOOSVS
    Makes the evaluation of OCCURS DEPENDING ON items more compatible with the OS/VS COBOL compiler.
  • ODOSLIDE
    Moves data items that follow a variable-length table in the same record as the table's length changes.
  • OLDBLANKLINE
    Changes the behavior of the BLANK LINE clause in the Screen Section.
  • OLDCOPY
    Makes COPY statements follow the ANSI'68 standard.
  • OLDINDEX
    Causes indexes to be compiled as 16-bit binary integer subscripts.
  • OLDNEXTSENTENCE
    Changes the behavior of the NEXT SENTENCE statement.
  • OLDREADINTO
    Changes the behavior of the READ ... INTO statement.
  • OLDSTRMIX
    Allows PIC X and PIC N fields to be specified in the same STRING, UNSTRING or INSPECT statement
  • OOCTRL
    Enables you to change language options when compiling OO COBOL classes and interfaces.
  • OPT (Intel x86 platforms)
    Specifies the level of optimization of the code produced by the compiler.
  • OPT (Non-Intel x86 platforms)
    Specifies the level of optimization of the code produced in the object code file. Use this version of the OPT directive on operating systems that use chips other than the Intel x86 chip, for example, AIX, Solaris Sparc, HP-UX, IA64 (this list is not exhaustive).
  • OPTIONAL-FILE
    Makes the Compiler treat all files opened for I-O or EXTEND as optional.
  • OS390
    Specifies that words reserved in IBM COBOL for OS/390 R2V2 are to be treated as reserved words.
  • OSEXT
    Tells the Compiler what extension to expect by default on the names of source files.
  • OSVS
    Specifies that words reserved in IBM OS/VS COBOL are to be treated as reserved words.
  • OUTDD
    Causes DISPLAY and EXHIBIT statements to be written to a specified output file.
  • OVERRIDE
    Replaces a reserved word by a new one.
  • P64
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • PANVALET
    Allows ++INCLUDE statements in your program.
  • PARAMCOUNTCHECK
    Enables the program to be called with fewer parameters than are specified in the relevant entry point's USING clause.
  • PC1
    Specifies that words reserved in IBM COBOL V1.00 are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • PERFORM-TYPE
    Specifies the behavior of return jumps from nested PERFORM statements.
  • PERFORMOPT
    Determines if the Compiler should optimize out code to PERFORM empty paragraphs in generated native code.
  • PPLITLINK
    Makes the Compiler declare literals as public symbols, in a SET statement using a data item defined as USAGE IS PROCEDURE-POINTER. This means literals are resolved at link time rather than run time. (Symbol references defined in this way are referred to as litlinked.)
  • PREPLIST
    Causes the list file produced during a compilation to show both the original and modified source created by the preprocessor. It shows all data passed to the Compiler by a preprocessor and any resultant messages on the preprocessor-inserted code.
  • PREPROCESS, P
    Makes the Compiler take the source program from a preprocessor instead of a source file.
  • PRESERVECASE
    Ensures that COBOL items declared in the current program retain their case and are not converted to uppercase as is usual in COBOL. This enables the items to be found from outside the program.
  • PRINT
    Specifies the destination of the source listing file.
  • PRINT-EXT
    Specifies the extension to be added to the filename associated with the ASSIGN TO PRINTER clause.
  • PROFILE
    Includes code in your program to produce detailed performance statistics each time you run the program.
  • PROGID-COMMENT
    Allows comments following the PROGRAM-ID header in the Program-Id paragraph.
  • PROGID-INT-NAME
    Causes the name of the intermediate code file to be taken from the PROGRAM-ID clause, rather than the name of the source file.
  • PROTECT-LINKAGE
    Extends the standard COBOL semantics so that the lengths of parameters can differ between the calling and the called program.
  • PROTOTYPE
    Enables relaxed or strict checking of call prototypes for COMP, BINARY, COMP-4, COMP-5 and COMP-X data items when used in the BY VALUE or RETURNING clauses of a CALL statement. It also inhibits or enables the implicit copying of parameter types from the prototype.
  • QUAL
    Allows qualified data-names and procedure-names in your program.
  • QUALPROC
    Allows qualified procedure-names in your program.
  • QUERY
    Each time the Compiler is unable to find a copybook, it prompts you for an action.
  • QUOTE
    Makes the Compiler interpret the figurative constant QUOTE as the double-quote character (").
  • RAWLIST
    Prevents changeable information, such as page headers, date, time, Compiler release level, from being included in any listing file produced.
  • RDFPATH
    Specifies a location for a repository file.
  • RDW
    Enables you to find out the length of a record that has just been read from a variable-length sequential file.
  • RECMODE
    Specifies the default format of files.
  • RECURSECHECK
    Turns on checking for recursion in generated code.
  • REENTRANT
    Controls reentrancy of a multithreading program. Any program that is to be reentrant in a multi-threaded application must be compiled with this directive. If REENTRANT is specified, many program areas are dynamically allocated, so that it is safe to have multiple copies of the program running.
  • REF
    Makes the Compiler include in the source listing the intermediate code address of each Procedure Division statement.
  • REFNO
    Makes the Compiler display its internal reference number at the start of a compilation as well as at the bottom of every listing.
  • REMAINDER
    Enables you to select how the remainder is calculated in a DIVIDE statement.
  • REMOVE
    Removes words from the reserved word list, so that they can be used as user-defined words.
  • REPORT-LINE
    Specifies the maximum length of a Report Writer line.
  • REPOSITORY
    Creates a repository file or requests that the program being compiled is checked against the repository file.
  • RESEQ
    Makes the Compiler produce line numbers.
  • RESTRICT-GOTO
    Generates a syntax error for GO TO statements that transfer control to outside of the current section.
  • RETRYLOCK
    Specifies that when a READ statement finds that a record is locked, the READ operation is to be retried repeatedly until the record is available.
  • REWRITE-LS
    Allows REWRITE statements on line sequential files.
  • RM
    Specifies that words reserved in RM/COBOL are to be regarded as reserved words, and changes the behavior of certain features to be compatible with that COBOL system.
  • RTNCODE-TYPE
    Defines the numeric type of the RETURN-CODE special register.
  • RTNCODE-SIZE
    Specifies the size of the RETURN-CODE special register and its alignment in memory.
  • RUNTIME-ENCODING
    Determines the run-time encoding.
  • RWHARDPAGE
    Causes the Report Writer control module to execute a form feed after the last item has been printed on a page, instead of the usual multiple blank lines. This ensures that the paper is positioned correctly ready for a new page.
  • SAA
    Specifies that words reserved under the Systems Application Architecture (SAA) definition of COBOL are to be treated as reserved words.
  • SCHEDULER
    Controls the invocation of the Intel COBOL Optimizer.
  • SEG
    Turns on COBOL segmentation.
  • SEQCHK
    Makes the Compiler check the sequence numbers in columns 1 through 6 and identify source lines that are out of sequence.
  • SEQUENTIAL
    Specifies the default file type for files defined (implicitly or explicitly) as ORGANIZATION SEQUENTIAL.
  • SERIAL
    Specifies that the program is to be a serial program.
  • SETTING, SETTINGS
    Makes the Compiler include in the source listing a list of the settings of directives.
  • SHARE-OUTDD
    When set, multiple threads can write to the same SYSOUT or OUTDD file. When not set, a file locking error occurs in this situation.
  • SHOW-DIR
    Makes the Compiler show the contents of directives files in the source listing.
  • SIGN
    Specifies the default convention for signs in signed numeric DISPLAY data items.
  • SIGNDISCARD
    Specifies that a MOVE of a signed numeric DISPLAY field to a group item should discard the sign, and treat the group as an elementary alphanumeric field.
  • SIGN-FIXUP
    Provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements.
  • SORTTYPE
    Selects which mainframe SORT module to emulate.
  • SOURCE-ENCODING
    Passes the encoding of the source program to the compiler.
  • SOURCEFORMAT
    Sets the layout format for your COBOL source.
  • SOURCETABSTOP
    Sets the tab stop boundary in effect. When the Tab key is pressed, the cursor advances n spaces to position itself on the next specified tab position.
  • SPZERO (deprecated)
    Causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros.
  • SQL
    Causes EXEC SQL statements in your program to be replaced by ODBC run-time calls, depending on the options you specify.
  • SSRANGE
    Turns on bounds checking for reference modifications, subscripting and indexes.
  • STDERR
    Causes error messages to be echoed to STDERR rather than to the console (STDOUT).
  • STICKY-LINKAGE
    Makes parameters to the program remain linked during subsequent calls of the program.
  • STICKY-PERFORM
    Specifies the behavior of PERFORM statements when a program is reentered.
  • SUPFF
    Suppresses form-feed characters on the compilation listing if it is sent to the screen.
  • SWITCH-TYPE
    Makes programmable switches behave in the same way as in the ISO 2002 standard.
  • SYMBSTART
    Sets the number from which the Compiler counts positions in the collating sequence when compiling the SYMBOLIC CHARACTERS clause.
  • SYSPUNCH
    Specifies the SYSPUNCH record length to be used.
  • TERMPAGE
    Determines whether the last page of a report file is to be padded with blank lines until it is a full page in length.
  • TESTCOVER
    Enables you to use the test coverage tool, which creates a statistical execution profile of a program.
  • TIME
    Puts the time at the top of each page of the listing.
  • TRACE
    Enables READY TRACE and RESET TRACE statements.
  • TRICKLE (deprecated)
    This directive is deprecated, and provided for backward compatibility only.
  • TRUNC
    Specifies whether data being stored into a USAGE COMP, USAGE BINARY or USAGE COMP-4 item is to be truncated to the size given by the item's PICTURE clause or to the maximum size the item can hold.
  • TRUNCCALLNAME
    Truncates subprogram names to a specified length.
  • TRUNCCOPY
    Specifies whether to truncate the names of copybooks.
  • TRUNCINC
    Specifies whether to truncate the names of ++INCLUDE files.
  • UNICODE
    Specifies the encoding to be used for Unicode characters.
  • USE
    Makes the Compiler read directives from a file.
  • VERBOSE
    Sends messages from the Compiler to the screen.
  • VSC2
    Specifies that words reserved in IBM VS COBOL II are to be treated as reserved words, and enables selected features for compatibility with a given level of that COBOL system.
  • WARNING, WARNINGS
    Specifies the lowest severity level of errors to report.
  • WB
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WB2
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WB3
    This directive is reserved for internal use by this COBOL system. Because it might appear in the list of settings, it is included for completeness. It is not intended for your use, and its setting should not be changed.
  • WRITELOCK, WRITE-LOCK
    Makes the WRITE and REWRITE statements acquire a record lock when the program is locking multiple records in a shared data file in a multi-user environment.
  • WRITETHROUGH, WRITETHRU
    Specifies that disk writes are not to be buffered.
  • XMLGEN
    Specifies whether the Compiler should produce an XML model file for either the file section or the working-storage section data items defined in the program.
  • XMLPARSE
    Determines the behavior of the XML PARSE statement and special registers relating to XML events.
  • XOPEN
    Specifies that words reserved under the X/Open definition of COBOL are to be treated as reserved words.
  • XREF
    Makes the Compiler produce a cross-reference listing.
  • ZEROLENGTHFALSE
    Changes the way that class tests involving zero-length items are carried out.
  • ZEROSEQ
    Causes leading zeros to appear in the sequence numbers in columns 1 through 6.
  • ZWB
    This Compiler directive is not intended for your use, and its setting should not be changed. It is included here for completeness, because it might appear in the list of settings.
Parent topic: Compiler Directives


ILINCREMENTALBUILD

Identifies and compiles only the programs that have changed since the previous compilation.
Restriction: This directive is supported for managed COBOL only.

Syntax:

>>-.----.---ILINCREMENTALBUILD---------><
   |    |
   +-NO-+

Parameters:

None

Properties:

Default: | NOILINCREMENTALBUILD
Phase: | Syntax check
IDE Equivalent: | Navigate to the projects's properties and click Micro Focus > Build Configuration and check Use incremental build.
$SET: | No

Comments:

When this directive is specified, the build only recompiles programs that have changed and programs that refer to types or programs within those programs that have changed. When using this directive, the build creates a directory within the project output directory called JVMDependencies that stores dependency information for all the programs in your project.

Micro Focus recommends that you clean your project and build before packaging for distribution.

Parent topic: Compiler Directives - Alphabetical List
Related information
Managed COBOL Command Line Compiler Directives
Key to Compiler Directives


JVMSOURCEBASE (IDE Only)

Specifies the absolute path to a source folder containing COBOL JVM source files.
Note: This directive is supported for managed COBOL in the Eclipse IDE only.

Syntax:

>>---------JVMSOURCEBASE---"cobolsourcebase"------><
Note: You can use multiple directives to specify a number of different source folder locations.

Parameters:

cobolsourcebase The absolute path to the source folder. This is case sensitive. The path delimiter uses a "/" or "\" depending on the OS.

Properties:

Default: JVMSOURCEBASE "cobolsourcebase"
IDE equivalent: By default, this is set automatically by the Eclipse IDE. To stop new projects from having a JVMSOURCEBASE by default:
  1. Click Window > Preferences > Micro Focus > Builder.
  2. Uncheck Each part of the package name corresponds to a subdirectory.

Comments:

This directive is set automatically by the Eclipse IDE when you create a class or package. The directive tells the Compiler to check the following:

  • The package corresponds with the file location prefixed by one of the directive values.
  • The name of the outer type must match the name of the source location.
  • The class files in the source folder can only have one outer type.
Note: Projects created before Visual COBOL 4.0 do not have a JVMSOURCEBASE as a default.
Parent topic: Compiler Directives - Alphabetical List


TRICKLE (deprecated)

This directive is deprecated, and provided for backward compatibility only.
Parent topic: Compiler Directives - Alphabetical List


XMLGEN

Specifies whether the Compiler should produce an XML model file for either the file section or the working-storage section data items defined in the program.

Restriction: XMLGEN is for use with XML Extensions only. For more information, see XML Extensions.

Syntax:

>>-.--XMLGEN--.------------.---.---><
   |          +-(ws)-------+---|
   |          +-(WS)-------+---|
   |          +-(pathname)-+---|
   |          +-($env-var)--+--|
   |                           |
   +--NOXMLGEN-----------------+

Parameters

none
When you use XMLGEN without any parameters, it generates an XML model file in the project directory, containing a model for file section data items only (no working-storage section data items).
Note: The XML model file must be accessible to the XML extensions run-time environment. To make the file accessible, either add it to the system path, or move it to the directory from which the program is run.
WS and ws
Generate a model that includes working-storage section data items only (no file section data items).
pathname
An absolute or relative path to use as an alternative location for the generated XML model file.
Note: To specify a path that starts with the letters ws or WS, begin the path specification with a slash (/) or a dot slash (./) to prevent XMLGEN from misinterpreting the ws characters as a WS or ws parameter specification.
$env-var
An environment variable set to an absolute or relative path to use as an alternative location for the generated XML model file.

Properties:

Default: | NOXMLGEN
Phase: | Syntax check
$SET: | Any

Comments:

  • XMLGEN produces one XML model file containing either file section data items or working-storage data items depending on whether or not ws or WS is specified. It does not produce both the file section and working-storage section descriptions in one compilation.
  • The XML model output filename is:
    source-name.xml
    where source-name is the prefix of the specified COBOL file.
  • XMLGEN overwrites existing output files.
  • To generate an XML model file with working-storage section data descriptions in an alternative directory, specify the XMLGEN directive twice with the first XMLGEN providing the pathname or $env-var parameter, followed by the second providing the WS or ws parameter. Reversing this order results in an output file in the specified path but with file section data items instead of working-storage data items.

Examples:

To generate an XML model file in the project directory, containing file section data items:

XMLGEN

To generate an XML model file in the c:\users\bob directory, containing file section data items:

XMLGEN(c:\users\bob)

To generate an XML model file in the project directory, containing working-storage data items:

XMLGEN(ws)

To generate an XML model file in the c:\users\bob directory, containing working-storage data items:

XMLGEN(c:\users\bob) XMLGEN(ws)

To generate an XML model file in the directory specified by the XMLPATH environment variable, containing working-storage data items:

XMLGEN($XMLPATH) XMLGEN(ws)
Parent topic: Compiler Directives - Alphabetical List
Related concepts
XML Extensions


Environment Variables

This appendix lists all the environment variables that are available, and describes how to specify them.

Environment Variable | Summary
CCITCP2 | Locates TCP/IP registration program
CCITRACE | Specifies the level of CCI tracing
COB_LIVE_RECORD Specifies the path (optional) and filename prefix for the live recording file (.mfr file) created by the Live Recorder feature.
Note: The live recording file must be replayed on a development product and on the same operating system as it was created.
COB_LIVE_RECORD_SIZE Specifies the amount of memory (in MB) that is used to store events that are to be written to the live recording file. This can help aid performance during recording.

When the limit is reached, the buffer is cycled so that the oldest events are removed to make space for the most recent events. The default value is 268. the minimum value is 67, and the maximum value is dependant on your environment (available memory, bitism, etc...). You may need to experiment with this value to find the most optimal setting, but for 32-bit systems, a range between 500 and 1000 is adequate. For example:

COB_LIVE_RECORD_SIZE=756
Note: This is not the actual size of the live recording file that is stored on disk, as the event log is compressed when writing to the file.
COBAIF | Locates .aif files
COBAIFNAME | Specifies basename of .aif files
COBANIMOPT | Specifies directives to Animator
COBANIMSRV | Attaches Animator to a running program
COBATTR | Selects appearance of HIGHLIGHT and LOWLIGHT
COBCONFIG | Tailors run-time configurable options
COBCPY | Locates copyfiles
COBDATA | Locates data files
COBDIR | Locates COBOL system software
COBIDY | Locates Animator information (.idy) files
COBKEYTIMEOUT | Tunes remote terminal response
COBLPFORM | Sets logical printer channels
COBMAINSTACK | Sets the size of the main stack
COBMODE | Sets the local effective working mode
COBOPT | Specifies user default Cob utility options
COBPATH | Locates programs for dynamic loading
COBPRINTER | Directs output to a print spooler
COBSES | Specifies the UNIX Session Recorder functions to perform
COBSW | Sets run-time system switches
COBTERMINFO | Locates COBOL terminfo terminal database
COLUMNS | Specifies screen width
ENTRYNAMEMAP | Specifies entry name map files and directories containing them
EXTFH | Specifies a configuration file for the Callable File Handler
FHREDIR | Specifies a configuration file to be used by the Fileshare Client
FS | Specifies a configuration file for Fileshare Server
FSCOMMS | Specifies that the Fileshare System is to run in single user mode
HCOBND | Specifies a directory for DB2 bind files
LANG | Specifies the language environment
LD_LIBRARY_PATH | Locates shared libraries (except AIX platforms)
LIBLIST | Locates special Cob library list
LIBPATH | Locates shared libraries (AIX platforms)
LINES | Specifies screen depth
MAINFRAME_FLOATING_POINT | Specifies the format to use for floating point data items
MFCODESET | Specifies which translation tables to use
MFCSCFG | Specifies a configuration file to be used by the Client/Server Binding client program
MFJSERET | Determines the response to an unsuccessful sort, copy or merge operation. Set to ABEND for an unsuccessful operation to abend and its program to continue instead of terminating with an unrecoverable error (return code 16).
MFJSTATS | Specifies to create a report containing statistics for a SORT
MFLECONFIG | Specifies a configuration file for Language Environment (LE) run-time options
MFLOGDIR | Specifies a directory to be used by Client/Server Binding for log files
PATH | Locates directories for all UNIX programs
SORTCOMPRESS | Specifies that a compression routine should be used on sort records
SORTSCHEME | Specifies a SORT operation to retain more record information in memory.
SORTSPACE | Specifies internal work space for SORT operations
SORTTEMPSPACE | Specifies temporary work space for SORT operations
TERM | Specifies terminal type
TERMINFO | Locates UNIX system terminfo database
TMPDIR | Locates directory for temporary files
Note: The syntax in the following descriptions is shown as required for the sh and ksh shells. Other shells, such as csh, require syntax of the form:
setenv env_var value

where the parameters are:

env_var
One of the environment variables shown on the following pages.
value
A value to which the environment variable can be set.
Parent topic: General Reference


Error Messages

  • COBOL
  • Data Related
  • ACUCOBOL
  • Enterprise
  • Licensing
Parent topic: General Reference


COBOL

Look in the sections below to find the error messages produced by the area of the product you are working with.

  • Syntax Checking Error Messages
  • Code Generation Error Messages
  • Run-time System Error Messages
  • COBOL Preprocessor Error Messages
  • Explanation of Error Codes
Parent topic: Error Messages
Related reference
cobutf8 Error Messages
Related information
cob Error Messages
Compiler Control - Error and Flag Messages
Test Coverage Error Messages


Syntax Checking Error Messages

These messages are output when the compiler is checking your COBOL program for syntax and consistency. The Help topcs for the messages list the text of each message, and where necessary explains the error or problem that causes the message and gives advice on how to prevent it. The severity is not listed, as the same message can be output with a different severity depending on the setting of directives.

  • Key to Syntax Checking Error Messages
  • Messages COBCH0001 to COBCH0100
  • Messages COBCH0101 to COBCH0200
  • Messages COBCH0201 to COBCH0300
  • Messages COBCH0301 to COBCH0400
  • Messages COBCH0401 to COBCH0500
  • Messages COBCH0501 to COBCH0600
  • Messages COBCH0601 to COBCH0700
  • Messages COBCH0701 to COBCH0800
  • Messages COBCH0801 to COBCH0900
  • Messages COBCH0901 to COBCH1000
  • Messages COBCH1001 to COBCH1100
  • Messages COBCH1101 to COBCH1200
  • Messages COBCH1201 to COBCH1300
  • Messages COBCH1301 to COBCH1400
  • Messages COBCH1401 to COBCH1500
  • Messages COBCH1501 to COBCH1600
  • Messages COBCH1601 - COBCH1700
  • Messages COBCH1701 - COBCH1800
  • Messages COBCH1801 - COBCH1900
  • COBCH1901 - COBCH1940
    Lists the Syntax Checking error messages from COBCH1901 through COBCH1940.
  • Messages COBCH2001 and above
Parent topic: COBOL


Key to Syntax Checking Error Messages

Syntax checking error messages have the following format:

ErrorCode Description : Location

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.
  • The severity of the error.
Description | A description of the cause of the error.
Location | The approximate location of the error in the source code.

The severity returned in ErrorCode can take one of the following values:

U | Unrecoverable. An unrecoverable error stops the COBOL system. These messages are produced by the run-time system. See also Run-time System Error Messages
S | Severe. You must correct the syntax error or inconsistency in your program. Otherwise the compiler cannot generate code.
E | Error. The compiler will make an assumption about what you meant. You might want to correct your program in case the compiler's assumption is not what you intended.
W | Warning. This means there might be an error, although the program is syntactically correct.
I | Information. This draws your attention to something in the source code that you might need to be aware of. It does not mean there is an error.

You can disable reporting of errors of E-, W-, and I-level, using the WARNING directive.

When the Compiler has finished, the total number of errors in each category is also output.

You can disregard some levels of errors and continue working. You can:

  • Debug programs that have S-, E-, W-, and I-level errors.
  • Produce object code from intermediate code that has E-, W-, and I-level errors, but not S-level errors.
  • Run programs that have E-, W-, and I-level errors. If the E-level run-time switch is on, which overrides the default setting, you can also run programs with S-level errors.

The error messages can contain variable information. This information is indicated as an item in italics. For example:

0005 User-name user-name not unique

will have the name of the item that is not unique in place of the text user-name.

Parent topic: Syntax Checking Error Messages


Messages COBCH0001 to COBCH0100

  • COBCH0001 - COBCH0020
    Lists the Syntax Checking error messages from COBCH0001 through COBCH0020.
  • COBCH0021 - COBCH0040
    Lists the Syntax Checking error messages from COBCH0021 through COBCH0040.
  • COBCH0041 - COBCH0060
    Lists the Syntax Checking error messages from COBCH0041 through COBCH0060.
  • COBCH0061 - COBCH0080
    Lists the Syntax Checking error messages from COBCH0061 through COBCH0080.
  • COBCH0081 - COBCH0100
    Lists the Syntax Checking error messages from COBCH0081 through COBCH0100.
Parent topic: Syntax Checking Error Messages


COBCH0001 - COBCH0020

Lists the Syntax Checking error messages from COBCH0001 through COBCH0020.

  • COBCH0001 Undefined error. Inform Technical Support
    Your program contains an error which the COBOL system has failed to recognize.
  • COBCH0002 Unexpected SQL error. Inform Technical Support
    Your program contains an SQL error which the COBOL system has failed to recognize.
  • COBCH0003 Illegal format : Literal
    The sequence of characters forming a literal in your source code does not conform to the rules governing the construction of such names. A literal can be either nonnumeric or numeric.
  • COBCH0004 Illegal character
    Your program contains a character that is not part of the COBOL language set.
  • COBCH0005 User-name user-name not unique
    You have given the same user-name without qualification to more than one data item or procedure-name in your source code.
  • COBCH0007 $ specified in indicator area of otherwise blank line
    The indicator area, column 7, contains an illegal character.
  • COBCH0008 Unknown COPY file filename specified
    A file with the name filename, specified in conjunction with a COPY statement, cannot be found.
  • COBCH0009 '.' missing
    Your code does not contain a period in a place where one is expected by the rules of COBOL syntax.
  • COBCH0010 Word starts or is continued in wrong area of source line
    The word starts either in area A when it should have started in area B, or in area B when it should have started in area A.
  • COBCH0011 Reserved word missing or incorrectly used
    You have either used a reserved word in a place where a user defined word is expected or you have failed to use a reserved word where one is needed.
  • COBCH0012 Operand data-name is not declared
    You are trying to use a data-name which you have not declared, or which you have misspelled.
  • COBCH0013 User-name required
    You have not supplied a user-defined-name at the specified place in your program.
  • COBCH0014 Invalid operand
    The operand you have specified is in some way incorrect, and cannot be processed by your COBOL system. For example, you might have specified a negative integer where only positive integers are allowed.
  • COBCH0015 Procedure Division too large
    Your program's Procedure Division exceeds the maximum size allowed.
  • COBCH0016 Data space too large
    Your program's Data Division exceeds the maximum size allowed.
  • COBCH0017 Incorrect use of reserved word word
  • COBCH0018 Preprocessor error on initialization
    An integrated preprocessor invoked by the COBOL system detected an error during its initialization and was unable to continue.
  • COBCH0019 BASIS line number sequencing error
    You have made an error in the sequence of line numbers in one of the statements that implement the BASIS mechanism. For example, the statement DELETE 100-60 is incorrect. (BASIS requires numeric sequence values.)
  • COBCH0020 Numeric literal expected
    You must specify a numeric literal in this context.
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0001 Undefined error. Inform Technical Support

Your program contains an error which the COBOL system has failed to recognize.

Resolution:

Send Technical Support a copy of your source code to enable them to find the cause of the error.

Parent topic: COBCH0001 - COBCH0020


COBCH0002 Unexpected SQL error. Inform Technical Support

Your program contains an SQL error which the COBOL system has failed to recognize.

Resolution:

Send Technical Support a copy of your source code to enable them to find the cause of the error.

Parent topic: COBCH0001 - COBCH0020


COBCH0003 Illegal format : Literal

The sequence of characters forming a literal in your source code does not conform to the rules governing the construction of such names. A literal can be either nonnumeric or numeric.

If numeric it can be up to 18 digits in length, but it must not contain more than one sign character or more than one decimal point.

A nonnumeric literal can consist of any allowable character in the computer's character set up to a maximum of 160 characters in the Procedure Division, or 2048 characters in the Data Division. A nonnumeric literal must be enclosed in quotation marks.

If you have used a figurative constant as the literal make sure that it is referenced by an allowable reserved word (such as ZERO) which you have spelled correctly. A figurative constant and a numeric literal must not be enclosed in quotation marks.

You might also have used the wrong class of literal for the context of the sentence.

Alternatively, if you have used the figurative constant ALL in your code, you have not coded it in accordance with the rules governing the use of this constant. ALL must be followed by a nonnumeric literal and not by a numeric one.

Resolution:

Revise your code to comply with the above rules.

Parent topic: COBCH0001 - COBCH0020


COBCH0004 Illegal character

Your program contains a character that is not part of the COBOL language set.

Resolution:

Replace the illegal character with a valid one.

Parent topic: COBCH0001 - COBCH0020


COBCH0005 User-name user-name not unique

You have given the same user-name without qualification to more than one data item or procedure-name in your source code.

Resolution:

You must rename or qualify the duplicated data items or procedure-names to ensure that uniqueness of reference is achieved.

Parent topic: COBCH0001 - COBCH0020


COBCH0007 $ specified in indicator area of otherwise blank line

The indicator area, column 7, contains an illegal character.

Resolution:

Legal characters are *, D, -, / or space.

Parent topic: COBCH0001 - COBCH0020


COBCH0008 Unknown COPY file filename specified

A file with the name filename, specified in conjunction with a COPY statement, cannot be found.

Resolution:

Change the filename, or make the file available to your COBOL system.

Parent topic: COBCH0001 - COBCH0020


COBCH0009 '.' missing

Your code does not contain a period in a place where one is expected by the rules of COBOL syntax.

Resolution:

Insert one at the relevant place.

Parent topic: COBCH0001 - COBCH0020


COBCH0010 Word starts or is continued in wrong area of source line

The word starts either in area A when it should have started in area B, or in area B when it should have started in area A.
Parent topic: COBCH0001 - COBCH0020


COBCH0011 Reserved word missing or incorrectly used

You have either used a reserved word in a place where a user defined word is expected or you have failed to use a reserved word where one is needed.

Resolution:

Alter the reserved word into a user defined one or insert a reserved word according to the context of this message.

Parent topic: COBCH0001 - COBCH0020


COBCH0012 Operand data-name is not declared

You are trying to use a data-name which you have not declared, or which you have misspelled.

Resolution:

This error might not always occur directly below the data item that is not declared. This is because your COBOL system continues processing through the source code to find out whether the data item is qualified. To find the item in error, work backward through the source to the most recent item.

Ensure that the data item is declared.

Parent topic: COBCH0001 - COBCH0020


COBCH0013 User-name required

You have not supplied a user-defined-name at the specified place in your program.

Resolution:

Insert a name ensuring that it conforms to the rules of COBOL syntax and that it is the correct type of name (for example a system-name or a condition-name).

Parent topic: COBCH0001 - COBCH0020


COBCH0014 Invalid operand

The operand you have specified is in some way incorrect, and cannot be processed by your COBOL system. For example, you might have specified a negative integer where only positive integers are allowed.

Resolution:

See the related topics for information on the operands allowed for this syntax.

Parent topic: COBCH0001 - COBCH0020
Related reference
Compilation Groups


COBCH0015 Procedure Division too large

Your program's Procedure Division exceeds the maximum size allowed.

Resolution:

Redesign your program as a set of smaller independent programs that call one another.

Parent topic: COBCH0001 - COBCH0020


COBCH0016 Data space too large

Your program's Data Division exceeds the maximum size allowed.

Resolution:

Redesign your program as a set of independent programs with smaller Data Divisions.

Parent topic: COBCH0001 - COBCH0020


COBCH0017 Incorrect use of reserved word word

Parent topic: COBCH0001 - COBCH0020


COBCH0018 Preprocessor error on initialization

An integrated preprocessor invoked by the COBOL system detected an error during its initialization and was unable to continue.

Resolution:

If the preprocessor displayed any further information correct the problem and resubmit the command

Parent topic: COBCH0001 - COBCH0020


COBCH0019 BASIS line number sequencing error

You have made an error in the sequence of line numbers in one of the statements that implement the BASIS mechanism. For example, the statement DELETE 100-60 is incorrect. (BASIS requires numeric sequence values.)

Resolution:

Correct the sequence error.

Parent topic: COBCH0001 - COBCH0020


COBCH0020 Numeric literal expected

You must specify a numeric literal in this context.

Resolution:

Ensure that your numeric literal complies with the syntax rules.

Parent topic: COBCH0001 - COBCH0020


COBCH0021 - COBCH0040

Lists the Syntax Checking error messages from COBCH0021 through COBCH0040.

  • COBCH0021 Too many qualifiers
    You have used too many qualifiers when referring to a qualified data-name, procedure-name or text-name.
  • COBCH0022 SKIP1/2/3, EJECT and TITLE must be alone on line
    Source program lines containing these words must not contain any other words.
  • COBCH0023 Nonnumeric literal expected
    You must specify a nonnumeric literal in this context.
  • COBCH0024 Illegal qualifier
    You have specified a qualified data-name, procedure-name, or text-name incorrectly.
  • COBCH0025 Qualification not permitted
    You cannot qualify a data-name, procedure-name, or text-name in this context.
  • COBCH0026 Literal too long
  • COBCH0027 Number too large
    You have declared a numeric value that is too large.
  • COBCH0028 Data item too long
    You have declared a data item that is too long for the specified data-type.
  • COBCH0029 Not a data-name
    You have specified an operand that is not a data item where a valid data item is expected. For example, you might have specified an FD-name or a condition-name instead of a data-name.
  • COBCH0030 Should be a group
    You have specified an elementary item as the sending or receiving field in a MOVE CORRESPONDING statement.
  • COBCH0031 Should be elementary
    You have specified the name of a group data item in a context in which an elementary item must be used.
  • COBCH0032 Should be unitary
    You have specified a subscripted or indexed data item where one is not allowed.
  • COBCH0033 Should be procedure name
    A procedure-name (that is, a paragraph or section-name) is expected in this context. You have probably specified a data-name.
  • COBCH0034 Operand operand should be numeric
    A numeric value is required in this context, and you have specified a nonnumeric value.
  • COBCH0035 Integer required
    An integer value is required in this context, and you have specified a noninteger value.
  • COBCH0036 Should be alphanumeric
    An alphanumeric value is required in this context, and you have specified a numeric value.
  • COBCH0037 Should have USAGE DISPLAY
    The data item should have USAGE DISPLAY.
  • COBCH0038 Paragraph or phrase repeated illegally
    You have specified a paragraph or phrase more than once, when you might specify it only once.
  • COBCH0039 Too many COPY ... REPLACING statements
    The program contains more than 255 COPY...REPLACING statements.
  • COBCH0040 Missing or illegal file name
    The filename you have specified either does not conform to COBOL rules for filenames, or has not been declared in the FILE-CONTROL paragraph. This might be due to a misspelled valid filename.
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0021 Too many qualifiers

You have used too many qualifiers when referring to a qualified data-name, procedure-name or text-name.

Resolution:

Change the reference in error so that it uses no more than the permitted number of qualifiers.

Parent topic: COBCH0021 - COBCH0040


COBCH0022 SKIP1/2/3, EJECT and TITLE must be alone on line

Source program lines containing these words must not contain any other words.

Resolution:

Edit your program so that these words are on a line of their own.

Parent topic: COBCH0021 - COBCH0040


COBCH0023 Nonnumeric literal expected

You must specify a nonnumeric literal in this context.

Resolution:

Ensure that the literal you have specified conforms to the rules for nonnumeric literals.

Parent topic: COBCH0021 - COBCH0040


COBCH0024 Illegal qualifier

You have specified a qualified data-name, procedure-name, or text-name incorrectly.

Resolution:

Correct the qualified reference.

Parent topic: COBCH0021 - COBCH0040


COBCH0025 Qualification not permitted

You cannot qualify a data-name, procedure-name, or text-name in this context.

Resolution:

Make the reference an unqualified reference.

Parent topic: COBCH0021 - COBCH0040


COBCH0026 Literal too long

Resolution:

Parent topic: COBCH0021 - COBCH0040


COBCH0027 Number too large

You have declared a numeric value that is too large.

Refer to the syntax rules for the particular declaration, as detailed in the COBOL Language Reference.

Parent topic: COBCH0021 - COBCH0040
Related reference
Concepts of the COBOL Language
Size and Number of Data Items
COBOL Language Reference


COBCH0028 Data item too long

You have declared a data item that is too long for the specified data-type.

Resolution:

See the related topics for information on the maximum sizes of data items of various types.

Parent topic: COBCH0021 - COBCH0040
Related reference
Compilation Groups


COBCH0029 Not a data-name

You have specified an operand that is not a data item where a valid data item is expected. For example, you might have specified an FD-name or a condition-name instead of a data-name.

Resolution:

Ensure that the item that is in error is a data-name, and that it is declared.

Parent topic: COBCH0021 - COBCH0040


COBCH0030 Should be a group

You have specified an elementary item as the sending or receiving field in a MOVE CORRESPONDING statement.

Resolution:

Ensure that both the sending and receiving fields are group items.

Parent topic: COBCH0021 - COBCH0040


COBCH0031 Should be elementary

You have specified the name of a group data item in a context in which an elementary item must be used.

Resolution:

Change the reference so that it is a reference to an elementary item.

Parent topic: COBCH0021 - COBCH0040


COBCH0032 Should be unitary

You have specified a subscripted or indexed data item where one is not allowed.

Resolution:

Change the reference so that it is a reference to a unitary (that is, nonsubscripted and nonindexed) data item.

Parent topic: COBCH0021 - COBCH0040


COBCH0033 Should be procedure name

A procedure-name (that is, a paragraph or section-name) is expected in this context. You have probably specified a data-name.

Resolution:

Ensure the procedure-name is correct.

Parent topic: COBCH0021 - COBCH0040


COBCH0034 Operand operand should be numeric

A numeric value is required in this context, and you have specified a nonnumeric value.

Resolution:

Make the value numeric.

Parent topic: COBCH0021 - COBCH0040


COBCH0035 Integer required

An integer value is required in this context, and you have specified a noninteger value.

Resolution:

Make the value an integer value.

Parent topic: COBCH0021 - COBCH0040


COBCH0036 Should be alphanumeric

An alphanumeric value is required in this context, and you have specified a numeric value.

Resolution:

Make the value an alphanumeric value.

Parent topic: COBCH0021 - COBCH0040


COBCH0037 Should have USAGE DISPLAY

The data item should have USAGE DISPLAY.

Resolution:

Change the data item's USAGE to DISPLAY.

Parent topic: COBCH0021 - COBCH0040


COBCH0038 Paragraph or phrase repeated illegally

You have specified a paragraph or phrase more than once, when you might specify it only once.

Resolution:

Delete the repeated paragraph or phrase.

Parent topic: COBCH0021 - COBCH0040


COBCH0039 Too many COPY ... REPLACING statements

The program contains more than 255 COPY...REPLACING statements.

Resolution:

Correct your program so that it contains fewer than 255 COPY...REPLACING statements.

Parent topic: COBCH0021 - COBCH0040


COBCH0040 Missing or illegal file name

The filename you have specified either does not conform to COBOL rules for filenames, or has not been declared in the FILE-CONTROL paragraph. This might be due to a misspelled valid filename.

Resolution:

Correct the filename (or, if necessary, add a file description entry to the FILE-CONTROL paragraph).

Parent topic: COBCH0021 - COBCH0040


COBCH0041 - COBCH0060

Lists the Syntax Checking error messages from COBCH0041 through COBCH0060.

  • COBCH0041 ZERO is an invalid value for an index-name
    You cannot enter a zero value here.
  • COBCH0042 Must be nonzero
    The numeric value you specify here must be nonzero.
  • COBCH0043 Literal or figurative constant expected
    You must specify a literal value or a figurative constant here.
  • COBCH0044 Literal expected
    You must specify a literal value here.
  • COBCH0045 Operand data-name has wrong size
    The operand in this statement is the wrong length (for example, you have specified a prompt character more than one character long).
  • COBCH0046 Alphabet name required
    You must specify the name of a user-defined collating sequence here.
  • COBCH0047 Numeric literal or ZERO expected
    You must specify a numeric literal or the figurative constant ZERO here.
  • COBCH0048 Missing or extra right parenthesis
    The number of left and right parentheses in an arithmetic expression is not the same.
  • COBCH0049 Illegal use of Index-name or Index Data item
    You have used an item with USAGE INDEX in a context where it is not allowed. See the related topics for details of where you can use such items.
  • COBCH0050 Illegal use of POINTER data item, ADDRESS OF or NULL
    You have tried to perform an illegal operation on a data item with USAGE POINTER. Alternatively, you have tried to apply the ADDRESS OF phrase to an item that is not an 01 or 77 level item in the Working-Storage or Linkage Section.
  • COBCH0051 Not a report name
    You must use a report-name in this context. You have probably misspelled a valid report-name.
  • COBCH0052 Only allowed with SEQUENTIAL files
    You have performed an operation that is permitted only if the file has SEQUENTIAL organization (for example, CLOSE REEL/UNIT).
  • COBCH0053 Directive directive invalid or not allowed here
    You have either specified a COBOL system directive in the wrong place or specified an invalid COBOL system directive in a $SET statement in your program.
  • COBCH0054 Class name required
    You have failed to define the class-name in the SPECIAL-NAMES paragraph, or you have misspelled a COBOL class-name.
  • COBCH0055 Index-name set to value greater than table size
    A SET index-name TO literal statement has been used to try to set an index name to a value greater than the number in the OCCURS clause for which that index name belongs.
  • COBCH0056 COPY is recursive
    One of the following:
  • COBCH0057 Not a report group
    You must use a report group in this context. You have probably misspelled a valid report group-name.
  • COBCH0058 Not a report name or a report group
    You have specified neither a valid report-name nor a valid report group in a GENERATE statement. You have probably misspelled the report-name or the report group.
  • COBCH0059 Cannot GENERATE this report name
    The report-name that you have specified should contain all of the following:
  • COBCH0060 Not a detail group
    You have specified a report group that is not of TYPE DETAIL.
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0041 ZERO is an invalid value for an index-name

You cannot enter a zero value here.
Parent topic: COBCH0041 - COBCH0060


COBCH0042 Must be nonzero

The numeric value you specify here must be nonzero.

Resolution:

Specify a nonzero value.

Parent topic: COBCH0041 - COBCH0060


COBCH0043 Literal or figurative constant expected

You must specify a literal value or a figurative constant here.

Resolution:

Alter the value you have specified to be a literal or a figurative constant.

Parent topic: COBCH0041 - COBCH0060


COBCH0044 Literal expected

You must specify a literal value here.

Resolution:

Alter the value you have specified to be a literal value.

Parent topic: COBCH0041 - COBCH0060


COBCH0045 Operand data-name has wrong size

The operand in this statement is the wrong length (for example, you have specified a prompt character more than one character long).

Resolution:

See the related topics for information on the correct length of the operand.

Parent topic: COBCH0041 - COBCH0060
Related reference
Compilation Groups


COBCH0046 Alphabet name required

You must specify the name of a user-defined collating sequence here.

Resolution:

The name of the alphabet that you have defined in the SPECIAL-NAMES paragraph should be specified.

Parent topic: COBCH0041 - COBCH0060


COBCH0047 Numeric literal or ZERO expected

You must specify a numeric literal or the figurative constant ZERO here.

Resolution:

Specify a numeric literal or ZERO.

Parent topic: COBCH0041 - COBCH0060


COBCH0048 Missing or extra right parenthesis

The number of left and right parentheses in an arithmetic expression is not the same.

Resolution:

Check the format of the arithmetic expression and ensure that you have a matching right parenthesis for each left parenthesis.

Parent topic: COBCH0041 - COBCH0060


COBCH0049 Illegal use of Index-name or Index Data item

You have used an item with USAGE INDEX in a context where it is not allowed. See the related topics for details of where you can use such items.

Resolution:

Change the USAGE of the item, or use an item that does not have USAGE INDEX.

Parent topic: COBCH0041 - COBCH0060
Related reference
Compilation Groups
Data Description Entry Skeleton
Screen Section Entry Skeleton
The USAGE Clause
The USAGE Clause
The USAGE Clause in the Screen Section


COBCH0050 Illegal use of POINTER data item, ADDRESS OF or NULL

You have tried to perform an illegal operation on a data item with USAGE POINTER. Alternatively, you have tried to apply the ADDRESS OF phrase to an item that is not an 01 or 77 level item in the Working-Storage or Linkage Section.

Resolution:

See the related topics for details of the operations you can perform on pointer items.

Parent topic: COBCH0041 - COBCH0060
Related reference
The CALL Statement
The CHAIN Statement
Compilation Groups
Concepts of the COBOL Language
Data Description Entry Skeleton
The EXIT Statement
The GOBACK Statement
The INVOKE Statement
Screen Section Entry Skeleton
The SET Statement
The STOP Statement
The USAGE Clause
The USAGE Clause
The USAGE Clause in the Screen Section
XML Syntax - SELECT Clause


COBCH0051 Not a report name

You must use a report-name in this context. You have probably misspelled a valid report-name.

Resolution:

Correct the reference.

Parent topic: COBCH0041 - COBCH0060


COBCH0052 Only allowed with SEQUENTIAL files

You have performed an operation that is permitted only if the file has SEQUENTIAL organization (for example, CLOSE REEL/UNIT).

Resolution:

Change the file organization to SEQUENTIAL.

Parent topic: COBCH0041 - COBCH0060


COBCH0053 Directive directive invalid or not allowed here

You have either specified a COBOL system directive in the wrong place or specified an invalid COBOL system directive in a $SET statement in your program.

Resolution:

For example, you can specify a $SET LIST anywhere, but a $SET PREPROCESS only on the first line.

Parent topic: COBCH0041 - COBCH0060


COBCH0054 Class name required

You have failed to define the class-name in the SPECIAL-NAMES paragraph, or you have misspelled a COBOL class-name.

Resolution:

Either define the class-name in the SPECIAL-NAMES paragraph, or make sure you have spelled the COBOL class-name you want to use correctly.

Parent topic: COBCH0041 - COBCH0060


COBCH0055 Index-name set to value greater than table size

A SET index-name TO literal statement has been used to try to set an index name to a value greater than the number in the OCCURS clause for which that index name belongs.
Parent topic: COBCH0041 - COBCH0060


COBCH0056 COPY is recursive

One of the following:
  • You have tried to COPY a file that you have already started copying.
  • You have incorrectly spelled the name of either the file you have previously started to COPY, or the file you currently want to copy.

Resolution:

Revise your program so that the file you have already started to COPY is copied completely before you try to COPY the same file again.

Correct the spelling error.

Parent topic: COBCH0041 - COBCH0060


COBCH0057 Not a report group

You must use a report group in this context. You have probably misspelled a valid report group-name.

Resolution:

Correct the reference.

Parent topic: COBCH0041 - COBCH0060


COBCH0058 Not a report name or a report group

You have specified neither a valid report-name nor a valid report group in a GENERATE statement. You have probably misspelled the report-name or the report group.

Resolution:

Correct your reference to the report-name or to the report group.

Parent topic: COBCH0041 - COBCH0060


COBCH0059 Cannot GENERATE this report name

The report-name that you have specified should contain all of the following:
  • A CONTROL clause
  • Only one DETAIL report group
  • At least one body group.

Resolution:

See the related topics for details of the contents you require for a report-name when it is used in a GENERATE statement.

Parent topic: COBCH0041 - COBCH0060
Related reference
The ACCEPT Statement
The CONTROL Clause
The DISPLAY Statement
Screen Section Entry Skeleton
The CONTROL Clause
The GENERATE Statement
The TYPE Clause
The XML GENERATE Statement


COBCH0060 Not a detail group

You have specified a report group that is not of TYPE DETAIL.

Resolution:

Revise your program so that the report group is of TYPE DETAIL.

Parent topic: COBCH0041 - COBCH0060


COBCH0061 - COBCH0080

Lists the Syntax Checking error messages from COBCH0061 through COBCH0080.

  • COBCH0061 Pseudo text incorrectly specified
    A two-character delimiter for pseudotext is missing from either a REPLACE or COPY REPLACING statement.
  • COBCH0062 Nested COPY replacement causes termination of parent COPY replacement
    When text replacement is already active because a parent COPY statement uses the REPLACING phrase, any text replacement specified in a nested COPY statement that uses the REPLACING phrase terminates (or overrides) all copy text replacement specified in the parent COPY statement.
  • COBCH0063 Cannot be used in nested program
    Your program contains a statement or clause that is not valid in a nested program.
  • COBCH0064 If file is EXTERNAL, then PADDING CHARACTER must be also
    If a file is defined as EXTERNAL then the data item specified in the associated PADDING CHARACTER clause must also be defined as EXTERNAL.
  • COBCH0065 Unsigned integer required
    An unsigned integer was expected but not supplied.
  • COBCH0066 Data item must have fixed location
    An item which is part of an OCCURS ... DEPENDING ON (ODO) table entry is being used as a subscript to the table, or to another ODO table earlier in the group. This is not allowed.
  • COBCH0067 Please recompile using a larger value for the LINKCOUNT directive
  • COBCH0068 SQL error
    The compiler detected the error shown on your screen in your SQL syntax.
  • COBCH0069 Error code code during SQL Remote Precompile. Cannot continue.
    The compiler detected the error code ruring the remote SQL precompile.
  • COBCH0070 Invalid argument
    You have either specified a COBOL system directive with an invalid argument in a $SET statement in your program or you have specified an incorrect argument type for an intrinsic function.
  • COBCH0071 PROCEDURE DIVISION missing or unknown statement
    You have omitted the PROCEDURE DIVISION header, and have then started without a verb.
  • COBCH0072 Invalid FUNCTION name
    The name specified after the word FUNCTION is not a recognized function-name. It is possible you are using the word "function" as a data-name. This word is a reserved word.
  • COBCH0073 Missing left parenthesis
    You have specified an intrinsic function which requires parameters, but have not preceded the parameter list with a left parenthesis.
  • COBCH0074 Numeric argument expected
    You have specified a nonnumeric argument with an intrinsic function which is expecting a numeric argument.
  • COBCH0075 Alphanumeric argument expected
    You have specified a numeric argument with an intrinsic function where an alphanumeric argument was expected.
  • COBCH0076 Illegal combination of argument types
    The set of arguments you have specified with an intrinsic function do not match the types required for that function.
  • COBCH0077 Unexpected end of source within EXEC
    The end of a program source was encountered in an EXEC statement. This probably indicates that an END-EXEC has been omitted earlier in the program.
  • COBCH0078 Numeric function not allowed
    You have specified an intrinsic function that returns a numeric value in a position where a numeric value is not allowed.
  • COBCH0079 Argument must have length 1
    The argument you have specified does not have a length of 1.
  • COBCH0080 Prompt character incompatible for ACCEPT
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0061 Pseudo text incorrectly specified

A two-character delimiter for pseudotext is missing from either a REPLACE or COPY REPLACING statement.

Resolution:

Insert the missing pseudotext delimiter (that is, ==) at the appropriate point in your program.

Parent topic: COBCH0061 - COBCH0080


COBCH0062 Nested COPY replacement causes termination of parent COPY replacement

When text replacement is already active because a parent COPY statement uses the REPLACING phrase, any text replacement specified in a nested COPY statement that uses the REPLACING phrase terminates (or overrides) all copy text replacement specified in the parent COPY statement.

When the copybook copied by the nested COPY statement reaches end-of-file, the COPY text replacement will not be active for any additional source text read by the Compiler. This does not apply to a REPLACE statement text replacement.

Parent topic: COBCH0061 - COBCH0080


COBCH0063 Cannot be used in nested program

Your program contains a statement or clause that is not valid in a nested program.

Resolution:

See Program Definition for the valid structure of a nested program.

Parent topic: COBCH0061 - COBCH0080
Related reference
Part 2. Program Definition


COBCH0064 If file is EXTERNAL, then PADDING CHARACTER must be also

If a file is defined as EXTERNAL then the data item specified in the associated PADDING CHARACTER clause must also be defined as EXTERNAL.
Parent topic: COBCH0061 - COBCH0080


COBCH0065 Unsigned integer required

An unsigned integer was expected but not supplied.

Resolution:

Specify an unsigned integer.

Parent topic: COBCH0061 - COBCH0080


COBCH0066 Data item must have fixed location

An item which is part of an OCCURS ... DEPENDING ON (ODO) table entry is being used as a subscript to the table, or to another ODO table earlier in the group. This is not allowed.

Resolution:

Move the item to a location outside the ODO and use that item in this statement.

Parent topic: COBCH0061 - COBCH0080


COBCH0067 Please recompile using a larger value for the LINKCOUNT directive

Resolution:

Parent topic: COBCH0061 - COBCH0080


COBCH0068 SQL error

The compiler detected the error shown on your screen in your SQL syntax.

Resolution:

Refer to your SQL documentation for details of valid SQL syntax.

Parent topic: COBCH0061 - COBCH0080


COBCH0069 Error code code during SQL Remote Precompile. Cannot continue.

The compiler detected the error code ruring the remote SQL precompile.

Resolution:

Refer to your SQL documentation for details of valid SQL syntax.

Parent topic: COBCH0061 - COBCH0080


COBCH0070 Invalid argument

You have either specified a COBOL system directive with an invalid argument in a $SET statement in your program or you have specified an incorrect argument type for an intrinsic function.

Resolution:

Correct the arguments.

Parent topic: COBCH0061 - COBCH0080


COBCH0071 PROCEDURE DIVISION missing or unknown statement

You have omitted the PROCEDURE DIVISION header, and have then started without a verb.
Parent topic: COBCH0061 - COBCH0080


COBCH0072 Invalid FUNCTION name

The name specified after the word FUNCTION is not a recognized function-name. It is possible you are using the word "function" as a data-name. This word is a reserved word.

Resolution:

If you require an intrinsic function, ensure the name you have used is correct. If you want to use function as a data-name, resubmit your program with the directive REMOVE"FUNCTION" to remove the word FUNCTION from the reserved word list.

Parent topic: COBCH0061 - COBCH0080


COBCH0073 Missing left parenthesis

You have specified an intrinsic function which requires parameters, but have not preceded the parameter list with a left parenthesis.

Resolution:

Check the format of the intrinsic function and ensure that you have a matching left parenthesis for each right parenthesis.

Parent topic: COBCH0061 - COBCH0080


COBCH0074 Numeric argument expected

You have specified a nonnumeric argument with an intrinsic function which is expecting a numeric argument.

Resolution:

Make the argument numeric.

Parent topic: COBCH0061 - COBCH0080


COBCH0075 Alphanumeric argument expected

You have specified a numeric argument with an intrinsic function where an alphanumeric argument was expected.

Resolution:

Make the argument alphanumeric.

Parent topic: COBCH0061 - COBCH0080


COBCH0076 Illegal combination of argument types

The set of arguments you have specified with an intrinsic function do not match the types required for that function.

Resolution:

Revise your code to comply with the rules governing the construction of argument types.

Parent topic: COBCH0061 - COBCH0080


COBCH0077 Unexpected end of source within EXEC

The end of a program source was encountered in an EXEC statement. This probably indicates that an END-EXEC has been omitted earlier in the program.

Resolution:

Ensure that each EXEC has a matching END-EXEC.

Parent topic: COBCH0061 - COBCH0080


COBCH0078 Numeric function not allowed

You have specified an intrinsic function that returns a numeric value in a position where a numeric value is not allowed.

Resolution:

Make the intrinsic function nonnumeric.

Parent topic: COBCH0061 - COBCH0080


COBCH0079 Argument must have length 1

The argument you have specified does not have a length of 1.

Resolution:

Change your argument, specifying length 1.

Parent topic: COBCH0061 - COBCH0080


COBCH0080 Prompt character incompatible for ACCEPT

Parent topic: COBCH0061 - COBCH0080


COBCH0081 - COBCH0100

Lists the Syntax Checking error messages from COBCH0081 through COBCH0100.

  • COBCH0081 Please recompile using a larger value for LOCALCOUNT directive
  • COBCH0082 COBOL Division or Section header encountered in incorrect order
    A COBOL Division or Section header was encountered in the wrong order in the source. For example, LINKAGE SECTION was encountered after SCREEN SECTION had already been read.
  • COBCH0083 Reserved word missing - word expected
    The reserved word word was expected but not found.
  • COBCH0084 SQL statement only allowed in the Procedure Division
  • COBCH0085 SQL statement only allowed in the Data Division
  • COBCH0086 Constant-name data-name same as reserved word
  • COBCH0087 SIZE must be a positive integer
    You have use the syntax CALL BY VALUE SIZE size with an invalid size.
  • COBCH0088 A SQL host variable name contains an underscore - illegal COBOL character.
    A host variable inside an SQL statement contained an underscore character and could not be processed.
  • COBCH0089 SQL statement contains more than one SQLDA.
    The COBOL system found more than one COBOL data items used as SQL Descriptor Areas in a single SQL statement, which is illegal.
  • COBCH0090 Too many errors
    The number of messages produced has reached the limit specified by the MAX-ERROR directive.
  • COBCH0091 Syntax not compatible with FILETYPE(11)
  • COBCH0092 Redefinition causes ambiguity in location of sliding data-item
  • COBCH0093 User-name not unique. Assumed qualified by current 01 level record
    The specified user-name is not unique, but has been qualified by the current 01 level item.
  • COBCH0094 Name is not a COBOL word
    The name you have specified is not a reserved word in COBOL.
  • COBCH0095 Literal used as COPY name
  • COBCH0096 Lower case used (future occurrences not flagged)
    You have used lower case where upper case was expected.
  • COBCH0097 Both single and double quotes used (future occurrences not flagged)
  • COBCH0098 Single quotes (apostrophe) used (future occurrences not flagged)
  • COBCH0099 Nested COPY file
  • COBCH0100 Sequence number out of order
    One or more numbers in your source code are out of sequence.
Parent topic: Messages COBCH0001 to COBCH0100


COBCH0081 Please recompile using a larger value for LOCALCOUNT directive

Parent topic: COBCH0081 - COBCH0100


COBCH0082 COBOL Division or Section header encountered in incorrect order

A COBOL Division or Section header was encountered in the wrong order in the source. For example, LINKAGE SECTION was encountered after SCREEN SECTION had already been read.
Parent topic: COBCH0081 - COBCH0100


COBCH0083 Reserved word missing - word expected

The reserved word word was expected but not found.
Parent topic: COBCH0081 - COBCH0100


COBCH0084 SQL statement only allowed in the Procedure Division

Parent topic: COBCH0081 - COBCH0100


COBCH0085 SQL statement only allowed in the Data Division

Parent topic: COBCH0081 - COBCH0100


COBCH0086 Constant-name data-name same as reserved word

Parent topic: COBCH0081 - COBCH0100


COBCH0087 SIZE must be a positive integer

You have use the syntax CALL BY VALUE SIZE size with an invalid size.

Resolution:

Recode with a valid positive integer.

Parent topic: COBCH0081 - COBCH0100


COBCH0088 A SQL host variable name contains an underscore - illegal COBOL character.

A host variable inside an SQL statement contained an underscore character and could not be processed.

Resolution:

Remove the underscore character. The message usually indicates that an underscore was used where a hyphen (-) was intended.

Parent topic: COBCH0081 - COBCH0100


COBCH0089 SQL statement contains more than one SQLDA.

The COBOL system found more than one COBOL data items used as SQL Descriptor Areas in a single SQL statement, which is illegal.

Resolution:

Ensure that the correct data items are used. The message is produced when the Compiler directive SQL(NODB2) is set and host variables are not declared inside the SQL DECLARE SECTION.

Parent topic: COBCH0081 - COBCH0100


COBCH0090 Too many errors

The number of messages produced has reached the limit specified by the MAX-ERROR directive.
Parent topic: COBCH0081 - COBCH0100
Related reference
MAX-ERROR


COBCH0091 Syntax not compatible with FILETYPE(11)

Parent topic: COBCH0081 - COBCH0100


COBCH0092 Redefinition causes ambiguity in location of sliding data-item

Parent topic: COBCH0081 - COBCH0100


COBCH0093 User-name not unique. Assumed qualified by current 01 level record

The specified user-name is not unique, but has been qualified by the current 01 level item.
Parent topic: COBCH0081 - COBCH0100


COBCH0094 Name is not a COBOL word

The name you have specified is not a reserved word in COBOL.

Resolution:

Change the name accordingly.

Parent topic: COBCH0081 - COBCH0100


COBCH0095 Literal used as COPY name

Parent topic: COBCH0081 - COBCH0100


COBCH0096 Lower case used (future occurrences not flagged)

You have used lower case where upper case was expected.
Parent topic: COBCH0081 - COBCH0100


COBCH0097 Both single and double quotes used (future occurrences not flagged)

Parent topic: COBCH0081 - COBCH0100


COBCH0098 Single quotes (apostrophe) used (future occurrences not flagged)

Parent topic: COBCH0081 - COBCH0100


COBCH0099 Nested COPY file

Parent topic: COBCH0081 - COBCH0100


COBCH0100 Sequence number out of order

One or more numbers in your source code are out of sequence.

Resolution:

Check that all sequence numbers are specified in correct numeric order.

Parent topic: COBCH0081 - COBCH0100


Messages COBCH0101 to COBCH0200

  • COBCH0101 - COBCH0120
    Lists the Syntax Checking error messages from COBCH0101 through COBCH0120.
  • COBCH0121 - COBCH0140
    Lists the Syntax Checking error messages from COBCH0121 through COBCH0140.
  • COBCH0141 - COBCH0160
    Lists the Syntax Checking error messages from COBCH0141 through COBCH0160.
  • COBCH0161 - COBCH0180
    Lists the Syntax Checking error messages from COBCH0161 through COBCH0180.
  • COBCH0181 - COBCH0200
    Lists the Syntax Checking error messages from COBCH0181 through COBCH0200.
Parent topic: Syntax Checking Error Messages


COBCH0101 - COBCH0120

Lists the Syntax Checking error messages from COBCH0101 through COBCH0120.

  • COBCH0101 Assignment-name is data-name
  • COBCH0102 RELATIVE KEY clause should immediately follow ACCESS clause
  • COBCH0103 RECORD missing
    You have omitted the word RECORD.
  • COBCH0104 IDENTIFICATION missing
  • COBCH0105 PROGRAM-ID missing
    You have omitted the word PROGRAM-ID from the PROGRAM-ID paragraph.
  • COBCH0106 PROGRAM-ID has illegal format
    You have specified an invalid program-name in the PROGRAM-ID paragraph.
  • COBCH0107 Second status area
    You cannot have more than one identifier after the FILE STATUS clause.
  • COBCH0108 OPTIONAL not permitted on non-sequential file
  • COBCH0109 Paragraphs or phrases in non-standard order or repeated
    You have either specified paragraphs in the wrong order, or a paragraph twice, or SPECIAL-NAMES clauses in a nonstandard order.
  • COBCH0110 ENVIRONMENT missing
    You have omitted the word ENVIRONMENT.
  • COBCH0111 CONFIGURATION missing
    You have omitted the word CONFIGURATION.
  • COBCH0112 SOURCE-COMPUTER missing
    You have omitted the words SOURCE-COMPUTER.
  • COBCH0113 SPECIAL-NAMES clause error
    You have not specified the SPECIAL-NAMES paragraph correctly.
  • COBCH0114 OBJECT-COMPUTER missing
    You have omitted the words OBJECT-COMPUTER.
  • COBCH0115 OBJECT-COMPUTER clause not recognized
    You have specified the OBJECT-COMPUTER paragraph incorrectly.
  • COBCH0116 Character specified twice in alphabet
    You have specified at least one character twice in the ALPHABET clause. For example, you might have included a character in a range and also specified it as a literal.
  • COBCH0117 SWITCH clause error or system name/mnemonic name error
    An error exists in the coding of the SWITCH clause of the SPECIAL-NAMES paragraph in the Environment Division of your program.
  • COBCH0118 COMMA expected
    You have omitted the word COMMA from the DECIMAL-POINT clause.
  • COBCH0119 CRT expected
    You have used a COBOL word or user-defined word where your COBOL system expected the reserved word CRT.
  • COBCH0120 Illegal currency symbol
    The literal which you have specified in the CURRENCY SIGN IS clause in the SPECIAL-NAMES paragraph of your program is not one of those permitted under the rules of COBOL syntax, or if it is then you have failed to enclose it in quotation marks. The literal must be a single character, not a digit, and cannot be any of the following, A B C D L P S V X Z * + - , . ; ( ) " / = or space (except in ANS85 where L is valid).
Parent topic: Messages COBCH0101 to COBCH0200


COBCH0101 Assignment-name is data-name

Parent topic: COBCH0101 - COBCH0120


COBCH0102 RELATIVE KEY clause should immediately follow ACCESS clause

Parent topic: COBCH0101 - COBCH0120


COBCH0103 RECORD missing

You have omitted the word RECORD.

Resolution:

Add the word RECORD.

Parent topic: COBCH0101 - COBCH0120


COBCH0104 IDENTIFICATION missing

Parent topic: COBCH0101 - COBCH0120


COBCH0105 PROGRAM-ID missing

You have omitted the word PROGRAM-ID from the PROGRAM-ID paragraph.

Resolution:

Add the word PROGRAM-ID to the PROGRAM-ID paragraph.

Parent topic: COBCH0101 - COBCH0120


COBCH0106 PROGRAM-ID has illegal format

You have specified an invalid program-name in the PROGRAM-ID paragraph.

Resolution:

Correct the format of program-names.

Parent topic: COBCH0101 - COBCH0120


COBCH0107 Second status area

You cannot have more than one identifier after the FILE STATUS clause.
Parent topic: COBCH0101 - COBCH0120


COBCH0108 OPTIONAL not permitted on non-sequential file

Parent topic: COBCH0101 - COBCH0120


COBCH0109 Paragraphs or phrases in non-standard order or repeated

You have either specified paragraphs in the wrong order, or a paragraph twice, or SPECIAL-NAMES clauses in a nonstandard order.

Resolution:

If you have repeated any of these, delete the repetition.

Parent topic: COBCH0101 - COBCH0120


COBCH0110 ENVIRONMENT missing

You have omitted the word ENVIRONMENT.

Resolution:

Add the word ENVIRONMENT.

Parent topic: COBCH0101 - COBCH0120


COBCH0111 CONFIGURATION missing

You have omitted the word CONFIGURATION.

Resolution:

Add the word CONFIGURATION.

Parent topic: COBCH0101 - COBCH0120


COBCH0112 SOURCE-COMPUTER missing

You have omitted the words SOURCE-COMPUTER.

Resolution:

Add the words SOURCE-COMPUTER.

Parent topic: COBCH0101 - COBCH0120


COBCH0113 SPECIAL-NAMES clause error

You have not specified the SPECIAL-NAMES paragraph correctly.

Resolution:

Correct the format of the SPECIAL-NAMES paragraph.

Parent topic: COBCH0101 - COBCH0120


COBCH0114 OBJECT-COMPUTER missing

You have omitted the words OBJECT-COMPUTER.

Resolution:

Add the words OBJECT-COMPUTER.

Parent topic: COBCH0101 - COBCH0120


COBCH0115 OBJECT-COMPUTER clause not recognized

You have specified the OBJECT-COMPUTER paragraph incorrectly.

Resolution:

Correct the format of the OBJECT-COMPUTER paragraph.

Parent topic: COBCH0101 - COBCH0120


COBCH0116 Character specified twice in alphabet

You have specified at least one character twice in the ALPHABET clause. For example, you might have included a character in a range and also specified it as a literal.

Resolution:

Edit your source code so that the characters specified in the ALPHABET clause are referenced only once.

Parent topic: COBCH0101 - COBCH0120


COBCH0117 SWITCH clause error or system name/mnemonic name error

An error exists in the coding of the SWITCH clause of the SPECIAL-NAMES paragraph in the Environment Division of your program.

Resolution:

Revise your program accordingly. Ensure that each condition named in this clause is declared in the Data Division.

Parent topic: COBCH0101 - COBCH0120


COBCH0118 COMMA expected

You have omitted the word COMMA from the DECIMAL-POINT clause.

Resolution:

Add the word COMMA.

Parent topic: COBCH0101 - COBCH0120


COBCH0119 CRT expected

You have used a COBOL word or user-defined word where your COBOL system expected the reserved word CRT.

Resolution:

Edit your code so that the reserved word CRT is used.

Parent topic: COBCH0101 - COBCH0120


COBCH0120 Illegal currency symbol

The literal which you have specified in the CURRENCY SIGN IS clause in the SPECIAL-NAMES paragraph of your program is not one of those permitted under the rules of COBOL syntax, or if it is then you have failed to enclose it in quotation marks. The literal must be a single character, not a digit, and cannot be any of the following, A B C D L P S V X Z * + - , . ; ( ) " / = or space (except in ANS85 where L is valid).

Resolution:

Change the literal to a permitted character and ensure that it is enclosed in quotation marks.

Parent topic: COBCH0101 - COBCH0120


COBCH0121 - COBCH0140

Lists the Syntax Checking error messages from COBCH0121 through COBCH0140.

  • COBCH0121 Cannot specify DYNAMIC or EXTERNAL with literal file name
    You can specify DYNAMIC or EXTERNAL in the ASSIGN clause of a file description entry only if the filename is contained in a data item rather than given as a literal filename.
  • COBCH0122 Cannot use Double Byte characters in alphabet or class definition
    When defining an alphabet or class, you cannot use double-byte characters.
  • COBCH0123 I-O-CONTROL missing
    You have omitted the heading I-O-CONTROL.
  • COBCH0124 INPUT-OUTPUT missing
    You have omitted the heading INPUT-OUTPUT.
  • COBCH0125 FILE-CONTROL missing
    You have omitted the heading FILE-CONTROL.
  • COBCH0126 ASSIGN missing
    You have used a SELECT clause to give a file a filename which the program recognizes, but you have failed to use a corresponding ASSIGN clause to give the file an implementor-name (the name which the system recognizes).
  • COBCH0127 [LINE] SEQUENTIAL, RELATIVE or INDEXED missing
    In the ORGANIZATION IS clause of the FILE-CONTROL paragraph you have failed to specify the logical structure your file is to take.
  • COBCH0128 ACCESS missing on indexed/relative file
    The format of this clause depends on the organization of the data-file. If you have specified the ORGANIZATION clause for a file as either INDEXED or RELATIVE you must specify an ACCESS MODE clause for it, indicating which mode you will use to access that file. If no mode is specified, sequential access mode is assumed.
  • COBCH0129 Too many keys or key components
    The number of separate data items making up the record key and alternate key fields of one indexed file is too great.
  • COBCH0130 Illegal ORGANIZATION/ACCESS/KEY combination
    If you have specified these clauses in your program, they must be compatible, but in your program they are not.
  • COBCH0131 Unrecognized phrase in SELECT clause
    Your COBOL system has failed to accept part of your SELECT clause. This message could be given if the filename which you have given in the SELECT clause does not conform to the rules for the naming of COBOL files.
  • COBCH0132 Repeated "condition-name TO TRUE/FALSE" in SET statement
    You have specified a repeated "condition-name to TRUE/FALSE" phrase in a single SET statement. This does not conform to your selected flagging dialect.
  • COBCH0133 SAME AREA clause syntax error
    This optional clause, by which you allow two or more files to access the same central storage space, does not conform to the relevant syntax rules.
  • COBCH0134 FILE SECTION missing
    You have omitted the heading FILE SECTION.
  • COBCH0135 DATA DIVISION missing
    You have omitted the heading DATA DIVISION.
  • COBCH0136 Illegal use of phrase for National Locale operation
    You have included one or more of the following COBOL clauses in your program:
  • COBCH0137 Program collating sequence not defined
    You have included the PROGRAM COLLATING SEQUENCE clause in the OBJECT-COMPUTER paragraph of your code but have failed to code a corresponding ALPHABET-NAME in the SPECIAL-NAMES paragraph. Your code must contain an ALPHABET-NAME clause if it has a PROGRAM COLLATING SEQUENCE clause in it.
  • COBCH0138 "EXCLUSIVE", "AUTOMATIC" or "MANUAL" missing
    The LOCK MODE clause in the FILE-CONTROL paragraph of the Environment Division does not contain one of the words EXCLUSIVE, AUTOMATIC, or MANUAL, or if it does, your COBOL system has failed to recognize the word, perhaps owing to a spelling mistake. The LOCK MODE clause controls access to files shared between a number of users in a multi-user environment. Its form is determined by the filetype with which it is used.
  • COBCH0139 Illegal LOCK MODE/file type combination
    The format of the LOCK MODE clause depends on the file type. You have specified a LOCK MODE clause which is incompatible with the type of the specified file. Non-shareable files must have lock mode EXCLUSIVE while shareable files can have lock mode AUTOMATIC or MANUAL.
  • COBCH0140 For indexed file, PASSWORD phrase must follow KEY
    For an indexed sequential file description entry, any PASSWORD phrase must immediately follow the KEY phrase.
Parent topic: Messages COBCH0101 to COBCH0200


COBCH0121 Cannot specify DYNAMIC or EXTERNAL with literal file name

You can specify DYNAMIC or EXTERNAL in the ASSIGN clause of a file description entry only if the filename is contained in a data item rather than given as a literal filename.

Resolution:

Redesign your program so that the filename is contained in a data item.

Parent topic: COBCH0121 - COBCH0140


COBCH0122 Cannot use Double Byte characters in alphabet or class definition

When defining an alphabet or class, you cannot use double-byte characters.

Resolution:

Redesign your program so that your alphabet or class definition does not include any double-byte characters.

Parent topic: COBCH0121 - COBCH0140


COBCH0123 I-O-CONTROL missing

You have omitted the heading I-O-CONTROL.

Resolution:

Add the heading I-O-CONTROL.

Parent topic: COBCH0121 - COBCH0140


COBCH0124 INPUT-OUTPUT missing

You have omitted the heading INPUT-OUTPUT.

Resolution:

Add the heading INPUT-OUTPUT.

Parent topic: COBCH0121 - COBCH0140


COBCH0125 FILE-CONTROL missing

You have omitted the heading FILE-CONTROL.

Resolution:

Add the heading FILE-CONTROL.

Parent topic: COBCH0121 - COBCH0140


COBCH0126 ASSIGN missing

You have used a SELECT clause to give a file a filename which the program recognizes, but you have failed to use a corresponding ASSIGN clause to give the file an implementor-name (the name which the system recognizes).

Resolution:

Insert the relevant ASSIGN clause after the SELECT clause.

Parent topic: COBCH0121 - COBCH0140


COBCH0127 [LINE] SEQUENTIAL, RELATIVE or INDEXED missing

In the ORGANIZATION IS clause of the FILE-CONTROL paragraph you have failed to specify the logical structure your file is to take.

Resolution:

Insert [LINE] SEQUENTIAL, INDEXED, or RELATIVE into this clause depending on how you want your records to be stored and accessed in your file.

Parent topic: COBCH0121 - COBCH0140


COBCH0128 ACCESS missing on indexed/relative file

The format of this clause depends on the organization of the data-file. If you have specified the ORGANIZATION clause for a file as either INDEXED or RELATIVE you must specify an ACCESS MODE clause for it, indicating which mode you will use to access that file. If no mode is specified, sequential access mode is assumed.

Resolution:

See the related topics for information on the use of the ACCESS MODE clause.

Parent topic: COBCH0121 - COBCH0140
Related reference
Compilation Groups
Data Description Entry Skeleton
The File Control Entry
The OCCURS Clause
XML Syntax - SELECT Clause


COBCH0129 Too many keys or key components

The number of separate data items making up the record key and alternate key fields of one indexed file is too great.

Resolution:

Simplify your program so you do not need so many keys, or components of keys, to the file.

Parent topic: COBCH0121 - COBCH0140


COBCH0130 Illegal ORGANIZATION/ACCESS/KEY combination

If you have specified these clauses in your program, they must be compatible, but in your program they are not.

Resolution:

Ensure that these clauses are compatible.

Parent topic: COBCH0121 - COBCH0140


COBCH0131 Unrecognized phrase in SELECT clause

Your COBOL system has failed to accept part of your SELECT clause. This message could be given if the filename which you have given in the SELECT clause does not conform to the rules for the naming of COBOL files.

Resolution:

See the related topics for more information.

Parent topic: COBCH0121 - COBCH0140
Related reference
Compilation Groups
The File Control Entry
XML Syntax - SELECT Clause


COBCH0132 Repeated "condition-name TO TRUE/FALSE" in SET statement

You have specified a repeated "condition-name to TRUE/FALSE" phrase in a single SET statement. This does not conform to your selected flagging dialect.

Resolution:

Split into two separate SET statements.

Parent topic: COBCH0121 - COBCH0140


COBCH0133 SAME AREA clause syntax error

This optional clause, by which you allow two or more files to access the same central storage space, does not conform to the relevant syntax rules.

Resolution:

Correct the format for this clause.

Parent topic: COBCH0121 - COBCH0140


COBCH0134 FILE SECTION missing

You have omitted the heading FILE SECTION.

Resolution:

Add the heading FILE SECTION.

Parent topic: COBCH0121 - COBCH0140


COBCH0135 DATA DIVISION missing

You have omitted the heading DATA DIVISION.

Resolution:

Add the heading DATA DIVISION.

Parent topic: COBCH0121 - COBCH0140


COBCH0136 Illegal use of phrase for National Locale operation

You have included one or more of the following COBOL clauses in your program:
PROGRAM COLLATING SEQUENCE IS
ALPHABET IS
CURRENCY SIGN IS
DECIMAL-POINT IS COMMA
and you have submitted the program with the NLS (National Locale Support) directive on, which is not allowed.

Resolution:

Either turn the NLS directive off, or edit your source code to ensure none of the above clauses appear in the program.

Parent topic: COBCH0121 - COBCH0140


COBCH0137 Program collating sequence not defined

You have included the PROGRAM COLLATING SEQUENCE clause in the OBJECT-COMPUTER paragraph of your code but have failed to code a corresponding ALPHABET-NAME in the SPECIAL-NAMES paragraph. Your code must contain an ALPHABET-NAME clause if it has a PROGRAM COLLATING SEQUENCE clause in it.

Resolution:

Insert the necessary ALPHABET-NAME clause ensuring it has the same user-defined-name as that used in the SEQUENCE entry. If you have specified both of these clauses in your code but have still received this message then ensure that you have used the same user-defined-name in each and that it is spelled the same in both. Correct any spelling error your code might contain.

Parent topic: COBCH0121 - COBCH0140


COBCH0138 "EXCLUSIVE", "AUTOMATIC" or "MANUAL" missing

The LOCK MODE clause in the FILE-CONTROL paragraph of the Environment Division does not contain one of the words EXCLUSIVE, AUTOMATIC, or MANUAL, or if it does, your COBOL system has failed to recognize the word, perhaps owing to a spelling mistake. The LOCK MODE clause controls access to files shared between a number of users in a multi-user environment. Its form is determined by the filetype with which it is used.

Resolution:

Correct the LOCK MODE clause.

Parent topic: COBCH0121 - COBCH0140


COBCH0139 Illegal LOCK MODE/file type combination

The format of the LOCK MODE clause depends on the file type. You have specified a LOCK MODE clause which is incompatible with the type of the specified file. Non-shareable files must have lock mode EXCLUSIVE while shareable files can have lock mode AUTOMATIC or MANUAL.

Resolution:

Correct the LOCK MODE clause.

Parent topic: COBCH0121 - COBCH0140


COBCH0140 For indexed file, PASSWORD phrase must follow KEY

For an indexed sequential file description entry, any PASSWORD phrase must immediately follow the KEY phrase.

Resolution:

Edit your program so that the PASSWORD phrase immediately follows the KEY phrase.

Parent topic: COBCH0121 - COBCH0140


COBCH0141 - COBCH0160

Lists the Syntax Checking error messages from COBCH0141 through COBCH0160.

  • COBCH0141 File name appears in more than one SAME clause of same type
    A file can appear in only one SAME AREA or SAME RECORD AREA clause.
  • COBCH0142 Can only be used in nested program
    A clause you have specified is allowed only in a nested program. For example, the COMMON clause, as defined by ANSI.
  • COBCH0143 Unknown Identification Division paragraph
    The paragraph header specified is not a legal paragraph of the Identification Division; at least, not in the selected COBOL dialect.
  • COBCH0144 OCCURS DEPENDING subsidiary to OCCURS only allowed with ODOSLIDE
    You have a record containing OCCURS DEPENDING ON as part of a record defined with OCCURS.
  • COBCH0145 "SET condition-name TO" syntax used
    The SET condition-name TO ... syntax is not a part of your chosen flagging dialect.
  • COBCH0146 Condition-name set to FALSE
    You have tried to SET a condition-name to FALSE. This is not a part of your chosen flagging dialect.
  • COBCH0147 Data item must be unsigned
    You have used the syntax RECORD VARYING IN SIZE DEPENDING ON signed-data-item which does not conform with your selected flagging dialect.
  • COBCH0148 Status condition missing
    You have failed to specify a status condition following a function-name IS mnemonic-name clause in the SPECIAL-NAMES paragraph. This is not conformant with your selected flagging dialect.
  • COBCH0149 No SQL directives have been set
    An EXEC SQL statement has been encountered but no SQL directive has been specified. The processing of the statement varies depending on whether the directive SQL is set or not; either SQL or NOSQL must be explicitly specified.
  • COBCH0154 COPY REPLACING nested within COPY
    A COPY REPLACING statement has been detected, nested under another COPY.
  • COBCH0155 Numeric item should be an integer and without a 'P' in its picture clause
    Where one of the identifiers in a STRING statement is an elementary numeric data item, it must be described as an integer without the 'P' symbol in its PICTURE clause.
  • COBCH0156 Period found in wrong area of source line
Parent topic: Messages COBCH0101 to COBCH0200


COBCH0141 File name appears in more than one SAME clause of same type

A file can appear in only one SAME AREA or SAME RECORD AREA clause.

Resolution:

Revise your program.

Parent topic: COBCH0141 - COBCH0160


COBCH0142 Can only be used in nested program

A clause you have specified is allowed only in a nested program. For example, the COMMON clause, as defined by ANSI.

Resolution:

Revise your program.

Parent topic: COBCH0141 - COBCH0160


COBCH0143 Unknown Identification Division paragraph

The paragraph header specified is not a legal paragraph of the Identification Division; at least, not in the selected COBOL dialect.

Resolution:

Revise your program or select another COBOL dialect.

Parent topic: COBCH0141 - COBCH0160


COBCH0144 OCCURS DEPENDING subsidiary to OCCURS only allowed with ODOSLIDE

You have a record containing OCCURS DEPENDING ON as part of a record defined with OCCURS.

Resolution:

Set the ODOSLIDE directive.

Parent topic: COBCH0141 - COBCH0160


COBCH0145 "SET condition-name TO" syntax used

The SET condition-name TO ... syntax is not a part of your chosen flagging dialect.
Parent topic: COBCH0141 - COBCH0160


COBCH0146 Condition-name set to FALSE

You have tried to SET a condition-name to FALSE. This is not a part of your chosen flagging dialect.
Parent topic: COBCH0141 - COBCH0160


COBCH0147 Data item must be unsigned

You have used the syntax RECORD VARYING IN SIZE DEPENDING ON signed-data-item which does not conform with your selected flagging dialect.

Resolution:

Recode with an unsigned data item.

Parent topic: COBCH0141 - COBCH0160


COBCH0148 Status condition missing

You have failed to specify a status condition following a function-name IS mnemonic-name clause in the SPECIAL-NAMES paragraph. This is not conformant with your selected flagging dialect.

Resolution:

Specify at least one status condition.

Parent topic: COBCH0141 - COBCH0160


COBCH0149 No SQL directives have been set

An EXEC SQL statement has been encountered but no SQL directive has been specified. The processing of the statement varies depending on whether the directive SQL is set or not; either SQL or NOSQL must be explicitly specified.
Parent topic: COBCH0141 - COBCH0160


COBCH0154 COPY REPLACING nested within COPY

A COPY REPLACING statement has been detected, nested under another COPY.
Parent topic: COBCH0141 - COBCH0160


COBCH0155 Numeric item should be an integer and without a 'P' in its picture clause

Where one of the identifiers in a STRING statement is an elementary numeric data item, it must be described as an integer without the 'P' symbol in its PICTURE clause.
Parent topic: COBCH0141 - COBCH0160


COBCH0156 Period found in wrong area of source line

Parent topic: COBCH0141 - COBCH0160


COBCH0161 - COBCH0180

Lists the Syntax Checking error messages from COBCH0161 through COBCH0180.

  • COBCH0161 Can only be used within a Paragraph
  • COBCH0162 Can only be used within a Section
  • COBCH0163 DISPLAY ... UPON SYSERR can only have one operand
  • COBCH0164 More than 250 USE statements
    Your program contains more than 250 USE statements. There is a system limit of 250 USE statements in a program.
  • COBCH0165 NEXT SENTENCE followed by non-executable imperative/conditional statements
  • COBCH0166 Source and target lengths do not match (integer1 <> integer2)
  • COBCH0167 WRITE ... ADVANCING and POSITIONING syntax used on same file
  • COBCH0168 DEPENDING ON item in RECORD VARYING clause not in WORKING-STORAGE/LINKAGE
  • COBCH0170 Invalid argument in directive
    An incorrect argument has been specified when setting a Compiler directive.
  • COBCH0172 Qualifying name name not unique. Discarded.
  • COBCH0173 Space invalid here.
  • COBCH0174 A RECORDING MODE of 'S' was assumed for the above file
  • COBCH0175 A VALUE clause was specified for a sliding item.
  • COBCH0176 'RENAMES' object object is an 01 level item
  • COBCH0177 'RENAMES' object object is not present in the preceeding record
  • COBCH0178 DEPENDING missing. Fixed length assumed.
  • COBCH0179 Number of subscripts in VALUE clause does not match table dimension
    FROM or TO in a VALUE clause does not contain the correct number of subscripts; there should be one subscript for each level of OCCURS for the data declaration.
  • COBCH0180 One or more subscripts in a VALUE clause is out of range
    A subscript value exceeds the maximum number of occurrences specified in the corresponding OCCURS clause.
Parent topic: Messages COBCH0101 to COBCH0200


COBCH0161 Can only be used within a Paragraph

Parent topic: COBCH0161 - COBCH0180


COBCH0162 Can only be used within a Section

Parent topic: COBCH0161 - COBCH0180


COBCH0163 DISPLAY ... UPON SYSERR can only have one operand

Parent topic: COBCH0161 - COBCH0180


COBCH0164 More than 250 USE statements

Your program contains more than 250 USE statements. There is a system limit of 250 USE statements in a program.
Parent topic: COBCH0161 - COBCH0180


COBCH0165 NEXT SENTENCE followed by non-executable imperative/conditional statements

Parent topic: COBCH0161 - COBCH0180


COBCH0166 Source and target lengths do not match (integer1 <> integer2)

Parent topic: COBCH0161 - COBCH0180


COBCH0167 WRITE ... ADVANCING and POSITIONING syntax used on same file

Parent topic: COBCH0161 - COBCH0180


COBCH0168 DEPENDING ON item in RECORD VARYING clause not in WORKING-STORAGE/LINKAGE

Parent topic: COBCH0161 - COBCH0180


COBCH0170 Invalid argument in directive

An incorrect argument has been specified when setting a Compiler directive.

Check the required syntax for the particular directive, as specified in Compiler Directives - Alphabetical List.

Example

When using the REMOVE directive to remove more than one reserved word, each word must be enclosed in separate parenthesis or quotation marks; otherwise the error will occur.
$set REMOVE(NATIVE NEXT)    *> this is incorrect

$set REMOVE(NATIVE) (NEXT)  *> this is correct

$set REMOVE"NATIVE" "NEXT"  *> this is correct
Parent topic: COBCH0161 - COBCH0180
Related reference
Compiler Directives - Alphabetical List


COBCH0172 Qualifying name name not unique. Discarded.

Parent topic: COBCH0161 - COBCH0180


COBCH0173 Space invalid here.

Parent topic: COBCH0161 - COBCH0180


COBCH0174 A RECORDING MODE of 'S' was assumed for the above file

Parent topic: COBCH0161 - COBCH0180


COBCH0175 A VALUE clause was specified for a sliding item.

Parent topic: COBCH0161 - COBCH0180


COBCH0176 'RENAMES' object object is an 01 level item

Parent topic: COBCH0161 - COBCH0180


COBCH0177 'RENAMES' object object is not present in the preceeding record

Parent topic: COBCH0161 - COBCH0180


COBCH0178 DEPENDING missing. Fixed length assumed.

Parent topic: COBCH0161 - COBCH0180


COBCH0179 Number of subscripts in VALUE clause does not match table dimension

FROM or TO in a VALUE clause does not contain the correct number of subscripts; there should be one subscript for each level of OCCURS for the data declaration.
Parent topic: COBCH0161 - COBCH0180


COBCH0180 One or more subscripts in a VALUE clause is out of range

A subscript value exceeds the maximum number of occurrences specified in the corresponding OCCURS clause.

Resolution:

Recode your program.

Parent topic: COBCH0161 - COBCH0180


COBCH0181 - COBCH0200

Lists the Syntax Checking error messages from COBCH0181 through COBCH0200.

  • COBCH0181 FROM subscript in VALUE clause must not be greater than TO subscript
    The table element specified by the TO subscript precedes that specified by the FROM subscript.
  • COBCH0182 Limit exceeded - too many literals in VALUE clause
    The VALUE clause is too complex for the compiler to process. Inform technical support.
  • COBCH0183 VALUE clause would result in initialisation of elements beyond end of table
    Not all of the specified values are contained within the table being declared.
  • COBCH0184 In-line comment
    Your program contains an in-line comment. In-line comments are permitted in the non-mainframe dialect, but your program was compiled using a different dialect.
  • COBCH0185 END-EXEC missing, or unexpected EXEC
    An EXEC was encountered before an END-EXEC closed the previous EXEC. The most common reason for this is that an END-EXEC intended to close the previous EXEC was missing or misspelled.
  • COBCH0186 EXEC too large or END-EXEC missing/misspelled
    An EXEC statement is larger than the maximum allowed. This is most likely because an END-EXEC has been omitted or misspelled.
  • COBCH0187 Program is nested in a program defined with the "RECURSIVE" attribute
    Mainframe compilers do not allow the RECURSIVE clause in a program that also has nested programs.
  • COBCH0188 Key file %1_s not found
  • COBCH0189 Directives file filename not found
  • COBCH0190 Zero is an invalid value for an index-name. 1 assumed.
  • COBCH0191 OCCURS DEPENDING ON phrase bisected by additional clause!
  • COBCH0192 CALL parameter is group at level other than 01.
    Your selected flagging dialect does not allow a CALL parameter to be a group at a level other than 01.
  • COBCH0193 Use of Z literals
    Your selected flagging dialect does not support Z literals.
  • COBCH0194 CALL procedure pointer
    Your selected flagging dialect does not support this.
  • COBCH0195 ASCENDING/DESCENDING KEY clause must appear before INDEXED BY clause
    Your selected flagging dialect does not support reversing the order of these clauses in the OCCURS phrase of a data item definition.
  • COBCH0196 Redefinition of item containing an 'OCCURS DEPENDING ON' clause
    Your selected flagging dialect does not support this.
  • COBCH0197 Qualification refers to invalid REDEFINES item - qualification ignored
  • COBCH0199 LINE clause also specified in containing group
    The LINE clause cannot appear in an elementary item if the containing group already contains a LINE clause.
  • COBCH0200 Empty paragraph
    Your paragraph contains no statements.
Parent topic: Messages COBCH0101 to COBCH0200


COBCH0181 FROM subscript in VALUE clause must not be greater than TO subscript

The table element specified by the TO subscript precedes that specified by the FROM subscript.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0182 Limit exceeded - too many literals in VALUE clause

The VALUE clause is too complex for the compiler to process. Inform technical support.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0183 VALUE clause would result in initialisation of elements beyond end of table

Not all of the specified values are contained within the table being declared.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0184 In-line comment

Your program contains an in-line comment. In-line comments are permitted in the non-mainframe dialect, but your program was compiled using a different dialect.

Resolution:

Recode your program so that it does not use in-line comments, or recompile it using the non-mainframe dialect.

Parent topic: COBCH0181 - COBCH0200


COBCH0185 END-EXEC missing, or unexpected EXEC

An EXEC was encountered before an END-EXEC closed the previous EXEC. The most common reason for this is that an END-EXEC intended to close the previous EXEC was missing or misspelled.

Resolution:

Recode your program so that each EXEC has a closing END-EXEC before the next EXEC, then recompile.

Parent topic: COBCH0181 - COBCH0200


COBCH0186 EXEC too large or END-EXEC missing/misspelled

An EXEC statement is larger than the maximum allowed. This is most likely because an END-EXEC has been omitted or misspelled.

Resolution:

Recode your program so that each EXEC has a closing END-EXEC, then recompile.

Parent topic: COBCH0181 - COBCH0200


COBCH0187 Program is nested in a program defined with the "RECURSIVE" attribute

Mainframe compilers do not allow the RECURSIVE clause in a program that also has nested programs.

Resolution:

Recode your program so that it does not use this structure.

Parent topic: COBCH0181 - COBCH0200


COBCH0188 Key file %1_s not found

Parent topic: COBCH0181 - COBCH0200


COBCH0189 Directives file filename not found

Parent topic: COBCH0181 - COBCH0200


COBCH0190 Zero is an invalid value for an index-name. 1 assumed.

Parent topic: COBCH0181 - COBCH0200


COBCH0191 OCCURS DEPENDING ON phrase bisected by additional clause!

Parent topic: COBCH0181 - COBCH0200


COBCH0192 CALL parameter is group at level other than 01.

Your selected flagging dialect does not allow a CALL parameter to be a group at a level other than 01.

Resolution:

Recode your program so that the parameter is either an elementary item or a group at level 01.

Parent topic: COBCH0181 - COBCH0200


COBCH0193 Use of Z literals

Your selected flagging dialect does not support Z literals.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0194 CALL procedure pointer

Your selected flagging dialect does not support this.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0195 ASCENDING/DESCENDING KEY clause must appear before INDEXED BY clause

Your selected flagging dialect does not support reversing the order of these clauses in the OCCURS phrase of a data item definition.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0196 Redefinition of item containing an 'OCCURS DEPENDING ON' clause

Your selected flagging dialect does not support this.

Resolution:

Recode your program.

Parent topic: COBCH0181 - COBCH0200


COBCH0197 Qualification refers to invalid REDEFINES item - qualification ignored

Parent topic: COBCH0181 - COBCH0200


COBCH0199 LINE clause also specified in containing group

The LINE clause cannot appear in an elementary item if the containing group already contains a LINE clause.
Parent topic: COBCH0181 - COBCH0200


COBCH0200 Empty paragraph

Your paragraph contains no statements.
Parent topic: COBCH0181 - COBCH0200


Messages COBCH0201 to COBCH0300

  • COBCH0201 - COBCH0220
    Lists the Syntax Checking error messages from COBCH0201 through COBCH0220.
  • COBCH0221 - COBCH0240
    Lists the Syntax Checking error messages from COBCH0221 through COBCH0240.
  • COBCH0241 - COBCH0260
    Lists the Syntax Checking error messages from COBCH0241 through COBCH0260.
  • COBCH0261 - COBCH0280
    Lists the Syntax Checking error messages from COBCH0261 through COBCH0280.
  • COBCH0281 - COBCH0300
    Lists the Syntax Checking error messages from COBCH0281 through COBCH0300.
Parent topic: Syntax Checking Error Messages


COBCH0201 - COBCH0220

Lists the Syntax Checking error messages from COBCH0201 through COBCH0220.

  • COBCH0201 Sort file cannot have ACCESS or ORGANIZATION clauses
    An SD file control entry cannot have ACCESS or ORGANIZATION clauses, because the access mode and organization of such files are fixed.
  • COBCH0202 Too many levels of OCCURS
    You have specified more than the permitted number of OCCURS clauses in the definition of a table item.
  • COBCH0203 CODE must be specified for all reports or no report
    You have specified the CODE clause in the definition of a report. If you are defining more than one report for the specified file, you must specify the CODE clause either for all reports or for none of them for that file.
  • COBCH0204 REDEFINES on incorrect field
    A REDEFINES clause must have the same level number as the item it redefines.
  • COBCH0205 RECORD missing or has zero size
    You have declared a file using the SELECT statement in the Environment Division of your program, but have either failed to define it in a corresponding FD entry in the Data Division or have used a different filename in the FD entry, perhaps owing to a spelling mistake. If a mismatch of the two occurs then the record associated with the file does not exist although the necessary space has been created for it.
  • COBCH0206 01 or 77 level required
    The specified data item must have level number 01 or 77.
  • COBCH0207 FD, CD or SD qualification syntax error
    These source code entries describe the structure of a specified file and take the form FD or CD or SD followed by a filename and a description of the records in that file. The filename must be the name of a file defined in the FILE-CONTROL paragraph of your program.
  • COBCH0208 WORKING-STORAGE missing
    The words WORKING-STORAGE are missing from the relevant Section heading in the Data Division or, if present, have not been recognized by your COBOL system. This might be due to a spelling mistake or to their position in your code.
  • COBCH0209 PROCEDURE DIVISION missing or unknown statement
    The PROCEDURE DIVISION header is missing from your program or, if present, your COBOL system has failed to recognize it. This might be due to a spelling mistake or you could have placed the header at the wrong place in your code.
  • COBCH0210 Unrecognized data description qualifier or "." missing
    A qualifier (for example, JUST or COMP) is misspelled in the description of a data item.
  • COBCH0211 PICTURE clause not compatible with qualifiers
    Your code contains a PICTURE clause that is qualified by the wrong type of qualifier. For example, a data item cannot be defined as PIC XX USAGE COMP because it is an alphanumeric PICTURE clause but the qualifier is numeric.
  • COBCH0212 Illegal data item used with BLANK clause
    The BLANK WHEN ZERO clause can be used only as part of the data description entry for data items which are numeric (those which contain a 9 in the PICTURE clause) or numeric edited (ordinary edited data items with special characters added to allow the data items to be presented in a form which can be easily understood). You have used this clause with a nonnumeric data item in your source code or with a numeric data item that contains a "P", "S", or "V".
  • COBCH0213 Item is longer than USAGE allows or contains too many numeric positions
    A PICTURE string defined in a PICTURE clause in your Data Division exceeds the maximum permitted by your COBOL system.
  • COBCH0214 VALUE too long for data item or has too many decimal positions
    The value you have specified in a VALUE clause is too big or has too many decimal places, to fit in the data item. For example, a declaration such as PIC 99 VALUE 123, where 123 is too large to fit into the receiving field without truncation.
  • COBCH0215 VALUE in error or illegal for PICTURE type
    You might have made a mistake in the coding of a VALUE clause in your program. For example, you have used a numeric data item with a nonnumeric VALUE clause. Alternatively, you have used a VALUE clause in an illegal place, for example in conjunction with a data item which has been redefined.
  • COBCH0216 Non-elementary item has JUSTIFIED or BLANK clause
    These clauses can be used in the data description entry of the Data Division but must be used only with elementary data items. Elementary data items are the most basic subdivisions of a record as they are not subdivided into higher level data items. You have used one of these clauses in conjunction with a non-elementary data item (that is, one which contains higher level data items).
  • COBCH0217 Preceding item at this level has zero length
    You have defined a data item but have failed to give it a size, either by not using a PICTURE clause in conjunction with it, or, if it is a group item, by failing to define any elementary items to go with it. If you enter something similar to the following:
  • COBCH0218 Illegal arithmetic operator
    You have specified an invalid operator in an arithmetic expression.
  • COBCH0219 Illegal level number
    You have specified an illegal level number in a data description entry.
  • COBCH0220 Literal type does not match data type
    You have specified a literal value that is incompatible with the PICTURE clause of the associated data item.
Parent topic: Messages COBCH0201 to COBCH0300


COBCH0201 Sort file cannot have ACCESS or ORGANIZATION clauses

An SD file control entry cannot have ACCESS or ORGANIZATION clauses, because the access mode and organization of such files are fixed.

Resolution:

Delete the clauses in error.

Parent topic: COBCH0201 - COBCH0220


COBCH0202 Too many levels of OCCURS

You have specified more than the permitted number of OCCURS clauses in the definition of a table item.

Resolution:

Delete the excess OCCURS clauses.

Parent topic: COBCH0201 - COBCH0220


COBCH0203 CODE must be specified for all reports or no report

You have specified the CODE clause in the definition of a report. If you are defining more than one report for the specified file, you must specify the CODE clause either for all reports or for none of them for that file.

Resolution:

Add CODE clauses to the other reports you have defined, or ensure that no report definition contains a CODE clause for that file.

Parent topic: COBCH0201 - COBCH0220


COBCH0204 REDEFINES on incorrect field

A REDEFINES clause must have the same level number as the item it redefines.

Resolution:

Change the level number in error.

Parent topic: COBCH0201 - COBCH0220


COBCH0205 RECORD missing or has zero size

You have declared a file using the SELECT statement in the Environment Division of your program, but have either failed to define it in a corresponding FD entry in the Data Division or have used a different filename in the FD entry, perhaps owing to a spelling mistake. If a mismatch of the two occurs then the record associated with the file does not exist although the necessary space has been created for it.

Resolution:

Add or revise the FD entry.

Parent topic: COBCH0201 - COBCH0220


COBCH0206 01 or 77 level required

The specified data item must have level number 01 or 77.

Resolution:

Change the level number of the item to 01 or 77.

Parent topic: COBCH0201 - COBCH0220


COBCH0207 FD, CD or SD qualification syntax error

These source code entries describe the structure of a specified file and take the form FD or CD or SD followed by a filename and a description of the records in that file. The filename must be the name of a file defined in the FILE-CONTROL paragraph of your program.

Resolution:

Correct the format of this syntax.

Parent topic: COBCH0201 - COBCH0220


COBCH0208 WORKING-STORAGE missing

The words WORKING-STORAGE are missing from the relevant Section heading in the Data Division or, if present, have not been recognized by your COBOL system. This might be due to a spelling mistake or to their position in your code.

Resolution:

Correct the errors.

Parent topic: COBCH0201 - COBCH0220


COBCH0209 PROCEDURE DIVISION missing or unknown statement

The PROCEDURE DIVISION header is missing from your program or, if present, your COBOL system has failed to recognize it. This might be due to a spelling mistake or you could have placed the header at the wrong place in your code.

Alternatively, your code might contain a statement in the Procedure Division that your COBOL system has failed to recognize. This is probably because you have used a reserved word but have spelled it incorrectly.

Resolution:

Insert the header immediately after the last entry in the Data Division.

Correct your spelling error.

Parent topic: COBCH0201 - COBCH0220


COBCH0210 Unrecognized data description qualifier or "." missing

A qualifier (for example, JUST or COMP) is misspelled in the description of a data item.

Alternatively you have not placed the necessary period at the end of a PICTURE clause.

Resolution:

A list of possible qualifiers can be found in the chapter Concepts of the COBOL Language in your Language Reference. Check the spelling of the qualifier in your code.

Add the period.

Parent topic: COBCH0201 - COBCH0220


COBCH0211 PICTURE clause not compatible with qualifiers

Your code contains a PICTURE clause that is qualified by the wrong type of qualifier. For example, a data item cannot be defined as PIC XX USAGE COMP because it is an alphanumeric PICTURE clause but the qualifier is numeric.

Resolution:

Revise your code so that the PICTURE clause and its qualifiers are of the same type.

Parent topic: COBCH0201 - COBCH0220


COBCH0212 Illegal data item used with BLANK clause

The BLANK WHEN ZERO clause can be used only as part of the data description entry for data items which are numeric (those which contain a 9 in the PICTURE clause) or numeric edited (ordinary edited data items with special characters added to allow the data items to be presented in a form which can be easily understood). You have used this clause with a nonnumeric data item in your source code or with a numeric data item that contains a "P", "S", or "V".

Resolution:

Delete this clause or redefine the data item to be either numeric or numeric edited, or remove the "P", "S", or "V" characters.

Parent topic: COBCH0201 - COBCH0220


COBCH0213 Item is longer than USAGE allows or contains too many numeric positions

A PICTURE string defined in a PICTURE clause in your Data Division exceeds the maximum permitted by your COBOL system.

Refer to the limits, as documented in the Restrictions, Compiler Limits, and System Limits section, and then amend your code accordingly.

Parent topic: COBCH0201 - COBCH0220
Related reference
Restrictions, Compiler Limits, and System Limits


COBCH0214 VALUE too long for data item or has too many decimal positions

The value you have specified in a VALUE clause is too big or has too many decimal places, to fit in the data item. For example, a declaration such as PIC 99 VALUE 123, where 123 is too large to fit into the receiving field without truncation.

Resolution:

Alter your code so that the data item is large enough to receive the value that is to be placed in it.

Parent topic: COBCH0201 - COBCH0220


COBCH0215 VALUE in error or illegal for PICTURE type

You might have made a mistake in the coding of a VALUE clause in your program. For example, you have used a numeric data item with a nonnumeric VALUE clause. Alternatively, you have used a VALUE clause in an illegal place, for example in conjunction with a data item which has been redefined.

Resolution:

See the related topics for topics giving information on the rules governing the use of the VALUE clause.

Parent topic: COBCH0201 - COBCH0220
Related reference
The CALL Statement
Compilation Groups
Data Description Entry Skeleton
The ENTRY Statement
File Description Entry Skeleton
The PROCEDURE DIVISION Header
Screen Section Entry Skeleton
The VALUE Clause (Report Writer)
The VALUE Clause
The VALUE Clause in the Screen Section
The VALUE OF Clause


COBCH0216 Non-elementary item has JUSTIFIED or BLANK clause

These clauses can be used in the data description entry of the Data Division but must be used only with elementary data items. Elementary data items are the most basic subdivisions of a record as they are not subdivided into higher level data items. You have used one of these clauses in conjunction with a non-elementary data item (that is, one which contains higher level data items).

Resolution:

Revise your program to ensure that these clauses appear only with elementary data items.

Parent topic: COBCH0201 - COBCH0220


COBCH0217 Preceding item at this level has zero length

You have defined a data item but have failed to give it a size, either by not using a PICTURE clause in conjunction with it, or, if it is a group item, by failing to define any elementary items to go with it. If you enter something similar to the following:
 01 my-data-item. 01 prog-data-item pic x.

you receive this message after prog-data-item because, although it is my-data-item that is in error, the error is detected only when the next item at the same level as the data item in error is encountered.

Resolution

Add the necessary PICTURE clause or elementary items to the level hierarchy.

Parent topic: COBCH0201 - COBCH0220


COBCH0218 Illegal arithmetic operator

You have specified an invalid operator in an arithmetic expression.

Resolution:

Correct the expression.

Parent topic: COBCH0201 - COBCH0220


COBCH0219 Illegal level number

You have specified an illegal level number in a data description entry.

Resolution:

Correct the level number.

Parent topic: COBCH0201 - COBCH0220


COBCH0220 Literal type does not match data type

You have specified a literal value that is incompatible with the PICTURE clause of the associated data item.

Resolution:

Make the literal value compatible with the data item.

Parent topic: COBCH0201 - COBCH0220


COBCH0221 - COBCH0240

Lists the Syntax Checking error messages from COBCH0221 through COBCH0240.

  • COBCH0221 Data description qualifier inappropriate or repeated
    You have used a data description qualifier which is incompatible with the associated PICTURE clause. For example, you might have used a BLANK WHEN ZERO clause for a PIC XX data item. This is illegal as the data item is alphanumeric but the associated qualifier refers only to numeric items.
  • COBCH0222 REDEFINES data-name not declared
    You have not declared the data-name which you have used in conjunction with a REDEFINES clause.
  • COBCH0223 Unknown USAGE
    You have specified an invalid USAGE qualifier in a data description entry.
  • COBCH0224 SIGN must be LEADING or TRAILING
    This optional clause can be specified only for numeric description entries which contain the character S in their PICTURE clause. The key word SIGN must be followed by either LEADING or TRAILING depending on the position you want the operational sign to take.
  • COBCH0225 Level hierarchy wrong
    The structure of level numbers in a group data item is incorrect.
  • COBCH0226 Variable length group not unitary
    You cannot declare a variable-length group item in an OCCURS clause.
  • COBCH0227 ZERO missing
    The BLANK clause must be followed by the word ZERO, ZEROS or ZEROES.
  • COBCH0228 Group VALUE truncated
    The value you have specified for a group item exceeds its defined length.
  • COBCH0229 Incompatible qualifiers
    The qualifiers you have specified in the description of a data item are not compatible.
  • COBCH0230 PICTURE string has illegal precedence or illegal character
    You have used a character in a PICTURE clause that your COBOL system does not recognize, or which is illegal for that particular type of PICTURE string.
  • COBCH0231 INDEXED data-name missing or already declared
  • COBCH0232 Edited PICTURE string is too large
    A PICTURE string which you have defined for an edited or numeric edited (one which presents numeric data items in a more readable form, for example, with leading zeros removed or with currency signs inserted) data item exceeds the maximum permitted for your COBOL system.
  • COBCH0233 Unknown data description qualifier data-name
    You have either used a reserved word as a data-name, or used an invalid qualifier in a data description: this is probably a misspelling of a valid qualifier.
  • COBCH0234 DEPENDING missing
    You have defined a variable length table without specifying the DEPENDING phrase that, at run time, enables your COBOL system to determine the actual table size.
  • COBCH0235 Record size size1 < minimum size given in FD statement size2
  • COBCH0236 Record > maximum size given in FD statement
  • COBCH0237 Cannot have more than one initial CD
    Only one of the CD entries in the Communications Section can have the INITIAL clause specified.
  • COBCH0238 RENAMES missing
    You have omitted the word RENAMES in the definition of a level 66 data item.
  • COBCH0239 First data-name does not precede second
    You have included the syntax data-name-1 RENAMES data-name-2 THRU data-name-3 in your program, but the data item you have specified for data-name-2 is declared after the data item for data-name-3. This is not valid COBOL syntax, as data-name-2 in a THRU clause must be declared before data-name-3.
  • COBCH0240 Only allowed at 01 level
    You have used either the NEXT or TYPE clauses in a report description entry, or the GLOBAL or EXTERNAL clauses in a report file description entry, which is not an 01 level item.
Parent topic: Messages COBCH0201 to COBCH0300


COBCH0221 Data description qualifier inappropriate or repeated

You have used a data description qualifier which is incompatible with the associated PICTURE clause. For example, you might have used a BLANK WHEN ZERO clause for a PIC XX data item. This is illegal as the data item is alphanumeric but the associated qualifier refers only to numeric items.

Alternatively, you have used more than one PICTURE clause to define a single data item when each data item should have only one PICTURE clause associated with it.

Resolution:

Revise the qualifier or the data-type to ensure that they are compatible.

Delete any extra PICTURE clause to leave only one for that data item.

Parent topic: COBCH0221 - COBCH0240


COBCH0222 REDEFINES data-name not declared

You have not declared the data-name which you have used in conjunction with a REDEFINES clause.

Resolution:

Ensure that the data-name is declared in your Data Description entry and that the relevant REDEFINES clause is placed immediately after the data-name which it describes.

Parent topic: COBCH0221 - COBCH0240


COBCH0223 Unknown USAGE

You have specified an invalid USAGE qualifier in a data description entry.

Resolution:

Correct the USAGE qualifier.

Parent topic: COBCH0221 - COBCH0240


COBCH0224 SIGN must be LEADING or TRAILING

This optional clause can be specified only for numeric description entries which contain the character S in their PICTURE clause. The key word SIGN must be followed by either LEADING or TRAILING depending on the position you want the operational sign to take.

Resolution:

Add one of these words.

Parent topic: COBCH0221 - COBCH0240


COBCH0225 Level hierarchy wrong

The structure of level numbers in a group data item is incorrect.

Resolution:

Check the hierarchy of the level numbers and correct it.

Parent topic: COBCH0221 - COBCH0240


COBCH0226 Variable length group not unitary

You cannot declare a variable-length group item in an OCCURS clause.

Resolution:

Make the group item fixed length.

Parent topic: COBCH0221 - COBCH0240


COBCH0227 ZERO missing

The BLANK clause must be followed by the word ZERO, ZEROS or ZEROES.

Resolution:

Delete any other word that you might have used in place of ZERO and ensure that the clause contains no spelling errors.

Parent topic: COBCH0221 - COBCH0240


COBCH0228 Group VALUE truncated

The value you have specified for a group item exceeds its defined length.

Resolution:

Redefine the length of the group item or the value.

Parent topic: COBCH0221 - COBCH0240


COBCH0229 Incompatible qualifiers

The qualifiers you have specified in the description of a data item are not compatible.

Resolution:

Refer to the chapter Concepts of the COBOL Language in your Language Reference for the rules governing qualifiers in data descriptions. Revise the data description.

Parent topic: COBCH0221 - COBCH0240


COBCH0230 PICTURE string has illegal precedence or illegal character

You have used a character in a PICTURE clause that your COBOL system does not recognize, or which is illegal for that particular type of PICTURE string.

Resolution:

A full list of permitted characters can be found in the chapter Program Definition in your Language Reference. Alter the relevant PICTURE clause.

Parent topic: COBCH0221 - COBCH0240


COBCH0231 INDEXED data-name missing or already declared

Parent topic: COBCH0221 - COBCH0240


COBCH0232 Edited PICTURE string is too large

A PICTURE string which you have defined for an edited or numeric edited (one which presents numeric data items in a more readable form, for example, with leading zeros removed or with currency signs inserted) data item exceeds the maximum permitted for your COBOL system.

A string comprises 32 slots, each containing 16 characters. If no two consecutive characters in the string are the same, a new slot is allocated to each character. For example:

X(32)B(480)

works, but:

XBXBXBXBXBXBXBXBXBXBXBXBXBXBXBXBX

fails.

Resolution:

Alter the format of the string so that it contains no more than 32 groups of characters, each group holding up to 16 identical, contiguous edit characters.

Parent topic: COBCH0221 - COBCH0240


COBCH0233 Unknown data description qualifier data-name

You have either used a reserved word as a data-name, or used an invalid qualifier in a data description: this is probably a misspelling of a valid qualifier.

Resolution:

Correct the data description.

Parent topic: COBCH0221 - COBCH0240


COBCH0234 DEPENDING missing

You have defined a variable length table without specifying the DEPENDING phrase that, at run time, enables your COBOL system to determine the actual table size.

Resolution:

Specify the DEPENDING phrase.

Parent topic: COBCH0221 - COBCH0240


COBCH0235 Record size size1 < minimum size given in FD statement size2

Parent topic: COBCH0221 - COBCH0240


COBCH0236 Record > maximum size given in FD statement

Parent topic: COBCH0221 - COBCH0240


COBCH0237 Cannot have more than one initial CD

Only one of the CD entries in the Communications Section can have the INITIAL clause specified.

Resolution:

Delete the INITIAL clauses from all but one of the CD entries.

Parent topic: COBCH0221 - COBCH0240


COBCH0238 RENAMES missing

You have omitted the word RENAMES in the definition of a level 66 data item.

Resolution:

Add the word RENAMES.

Parent topic: COBCH0221 - COBCH0240


COBCH0239 First data-name does not precede second

You have included the syntax data-name-1 RENAMES data-name-2 THRU data-name-3 in your program, but the data item you have specified for data-name-2 is declared after the data item for data-name-3. This is not valid COBOL syntax, as data-name-2 in a THRU clause must be declared before data-name-3.

Resolution:

Check that you have specified the THRU phrase correctly.

Parent topic: COBCH0221 - COBCH0240


COBCH0240 Only allowed at 01 level

You have used either the NEXT or TYPE clauses in a report description entry, or the GLOBAL or EXTERNAL clauses in a report file description entry, which is not an 01 level item.

Resolution:

Edit your source code to ensure that where you have used NEXT, TYPE, GLOBAL or EXTERNAL the clause applies to an 01 level item.

Parent topic: COBCH0221 - COBCH0240


COBCH0241 - COBCH0260

Lists the Syntax Checking error messages from COBCH0241 through COBCH0260.

  • COBCH0241 Only allowed in Working-Storage Section
    The syntax indicated is allowed only in the Working-Storage Section.
  • COBCH0242 Only allowed in WORKING-STORAGE and FILE sections
    The syntax indicated is allowed only in the Working-Storage Section or the File Section.
  • COBCH0243 VALUE of group item must be nonnumeric or figurative constant
    If you specify a VALUE clause for a group item, the value in the clause must be either a nonnumeric literal or a figurative constant.
  • COBCH0244 FD missing for file filename
    You have not made an FD entry for all the files named in the FILE-CONTROL paragraph.
  • COBCH0245 DEPENDING ON item data-name missing or illegal
    You have not declared a data item named in the DEPENDING phrase of an OCCURS clause.
  • COBCH0246 KEY key-name missing or illegal
    You have not specified the RECORD KEY clause in the file description of an indexed sequential file.
  • COBCH0247 Index-name has been declared explicitly
    You have declared an index data item explicitly. The item is declared implicitly by its appearance in an INDEX phrase, so you have in effect declared the same item twice.
  • COBCH0248 ISAM key key-name too long
    A data item that is to be used as an indexed sequential file key is longer than the maximum length allowed for such keys.
  • COBCH0249 Alternate keys have same reference
    The two alternate keys you have defined for an indexed sequential file overlap. Alternate keys must be completely distinct from one another.
  • COBCH0250 STATUS field data-name missing or illegal
    You have either not declared the data item specified in the FILE STATUS clause of a file control entry, or you have declared it incorrectly.
  • COBCH0251 CURSOR field data-name missing or illegal
    You have either not declared the data item specified in the CURSOR IS clause in the SPECIAL-NAMES paragraph, or you have declared the item incorrectly.
  • COBCH0252 PASSWORD field data-name missing or illegal
    You have either not declared the data item specified in the PASSWORD clause in a file description entry, or you have declared the item incorrectly.
  • COBCH0253 LABEL RECORD or DATA RECORD record-name missing or illegal
    You have either not declared the record item specified in the LABEL RECORD or DATA RECORD clauses in a file description entry, or you have declared the item incorrectly.
  • COBCH0254 'VALUE OF' field data-name missing or illegal
    You have either not declared one or more of the data items named in the VALUE OF clause of an FD entry in the File Section, or you have declared such an item incorrectly.
  • COBCH0255 User name data-name same as special register
    You have declared a data item with the same name as one of the special registers, which are data items that are automatically declared by your COBOL system.
  • COBCH0256 Preceding record has zero length
    You have defined a file record with zero length. This is probably due to errors in all of the elementary item descriptions in the record definition.
  • COBCH0257 KEY data-name missing or already declared
    You have either not declared a data item specified in the KEY phrase of an OCCURS clause, or you have declared it twice.
  • COBCH0258 ASSIGN data-name data-name illegal
    You have specified an ASSIGN data-name in a SELECT ... ASSIGN clause that is not unitary, that is, the data definition contains an OCCURS clause.
  • COBCH0259 Illegal report-name or bad RD clause
    You have defined a report-name that is either not unique or which does not conform to the rules for user-defined words. Alternatively, you have specified a clause in an RD entry incorrectly.
  • COBCH0260 Inconsistent page specification
    The values you have specified in the PAGE LIMIT clause are not consistent; for example, the integer in the LAST DETAIL phrase is smaller than the integer in the FIRST DETAIL phrase.
Parent topic: Messages COBCH0201 to COBCH0300


COBCH0241 Only allowed in Working-Storage Section

The syntax indicated is allowed only in the Working-Storage Section.

Resolution:

Edit your source code to ensure that the syntax appears only in the Working-Storage Section.

Parent topic: COBCH0241 - COBCH0260


COBCH0242 Only allowed in WORKING-STORAGE and FILE sections

The syntax indicated is allowed only in the Working-Storage Section or the File Section.

Resolution:

Edit your source code to ensure that the syntax appears only in the Working-Storage or File Sections.

Parent topic: COBCH0241 - COBCH0260


COBCH0243 VALUE of group item must be nonnumeric or figurative constant

If you specify a VALUE clause for a group item, the value in the clause must be either a nonnumeric literal or a figurative constant.

Resolution:

Revise the value in the VALUE clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0244 FD missing for file filename

You have not made an FD entry for all the files named in the FILE-CONTROL paragraph.

Resolution:

Ensure that you have an FD entry for each file named in a SELECT clause in the FILE-CONTROL paragraph.

Parent topic: COBCH0241 - COBCH0260


COBCH0245 DEPENDING ON item data-name missing or illegal

You have not declared a data item named in the DEPENDING phrase of an OCCURS clause.

Resolution:

Add a declaration of the missing data item.

Parent topic: COBCH0241 - COBCH0260


COBCH0246 KEY key-name missing or illegal

You have not specified the RECORD KEY clause in the file description of an indexed sequential file.

Resolution:

Add the RECORD KEY clause to the file description.

Parent topic: COBCH0241 - COBCH0260


COBCH0247 Index-name has been declared explicitly

You have declared an index data item explicitly. The item is declared implicitly by its appearance in an INDEX phrase, so you have in effect declared the same item twice.

Resolution:

Delete the explicit declaration of the index data item.

Parent topic: COBCH0241 - COBCH0260


COBCH0248 ISAM key key-name too long

A data item that is to be used as an indexed sequential file key is longer than the maximum length allowed for such keys.

Resolution:

Redefine the key accordingly.

Parent topic: COBCH0241 - COBCH0260


COBCH0249 Alternate keys have same reference

The two alternate keys you have defined for an indexed sequential file overlap. Alternate keys must be completely distinct from one another.

Resolution:

Redefine the alternate keys so that they do not overlap, or define them as split keys (which are allowed to overlap).

Parent topic: COBCH0241 - COBCH0260


COBCH0250 STATUS field data-name missing or illegal

You have either not declared the data item specified in the FILE STATUS clause of a file control entry, or you have declared it incorrectly.

Resolution:

Add or revise the definition of the FILE STATUS data item.

Parent topic: COBCH0241 - COBCH0260


COBCH0251 CURSOR field data-name missing or illegal

You have either not declared the data item specified in the CURSOR IS clause in the SPECIAL-NAMES paragraph, or you have declared the item incorrectly.

Resolution:

Refer to the chapter Program Definition in your Language Reference for the correct form of the cursor data item. Add or revise the declaration of the data item in the CURSOR IS clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0252 PASSWORD field data-name missing or illegal

You have either not declared the data item specified in the PASSWORD clause in a file description entry, or you have declared the item incorrectly.

Resolution:

Add or correct the declaration of the data item in the PASSWORD clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0253 LABEL RECORD or DATA RECORD record-name missing or illegal

You have either not declared the record item specified in the LABEL RECORD or DATA RECORD clauses in a file description entry, or you have declared the item incorrectly.

Resolution:

Add or correct the declaration of the record item in the LABEL RECORD or DATA RECORD clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0254 'VALUE OF' field data-name missing or illegal

You have either not declared one or more of the data items named in the VALUE OF clause of an FD entry in the File Section, or you have declared such an item incorrectly.

Resolution:

Add or correct the declaration of the data item(s) in the VALUE OF clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0255 User name data-name same as special register

You have declared a data item with the same name as one of the special registers, which are data items that are automatically declared by your COBOL system.

Resolution:

Alter the name of the data item in error.

Parent topic: COBCH0241 - COBCH0260


COBCH0256 Preceding record has zero length

You have defined a file record with zero length. This is probably due to errors in all of the elementary item descriptions in the record definition.

Resolution:

Correct the record description.

Parent topic: COBCH0241 - COBCH0260


COBCH0257 KEY data-name missing or already declared

You have either not declared a data item specified in the KEY phrase of an OCCURS clause, or you have declared it twice.

Resolution:

Declare the data item or remove the extra declaration.

Parent topic: COBCH0241 - COBCH0260


COBCH0258 ASSIGN data-name data-name illegal

You have specified an ASSIGN data-name in a SELECT ... ASSIGN clause that is not unitary, that is, the data definition contains an OCCURS clause.

Resolution:

Edit your source code to ensure that the ASSIGN data item does not include an OCCURS clause.

Parent topic: COBCH0241 - COBCH0260


COBCH0259 Illegal report-name or bad RD clause

You have defined a report-name that is either not unique or which does not conform to the rules for user-defined words. Alternatively, you have specified a clause in an RD entry incorrectly.

Resolution:

Correct your program accordingly.

Parent topic: COBCH0241 - COBCH0260


COBCH0260 Inconsistent page specification

The values you have specified in the PAGE LIMIT clause are not consistent; for example, the integer in the LAST DETAIL phrase is smaller than the integer in the FIRST DETAIL phrase.

Resolution:

Refer to the chapter Report Writer in your Language Reference - Additional Topics for the rules governing the PAGE LIMIT clause. Correct your program accordingly.

Parent topic: COBCH0241 - COBCH0260


COBCH0261 - COBCH0280

Lists the Syntax Checking error messages from COBCH0261 through COBCH0280.

  • COBCH0261 Only allowed in Report Section
    You have tried to specify syntax for a report outside the Report Section of the Data Division.
  • COBCH0262 Not a CONTROL for this report
    The data-name in a TYPE CH or TYPE CF clause must appear in the CONTROL clause of the associated RD entry. You might have misspelled the data-name.
  • COBCH0263 Not allowed when PAGE not specified in RD
    You have either specified a TYPE PH or TYPE PF clause without specifying a PAGE clause in the associated RD entry, or you have specified an absolute line number in the LINE NUMBER clause without specifying a PAGE clause in the associated RD entry.
  • COBCH0264 Only one report group with this TYPE allowed per RD
    You have specified a duplicate of one of the TYPE clauses (for example, you have specified two TYPE PF clauses); only one clause of each type is allowed in a particular RD entry.
  • COBCH0265 Not allowed with this TYPE
    You are using a qualifier in a statement that either does not allow any qualifiers, or that does not allow this particular qualifier.
  • COBCH0266 No TYPE specified
    All level 01 entries in the Report Section must have a TYPE clause.
  • COBCH0267 LINE specification missing or inconsistent
    This message has three possible causes:
  • COBCH0268 REPORT specified in more than one FD
    You have specified the same report-name in more than one FD.
  • COBCH0269 Duplicate CONTROL field
    You have specified the same CONTROL field value in more than one RD entry.
  • COBCH0270 COLUMN specification overlapping or not left to right
  • COBCH0271 Only allowed with DETAIL groups
    You can specify a GROUP INDICATE clause only with DETAIL report groups.
  • COBCH0272 Only allowed with CONTROL FOOTING groups
    You can specify a SUM clause only in a control footing report group.
  • COBCH0273 Non-elementary item has invalid qualifier, or PICTURE missing
    You have specified in a group item a qualifier that can be used only in an elementary item. Possibly you intended the item to be elementary but omitted the PICTURE clause.
  • COBCH0274 GROUP INDICATE without COLUMN
    You have specified the GROUP INDICATE clause but no COLUMN clause in the same report group description.
  • COBCH0275 NEXT GROUP not allowed with this group TYPE
    You have specified NEXT GROUP in a group with TYPE RF or PH.
  • COBCH0276 NEXT GROUP NEXT PAGE not allowed with this group TYPE
    You have specified NEXT GROUP or NEXT PAGE in a group with TYPE PF.
  • COBCH0277 LINE NEXT PAGE not allowed with this group TYPE
    You can specify the LINE NEXT PAGE clause only with a group of TYPE CH, CF, or DE.
  • COBCH0278 RESET item is lower CONTROL level than group
    The control group on which a sum is reset must be at either the same level as or a lower level than the sum.
  • COBCH0279 Report line too long
    The syntax you have specified is trying to create a report line which is longer than the maximum allowed.
  • COBCH0280 THRU phrase not allowed with DBCS field
    DBCS is Double Byte Character Set.
Parent topic: Messages COBCH0201 to COBCH0300


COBCH0261 Only allowed in Report Section

You have tried to specify syntax for a report outside the Report Section of the Data Division.

Resolution:

Refer to the chapter Report Writer in your Language Reference - Additional Topics to see what syntax is allowed in the Report Section. Delete the syntax in error or relocate it in the Report Section.

Parent topic: COBCH0261 - COBCH0280


COBCH0262 Not a CONTROL for this report

The data-name in a TYPE CH or TYPE CF clause must appear in the CONTROL clause of the associated RD entry. You might have misspelled the data-name.

Resolution:

Ensure that the correct data-name appears in both the TYPE CF/CH and CONTROL clauses.

Parent topic: COBCH0261 - COBCH0280


COBCH0263 Not allowed when PAGE not specified in RD

You have either specified a TYPE PH or TYPE PF clause without specifying a PAGE clause in the associated RD entry, or you have specified an absolute line number in the LINE NUMBER clause without specifying a PAGE clause in the associated RD entry.

Resolution:

Add a PAGE clause to the RD entry.

Parent topic: COBCH0261 - COBCH0280


COBCH0264 Only one report group with this TYPE allowed per RD

You have specified a duplicate of one of the TYPE clauses (for example, you have specified two TYPE PF clauses); only one clause of each type is allowed in a particular RD entry.

Resolution:

Delete the duplicate TYPE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0265 Not allowed with this TYPE

You are using a qualifier in a statement that either does not allow any qualifiers, or that does not allow this particular qualifier.

Resolution:

Refer to the chapter Concepts of the COBOL Language in your Language Reference for details of the qualifiers allowed with this statement. Revise your program.

Parent topic: COBCH0261 - COBCH0280


COBCH0266 No TYPE specified

All level 01 entries in the Report Section must have a TYPE clause.

Resolution:

Add a TYPE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0267 LINE specification missing or inconsistent

This message has three possible causes:

You have specified a NEXT PAGE clause in a LINE clause other than the first of a report group description entry.

The absolute line numbers in the LINE clauses of a report group description entry are not in ascending order.

You have not specified a LINE clause in a particular report group description entry.

Resolution:

Depending on the cause of this message, you should:

Delete the NEXT PAGE clause from any but the first LINE clause.

Rearrange the LINE clauses so that absolute line numbers are in ascending order.

Add a LINE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0268 REPORT specified in more than one FD

You have specified the same report-name in more than one FD.

Resolution:

Delete the duplicate report-name.

Parent topic: COBCH0261 - COBCH0280


COBCH0269 Duplicate CONTROL field

You have specified the same CONTROL field value in more than one RD entry.

Resolution:

Delete the duplicate CONTROL field value.

Parent topic: COBCH0261 - COBCH0280


COBCH0270 COLUMN specification overlapping or not left to right

Parent topic: COBCH0261 - COBCH0280


COBCH0271 Only allowed with DETAIL groups

You can specify a GROUP INDICATE clause only with DETAIL report groups.

Resolution:

Delete the GROUP INDICATE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0272 Only allowed with CONTROL FOOTING groups

You can specify a SUM clause only in a control footing report group.

Resolution:

Delete the SUM clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0273 Non-elementary item has invalid qualifier, or PICTURE missing

You have specified in a group item a qualifier that can be used only in an elementary item. Possibly you intended the item to be elementary but omitted the PICTURE clause.

Resolution:

Refer to the chapter Program Definition in your Language Reference for details of the correct syntax. Delete the clause in error, or insert the PICTURE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0274 GROUP INDICATE without COLUMN

You have specified the GROUP INDICATE clause but no COLUMN clause in the same report group description.

Resolution:

Include the COLUMN qualifier.

Parent topic: COBCH0261 - COBCH0280


COBCH0275 NEXT GROUP not allowed with this group TYPE

You have specified NEXT GROUP in a group with TYPE RF or PH.

Resolution:

Delete the NEXT GROUP clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0276 NEXT GROUP NEXT PAGE not allowed with this group TYPE

You have specified NEXT GROUP or NEXT PAGE in a group with TYPE PF.

Resolution:

Delete the clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0277 LINE NEXT PAGE not allowed with this group TYPE

You can specify the LINE NEXT PAGE clause only with a group of TYPE CH, CF, or DE.

Resolution:

Delete the LINE NEXT PAGE clause.

Parent topic: COBCH0261 - COBCH0280


COBCH0278 RESET item is lower CONTROL level than group

The control group on which a sum is reset must be at either the same level as or a lower level than the sum.

Resolution:

Refer to the chapter Report Writer in the Language Reference - Additional Topics for the rules governing the resetting of sums. Revise your code accordingly.

Parent topic: COBCH0261 - COBCH0280


COBCH0279 Report line too long

The syntax you have specified is trying to create a report line which is longer than the maximum allowed.

Resolution:

Ensure that any report lines are not longer than the permitted length.

Parent topic: COBCH0261 - COBCH0280


COBCH0280 THRU phrase not allowed with DBCS field

DBCS is Double Byte Character Set.

Resolution:

Refer to the chapter Micro Focus Extensions for Double-Byte Character Set Support in your Language Reference - Additional Topics for the rules governing the use of DBCS. Revise your code accordingly.

Parent topic: COBCH0261 - COBCH0280


COBCH0281 - COBCH0300

Lists the Syntax Checking error messages from COBCH0281 through COBCH0300.

  • COBCH0281 Illegal use of DBCS field
    DBCS is Double Byte Character Set.
  • COBCH0282 Number of BLL cells incorrect
  • COBCH0283 An EXTERNAL file cannot be subject of SAME RECORD AREA clause
    You have specified a file in a SAME RECORD AREA clause in your program that is specified as EXTERNAL in an FD entry.
  • COBCH0284 Not allowed in Report Section
    The syntax you have specified is not allowed in the Report Section.
  • COBCH0285 First LINE NUMBER clause in PAGE FOOTING group is relative
  • COBCH0286 Not specified in CONTROL clause of RD
  • COBCH0287 Data record specified for Report file
  • COBCH0288 SYNC with USAGE IS INDEX
  • COBCH0289 SYNC at group level
  • COBCH0290 Index key key-name not alphanumeric
    You have specified a key item that is not alphanumeric, in an index key clause where an alphanumeric key item is expected.
  • COBCH0291 Group FILLER
  • COBCH0292 SIGN different from that at group level
  • COBCH0293 SYNC on non-01 level group
  • COBCH0295 VALUE clause in File or Linkage Section. Clause processed as comment
    You have specified a VALUE clause in either the File Section or the Linkage Section where you should not have specified one.
  • COBCH0296 BLANK WHEN ZERO with zero suppression
  • COBCH0297 OCCURS .. DEPENDING clause without "integer TO". "1 TO" assumed
  • COBCH0298 OCCURS at level 01 or 77
  • COBCH0299 FILLER omitted
    You have omitted the word FILLER.
  • COBCH0300 LABEL RECORDS clause omitted
    You have omitted the heading LABEL RECORDS.
Parent topic: Messages COBCH0201 to COBCH0300


COBCH0281 Illegal use of DBCS field

DBCS is Double Byte Character Set.

Resolution:

Refer to the chapter Report Writer in your Language Reference - Additional Topics for the rules governing the use of DBCS. Revise your code accordingly.

Parent topic: COBCH0281 - COBCH0300


COBCH0282 Number of BLL cells incorrect

Parent topic: COBCH0281 - COBCH0300


COBCH0283 An EXTERNAL file cannot be subject of SAME RECORD AREA clause

You have specified a file in a SAME RECORD AREA clause in your program that is specified as EXTERNAL in an FD entry.

Resolution:

Delete the EXTERNAL file in error from the SAME RECORD AREA clause in your program.

Parent topic: COBCH0281 - COBCH0300


COBCH0284 Not allowed in Report Section

The syntax you have specified is not allowed in the Report Section.

Resolution:

Delete the syntax from the Report Section.

Parent topic: COBCH0281 - COBCH0300


COBCH0285 First LINE NUMBER clause in PAGE FOOTING group is relative

Parent topic: COBCH0281 - COBCH0300


COBCH0286 Not specified in CONTROL clause of RD

Parent topic: COBCH0281 - COBCH0300


COBCH0287 Data record specified for Report file

Parent topic: COBCH0281 - COBCH0300


COBCH0288 SYNC with USAGE IS INDEX

Parent topic: COBCH0281 - COBCH0300


COBCH0289 SYNC at group level

Parent topic: COBCH0281 - COBCH0300


COBCH0290 Index key key-name not alphanumeric

You have specified a key item that is not alphanumeric, in an index key clause where an alphanumeric key item is expected.

Resolution:

Specify an alphanumeric key item.

Parent topic: COBCH0281 - COBCH0300


COBCH0291 Group FILLER

Parent topic: COBCH0281 - COBCH0300


COBCH0292 SIGN different from that at group level

Parent topic: COBCH0281 - COBCH0300


COBCH0293 SYNC on non-01 level group

Parent topic: COBCH0281 - COBCH0300


COBCH0295 VALUE clause in File or Linkage Section. Clause processed as comment

You have specified a VALUE clause in either the File Section or the Linkage Section where you should not have specified one.

Resolution:

You can delete the VALUE clause, although this has no effect on your program.

Parent topic: COBCH0281 - COBCH0300


COBCH0296 BLANK WHEN ZERO with zero suppression

Parent topic: COBCH0281 - COBCH0300


COBCH0297 OCCURS .. DEPENDING clause without "integer TO". "1 TO" assumed

Parent topic: COBCH0281 - COBCH0300


COBCH0298 OCCURS at level 01 or 77

Parent topic: COBCH0281 - COBCH0300


COBCH0299 FILLER omitted

You have omitted the word FILLER.

Resolution:

Add the word FILLER.

Parent topic: COBCH0281 - COBCH0300


COBCH0300 LABEL RECORDS clause omitted

You have omitted the heading LABEL RECORDS.

Resolution:

Add the LABEL RECORDS clause.

Parent topic: COBCH0281 - COBCH0300


Messages COBCH0301 to COBCH0400

  • COBCH0301 - COBCH0320
    Lists the Syntax Checking error messages from COBCH0301 through COBCH0320.
  • COBCH0321 - COBCH0340
    Lists the Syntax Checking error messages from COBCH0321 through COBCH0340.
  • COBCH0341 - COBCH0360
    Lists the Syntax Checking error messages from COBCH0341 through COBCH0360.
  • COBCH0361 - COBCH0380
    Lists the Syntax Checking error messages from COBCH0361 through COBCH0380.
  • COBCH0381 - COBCH0400
    Lists the Syntax Checking error messages from COBCH0381 through COBCH0400.
Parent topic: Syntax Checking Error Messages


COBCH0301 - COBCH0320

Lists the Syntax Checking error messages from COBCH0301 through COBCH0320.

  • COBCH0301 Unrecognized verb
    You have either used a verb in the Procedure Division of your program that your COBOL system does not recognize as a valid COBOL verb, or have misspelled a COBOL verb.
  • COBCH0302 IF....ELSE or scope-delimiter mismatch
    An error exists in your coding of an IF statement in the Procedure Division of your program. The two halves of one IF statement do not match.
  • COBCH0303 Operand has wrong data-type
    You have used a data item with the wrong data-type in one of your statements. For example, you have used a filename instead of a record-name in a WRITE statement.
  • COBCH0304 Procedure name name not unique
    Two or more sections in the Procedure Division, or two or more paragraphs in a section, of your program have the same title.
  • COBCH0305 Procedure name name same as data-name
    A paragraph in the Procedure Division of your program has the same name as a data item declared in the Data Division.
  • COBCH0306 Entry name not unique
    You have used the same entry point-name more than once in your program. (This might be because the entry point name is the same as the Program-ID.)
  • COBCH0307 Wrong combination of data-types
    You are trying to manipulate data items which are not compatible.
  • COBCH0308 Conditional statement not allowed in this context
    You have used a conditional statement (one which specifies that the truth value of a condition is to be determined at run time) in the Procedure Division where an imperative statement is expected.
  • COBCH0309 Malformed subscript
    You have probably specified two subscripts for a one-dimensional table item.
  • COBCH0310 ACCEPT/DISPLAY syntax incorrect
    You have either used invalid syntax with an ACCEPT or DISPLAY statement, or have incorrectly coded that part of your code containing the communications syntax. The most likely cause of this message is a spelling mistake in your code.
  • COBCH0311 Illegal syntax used with I-O verb
    Code following an I/O verb (for example READ or WRITE) violates the rules of COBOL syntax.
  • COBCH0312 Invalid arithmetic statement
    An arithmetic statement which you have used in the Procedure Division does not conform to the rules of COBOL syntax. These statements must begin with an arithmetic verb (for example SUBTRACT or DIVIDE), followed by the relevant numeric literals or identifiers which the verb will act upon when the program is executed. The statement which you have specified is not a valid one.
  • COBCH0313 Invalid arithmetic expression
    An arithmetic expression which you have used in the Procedure Division is not a valid one.
  • COBCH0314 Illegal key
    The key value in a file operation or in a SEARCH statement is the wrong size.
  • COBCH0315 Invalid conditional expression
    A conditional expression which you have specified in the Procedure Division of your program does not conform to the rules of COBOL syntax. These expressions, an example of which is the statement immediately following an IF, enable one of two following statements to be executed at run time depending on the truth value.
  • COBCH0316 Too many AFTERs in PERFORM statement
    A PERFORM statement can be followed only by seven AFTER phrases. Your code exceeds this limit.
  • COBCH0317 Incorrect structure of Procedure Division
    You have made a mistake in the coding of the Procedure Division. For example, you might have forgotten one of the Section headers.
  • COBCH0318 File must have ACCESS SEQUENTIAL
    The file named in this statement must have sequential access mode. A file's access mode is derived from its SELECT statement; it is either implied by the file's organization or specified by its ACCESS MODE clause.
  • COBCH0319 Only index-names allowed with this format
    An index-name is required at this point in the operation you are trying.
  • COBCH0320 Too many operands in one statement
    A statement in the Procedure Division of your program contains too many operands or individual operands that are too long.
Parent topic: Messages COBCH0301 to COBCH0400


COBCH0301 Unrecognized verb

You have either used a verb in the Procedure Division of your program that your COBOL system does not recognize as a valid COBOL verb, or have misspelled a COBOL verb.

Resolution:

Chech which verbs are permitted in the COBOL language, and ensure that you have spelled them correctly.

You might need to set a language-enabling directive if the verb you require is not part of your system's standard COBOL language.

Parent topic: COBCH0301 - COBCH0320


COBCH0302 IF....ELSE or scope-delimiter mismatch

An error exists in your coding of an IF statement in the Procedure Division of your program. The two halves of one IF statement do not match.

Alternatively, you have made an error in coding a construct that uses one of the scope delimiters (for example, END-ADD). There is a mismatch between the number of scope delimiters and the statements whose scope they delimit.

Resolution:

Ensure you do not have more ELSE phrases than IF phrases.

Revise your source code.

Parent topic: COBCH0301 - COBCH0320


COBCH0303 Operand has wrong data-type

You have used a data item with the wrong data-type in one of your statements. For example, you have used a filename instead of a record-name in a WRITE statement.

Resolution:

Revise the relevant item.

Parent topic: COBCH0301 - COBCH0320


COBCH0304 Procedure name name not unique

Two or more sections in the Procedure Division, or two or more paragraphs in a section, of your program have the same title.

Resolution:

Rename or qualify the sections or paragraphs in error to ensure uniqueness of reference.

Parent topic: COBCH0301 - COBCH0320


COBCH0305 Procedure name name same as data-name

A paragraph in the Procedure Division of your program has the same name as a data item declared in the Data Division.

Resolution:

Change the name of either the paragraph or the relevant data item to ensure uniqueness of reference.

Parent topic: COBCH0301 - COBCH0320


COBCH0306 Entry name not unique

You have used the same entry point-name more than once in your program. (This might be because the entry point name is the same as the Program-ID.)

Resolution:

Alter the entry-name in error or qualify it.

Parent topic: COBCH0301 - COBCH0320


COBCH0307 Wrong combination of data-types

You are trying to manipulate data items which are not compatible.

Resolution:

Ensure that the data items are of the same type.

Parent topic: COBCH0301 - COBCH0320


COBCH0308 Conditional statement not allowed in this context

You have used a conditional statement (one which specifies that the truth value of a condition is to be determined at run time) in the Procedure Division where an imperative statement is expected.

Resolution:

Replace the statement with one that begins with an imperative verb and is followed by a specification of an unconditional action to be taken at run time.

Parent topic: COBCH0301 - COBCH0320


COBCH0309 Malformed subscript

You have probably specified two subscripts for a one-dimensional table item.

Resolution:

Revise your code to ensure that you do not specify more than one subscript for a one-dimensional table item.

Parent topic: COBCH0301 - COBCH0320


COBCH0310 ACCEPT/DISPLAY syntax incorrect

You have either used invalid syntax with an ACCEPT or DISPLAY statement, or have incorrectly coded that part of your code containing the communications syntax. The most likely cause of this message is a spelling mistake in your code.

Resolution:

Correct the spelling mistake.

Parent topic: COBCH0301 - COBCH0320


COBCH0311 Illegal syntax used with I-O verb

Code following an I/O verb (for example READ or WRITE) violates the rules of COBOL syntax.

Resolution:

Revise your code accordingly.

Parent topic: COBCH0301 - COBCH0320


COBCH0312 Invalid arithmetic statement

An arithmetic statement which you have used in the Procedure Division does not conform to the rules of COBOL syntax. These statements must begin with an arithmetic verb (for example SUBTRACT or DIVIDE), followed by the relevant numeric literals or identifiers which the verb will act upon when the program is executed. The statement which you have specified is not a valid one.

Resolution:

Ensure that the arithmetic statement you want to use conforms to the relevant rules.

Parent topic: COBCH0301 - COBCH0320


COBCH0313 Invalid arithmetic expression

An arithmetic expression which you have used in the Procedure Division is not a valid one.

Resolution:

See the related topics for details of the COBOL syntax for complicated arithmetic tasks.

Parent topic: COBCH0301 - COBCH0320
Related reference
Compilation Groups
Arithmetic Expressions


COBCH0314 Illegal key

The key value in a file operation or in a SEARCH statement is the wrong size.

Resolution:

Check the key definition and correct the key value.

Parent topic: COBCH0301 - COBCH0320


COBCH0315 Invalid conditional expression

A conditional expression which you have specified in the Procedure Division of your program does not conform to the rules of COBOL syntax. These expressions, an example of which is the statement immediately following an IF, enable one of two following statements to be executed at run time depending on the truth value.

Resolution:

Refer to the chapter Program Definition in your Language Reference for details on the coding of the particular statement which you have used. Revise your code accordingly.

Parent topic: COBCH0301 - COBCH0320


COBCH0316 Too many AFTERs in PERFORM statement

A PERFORM statement can be followed only by seven AFTER phrases. Your code exceeds this limit.

Resolution:

Rewrite your code ensuring that no PERFORM statement has more than seven associated AFTER phrases.

Parent topic: COBCH0301 - COBCH0320


COBCH0317 Incorrect structure of Procedure Division

You have made a mistake in the coding of the Procedure Division. For example, you might have forgotten one of the Section headers.

Resolution:

Ensure that the Procedure Division follows a logical order and that each section in it has its own header.

Parent topic: COBCH0301 - COBCH0320


COBCH0318 File must have ACCESS SEQUENTIAL

The file named in this statement must have sequential access mode. A file's access mode is derived from its SELECT statement; it is either implied by the file's organization or specified by its ACCESS MODE clause.

Resolution:

Change the access mode of the file to sequential.

Parent topic: COBCH0301 - COBCH0320


COBCH0319 Only index-names allowed with this format

An index-name is required at this point in the operation you are trying.

Resolution:

Edit your source code to ensure that the name you have specified is an index-name.

Parent topic: COBCH0301 - COBCH0320


COBCH0320 Too many operands in one statement

A statement in the Procedure Division of your program contains too many operands or individual operands that are too long.

Resolution:

Reduce the number of operands, or shorten those operands that are too long.

Parent topic: COBCH0301 - COBCH0320


COBCH0321 - COBCH0340

Lists the Syntax Checking error messages from COBCH0321 through COBCH0340.

  • COBCH0321 Repeated INDEXED BY phrase
    You have used more than one INDEXED BY phrase on a table. This is not conformant with your selected flagging dialect.
  • COBCH0322 Cannot reference DEBUG-ITEM outside declaratives
    You have referred to your COBOL system-generated data item DEBUG-ITEM in a procedure that is not in the Declaratives Section of your program's Procedure Division. References to DEBUG-ITEM are permitted only in the Declaratives Section.
  • COBCH0323 More than one USE procedure on same file
    You have associated two or more USE procedures with the same file when you can associate only one.
  • COBCH0324 More than one USE procedure for same open mode
    You have associated two or more USE procedures with the same file open mode when you can associate only one.
  • COBCH0325 Illegal combination of debugging procedures
    You have specified an invalid combination of USE FOR DEBUGGING procedures in the Declaratives.
  • COBCH0326 Literal cannot be receiving field
    You have specified a literal value as the receiving field in an operation involving an implicit or explicit move. A receiving field must be a data item.
  • COBCH0327 Index item not permitted
    You have named an index data item as the sending or receiving field in a MOVE statement. This is not permitted.
  • COBCH0328 Not allowed with OPTIONAL file
  • COBCH0329 WHEN phrase missing from SEARCH statement
    You have specified a SEARCH statement with no WHEN phrase. You must specify at least one WHEN phrase in a SEARCH statement.
  • COBCH0330 Not a record name
    You must specify the name of a file record in this context (as defined in an FD entry in the File Section). You have probably misspelled a valid record-name.
  • COBCH0331 Program is nested - must compile with NESTCALL directive
  • COBCH0332 AFTER phrase not allowed with in-line perform
    You cannot specify an AFTER phrase in an inline PERFORM statement.
  • COBCH0333 Not an alterable paragraph
    The paragraph you have named in an ALTER statement is not a paragraph on which an ALTER statement can operate. Such a paragraph must consist of a single sentence containing only a single GO TO statement (without a DEPENDING phrase).
  • COBCH0334 Cannot follow WHEN OTHER
    The WHEN OTHER phrase, if specified, must be the last phrase in an EVALUATE statement.
  • COBCH0335 Selection object does not match selection subject
    A type mismatch has occurred between one of the selection subjects in an EVALUATE statement and the corresponding selection object.
  • COBCH0336 Variable length group not allowed
    You cannot INITIALIZE a variable-length item.
  • COBCH0337 Cannot repeat same category
    You have repeated the same data class in the REPLACING phrase of an INITIALIZE statement.
  • COBCH0338 REPORT not specified in an FD
    You have referred to a report for which no FD entry exists in the Report Section. You might have forgotten to specify the report entry, or you might have misspelled a correct report-name.
  • COBCH0339 Not allowed with SEQUENTIAL files
    You have specified an operation that cannot be performed on a file opened in sequential access mode.
  • COBCH0340 Not allowed with RANDOM ACCESS files
    You have specified an operation that cannot be performed on a file opened in random access mode.
Parent topic: Messages COBCH0301 to COBCH0400


COBCH0321 Repeated INDEXED BY phrase

You have used more than one INDEXED BY phrase on a table. This is not conformant with your selected flagging dialect.
Parent topic: COBCH0321 - COBCH0340


COBCH0322 Cannot reference DEBUG-ITEM outside declaratives

You have referred to your COBOL system-generated data item DEBUG-ITEM in a procedure that is not in the Declaratives Section of your program's Procedure Division. References to DEBUG-ITEM are permitted only in the Declaratives Section.

Resolution:

Delete the reference to DEBUG-ITEM, or move it to the Declaratives Section.

Parent topic: COBCH0321 - COBCH0340


COBCH0323 More than one USE procedure on same file

You have associated two or more USE procedures with the same file when you can associate only one.

Resolution:

Delete the additional USE references.

Parent topic: COBCH0321 - COBCH0340


COBCH0324 More than one USE procedure for same open mode

You have associated two or more USE procedures with the same file open mode when you can associate only one.

Resolution:

Delete the additional USE references.

Parent topic: COBCH0321 - COBCH0340


COBCH0325 Illegal combination of debugging procedures

You have specified an invalid combination of USE FOR DEBUGGING procedures in the Declaratives.

Resolution:

Refer to the chapter Debug Module in your Language Reference - Additional Topics for details of debugging procedures. Correct the declaratives.

Parent topic: COBCH0321 - COBCH0340


COBCH0326 Literal cannot be receiving field

You have specified a literal value as the receiving field in an operation involving an implicit or explicit move. A receiving field must be a data item.

Resolution:

Change the literal value to a reference to a data item.

Parent topic: COBCH0321 - COBCH0340


COBCH0327 Index item not permitted

You have named an index data item as the sending or receiving field in a MOVE statement. This is not permitted.

Resolution:

Move the value into a nonindex data item and use this data item in the MOVE statement.

Parent topic: COBCH0321 - COBCH0340


COBCH0328 Not allowed with OPTIONAL file

Parent topic: COBCH0321 - COBCH0340


COBCH0329 WHEN phrase missing from SEARCH statement

You have specified a SEARCH statement with no WHEN phrase. You must specify at least one WHEN phrase in a SEARCH statement.

Resolution:

Add a WHEN phrase to the SEARCH statement.

Parent topic: COBCH0321 - COBCH0340


COBCH0330 Not a record name

You must specify the name of a file record in this context (as defined in an FD entry in the File Section). You have probably misspelled a valid record-name.

Resolution:

Correct the reference so that it is a reference to a file record.

Parent topic: COBCH0321 - COBCH0340


COBCH0331 Program is nested - must compile with NESTCALL directive

Resolution:

Parent topic: COBCH0321 - COBCH0340


COBCH0332 AFTER phrase not allowed with in-line perform

You cannot specify an AFTER phrase in an inline PERFORM statement.

Resolution:

Delete the AFTER phrase.

Parent topic: COBCH0321 - COBCH0340


COBCH0333 Not an alterable paragraph

The paragraph you have named in an ALTER statement is not a paragraph on which an ALTER statement can operate. Such a paragraph must consist of a single sentence containing only a single GO TO statement (without a DEPENDING phrase).

Resolution:

Change the reference in the ALTER statement to refer to a paragraph that can be operated on by ALTER, or edit the named paragraph so that it can be operated on by ALTER

Parent topic: COBCH0321 - COBCH0340


COBCH0334 Cannot follow WHEN OTHER

The WHEN OTHER phrase, if specified, must be the last phrase in an EVALUATE statement.

Resolution:

Ensure any WHEN phrases precede the WHEN OTHER phrase.

Parent topic: COBCH0321 - COBCH0340


COBCH0335 Selection object does not match selection subject

A type mismatch has occurred between one of the selection subjects in an EVALUATE statement and the corresponding selection object.

Resolution:

Correct the EVALUATE statement.

Parent topic: COBCH0321 - COBCH0340


COBCH0336 Variable length group not allowed

You cannot INITIALIZE a variable-length item.

Resolution:

Delete the item-name from the INITIALIZE statement.

Parent topic: COBCH0321 - COBCH0340


COBCH0337 Cannot repeat same category

You have repeated the same data class in the REPLACING phrase of an INITIALIZE statement.

Resolution:

Delete the repeated class from the INITIALIZE statement.

Parent topic: COBCH0321 - COBCH0340


COBCH0338 REPORT not specified in an FD

You have referred to a report for which no FD entry exists in the Report Section. You might have forgotten to specify the report entry, or you might have misspelled a correct report-name.

Resolution:

Correct the report-name or add the necessary report definition to the Report Section.

Parent topic: COBCH0321 - COBCH0340


COBCH0339 Not allowed with SEQUENTIAL files

You have specified an operation that cannot be performed on a file opened in sequential access mode.
Parent topic: COBCH0321 - COBCH0340


COBCH0340 Not allowed with RANDOM ACCESS files

You have specified an operation that cannot be performed on a file opened in random access mode.
Parent topic: COBCH0321 - COBCH0340


COBCH0341 - COBCH0360

Lists the Syntax Checking error messages from COBCH0341 through COBCH0360.

  • COBCH0341 Not allowed with LINE SEQUENTIAL files
    You have specified an operation that cannot be performed on a line sequential file.
  • COBCH0342 Not allowed with LINAGE files
    You have performed an illegal operation on a file defined with a LINAGE clause (for example, WRITE AFTER CO1).
  • COBCH0343 Can only be used in inline PERFORM
  • COBCH0344 Should be level 01 or 77
    You have specified a data item that is not a level 01 or level 77 data item where your COBOL system is expecting the data item to be either one of these levels.
  • COBCH0345 USING parameter used twice in parameter list
    You have specified the same data item-name twice in the USING phrase of the Procedure Division header. All the names in the USING phrase must be different.
  • COBCH0346 Only one WHEN phrase allowed with SEARCH ALL
    You have specified two WHEN phrases in a SEARCH statement using the ALL option. You can specify only one WHEN phrase in this context.
  • COBCH0347 MERGE needs at least two USING files
    You have specified fewer than two filenames in the USING phrase of a MERGE statement.
  • COBCH0348 Procedure name procedure-name undeclared, first used on line line-number
    You have referred to a nonexistent paragraph or section. You have probably misspelled a valid procedure-name.
  • COBCH0349 "LOCK" clause expected
    You have not specified the LOCK phrase with a READ statement.
  • COBCH0350 Illegal use of "NO LOCK"
    You have used a READ statement with the NO LOCK phrase on a file for which no record locking is required.
  • COBCH0351 "LOCK" clause specified for "EXCLUSIVE" file
    You have specified a LOCK clause in a READ statement for a file that you have already locked with an EXCLUSIVE lock (in the FILE-CONTROL paragraph of your code).
  • COBCH0352 "KEPT" specified for file with single record locking
    This message applies only to multi-user syntax. You have specified a WITH KEPT LOCK phrase in a READ statement which accesses a file that does not support multiple record locking.
  • COBCH0353 Cannot reference a Report Section item that is not a sum-counter
  • COBCH0354 Multiple receiving fields in MOVE CORRESPONDING
  • COBCH0355 Only "=" and "NOT =" allowed for pointer data items
    You can use the operators = and NOT = only in comparisons involving pointer data items.
  • COBCH0356 Not allowed with REPORT files
    You have tried to perform a file operation (READ, WRITE, REWRITE) on a file whose FD entry indicates that it is a report.
  • COBCH0357 Screen is display-only
    You have named a screen in an ACCEPT statement that contains only display fields.
  • COBCH0358 Missing comma
    COBOL syntax expects a comma at this point.
  • COBCH0359 Mismatch of table dimensions
    A data item in an ACCEPT/DISPLAY statement has a different number of dimensions from the corresponding Screen Section item.
  • COBCH0360 File must have ACCESS DYNAMIC
    You have specified an operation on a file that can be performed only if the file has access mode DYNAMIC.
Parent topic: Messages COBCH0301 to COBCH0400


COBCH0341 Not allowed with LINE SEQUENTIAL files

You have specified an operation that cannot be performed on a line sequential file.
Parent topic: COBCH0341 - COBCH0360


COBCH0342 Not allowed with LINAGE files

You have performed an illegal operation on a file defined with a LINAGE clause (for example, WRITE AFTER CO1).

Resolution:

Delete the illegal operation or redefine the file without a LINAGE clause.

Parent topic: COBCH0341 - COBCH0360


COBCH0343 Can only be used in inline PERFORM

Parent topic: COBCH0341 - COBCH0360


COBCH0344 Should be level 01 or 77

You have specified a data item that is not a level 01 or level 77 data item where your COBOL system is expecting the data item to be either one of these levels.

Resolution:

Redefine the data item to be level 01 or level 77.

Parent topic: COBCH0341 - COBCH0360


COBCH0345 USING parameter used twice in parameter list

You have specified the same data item-name twice in the USING phrase of the Procedure Division header. All the names in the USING phrase must be different.

Resolution:

Delete the extra reference.

Parent topic: COBCH0341 - COBCH0360


COBCH0346 Only one WHEN phrase allowed with SEARCH ALL

You have specified two WHEN phrases in a SEARCH statement using the ALL option. You can specify only one WHEN phrase in this context.

Resolution:

Delete the extra WHEN phrase.

Parent topic: COBCH0341 - COBCH0360


COBCH0347 MERGE needs at least two USING files

You have specified fewer than two filenames in the USING phrase of a MERGE statement.

Resolution:

Ensure that you specify at least two filenames in the USING phrase of the MERGE statement.

Parent topic: COBCH0341 - COBCH0360


COBCH0348 Procedure name procedure-name undeclared, first used on line line-number

You have referred to a nonexistent paragraph or section. You have probably misspelled a valid procedure-name.

Resolution:

Ensure that the procedure you have referred to exists and that you have spelled it correctly.

Parent topic: COBCH0341 - COBCH0360


COBCH0349 "LOCK" clause expected

You have not specified the LOCK phrase with a READ statement.

Resolution:

Insert a LOCK phrase in the READ statement.

Parent topic: COBCH0341 - COBCH0360


COBCH0350 Illegal use of "NO LOCK"

You have used a READ statement with the NO LOCK phrase on a file for which no record locking is required.

Resolution:

Delete the NO LOCK phrase.

Parent topic: COBCH0341 - COBCH0360


COBCH0351 "LOCK" clause specified for "EXCLUSIVE" file

You have specified a LOCK clause in a READ statement for a file that you have already locked with an EXCLUSIVE lock (in the FILE-CONTROL paragraph of your code).

Resolution:

Record locking is impossible on a file which your run unit has already locked with an EXCLUSIVE lock. To ensure that the two LOCK entries are compatible, you should either delete the LOCK entry in the relevant READ statement, or alter the LOCK MODE IS entry in the FILE-CONTROL paragraph.

Parent topic: COBCH0341 - COBCH0360


COBCH0352 "KEPT" specified for file with single record locking

This message applies only to multi-user syntax. You have specified a WITH KEPT LOCK phrase in a READ statement which accesses a file that does not support multiple record locking.

Resolution:

Either change the filetype or delete the WITH KEPT LOCK phrase to ensure compatibility between the two entries.

Parent topic: COBCH0341 - COBCH0360


COBCH0353 Cannot reference a Report Section item that is not a sum-counter

Parent topic: COBCH0341 - COBCH0360


COBCH0354 Multiple receiving fields in MOVE CORRESPONDING

Parent topic: COBCH0341 - COBCH0360


COBCH0355 Only "=" and "NOT =" allowed for pointer data items

You can use the operators = and NOT = only in comparisons involving pointer data items.

Resolution:

Correct the comparison.

Parent topic: COBCH0341 - COBCH0360


COBCH0356 Not allowed with REPORT files

You have tried to perform a file operation (READ, WRITE, REWRITE) on a file whose FD entry indicates that it is a report.

Resolution:

Delete the input-output statement.

Parent topic: COBCH0341 - COBCH0360


COBCH0357 Screen is display-only

You have named a screen in an ACCEPT statement that contains only display fields.

Resolution:

Make sure that you have named the correct screen.

Parent topic: COBCH0341 - COBCH0360


COBCH0358 Missing comma

COBOL syntax expects a comma at this point.

Resolution:

Add the missing comma.

Parent topic: COBCH0341 - COBCH0360


COBCH0359 Mismatch of table dimensions

A data item in an ACCEPT/DISPLAY statement has a different number of dimensions from the corresponding Screen Section item.

Alternatively, the Screen Section item has a different number of dimensions from the corresponding data item appearing in the USING or TO clause.

Resolution:

Make the two item definitions consistent.

Parent topic: COBCH0341 - COBCH0360


COBCH0360 File must have ACCESS DYNAMIC

You have specified an operation on a file that can be performed only if the file has access mode DYNAMIC.

Resolution:

Change the file control entry for the file so that it has access mode DYNAMIC.

Parent topic: COBCH0341 - COBCH0360


COBCH0361 - COBCH0380

Lists the Syntax Checking error messages from COBCH0361 through COBCH0380.

  • COBCH0361 Operation exceeds COMP subset
    Your program contains a statement that cannot be compiled to COMP subset instructions.
  • COBCH0362 data-name not declared for file or wrong type for CODE-SET
    The data-names you have specified in the CODE-SET clause do not belong to a record in the file.
  • COBCH0363 data-name not in same record as first item in CODE-SET clause
    You have specified data-names in the CODE-SET clause that belong to more than one record. All data-names specified in this clause must belong to a single record in the file.
  • COBCH0364 data-name overlaps another item in CODE-SET clause
    One or more of the data-names specified in the CODE-SET clause is redefined, or you might have specified the whole record, rather than individual data-names contained in that record, in the CODE-SET clause.
  • COBCH0365 Variable size table not last in group or subsidiary to OCCURS
    OCCURS DEPENDING ON item must be last item in a group.
  • COBCH0366 Variable length delimiter not allowed
    You cannot use a reference modified item or a group containing an OCCURS ... DEPENDING ON clause in this context.
  • COBCH0367 Description of operand does not contain the INDEXED BY clause
    A SEARCH is not possible as the description of the operand does not contain the INDEXED BY clause.
  • COBCH0368 Exception phrase inappropriate
    The specified exception is not appropriate with this statement in the specified access mode. For example an AT END has been specified with random access, or INVALID KEY with sequential access.
  • COBCH0369 OPEN EXTEND on file with LINAGE clause
    OPEN EXTEND is not allowed on a file defined with a LINAGE clause.
  • COBCH0370 Operand must be a table
    The operand used in this situation can only be a table.
  • COBCH0371 Data size is too large
    Your program's data size exceeds the maximum size permitted.
  • COBCH0372 Illegal use of SORT file
    You have specified a SORT file incorrectly.
  • COBCH0373 PICTURE string contains more than 18 numeric positions
    Your PICTURE string can contain a maximum of 18 numeric positions.
  • COBCH0374 Illegal use of floating-point item
    You have specified a floating-point item incorrectly.
  • COBCH0375 Literal includes repeated characters
  • COBCH0376 Table superordinate to operand is not indexed
  • COBCH0377 SORT table does not support complex OCCURS DEPENDING ON tables
  • COBCH0378 More than seven AFTER phrases
    You can include a maximum of seven AFTER phrases in a PERFORM statement.
  • COBCH0379 Non-DISPLAY numeric data cannot be compared with alphanumeric data
  • COBCH0380 Parameter count in CALL different from that in PROCEDURE DIVISION header
Parent topic: Messages COBCH0301 to COBCH0400


COBCH0361 Operation exceeds COMP subset

Your program contains a statement that cannot be compiled to COMP subset instructions.
Parent topic: COBCH0361 - COBCH0380


COBCH0362 data-name not declared for file or wrong type for CODE-SET

The data-names you have specified in the CODE-SET clause do not belong to a record in the file.

Resolution:

Edit your source code so that the data-names in the CODE-SET clause refer to a record in the file.

Parent topic: COBCH0361 - COBCH0380


COBCH0363 data-name not in same record as first item in CODE-SET clause

You have specified data-names in the CODE-SET clause that belong to more than one record. All data-names specified in this clause must belong to a single record in the file.

Resolution:

Edit your source code to delete one or more of the CODE-SET data-names to ensure that all data-names belong to only one record.

Parent topic: COBCH0361 - COBCH0380


COBCH0364 data-name overlaps another item in CODE-SET clause

One or more of the data-names specified in the CODE-SET clause is redefined, or you might have specified the whole record, rather than individual data-names contained in that record, in the CODE-SET clause.

Resolution:

Edit your source code so that the data-names in the record are specified only once.

Parent topic: COBCH0361 - COBCH0380


COBCH0365 Variable size table not last in group or subsidiary to OCCURS

OCCURS DEPENDING ON item must be last item in a group.

Resolution:

Restructure your data items so that the OCCURS DEPENDING ON item is the last item in the group.

Parent topic: COBCH0361 - COBCH0380


COBCH0366 Variable length delimiter not allowed

You cannot use a reference modified item or a group containing an OCCURS ... DEPENDING ON clause in this context.

Resolution:

Replace the reference modified item, or specify a valid item in the OCCURS DEPENDING ON clause.

Parent topic: COBCH0361 - COBCH0380


COBCH0367 Description of operand does not contain the INDEXED BY clause

A SEARCH is not possible as the description of the operand does not contain the INDEXED BY clause.

Resolution:

Include an INDEXED BY clause in your operand description.

Parent topic: COBCH0361 - COBCH0380


COBCH0368 Exception phrase inappropriate

The specified exception is not appropriate with this statement in the specified access mode. For example an AT END has been specified with random access, or INVALID KEY with sequential access.
Parent topic: COBCH0361 - COBCH0380


COBCH0369 OPEN EXTEND on file with LINAGE clause

OPEN EXTEND is not allowed on a file defined with a LINAGE clause.
Parent topic: COBCH0361 - COBCH0380


COBCH0370 Operand must be a table

The operand used in this situation can only be a table.

Resolution:

Revise your code so that the operand is a table.

Parent topic: COBCH0361 - COBCH0380


COBCH0371 Data size is too large

Your program's data size exceeds the maximum size permitted.

Resolution:

Redesign your program to include less data.

Parent topic: COBCH0361 - COBCH0380


COBCH0372 Illegal use of SORT file

You have specified a SORT file incorrectly.

Resolution:

Correct the syntax.

Parent topic: COBCH0361 - COBCH0380


COBCH0373 PICTURE string contains more than 18 numeric positions

Your PICTURE string can contain a maximum of 18 numeric positions.

Resolution:

Change your PICTURE string so that it contains no more than 18 numeric positions.

Parent topic: COBCH0361 - COBCH0380


COBCH0374 Illegal use of floating-point item

You have specified a floating-point item incorrectly.

Resolution:

Do not use a floating-point item in this context.

Parent topic: COBCH0361 - COBCH0380


COBCH0375 Literal includes repeated characters

Parent topic: COBCH0361 - COBCH0380


COBCH0376 Table superordinate to operand is not indexed

Parent topic: COBCH0361 - COBCH0380


COBCH0377 SORT table does not support complex OCCURS DEPENDING ON tables

Parent topic: COBCH0361 - COBCH0380


COBCH0378 More than seven AFTER phrases

You can include a maximum of seven AFTER phrases in a PERFORM statement.

Resolution:

Delete any extra AFTER phrases.

Parent topic: COBCH0361 - COBCH0380


COBCH0379 Non-DISPLAY numeric data cannot be compared with alphanumeric data

Parent topic: COBCH0361 - COBCH0380


COBCH0380 Parameter count in CALL different from that in PROCEDURE DIVISION header

Parent topic: COBCH0361 - COBCH0380


COBCH0381 - COBCH0400

Lists the Syntax Checking error messages from COBCH0381 through COBCH0400.

  • COBCH0381 TALLYING option has ALL etc. distributed over multiple identifiers
  • COBCH0382 Only one Procedure-name in GO TO ... DEPENDING
  • COBCH0383 Missing ALSO
    You have omitted the word ALSO.
  • COBCH0384 NEXT SENTENCE does not follow ON, IF, ELSE or SEARCH WHEN
    NEXT SENTENCE should be used only in either branch of an IF statement or the WHEN branch of a SEARCH statement.
  • COBCH0385 Order of initialization changed
  • COBCH0386 No section or paragraph at start of Procedure Division
  • COBCH0387 AFTER and BEFORE options used together
  • COBCH0388 Key is right hand side of condition
  • COBCH0389 EXIT not in separate paragraph
  • COBCH0390 OPEN EXTEND on non-sequential file
  • COBCH0391 MF format Accept/Display
  • COBCH0392 More than two AFTER phrases
    You have included more than the maximum of two AFTER phrases in your program.
  • COBCH0393 Inline PERFORM
  • COBCH0394 No section header after END DECLARATIVES
  • COBCH0395 FROM literal
  • COBCH0396 No suitable conditional phrase and no applicable declarative
  • COBCH0397 No preceding section
  • COBCH0398 Offset only allowed with Index-names
  • COBCH0399 Index-name belongs to different table
  • COBCH0400 Cannot use index data item as subscript
    You have used an index data item as a subscript in your program.
Parent topic: Messages COBCH0301 to COBCH0400


COBCH0381 TALLYING option has ALL etc. distributed over multiple identifiers

Parent topic: COBCH0381 - COBCH0400


COBCH0382 Only one Procedure-name in GO TO ... DEPENDING

Parent topic: COBCH0381 - COBCH0400


COBCH0383 Missing ALSO

You have omitted the word ALSO.

Resolution:

Add the word ALSO.

Parent topic: COBCH0381 - COBCH0400


COBCH0384 NEXT SENTENCE does not follow ON, IF, ELSE or SEARCH WHEN

NEXT SENTENCE should be used only in either branch of an IF statement or the WHEN branch of a SEARCH statement.

Resolution:

Revise your code to ensure that you have obeyed these rules.

Parent topic: COBCH0381 - COBCH0400


COBCH0385 Order of initialization changed

Parent topic: COBCH0381 - COBCH0400


COBCH0386 No section or paragraph at start of Procedure Division

Parent topic: COBCH0381 - COBCH0400


COBCH0387 AFTER and BEFORE options used together

Parent topic: COBCH0381 - COBCH0400


COBCH0388 Key is right hand side of condition

Parent topic: COBCH0381 - COBCH0400


COBCH0389 EXIT not in separate paragraph

Parent topic: COBCH0381 - COBCH0400


COBCH0390 OPEN EXTEND on non-sequential file

Parent topic: COBCH0381 - COBCH0400


COBCH0391 MF format Accept/Display

Parent topic: COBCH0381 - COBCH0400


COBCH0392 More than two AFTER phrases

You have included more than the maximum of two AFTER phrases in your program.

Resolution:

Delete any extra AFTER phrases.

Parent topic: COBCH0381 - COBCH0400


COBCH0393 Inline PERFORM

Parent topic: COBCH0381 - COBCH0400


COBCH0394 No section header after END DECLARATIVES

Parent topic: COBCH0381 - COBCH0400


COBCH0395 FROM literal

Parent topic: COBCH0381 - COBCH0400


COBCH0396 No suitable conditional phrase and no applicable declarative

Parent topic: COBCH0381 - COBCH0400


COBCH0397 No preceding section

Parent topic: COBCH0381 - COBCH0400


COBCH0398 Offset only allowed with Index-names

Parent topic: COBCH0381 - COBCH0400


COBCH0399 Index-name belongs to different table

Parent topic: COBCH0381 - COBCH0400


COBCH0400 Cannot use index data item as subscript

You have used an index data item as a subscript in your program.
Parent topic: COBCH0381 - COBCH0400


Messages COBCH0401 to COBCH0500

  • COBCH0401 - COBCH0420
    Lists the Syntax Checking error messages from COBCH0401 through COBCH0420.
  • COBCH0421 - COBCH0440
    Lists the Syntax Checking error messages from COBCH0421 through COBCH0440.
  • COBCH0441 - COBCH0460
    Lists the Syntax Checking error messages from COBCH0441 through COBCH0460.
  • COBCH0461 - COBCH0480
    Lists the Syntax Checking error messages from COBCH0461 through COBCH0480.
  • COBCH0481 - COBCH0500
    Lists the Syntax Checking error messages from COBCH0481 through COBCH0500.
Parent topic: Syntax Checking Error Messages


COBCH0401 - COBCH0420

Lists the Syntax Checking error messages from COBCH0401 through COBCH0420.

  • COBCH0401 Limit exceeded - number of source statements > limit
  • COBCH0402 Limit exceeded - number of files > limit
  • COBCH0404 Limit exceeded - number of pairs of REPLACING operands > limit
  • COBCH0406 Limit exceeded - length of file/copy/library name > limit
  • COBCH0408 Limit exceeded - number of sections/paragraphs/labels > 64k
    The combined number of sections, paragraphs and labels in the Procedure Division is greater than 65535 (64K).
  • COBCH0409 Limit exceeded - number of SELECT filenames > limit
  • COBCH0410 Limit exceeded - number of SAME RECORD AREA clauses > limit
  • COBCH0411 Limit exceeded - number of MULTIPLE FILE filenames > limit
  • COBCH0412 Limit exceeded - number of ALTERNATE RECORD KEY clauses in a file > limit
  • COBCH0413 Limit exceeded - length of RECORD KEY > limit characters
  • COBCH0414 Limit exceeded - length of Data Division > limit
  • COBCH0415 Limit exceeded - length of Data Section > limit
  • COBCH0419 Limit exceeded - BLOCK size > limit characters
  • COBCH0420 Limit exceeded - RECORD length > limit characters
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0401 Limit exceeded - number of source statements > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0402 Limit exceeded - number of files > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0404 Limit exceeded - number of pairs of REPLACING operands > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0406 Limit exceeded - length of file/copy/library name > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0408 Limit exceeded - number of sections/paragraphs/labels > 64k

The combined number of sections, paragraphs and labels in the Procedure Division is greater than 65535 (64K).

You need to restructure your code to comply with this limit.

Parent topic: COBCH0401 - COBCH0420
Related concepts
Size of Programs, Divisions and Sections


COBCH0409 Limit exceeded - number of SELECT filenames > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0410 Limit exceeded - number of SAME RECORD AREA clauses > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0411 Limit exceeded - number of MULTIPLE FILE filenames > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0412 Limit exceeded - number of ALTERNATE RECORD KEY clauses in a file > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0413 Limit exceeded - length of RECORD KEY > limit characters

Parent topic: COBCH0401 - COBCH0420


COBCH0414 Limit exceeded - length of Data Division > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0415 Limit exceeded - length of Data Section > limit

Parent topic: COBCH0401 - COBCH0420


COBCH0419 Limit exceeded - BLOCK size > limit characters

Parent topic: COBCH0401 - COBCH0420


COBCH0420 Limit exceeded - RECORD length > limit characters

Parent topic: COBCH0401 - COBCH0420


COBCH0421 - COBCH0440

Lists the Syntax Checking error messages from COBCH0421 through COBCH0440.

  • COBCH0421 Limit exceeded - number of FD filenames > limit
  • COBCH0422 Limit exceeded - number of SD filenames > limit
  • COBCH0424 Limit exceeded - number of 01 &77 items in Linkage Section > limit
  • COBCH0425 Limit exceeded - length of File Section group item > limit characters
  • COBCH0426 Limit exceeded - length of group item > limit characters
  • COBCH0427 Limit exceeded - length of data item > limit characters
  • COBCH0428 Limit exceeded - length of edited item > limit characters
  • COBCH0429 Limit exceeded - length of variable length table > limit characters
  • COBCH0430 Total length of VALUE literals > integer - possible problem on mainframe
  • COBCH0431 Limit exceeded - length of PICTURE string > limit characters
  • COBCH0432 Limit exceeded - length of PICTURE replication > limit
  • COBCH0433 Limit exceeded - length of sort record > limit characters
  • COBCH0434 Limit exceeded - length of table > limit characters
  • COBCH0435 Limit exceeded - length of table element > limit characters
  • COBCH0436 Limit exceeded - number of ASC/DESC KEY clauses > limit
  • COBCH0437 Limit exceeded at limit - length of ASC/DESC KEYs > limit characters
  • COBCH0438 Limit exceeded - number of INDEXED BY clauses > limit
  • COBCH0440 Limit exceeded - number of paragraph labels > limit
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0421 Limit exceeded - number of FD filenames > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0422 Limit exceeded - number of SD filenames > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0424 Limit exceeded - number of 01 &77 items in Linkage Section > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0425 Limit exceeded - length of File Section group item > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0426 Limit exceeded - length of group item > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0427 Limit exceeded - length of data item > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0428 Limit exceeded - length of edited item > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0429 Limit exceeded - length of variable length table > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0430 Total length of VALUE literals > integer - possible problem on mainframe

Parent topic: COBCH0421 - COBCH0440


COBCH0431 Limit exceeded - length of PICTURE string > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0432 Limit exceeded - length of PICTURE replication > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0433 Limit exceeded - length of sort record > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0434 Limit exceeded - length of table > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0435 Limit exceeded - length of table element > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0436 Limit exceeded - number of ASC/DESC KEY clauses > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0437 Limit exceeded at limit - length of ASC/DESC KEYs > limit characters

Parent topic: COBCH0421 - COBCH0440


COBCH0438 Limit exceeded - number of INDEXED BY clauses > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0440 Limit exceeded - number of paragraph labels > limit

Parent topic: COBCH0421 - COBCH0440


COBCH0441 - COBCH0460

Lists the Syntax Checking error messages from COBCH0441 through COBCH0460.

  • COBCH0441 Limit exceeded - number of PERFORMs > limit
  • COBCH0442 Limit exceeded - OCCURS nesting > limit
  • COBCH0443 Limit exceeded - number of GO TO DEPENDING ON names > limit
  • COBCH0444 Limit exceeded - number of IF nesting levels > limit
  • COBCH0445 Limit exceeded - number of CALL parameters > limit
  • COBCH0446 Limit exceeded - number of SORT/MERGE input files > limit
  • COBCH0447 Limit exceeded - number of SORT/MERGE keys > limit
  • COBCH0448 Limit exceeded - number of conditions in a SEARCH ALL > limit
  • COBCH0449 Limit exceeded - number of UNSTRING delimiters > limit
  • COBCH0450 Limit exceeded - number of operands in INSPECT TALLYING/REPLACING > limit
  • COBCH0451 Limit exceeded - length of SORT/MERGE keys > limit characters
  • COBCH0452 Limit exceeded - number of PROCEDURE DIVISION USING parameters > limit
  • COBCH0453 Limit exceeded - number of ENTRY USING parameters > limit
  • COBCH0460 Previous item crosses 64K boundary. Segment checking code produced
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0441 Limit exceeded - number of PERFORMs > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0442 Limit exceeded - OCCURS nesting > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0443 Limit exceeded - number of GO TO DEPENDING ON names > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0444 Limit exceeded - number of IF nesting levels > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0445 Limit exceeded - number of CALL parameters > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0446 Limit exceeded - number of SORT/MERGE input files > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0447 Limit exceeded - number of SORT/MERGE keys > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0448 Limit exceeded - number of conditions in a SEARCH ALL > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0449 Limit exceeded - number of UNSTRING delimiters > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0450 Limit exceeded - number of operands in INSPECT TALLYING/REPLACING > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0451 Limit exceeded - length of SORT/MERGE keys > limit characters

Parent topic: COBCH0441 - COBCH0460


COBCH0452 Limit exceeded - number of PROCEDURE DIVISION USING parameters > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0453 Limit exceeded - number of ENTRY USING parameters > limit

Parent topic: COBCH0441 - COBCH0460


COBCH0460 Previous item crosses 64K boundary. Segment checking code produced

Parent topic: COBCH0441 - COBCH0460


COBCH0461 - COBCH0480

Lists the Syntax Checking error messages from COBCH0461 through COBCH0480.

  • COBCH0461 Table crosses 64K boundary. Segment checking code produced
  • COBCH0462 Directive use(filename.dir) used causes recursion
    There is a recursive reference in one of the directives files specified through the USE Compiler directive.
  • COBCH0463 Parameter to call-by-number routine not contained in first 64K of WS
  • COBCH0465 File Section exceeds 64K. Recompile with CALLFH directive
  • COBCH0466 KEY-YY not supported; assumed KEY
    The Siemens BS2000 SORT statement allows the use of KEY-YY. This compiler has accepted the syntax but will most likely produce invalid results.
  • COBCH0467 Overlapping data-items
  • COBCH0468 No valid data for xml generation
  • COBCH0469 %1_s must be a NATIONAL data-item
  • COBCH0470 No next sentence found for NEXT SENTENCE statement_
  • COBCH0471 ASSIGN name %1_s in THREAD-LOCAL, but no THREAD-LOCAL clause on FD
  • COBCH0473 SORT key not within the first %1_s bytes of the file record_
  • COBCH0474 A duplicate "RECORD" clause was found in an "FD" or "SD" entry_
  • COBCH0475 A FUNCTION cannot be the subject of an INSPECT REPLACING statement
  • COBCH0477 More than 18 numeric positions in extended ACCEPT/DISPLAY syntax
    You have attempted to use an extended ACCEPT or DISPLAY statement with a numeric item larger than 18 numeric positions.
  • COBCH0478 Conflicting SQL directives specified
  • COBCH0479 Cannot specify a special register in ADDRSV ADDSYN MAKESYN OVERRIDE REMOVE
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0461 Table crosses 64K boundary. Segment checking code produced

Parent topic: COBCH0461 - COBCH0480


COBCH0462 Directive use(filename.dir) used causes recursion

There is a recursive reference in one of the directives files specified through the USE Compiler directive.

Check the directives file(s) in use for any recursive references, and correct them.

Parent topic: COBCH0461 - COBCH0480


COBCH0463 Parameter to call-by-number routine not contained in first 64K of WS

Parent topic: COBCH0461 - COBCH0480


COBCH0465 File Section exceeds 64K. Recompile with CALLFH directive

Parent topic: COBCH0461 - COBCH0480


COBCH0466 KEY-YY not supported; assumed KEY

The Siemens BS2000 SORT statement allows the use of KEY-YY. This compiler has accepted the syntax but will most likely produce invalid results.
Parent topic: COBCH0461 - COBCH0480


COBCH0467 Overlapping data-items

Parent topic: COBCH0461 - COBCH0480


COBCH0468 No valid data for xml generation

Parent topic: COBCH0461 - COBCH0480


COBCH0469 %1_s must be a NATIONAL data-item

Parent topic: COBCH0461 - COBCH0480


COBCH0470 No next sentence found for NEXT SENTENCE statement_

Parent topic: COBCH0461 - COBCH0480


COBCH0471 ASSIGN name %1_s in THREAD-LOCAL, but no THREAD-LOCAL clause on FD

Parent topic: COBCH0461 - COBCH0480


COBCH0473 SORT key not within the first %1_s bytes of the file record_

Parent topic: COBCH0461 - COBCH0480


COBCH0474 A duplicate "RECORD" clause was found in an "FD" or "SD" entry_

Parent topic: COBCH0461 - COBCH0480


COBCH0475 A FUNCTION cannot be the subject of an INSPECT REPLACING statement

Parent topic: COBCH0461 - COBCH0480


COBCH0477 More than 18 numeric positions in extended ACCEPT/DISPLAY syntax

You have attempted to use an extended ACCEPT or DISPLAY statement with a numeric item larger than 18 numeric positions.

This is a limitation if you are using extended ACCEPT and DISPLAY statements.

Parent topic: COBCH0461 - COBCH0480


COBCH0478 Conflicting SQL directives specified

Resolution:

Parent topic: COBCH0461 - COBCH0480


COBCH0479 Cannot specify a special register in ADDRSV ADDSYN MAKESYN OVERRIDE REMOVE

Resolution:

Parent topic: COBCH0461 - COBCH0480


COBCH0481 - COBCH0500

Lists the Syntax Checking error messages from COBCH0481 through COBCH0500.

  • COBCH0498 Procedure name %1_s undeclared, line %2_s
  • COBCH0499 DISPLAY ALL figurative constant syntax used
    You have used the syntax DISPLAY ALL figurative constant which is not conformant with your selected flagging dialect.
  • COBCH0500 DISPLAY ALL literal syntax used
    You have used the syntax DISPLAY ALL literal which is not conformant with your selected flagging dialect.
Parent topic: Messages COBCH0401 to COBCH0500


COBCH0498 Procedure name %1_s undeclared, line %2_s

Parent topic: COBCH0481 - COBCH0500


COBCH0499 DISPLAY ALL figurative constant syntax used

You have used the syntax DISPLAY ALL figurative constant which is not conformant with your selected flagging dialect.
Parent topic: COBCH0481 - COBCH0500


COBCH0500 DISPLAY ALL literal syntax used

You have used the syntax DISPLAY ALL literal which is not conformant with your selected flagging dialect.
Parent topic: COBCH0481 - COBCH0500


Messages COBCH0501 to COBCH0600

  • COBCH0501 - COBCH0520
    Lists the Syntax Checking error messages from COBCH0501 through COBCH0520.
  • COBCH0521 - COBCH0540
    Lists the Syntax Checking error messages from COBCH0521 through COBCH0540.
  • COBCH0541 - COBCH0560
    Lists the Syntax Checking error messages from COBCH0541 through COBCH0560.
  • COBCH0561 - COBCH0580
    Lists the Syntax Checking error messages from COBCH0561 through COBCH0580.
  • COBCH0581 - COBCH0600
    Lists the Syntax Checking error messages from COBCH0581 through COBCH0600.
Parent topic: Syntax Checking Error Messages


COBCH0501 - COBCH0520

Lists the Syntax Checking error messages from COBCH0501 through COBCH0520.

  • COBCH0501 Feature is part of an optional module - module-name
  • COBCH0502 This entire section is part of an optional module - module-name
  • COBCH0503 USAGE COMP used at other than 01 level
  • COBCH0504 ORGANIZATION clause in SELECT statement of sort file
  • COBCH0505 VALUE OF clause in SD or CD
  • COBCH0506 REDEFINES does not immediately follow data-name
    The REDEFINES clause does not immediately follow data-name in your program.
  • COBCH0507 Numeric literal VALUE on edited item
  • COBCH0508 NEXT used in READ of sequential file
  • COBCH0509 SET operation on non-index data item
  • COBCH0510 ZEROS or ZEROES in BLANK WHEN clause. Treated as ZERO
  • COBCH0511 FILE STATUS data-name is not alphanumeric
    You have specified a nonalphanumeric data item in your FILE STATUS.
  • COBCH0512 Data-name is qualified
  • COBCH0513 Flag refers to entire section
  • COBCH0514 "CHANGED" and/or "NAMED" missing
    You have omitted at least one of CHANGED or NAMED.
  • COBCH0515 Phrases repeated
  • COBCH0516 Only 1 file specified in SAME AREA clause
  • COBCH0517 Jump out of inline PERFORM
  • COBCH0518 > or < followed by THAN or THEN, or = followed by TO
    You have included the noise words THAN and TO unnecessarily in your code.
  • COBCH0519 More than 5 levels of qualification
  • COBCH0520 "INVALID KEY" phrase used with sequential file
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0501 Feature is part of an optional module - module-name

Parent topic: COBCH0501 - COBCH0520


COBCH0502 This entire section is part of an optional module - module-name

Parent topic: COBCH0501 - COBCH0520


COBCH0503 USAGE COMP used at other than 01 level

Parent topic: COBCH0501 - COBCH0520


COBCH0504 ORGANIZATION clause in SELECT statement of sort file

Parent topic: COBCH0501 - COBCH0520


COBCH0505 VALUE OF clause in SD or CD

Parent topic: COBCH0501 - COBCH0520


COBCH0506 REDEFINES does not immediately follow data-name

The REDEFINES clause does not immediately follow data-name in your program.

Resolution:

Revise your program so that REDEFINES immediately follows data-name.

Parent topic: COBCH0501 - COBCH0520


COBCH0507 Numeric literal VALUE on edited item

Parent topic: COBCH0501 - COBCH0520


COBCH0508 NEXT used in READ of sequential file

Parent topic: COBCH0501 - COBCH0520


COBCH0509 SET operation on non-index data item

Parent topic: COBCH0501 - COBCH0520


COBCH0510 ZEROS or ZEROES in BLANK WHEN clause. Treated as ZERO

Parent topic: COBCH0501 - COBCH0520


COBCH0511 FILE STATUS data-name is not alphanumeric

You have specified a nonalphanumeric data item in your FILE STATUS.

Resolution:

Amend your code to make the data item alphanumeric.

Parent topic: COBCH0501 - COBCH0520


COBCH0512 Data-name is qualified

Parent topic: COBCH0501 - COBCH0520


COBCH0513 Flag refers to entire section

Parent topic: COBCH0501 - COBCH0520


COBCH0514 "CHANGED" and/or "NAMED" missing

You have omitted at least one of CHANGED or NAMED.

Resolution:

Add CHANGED and/or NAMED to your program.

Parent topic: COBCH0501 - COBCH0520


COBCH0515 Phrases repeated

Parent topic: COBCH0501 - COBCH0520


COBCH0516 Only 1 file specified in SAME AREA clause

Parent topic: COBCH0501 - COBCH0520


COBCH0517 Jump out of inline PERFORM

Parent topic: COBCH0501 - COBCH0520


COBCH0518 > or < followed by THAN or THEN, or = followed by TO

You have included the noise words THAN and TO unnecessarily in your code.

Resolution:

Delete these words.

Parent topic: COBCH0501 - COBCH0520


COBCH0519 More than 5 levels of qualification

Parent topic: COBCH0501 - COBCH0520


COBCH0520 "INVALID KEY" phrase used with sequential file

Parent topic: COBCH0501 - COBCH0520


COBCH0521 - COBCH0540

Lists the Syntax Checking error messages from COBCH0521 through COBCH0540.

  • COBCH0521 USING literal/LENGTH OF identifier. (BY CONTENT implied for this item)
  • COBCH0522 BY CONTENT literal/LENGTH OF identifier
  • COBCH0523 Declarative Section without USE statement
  • COBCH0524 ALPHABET IS ASCII
  • COBCH0525 EOP or END-OF-PAGE used on file which has no LINAGE
    You have specified EOP, which is invalid for a file which has no LINAGE.
  • COBCH0526 Phrases are not in the correct order
  • COBCH0527 REDEFINES at 01 in File Section
  • COBCH0528 Data-name data-name in ASC/DESC key clause is not uniquely identified
  • COBCH0529 Clause treated as documentary
  • COBCH0530 Data item used as index file key is not alphanumeric
    The data item you have specified as an index file key is not alphanumeric.
  • COBCH0531 Too many subscripts
  • COBCH0532 INTO data-name is group item
  • COBCH0533 START ... LESS/NOT GREATER THAN ...
  • COBCH0534 Entry treated as documentary
  • COBCH0535 ALPHABET is EBCDIC
  • COBCH0537 BASIS mechanism (BASIS, DELETE or INSERT)
  • COBCH0538 Picture string is continued
  • COBCH0539 This item is obsolete in 1985 standard
    The syntax you have used is not supported under ANSI'85.
  • COBCH0540 Source field is edited
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0521 USING literal/LENGTH OF identifier. (BY CONTENT implied for this item)

Parent topic: COBCH0521 - COBCH0540


COBCH0522 BY CONTENT literal/LENGTH OF identifier

Parent topic: COBCH0521 - COBCH0540


COBCH0523 Declarative Section without USE statement

Parent topic: COBCH0521 - COBCH0540


COBCH0524 ALPHABET IS ASCII

Parent topic: COBCH0521 - COBCH0540


COBCH0525 EOP or END-OF-PAGE used on file which has no LINAGE

You have specified EOP, which is invalid for a file which has no LINAGE.

Resolution:

Delete EOP.

Parent topic: COBCH0521 - COBCH0540


COBCH0526 Phrases are not in the correct order

Parent topic: COBCH0521 - COBCH0540


COBCH0527 REDEFINES at 01 in File Section

Parent topic: COBCH0521 - COBCH0540


COBCH0528 Data-name data-name in ASC/DESC key clause is not uniquely identified

Parent topic: COBCH0521 - COBCH0540


COBCH0529 Clause treated as documentary

Parent topic: COBCH0521 - COBCH0540


COBCH0530 Data item used as index file key is not alphanumeric

The data item you have specified as an index file key is not alphanumeric.

Resolution:

Revise your code to make the data item alphanumeric.

Parent topic: COBCH0521 - COBCH0540


COBCH0531 Too many subscripts

Parent topic: COBCH0521 - COBCH0540


COBCH0532 INTO data-name is group item

Parent topic: COBCH0521 - COBCH0540


COBCH0533 START ... LESS/NOT GREATER THAN ...

Parent topic: COBCH0521 - COBCH0540


COBCH0534 Entry treated as documentary

Parent topic: COBCH0521 - COBCH0540


COBCH0535 ALPHABET is EBCDIC

Parent topic: COBCH0521 - COBCH0540


COBCH0537 BASIS mechanism (BASIS, DELETE or INSERT)

Parent topic: COBCH0521 - COBCH0540


COBCH0538 Picture string is continued

Parent topic: COBCH0521 - COBCH0540


COBCH0539 This item is obsolete in 1985 standard

The syntax you have used is not supported under ANSI'85.

Resolution:

Delete this syntax.

Parent topic: COBCH0521 - COBCH0540


COBCH0540 Source field is edited

Parent topic: COBCH0521 - COBCH0540


COBCH0541 - COBCH0560

Lists the Syntax Checking error messages from COBCH0541 through COBCH0560.

  • COBCH0541 Comparison between edited field and COMP field
  • COBCH0542 VALUE clause on group COMP
  • COBCH0543 VALUE clause on variable length group
  • COBCH0544 VALUE clause with OCCURS or subsidiary to group OCCURS
  • COBCH0545 ALTERNATE RECORD KEY is not in SAA
  • COBCH0546 PICTURE symbol P not allowed in RELATIVE KEY
    You have included the PICTURE symbol P in a Relative Key.
  • COBCH0547 END-IF used with NEXT SENTENCE
  • COBCH0548 Program is nested
  • COBCH0549 USING identifier must not be a redefinition
  • COBCH0550 Pseudo-text consists entirely of a separator comma or semicolon
  • COBCH0551 Second status field does not comply with VSC2_BS2000 specifications
  • COBCH0552 Comment lines precede IDENTIFICATION DIVISION
  • COBCH0553 syntax : non-conforming standard ANS85
    The language element is part of the ANSI'85 standard but above the flagging level selected.
  • COBCH0554 Syntax is non-conforming non-standard ANS85
    The language element is not part of the ANSI'85 standard. It is an OS/VS COBOL, VS COBOL II, Micro Focus, or other extension.
  • COBCH0555 syntax : marked as obsolete in the ANS85 standard
    The ANSI'85 standard has defined this language element as obsolete. It will be removed from the next ANSI standard.
  • COBCH0556 Multiple program source
    Source file contains more than one source program. In this situation, more than one separate, not nested, program exists.
  • COBCH0557 Multiple GIVING files
    A SORT or MERGE statement contains multiple files in the GIVING clause.
  • COBCH0558 Comparison between index-name and arithmetic expression
  • COBCH0559 Statement cannot be reached
  • COBCH0560 Alphabet declared without ALPHABET keyword
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0541 Comparison between edited field and COMP field

Parent topic: COBCH0541 - COBCH0560


COBCH0542 VALUE clause on group COMP

Parent topic: COBCH0541 - COBCH0560


COBCH0543 VALUE clause on variable length group

Parent topic: COBCH0541 - COBCH0560


COBCH0544 VALUE clause with OCCURS or subsidiary to group OCCURS

Parent topic: COBCH0541 - COBCH0560


COBCH0545 ALTERNATE RECORD KEY is not in SAA

Parent topic: COBCH0541 - COBCH0560


COBCH0546 PICTURE symbol P not allowed in RELATIVE KEY

You have included the PICTURE symbol P in a Relative Key.

Resolution:

Delete P.

Parent topic: COBCH0541 - COBCH0560


COBCH0547 END-IF used with NEXT SENTENCE

Parent topic: COBCH0541 - COBCH0560


COBCH0548 Program is nested

Parent topic: COBCH0541 - COBCH0560


COBCH0549 USING identifier must not be a redefinition

Parent topic: COBCH0541 - COBCH0560


COBCH0550 Pseudo-text consists entirely of a separator comma or semicolon

Parent topic: COBCH0541 - COBCH0560


COBCH0551 Second status field does not comply with VSC2_BS2000 specifications

Parent topic: COBCH0541 - COBCH0560


COBCH0552 Comment lines precede IDENTIFICATION DIVISION

Parent topic: COBCH0541 - COBCH0560


COBCH0553 syntax : non-conforming standard ANS85

The language element is part of the ANSI'85 standard but above the flagging level selected.
Parent topic: COBCH0541 - COBCH0560


COBCH0554 Syntax is non-conforming non-standard ANS85

The language element is not part of the ANSI'85 standard. It is an OS/VS COBOL, VS COBOL II, Micro Focus, or other extension.
Parent topic: COBCH0541 - COBCH0560


COBCH0555 syntax : marked as obsolete in the ANS85 standard

The ANSI'85 standard has defined this language element as obsolete. It will be removed from the next ANSI standard.

Resolution:

Delete this syntax.

Parent topic: COBCH0541 - COBCH0560


COBCH0556 Multiple program source

Source file contains more than one source program. In this situation, more than one separate, not nested, program exists.
Parent topic: COBCH0541 - COBCH0560


COBCH0557 Multiple GIVING files

A SORT or MERGE statement contains multiple files in the GIVING clause.
Parent topic: COBCH0541 - COBCH0560


COBCH0558 Comparison between index-name and arithmetic expression

Parent topic: COBCH0541 - COBCH0560


COBCH0559 Statement cannot be reached

Parent topic: COBCH0541 - COBCH0560


COBCH0560 Alphabet declared without ALPHABET keyword

Parent topic: COBCH0541 - COBCH0560


COBCH0561 - COBCH0580

Lists the Syntax Checking error messages from COBCH0561 through COBCH0580.

  • COBCH0561 A "NOT" phrase did not have a matching verb and was discarded
    You declared a NOT phrase but failed to declare a matching verb.
  • COBCH0562 An "ELSE" phrase did not have a matching IF and was discarded
    You declared an ELSE phrase but failed to declare a matching IF.
  • COBCH0563 A "WHEN" phrase did not have a matching verb and was discarded
    You declared a WHEN phrase but failed to declare a matching verb.
  • COBCH0564 A scope-delimiter did not have a matching verb and was discarded
    You declared a scope-delimiter but failed to declare a matching verb.
  • COBCH0565 RECORDING MODE used with INDEXED or RELATIVE file
  • COBCH0566 This release does not support floating point in this context
  • COBCH0567 USAGE DISPLAY-1 missing
    You have omitted the words USAGE DISPLAY-1.
  • COBCH0568 Sign condition in EVALUATE statement
  • COBCH0569 Data item does not have fixed location
  • COBCH0570 Insufficient space in area B for SO/SI insertion
    You do not have sufficient space in area B for SO/SI characters to be inserted for the DBCS items. If the source program is ported to an environment requiring SO/SI characters the source line might become corrupted.
  • COBCH0571 Mixed literal is continued
  • COBCH0572 INITIALIZE operand does not have fixed location
  • COBCH0573 More than one REPLACING phrase
  • COBCH0574 Conditional statement not terminated by its scope-delimiter
  • COBCH0575 Zero suppression follows floating insertion
  • COBCH0576 Preceding statement is not imperative
  • COBCH0577 Group level USAGE does not match PICTURE type - USAGE ignored
    You have declared a PICTURE clause but the group USAGE does not match this type.
  • COBCH0578 PROGRAM-ID specified as literal
  • COBCH0579 PROGRAM-ID is DBCS name
  • COBCH0580 User-defined word as DBCS name
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0561 A "NOT" phrase did not have a matching verb and was discarded

You declared a NOT phrase but failed to declare a matching verb.

Resolution:

Add the appropriate verb.

Parent topic: COBCH0561 - COBCH0580


COBCH0562 An "ELSE" phrase did not have a matching IF and was discarded

You declared an ELSE phrase but failed to declare a matching IF.

Resolution:

Resolve the mismatch between the conditional verbs.

Parent topic: COBCH0561 - COBCH0580


COBCH0563 A "WHEN" phrase did not have a matching verb and was discarded

You declared a WHEN phrase but failed to declare a matching verb.

Resolution:

Add the appropriate verb.

Parent topic: COBCH0561 - COBCH0580


COBCH0564 A scope-delimiter did not have a matching verb and was discarded

You declared a scope-delimiter but failed to declare a matching verb.

Resolution:

Resolve the mismatch between the conditional verbs.

Parent topic: COBCH0561 - COBCH0580


COBCH0565 RECORDING MODE used with INDEXED or RELATIVE file

Parent topic: COBCH0561 - COBCH0580


COBCH0566 This release does not support floating point in this context

Parent topic: COBCH0561 - COBCH0580


COBCH0567 USAGE DISPLAY-1 missing

You have omitted the words USAGE DISPLAY-1.

Resolution:

Add USAGE DISPLAY-1.

Parent topic: COBCH0561 - COBCH0580


COBCH0568 Sign condition in EVALUATE statement

Parent topic: COBCH0561 - COBCH0580


COBCH0569 Data item does not have fixed location

Parent topic: COBCH0561 - COBCH0580


COBCH0570 Insufficient space in area B for SO/SI insertion

You do not have sufficient space in area B for SO/SI characters to be inserted for the DBCS items. If the source program is ported to an environment requiring SO/SI characters the source line might become corrupted.
Parent topic: COBCH0561 - COBCH0580


COBCH0571 Mixed literal is continued

Parent topic: COBCH0561 - COBCH0580


COBCH0572 INITIALIZE operand does not have fixed location

Parent topic: COBCH0561 - COBCH0580


COBCH0573 More than one REPLACING phrase

Parent topic: COBCH0561 - COBCH0580


COBCH0574 Conditional statement not terminated by its scope-delimiter

Parent topic: COBCH0561 - COBCH0580


COBCH0575 Zero suppression follows floating insertion

Parent topic: COBCH0561 - COBCH0580


COBCH0576 Preceding statement is not imperative

Parent topic: COBCH0561 - COBCH0580


COBCH0577 Group level USAGE does not match PICTURE type - USAGE ignored

You have declared a PICTURE clause but the group USAGE does not match this type.

Resolution:

Either delete the USAGE clause or change the PICTURE clause.

Parent topic: COBCH0561 - COBCH0580


COBCH0578 PROGRAM-ID specified as literal

Parent topic: COBCH0561 - COBCH0580


COBCH0579 PROGRAM-ID is DBCS name

Parent topic: COBCH0561 - COBCH0580


COBCH0580 User-defined word as DBCS name

Parent topic: COBCH0561 - COBCH0580


COBCH0581 - COBCH0600

Lists the Syntax Checking error messages from COBCH0581 through COBCH0600.

  • COBCH0581 END-SEARCH used with NEXT SENTENCE
  • COBCH0582 Redefined item has OCCURS phrase
  • COBCH0583 EXIT PROGRAM in GLOBAL declarative
  • COBCH0584 Inline PERFORM statement not terminated by END-PERFORM
  • COBCH0585 Imperative statement missing
    You have failed to specify an imperative statement.
  • COBCH0586 Smallest record size size1 > minimum in RECORD clause size2
    You have specified a minimum size for your record definitions, but none of the records you have defined is that small.
  • COBCH0587 Largest record size size1 < maximum in RECORD clause size2
    You have specified a maximum size for your record definitions, but none of the records you have defined is that large.
  • COBCH0588 Operand does not have USAGE DISPLAY
  • COBCH0589 Procedure Division does not finish with complete sentence
  • COBCH0590 USING/GIVING file does not have ORGANIZATION SEQUENTIAL
  • COBCH0591 USING/GIVING file has ACCESS RANDOM
  • COBCH0592 USING/GIVING file has ACCESS DYNAMIC
  • COBCH0593 Sequence number contains nonnumeric characters
  • COBCH0594 Variable length group is operand of INITIALIZE statement
  • COBCH0595 SORT file has FILE STATUS clause
  • COBCH0596 01 level record in Report Section is elementary
  • COBCH0597 Object of SUM clause belongs to different report
  • COBCH0598 Assignment-name is alphanumeric literal
  • COBCH0599 Literal form of CODE phrase
  • COBCH0600 Name is implicitly qualified
Parent topic: Messages COBCH0501 to COBCH0600


COBCH0581 END-SEARCH used with NEXT SENTENCE

Parent topic: COBCH0581 - COBCH0600


COBCH0582 Redefined item has OCCURS phrase

Parent topic: COBCH0581 - COBCH0600


COBCH0583 EXIT PROGRAM in GLOBAL declarative

Parent topic: COBCH0581 - COBCH0600


COBCH0584 Inline PERFORM statement not terminated by END-PERFORM

Parent topic: COBCH0581 - COBCH0600


COBCH0585 Imperative statement missing

You have failed to specify an imperative statement.

Resolution:

Include an imperative statement.

Parent topic: COBCH0581 - COBCH0600


COBCH0586 Smallest record size size1 > minimum in RECORD clause size2

You have specified a minimum size for your record definitions, but none of the records you have defined is that small.

Resolution:

Revise your code so that the minimum size specified is equal to your smallest data record.

Parent topic: COBCH0581 - COBCH0600


COBCH0587 Largest record size size1 < maximum in RECORD clause size2

You have specified a maximum size for your record definitions, but none of the records you have defined is that large.

Resolution:

Revise your code so that the maximum size specified is equal to your largest data record.

Parent topic: COBCH0581 - COBCH0600


COBCH0588 Operand does not have USAGE DISPLAY

Parent topic: COBCH0581 - COBCH0600


COBCH0589 Procedure Division does not finish with complete sentence

Parent topic: COBCH0581 - COBCH0600


COBCH0590 USING/GIVING file does not have ORGANIZATION SEQUENTIAL

Parent topic: COBCH0581 - COBCH0600


COBCH0591 USING/GIVING file has ACCESS RANDOM

Parent topic: COBCH0581 - COBCH0600


COBCH0592 USING/GIVING file has ACCESS DYNAMIC

Parent topic: COBCH0581 - COBCH0600


COBCH0593 Sequence number contains nonnumeric characters

Parent topic: COBCH0581 - COBCH0600


COBCH0594 Variable length group is operand of INITIALIZE statement

Parent topic: COBCH0581 - COBCH0600


COBCH0595 SORT file has FILE STATUS clause

Parent topic: COBCH0581 - COBCH0600


COBCH0596 01 level record in Report Section is elementary

Parent topic: COBCH0581 - COBCH0600


COBCH0597 Object of SUM clause belongs to different report

Parent topic: COBCH0581 - COBCH0600


COBCH0598 Assignment-name is alphanumeric literal

Parent topic: COBCH0581 - COBCH0600


COBCH0599 Literal form of CODE phrase

Parent topic: COBCH0581 - COBCH0600


COBCH0600 Name is implicitly qualified

Parent topic: COBCH0581 - COBCH0600


Messages COBCH0601 to COBCH0700

  • COBCH0601 - COBCH0620
    Lists the Syntax Checking error messages from COBCH0601 through COBCH0620.
  • COBCH0621 - COBCH0640
    Lists the Syntax Checking error messages from COBCH0621 through COBCH0640.
  • COBCH0641 - COBCH0660
    Lists the Syntax Checking error messages from COBCH0641 through COBCH0660.
  • COBCH0661 - COBCH0680
    Lists the Syntax Checking error messages from COBCH0661 through COBCH0680.
  • COBCH0681 - COBCH0700
    Lists the Syntax Checking error messages from COBCH0681 through COBCH0700.
Parent topic: Syntax Checking Error Messages


COBCH0601 - COBCH0620

Lists the Syntax Checking error messages from COBCH0601 through COBCH0620.

  • COBCH0601 USE BEFORE REPORTING on DETAIL group
  • COBCH0602 Neither LINE nor LINES specified
  • COBCH0603 SIGN phrase in Report Section
  • COBCH0604 GLOBAL specified for entry without data-name
  • COBCH0605 More than one SUM for single item
  • COBCH0606 Program does not contain Procedure Division
  • COBCH0607 PROCEDURE DIVISION header missing
  • COBCH0608 Pseudo-text delimiter preceded / followed by illegal character
    The pseudo text delimiters used in COPY ... REPLACING and REPLACE must be preceded by a space and followed by a separator. The system assumes one was present.
  • COBCH0609 Apostrophe found with QUOTE directive (future occurrences not flagged)
  • COBCH0610 Quote found with APOST directive (future occurrences not flagged)
  • COBCH0611 Line %1$d Column %2$d
  • COBCH0612 EXIT PROGRAM not in separate paragraph
  • COBCH0613 Invalid program name
  • COBCH0614 Previous LINE clause specified same number
  • COBCH0615 Floating point data item
  • COBCH0616 This EXIT statement format is an MF extension
  • COBCH0617 Data item is defined at level 66
  • COBCH0618 Data item is not declared in Linkage Section
  • COBCH0619 User-name mixes single-byte and double-byte characters
  • COBCH0620 DBCS user-name exceeds 14 characters in length
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0601 USE BEFORE REPORTING on DETAIL group

Parent topic: COBCH0601 - COBCH0620


COBCH0602 Neither LINE nor LINES specified

Parent topic: COBCH0601 - COBCH0620


COBCH0603 SIGN phrase in Report Section

Parent topic: COBCH0601 - COBCH0620


COBCH0604 GLOBAL specified for entry without data-name

Parent topic: COBCH0601 - COBCH0620


COBCH0605 More than one SUM for single item

Parent topic: COBCH0601 - COBCH0620


COBCH0606 Program does not contain Procedure Division

Parent topic: COBCH0601 - COBCH0620


COBCH0607 PROCEDURE DIVISION header missing

Parent topic: COBCH0601 - COBCH0620


COBCH0608 Pseudo-text delimiter preceded / followed by illegal character

The pseudo text delimiters used in COPY ... REPLACING and REPLACE must be preceded by a space and followed by a separator. The system assumes one was present.
Parent topic: COBCH0601 - COBCH0620


COBCH0609 Apostrophe found with QUOTE directive (future occurrences not flagged)

Parent topic: COBCH0601 - COBCH0620


COBCH0610 Quote found with APOST directive (future occurrences not flagged)

Parent topic: COBCH0601 - COBCH0620


COBCH0611 Line %1$d Column %2$d

Resolution:

Parent topic: COBCH0601 - COBCH0620


COBCH0612 EXIT PROGRAM not in separate paragraph

Parent topic: COBCH0601 - COBCH0620


COBCH0613 Invalid program name

Parent topic: COBCH0601 - COBCH0620


COBCH0614 Previous LINE clause specified same number

Parent topic: COBCH0601 - COBCH0620


COBCH0615 Floating point data item

Parent topic: COBCH0601 - COBCH0620


COBCH0616 This EXIT statement format is an MF extension

Parent topic: COBCH0601 - COBCH0620


COBCH0617 Data item is defined at level 66

Parent topic: COBCH0601 - COBCH0620


COBCH0618 Data item is not declared in Linkage Section

Parent topic: COBCH0601 - COBCH0620


COBCH0619 User-name mixes single-byte and double-byte characters

Parent topic: COBCH0601 - COBCH0620


COBCH0620 DBCS user-name exceeds 14 characters in length

Parent topic: COBCH0601 - COBCH0620


COBCH0621 - COBCH0640

Lists the Syntax Checking error messages from COBCH0621 through COBCH0640.

  • COBCH0621 DBCS user-name begins with DBCS equivalent of SBCS "-" character
  • COBCH0622 DBCS name contains illegal character
  • COBCH0623 DBCS name contains only DBCS characters equivalent to SBCS characters
  • COBCH0624 Belongs to Linkage record not specified in PROCEDURE DIVISION header
    A linkage item referenced in your source code does not have addressability.
  • COBCH0625 Alphabetic edited item treated as alphabetic
  • COBCH0626 Edited field not allowed
  • COBCH0627 Section header not followed by paragraph name or other Section header
  • COBCH0628 Use of symbolic literal defined in level 78 or CONSTANT directive
  • COBCH0629 Use of signed or non-integer numeric literal
  • COBCH0630 INTO not legal for this file
  • COBCH0631 GLOBAL specified in Linkage Section
  • COBCH0632 A FUNCTION cannot be a receiving item
  • COBCH0633 REPORT HEADING extends beyond first detail_ NEXT GROUP NEXT PAGE assumed_
  • COBCH0634 Feature not supported in selected dialect
    Your source code contains a language feature that is not supported in the dialect that you are currently using.
  • COBCH0635 VALUE specified for external floating point data item
  • COBCH0636 Level 88 defined on external floating point data item
  • COBCH0637 ACCEPT references internal floating point data item
  • COBCH0638 Floating point data illegal in DIVIDE with REMAINDER clause
  • COBCH0639 Reserved word OR missing
  • COBCH0640 Floating point data item used in SEARCH ALL statement
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0621 DBCS user-name begins with DBCS equivalent of SBCS "-" character

Parent topic: COBCH0621 - COBCH0640


COBCH0622 DBCS name contains illegal character

Parent topic: COBCH0621 - COBCH0640


COBCH0623 DBCS name contains only DBCS characters equivalent to SBCS characters

Parent topic: COBCH0621 - COBCH0640


COBCH0624 Belongs to Linkage record not specified in PROCEDURE DIVISION header

A linkage item referenced in your source code does not have addressability.
You must give the item addressability, using one of the following methods:
  • Specify the item in the USING phrase of the PROCEDURE DIVISION:
    Procedure division USING itema.
  • Specify a valid address for the item using the SET statement:
    SET address of itema to address of itemb.
    Note: This option is not available for all dialects.
Parent topic: COBCH0621 - COBCH0640


COBCH0625 Alphabetic edited item treated as alphabetic

Parent topic: COBCH0621 - COBCH0640


COBCH0626 Edited field not allowed

Parent topic: COBCH0621 - COBCH0640


COBCH0627 Section header not followed by paragraph name or other Section header

Parent topic: COBCH0621 - COBCH0640


COBCH0628 Use of symbolic literal defined in level 78 or CONSTANT directive

Parent topic: COBCH0621 - COBCH0640


COBCH0629 Use of signed or non-integer numeric literal

Parent topic: COBCH0621 - COBCH0640


COBCH0630 INTO not legal for this file

Parent topic: COBCH0621 - COBCH0640


COBCH0631 GLOBAL specified in Linkage Section

Parent topic: COBCH0621 - COBCH0640


COBCH0632 A FUNCTION cannot be a receiving item

Parent topic: COBCH0621 - COBCH0640


COBCH0633 REPORT HEADING extends beyond first detail_ NEXT GROUP NEXT PAGE assumed_

Parent topic: COBCH0621 - COBCH0640


COBCH0634 Feature not supported in selected dialect

Your source code contains a language feature that is not supported in the dialect that you are currently using.

You must either change your code to avoid using the feature, or specify a dialect that supports the feature.

Parent topic: COBCH0621 - COBCH0640


COBCH0635 VALUE specified for external floating point data item

Parent topic: COBCH0621 - COBCH0640


COBCH0636 Level 88 defined on external floating point data item

Parent topic: COBCH0621 - COBCH0640


COBCH0637 ACCEPT references internal floating point data item

Parent topic: COBCH0621 - COBCH0640


COBCH0638 Floating point data illegal in DIVIDE with REMAINDER clause

Parent topic: COBCH0621 - COBCH0640


COBCH0639 Reserved word OR missing

Parent topic: COBCH0621 - COBCH0640


COBCH0640 Floating point data item used in SEARCH ALL statement

Parent topic: COBCH0621 - COBCH0640


COBCH0641 - COBCH0660

Lists the Syntax Checking error messages from COBCH0641 through COBCH0660.

  • COBCH0641 '_' missing following procedure name declaration, or unrecognized verb
  • COBCH0642 Source and target start at same location
  • COBCH0643 Source and target overlap, and source is at a higher address than target
    If the source and target items in a move overlap, the result of the move is undefined.
  • COBCH0644 Significand has more than 16 numeric positions
  • COBCH0645 Floating-point value out of range
  • COBCH0647 CURSOR/CRT STATUS data item may not be in LOCAL-STORAGE/LINKAGE
  • COBCH0648 Illegal use of Local-Storage item
  • COBCH0649 Record length exceeds system limit
  • COBCH0650 No matching $IF - ignored
    A $END or $ELSE conditional compilation statement has been found without a preceding $IF. The line was ignored.
  • COBCH0651 SORT key cannot have, or be subsidiary to item with, OCCURS clause
  • COBCH0652 BY CONTENT numeric literal
    You have specified a numeric literal as a BY CONTENT parameter on a CALL/ CHAIN/ INVOKE statement which is not supported under your selected dialect.
  • COBCH0654 NEXT GROUP specified for group with no LINE NUMBER clause
  • COBCH0655 NEXT GROUP NEXT PAGE specified for report without PAGE description
  • COBCH0656 Source and target overlap, and source is at lower address than target
  • COBCH0657 Should be declared in Linkage Section
  • COBCH0658 NUMERIC class test on ALPHABETIC item
  • COBCH0659 Screen name mandatory at 01 level in Screen Section
  • COBCH0660 Positive signed integer used in relative subscripting
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0641 '_' missing following procedure name declaration, or unrecognized verb

Parent topic: COBCH0641 - COBCH0660


COBCH0642 Source and target start at same location

Parent topic: COBCH0641 - COBCH0660


COBCH0643 Source and target overlap, and source is at a higher address than target

If the source and target items in a move overlap, the result of the move is undefined.
Parent topic: COBCH0641 - COBCH0660


COBCH0644 Significand has more than 16 numeric positions

Parent topic: COBCH0641 - COBCH0660


COBCH0645 Floating-point value out of range

Parent topic: COBCH0641 - COBCH0660


COBCH0647 CURSOR/CRT STATUS data item may not be in LOCAL-STORAGE/LINKAGE

Parent topic: COBCH0641 - COBCH0660


COBCH0648 Illegal use of Local-Storage item

Parent topic: COBCH0641 - COBCH0660


COBCH0649 Record length exceeds system limit

Parent topic: COBCH0641 - COBCH0660


COBCH0650 No matching $IF - ignored

A $END or $ELSE conditional compilation statement has been found without a preceding $IF. The line was ignored.
Parent topic: COBCH0641 - COBCH0660


COBCH0651 SORT key cannot have, or be subsidiary to item with, OCCURS clause

Parent topic: COBCH0641 - COBCH0660


COBCH0652 BY CONTENT numeric literal

You have specified a numeric literal as a BY CONTENT parameter on a CALL/ CHAIN/ INVOKE statement which is not supported under your selected dialect.

Resolution:

Change it to something that is not a numeric literal.

Parent topic: COBCH0641 - COBCH0660


COBCH0654 NEXT GROUP specified for group with no LINE NUMBER clause

Parent topic: COBCH0641 - COBCH0660


COBCH0655 NEXT GROUP NEXT PAGE specified for report without PAGE description

Parent topic: COBCH0641 - COBCH0660


COBCH0656 Source and target overlap, and source is at lower address than target

Parent topic: COBCH0641 - COBCH0660


COBCH0657 Should be declared in Linkage Section

Parent topic: COBCH0641 - COBCH0660


COBCH0658 NUMERIC class test on ALPHABETIC item

Parent topic: COBCH0641 - COBCH0660


COBCH0659 Screen name mandatory at 01 level in Screen Section

Parent topic: COBCH0641 - COBCH0660


COBCH0660 Positive signed integer used in relative subscripting

Parent topic: COBCH0641 - COBCH0660


COBCH0661 - COBCH0680

Lists the Syntax Checking error messages from COBCH0661 through COBCH0680.

  • COBCH0661 Superfluous TO found in MOVE statement. Ignored
  • COBCH0662 Figurative constant or ALL not allowed here
  • COBCH0663 LENGTH function in non-standard context
  • COBCH0664 INPUT-OUTPUT SECTION precedes CONFIGURATION SECTION
  • COBCH0665 Communications syntax incorrect
  • COBCH0666 Reserved word used as data-name or unknown data description qualifier
  • COBCH0667 ODO object object must have fixed location
  • COBCH0668 JUSTIFIED specified on edited field
  • COBCH0669 EVALUATE statement using partial conditional expressions
  • COBCH0670 Selection object does not correspond to selection subject
  • COBCH0671 PERFORM UNTIL EXIT
  • COBCH0672 COPY nested in COPY REPLACING
  • COBCH0673 Incompatible options specified
  • COBCH0674 Subscripting and indexing used for the same identifier
  • COBCH0675 Numeric FUNCTION used as source of MOVE statement
  • COBCH0676 THEN used instead of THAN
  • COBCH0677 Value of previous expression may not be the same under OSVS / VSC2
    The result of the arithmetic expression just evaluated under the OS/VS or VSC2 dialect could be different when evaluated on the mainframe. This warning is displayed when an intermediate result needs more than 19 digits on either side of the decimal point.
  • COBCH0678 Too many CONTROLS specified for report
  • COBCH0679 QUOTE character must be double in an N literal
  • COBCH0680 N" format literal
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0661 Superfluous TO found in MOVE statement. Ignored

Parent topic: COBCH0661 - COBCH0680


COBCH0662 Figurative constant or ALL not allowed here

Parent topic: COBCH0661 - COBCH0680


COBCH0663 LENGTH function in non-standard context

Parent topic: COBCH0661 - COBCH0680


COBCH0664 INPUT-OUTPUT SECTION precedes CONFIGURATION SECTION

Parent topic: COBCH0661 - COBCH0680


COBCH0665 Communications syntax incorrect

Parent topic: COBCH0661 - COBCH0680


COBCH0666 Reserved word used as data-name or unknown data description qualifier

Parent topic: COBCH0661 - COBCH0680


COBCH0667 ODO object object must have fixed location

Parent topic: COBCH0661 - COBCH0680


COBCH0668 JUSTIFIED specified on edited field

Parent topic: COBCH0661 - COBCH0680


COBCH0669 EVALUATE statement using partial conditional expressions

Parent topic: COBCH0661 - COBCH0680


COBCH0670 Selection object does not correspond to selection subject

Parent topic: COBCH0661 - COBCH0680


COBCH0671 PERFORM UNTIL EXIT

Parent topic: COBCH0661 - COBCH0680


COBCH0672 COPY nested in COPY REPLACING

Parent topic: COBCH0661 - COBCH0680


COBCH0673 Incompatible options specified

Parent topic: COBCH0661 - COBCH0680


COBCH0674 Subscripting and indexing used for the same identifier

Parent topic: COBCH0661 - COBCH0680


COBCH0675 Numeric FUNCTION used as source of MOVE statement

Parent topic: COBCH0661 - COBCH0680


COBCH0676 THEN used instead of THAN

Parent topic: COBCH0661 - COBCH0680


COBCH0677 Value of previous expression may not be the same under OSVS / VSC2

The result of the arithmetic expression just evaluated under the OS/VS or VSC2 dialect could be different when evaluated on the mainframe. This warning is displayed when an intermediate result needs more than 19 digits on either side of the decimal point.
Parent topic: COBCH0661 - COBCH0680


COBCH0678 Too many CONTROLS specified for report

Parent topic: COBCH0661 - COBCH0680


COBCH0679 QUOTE character must be double in an N literal

Parent topic: COBCH0661 - COBCH0680


COBCH0680 N" format literal

Parent topic: COBCH0661 - COBCH0680


COBCH0681 - COBCH0700

Lists the Syntax Checking error messages from COBCH0681 through COBCH0700.

  • COBCH0681 Function argument must be positive
  • COBCH0682 Function argument must be positive or zero
  • COBCH0683 Function argument must be nonzero
  • COBCH0684 Function argument must be between -1 and +1
  • COBCH0685 Function argument must be greater than -1
  • COBCH0686 Function argument must be between 1 and collating sequence length
  • COBCH0687 Use of PROCEDURE-POINTER data item
  • COBCH0688 Use of "C" or "R" as currency sign
  • COBCH0689 Condition-name cannot be set to FALSE (no FALSE value specified)
    You have tried to set a level-88 item to FALSE without having specified the WHEN SET TO FALSE clause in the item's data description.
  • COBCH0690 Illegal use of floating-point literal
  • COBCH0691 Simple COPY and qualified COPY both used in the same program
    You have mixed two different copies of copylbr in the same program. You must not use COPY statements if some have qualification and some have not.
  • COBCH0692 REPORT specified in more than two FDs
  • COBCH0693 Cannot be an external item
  • COBCH0694 Identifier is reference modified
  • COBCH0695 EXTERNAL program
  • COBCH0696 Data-name must be specified with TYPEDEF
  • COBCH0697 Data item is redefinition of KEY, rather than the key itself
  • COBCH0698 Use of positive literal in AFTER ADVANCING phrase
  • COBCH0699 ADVANCING PAGE and END-OF-PAGE used in same WRITE statement
    Under ANS85, ADVANCING PAGE and END-OF-PAGE are not allowed in the same WRITE statement.
  • COBCH0700 Function argument is wrong format
    You have supplied an argument to an intrinsic function which is of the wrong format, for example INTEGER-OF-DAY requires a date of a certain format.
Parent topic: Messages COBCH0601 to COBCH0700


COBCH0681 Function argument must be positive

Parent topic: COBCH0681 - COBCH0700


COBCH0682 Function argument must be positive or zero

Parent topic: COBCH0681 - COBCH0700


COBCH0683 Function argument must be nonzero

Parent topic: COBCH0681 - COBCH0700


COBCH0684 Function argument must be between -1 and +1

Parent topic: COBCH0681 - COBCH0700


COBCH0685 Function argument must be greater than -1

Parent topic: COBCH0681 - COBCH0700


COBCH0686 Function argument must be between 1 and collating sequence length

Parent topic: COBCH0681 - COBCH0700


COBCH0687 Use of PROCEDURE-POINTER data item

Parent topic: COBCH0681 - COBCH0700


COBCH0688 Use of "C" or "R" as currency sign

Parent topic: COBCH0681 - COBCH0700


COBCH0689 Condition-name cannot be set to FALSE (no FALSE value specified)

You have tried to set a level-88 item to FALSE without having specified the WHEN SET TO FALSE clause in the item's data description.
Parent topic: COBCH0681 - COBCH0700


COBCH0690 Illegal use of floating-point literal

Parent topic: COBCH0681 - COBCH0700


COBCH0691 Simple COPY and qualified COPY both used in the same program

You have mixed two different copies of copylbr in the same program. You must not use COPY statements if some have qualification and some have not.
Parent topic: COBCH0681 - COBCH0700


COBCH0692 REPORT specified in more than two FDs

Parent topic: COBCH0681 - COBCH0700


COBCH0693 Cannot be an external item

Parent topic: COBCH0681 - COBCH0700


COBCH0694 Identifier is reference modified

Parent topic: COBCH0681 - COBCH0700


COBCH0695 EXTERNAL program

Parent topic: COBCH0681 - COBCH0700


COBCH0696 Data-name must be specified with TYPEDEF

Parent topic: COBCH0681 - COBCH0700


COBCH0697 Data item is redefinition of KEY, rather than the key itself

Parent topic: COBCH0681 - COBCH0700


COBCH0698 Use of positive literal in AFTER ADVANCING phrase

Parent topic: COBCH0681 - COBCH0700


COBCH0699 ADVANCING PAGE and END-OF-PAGE used in same WRITE statement

Under ANS85, ADVANCING PAGE and END-OF-PAGE are not allowed in the same WRITE statement.
Parent topic: COBCH0681 - COBCH0700


COBCH0700 Function argument is wrong format

You have supplied an argument to an intrinsic function which is of the wrong format, for example INTEGER-OF-DAY requires a date of a certain format.

Resolution:

Check the format of your argument against the documentation and recode.

Parent topic: COBCH0681 - COBCH0700


Messages COBCH0701 to COBCH0800

  • COBCH0701 - COBCH0720
    Lists the Syntax Checking error messages from COBCH0701 through COBCH0720.
  • COBCH0721 - COBCH0740
    Lists the Syntax Checking error messages from COBCH0721 through COBCH0740.
  • COBCH0741 - COBCH0760
    Lists the Syntax Checking error messages from COBCH0741 through COBCH0760.
  • COBCH0761 - COBCH0780
    Lists the Syntax Checking error messages from COBCH0761 through COBCH0780.
  • COBCH0781 - COBCH0800
    Lists the Syntax Checking error messages from COBCH0781 through COBCH0800.
Parent topic: Syntax Checking Error Messages


COBCH0701 - COBCH0720

Lists the Syntax Checking error messages from COBCH0701 through COBCH0720.

  • COBCH0701 Alphabet-name must be preceded by ALPHABET
  • COBCH0702 Alphabetic class expanded to include lower-case letters
  • COBCH0703 ON OVERFLOW will execute under more conditions
  • COBCH0704 Comparison between scaled integer and nonnumeric is different
    You are trying to compare a scaled integer with a numeric edited or alphanumeric item.
  • COBCH0705 ":" treated as a separator
  • COBCH0706 Non-COBOL character character found. Results might be different
    Your COBOL system has found non-COBOL characters when trying a COPY REPLACING BY operation. The results might be different on other environments.
  • COBCH0707 An implicit EXIT PROGRAM will be executed at end of program
  • COBCH0708 PICTURE consists of A's and B's. Treated as alphanumeric-edited
  • COBCH0709 Order of initialization different for PERFORM... VARYING.. . AFTER
  • COBCH0710 The maximum length of receiver receiver will be used
  • COBCH0711 RECORD CONTAINS with one integer is supported differently
  • COBCH0712 The file status values are different
    The file status values for file operations differ between environments.
  • COBCH0713 Subscripting and ODO for UNSTRING evaluated at start of statement
  • COBCH0714 Non-space characters following "." are ignored
  • COBCH0715 EXIT not followed by "."
  • COBCH0716 EXIT PROGRAM not followed by "."
  • COBCH0717 Shift out character not followed by valid DBCS character
  • COBCH0718 Shift out character not matched with shift in, or vice versa
  • COBCH0719 I-O CONTROL paragraph contains multiple sentences
  • COBCH0720 SEQUENTIAL file used as CALL parameter
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0701 Alphabet-name must be preceded by ALPHABET

Parent topic: COBCH0701 - COBCH0720


COBCH0702 Alphabetic class expanded to include lower-case letters

Parent topic: COBCH0701 - COBCH0720


COBCH0703 ON OVERFLOW will execute under more conditions

Parent topic: COBCH0701 - COBCH0720


COBCH0704 Comparison between scaled integer and nonnumeric is different

You are trying to compare a scaled integer with a numeric edited or alphanumeric item.
Parent topic: COBCH0701 - COBCH0720


COBCH0705 ":" treated as a separator

Parent topic: COBCH0701 - COBCH0720


COBCH0706 Non-COBOL character character found. Results might be different

Your COBOL system has found non-COBOL characters when trying a COPY REPLACING BY operation. The results might be different on other environments.
Parent topic: COBCH0701 - COBCH0720


COBCH0707 An implicit EXIT PROGRAM will be executed at end of program

Parent topic: COBCH0701 - COBCH0720


COBCH0708 PICTURE consists of A's and B's. Treated as alphanumeric-edited

Parent topic: COBCH0701 - COBCH0720


COBCH0709 Order of initialization different for PERFORM... VARYING.. . AFTER

Parent topic: COBCH0701 - COBCH0720


COBCH0710 The maximum length of receiver receiver will be used

Parent topic: COBCH0701 - COBCH0720


COBCH0711 RECORD CONTAINS with one integer is supported differently

Parent topic: COBCH0701 - COBCH0720


COBCH0712 The file status values are different

The file status values for file operations differ between environments.
Parent topic: COBCH0701 - COBCH0720


COBCH0713 Subscripting and ODO for UNSTRING evaluated at start of statement

Parent topic: COBCH0701 - COBCH0720


COBCH0714 Non-space characters following "." are ignored

Parent topic: COBCH0701 - COBCH0720


COBCH0715 EXIT not followed by "."

Parent topic: COBCH0701 - COBCH0720


COBCH0716 EXIT PROGRAM not followed by "."

Parent topic: COBCH0701 - COBCH0720


COBCH0717 Shift out character not followed by valid DBCS character

Parent topic: COBCH0701 - COBCH0720


COBCH0718 Shift out character not matched with shift in, or vice versa

Parent topic: COBCH0701 - COBCH0720


COBCH0719 I-O CONTROL paragraph contains multiple sentences

Parent topic: COBCH0701 - COBCH0720


COBCH0720 SEQUENTIAL file used as CALL parameter

Parent topic: COBCH0701 - COBCH0720


COBCH0721 - COBCH0740

Lists the Syntax Checking error messages from COBCH0721 through COBCH0740.

  • COBCH0721 Non-SEQUENTIAL file used as CALL parameter
  • COBCH0722 Data item too small (must be at least 16 characters long)
  • COBCH0723 USE...GIVING option
  • COBCH0724 Period follows SKIP1/ 2/ 3 or EJECT
  • COBCH0725 Function argument invalid, year must be greater than 1600
  • COBCH0726 Function argument invalid, month must be an integer between 1 and 12
  • COBCH0727 Function argument invalid, day must be an integer between 1 and 31
  • COBCH0728 Function argument invalid, day must be an integer between 1 and 366
  • COBCH0729 OO: parameter-name not specified in USING
  • COBCH0730 OO: Definition too long
  • COBCH0731 OO: Syntax matches multiple signatures of signature - first assumed
  • COBCH0732 OO: Signature signature does not match or data name data-name not declared
  • COBCH0733 OO: FUNCTION not permitted - no RETURNING/GIVING phrase specified
  • COBCH0734 OO: FUNCTION cannot use RETURNING/GIVING parameter parameter-name
  • COBCH0735 OO: Invalid verb/function signature signature
  • COBCH0736 OO: CLASS class-name not declared
  • COBCH0737 OO: Object types do not conform (type-1,type-2)
  • COBCH0738 OO: Signature must contain <SELF> or <OBJECT> exactlyonce
  • COBCH0739 OO: Signature includes IN, OF or "(" after parameter. May be ambiguous.
  • COBCH0740 OO: Sorry, too many use signatures of signature to consider
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0721 Non-SEQUENTIAL file used as CALL parameter

Parent topic: COBCH0721 - COBCH0740


COBCH0722 Data item too small (must be at least 16 characters long)

Parent topic: COBCH0721 - COBCH0740


COBCH0723 USE...GIVING option

Parent topic: COBCH0721 - COBCH0740


COBCH0724 Period follows SKIP1/ 2/ 3 or EJECT

Parent topic: COBCH0721 - COBCH0740


COBCH0725 Function argument invalid, year must be greater than 1600

Parent topic: COBCH0721 - COBCH0740


COBCH0726 Function argument invalid, month must be an integer between 1 and 12

Parent topic: COBCH0721 - COBCH0740


COBCH0727 Function argument invalid, day must be an integer between 1 and 31

Parent topic: COBCH0721 - COBCH0740


COBCH0728 Function argument invalid, day must be an integer between 1 and 366

Parent topic: COBCH0721 - COBCH0740


COBCH0729 OO: parameter-name not specified in USING

Parameters to user defined syntax must be listed in the PROCEDURE DIVISION USING clause of the program.

Parent topic: COBCH0721 - COBCH0740


COBCH0730 OO: Definition too long

The definitions of user defined syntax are restricted in size.

Resolution:

Shorten your syntax definition, for example, by omitting optional noise words.

Parent topic: COBCH0721 - COBCH0740


COBCH0731 OO: Syntax matches multiple signatures of signature - first assumed

The syntax defined in the program matches more than one user defined syntax definition. The code could be ambiguous. However, in many cases the definitions resolve to the same method. The Compiler uses the first matching definition.

Parent topic: COBCH0721 - COBCH0740


COBCH0732 OO: Signature signature does not match or data name data-name not declared

Parent topic: COBCH0721 - COBCH0740


COBCH0733 OO: FUNCTION not permitted - no RETURNING/GIVING phrase specified

User-defined syntax FUNCTIONs can only be defined for methods which have a RETURNING or GIVING phrase on the PROCEDURE DIVISION.

Parent topic: COBCH0721 - COBCH0740


COBCH0734 OO: FUNCTION cannot use RETURNING/GIVING parameter parameter-name

User-defined syntax FUNCTIONs cannot include the RETURNING/GIVING parameter as a parameter to the function.

Parent topic: COBCH0721 - COBCH0740


COBCH0735 OO: Invalid verb/function signature signature

You are trying to use a reserved word as the verb of user-defined syntax definition.

Resolution:

Choose a different verb.

Parent topic: COBCH0721 - COBCH0740


COBCH0736 OO: CLASS class-name not declared

class-name is not declared as a CLASS in the SPECIAL-NAMES paragraph of a program. It's definition might be required as a result of specified inheritance.

Resolution:

Include an appropriate CLASS statement in the SPECIAL-NAMES paragraph and resubmit.

Parent topic: COBCH0721 - COBCH0740


COBCH0737 OO: Object types do not conform (type-1,type-2)

You are trying an operation involving incompatible types of OBJECT REFERENCEs, as defined by the inheritance hierarchy. Such objects are said to be non-conforming.

Parent topic: COBCH0721 - COBCH0740


COBCH0738 OO: Signature must contain <SELF> or <OBJECT> exactlyonce

User defined syntax definitions must contain <SELF> or <OBJECT> exactly once.

Parent topic: COBCH0721 - COBCH0740


COBCH0739 OO: Signature includes IN, OF or "(" after parameter. May be ambiguous.

The use of OF or parentheses in user defined syntax definitions can lead to ambiguities in parsing which might give unexpected results. For example, parentheses following a parameter might be interpreted as subscripting.

Parent topic: COBCH0721 - COBCH0740


COBCH0740 OO: Sorry, too many use signatures of signature to consider

There is a limitation as to how many user defined syntax definitions with the same verb or function name can be considered at one time. For example, you have many definitions of the same verb.

Resolution:

Reduce the number of definitions of each verb, or shorten those definitions.

Parent topic: COBCH0721 - COBCH0740


COBCH0741 - COBCH0760

Lists the Syntax Checking error messages from COBCH0741 through COBCH0760.

  • COBCH0741 OO: Only allowed in an instance method
    You have tried to use syntax that is only permitted in an instance method.
  • COBCH0742 OO: Implicit use of SELF only allowed in a METHOD
    INVOKE statements might omit the initial object reference, and this implies an object reference of SELF. This can only be done in a METHOD, not a program.
  • COBCH0743 Expressions in SQL statements not affected by ARITHMETIC directive
    Arithmetical expressions in SQL statements are processed by the database engine and are therefore not affected by the ARITHMETIC directive.
  • COBCH0744 BY VALUE not allowed in nested programs
    You have tried to pass a parameter BY VALUE when calling a nested program.
  • COBCH0745 END DECLARATIVES missing
  • COBCH0746 WHEN OTHER must follow other WHEN phrase
  • COBCH0747 Object of SUM...UPON phrase is not a detail group for this report
  • COBCH0748 Index name set to negative value
    You have set the value of an index to a negative number. Index values must be no less than 1.
  • COBCH0749 Index name set to +0
    You have set the value of an index to 0. Index values must be no less than 1.
  • COBCH0750 Index name set to 0
    You have set the value of an index to 0. Index values must be no less than 1.
  • COBCH0751 Index name augmented by 0
  • COBCH0752 Complex arithmetic expression used as subscript
  • COBCH0753 OR phrase in INSPECT BEFORE/AFTER
    The INSPECT statement contains an OR operand after a BEFORE or AFTER phrase.
  • COBCH0754 Negative integer not allowed
  • COBCH0755 Special register used with ACCEPT/DISPLAY/EXHIBIT or CALL statement
  • COBCH0756 TYPEDEF name missing
  • COBCH0757 POINTER name required
  • COBCH0758 POINTER item has incorrect type
  • COBCH0759 Illegal use of logical operator
  • COBCH0760 INITIALIZE TO VALUE statement
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0741 OO: Only allowed in an instance method

You have tried to use syntax that is only permitted in an instance method.
Parent topic: COBCH0741 - COBCH0760


COBCH0742 OO: Implicit use of SELF only allowed in a METHOD

INVOKE statements might omit the initial object reference, and this implies an object reference of SELF. This can only be done in a METHOD, not a program.
Parent topic: COBCH0741 - COBCH0760


COBCH0743 Expressions in SQL statements not affected by ARITHMETIC directive

Arithmetical expressions in SQL statements are processed by the database engine and are therefore not affected by the ARITHMETIC directive.
Parent topic: COBCH0741 - COBCH0760


COBCH0744 BY VALUE not allowed in nested programs

You have tried to pass a parameter BY VALUE when calling a nested program.
Parent topic: COBCH0741 - COBCH0760


COBCH0745 END DECLARATIVES missing

Parent topic: COBCH0741 - COBCH0760


COBCH0746 WHEN OTHER must follow other WHEN phrase

Parent topic: COBCH0741 - COBCH0760


COBCH0747 Object of SUM...UPON phrase is not a detail group for this report

Parent topic: COBCH0741 - COBCH0760


COBCH0748 Index name set to negative value

You have set the value of an index to a negative number. Index values must be no less than 1.

Resolution:

Modify your code to specify a positive value for the index, then resubmit.

Parent topic: COBCH0741 - COBCH0760


COBCH0749 Index name set to +0

You have set the value of an index to 0. Index values must be no less than 1.

Resolution:

Modify your code to specify a positive value for the index, then resubmit.

Parent topic: COBCH0741 - COBCH0760


COBCH0750 Index name set to 0

You have set the value of an index to 0. Index values must be no less than 1.

Resolution:

Modify your code to specify a positive value for the index, then resubmit.

Parent topic: COBCH0741 - COBCH0760


COBCH0751 Index name augmented by 0

Parent topic: COBCH0741 - COBCH0760


COBCH0752 Complex arithmetic expression used as subscript

Parent topic: COBCH0741 - COBCH0760


COBCH0753 OR phrase in INSPECT BEFORE/AFTER

The INSPECT statement contains an OR operand after a BEFORE or AFTER phrase.
Parent topic: COBCH0741 - COBCH0760


COBCH0754 Negative integer not allowed

Parent topic: COBCH0741 - COBCH0760


COBCH0755 Special register used with ACCEPT/DISPLAY/EXHIBIT or CALL statement

Parent topic: COBCH0741 - COBCH0760


COBCH0756 TYPEDEF name missing

Parent topic: COBCH0741 - COBCH0760


COBCH0757 POINTER name required

Parent topic: COBCH0741 - COBCH0760


COBCH0758 POINTER item has incorrect type

Parent topic: COBCH0741 - COBCH0760


COBCH0759 Illegal use of logical operator

Parent topic: COBCH0741 - COBCH0760


COBCH0760 INITIALIZE TO VALUE statement

Parent topic: COBCH0741 - COBCH0760


COBCH0761 - COBCH0780

Lists the Syntax Checking error messages from COBCH0761 through COBCH0780.

  • COBCH0761 DELIMITED BY SIZE omitted
  • COBCH0762 Must be a typed pointer
  • COBCH0763 RETURNING phrase cannot be used on an ENTRY statement
  • COBCH0764 ENTRY statement in a program with a PROCEDURE DIVISION RETURNING phrase
  • COBCH0765 Failed to create directory %1_s
  • COBCH0766 Failed to create class file (%1_s) %2_s_
  • COBCH0767 $END-IF expected
  • COBCH0768 $END-REGION expected.
  • COBCH0769 No matching $REGION - ignored
  • COBCH0770 OO: Signature includes IN, OF or "(" after parameter.
    The use of OF, IN or parentheses in user defined syntax definitions that follow or might possibly follow a parameter are not allowed.
  • COBCH0771 OO: Required or Optional word must not be a verb.
    The use of a COBOL verb is not allowed as a user defined required, or optionaly required, word in user defined syntax definitions.
  • COBCH0772 Illegal combination of ALLOW clauses
  • COBCH0773 CLASS clause cannot be used with numeric item
  • COBCH0774 COBOL word contains 31 characters.
  • COBCH0775 Data item too small - must have at least 4 digits.
  • COBCH0776 Partial word replacement.
  • COBCH0777 Only one word allowed with partial word replacement.
  • COBCH0778 Additional messages suppressed
  • COBCH0779 The intermediate code may not be portable at the intlevel set.
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0761 DELIMITED BY SIZE omitted

Parent topic: COBCH0761 - COBCH0780


COBCH0762 Must be a typed pointer

Parent topic: COBCH0761 - COBCH0780


COBCH0763 RETURNING phrase cannot be used on an ENTRY statement

Parent topic: COBCH0761 - COBCH0780


COBCH0764 ENTRY statement in a program with a PROCEDURE DIVISION RETURNING phrase

Parent topic: COBCH0761 - COBCH0780


COBCH0765 Failed to create directory %1_s

Parent topic: COBCH0761 - COBCH0780


COBCH0766 Failed to create class file (%1_s) %2_s_

Parent topic: COBCH0761 - COBCH0780


COBCH0767 $END-IF expected

Resolution:

Parent topic: COBCH0761 - COBCH0780


COBCH0768 $END-REGION expected.

Resolution:

Parent topic: COBCH0761 - COBCH0780


COBCH0769 No matching $REGION - ignored

Resolution:

Parent topic: COBCH0761 - COBCH0780


COBCH0770 OO: Signature includes IN, OF or "(" after parameter.

The use of OF, IN or parentheses in user defined syntax definitions that follow or might possibly follow a parameter are not allowed.
Parent topic: COBCH0761 - COBCH0780


COBCH0771 OO: Required or Optional word must not be a verb.

The use of a COBOL verb is not allowed as a user defined required, or optionaly required, word in user defined syntax definitions.
Parent topic: COBCH0761 - COBCH0780


COBCH0772 Illegal combination of ALLOW clauses

Parent topic: COBCH0761 - COBCH0780


COBCH0773 CLASS clause cannot be used with numeric item

Parent topic: COBCH0761 - COBCH0780


COBCH0774 COBOL word contains 31 characters.

Parent topic: COBCH0761 - COBCH0780


COBCH0775 Data item too small - must have at least 4 digits.

Parent topic: COBCH0761 - COBCH0780


COBCH0776 Partial word replacement.

Parent topic: COBCH0761 - COBCH0780


COBCH0777 Only one word allowed with partial word replacement.

Parent topic: COBCH0761 - COBCH0780


COBCH0778 Additional messages suppressed

Parent topic: COBCH0761 - COBCH0780


COBCH0779 The intermediate code may not be portable at the intlevel set.

Resolution:

Parent topic: COBCH0761 - COBCH0780


COBCH0781 - COBCH0800

Lists the Syntax Checking error messages from COBCH0781 through COBCH0800.

  • COBCH0781 01 Group item must have the EXTERNAL-FORM clause
  • COBCH0782 Call by number routine x"%1_s" does not exist_
  • COBCH0789 Pre-compiled header %1_s is incompatible with this compiler
  • COBCH0790 OO: Invalid method name.
  • COBCH0791 Pre-compiled header header not found.
  • COBCH0792 MOVE used with pointer item.
  • COBCH0793 No PICTURE specified for elementary alphanumeric item.
  • COBCH0794 KEY specification uses SOURCE syntax.
  • COBCH0795 END PROGRAM value missing.
  • COBCH0796 SYNC would cause re-alignment of redefined group - not allowed
  • COBCH0797 Non-COBOL character character found.
  • COBCH0799 COLUMN clause requires a SOURCE/SUM/VALUE clause also.
  • COBCH0800 Bad task request from External Compiler Module
Parent topic: Messages COBCH0701 to COBCH0800


COBCH0781 01 Group item must have the EXTERNAL-FORM clause

Parent topic: COBCH0781 - COBCH0800


COBCH0782 Call by number routine x"%1_s" does not exist_

Parent topic: COBCH0781 - COBCH0800


COBCH0789 Pre-compiled header %1_s is incompatible with this compiler

Parent topic: COBCH0781 - COBCH0800


COBCH0790 OO: Invalid method name.

Parent topic: COBCH0781 - COBCH0800


COBCH0791 Pre-compiled header header not found.

Parent topic: COBCH0781 - COBCH0800


COBCH0792 MOVE used with pointer item.

Parent topic: COBCH0781 - COBCH0800


COBCH0793 No PICTURE specified for elementary alphanumeric item.

Parent topic: COBCH0781 - COBCH0800


COBCH0794 KEY specification uses SOURCE syntax.

Parent topic: COBCH0781 - COBCH0800


COBCH0795 END PROGRAM value missing.

Parent topic: COBCH0781 - COBCH0800


COBCH0796 SYNC would cause re-alignment of redefined group - not allowed

Parent topic: COBCH0781 - COBCH0800


COBCH0797 Non-COBOL character character found.

Parent topic: COBCH0781 - COBCH0800


COBCH0799 COLUMN clause requires a SOURCE/SUM/VALUE clause also.

Parent topic: COBCH0781 - COBCH0800


COBCH0800 Bad task request from External Compiler Module

Parent topic: COBCH0781 - COBCH0800


Messages COBCH0801 to COBCH0900

  • COBCH0801 - COBCH0820
    Lists the Syntax Checking error messages from COBCH0801 through COBCH0820.
  • COBCH0821 - COBCH0840
    Lists the Syntax Checking error messages from COBCH0821 through COBCH0840.
  • COBCH0841 - COBCH0860
    Lists the Syntax Checking error messages from COBCH0841 through COBCH0860.
  • COBCH0861 - COBCH0880
    Lists the Syntax Checking error messages from COBCH0861 through COBCH0880.
  • COBCH0881 - COBCH0900
    Lists the Syntax Checking error messages from COBCH0881 through COBCH0900.
Parent topic: Syntax Checking Error Messages


COBCH0801 - COBCH0820

Lists the Syntax Checking error messages from COBCH0801 through COBCH0820.

  • COBCH0801 External Compiler Module message
  • COBCH0802 Data name defined using SQL syntax too long to modify
  • COBCH0803 Integrated preprocessor message
  • COBCH0804 Source limit of integer lines exceeded
    You have exceeded the number of lines of source code permitted by your current license.
  • COBCH0805 Bad directive or option in _IF
  • COBCH0806 Too many items in CODE-SET FOR clause
  • COBCH0807 VALUE clause requires a table declaration_
  • COBCH0808 Maximum number of data items exceeded
    The compiled program contains more than 64,000 data items.
  • COBCH0809 Pseudo-text delimiter missing_
  • COBCH0810 Reserved word missing - OF expected_
  • COBCH0811 Number of WHEN phrases _ %1_s
  • COBCH0812 USAGE NATIONAL - need to compile with NSYMBOL(NATIONAL) directive_
  • COBCH0813 Feature not yet supported when compiling for _NET
  • COBCH0814 Feature not supported
  • COBCH0815 Cannot have an abstract method in a non-abstract class
  • COBCH0816 CUSTOM-ATTRIBUTE must derive from System_Attribute class
  • COBCH0817 Exception-name must derive from System_Exception class
  • COBCH0818 '%1_s' not found or is not an interface
  • COBCH0819 Interface member '%1_s' or one of its overloads not implemented or not public
  • COBCH0820 Class <class-name> not found or is not a delegate class
    A delegate type is expected, and cannot be found.
Parent topic: Messages COBCH0801 to COBCH0900


COBCH0801 External Compiler Module message

Parent topic: COBCH0801 - COBCH0820


COBCH0802 Data name defined using SQL syntax too long to modify

Parent topic: COBCH0801 - COBCH0820


COBCH0803 Integrated preprocessor message

Parent topic: COBCH0801 - COBCH0820


COBCH0804 Source limit of integer lines exceeded

You have exceeded the number of lines of source code permitted by your current license.

To remove the restriction, contact your sales representative to upgrade to a full license.

Parent topic: COBCH0801 - COBCH0820


COBCH0805 Bad directive or option in _IF

Parent topic: COBCH0801 - COBCH0820


COBCH0806 Too many items in CODE-SET FOR clause

Parent topic: COBCH0801 - COBCH0820


COBCH0807 VALUE clause requires a table declaration_

Parent topic: COBCH0801 - COBCH0820


COBCH0808 Maximum number of data items exceeded

The compiled program contains more than 64,000 data items.

Resolution:

Reduce the number of data items then recompile your program.

Parent topic: COBCH0801 - COBCH0820


COBCH0809 Pseudo-text delimiter missing_

Parent topic: COBCH0801 - COBCH0820


COBCH0810 Reserved word missing - OF expected_

Parent topic: COBCH0801 - COBCH0820


COBCH0811 Number of WHEN phrases _ %1_s

Parent topic: COBCH0801 - COBCH0820


COBCH0812 USAGE NATIONAL - need to compile with NSYMBOL(NATIONAL) directive_

Parent topic: COBCH0801 - COBCH0820


COBCH0813 Feature not yet supported when compiling for _NET

Parent topic: COBCH0801 - COBCH0820


COBCH0814 Feature not supported

Parent topic: COBCH0801 - COBCH0820


COBCH0815 Cannot have an abstract method in a non-abstract class

Parent topic: COBCH0801 - COBCH0820


COBCH0816 CUSTOM-ATTRIBUTE must derive from System_Attribute class

Parent topic: COBCH0801 - COBCH0820


COBCH0817 Exception-name must derive from System_Exception class

Parent topic: COBCH0801 - COBCH0820


COBCH0818 '%1_s' not found or is not an interface

Parent topic: COBCH0801 - COBCH0820


COBCH0819 Interface member '%1_s' or one of its overloads not implemented or not public

Parent topic: COBCH0801 - COBCH0820


COBCH0820 Class <class-name> not found or is not a delegate class

A delegate type is expected, and cannot be found.

This can occur when the delegate-invocation-expression cannot be resolved to an object of delegate type, or when the EVENT keyword is specified for a field not of delegate type.

delegate-id MessageHandler (str as string)
end delegate.
class-id DelegatesEvents.
01 MessageSnooze string EVENT STATIC.                *> this causes the error
01 MessageArrived EVENT type MessageHandler STATIC.  *> this does not
...
Parent topic: COBCH0801 - COBCH0820


COBCH0821 - COBCH0840

Lists the Syntax Checking error messages from COBCH0821 through COBCH0840.

  • COBCH0821 Not a valid iterator
  • COBCH0822 Exception-name must derive from java.lang.Throwable class
    When the program is compiled with JVMGEN, the type specified, e.g. in the catch phrase of a try/catch block, must derive from the class java.lang.Throwable.
  • COBCH0824 RAISE must specify exception object when not in CATCH block
  • COBCH0825 Cannot inherit from FINAL class '%1_s'
  • COBCH0826 Illegal parameter to delegate constructor
  • COBCH0827 Method has different signature from delegate
  • COBCH0828 Illegal cast or test - object types do not conform (%1_s, %2_s)
  • COBCH0829 Could not find method new with this signature
  • COBCH0830 Attribute class does not have constructor with this signature
  • COBCH0831 Illegal specification of named parameter
  • COBCH0832 Attribute class does not have property '%1_s'
  • COBCH0833 Invalid value for property '%1_s'
  • COBCH0834 Property can not be a sending item
  • COBCH0835 Property cannot be a receiving item
  • COBCH0836 Method in interface definition must be public
  • COBCH0837 Procedural code not allowed here
  • COBCH0838 System limit - Data Division too large _ 256Mbytes_
  • COBCH0839 System limit - Procedure Division or segment too large_ _ 16Mbytes_
    The limit of a segment in the procedure division has been exceeded.
  • COBCH0840 RETURNING item is incompatible with method return type
Parent topic: Messages COBCH0801 to COBCH0900


COBCH0821 Not a valid iterator

Parent topic: COBCH0821 - COBCH0840


COBCH0822 Exception-name must derive from java.lang.Throwable class

When the program is compiled with JVMGEN, the type specified, e.g. in the catch phrase of a try/catch block, must derive from the class java.lang.Throwable.

Resolution:

Edit the code to ensure that the type is derived from java.lang.Throwable; then recompile.

Example:

In the following example, the type is derived from java.lang.String. You must change the type to java.lang.Throwable.

       class-id a.
       method-id main static.
           try
               display "Hello"
           catch e as type java.lang.String
               display "In catch block"
           end-try
       end method.
       end class.
Parent topic: COBCH0821 - COBCH0840


COBCH0824 RAISE must specify exception object when not in CATCH block

Parent topic: COBCH0821 - COBCH0840


COBCH0825 Cannot inherit from FINAL class '%1_s'

Parent topic: COBCH0821 - COBCH0840


COBCH0826 Illegal parameter to delegate constructor

Parent topic: COBCH0821 - COBCH0840


COBCH0827 Method has different signature from delegate

Parent topic: COBCH0821 - COBCH0840


COBCH0828 Illegal cast or test - object types do not conform (%1_s, %2_s)

Parent topic: COBCH0821 - COBCH0840


COBCH0829 Could not find method new with this signature

Parent topic: COBCH0821 - COBCH0840


COBCH0830 Attribute class does not have constructor with this signature

Parent topic: COBCH0821 - COBCH0840


COBCH0831 Illegal specification of named parameter

Parent topic: COBCH0821 - COBCH0840


COBCH0832 Attribute class does not have property '%1_s'

Parent topic: COBCH0821 - COBCH0840


COBCH0833 Invalid value for property '%1_s'

Parent topic: COBCH0821 - COBCH0840


COBCH0834 Property can not be a sending item

Parent topic: COBCH0821 - COBCH0840


COBCH0835 Property cannot be a receiving item

Parent topic: COBCH0821 - COBCH0840


COBCH0836 Method in interface definition must be public

Parent topic: COBCH0821 - COBCH0840


COBCH0837 Procedural code not allowed here

Parent topic: COBCH0821 - COBCH0840


COBCH0838 System limit - Data Division too large _ 256Mbytes_

Parent topic: COBCH0821 - COBCH0840


COBCH0839 System limit - Procedure Division or segment too large_ _ 16Mbytes_

The limit of a segment in the procedure division has been exceeded.

Each segment in the procedure division has a limit of 16MB.

Parent topic: COBCH0821 - COBCH0840


COBCH0840 RETURNING item is incompatible with method return type

Parent topic: COBCH0821 - COBCH0840


COBCH0841 - COBCH0860

Lists the Syntax Checking error messages from COBCH0841 through COBCH0860.

  • COBCH0841 RETURNING item requires implicit cast
  • COBCH0842 Method <method-name> has multiple definitions with same signature
    A method is defined more than once with the same signature. This isn't allowed as it would lead to ambiguity when the method was invoked.
  • COBCH0843 SET PROPERTY must have USING parameter and no RETURNING
  • COBCH0844 GET PROPERTY must have a RETURNING parameter
  • COBCH0845 Unknown class "class-name"
  • COBCH0846 Invalid use of ANY LENGTH clause
    An invalid declaration of the ANY LENGTH clause has been made.
  • COBCH0847 OBJECT REFERENCE can only have OCCURS at 01 level
  • COBCH0848 Can only be used on native data item with OCCURS at 01 level
  • COBCH0849 Too many types specified for generic class
  • COBCH0850 Too many constraints specified for generic type
  • COBCH0851 Methods cannot be nested - END METHOD missing
  • COBCH0852 System error - unexpected error while generating IL code
  • COBCH0853 System error - evaluation stack mismatch
  • COBCH0854 System error - evaluation stack negative
  • COBCH0855 System error - evaluation stack exceeded limit
  • COBCH0856 System error - evaluation stack non-empty
  • COBCH0857 System error - failure during ILASM phase
  • COBCH0859 System error - peverify has determined that this program is not verifiable
  • COBCH0858 No static method found - cannot be a main program
  • COBCH0860 Object references must be specified at 01 level
Parent topic: Messages COBCH0801 to COBCH0900


COBCH0841 RETURNING item requires implicit cast

Parent topic: COBCH0841 - COBCH0860


COBCH0842 Method <method-name> has multiple definitions with same signature

A method is defined more than once with the same signature. This isn't allowed as it would lead to ambiguity when the method was invoked.

Resolution:

Change the method signature.

Parent topic: COBCH0841 - COBCH0860


COBCH0843 SET PROPERTY must have USING parameter and no RETURNING

Parent topic: COBCH0841 - COBCH0860


COBCH0844 GET PROPERTY must have a RETURNING parameter

Parent topic: COBCH0841 - COBCH0860


COBCH0845 Unknown class "class-name"

These are the possible causes for this problem:

  1. The class name might be misspelled.
  2. The class is included in the referenced assemblies, but its namespace is not imported in your project.
  3. The class is not included in the referenced assemblies.

Resolution:

  1. Ensure you are spelling the class name correctly.
Parent topic: COBCH0841 - COBCH0860


COBCH0846 Invalid use of ANY LENGTH clause

An invalid declaration of the ANY LENGTH clause has been made.

Refer to the syntax rules as defined in The ANY LENGTH Clause and correct the declaration.

Parent topic: COBCH0841 - COBCH0860
Related reference
The ANY LENGTH Clause


COBCH0847 OBJECT REFERENCE can only have OCCURS at 01 level

Parent topic: COBCH0841 - COBCH0860


COBCH0848 Can only be used on native data item with OCCURS at 01 level

Parent topic: COBCH0841 - COBCH0860


COBCH0849 Too many types specified for generic class

Parent topic: COBCH0841 - COBCH0860


COBCH0850 Too many constraints specified for generic type

Parent topic: COBCH0841 - COBCH0860


COBCH0851 Methods cannot be nested - END METHOD missing

Parent topic: COBCH0841 - COBCH0860


COBCH0852 System error - unexpected error while generating IL code

Parent topic: COBCH0841 - COBCH0860


COBCH0853 System error - evaluation stack mismatch

Parent topic: COBCH0841 - COBCH0860


COBCH0854 System error - evaluation stack negative

Parent topic: COBCH0841 - COBCH0860


COBCH0855 System error - evaluation stack exceeded limit

Parent topic: COBCH0841 - COBCH0860


COBCH0856 System error - evaluation stack non-empty

Parent topic: COBCH0841 - COBCH0860


COBCH0857 System error - failure during ILASM phase

Parent topic: COBCH0841 - COBCH0860


COBCH0859 System error - peverify has determined that this program is not verifiable

Parent topic: COBCH0841 - COBCH0860


COBCH0858 No static method found - cannot be a main program

Note: The following applies to .NET COBOL only.

The startup object for your project is specified incorrectly or the main program in the project does not contain a static method.

Resolution:

Do not use the Startup object in the Application properties page to set the main program. The startup object must be the first static method in a class specified using the ILMAIN directive.

Parent topic: COBCH0841 - COBCH0860


COBCH0860 Object references must be specified at 01 level

Parent topic: COBCH0841 - COBCH0860


COBCH0861 - COBCH0880

Lists the Syntax Checking error messages from COBCH0861 through COBCH0880.

  • COBCH0861 Object references must not be redefined
  • COBCH0862 Object references must not have REDEFINES clause
  • COBCH0863 Operand must be an ENUM
  • COBCH0864 All operands in an ENUM expression must be of the same type
  • COBCH0865 Failed to find system program '%1_s'
  • COBCH0866 Illegal combination of visibility attributes
  • COBCH0867 Cannot jump out of a FINALLY block
  • COBCH0868 Inherited class '%1_s' not found
  • COBCH0869 Cannot create an instance of abstract class '%1_s'
  • COBCH0870 ABSTRACT method cannot be PRIVATE
  • COBCH0871 ABSTRACT class or method cannot be FINAL
  • COBCH0872 ABSTRACT method cannot be static
  • COBCH0873 Program or method name missing
  • COBCH0874 Interface methods cannot be FINAL
  • COBCH0875 Property '%1_s' not implemented or not public
  • COBCH0876 Only one field may be declared in ENUM
  • COBCH0877 ENUM field must be a numeric field of native _NET type
  • COBCH0878 ENUM literal must a numeric integer
  • COBCH0879 ENUM literals must follow ENUM field
  • COBCH0880 VALUETYPE programs cannot inherit
Parent topic: Messages COBCH0801 to COBCH0900


COBCH0861 Object references must not be redefined

Parent topic: COBCH0861 - COBCH0880


COBCH0862 Object references must not have REDEFINES clause

Parent topic: COBCH0861 - COBCH0880


COBCH0863 Operand must be an ENUM

Parent topic: COBCH0861 - COBCH0880


COBCH0864 All operands in an ENUM expression must be of the same type

Parent topic: COBCH0861 - COBCH0880


COBCH0865 Failed to find system program '%1_s'

Parent topic: COBCH0861 - COBCH0880


COBCH0866 Illegal combination of visibility attributes

Parent topic: COBCH0861 - COBCH0880


COBCH0867 Cannot jump out of a FINALLY block

Parent topic: COBCH0861 - COBCH0880


COBCH0868 Inherited class '%1_s' not found

Parent topic: COBCH0861 - COBCH0880


COBCH0869 Cannot create an instance of abstract class '%1_s'

Parent topic: COBCH0861 - COBCH0880


COBCH0870 ABSTRACT method cannot be PRIVATE

Parent topic: COBCH0861 - COBCH0880


COBCH0871 ABSTRACT class or method cannot be FINAL

Parent topic: COBCH0861 - COBCH0880


COBCH0872 ABSTRACT method cannot be static

Parent topic: COBCH0861 - COBCH0880


COBCH0873 Program or method name missing

Parent topic: COBCH0861 - COBCH0880


COBCH0874 Interface methods cannot be FINAL

Parent topic: COBCH0861 - COBCH0880


COBCH0875 Property '%1_s' not implemented or not public

Parent topic: COBCH0861 - COBCH0880


COBCH0876 Only one field may be declared in ENUM

Parent topic: COBCH0861 - COBCH0880


COBCH0877 ENUM field must be a numeric field of native _NET type

Parent topic: COBCH0861 - COBCH0880


COBCH0878 ENUM literal must a numeric integer

Parent topic: COBCH0861 - COBCH0880


COBCH0879 ENUM literals must follow ENUM field

Parent topic: COBCH0861 - COBCH0880


COBCH0880 VALUETYPE programs cannot inherit

Parent topic: COBCH0861 - COBCH0880


COBCH0881 - COBCH0900

Lists the Syntax Checking error messages from COBCH0881 through COBCH0900.

  • COBCH0881 OCCURS format can only be used with native _NET types at 01 level
  • COBCH0882 Only one visibility attribute allowed
  • COBCH0883 Attribute repeated
  • COBCH0884 Cannot use ADDRESS OF operator on _NET native type
  • COBCH0885 Visibility attributes can only be used with native _NET types at 01 level
  • COBCH0886 EVENT can only be specified with objects of delegate type
  • COBCH0887 Class class-name has multiple definitions
    A class is defined more than once with the same name. This isn't allowed.
  • COBCH0888 Illegal comparison for this type
  • COBCH0889 Illegal operator
  • COBCH0890 Operator already defined
  • COBCH0891 '_' operator is defined without matching '__' operator
  • COBCH0892 '__' operator is defined without matching '_' operator
  • COBCH0893 '_' operator is defined without matching '_' operator
  • COBCH0894 '_' operator is defined without matching '_' operator
  • COBCH0895 '__' operator is defined without matching '__' operator
  • COBCH0896 '__' operator is defined without matching '__' operator
  • COBCH0897 Cannot specify reference modification on an object reference
  • COBCH0898 Ambiguous match for method '%1_s' with this signature
  • COBCH0899 Class constructors cannot have parameters
  • COBCH0900 Internal error - Stack overflow_ Inform Technical Support_
Parent topic: Messages COBCH0801 to COBCH0900


COBCH0881 OCCURS format can only be used with native _NET types at 01 level

Parent topic: COBCH0881 - COBCH0900


COBCH0882 Only one visibility attribute allowed

Parent topic: COBCH0881 - COBCH0900


COBCH0883 Attribute repeated

Parent topic: COBCH0881 - COBCH0900


COBCH0884 Cannot use ADDRESS OF operator on _NET native type

Parent topic: COBCH0881 - COBCH0900


COBCH0885 Visibility attributes can only be used with native _NET types at 01 level

Parent topic: COBCH0881 - COBCH0900


COBCH0886 EVENT can only be specified with objects of delegate type

Parent topic: COBCH0881 - COBCH0900


COBCH0887 Class class-name has multiple definitions

A class is defined more than once with the same name. This isn't allowed.

Parent topic: COBCH0881 - COBCH0900


COBCH0888 Illegal comparison for this type

Parent topic: COBCH0881 - COBCH0900


COBCH0889 Illegal operator

Parent topic: COBCH0881 - COBCH0900


COBCH0890 Operator already defined

Parent topic: COBCH0881 - COBCH0900


COBCH0891 '_' operator is defined without matching '__' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0892 '__' operator is defined without matching '_' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0893 '_' operator is defined without matching '_' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0894 '_' operator is defined without matching '_' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0895 '__' operator is defined without matching '__' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0896 '__' operator is defined without matching '__' operator

Parent topic: COBCH0881 - COBCH0900


COBCH0897 Cannot specify reference modification on an object reference

Parent topic: COBCH0881 - COBCH0900


COBCH0898 Ambiguous match for method '%1_s' with this signature

Parent topic: COBCH0881 - COBCH0900


COBCH0899 Class constructors cannot have parameters

Parent topic: COBCH0881 - COBCH0900


COBCH0900 Internal error - Stack overflow_ Inform Technical Support_

Parent topic: COBCH0881 - COBCH0900


Messages COBCH0901 to COBCH1000

  • COBCH0901 - COBCH0920
    Lists the Syntax Checking error messages from COBCH0901 through COBCH0920.
  • COBCH0921 - COBCH0940
    Lists the Syntax Checking error messages from COBCH0921 through COBCH0940.
  • COBCH0941 - COBCH0960
    Lists the Syntax Checking error messages from COBCH0941 through COBCH0960.
  • COBCH0961 - COBCH0980
    Lists the Syntax Checking error messages from COBCH0961 through COBCH0980.
  • COBCH0981 - COBCH1000
    Lists the Syntax Checking error messages from COBCH0981 through COBCH1000.
Parent topic: Syntax Checking Error Messages


COBCH0901 - COBCH0920

Lists the Syntax Checking error messages from COBCH0901 through COBCH0920.

  • COBCH0901 Internal error - Enlarge Memory overflow_ Inform Technical Support_
  • COBCH0902 Internal error - Restore String invalid_ Inform Technical Support_
  • COBCH0903 Internal error - Dictionary corruption_ Inform Technical Support_
  • COBCH0904 Internal error - Stack underflow_ Inform Technical Support_
  • COBCH0905 Internal error - Invalid tree node_ Inform Technical Support_
  • COBCH0906 Internal error - Subscript count overflow_ Inform Technical Support_
  • COBCH0907 Internal error - Debug info buffer overflow_ Inform Technical Support_
  • COBCH0908 Internal error - Verb processing error_ Inform Technical Support_
  • COBCH0909 Internal error - Bad numeric descriptor_ Inform Technical Support_
  • COBCH0910 Internal error - Int code buffer overflow_ Inform Technical Support_
  • COBCH0911 Internal error - Dictionary heap failure %1_s Inform Technical Support_
  • COBCH0912 Internal error - Dictionary invalid r_w %1_s Inform Technical Support_
  • COBCH0913 Internal error - Dictionary open_close failure_ Inform Technical Support_
  • COBCH0914 Internal error - Dictionary literal size error_ Inform Technical Support_
  • COBCH0915 Internal error - Error during repository processing_ Inform Technical Support_
  • COBCH0916 Internal error - Error opening cdi2 handle_
  • COBCH0917 Internal error - CTF failed_
  • COBCH0918 Unknown attribute '%1_s'
  • COBCH0919 An AS expression cannot be used as a receiving item
  • COBCH0920 Can only INVOKE a method or a constructor
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0901 Internal error - Enlarge Memory overflow_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0902 Internal error - Restore String invalid_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0903 Internal error - Dictionary corruption_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0904 Internal error - Stack underflow_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0905 Internal error - Invalid tree node_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0906 Internal error - Subscript count overflow_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0907 Internal error - Debug info buffer overflow_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0908 Internal error - Verb processing error_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0909 Internal error - Bad numeric descriptor_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0910 Internal error - Int code buffer overflow_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0911 Internal error - Dictionary heap failure %1_s Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0912 Internal error - Dictionary invalid r_w %1_s Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0913 Internal error - Dictionary open_close failure_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0914 Internal error - Dictionary literal size error_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0915 Internal error - Error during repository processing_ Inform Technical Support_

Parent topic: COBCH0901 - COBCH0920


COBCH0916 Internal error - Error opening cdi2 handle_

Parent topic: COBCH0901 - COBCH0920


COBCH0917 Internal error - CTF failed_

Parent topic: COBCH0901 - COBCH0920


COBCH0918 Unknown attribute '%1_s'

Parent topic: COBCH0901 - COBCH0920


COBCH0919 An AS expression cannot be used as a receiving item

Parent topic: COBCH0901 - COBCH0920


COBCH0920 Can only INVOKE a method or a constructor

Parent topic: COBCH0901 - COBCH0920


COBCH0921 - COBCH0940

Lists the Syntax Checking error messages from COBCH0921 through COBCH0940.

  • COBCH0921 Comparison operator must return a condition-value
  • COBCH0922 Comparison operator must have two parameters that belong to current class
  • COBCH0923 Conversion operator must have one parameter and one return type
  • COBCH0924 Either the parameter or the return type must belong to current class
  • COBCH0925 Referenced non-managed module '%1_s' not found
  • COBCH0926 Array initializer has non-uniform structure_
  • COBCH0927 Table dimensions are different from original declaration_
  • COBCH0928 Must be interface implemented by current class_
  • COBCH0929 Operator must have one parameters
  • COBCH0930 Operator must have two parameters
  • COBCH0931 Operator must have one or two parameters
  • COBCH0932 At least one parameter must be of current class
  • COBCH0933 Operator is not defined for operands of this type
  • COBCH0934 Only native _NET types are allowed in Valuetype instances
  • COBCH0935 Operator parameters must be passed BY VALUE
  • COBCH0936 Number of operands does not match dimensions of table
  • COBCH0937 CUSTOM-ATTRIBUTE %1_s not allowed in this context
  • COBCH0938 Only native _NET types are allowed to have custom attributes
  • COBCH0939 CUSTOM-ATTRIBUTE %1_s is only allowed once
  • COBCH0940 PROPERTY and EVENT must be specified before CUSTOM-ATTRIBUTE
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0921 Comparison operator must return a condition-value

Parent topic: COBCH0921 - COBCH0940


COBCH0922 Comparison operator must have two parameters that belong to current class

Parent topic: COBCH0921 - COBCH0940


COBCH0923 Conversion operator must have one parameter and one return type

Parent topic: COBCH0921 - COBCH0940


COBCH0924 Either the parameter or the return type must belong to current class

Parent topic: COBCH0921 - COBCH0940


COBCH0925 Referenced non-managed module '%1_s' not found

Parent topic: COBCH0921 - COBCH0940


COBCH0926 Array initializer has non-uniform structure_

Parent topic: COBCH0921 - COBCH0940


COBCH0927 Table dimensions are different from original declaration_

Parent topic: COBCH0921 - COBCH0940


COBCH0928 Must be interface implemented by current class_

Parent topic: COBCH0921 - COBCH0940


COBCH0929 Operator must have one parameters

Parent topic: COBCH0921 - COBCH0940


COBCH0930 Operator must have two parameters

Parent topic: COBCH0921 - COBCH0940


COBCH0931 Operator must have one or two parameters

Parent topic: COBCH0921 - COBCH0940


COBCH0932 At least one parameter must be of current class

Parent topic: COBCH0921 - COBCH0940


COBCH0933 Operator is not defined for operands of this type

Parent topic: COBCH0921 - COBCH0940


COBCH0934 Only native _NET types are allowed in Valuetype instances

Parent topic: COBCH0921 - COBCH0940


COBCH0935 Operator parameters must be passed BY VALUE

Parent topic: COBCH0921 - COBCH0940


COBCH0936 Number of operands does not match dimensions of table

Parent topic: COBCH0921 - COBCH0940


COBCH0937 CUSTOM-ATTRIBUTE %1_s not allowed in this context

Parent topic: COBCH0921 - COBCH0940


COBCH0938 Only native _NET types are allowed to have custom attributes

Parent topic: COBCH0921 - COBCH0940


COBCH0939 CUSTOM-ATTRIBUTE %1_s is only allowed once

Parent topic: COBCH0921 - COBCH0940


COBCH0940 PROPERTY and EVENT must be specified before CUSTOM-ATTRIBUTE

Parent topic: COBCH0921 - COBCH0940


COBCH0941 - COBCH0960

Lists the Syntax Checking error messages from COBCH0941 through COBCH0960.

  • COBCH0941 Source file %1_s not found
  • COBCH0942 Could not load assembly '%1_s'
  • COBCH0943 %1_s is not the name of a generic parameter
  • COBCH0944 Generic class '%1_s' has wrong number of type arguments
  • COBCH0945 One or more of the type arguments for '%1_s' violates constraints
  • COBCH0946 Class, method, property or field is marked as obsolete
  • COBCH0947 ANY LENGTH item cannot be RETURNING item when compiling for _NET
  • COBCH0948 Invalid type name
  • COBCH0949 Cannot use PROPERTY on an item that is subject to an OCCURS clause
  • COBCH0950 Too many generic arguments
  • COBCH0951 System limit - number of multiple inheritance _ 10_
  • COBCH0952 Method '%1_s' must have the REDEFINE clause_
  • COBCH0953 Method '%1_s' must have the OVERRIDE or REDEFINE clause_
  • COBCH0954 Method '%1_s' cannot OVERRIDE a non-virtual method in inherited class_
  • COBCH0955 Method '%1_s' cannot OVERRIDE a FINAL method in inherited class_
  • COBCH0956 Method '%1_s' not found in inherited class - must not have the OVERRIDE or REDEFINE clause_
  • COBCH0957 Explicit interface implementations cannot have visibility attributes_
  • COBCH0958 Property '%1_s' has multiple definitions
  • COBCH0959 Invalid _line directive_
  • COBCH0960 Too many _line directives_
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0941 Source file %1_s not found

Parent topic: COBCH0941 - COBCH0960


COBCH0942 Could not load assembly '%1_s'

Parent topic: COBCH0941 - COBCH0960


COBCH0943 %1_s is not the name of a generic parameter

Parent topic: COBCH0941 - COBCH0960


COBCH0944 Generic class '%1_s' has wrong number of type arguments

Parent topic: COBCH0941 - COBCH0960


COBCH0945 One or more of the type arguments for '%1_s' violates constraints

Parent topic: COBCH0941 - COBCH0960


COBCH0946 Class, method, property or field is marked as obsolete

Parent topic: COBCH0941 - COBCH0960


COBCH0947 ANY LENGTH item cannot be RETURNING item when compiling for _NET

Parent topic: COBCH0941 - COBCH0960


COBCH0948 Invalid type name

Parent topic: COBCH0941 - COBCH0960


COBCH0949 Cannot use PROPERTY on an item that is subject to an OCCURS clause

Parent topic: COBCH0941 - COBCH0960


COBCH0950 Too many generic arguments

Parent topic: COBCH0941 - COBCH0960


COBCH0951 System limit - number of multiple inheritance _ 10_

Parent topic: COBCH0941 - COBCH0960


COBCH0952 Method '%1_s' must have the REDEFINE clause_

Parent topic: COBCH0941 - COBCH0960


COBCH0953 Method '%1_s' must have the OVERRIDE or REDEFINE clause_

Parent topic: COBCH0941 - COBCH0960


COBCH0954 Method '%1_s' cannot OVERRIDE a non-virtual method in inherited class_

Parent topic: COBCH0941 - COBCH0960


COBCH0955 Method '%1_s' cannot OVERRIDE a FINAL method in inherited class_

Parent topic: COBCH0941 - COBCH0960


COBCH0956 Method '%1_s' not found in inherited class - must not have the OVERRIDE or REDEFINE clause_

Parent topic: COBCH0941 - COBCH0960


COBCH0957 Explicit interface implementations cannot have visibility attributes_

Parent topic: COBCH0941 - COBCH0960


COBCH0958 Property '%1_s' has multiple definitions

Parent topic: COBCH0941 - COBCH0960


COBCH0959 Invalid _line directive_

Parent topic: COBCH0941 - COBCH0960


COBCH0960 Too many _line directives_

Parent topic: COBCH0941 - COBCH0960


COBCH0961 - COBCH0980

Lists the Syntax Checking error messages from COBCH0961 through COBCH0980.

  • COBCH0961 Overriding method '%1_s' must have visibility 'PRIVATE'_
  • COBCH0962 Overriding method '%1_s' must have visibility 'INTERNAL'_
  • COBCH0963 Overriding method '%1_s' must have visibility 'PROTECTED'_
  • COBCH0964 Overriding method '%1_s' must have visibility 'PROTECTED INTERNAL'_
  • COBCH0965 Overriding method '%1_s' must have visibility 'PUBLIC'_
  • COBCH0966 Either all or no dimensions must be specified using ANY_
  • COBCH0967 Class '%1_s' inherits from itself (directly or indirectly)_
  • COBCH0968 Collection element has incompatible type
  • COBCH0969 Cannot access object data from a static method
  • COBCH0970 Class '%1_s' inherits from more than one base class
  • COBCH0971 EXTERNAL not allowed with instance data
  • COBCH0972 Linkage item data-item-1 (or subordinate item) is referenced but has no addressability
  • COBCH0973 Must specify at least one CATCH or FINALLY clause_
  • COBCH0974 Inherited class does not have a default constructor_
  • COBCH0975 An anonymous method can only be used as a parameter to a delegate constructor_
  • COBCH0976 SET CONTENT syntax cannot be used with jagged arrays_
  • COBCH0977 Anonymous method signature does not match that of delegate_
  • COBCH0978 Anonymous method returning item does not match that of delegate_
  • COBCH0979 Anonymous method parameter must be new item specified with AS clause_
  • COBCH0980 YIELDING phrase can only be used in the context of an iterator_
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0961 Overriding method '%1_s' must have visibility 'PRIVATE'_

Parent topic: COBCH0961 - COBCH0980


COBCH0962 Overriding method '%1_s' must have visibility 'INTERNAL'_

Parent topic: COBCH0961 - COBCH0980


COBCH0963 Overriding method '%1_s' must have visibility 'PROTECTED'_

Parent topic: COBCH0961 - COBCH0980


COBCH0964 Overriding method '%1_s' must have visibility 'PROTECTED INTERNAL'_

Parent topic: COBCH0961 - COBCH0980


COBCH0965 Overriding method '%1_s' must have visibility 'PUBLIC'_

Parent topic: COBCH0961 - COBCH0980


COBCH0966 Either all or no dimensions must be specified using ANY_

Parent topic: COBCH0961 - COBCH0980


COBCH0967 Class '%1_s' inherits from itself (directly or indirectly)_

Parent topic: COBCH0961 - COBCH0980


COBCH0968 Collection element has incompatible type

Parent topic: COBCH0961 - COBCH0980


COBCH0969 Cannot access object data from a static method

Parent topic: COBCH0961 - COBCH0980


COBCH0970 Class '%1_s' inherits from more than one base class

Parent topic: COBCH0961 - COBCH0980


COBCH0971 EXTERNAL not allowed with instance data

Parent topic: COBCH0961 - COBCH0980


COBCH0972 Linkage item data-item-1 (or subordinate item) is referenced but has no addressability

An item in the LINKAGE SECTION has been referenced in the source code, but has no addressability.

A linkage item has to be given addressability before it is referenced, either by a SET statement or by being passed as a parameter. If the code flow at run time is such that addressability has not been assigned, then you receive this error at run time.

Additionally, if the program does not contains any possible way for addressability to be given to that item (such as the item is not a parameter, or not referenced in a SET statement at all) then, the Compiler already has the information at compile time that whatever the code flow is, the item will not be assigned.

Parent topic: COBCH0961 - COBCH0980


COBCH0973 Must specify at least one CATCH or FINALLY clause_

Parent topic: COBCH0961 - COBCH0980


COBCH0974 Inherited class does not have a default constructor_

Parent topic: COBCH0961 - COBCH0980


COBCH0975 An anonymous method can only be used as a parameter to a delegate constructor_

Parent topic: COBCH0961 - COBCH0980


COBCH0976 SET CONTENT syntax cannot be used with jagged arrays_

Parent topic: COBCH0961 - COBCH0980


COBCH0977 Anonymous method signature does not match that of delegate_

Parent topic: COBCH0961 - COBCH0980


COBCH0978 Anonymous method returning item does not match that of delegate_

Parent topic: COBCH0961 - COBCH0980


COBCH0979 Anonymous method parameter must be new item specified with AS clause_

Parent topic: COBCH0961 - COBCH0980


COBCH0980 YIELDING phrase can only be used in the context of an iterator_

Parent topic: COBCH0961 - COBCH0980


COBCH0981 - COBCH1000

Lists the Syntax Checking error messages from COBCH0981 through COBCH1000.

  • COBCH0981 YIELDING phrase must be used in the context of an iterator_
  • COBCH0982 Statement can only be used in the context of an iterator_
  • COBCH0983 Cannot initialize MicroFocus_COBOL_Compiler_dll_
  • COBCH0984 Could not find suitable '%1_s' method_
  • COBCH0985 Attribute class has multiple constructors with equally valid signature
  • COBCH0986 A method invoke cannot be a receiving item
  • COBCH0987 Could not find method '%1_s' with this signature - will generate dynamic call
  • COBCH0988 Operand must be Boolean
  • COBCH0989 GROUP-USAGE must be NATIONAL or BIT
  • COBCH0990 No period following EXEC SQL INCLUDE END-EXEC_ DB2 coprocessor will fail
  • COBCH0991 A readonly field cannot be a receiving item
  • COBCH0992 Program requires setting of INTLEVEL(4)
  • COBCH0993 Number of parameters in CALL (%1_s) different from number in target method (%2_s)
  • COBCH0994 Illegal function argument
  • COBCH0995 Iterator parameters must be passed BY VALUE
  • COBCH0996 A class can only be PUBLIC or INTERNAL
  • COBCH0997 Feature not yet supported when compiling for _NET - statement ignored
  • COBCH0998 Can only be PUBLIC or INTERNAL
  • COBCH0999 PROFILE directive ignored for nested programs
  • COBCH1000 Open fail _ %1_s
Parent topic: Messages COBCH0901 to COBCH1000


COBCH0981 YIELDING phrase must be used in the context of an iterator_

Parent topic: COBCH0981 - COBCH1000


COBCH0982 Statement can only be used in the context of an iterator_

Parent topic: COBCH0981 - COBCH1000


COBCH0983 Cannot initialize MicroFocus_COBOL_Compiler_dll_

Parent topic: COBCH0981 - COBCH1000


COBCH0984 Could not find suitable '%1_s' method_

Parent topic: COBCH0981 - COBCH1000


COBCH0985 Attribute class has multiple constructors with equally valid signature

Parent topic: COBCH0981 - COBCH1000


COBCH0986 A method invoke cannot be a receiving item

Parent topic: COBCH0981 - COBCH1000


COBCH0987 Could not find method '%1_s' with this signature - will generate dynamic call

Parent topic: COBCH0981 - COBCH1000


COBCH0988 Operand must be Boolean

Parent topic: COBCH0981 - COBCH1000


COBCH0989 GROUP-USAGE must be NATIONAL or BIT

Parent topic: COBCH0981 - COBCH1000


COBCH0990 No period following EXEC SQL INCLUDE END-EXEC_ DB2 coprocessor will fail

Parent topic: COBCH0981 - COBCH1000


COBCH0991 A readonly field cannot be a receiving item

Parent topic: COBCH0981 - COBCH1000


COBCH0992 Program requires setting of INTLEVEL(4)

Resolution:

Parent topic: COBCH0981 - COBCH1000


COBCH0993 Number of parameters in CALL (%1_s) different from number in target method (%2_s)

Parent topic: COBCH0981 - COBCH1000


COBCH0994 Illegal function argument

Parent topic: COBCH0981 - COBCH1000


COBCH0995 Iterator parameters must be passed BY VALUE

Parent topic: COBCH0981 - COBCH1000


COBCH0996 A class can only be PUBLIC or INTERNAL

Parent topic: COBCH0981 - COBCH1000


COBCH0997 Feature not yet supported when compiling for _NET - statement ignored

Parent topic: COBCH0981 - COBCH1000


COBCH0998 Can only be PUBLIC or INTERNAL

Parent topic: COBCH0981 - COBCH1000


COBCH0999 PROFILE directive ignored for nested programs

Parent topic: COBCH0981 - COBCH1000


COBCH1000 Open fail _ %1_s

Parent topic: COBCH0981 - COBCH1000


Messages COBCH1001 to COBCH1100

  • COBCH1001 - COBCH1020
    Lists the Syntax Checking error messages from COBCH1001 through COBCH1020.
  • COBCH1021 - COBCH1040
    Lists the Syntax Checking error messages from COBCH1021 through COBCH1040.
  • COBCH1041 - COBCH1060
    Lists the Syntax Checking error messages from COBCH1041 through COBCH1060.
  • COBCH1061 - COBCH1080
    Lists the Syntax Checking error messages from COBCH1061 through COBCH1080.
  • COBCH1081 - COBCH1100
    Lists the Syntax Checking error messages from COBCH1081 through COBCH1100.
Parent topic: Syntax Checking Error Messages


COBCH1001 - COBCH1020

Lists the Syntax Checking error messages from COBCH1001 through COBCH1020.

  • COBCH1001 Character other than *, D, /, -, or $ found in column 7. Blank assumed
    You might have mistyped one of the characters allowed in column 7. Your COBOL system cannot interpret the character in column 7, and has treated it as a space.
  • COBCH1002 Continuation character invalid at this point. Blank assumed
    You have placed a hyphen in column 7, though your COBOL system is not expecting the syntax to be continued at this point. The continuation character is ignored.
  • COBCH1003 First character of a continued literal not a quote. Quote assumed
    You have included a continuation character in column 7, but you have forgotten to start the continuation of the literal with a quotation mark. Your COBOL system assumes that the quotation mark is included.
  • COBCH1004 Continuation character expected. End of literal assumed
    The literal in the previous line of source code is not delimited by quotation marks, so your COBOL system is expecting a continuation character in column 7, and a continuation of the literal. Your COBOL system has assumed that you meant to end the literal on the previous line.
  • COBCH1005 Name ends in hyphen. Processed as written
    You have used a hyphen as the last character in a user-defined-name, which is against the rules of COBOL syntax. Your COBOL system has accepted this as a valid name, however, and has not changed the name in any way.
  • COBCH1006 COBOL word contains more than nn characters. Word truncated
    The name that you have specified is longer than the maximum amount of characters allowed under the current COBOL dialect. Your COBOL system treats this as a name consisting of the first nn characters specified.
  • COBCH1007 VALUE literal size size1 > data item size size2. Literal truncated
    The literal you have specified in the VALUE clause is too long to fit into the data item. Your COBOL system inserts characters from the literal into the data item, until the data item is full.
  • COBCH1008 DBCS literal must contain an even number of characters. Literal truncated
    All Double Byte Character Set (DBCS) symbols are two bytes (two characters) long. You have specified a literal that consists of an odd number of characters. Your COBOL system ignores the last, single character of the literal.
  • COBCH1009 Closing delimiter for DBCS literal not found. Delimiter assumed
    You have not included the quotation mark to show the end of the Double Byte Character Set (DBCS) literal. Your COBOL system has assumed that you intended to end the literal at this point.
  • COBCH1010 Nonnumeric literal has length of zero. One SPACE assumed
    The alphabetic or alphanumeric literal you have defined in your source code is empty, that is, you have a pair of quotation marks with no character between them. Your COBOL system has assumed that the literal contains one space character.
  • COBCH1011 DBCS literal has length of zero. Length of one DBCS character assumed
    The Double Byte Character Set (DBCS) literal you have defined in your source code is empty, that is, you have a pair of quotation marks with no DBCS character between them. Your COBOL system has assumed that the literal is two characters long, and that it has a value of spaces.
  • COBCH1012 DIVISION missing or misspelled. DIVISION assumed
    You have omitted the word DIVISION from a Division header, or you have spelled it incorrectly. Your COBOL system has assumed that DIVISION is what was meant.
  • COBCH1013 SECTION missing or misspelled. SECTION assumed
    You have omitted the word SECTION from a Section header, or you have spelled it incorrectly. Your COBOL system has assumed that SECTION is what was meant.
  • COBCH1014 Period missing. Period assumed
    You have omitted a period in a place where one is expected by the rules of COBOL syntax. Your COBOL system has assumed the period is present.
  • COBCH1015 OCCURS integer-1 exceeds OCCURS integer-2. Zero is assumed for integer-1
    You have included the OCCURS integer-1 TO integer-2 DEPENDING clause in your source code, but the value given for integer-1 is greater than that for integer-2, which is against the rules of COBOL syntax. Your COBOL system has effectively changed the value of integer-1 to 0.
  • COBCH1016 Expected SEPARATE before CHARACTER in SIGN clause. SEPARATE assumed
    You have incorrectly coded the SIGN clause because you have included the word CHARACTER, which is not required, but you have omitted the required word SEPARATE. Your COBOL system has assumed that you intended the clause to be SIGN IS LEADING (or TRAILING) SEPARATE CHARACTER.
  • COBCH1017 REDEFINES ignored for 01 level item in File or Communication Section
    You have tried to REDEFINE a data item in the File or Communication Section but the data item is an 01 level item. Level 01 items for the same FD or CD automatically redefine one another.
  • COBCH1018 VALUE clause not allowed here. Clause processed as comment
    You have tried to assign a value to a data item defined in the File Section or the Linkage Section. The VALUE clause is ignored.
  • COBCH1019 Unsigned numeric literal expected. Sign ignored
    You have specified a sign where one is not expected, for example, you have used the AFTER ADVANCING +1 or BEFORE ADVANCING -2 clause to the WRITE statement. Your COBOL system ignores the sign, and treats the digits as a positive value.
  • COBCH1020 Unsigned numeric field. Sign in VALUE clause ignored
    You have defined a numeric data item (that is, PIC 9) and you have tried to assign a signed number as its value. Your COBOL system ignores the sign you have specified. Where you are trying to move a number with a negative sign into a numeric field, the result is not as expected.
Parent topic: Messages COBCH1001 to COBCH1100


COBCH1001 Character other than *, D, /, -, or $ found in column 7. Blank assumed

You might have mistyped one of the characters allowed in column 7. Your COBOL system cannot interpret the character in column 7, and has treated it as a space.
Parent topic: COBCH1001 - COBCH1020


COBCH1002 Continuation character invalid at this point. Blank assumed

You have placed a hyphen in column 7, though your COBOL system is not expecting the syntax to be continued at this point. The continuation character is ignored.
Parent topic: COBCH1001 - COBCH1020


COBCH1003 First character of a continued literal not a quote. Quote assumed

You have included a continuation character in column 7, but you have forgotten to start the continuation of the literal with a quotation mark. Your COBOL system assumes that the quotation mark is included.
Parent topic: COBCH1001 - COBCH1020


COBCH1004 Continuation character expected. End of literal assumed

The literal in the previous line of source code is not delimited by quotation marks, so your COBOL system is expecting a continuation character in column 7, and a continuation of the literal. Your COBOL system has assumed that you meant to end the literal on the previous line.
Parent topic: COBCH1001 - COBCH1020


COBCH1005 Name ends in hyphen. Processed as written

You have used a hyphen as the last character in a user-defined-name, which is against the rules of COBOL syntax. Your COBOL system has accepted this as a valid name, however, and has not changed the name in any way.
Parent topic: COBCH1001 - COBCH1020


COBCH1006 COBOL word contains more than nn characters. Word truncated

The name that you have specified is longer than the maximum amount of characters allowed under the current COBOL dialect. Your COBOL system treats this as a name consisting of the first nn characters specified.
Parent topic: COBCH1001 - COBCH1020


COBCH1007 VALUE literal size size1 > data item size size2. Literal truncated

The literal you have specified in the VALUE clause is too long to fit into the data item. Your COBOL system inserts characters from the literal into the data item, until the data item is full.
Parent topic: COBCH1001 - COBCH1020


COBCH1008 DBCS literal must contain an even number of characters. Literal truncated

All Double Byte Character Set (DBCS) symbols are two bytes (two characters) long. You have specified a literal that consists of an odd number of characters. Your COBOL system ignores the last, single character of the literal.
Parent topic: COBCH1001 - COBCH1020


COBCH1009 Closing delimiter for DBCS literal not found. Delimiter assumed

You have not included the quotation mark to show the end of the Double Byte Character Set (DBCS) literal. Your COBOL system has assumed that you intended to end the literal at this point.
Parent topic: COBCH1001 - COBCH1020


COBCH1010 Nonnumeric literal has length of zero. One SPACE assumed

The alphabetic or alphanumeric literal you have defined in your source code is empty, that is, you have a pair of quotation marks with no character between them. Your COBOL system has assumed that the literal contains one space character.
Parent topic: COBCH1001 - COBCH1020


COBCH1011 DBCS literal has length of zero. Length of one DBCS character assumed

The Double Byte Character Set (DBCS) literal you have defined in your source code is empty, that is, you have a pair of quotation marks with no DBCS character between them. Your COBOL system has assumed that the literal is two characters long, and that it has a value of spaces.
Parent topic: COBCH1001 - COBCH1020


COBCH1012 DIVISION missing or misspelled. DIVISION assumed

You have omitted the word DIVISION from a Division header, or you have spelled it incorrectly. Your COBOL system has assumed that DIVISION is what was meant.
Parent topic: COBCH1001 - COBCH1020


COBCH1013 SECTION missing or misspelled. SECTION assumed

You have omitted the word SECTION from a Section header, or you have spelled it incorrectly. Your COBOL system has assumed that SECTION is what was meant.
Parent topic: COBCH1001 - COBCH1020


COBCH1014 Period missing. Period assumed

You have omitted a period in a place where one is expected by the rules of COBOL syntax. Your COBOL system has assumed the period is present.
Parent topic: COBCH1001 - COBCH1020


COBCH1015 OCCURS integer-1 exceeds OCCURS integer-2. Zero is assumed for integer-1

You have included the OCCURS integer-1 TO integer-2 DEPENDING clause in your source code, but the value given for integer-1 is greater than that for integer-2, which is against the rules of COBOL syntax. Your COBOL system has effectively changed the value of integer-1 to 0.
Parent topic: COBCH1001 - COBCH1020


COBCH1016 Expected SEPARATE before CHARACTER in SIGN clause. SEPARATE assumed

You have incorrectly coded the SIGN clause because you have included the word CHARACTER, which is not required, but you have omitted the required word SEPARATE. Your COBOL system has assumed that you intended the clause to be SIGN IS LEADING (or TRAILING) SEPARATE CHARACTER.
Parent topic: COBCH1001 - COBCH1020


COBCH1017 REDEFINES ignored for 01 level item in File or Communication Section

You have tried to REDEFINE a data item in the File or Communication Section but the data item is an 01 level item. Level 01 items for the same FD or CD automatically redefine one another.
Parent topic: COBCH1001 - COBCH1020


COBCH1018 VALUE clause not allowed here. Clause processed as comment

You have tried to assign a value to a data item defined in the File Section or the Linkage Section. The VALUE clause is ignored.
Parent topic: COBCH1001 - COBCH1020


COBCH1019 Unsigned numeric literal expected. Sign ignored

You have specified a sign where one is not expected, for example, you have used the AFTER ADVANCING +1 or BEFORE ADVANCING -2 clause to the WRITE statement. Your COBOL system ignores the sign, and treats the digits as a positive value.
Parent topic: COBCH1001 - COBCH1020


COBCH1020 Unsigned numeric field. Sign in VALUE clause ignored

You have defined a numeric data item (that is, PIC 9) and you have tried to assign a signed number as its value. Your COBOL system ignores the sign you have specified. Where you are trying to move a number with a negative sign into a numeric field, the result is not as expected.
Parent topic: COBCH1001 - COBCH1020


COBCH1021 - COBCH1040

Lists the Syntax Checking error messages from COBCH1021 through COBCH1040.

  • COBCH1021 Slack bytes added in conversion of COMP-6 to COMP
    You are using a program converted from RM/COBOL that contains a COMP-6 numeric data item which has been converted to a COMP numeric data item. As a result of this conversion, less data space might have been allocated to the numeric data item and, therefore, your COBOL system adds leading binary zeros to pad the space, if required.
  • COBCH1022 Table item not subscripted or indexed. First occurrence assumed
  • COBCH1023 WORKING-STORAGE SECTION expected. Start of Working-Storage assumed
    Your program begins with an 01 level entry. It is assumed that this is the first item of the Working-Storage Section.
  • COBCH1024 VALUE clause literal does not conform to PICTURE. Changed to blanks.
    A numeric value has been specified for a nonnumeric data item. The data item is filled with spaces.
  • COBCH1025 MOVE edited field to edited field - treated as alphanumeric move
    A move of one edited field to another is treated as an alphanumeric move.
  • COBCH1026 Source literal is nonnumeric - substituting zero
    A MOVE statement is trying to MOVE a nonnumeric literal to a numeric data item. This cannot be done. To avoid undefined results, ZERO is moved to the target data item.
  • COBCH1027 Literal is numeric - treated as nonnumeric
    A numeric literal is being used in relation to a nonnumeric data item; for example, as the VALUE of an 88 level entry attached to a nonnumeric data item. The literal is converted to an alphanumeric literal.
  • COBCH1028 Statement should not reference an alphabetic data item
    A statement would cause invalid data to be contained in an alphabetic data item. Your COBOL system executes the statement as written.
  • COBCH1029 A non-integer is being moved to an alphanumeric data item
    A MOVE statement is trying to move a noninteger item to an alphanumeric data item. The decimal point is ignored and all the digits moved as if they constituted an integer.
  • COBCH1030 Cannot SORT or MERGE USING or GIVING two files with SAME AREA
    Two files specified in a SORT or MERGE statement are defined as sharing the same area. The files are allocated different areas.
  • COBCH1031 SORT file appears in more than one SAME SORT (-MERGE) AREA clause
    A SORT file has been referenced in more than one SAME SORT (-MERGE) AREA clause. The files are allocated different areas.
  • COBCH1032 Filenames illegally specified in same SAME RECORD AREA clause
    Two files in a SORT or MERGE statement are defined as sharing the same record area. The files are allocated different record areas.
  • COBCH1033 Filenames illegally specified in same SAME SORT (-MERGE) AREA clause
    Two files in a SORT or MERGE statement are defined as sharing the same sort (-merge) area. The files are allocated different sort-merge areas.
  • COBCH1034 Source item is ALPHABETIC or ALPHANUMERIC-EDITED - treated as alphanumeric
    You have moved either an alphabetic, alphabetic justified, edited alphabetic or edited alphanumeric field to a numeric display field. The source field has been treated as though it were a numeric field.
  • COBCH1035 Key is not wholly contained within minimum record length
    The specified key is greater in length than the minimum size of the record.
  • COBCH1036 External name illegal
    An external name, such as program-id or an entry name does not conform to the syntax rules for that item.
  • COBCH1037 Data-name must be specified for an EXTERNAL record - EXTERNAL ignored
  • COBCH1038 RECORD key or ALTERNATE key has same starting position as another key
    The specified key has the same starting position in the file's record as a previously defined key.
  • COBCH1039 Error in structure information. No structure diagram created
    You are trying to perform structure animation of a program in which a PERFORM THRU statement performs sections in the Declaratives.
  • COBCH1040 ALL not allowed here - ALL ignored
Parent topic: Messages COBCH1001 to COBCH1100


COBCH1021 Slack bytes added in conversion of COMP-6 to COMP

You are using a program converted from RM/COBOL that contains a COMP-6 numeric data item which has been converted to a COMP numeric data item. As a result of this conversion, less data space might have been allocated to the numeric data item and, therefore, your COBOL system adds leading binary zeros to pad the space, if required.
Parent topic: COBCH1021 - COBCH1040


COBCH1022 Table item not subscripted or indexed. First occurrence assumed

Parent topic: COBCH1021 - COBCH1040


COBCH1023 WORKING-STORAGE SECTION expected. Start of Working-Storage assumed

Your program begins with an 01 level entry. It is assumed that this is the first item of the Working-Storage Section.
Parent topic: COBCH1021 - COBCH1040


COBCH1024 VALUE clause literal does not conform to PICTURE. Changed to blanks.

A numeric value has been specified for a nonnumeric data item. The data item is filled with spaces.
Parent topic: COBCH1021 - COBCH1040


COBCH1025 MOVE edited field to edited field - treated as alphanumeric move

A move of one edited field to another is treated as an alphanumeric move.
Parent topic: COBCH1021 - COBCH1040


COBCH1026 Source literal is nonnumeric - substituting zero

A MOVE statement is trying to MOVE a nonnumeric literal to a numeric data item. This cannot be done. To avoid undefined results, ZERO is moved to the target data item.
Parent topic: COBCH1021 - COBCH1040


COBCH1027 Literal is numeric - treated as nonnumeric

A numeric literal is being used in relation to a nonnumeric data item; for example, as the VALUE of an 88 level entry attached to a nonnumeric data item. The literal is converted to an alphanumeric literal.
Parent topic: COBCH1021 - COBCH1040


COBCH1028 Statement should not reference an alphabetic data item

A statement would cause invalid data to be contained in an alphabetic data item. Your COBOL system executes the statement as written.
Parent topic: COBCH1021 - COBCH1040


COBCH1029 A non-integer is being moved to an alphanumeric data item

A MOVE statement is trying to move a noninteger item to an alphanumeric data item. The decimal point is ignored and all the digits moved as if they constituted an integer.
Parent topic: COBCH1021 - COBCH1040


COBCH1030 Cannot SORT or MERGE USING or GIVING two files with SAME AREA

Two files specified in a SORT or MERGE statement are defined as sharing the same area. The files are allocated different areas.
Parent topic: COBCH1021 - COBCH1040


COBCH1031 SORT file appears in more than one SAME SORT (-MERGE) AREA clause

A SORT file has been referenced in more than one SAME SORT (-MERGE) AREA clause. The files are allocated different areas.
Parent topic: COBCH1021 - COBCH1040


COBCH1032 Filenames illegally specified in same SAME RECORD AREA clause

Two files in a SORT or MERGE statement are defined as sharing the same record area. The files are allocated different record areas.
Parent topic: COBCH1021 - COBCH1040


COBCH1033 Filenames illegally specified in same SAME SORT (-MERGE) AREA clause

Two files in a SORT or MERGE statement are defined as sharing the same sort (-merge) area. The files are allocated different sort-merge areas.
Parent topic: COBCH1021 - COBCH1040


COBCH1034 Source item is ALPHABETIC or ALPHANUMERIC-EDITED - treated as alphanumeric

You have moved either an alphabetic, alphabetic justified, edited alphabetic or edited alphanumeric field to a numeric display field. The source field has been treated as though it were a numeric field.
Parent topic: COBCH1021 - COBCH1040


COBCH1035 Key is not wholly contained within minimum record length

The specified key is greater in length than the minimum size of the record.
Parent topic: COBCH1021 - COBCH1040


COBCH1036 External name illegal

An external name, such as program-id or an entry name does not conform to the syntax rules for that item.

Correct the syntax and recompile the code.

See the section COBOL Language Reference for more details on the required syntax.

Parent topic: COBCH1021 - COBCH1040


COBCH1037 Data-name must be specified for an EXTERNAL record - EXTERNAL ignored

Parent topic: COBCH1021 - COBCH1040


COBCH1038 RECORD key or ALTERNATE key has same starting position as another key

The specified key has the same starting position in the file's record as a previously defined key.
Parent topic: COBCH1021 - COBCH1040


COBCH1039 Error in structure information. No structure diagram created

You are trying to perform structure animation of a program in which a PERFORM THRU statement performs sections in the Declaratives.

Resolution:

Normal animation can be performed, but not structure animation.

Parent topic: COBCH1021 - COBCH1040


COBCH1040 ALL not allowed here - ALL ignored

Parent topic: COBCH1021 - COBCH1040


COBCH1041 - COBCH1060

Lists the Syntax Checking error messages from COBCH1041 through COBCH1060.

  • COBCH1041 Data item has zero size, or group not yet completed. Value of 0 assumed
  • COBCH1042 A numeric item is being moved to an ALPHABETIC data item
  • COBCH1043 PERFORM may be recursive
  • COBCH1044 Load failure on SLOAD - STRUCT ignored
  • COBCH1045 Capacity of POINTER may be exceeded
  • COBCH1046 Host variable name might cause problems
  • COBCH1047 Phrase ignored - unsuccessful chain will cause program termination
  • COBCH1048 DBCS literal includes invalid data
  • COBCH1049 KEY clause not allowed with sequential READ - clause ignored
  • COBCH1050 Invalid condition in $IF
  • COBCH1051 Value evaluated left to right, differs from normal arithmetic precedence
  • COBCH1052 ALL specified more than once - repeated occurrences ignored
    You have specified the word ALL more than once in an ALL literal.
  • COBCH1053 Multiple 01 level EXTERNAL records with same name - treated as same record
  • COBCH1054 Variable length group redefines or is redefined
  • COBCH1055 Requested SQLSTDLVL incompatible with your version of DBM. Directive ignored
    You have specified a directive which has no meaning on your database manager
  • COBCH1056 CALL-CONVENTION does not match that specified in prototype
  • COBCH1057 REFERENCE/ CONTENT/ VALUE phrase does not match that specified in prototype
  • COBCH1058 Number of parameters is greater than in prototype
  • COBCH1059 Parameter is not consistent with that defined in prototype
  • COBCH1060 Can only use DELIMITED with alphanumeric items
Parent topic: Messages COBCH1001 to COBCH1100


COBCH1041 Data item has zero size, or group not yet completed. Value of 0 assumed

Parent topic: COBCH1041 - COBCH1060


COBCH1042 A numeric item is being moved to an ALPHABETIC data item

Parent topic: COBCH1041 - COBCH1060


COBCH1043 PERFORM may be recursive

Parent topic: COBCH1041 - COBCH1060


COBCH1044 Load failure on SLOAD - STRUCT ignored

Parent topic: COBCH1041 - COBCH1060


COBCH1045 Capacity of POINTER may be exceeded

Parent topic: COBCH1041 - COBCH1060


COBCH1046 Host variable name might cause problems

Parent topic: COBCH1041 - COBCH1060


COBCH1047 Phrase ignored - unsuccessful chain will cause program termination

Parent topic: COBCH1041 - COBCH1060


COBCH1048 DBCS literal includes invalid data

Parent topic: COBCH1041 - COBCH1060


COBCH1049 KEY clause not allowed with sequential READ - clause ignored

Parent topic: COBCH1041 - COBCH1060


COBCH1050 Invalid condition in $IF

Parent topic: COBCH1041 - COBCH1060


COBCH1051 Value evaluated left to right, differs from normal arithmetic precedence

Parent topic: COBCH1041 - COBCH1060


COBCH1052 ALL specified more than once - repeated occurrences ignored

You have specified the word ALL more than once in an ALL literal.

Resolution:

We recommend that you remove any repetition of the word ALL, although any further occurrences are actually ignored.

Parent topic: COBCH1041 - COBCH1060


COBCH1053 Multiple 01 level EXTERNAL records with same name - treated as same record

Parent topic: COBCH1041 - COBCH1060


COBCH1054 Variable length group redefines or is redefined

Parent topic: COBCH1041 - COBCH1060


COBCH1055 Requested SQLSTDLVL incompatible with your version of DBM. Directive ignored

You have specified a directive which has no meaning on your database manager
Parent topic: COBCH1041 - COBCH1060


COBCH1056 CALL-CONVENTION does not match that specified in prototype

Parent topic: COBCH1041 - COBCH1060


COBCH1057 REFERENCE/ CONTENT/ VALUE phrase does not match that specified in prototype

Parent topic: COBCH1041 - COBCH1060


COBCH1058 Number of parameters is greater than in prototype

Parent topic: COBCH1041 - COBCH1060


COBCH1059 Parameter is not consistent with that defined in prototype

Parent topic: COBCH1041 - COBCH1060


COBCH1060 Can only use DELIMITED with alphanumeric items

Parent topic: COBCH1041 - COBCH1060


COBCH1061 - COBCH1080

Lists the Syntax Checking error messages from COBCH1061 through COBCH1080.

  • COBCH1061 Number of parameters is less than in prototype
  • COBCH1062 Not allowed in EXTERNAL program
  • COBCH1063 EXTERNAL not allowed with nested, INITIAL or COMMON programs - ignored
  • COBCH1064 Illegal use of literal
  • COBCH1065 OO: SELF only allowed in CLASS program
  • COBCH1066 OO: SUPER not allowed - CLASS has no INHERITING phrase
  • COBCH1067 OO: RETURNING phrase not allowed in METHOD
  • COBCH1068 OO: Class name class-name missing in SPECIAL-NAMES - assumed
  • COBCH1069 Identifier in area A assumed procedure name. Period missing before it
  • COBCH1070 OO: Incorrect structure of CLASS program
  • COBCH1071 OO: Missing OBJECT-STORAGE SECTION, required for inheritance
  • COBCH1072 OO: Not allowed in PROGRAM-ID. OBJECT
  • COBCH1073 LOCAL-STORAGE should be used with PERFORM-TYPE(MF).
  • COBCH1074 OO: INVOKE data-item not yet supported by OOPS run-time
  • COBCH1075 Invalid combination of RECORD and RECORDING MODE clauses
  • COBCH1076 Reference modified length should not be > 8191 at run-time
  • COBCH1077 Host variable name longer than permitted by database engine - truncated
  • COBCH1078 Setting of directives inline / conditional compilation / region syntax
    Inline directives ($SET statements), conditional compilation, and region syntax conflict with the selected flagging dialect.
  • COBCH1079 Expected positive integer, positive integer assumed
    You have used a negative integer where a positive integer was expected. Your COBOL system has ignored the negative sign.
  • COBCH1080 Odd number of hexadecimal digits
    Hexadecimal constants should be specified in pairs. The constant contains an odd number of characters and a leading zero has been assumed.
Parent topic: Messages COBCH1001 to COBCH1100


COBCH1061 Number of parameters is less than in prototype

Parent topic: COBCH1061 - COBCH1080


COBCH1062 Not allowed in EXTERNAL program

Parent topic: COBCH1061 - COBCH1080


COBCH1063 EXTERNAL not allowed with nested, INITIAL or COMMON programs - ignored

Parent topic: COBCH1061 - COBCH1080


COBCH1064 Illegal use of literal

Parent topic: COBCH1061 - COBCH1080


COBCH1065 OO: SELF only allowed in CLASS program

Parent topic: COBCH1061 - COBCH1080


COBCH1066 OO: SUPER not allowed - CLASS has no INHERITING phrase

Parent topic: COBCH1061 - COBCH1080


COBCH1067 OO: RETURNING phrase not allowed in METHOD

Parent topic: COBCH1061 - COBCH1080


COBCH1068 OO: Class name class-name missing in SPECIAL-NAMES - assumed

A common cause of this error is the omission of the word "type" in an inherit statement.

Parent topic: COBCH1061 - COBCH1080


COBCH1069 Identifier in area A assumed procedure name. Period missing before it

Parent topic: COBCH1061 - COBCH1080


COBCH1070 OO: Incorrect structure of CLASS program

Parent topic: COBCH1061 - COBCH1080


COBCH1071 OO: Missing OBJECT-STORAGE SECTION, required for inheritance

Parent topic: COBCH1061 - COBCH1080


COBCH1072 OO: Not allowed in PROGRAM-ID. OBJECT

Parent topic: COBCH1061 - COBCH1080


COBCH1073 LOCAL-STORAGE should be used with PERFORM-TYPE(MF).

Parent topic: COBCH1061 - COBCH1080


COBCH1074 OO: INVOKE data-item not yet supported by OOPS run-time

Parent topic: COBCH1061 - COBCH1080


COBCH1075 Invalid combination of RECORD and RECORDING MODE clauses

Parent topic: COBCH1061 - COBCH1080


COBCH1076 Reference modified length should not be > 8191 at run-time

Parent topic: COBCH1061 - COBCH1080


COBCH1077 Host variable name longer than permitted by database engine - truncated

Parent topic: COBCH1061 - COBCH1080


COBCH1078 Setting of directives inline / conditional compilation / region syntax

Inline directives ($SET statements), conditional compilation, and region syntax conflict with the selected flagging dialect.

Resolution:

Embedded directives may be set within a comment so that the code is compatible with the selected flagging dialect. To use this feature you must set the DIRECTIVES-IN-COMMENTS compiler directive.

Parent topic: COBCH1061 - COBCH1080


COBCH1079 Expected positive integer, positive integer assumed

You have used a negative integer where a positive integer was expected. Your COBOL system has ignored the negative sign.
Parent topic: COBCH1061 - COBCH1080


COBCH1080 Odd number of hexadecimal digits

Hexadecimal constants should be specified in pairs. The constant contains an odd number of characters and a leading zero has been assumed.
Parent topic: COBCH1061 - COBCH1080


COBCH1081 - COBCH1100

Lists the Syntax Checking error messages from COBCH1081 through COBCH1100.

  • COBCH1081 More than 255 BLL Cells
  • COBCH1082 Source line is too long
    You have coded a source line greater than 80 characters. Your chosen flagging dialect does not support this.
  • COBCH1083 RECORDING MODE IS F specified for a variable length record structure
  • COBCH1084 OO: Missing OBJECT-STORAGE SECTION, required for class extension
  • COBCH1085 Created subordinate data item item
  • COBCH1086 Clause should be part of the File Description
    A period character (.) was detected inside an FD statement.
  • COBCH1087 Cannot use both INITIAL and RECURSIVE clauses in PROGRAM-ID.
  • COBCH1088 Cannot pass an arithmetic expression BY REFERENCE.
  • COBCH1089 Micro Focus COBOL .NET license expired or not present.
  • COBCH1090 Literal contains SBCS Katakana characters
  • COBCH1091 Literal contains DBCS or SBCS Katakana characters
  • COBCH1092 SBCS Katakana character usage in source is not portable
  • COBCH1093 RECORDING MODE clause found in an SD entry. The clause was ignored.
  • COBCH1094 NOPRESERVECASE not supported with ILGEN. Consider removing NOPRESERVECASE.
  • COBCH1095 PERFORMTYPE not yet supported with JVMGEN.
  • COBCH1096 HOSTFD not yet supported with JVMGEN.
    HOSTFD functionality is not currently supported when compiling with JVMGEN. When the HOSTFD directive is set implicitly as part of a selected dialect, then it is ignored.
  • COBCH1097 File as CALL parameter not yet supported with JVMGEN.
  • COBCH1098 JVMGEN directive not supported by this product.
  • COBCH1099 ILGEN directive not supported by this product.
Parent topic: Messages COBCH1001 to COBCH1100


COBCH1081 More than 255 BLL Cells

Parent topic: COBCH1081 - COBCH1100


COBCH1082 Source line is too long

You have coded a source line greater than 80 characters. Your chosen flagging dialect does not support this.
Parent topic: COBCH1081 - COBCH1100


COBCH1083 RECORDING MODE IS F specified for a variable length record structure

Parent topic: COBCH1081 - COBCH1100


COBCH1084 OO: Missing OBJECT-STORAGE SECTION, required for class extension

Parent topic: COBCH1081 - COBCH1100


COBCH1085 Created subordinate data item item

Parent topic: COBCH1081 - COBCH1100


COBCH1086 Clause should be part of the File Description

A period character (.) was detected inside an FD statement.

Resolution:

Remove the offending period, or move it to a position that follows all of the FD syntax; then recompile.

Example:

In the following example, the FD statement contains a period after "f1". You must remove this period.

       select f1 assign "MyFile".
       fd f1. recording mode is F.
       01 r1 pic x(10).
Parent topic: COBCH1081 - COBCH1100


COBCH1087 Cannot use both INITIAL and RECURSIVE clauses in PROGRAM-ID.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1088 Cannot pass an arithmetic expression BY REFERENCE.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1089 Micro Focus COBOL .NET license expired or not present.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1090 Literal contains SBCS Katakana characters

Parent topic: COBCH1081 - COBCH1100


COBCH1091 Literal contains DBCS or SBCS Katakana characters

Parent topic: COBCH1081 - COBCH1100


COBCH1092 SBCS Katakana character usage in source is not portable

Parent topic: COBCH1081 - COBCH1100


COBCH1093 RECORDING MODE clause found in an SD entry. The clause was ignored.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1094 NOPRESERVECASE not supported with ILGEN. Consider removing NOPRESERVECASE.

Parent topic: COBCH1081 - COBCH1100


COBCH1095 PERFORMTYPE not yet supported with JVMGEN.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1096 HOSTFD not yet supported with JVMGEN.

HOSTFD functionality is not currently supported when compiling with JVMGEN. When the HOSTFD directive is set implicitly as part of a selected dialect, then it is ignored.

Resolution:

Recompile without the HOSTFD directive.

Example:

In the following example, the $set statement must be removed.

      $set hostfd
       select f1 assign "MyFile".
       fd f1.
       01 r1 pic x(10).
Parent topic: COBCH1081 - COBCH1100


COBCH1097 File as CALL parameter not yet supported with JVMGEN.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1098 JVMGEN directive not supported by this product.

Resolution:

Parent topic: COBCH1081 - COBCH1100


COBCH1099 ILGEN directive not supported by this product.

Resolution:

Parent topic: COBCH1081 - COBCH1100


Messages COBCH1101 to COBCH1200

  • COBCH1101 - COBCH1120
    Lists the Syntax Checking error messages from COBCH1101 through COBCH1120.
  • COBCH1121 - COBCH1140
    Lists the Syntax Checking error messages from COBCH1121 through COBCH1140.
  • COBCH1141 - COBCH1160
    Lists the Syntax Checking error messages from COBCH1141 through COBCH1160.
  • COBCH1161 - COBCH1180
    Lists the Syntax Checking error messages from COBCH1161 through COBCH1180.
  • COBCH1181 - COBCH1200
    Lists the Syntax Checking error messages from COBCH1181 through COBCH1200.
Parent topic: Syntax Checking Error Messages


COBCH1101 - COBCH1120

Lists the Syntax Checking error messages from COBCH1101 through COBCH1120.

  • COBCH1101 No COBOL statement between periods
    You have placed one period immediately following another period. This is not against the rules of COBOL syntax, but it might indicate a fault in your program, for example, you might have wanted to include a line of source code here.
  • COBCH1102 Blank continuation source line. Line ignored
    You have placed a hyphen in column 7, but the rest of the line contains no other code. The next line should also contain a hyphen in column 7, to continue correctly.
  • COBCH1103 Sequence number out of order or missing
  • COBCH1104 77 level item in File Section. Processed as 01 level
    You have assigned a level of 77 to a data item in the File Section which is against the rules of COBOL syntax. Your COBOL system assumes that you had intended to code this as an 01 level item, and processes it as such.
  • COBCH1105 No CORRESPONDING items were found. Statement has no effect
    Your COBOL system found no matching data items for the CORRESPONDING clause, so no intermediate code is produced for this statement.
  • COBCH1106 ZERO value for BY operand. Statement processed as written
    You have used the BY operand with the verb PERFORM, but the value you have specified for the increment is zero. Your COBOL system produces code to execute this statement, but the value is never incremented.
  • COBCH1107 Statement exceeds COMP subset
    The COMP subset code you have written could be rewritten to execute more efficiently.
  • COBCH1108 Signed numeric compared with group. Processed as alphanumeric compare
    You have written your code so that a signed numeric field is compared with a group item. Your COBOL system has treated the signed numeric field as an alphanumeric field for the comparison. There are no problems with comparing a signed numeric field with an elementary item.
  • COBCH1109 WITH DEBUGGING MODE not specified. Section ignored
    Your program includes the USE FOR DEBUGGING statement in a section in the Declaratives of your Procedure Division, but you have not included the WITH DEBUGGING MODE clause in the Source-Computer paragraph. Your COBOL system ignores all code in this section.
  • COBCH1110 First literal is greater than second. Processed as written
    In the ALPHABET clause the first literal that is specified has a value greater than that of the second, for example, P THRU D. Your COBOL system accepts this as written, that is, the characters are processed in reverse order.
  • COBCH1111 Boundary violation. Processed as written
    You have tried to access an item beyond the end of a table. Your COBOL system generates code to access the appropriate line of code beyond the end of the table, but the result of this is undefined.
  • COBCH1112 Compatibility directive forcing non standard behaviour
  • COBCH1113 Imperative statement missing - CONTINUE assumed
    Your program contains a conditional statement which has not been followed by an imperative statement. Your COBOL system executes the code, but the result of this might be undefined.
  • COBCH1114 Clause treated as documentary
    You have assigned more than one external file reference to a SELECT ... ASSIGN clause. Your COBOL system accepts the first external file reference, but treats all remaining external file references in that clause as documentary.
  • COBCH1115 SAME AREA treated as SAME RECORD AREA
    You are using a program converted from DG Interactive COBOL to this COBOL that contains a SAME AREA clause. Your COBOL system has assumed that the SAME RECORD AREA clause is what was meant.
  • COBCH1116 ACCEPT qualifier used with display-only field - qualifier ignored
    The qualifier used with a DISPLAY only field, or in a DISPLAY statement, can be used only with an ACCEPT. It is ignored.
  • COBCH1117 Zero suppression follows floating insertion - treated as floating insertion
    As an example, PIC ++Z.ZZ is treated as PIC +++.++.
  • COBCH1118 Index-name belongs to different table
    The index used to subscript a table item is not one used in the INDEXED BY clause for this table. The results are unpredictable.
  • COBCH1119 Record size size1 < minimum size given in FD statement size2
    The definition of a record following an FD clause is smaller than the minimum size specified in the RECORD CONTAINS phrase of that FD clause.
  • COBCH1120 Record size size1 > maximum size given in FD statement size2
    The definition of a record following an FD clause is larger than the maximum size specified in the RECORD CONTAINS phrase of that FD clause.
Parent topic: Messages COBCH1101 to COBCH1200


COBCH1101 No COBOL statement between periods

You have placed one period immediately following another period. This is not against the rules of COBOL syntax, but it might indicate a fault in your program, for example, you might have wanted to include a line of source code here.
Parent topic: COBCH1101 - COBCH1120


COBCH1102 Blank continuation source line. Line ignored

You have placed a hyphen in column 7, but the rest of the line contains no other code. The next line should also contain a hyphen in column 7, to continue correctly.
Parent topic: COBCH1101 - COBCH1120


COBCH1103 Sequence number out of order or missing

Parent topic: COBCH1101 - COBCH1120


COBCH1104 77 level item in File Section. Processed as 01 level

You have assigned a level of 77 to a data item in the File Section which is against the rules of COBOL syntax. Your COBOL system assumes that you had intended to code this as an 01 level item, and processes it as such.
Parent topic: COBCH1101 - COBCH1120


COBCH1105 No CORRESPONDING items were found. Statement has no effect

Your COBOL system found no matching data items for the CORRESPONDING clause, so no intermediate code is produced for this statement.
Parent topic: COBCH1101 - COBCH1120


COBCH1106 ZERO value for BY operand. Statement processed as written

You have used the BY operand with the verb PERFORM, but the value you have specified for the increment is zero. Your COBOL system produces code to execute this statement, but the value is never incremented.
Parent topic: COBCH1101 - COBCH1120


COBCH1107 Statement exceeds COMP subset

The COMP subset code you have written could be rewritten to execute more efficiently.

Click below for information on writing efficient code.

Parent topic: COBCH1101 - COBCH1120


COBCH1108 Signed numeric compared with group. Processed as alphanumeric compare

You have written your code so that a signed numeric field is compared with a group item. Your COBOL system has treated the signed numeric field as an alphanumeric field for the comparison. There are no problems with comparing a signed numeric field with an elementary item.
Parent topic: COBCH1101 - COBCH1120


COBCH1109 WITH DEBUGGING MODE not specified. Section ignored

Your program includes the USE FOR DEBUGGING statement in a section in the Declaratives of your Procedure Division, but you have not included the WITH DEBUGGING MODE clause in the Source-Computer paragraph. Your COBOL system ignores all code in this section.
Parent topic: COBCH1101 - COBCH1120


COBCH1110 First literal is greater than second. Processed as written

In the ALPHABET clause the first literal that is specified has a value greater than that of the second, for example, P THRU D. Your COBOL system accepts this as written, that is, the characters are processed in reverse order.
Parent topic: COBCH1101 - COBCH1120


COBCH1111 Boundary violation. Processed as written

You have tried to access an item beyond the end of a table. Your COBOL system generates code to access the appropriate line of code beyond the end of the table, but the result of this is undefined.
Parent topic: COBCH1101 - COBCH1120


COBCH1112 Compatibility directive forcing non standard behaviour

Parent topic: COBCH1101 - COBCH1120


COBCH1113 Imperative statement missing - CONTINUE assumed

Your program contains a conditional statement which has not been followed by an imperative statement. Your COBOL system executes the code, but the result of this might be undefined.
Parent topic: COBCH1101 - COBCH1120


COBCH1114 Clause treated as documentary

You have assigned more than one external file reference to a SELECT ... ASSIGN clause. Your COBOL system accepts the first external file reference, but treats all remaining external file references in that clause as documentary.
Parent topic: COBCH1101 - COBCH1120


COBCH1115 SAME AREA treated as SAME RECORD AREA

You are using a program converted from DG Interactive COBOL to this COBOL that contains a SAME AREA clause. Your COBOL system has assumed that the SAME RECORD AREA clause is what was meant.
Parent topic: COBCH1101 - COBCH1120


COBCH1116 ACCEPT qualifier used with display-only field - qualifier ignored

The qualifier used with a DISPLAY only field, or in a DISPLAY statement, can be used only with an ACCEPT. It is ignored.
Parent topic: COBCH1101 - COBCH1120


COBCH1117 Zero suppression follows floating insertion - treated as floating insertion

As an example, PIC ++Z.ZZ is treated as PIC +++.++.
Parent topic: COBCH1101 - COBCH1120


COBCH1118 Index-name belongs to different table

The index used to subscript a table item is not one used in the INDEXED BY clause for this table. The results are unpredictable.
Parent topic: COBCH1101 - COBCH1120


COBCH1119 Record size size1 < minimum size given in FD statement size2

The definition of a record following an FD clause is smaller than the minimum size specified in the RECORD CONTAINS phrase of that FD clause.
Parent topic: COBCH1101 - COBCH1120


COBCH1120 Record size size1 > maximum size given in FD statement size2

The definition of a record following an FD clause is larger than the maximum size specified in the RECORD CONTAINS phrase of that FD clause.
Parent topic: COBCH1101 - COBCH1120


COBCH1121 - COBCH1140

Lists the Syntax Checking error messages from COBCH1121 through COBCH1140.

  • COBCH1121 VALUE in File, Linkage, or Local-Storage Section - processed as comment
    A data item in the File or Linkage Section cannot be given a value. The VALUE clause specified is ignored.
  • COBCH1122 Period must be followed by a space
    In all cases a period must be followed by a space.
  • COBCH1123 Neither NAMED nor CHANGED specified. Will be treated as formatted DISPLAY.
    An EXHIBIT statement has been used without the NAMED or CHANGED phrase. The resulting display is formatted by separating each item with a space.
  • COBCH1124 CALL parameter is literal (or LENGTH OF). BY CONTENT assumed
    You are using a program converted from RM/COBOL to this COBOL that contains a CALL ... USING literal statement. Your COBOL system has assumed that CALL ... USING BY CONTENT literal is what was meant.
  • COBCH1125 Punctuation character not followed by a space. Assume space
    A punctuation character should be followed by a space.
  • COBCH1126 Punctuation character not preceded by a space. Assume space
    In accordance with ANS85 specifications, the relational operator "=" is considered to be a COBOL reserved word; all reserved words must be both preceded and delimited by a space.
  • COBCH1127 Double-Byte character(s) might be corrupted by use of this move
    This MOVE statement might cause a double-byte data item to be corrupted by changing one byte of a double-byte pair.
  • COBCH1128 No STOP RUN, GOBACK, or EXIT PROGRAM statements encountered in source
    The source has no STOP RUN, GOBACK or EXIT PROGRAM statement. Your COBOL system automatically inserts an EXIT statement followed by a STOP RUN statement following the last line in the program. However, this might not have the effect you desire.
  • COBCH1129 Statement cannot be reached
    The program flow prevents the statement flagged from being executed.
  • COBCH1130 Prefix of filename treated as documentary
  • COBCH1131 Statement generated no executable code
    This error might be produced when, for example, an INITIALIZE statement does not cause any code to be created. It is an indication that the statement can be removed from the program. If the error is ignored the effect is as if the statement were removed.
  • COBCH1132 Unable to validate contents of DBCS literals
    Your COBOL system is unable to check that the contents of a DBCS literal are valid. If the contents are invalid the results are unpredictable.
  • COBCH1133 SQL warning/ recoverable error
    The SQL processor generated a warning. Check your SQL documentation for further details.
  • COBCH1134 Entry name has been converted following OS/VS COBOL and VS COBOL II rules
  • COBCH1135 No OPEN statement was found for file
  • COBCH1136 No CLOSE statement was found for file
  • COBCH1137 "KEPT" omitted for file with multiple record locking
    The KEPT phrase has not been included in your multiple record locked file.
  • COBCH1138 Name truncated to characters characters
  • COBCH1139 Operand operand does not have suitable data type
  • COBCH1140 VALUE in FILE or LINKAGE SECTION - only used with INITIALIZE statement
    A VALUE clause has been specified on an item within the FILE or LINKAGE SECTION of your program.
Parent topic: Messages COBCH1101 to COBCH1200


COBCH1121 VALUE in File, Linkage, or Local-Storage Section - processed as comment

A data item in the File or Linkage Section cannot be given a value. The VALUE clause specified is ignored.
Parent topic: COBCH1121 - COBCH1140


COBCH1122 Period must be followed by a space

In all cases a period must be followed by a space.
Parent topic: COBCH1121 - COBCH1140


COBCH1123 Neither NAMED nor CHANGED specified. Will be treated as formatted DISPLAY.

An EXHIBIT statement has been used without the NAMED or CHANGED phrase. The resulting display is formatted by separating each item with a space.
Parent topic: COBCH1121 - COBCH1140


COBCH1124 CALL parameter is literal (or LENGTH OF). BY CONTENT assumed

You are using a program converted from RM/COBOL to this COBOL that contains a CALL ... USING literal statement. Your COBOL system has assumed that CALL ... USING BY CONTENT literal is what was meant.
Parent topic: COBCH1121 - COBCH1140


COBCH1125 Punctuation character not followed by a space. Assume space

A punctuation character should be followed by a space.
Parent topic: COBCH1121 - COBCH1140


COBCH1126 Punctuation character not preceded by a space. Assume space

In accordance with ANS85 specifications, the relational operator "=" is considered to be a COBOL reserved word; all reserved words must be both preceded and delimited by a space.
Parent topic: COBCH1121 - COBCH1140


COBCH1127 Double-Byte character(s) might be corrupted by use of this move

This MOVE statement might cause a double-byte data item to be corrupted by changing one byte of a double-byte pair.
Parent topic: COBCH1121 - COBCH1140


COBCH1128 No STOP RUN, GOBACK, or EXIT PROGRAM statements encountered in source

The source has no STOP RUN, GOBACK or EXIT PROGRAM statement. Your COBOL system automatically inserts an EXIT statement followed by a STOP RUN statement following the last line in the program. However, this might not have the effect you desire.
Parent topic: COBCH1121 - COBCH1140


COBCH1129 Statement cannot be reached

The program flow prevents the statement flagged from being executed.
Parent topic: COBCH1121 - COBCH1140


COBCH1130 Prefix of filename treated as documentary

Parent topic: COBCH1121 - COBCH1140


COBCH1131 Statement generated no executable code

This error might be produced when, for example, an INITIALIZE statement does not cause any code to be created. It is an indication that the statement can be removed from the program. If the error is ignored the effect is as if the statement were removed.
Parent topic: COBCH1121 - COBCH1140


COBCH1132 Unable to validate contents of DBCS literals

Your COBOL system is unable to check that the contents of a DBCS literal are valid. If the contents are invalid the results are unpredictable.
Parent topic: COBCH1121 - COBCH1140


COBCH1133 SQL warning/ recoverable error

The SQL processor generated a warning. Check your SQL documentation for further details.
Parent topic: COBCH1121 - COBCH1140


COBCH1134 Entry name has been converted following OS/VS COBOL and VS COBOL II rules

Parent topic: COBCH1121 - COBCH1140


COBCH1135 No OPEN statement was found for file

Parent topic: COBCH1121 - COBCH1140


COBCH1136 No CLOSE statement was found for file

Parent topic: COBCH1121 - COBCH1140


COBCH1137 "KEPT" omitted for file with multiple record locking

The KEPT phrase has not been included in your multiple record locked file.
Parent topic: COBCH1121 - COBCH1140


COBCH1138 Name truncated to characters characters

Parent topic: COBCH1121 - COBCH1140


COBCH1139 Operand operand does not have suitable data type

Parent topic: COBCH1121 - COBCH1140


COBCH1140 VALUE in FILE or LINKAGE SECTION - only used with INITIALIZE statement

A VALUE clause has been specified on an item within the FILE or LINKAGE SECTION of your program.

This clause will be ignored until you use the VALUE clause as part of an INITIALIZE statement; at which point, the value is assigned to the item.

...
linkage section.
01 lnk-item1 pic x(5) value "hello".
procedure division using lnk-item1.
display lnk-item1.                  *> displays value passed in to program
initialize lnk-item1 to value.
display lnk-item1.                  *> displays "hello"
Parent topic: COBCH1121 - COBCH1140
Related tasks
The INITIALIZE Statement


COBCH1141 - COBCH1160

Lists the Syntax Checking error messages from COBCH1141 through COBCH1160.

  • COBCH1141 Name longer than 8 characters
  • COBCH1142 Name includes characters that would be changed by OS/VS COBOL and VS COBOL II
  • COBCH1143 Name includes characters that would be illegal for OS/VS COBOL and VS COBOL II
  • COBCH1144 String will be null terminated when returned by SQL
  • COBCH1145 DUPLICATES phrase with keys generates slower sort; remove if possible
  • COBCH1146 procedure-name lies in more than one PERFORM THRU range
  • COBCH1147 End precedes start in PERFORM procedure-name THRU procedure-name
    The procedure-name after the THRU comes earlier in the source program than the one before the THRU.
  • COBCH1148 Segmentation specified in nested program.
  • COBCH1149 Operand data-name ambiguous in corresponding target
    In a MOVE, ADD or SUBTRACT CORRESPONDING, the sending group contains an item, data-name, which is ambiguous in the receiving group.
  • COBCH1150 Redefinition of internal floating-point item. Might not be portable
  • COBCH1151 Forward overlapping move might produce unpredictable results
    You have specified a MOVE to a target whose starting position is before the ending position of the source data item.
  • COBCH1152 Comparison involving floating point data might not be portable
  • COBCH1153 Some mainframe values for this data-type cannot be handled on PC
  • COBCH1154 PC allows values for this data-type that cannot be handled on mainframes
  • COBCH1155 Both PANVALET and LIBRARIAN specified - not mainframe compatible
  • COBCH1156 BLOCK or LABEL clause in SD not allowed. Ignored
  • COBCH1157 JUSTIFIED specified on edited field
  • COBCH1158 CBL PROCESS *CBL or *CONTROL record encountered. Directives ignored
  • COBCH1159 Portion of name following first "-" treated as documentary.
  • COBCH1160 Changes before first statement cannot be checked. Ignored
Parent topic: Messages COBCH1101 to COBCH1200


COBCH1141 Name longer than 8 characters

Parent topic: COBCH1141 - COBCH1160


COBCH1142 Name includes characters that would be changed by OS/VS COBOL and VS COBOL II

Parent topic: COBCH1141 - COBCH1160


COBCH1143 Name includes characters that would be illegal for OS/VS COBOL and VS COBOL II

Parent topic: COBCH1141 - COBCH1160


COBCH1144 String will be null terminated when returned by SQL

Parent topic: COBCH1141 - COBCH1160


COBCH1145 DUPLICATES phrase with keys generates slower sort; remove if possible

Parent topic: COBCH1141 - COBCH1160


COBCH1146 procedure-name lies in more than one PERFORM THRU range

Parent topic: COBCH1141 - COBCH1160


COBCH1147 End precedes start in PERFORM procedure-name THRU procedure-name

The procedure-name after the THRU comes earlier in the source program than the one before the THRU.
Parent topic: COBCH1141 - COBCH1160


COBCH1148 Segmentation specified in nested program.

Parent topic: COBCH1141 - COBCH1160


COBCH1149 Operand data-name ambiguous in corresponding target

In a MOVE, ADD or SUBTRACT CORRESPONDING, the sending group contains an item, data-name, which is ambiguous in the receiving group.

Resolution:

Although data-name occurs in both the sending and receiving groups, no relevant MOVE, ADD or SUBTRACT is generated: this is in accordance with ANSI defined behavior.

Parent topic: COBCH1141 - COBCH1160


COBCH1150 Redefinition of internal floating-point item. Might not be portable

Parent topic: COBCH1141 - COBCH1160


COBCH1151 Forward overlapping move might produce unpredictable results

You have specified a MOVE to a target whose starting position is before the ending position of the source data item.
Parent topic: COBCH1141 - COBCH1160


COBCH1152 Comparison involving floating point data might not be portable

Parent topic: COBCH1141 - COBCH1160


COBCH1153 Some mainframe values for this data-type cannot be handled on PC

Parent topic: COBCH1141 - COBCH1160


COBCH1154 PC allows values for this data-type that cannot be handled on mainframes

Parent topic: COBCH1141 - COBCH1160


COBCH1155 Both PANVALET and LIBRARIAN specified - not mainframe compatible

Parent topic: COBCH1141 - COBCH1160


COBCH1156 BLOCK or LABEL clause in SD not allowed. Ignored

Parent topic: COBCH1141 - COBCH1160


COBCH1157 JUSTIFIED specified on edited field

Parent topic: COBCH1141 - COBCH1160


COBCH1158 CBL PROCESS *CBL or *CONTROL record encountered. Directives ignored

Parent topic: COBCH1141 - COBCH1160


COBCH1159 Portion of name following first "-" treated as documentary.

Parent topic: COBCH1141 - COBCH1160


COBCH1160 Changes before first statement cannot be checked. Ignored

Parent topic: COBCH1141 - COBCH1160


COBCH1161 - COBCH1180

Lists the Syntax Checking error messages from COBCH1161 through COBCH1180.

  • COBCH1161 Paragraph/section definition has changed. Ignored
  • COBCH1162 Attempt to define item as procedure. Ignored
  • COBCH1163 Animator restriction - can't check this statement
  • COBCH1164 Too many basic blocks for TESTCOVER to work
    The limit of 65535 basic blocks per program has been exceeded.
  • COBCH1165 GIVING option treated as documentary
  • COBCH1166 BLANK WHEN ZERO phrase ignored
  • COBCH1167 Use of COMP-5 data type
  • COBCH1168 COMP-5 redefinition
    You have redefined a COMP-5 data item. Porting your code to other environments might produce inconsistent results.
  • COBCH1169 Reference modification on a COMP-5 item
    You have used reference modification on a COMP-5 data item. Porting your code to other environments might produce inconsistent results.
  • COBCH1170 A non-integer operand cannot be compared with a nonnumeric operand
  • COBCH1171 Numeric class test on a group containing a signed numeric item
  • COBCH1172 Improper BLL Cell List item
  • COBCH1173 BLL Cell Addressability invalid
  • COBCH1174 Comparison of numeric literal with numeric literal
  • COBCH1175 Synchronization non-optimal
  • COBCH1176 Literal is greater in length than data item
    When compiling with mainframe dialects, this warning is produced when a data item is compared with a literal of greater length.
  • COBCH1177 Operand %1$s ambiguous in corresponding source
  • COBCH1178 Nonnumeric literal has length of zero.
    When compiling for managed code, use of a zero-length literal is flagged as a Micro Focus language extension. When compiling for native code, the use of such a literal results in warning message 1010, and the literal is converted to a single character space.
  • COBCH1179 Integer specified in the RESERVE clause was not in the range 1 to 255
Parent topic: Messages COBCH1101 to COBCH1200


COBCH1161 Paragraph/section definition has changed. Ignored

Parent topic: COBCH1161 - COBCH1180


COBCH1162 Attempt to define item as procedure. Ignored

Parent topic: COBCH1161 - COBCH1180


COBCH1163 Animator restriction - can't check this statement

Parent topic: COBCH1161 - COBCH1180


COBCH1164 Too many basic blocks for TESTCOVER to work

The limit of 65535 basic blocks per program has been exceeded.

The number of blocks must be reduced for Test Coverage to work on the program.

Parent topic: COBCH1161 - COBCH1180


COBCH1165 GIVING option treated as documentary

Parent topic: COBCH1161 - COBCH1180


COBCH1166 BLANK WHEN ZERO phrase ignored

Parent topic: COBCH1161 - COBCH1180


COBCH1167 Use of COMP-5 data type

Parent topic: COBCH1161 - COBCH1180


COBCH1168 COMP-5 redefinition

You have redefined a COMP-5 data item. Porting your code to other environments might produce inconsistent results.
Parent topic: COBCH1161 - COBCH1180


COBCH1169 Reference modification on a COMP-5 item

You have used reference modification on a COMP-5 data item. Porting your code to other environments might produce inconsistent results.
Parent topic: COBCH1161 - COBCH1180


COBCH1170 A non-integer operand cannot be compared with a nonnumeric operand

Parent topic: COBCH1161 - COBCH1180


COBCH1171 Numeric class test on a group containing a signed numeric item

Parent topic: COBCH1161 - COBCH1180


COBCH1172 Improper BLL Cell List item

Parent topic: COBCH1161 - COBCH1180


COBCH1173 BLL Cell Addressability invalid

Parent topic: COBCH1161 - COBCH1180


COBCH1174 Comparison of numeric literal with numeric literal

Parent topic: COBCH1161 - COBCH1180


COBCH1175 Synchronization non-optimal

Parent topic: COBCH1161 - COBCH1180


COBCH1176 Literal is greater in length than data item

When compiling with mainframe dialects, this warning is produced when a data item is compared with a literal of greater length.

Resolution:

Correct the length of the literal and/or data item as required; then recompile.

Example:

In the following example, the X1 data item is shorter than the literal string provided for the test, ABC. Increase the size of the X1 data item to accommodate the ABC literal.

      $set warning(2) vsc2
       01 x1 pic x(2).
       01 n1 pic 9(2).
           if x1 = "ABC"
               display "Possibly"
           end-if
           if n1 = 123
               display "Possibly"
           end-if
Parent topic: COBCH1161 - COBCH1180


COBCH1177 Operand %1$s ambiguous in corresponding source

Resolution:

Parent topic: COBCH1161 - COBCH1180


COBCH1178 Nonnumeric literal has length of zero.

When compiling for managed code, use of a zero-length literal is flagged as a Micro Focus language extension. When compiling for native code, the use of such a literal results in warning message 1010, and the literal is converted to a single character space.

Resolution:

When compiling for managed code, you must change the length of the nonnumeric literal to a value greater than zero. Do the same when compiling for native code unless you intend that the zero-length literal be converted to a single space character.

Example:

In the following example, the move statement contains a zero-length literal. When compiling for native code, a single-space character is moved to the X1 data item. If this is not the desired behavior, you must change the code.

       identification division.
       program-id. err1178.
       data division.
       working-storage section.
       01 x1 pic x(10).
       procedure division.
       p1.
           move "" to x1
           if x1 = space
               display "Pass"
           end-if
           .
Parent topic: COBCH1161 - COBCH1180


COBCH1179 Integer specified in the RESERVE clause was not in the range 1 to 255

Resolution:

Parent topic: COBCH1161 - COBCH1180


COBCH1181 - COBCH1200

Lists the Syntax Checking error messages from COBCH1181 through COBCH1200.

  • COBCH1181 Operand "%1_s" should be numeric
  • COBCH1182 Comparison between two ALL literals is not allowed
  • COBCH1183 EXAMINE TALLYING requires the TALLY special register_
  • COBCH1184 CBL PROCESS record invalid here
    A CBL PROCESS record has been encountered in the source at a location that IBM mainframe compilers will not accept by default.
Parent topic: Messages COBCH1101 to COBCH1200


COBCH1181 Operand "%1_s" should be numeric

Parent topic: COBCH1181 - COBCH1200


COBCH1182 Comparison between two ALL literals is not allowed

Parent topic: COBCH1181 - COBCH1200


COBCH1183 EXAMINE TALLYING requires the TALLY special register_

Parent topic: COBCH1181 - COBCH1200


COBCH1184 CBL PROCESS record invalid here

A CBL PROCESS record has been encountered in the source at a location that IBM mainframe compilers will not accept by default.

However, if you are using certain software, for example ChangeMan ZMF, to allow such a setup, use the HIDEMESSAGE(1184) or equivalent CHANGEMESSAGE directives to suppress the message during compilation.

Parent topic: COBCH1181 - COBCH1200
Related concepts
CHANGE-MESSAGE
HIDE-MESSAGE


Messages COBCH1201 to COBCH1300

  • COBCH1201 - COBCH1220
    Lists the Syntax Checking error messages from COBCH1201 through COBCH1220.
  • COBCH1221 - COBCH1240
    Lists the Syntax Checking error messages from COBCH1221 through COBCH1240.
  • COBCH1241 - COBCH1260
    Lists the Syntax Checking error messages from COBCH1241 through COBCH1260.
  • COBCH1261 - COBCH1280
    Lists the Syntax Checking error messages from COBCH1261 through COBCH1280.
Parent topic: Syntax Checking Error Messages


COBCH1201 - COBCH1220

Lists the Syntax Checking error messages from COBCH1201 through COBCH1220.

  • COBCH1201 Zero suppression PICTURE string overrides the BLANK WHEN ZERO clause
  • COBCH1202 Original item is larger than redefinition (size1 > size2)
  • COBCH1203 LABEL clause processed as comment
  • COBCH1204 BLOCK CONTAINS clause processed as comment
  • COBCH1205 Previous paragraph or section contains no statements
  • COBCH1206 Procedure Division does not start with a section
  • COBCH1207 Original item is smaller than redefinition (size1 < size2)
  • COBCH1208 USE clause omitted
  • COBCH1209 COMP-5 is machine specific format. (Future occurrences not indicated)
  • COBCH1210 COMP processed as usage (future occurrences not indicated)
    This informational message is generated when COMPUTATIONAL or COMP usage in a data description entry is not processed as BINARY usage.
  • COBCH1211 COMP-6 processed as COMP (future occurrences not indicated)
  • COBCH1212 COMP-1 processed as PIC S9(4) COMP (future occurrences not indicated)
  • COBCH1213 COMP-0 field exceeds S9(5), converted to USAGE DISPLAY
  • COBCH1214 COMP-0 processed as PIC S9(4) COMP (future occurrences not indicated)
  • COBCH1215 UNIT phrase processed as comment
  • COBCH1216 Literal exceeds 160 characters
  • COBCH1217 procedure-name same as level 78 name
  • COBCH1218 RERUN clause processed as comment
  • COBCH1219 No REPLACE currently in effect
  • COBCH1220 COMP-4 processed as PIC S9(9) COMP (future occurrences not indicated)
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1201 Zero suppression PICTURE string overrides the BLANK WHEN ZERO clause

Parent topic: COBCH1201 - COBCH1220


COBCH1202 Original item is larger than redefinition (size1 > size2)

Parent topic: COBCH1201 - COBCH1220


COBCH1203 LABEL clause processed as comment

Parent topic: COBCH1201 - COBCH1220


COBCH1204 BLOCK CONTAINS clause processed as comment

Parent topic: COBCH1201 - COBCH1220


COBCH1205 Previous paragraph or section contains no statements

Parent topic: COBCH1201 - COBCH1220


COBCH1206 Procedure Division does not start with a section

Parent topic: COBCH1201 - COBCH1220


COBCH1207 Original item is smaller than redefinition (size1 < size2)

Parent topic: COBCH1201 - COBCH1220


COBCH1208 USE clause omitted

Parent topic: COBCH1201 - COBCH1220


COBCH1209 COMP-5 is machine specific format. (Future occurrences not indicated)

Parent topic: COBCH1201 - COBCH1220


COBCH1210 COMP processed as usage (future occurrences not indicated)

This informational message is generated when COMPUTATIONAL or COMP usage in a data description entry is not processed as BINARY usage.
This message is generated only for the first instance of the COMPUTATIONAL or COMP usage in the source file. The message contains only the usage in effect for COMPUTATIONAL or COMP usage, that is, one of DISPLAY, PACKED-DECIMAL or UNPACKED-DECIMAL.
Note: UNPACKED-DECIMAL is not a usage that can be explicitly specified in a data description entry; UNPACKED-DECIMAL can only be specified by specifying COMP"UNPACKED" and using the COMPUTATIONAL or COMP usage in a data description entry.

COMPUTATIONAL or COMP usage in a data description entry is normally processed as BINARY usage. The COMP directive can specify DISPLAY, PACKED or UNPACKED for COMP usage to provide compatibility with other COBOL dialects. The DIALECT directives may cause one of these alternative forms for COMP usage to be chosen. For example DIALECT"RM" causes UNPACKED to be chosen and the MS directive causes DISPLAY to be chosen.

Parent topic: COBCH1201 - COBCH1220
Related tasks
COMP


COBCH1211 COMP-6 processed as COMP (future occurrences not indicated)

Parent topic: COBCH1201 - COBCH1220


COBCH1212 COMP-1 processed as PIC S9(4) COMP (future occurrences not indicated)

Parent topic: COBCH1201 - COBCH1220


COBCH1213 COMP-0 field exceeds S9(5), converted to USAGE DISPLAY

Parent topic: COBCH1201 - COBCH1220


COBCH1214 COMP-0 processed as PIC S9(4) COMP (future occurrences not indicated)

Parent topic: COBCH1201 - COBCH1220


COBCH1215 UNIT phrase processed as comment

Parent topic: COBCH1201 - COBCH1220


COBCH1216 Literal exceeds 160 characters

Parent topic: COBCH1201 - COBCH1220


COBCH1217 procedure-name same as level 78 name

Parent topic: COBCH1201 - COBCH1220


COBCH1218 RERUN clause processed as comment

Parent topic: COBCH1201 - COBCH1220


COBCH1219 No REPLACE currently in effect

Parent topic: COBCH1201 - COBCH1220


COBCH1220 COMP-4 processed as PIC S9(9) COMP (future occurrences not indicated)

Parent topic: COBCH1201 - COBCH1220


COBCH1221 - COBCH1240

Lists the Syntax Checking error messages from COBCH1221 through COBCH1240.

  • COBCH1221 COMP-4 field exceeds S9(10), converted to USAGE DISPLAY
  • COBCH1222 COMP-3 unsigned, converted to signed COMP-3
  • COBCH1223 BLANK WHEN ZERO clause overrides the zero suppression PICTURE string
  • COBCH1224 MEMORY SIZE clause processed as comment
    The MEMORY SIZE clause is treated as documentary.
  • COBCH1225 MULTIPLE FILE TAPE clause processed as comment
    The MULTIPLE FILE TAPE clause is treated as documentary.
  • COBCH1226 COMMON can only be used in nested program - processed as comment
    The program defined as COMMON is a main program, not a nested program.
  • COBCH1227 Scope terminator value generated implicitly
  • COBCH1228 Word non-portable; reserved in OS/400
  • COBCH1229 Word non-portable; reserved in VSC2(3)
  • COBCH1230 Word non-portable; reserved in OS/2 COBOL
  • COBCH1231 Syntax is non-conforming SAA
  • COBCH1232 Use of early-release MF syntax
  • COBCH1233 item directive or parameter is early-release
  • COBCH1234 item is CORRESPONDING item in statement
  • COBCH1235 Conflicting definition of level 78 item item
  • COBCH1236 Duplicate, equivalent definition of level 78 item
  • COBCH1237 File handling used with REENTRANT directive
    File handling syntax has been used in a COBOL program that also has the REENTRANT Compiler directive set.
  • COBCH1238 Conflict with REENTRANT directive and user code or other directives
    The Compiler has rejected the REENTRANT directive as it contains syntax that is not compatible with reentrant programs.
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1221 COMP-4 field exceeds S9(10), converted to USAGE DISPLAY

Parent topic: COBCH1221 - COBCH1240


COBCH1222 COMP-3 unsigned, converted to signed COMP-3

Parent topic: COBCH1221 - COBCH1240


COBCH1223 BLANK WHEN ZERO clause overrides the zero suppression PICTURE string

Parent topic: COBCH1221 - COBCH1240


COBCH1224 MEMORY SIZE clause processed as comment

The MEMORY SIZE clause is treated as documentary.
Parent topic: COBCH1221 - COBCH1240


COBCH1225 MULTIPLE FILE TAPE clause processed as comment

The MULTIPLE FILE TAPE clause is treated as documentary.
Parent topic: COBCH1221 - COBCH1240


COBCH1226 COMMON can only be used in nested program - processed as comment

The program defined as COMMON is a main program, not a nested program.
Parent topic: COBCH1221 - COBCH1240


COBCH1227 Scope terminator value generated implicitly

Parent topic: COBCH1221 - COBCH1240


COBCH1228 Word non-portable; reserved in OS/400

Parent topic: COBCH1221 - COBCH1240


COBCH1229 Word non-portable; reserved in VSC2(3)

Parent topic: COBCH1221 - COBCH1240


COBCH1230 Word non-portable; reserved in OS/2 COBOL

Parent topic: COBCH1221 - COBCH1240


COBCH1231 Syntax is non-conforming SAA

Parent topic: COBCH1221 - COBCH1240


COBCH1232 Use of early-release MF syntax

Parent topic: COBCH1221 - COBCH1240


COBCH1233 item directive or parameter is early-release

Parent topic: COBCH1221 - COBCH1240


COBCH1234 item is CORRESPONDING item in statement

Parent topic: COBCH1221 - COBCH1240


COBCH1235 Conflicting definition of level 78 item item

Parent topic: COBCH1221 - COBCH1240


COBCH1236 Duplicate, equivalent definition of level 78 item

Parent topic: COBCH1221 - COBCH1240


COBCH1237 File handling used with REENTRANT directive

File handling syntax has been used in a COBOL program that also has the REENTRANT Compiler directive set.

The two things are mutually exclusive, and you must remove one or the other.

Parent topic: COBCH1221 - COBCH1240


COBCH1238 Conflict with REENTRANT directive and user code or other directives

The Compiler has rejected the REENTRANT directive as it contains syntax that is not compatible with reentrant programs.

The REENTRANT directive is rejected if the program contains any of the following syntax elements:

  • ALTER statements
  • Debug facility (SOURCE-COMPUTER...WITH DEBUGGING)
  • ON statements
  • Segmentation
  • Any of the following directives:
    • PROTECT-LINKAGE
    • STICKY-LINKAGE
    • STICK-PERFORM

Also, if you are using the PROGRAM-ID. … IS INITIAL statement, you cannot use REENTRANT"1", and can only use REENTRANT "2" if the program does not contain nested programs.

Parent topic: COBCH1221 - COBCH1240
Related reference
REENTRANT


COBCH1241 - COBCH1260

Lists the Syntax Checking error messages from COBCH1241 through COBCH1260.

  • COBCH1241 Results incompatible with BS2000 if src table length > dest table length
    A table SORT containing a USING phrase gives different run-time results to Siemens BS2000 when there are more elements in the source table than can be contained in the destination table.
  • COBCH1242 USAGE must be DISPLAY for entries in a group with VALUE clause
  • COBCH1243 Non-positive value changed to 1
  • COBCH1244 WITH NO ADVANCING phrase has no effect for CONSOLE device
  • COBCH1245 Should be in upper case
    A call to a COBOL run-time library routine (where the name begins CBL_) has been specified partly or all in lower case. This is not portable and will not work on operating systems where names are case-sensitive.
  • COBCH1246 One or more operands are missing and have taken a default value of 1
    A reference to a table item has fewer subscripts than dimensions. Additional subscripts are assumed, all taking the default value 1.
  • COBCH1247 Truncated MOVE. Source length (length) exceeds target length (length)
  • COBCH1248 Function argument invalid, date YYYYMMDD must be greater than 15821014
  • COBCH1249 Function argument invalid, date YYYYDDD must be greater than 1582287
  • COBCH1250 Use of intrinsic funtion module or function not in selected dialect.
  • COBCH1251 Results incompatible with BS2000 if src table length > dest table length
  • COBCH1252 Requires an abstract machine level of 4 or greater
  • COBCH1253 THRU not allowed with boolean items
  • COBCH1254 Job variable name is too long
    Siemens BS2000 Job variable names are limited to 10 characters.
  • COBCH1255 Literal exceeds 180 characters
    Using the Siemens BS2000 dialect, the maximum allowable length of a literal is 180 characters.
  • COBCH1256 -INC name terminated by a period
  • COBCH1257 Reference modified item should be USAGE DISPLAY
  • COBCH1258 Must be declared in LINKAGE, WORKING-STORAGE or LOCAL-STORAGE SECTION
  • COBCH1259 GO TO target outside current section
    A GO TO statement has attempted to change control to outside of the current section.
  • COBCH1300 Expected Interface name.
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1241 Results incompatible with BS2000 if src table length > dest table length

A table SORT containing a USING phrase gives different run-time results to Siemens BS2000 when there are more elements in the source table than can be contained in the destination table.
Parent topic: COBCH1241 - COBCH1260


COBCH1242 USAGE must be DISPLAY for entries in a group with VALUE clause

Parent topic: COBCH1241 - COBCH1260


COBCH1243 Non-positive value changed to 1

Parent topic: COBCH1241 - COBCH1260


COBCH1244 WITH NO ADVANCING phrase has no effect for CONSOLE device

Parent topic: COBCH1241 - COBCH1260


COBCH1245 Should be in upper case

A call to a COBOL run-time library routine (where the name begins CBL_) has been specified partly or all in lower case. This is not portable and will not work on operating systems where names are case-sensitive.
Parent topic: COBCH1241 - COBCH1260


COBCH1246 One or more operands are missing and have taken a default value of 1

A reference to a table item has fewer subscripts than dimensions. Additional subscripts are assumed, all taking the default value 1.
Parent topic: COBCH1241 - COBCH1260


COBCH1247 Truncated MOVE. Source length (length) exceeds target length (length)

Parent topic: COBCH1241 - COBCH1260


COBCH1248 Function argument invalid, date YYYYMMDD must be greater than 15821014

Parent topic: COBCH1241 - COBCH1260


COBCH1249 Function argument invalid, date YYYYDDD must be greater than 1582287

Parent topic: COBCH1241 - COBCH1260


COBCH1250 Use of intrinsic funtion module or function not in selected dialect.

Parent topic: COBCH1241 - COBCH1260


COBCH1251 Results incompatible with BS2000 if src table length > dest table length

Resolution:

Parent topic: COBCH1241 - COBCH1260


COBCH1252 Requires an abstract machine level of 4 or greater

Parent topic: COBCH1241 - COBCH1260


COBCH1253 THRU not allowed with boolean items

Parent topic: COBCH1241 - COBCH1260


COBCH1254 Job variable name is too long

Siemens BS2000 Job variable names are limited to 10 characters.
Parent topic: COBCH1241 - COBCH1260


COBCH1255 Literal exceeds 180 characters

Using the Siemens BS2000 dialect, the maximum allowable length of a literal is 180 characters.
Parent topic: COBCH1241 - COBCH1260


COBCH1256 -INC name terminated by a period

Resolution:

Parent topic: COBCH1241 - COBCH1260


COBCH1257 Reference modified item should be USAGE DISPLAY

Resolution:

Parent topic: COBCH1241 - COBCH1260


COBCH1258 Must be declared in LINKAGE, WORKING-STORAGE or LOCAL-STORAGE SECTION

Resolution:

Parent topic: COBCH1241 - COBCH1260


COBCH1259 GO TO target outside current section

A GO TO statement has attempted to change control to outside of the current section.

The RESTRICT-GOTO Compiler directive switches on this behavior. To allow GO TO statements to transfer control to another section, remove the directive.

Parent topic: COBCH1241 - COBCH1260
Related concepts
RESTRICT-GOTO


COBCH1300 Expected Interface name.

Parent topic: COBCH1241 - COBCH1260


COBCH1261 - COBCH1280

Lists the Syntax Checking error messages from COBCH1261 through COBCH1280.

  • COBCH1261 Conversion operator must have mutually incompatible parameter and return type
  • COBCH1262 A method without a returning item cannot be a source operand
  • COBCH1263 PARAMS may only be specified for a single dimensional array as the last parameter
  • COBCH1264 Only '_' and 'NOT _' allowed for comparisons with NULL
  • COBCH1265 Cannot compare a value type with NULL
  • COBCH1266 Incompatible options specified, %1_s and %2_s
  • COBCH1267 Can only INVOKE self__new or super__new as first statement in constructor
  • COBCH1268 A static file cannot reference instance items
  • COBCH1269 Visibility attributes cannot be used with local data
  • COBCH1270 SIZE OF operator can only be used with single-dimensional managed arrays, strings or collections
    An attempt has been made to use the SIZE OF operator on an element that is not a single-dimensional managed array, a string, or a collection.
Parent topic: Messages COBCH1201 to COBCH1300


COBCH1261 Conversion operator must have mutually incompatible parameter and return type

Parent topic: COBCH1261 - COBCH1280


COBCH1262 A method without a returning item cannot be a source operand

Parent topic: COBCH1261 - COBCH1280


COBCH1263 PARAMS may only be specified for a single dimensional array as the last parameter

Parent topic: COBCH1261 - COBCH1280


COBCH1264 Only '_' and 'NOT _' allowed for comparisons with NULL

Parent topic: COBCH1261 - COBCH1280


COBCH1265 Cannot compare a value type with NULL

Parent topic: COBCH1261 - COBCH1280


COBCH1266 Incompatible options specified, %1_s and %2_s

Parent topic: COBCH1261 - COBCH1280


COBCH1267 Can only INVOKE self__new or super__new as first statement in constructor

Parent topic: COBCH1261 - COBCH1280


COBCH1268 A static file cannot reference instance items

Parent topic: COBCH1261 - COBCH1280


COBCH1269 Visibility attributes cannot be used with local data

Parent topic: COBCH1261 - COBCH1280


COBCH1270 SIZE OF operator can only be used with single-dimensional managed arrays, strings or collections

An attempt has been made to use the SIZE OF operator on an element that is not a single-dimensional managed array, a string, or a collection.

See the size-of-expression section for details of its syntax usage.

Parent topic: COBCH1261 - COBCH1280


Messages COBCH1301 to COBCH1400

  • COBCH1301 - COBCH1320
    Lists the Syntax Checking error messages from COBCH1301 through COBCH1320.
  • COBCH1321 - COBCH1340
    Lists the Syntax Checking error messages from COBCH1321 through COBCH1340.
Parent topic: Syntax Checking Error Messages


COBCH1301 - COBCH1320

Lists the Syntax Checking error messages from COBCH1301 through COBCH1320.

  • COBCH1301 Expected Class name.
  • COBCH1302 Expected Class or Interface name.
  • COBCH1303 PROPERTY clause only allowed in Object or Factory.
  • COBCH1304 Method not found in the repository.
  • COBCH1305 Universal Object Reference is not allowed.
  • COBCH1306 Redefintion of an Object Reference is illegal.
  • COBCH1307 Object Reference with REDEFINES clause is illegal.
  • COBCH1308 VALUE clause is illegal with Object Reference or Pointer.
  • COBCH1309 INPUT-OUTPUT section not allowed.
  • COBCH1310 Not allowed in a FACTORY or OBJECT definition.
  • COBCH1311 Not allowed in a METHOD definition.
  • COBCH1312 Not allowed in the outer level of a Class Definition.
  • COBCH1313 Not allowed in an INTERFACE definition.
  • COBCH1314 LOCK MODE clause must be specified in the File Control Entry.
  • COBCH1315 Illegal use of floating-point item %1_s
  • COBCH1316 Non-integer moved to alphanumeric item %1_s
  • COBCH1317 Method '%1_s' not found in this class_
  • COBCH1318 Cannot resolve forward reference of method in an inline invoke_
  • COBCH1319 Clause from the REPOSITORY paragraph expected_
  • COBCH1320 HOSTNUMCOMPARE(1)_HOSTNUMMOVE(1) may be removed in future releases
Parent topic: Messages COBCH1301 to COBCH1400


COBCH1301 Expected Class name.

Parent topic: COBCH1301 - COBCH1320


COBCH1302 Expected Class or Interface name.

Parent topic: COBCH1301 - COBCH1320


COBCH1303 PROPERTY clause only allowed in Object or Factory.

Parent topic: COBCH1301 - COBCH1320


COBCH1304 Method not found in the repository.

Parent topic: COBCH1301 - COBCH1320


COBCH1305 Universal Object Reference is not allowed.

Parent topic: COBCH1301 - COBCH1320


COBCH1306 Redefintion of an Object Reference is illegal.

Parent topic: COBCH1301 - COBCH1320


COBCH1307 Object Reference with REDEFINES clause is illegal.

Parent topic: COBCH1301 - COBCH1320


COBCH1308 VALUE clause is illegal with Object Reference or Pointer.

Parent topic: COBCH1301 - COBCH1320


COBCH1309 INPUT-OUTPUT section not allowed.

Parent topic: COBCH1301 - COBCH1320


COBCH1310 Not allowed in a FACTORY or OBJECT definition.

Parent topic: COBCH1301 - COBCH1320


COBCH1311 Not allowed in a METHOD definition.

Parent topic: COBCH1301 - COBCH1320


COBCH1312 Not allowed in the outer level of a Class Definition.

Parent topic: COBCH1301 - COBCH1320


COBCH1313 Not allowed in an INTERFACE definition.

Parent topic: COBCH1301 - COBCH1320


COBCH1314 LOCK MODE clause must be specified in the File Control Entry.

Parent topic: COBCH1301 - COBCH1320


COBCH1315 Illegal use of floating-point item %1_s

Parent topic: COBCH1301 - COBCH1320


COBCH1316 Non-integer moved to alphanumeric item %1_s

Parent topic: COBCH1301 - COBCH1320


COBCH1317 Method '%1_s' not found in this class_

Parent topic: COBCH1301 - COBCH1320


COBCH1318 Cannot resolve forward reference of method in an inline invoke_

Parent topic: COBCH1301 - COBCH1320


COBCH1319 Clause from the REPOSITORY paragraph expected_

Parent topic: COBCH1301 - COBCH1320


COBCH1320 HOSTNUMCOMPARE(1)_HOSTNUMMOVE(1) may be removed in future releases

Parent topic: COBCH1301 - COBCH1320


COBCH1321 - COBCH1340

Lists the Syntax Checking error messages from COBCH1321 through COBCH1340.

  • COBCH1321 Cannot have REFERENCE to a value type - omit OBJECT REFERENCE_
  • COBCH1322 Cannot specify BEFORE or AFTER with TRAILING option_
  • COBCH1323 Cannot mix TRAILING option with other INSPECT phrases_
  • COBCH1324 Invalid HANDLE field_
  • COBCH1325 WHEN OTHER follows other WHEN clause_
  • COBCH1326 Level 78 literal too long_
  • COBCH1327 Cannot specify PROPERTY subsidiary to PROPERTY ALL_
  • COBCH1328 Illegal use of national item %1$s
  • COBCH1329 Floating point usage incompatible with other languages
  • COBCH1330 A signed numeric national item must have a SIGN IS SEPARATE clause
Parent topic: Messages COBCH1301 to COBCH1400


COBCH1321 Cannot have REFERENCE to a value type - omit OBJECT REFERENCE_

Parent topic: COBCH1321 - COBCH1340


COBCH1322 Cannot specify BEFORE or AFTER with TRAILING option_

Parent topic: COBCH1321 - COBCH1340


COBCH1323 Cannot mix TRAILING option with other INSPECT phrases_

Parent topic: COBCH1321 - COBCH1340


COBCH1324 Invalid HANDLE field_

Parent topic: COBCH1321 - COBCH1340


COBCH1325 WHEN OTHER follows other WHEN clause_

Parent topic: COBCH1321 - COBCH1340


COBCH1326 Level 78 literal too long_

Parent topic: COBCH1321 - COBCH1340


COBCH1327 Cannot specify PROPERTY subsidiary to PROPERTY ALL_

Parent topic: COBCH1321 - COBCH1340


COBCH1328 Illegal use of national item %1$s

Resolution:

Parent topic: COBCH1321 - COBCH1340


COBCH1329 Floating point usage incompatible with other languages

Resolution:

Parent topic: COBCH1321 - COBCH1340


COBCH1330 A signed numeric national item must have a SIGN IS SEPARATE clause

Resolution:

Parent topic: COBCH1321 - COBCH1340


Messages COBCH1401 to COBCH1500

  • COBCH1401 - COBCH1420
    Lists the Syntax Checking error messages from COBCH1401 through COBCH1420.
  • COBCH1421 - COBCH1440
    Lists the Syntax Checking error messages from COBCH1421 through COBCH1440.
  • COBCH1441 - COBCH1460
    Lists the Syntax Checking error messages from COBCH1441 through COBCH1460.
  • COBCH1461 - COBCH1480
    Lists the Syntax Checking error messages from COBCH1461 through COBCH1480.
  • COBCH1481 - COBCH1500
    Lists the Syntax Checking error messages from COBCH1481 through COBCH1500.
Parent topic: Syntax Checking Error Messages


COBCH1401 - COBCH1420

Lists the Syntax Checking error messages from COBCH1401 through COBCH1420.

  • COBCH1401 OO_ Class '%1_s' can not inherit from itself_
  • COBCH1402 OO_ Class '%1_s' directly or indirectly inherits class '%2_s'_
  • COBCH1403 OO_ External name is illegal_
  • COBCH1404 OO_ Repository information for externalised class name '%1_s' not found_
  • COBCH1405 OO_ Externalised class name '%1_s' has FINAL clause and can not be inherited_
  • COBCH1406 OO_ Class name '%1_s' is not defined in the REPSOITORY paragraph_
  • COBCH1407 OO_ Interface name '%1_s' is not defined in the REPSOITORY paragraph_
  • COBCH1408 OO_ Class or Interface name '%1_s' is not defined in the REPSOITORY paragraph_
  • COBCH1409 OO_ EXPANDS phrase is illegal in a parameterised Class or Interface_
  • COBCH1410 OO_ The number of Actual parameters and Formal paramters is not the same_
  • COBCH1411 OO_ Expanded Class or Interface name '%1_s' is invalid_
  • COBCH1412 OO_ Expanded Class or Interface parameter name '%1_s' is invalid_
  • COBCH1413 OO_ Number of Expanded Class or Interface parameters do not match_
  • COBCH1414 OO_ Class or Interface name expected_
  • COBCH1415 OO_ Reserved word USING expected_
  • COBCH1416 OO_ There must be USING parameters_
  • COBCH1417 OO_ Method '%1_s' must not have the OVERRIDE clause_
  • COBCH1418 OO_ Method '%1_s' must have the OVERRIDE clause_
  • COBCH1419 OO_ Inherited method '%1_s' must not have the FINAL clause_
  • COBCH1420 OO_ Parameters of method '%1_s' do not conform _
Parent topic: Messages COBCH1401 to COBCH1500


COBCH1401 OO_ Class '%1_s' can not inherit from itself_

Parent topic: COBCH1401 - COBCH1420


COBCH1402 OO_ Class '%1_s' directly or indirectly inherits class '%2_s'_

Parent topic: COBCH1401 - COBCH1420


COBCH1403 OO_ External name is illegal_

Parent topic: COBCH1401 - COBCH1420


COBCH1404 OO_ Repository information for externalised class name '%1_s' not found_

Parent topic: COBCH1401 - COBCH1420


COBCH1405 OO_ Externalised class name '%1_s' has FINAL clause and can not be inherited_

Parent topic: COBCH1401 - COBCH1420


COBCH1406 OO_ Class name '%1_s' is not defined in the REPSOITORY paragraph_

Parent topic: COBCH1401 - COBCH1420


COBCH1407 OO_ Interface name '%1_s' is not defined in the REPSOITORY paragraph_

Parent topic: COBCH1401 - COBCH1420


COBCH1408 OO_ Class or Interface name '%1_s' is not defined in the REPSOITORY paragraph_

Parent topic: COBCH1401 - COBCH1420


COBCH1409 OO_ EXPANDS phrase is illegal in a parameterised Class or Interface_

Parent topic: COBCH1401 - COBCH1420


COBCH1410 OO_ The number of Actual parameters and Formal paramters is not the same_

Parent topic: COBCH1401 - COBCH1420


COBCH1411 OO_ Expanded Class or Interface name '%1_s' is invalid_

Parent topic: COBCH1401 - COBCH1420


COBCH1412 OO_ Expanded Class or Interface parameter name '%1_s' is invalid_

Parent topic: COBCH1401 - COBCH1420


COBCH1413 OO_ Number of Expanded Class or Interface parameters do not match_

Parent topic: COBCH1401 - COBCH1420


COBCH1414 OO_ Class or Interface name expected_

Parent topic: COBCH1401 - COBCH1420


COBCH1415 OO_ Reserved word USING expected_

Parent topic: COBCH1401 - COBCH1420


COBCH1416 OO_ There must be USING parameters_

Parent topic: COBCH1401 - COBCH1420


COBCH1417 OO_ Method '%1_s' must not have the OVERRIDE clause_

Parent topic: COBCH1401 - COBCH1420


COBCH1418 OO_ Method '%1_s' must have the OVERRIDE clause_

Parent topic: COBCH1401 - COBCH1420


COBCH1419 OO_ Inherited method '%1_s' must not have the FINAL clause_

Parent topic: COBCH1401 - COBCH1420


COBCH1420 OO_ Parameters of method '%1_s' do not conform _

Parent topic: COBCH1401 - COBCH1420


COBCH1421 - COBCH1440

Lists the Syntax Checking error messages from COBCH1421 through COBCH1440.

  • COBCH1421 OO_ Parameters of Method '%1_s' do not conform to Repository_
  • COBCH1422 OO_ Call Convention of '%1_s' does not match that in the Repository_
  • COBCH1423 OO_ Number of parameters of '%1_s' does not match Repository entry_
  • COBCH1424 OO_ The Prototype for Method '%1_s' was not found_
  • COBCH1425 OO_ Duplicated Internal Method name '%1_s'_
  • COBCH1426 OO_ Duplicated External Method name '%1_s'_
  • COBCH1427 OO_ Method_Function '%1_s" does not have a RETURNING clause defined_
  • COBCH1428 OO_ Method %1_s in interface %2_s not implemented_
  • COBCH1429 OO_ Method %1_s does not conform to that in class_interface %2_s
  • COBCH1430 PERFORM only allowed in TRY CATCH or SYNC block with PERFORMTYPE(MF)
    The program has been compiled using the PERFORM-TYPE directive with a parameter other than the default of MF, and contains an out-of-line perform statement within a TRY or SYNC block. This is not supported.
  • COBCH1431 Exception declarative only allowed with PERFORMTYPE(MF)
    The program has been compiled using the PERFORM-TYPE directive with a parameter other than the default of MF, and contains exception declaratives. This is not recommended.
Parent topic: Messages COBCH1401 to COBCH1500


COBCH1421 OO_ Parameters of Method '%1_s' do not conform to Repository_

Parent topic: COBCH1421 - COBCH1440


COBCH1422 OO_ Call Convention of '%1_s' does not match that in the Repository_

Parent topic: COBCH1421 - COBCH1440


COBCH1423 OO_ Number of parameters of '%1_s' does not match Repository entry_

Parent topic: COBCH1421 - COBCH1440


COBCH1424 OO_ The Prototype for Method '%1_s' was not found_

Parent topic: COBCH1421 - COBCH1440


COBCH1425 OO_ Duplicated Internal Method name '%1_s'_

Parent topic: COBCH1421 - COBCH1440


COBCH1426 OO_ Duplicated External Method name '%1_s'_

Parent topic: COBCH1421 - COBCH1440


COBCH1427 OO_ Method_Function '%1_s" does not have a RETURNING clause defined_

Parent topic: COBCH1421 - COBCH1440


COBCH1428 OO_ Method %1_s in interface %2_s not implemented_

Parent topic: COBCH1421 - COBCH1440


COBCH1429 OO_ Method %1_s does not conform to that in class_interface %2_s

Parent topic: COBCH1421 - COBCH1440


COBCH1430 PERFORM only allowed in TRY CATCH or SYNC block with PERFORMTYPE(MF)

The program has been compiled using the PERFORM-TYPE directive with a parameter other than the default of MF, and contains an out-of-line perform statement within a TRY or SYNC block. This is not supported.

Resolution:

Either edit the code to remove out-of-line perform statements within TRY and SYNC blocks and then recompile as before, or recompile using the default PERFORM-TYPE(MF) setting.

Example:

In the following example, remove the $set statement to invoke the default perform-type(mf) directive.

      $set perform-type(osvs)
           try
               perform p1
           catch e as type System.Exception
               display "In catch"
           end-try
           goback.

       p1.
           display "In performed paragraph"
Parent topic: COBCH1421 - COBCH1440


COBCH1431 Exception declarative only allowed with PERFORMTYPE(MF)

The program has been compiled using the PERFORM-TYPE directive with a parameter other than the default of MF, and contains exception declaratives. This is not recommended.

Resolution:

Edit the code to use the TRY/CATCH construct instead of exception declaratives; then recompile.

Example:

In the following example, remove the $set statement to invoke the default perform-type(mf) directive.

      $set perform-type(osvs)
       repository.
           class exception-class as "System.Exception".
       procedure division.
       declaratives.
       s1 section.
       use after exception exception-class.
           display "Hit exception"
       end declaratives.
       s2 section.
Parent topic: COBCH1421 - COBCH1440


COBCH1441 - COBCH1460

Lists the Syntax Checking error messages from COBCH1441 through COBCH1460.

  • COBCH1450 PIC 1 with CHARSET(EBCDIC) not supported
  • COBCH1451 Boolean with reference modification not supported
  • COBCH1452 MOVE of boolean to and from national not supported
  • COBCH1453 PIC 1 with VALUE FROM not supported
  • COBCH1454 PIC 1 with JUSTIFIED clause not supported
  • COBCH1455 Sliding items after PIC 1 table not supported
  • COBCH1456 Sliding PIC 1 items not supported
  • COBCH1457 PIC 1 fields > <num> not supported
  • COBCH1458 PIC 1 fields > <num> not supported. (Group-usage size: <num>)
  • COBCH1459 Only '=' and 'NOT =' allowed for boolean data items
  • COBCH1460 Arithmetic operator not allowed in boolean expression
Parent topic: Messages COBCH1401 to COBCH1500


COBCH1450 PIC 1 with CHARSET(EBCDIC) not supported

Boolean data items are only supported for ASCII environments.

Parent topic: COBCH1441 - COBCH1460


COBCH1451 Boolean with reference modification not supported

You cannot use reference modification on a boolean data item or a group item defined by the GROUP-USAGE BIT clause.

Parent topic: COBCH1441 - COBCH1460


COBCH1452 MOVE of boolean to and from national not supported

Boolean data items can only be moved to alphanumeric and alphanumeric-edited data items, and from alphanumeric data items.

Parent topic: COBCH1441 - COBCH1460


COBCH1453 PIC 1 with VALUE FROM not supported

You cannot define the values for the boolean elements of a table for a specified range of index values.

Parent topic: COBCH1441 - COBCH1460


COBCH1454 PIC 1 with JUSTIFIED clause not supported

The JUSTIFIED clause cannot be specified for boolean data items.

Parent topic: COBCH1441 - COBCH1460


COBCH1455 Sliding items after PIC 1 table not supported

If you use the ODOSLIDE directive, you cannot have boolean data items following a variable-length table in the same record; neither can you have data items following a variable-length table containing boolean data items.

Parent topic: COBCH1441 - COBCH1460


COBCH1456 Sliding PIC 1 items not supported

If you use the ODOSLIDE directive, you cannot have boolean data items following a variable-length table in the same record; neither can you have data items following a variable-length table containing boolean data items.

Parent topic: COBCH1441 - COBCH1460


COBCH1457 PIC 1 fields > <num> not supported

You have tried to define a boolean data item that is longer than the maximum allowed.

Parent topic: COBCH1441 - COBCH1460


COBCH1458 PIC 1 fields > <num> not supported. (Group-usage size: <num>)

You have tried to define a boolean data item that is longer than the maximum allowed.

Parent topic: COBCH1441 - COBCH1460


COBCH1459 Only '=' and 'NOT =' allowed for boolean data items

When comparing boolean items, you can only check whether the items are equal or unequal.

Parent topic: COBCH1441 - COBCH1460


COBCH1460 Arithmetic operator not allowed in boolean expression

Boolean expressions cannot contain the operators "+", "-", "/", "*", or "**".

Parent topic: COBCH1441 - COBCH1460


COBCH1461 - COBCH1480

Lists the Syntax Checking error messages from COBCH1461 through COBCH1480.

  • COBCH1461 To enable boolean literals BINLIT(BOOLEAN) must be specified
  • COBCH1462 KEY may not be of type boolean
  • COBCH1463 Boolean argument required
  • COBCH1464 Boolean argument not allowed
  • COBCH1465 Function BOOLEAN-OF-INTEGER, bit length needs to be an integer constant
  • COBCH1466 Boolean parameter must be aligned on a byte boundary
  • COBCH1467 Cannot pass boolean BY VALUE
  • COBCH1468 RETURNING boolean not supported
  • COBCH1480 Illegal use of condition name
Parent topic: Messages COBCH1401 to COBCH1500


COBCH1461 To enable boolean literals BINLIT(BOOLEAN) must be specified

Use the BINLIT directive to control whether binary b"" literals are interpreted as numeric values, or Boolean values for use with PIC 1 data items.

Parent topic: COBCH1461 - COBCH1480


COBCH1462 KEY may not be of type boolean

You cannot define a KEY to be a boolean data item.

Parent topic: COBCH1461 - COBCH1480


COBCH1463 Boolean argument required

This function must have a boolean argument.

Parent topic: COBCH1461 - COBCH1480


COBCH1464 Boolean argument not allowed

This function cannot have a boolean argument.

Parent topic: COBCH1461 - COBCH1480


COBCH1465 Function BOOLEAN-OF-INTEGER, bit length needs to be an integer constant

The BOOLEAN-OF-INTEGER function returns a boolean item of usage bit representing the binary equivalent of a value. The length of the returned value must be expressed as a positive nonzero integer or numeric constant.

Parent topic: COBCH1461 - COBCH1480


COBCH1466 Boolean parameter must be aligned on a byte boundary

Parent topic: COBCH1461 - COBCH1480


COBCH1467 Cannot pass boolean BY VALUE

Parent topic: COBCH1461 - COBCH1480


COBCH1468 RETURNING boolean not supported

Parent topic: COBCH1461 - COBCH1480


COBCH1480 Illegal use of condition name

Parent topic: COBCH1461 - COBCH1480


COBCH1481 - COBCH1500

Lists the Syntax Checking error messages from COBCH1481 through COBCH1500.

  • COBCH1481 Boundary violation_ Processed as maximum value (%1_s)
    A boundary violation has occurred because reference modification has referred to data beyond the boundaries of the base data item.
  • COBCH1482 Interface interface-name inherits from itself (directly or indirectly).
    An interface is attempting to inherit from itself either directly or via another interface.
  • COBCH1483 END METHOD for method method-name missing.
    The method identified in the message was not terminated with an END METHOD before the end of source was met.
  • COBCH1484 An indexer cannot be STATIC
    The program contains an indexer defined as a STATIC member. This is not allowed.
  • COBCH1485 Field field-name can only be modified inside class constructor
    The program contains a static field defined with the INITIALIZE ONLY phrase, and that is modified outside of a class constructor (new static) method. This is not allowed.
  • COBCH1486 Field field-name can only be modified inside constructor
    The program contains an instance field defined with the INITIALIZE ONLY phrase, and that is modified outside of a constructor (new) method.
  • COBCH1487 STATIC class can only include static data and methods
    The program contains a STATIC class that includes instance fields or instance methods. This is not allowed.
  • COBCH1488 This phrase may only be specified for managed fields
    The program contains a phrase that can only be specified for static or instance fields in a class program.
  • COBCH1489 Extension methods may only be defined in non-generic static classes
    The program contains an extension method that can only be defined in a static class that does not have generic parameters.
  • COBCH1490 Cannot redefine equality and inequality operators for string type
    The program specifies an extension operator for an = operator on a string or <> operators on a string. This is not allowed because these operators are provided as built-in extensions in JVM COBOL.
  • COBCH1491 Cannot redefine operators for primitive types
    The program redefines an extension operator for a primitive type such as binary-long (32 bit integer). This is not allowed.
  • COBCH1492 Ambiguous type name '%1_s, could refer to either '%2_s' or '%3_s'
    An ambiguous reference has been made to a type name that is found in two or more namespaces referenced in ILUSING directives.
  • COBCH1494 Method method-name cannot OVERRIDE an inherited method with different return type.
    The program contains a method that overrides another method in an inherited class, but has a different return type than the inherited method. This is not allowed.
  • COBCH1495 Class member '%1$s' cannot OVERRIDE parent member of different kind.
  • COBCH1498 Preprocessor file logic error
    A preprocessor has passed an incorrect or unexpected sequence of response codes.
  • COBCH1500 Memory allocation failure - module_ '%1_s'
Parent topic: Messages COBCH1401 to COBCH1500


COBCH1481 Boundary violation_ Processed as maximum value (%1_s)

A boundary violation has occurred because reference modification has referred to data beyond the boundaries of the base data item.

Example:

The following code will result in this error:

$SET VSC2(3)
 01 ITEM1 PIC X(256).
 01 ITEM2 PIC X(1).
      MOVE ITEM2(1:256) TO ITEM1.

Resolution:

Check your code for data items being manipulated with reference modification and ensure that either the data item being moved is of sufficient size or that the reference modification parameters are set correctly.

Parent topic: COBCH1481 - COBCH1500


COBCH1482 Interface interface-name inherits from itself (directly or indirectly).

An interface is attempting to inherit from itself either directly or via another interface.

Resolution:

Modify the code to correct the interface inheritance problem; then recompile.

Example:

In the following example, IMyInterface2 inherits itself indirectly because it inherits an interface (IMyInterface3) that inherits IMyInterface2. This is incorrect.

       interface-id IMyInterface1 inherits type IMyInterface1.
       end interface.
       interface-id IMyInterface2 inherits type IMyInterface3.
       end interface.
       interface-id IMyInterface3 inherits type IMyInterface2.
       end interface.
Parent topic: COBCH1481 - COBCH1500


COBCH1483 END METHOD for method method-name missing.

The method identified in the message was not terminated with an END METHOD before the end of source was met.

Resolution:

Add END METHOD sytax to properly terminate the METHOD; then recompile.

Example:

In the following example, the main static method is not terminated with end-method syntax. Add the end-method syntax.

       class-id a.
       method-id main static.
Parent topic: COBCH1481 - COBCH1500


COBCH1484 An indexer cannot be STATIC

The program contains an indexer defined as a STATIC member. This is not allowed.

Resolution:

Remove the STATIC specification on the indexer definition; then recompile.

Example:

In the following example, the indexer is incorrectly defined as static.

       class-id a.
       indexer-id string (#index as binary-long) static.
       getter.
           set property-value to "Hello"
       end indexer.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1485 Field field-name can only be modified inside class constructor

The program contains a static field defined with the INITIALIZE ONLY phrase, and that is modified outside of a class constructor (new static) method. This is not allowed.

Resolution:

Change the code to modify the static field inside of a class constructor, or make other appropriate code adjustments to eliminate the coding error.

Example:

In the following example, the MAIN static method, which is not a class constructor method, modifies the INIT-ONLY field. Because the INIT-ONLY field is defined with the INITIALIZE ONLY phrase, this is incorrect. The example also correctly shows the INIT-ONLY field modified by the NEW static method. This is correct because the NEW method is a class constuctor.

       class-id a.
       01 init-only string initialize only static.
       method-id main static.
           move "A" to init-only    *> Error
       end method.
       method-id new static.
           move "A" to init-only    *> Ok
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1486 Field field-name can only be modified inside constructor

The program contains an instance field defined with the INITIALIZE ONLY phrase, and that is modified outside of a constructor (new) method.

Resolution:

Change the code to modify the instance field inside of a constructor method, or make other appropriate code adjustments to eliminate the coding error.

Example:

In the following example, the M1 method, which is not a constructor method, modifies the INIT-ONLY field. Because the INIT-ONLY field is defined with the INITIALIZE ONLY phrase, this is incorrect. The example also correctly shows the INIT-ONLY field modified by the NEW method. This is correct because the NEW method is a constuctor method.

       class-id a.
       01 init-only string initialize only.
       method-id m1.
           move "A" to init-only    *> Error
       end method.
       method-id new.
           move "A" to init-only    *> Ok
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1487 STATIC class can only include static data and methods

The program contains a STATIC class that includes instance fields or instance methods. This is not allowed.

Resolution:

Remove instance fields and methods from the STATIC class.

Example:

In the following example of a static class definition, neither the Field1 string declaration nor the Inst1 method definition are static, and therefore must be removed from the static class definition.

       class-id a static.
       01 Field1 string.           *> Error
       01 Field2 string static.    *> Ok
       method-id Inst1.            *> Error
       end method.
       method-id Stat1 static.     *> Ok
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1488 This phrase may only be specified for managed fields

The program contains a phrase that can only be specified for static or instance fields in a class program.

Resolution:

Correct the code; then recompile.

Example:

The following example contains an illegal phrase.

       class-id a.
       method-id main static.
       01 x1 pic x(10) initialize only.
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1489 Extension methods may only be defined in non-generic static classes

The program contains an extension method that can only be defined in a static class that does not have generic parameters.

Resolution:

Recode the extension method as part of a static class that does not have generic parameters; then recompile.

Example:

In the following example,the MyExt extension method defined in class-id a static is correct because this static method does not have generic parameters. The MyExt defined in class-id b is incorrect because class-id b is not static. The MyExt defined in class-id c is incorrect because class-id c uses a generic parameter.

       class-id a static.
       method-id MyExt extension (s as string, i as binary-long).  *> ok
       end method.
       end class.
       class-id b.
       method-id MyExt extension (s as string, i as binary-long).  *> Error
       end method.
       end class.
       class-id c static using T.
       method-id MyExt extension (s as string, i as binary-long).  *> Error
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1490 Cannot redefine equality and inequality operators for string type

The program specifies an extension operator for an = operator on a string or <> operators on a string. This is not allowed because these operators are provided as built-in extensions in JVM COBOL.

Resolution:

Modify the code to eliminate the extension operator; then recompile.

Example:

In the following example, the operator-id extension operator definition is not allowed.

       class-id a static.
       operator-id = extension (s1 as string, s2 as string) returning ret as condition-value.
           set ret to s1 = s2
       end operator.
Parent topic: COBCH1481 - COBCH1500


COBCH1491 Cannot redefine operators for primitive types

The program redefines an extension operator for a primitive type such as binary-long (32 bit integer). This is not allowed.

Resolution:

Modify the code to eliminate the redefines of the extension operator; then recompile.

Example:

In the following example, the operator definition redefines a binary-long type. This is not allowed.

       class-id a static.
       operator-id + extension (i1 as binary-long, i2 as binary-long) returning ret as binary-long.
           set ret to i1 + i2
       end operator.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1492 Ambiguous type name '%1_s, could refer to either '%2_s' or '%3_s'

An ambiguous reference has been made to a type name that is found in two or more namespaces referenced in ILUSING directives.

Resolution:

To resolve the error, you can either:

  • Specify the fully qualified type name in the code.
  • Modify the names of the imported usings/projects, to ensure their namespaces are unique.
Parent topic: COBCH1481 - COBCH1500


COBCH1494 Method method-name cannot OVERRIDE an inherited method with different return type.

The program contains a method that overrides another method in an inherited class, but has a different return type than the inherited method. This is not allowed.

Resolution:

Correct the code such that the return type for both the overriding method and the inherited method match; then recompile

Example:

The following example shows that method M1 overrides a binary-long return type with a string return type. This is not allowed.

       class-id A1.
       method-id M1 returning ret as binary-long.
       end method.
       end class.
       class-id A2 inherits type A1.
       method-id M1 override returning ret as string.
       end method.
       end class.
Parent topic: COBCH1481 - COBCH1500


COBCH1495 Class member '%1$s' cannot OVERRIDE parent member of different kind.

Resolution:

Parent topic: COBCH1481 - COBCH1500


COBCH1498 Preprocessor file logic error

A preprocessor has passed an incorrect or unexpected sequence of response codes.

For example, there is no corresponding end of copybook code when the start of a copybook has been indicated.

Parent topic: COBCH1481 - COBCH1500


COBCH1500 Memory allocation failure - module_ '%1_s'

Parent topic: COBCH1481 - COBCH1500


Messages COBCH1501 to COBCH1600

  • COBCH1501 - COBCH1520
    Lists the Syntax Checking error messages from COBCH1501 through COBCH1520.
  • COBCH1521 - COBCH1540
    Lists the Syntax Checking error messages from COBCH1521 through COBCH1540.
  • COBCH1541 - COBCH1560
    Lists the Syntax Checking error messages from COBCH1541 through COBCH1560.
  • COBCH1561 - COBCH1580
    Lists the Syntax Checking error messages from COBCH1561 through COBCH1580.
  • COBCH1581 - COBCH1600
    Lists the Syntax Checking error messages from COBCH1581 through COBCH1600.
Parent topic: Syntax Checking Error Messages


COBCH1501 - COBCH1520

Lists the Syntax Checking error messages from COBCH1501 through COBCH1520.

  • COBCH1501 Insufficient memory
  • COBCH1502 Open fail _ '%1_s'
  • COBCH1503 Read error_ '%1_s'
  • COBCH1504 I-O error _ <file-status> <file-name>
    An I-O file handling operation has failed for <file-name>.
  • COBCH1505 I-O error _ IDY file
  • COBCH1506 Checker _ pointer or index invalid - module_ '%1_s'
  • COBCH1507 Illegal command line
  • COBCH1508 Unknown XFD directive_ '%1_s'
  • COBCH1509 Missing '_' in XFD directive
  • COBCH1510 XFD value should be a name_ %1_s
  • COBCH1511 XFD value should be numeric_ %1_s
  • COBCH1512 XFD value should be a literal_ %1_s
  • COBCH1513 GROUP expected after USE
  • COBCH1514 Date format missing
  • COBCH1515 Missing field name after WHEN
  • COBCH1516 Condition value too long (%1_s max)
  • COBCH1517 Invalid date format
  • COBCH1518 Field %1_s causes duplicate data data
  • COBCH1519 Too many AND_OR conditions (50 max)
    Your source code has exceeded the number of AND or OR conditions in a single XFD WHEN directive, or has exceeded the number of XFD WHEN directives allowed.
  • COBCH1520 Error - duplicate file name
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1501 Insufficient memory

Parent topic: COBCH1501 - COBCH1520


COBCH1502 Open fail _ '%1_s'

Issue

Failed to open file filename.

You may not have write permissions for the destination folder of the specified file, the folder may not exist or the disk space may be insufficient.

Parent topic: COBCH1501 - COBCH1520


COBCH1503 Read error_ '%1_s'

Parent topic: COBCH1501 - COBCH1520


COBCH1504 I-O error _ <file-status> <file-name>

An I-O file handling operation has failed for <file-name>.

The <file-status> corresponds to an extended file status code of the format 9/nnn (for example 9/181). You can usually cross-reference the second part of the status (181 to use the earlier example) with the definition of the corresponding run-time system error (for example, COBRT181) for more details.

Parent topic: COBCH1501 - COBCH1520
Related reference
Extended File Status Codes
Run-time System Error Messages


COBCH1505 I-O error _ IDY file

Parent topic: COBCH1501 - COBCH1520


COBCH1506 Checker _ pointer or index invalid - module_ '%1_s'

Parent topic: COBCH1501 - COBCH1520


COBCH1507 Illegal command line

Parent topic: COBCH1501 - COBCH1520


COBCH1508 Unknown XFD directive_ '%1_s'

Parent topic: COBCH1501 - COBCH1520


COBCH1509 Missing '_' in XFD directive

Parent topic: COBCH1501 - COBCH1520


COBCH1510 XFD value should be a name_ %1_s

Parent topic: COBCH1501 - COBCH1520


COBCH1511 XFD value should be numeric_ %1_s

Parent topic: COBCH1501 - COBCH1520


COBCH1512 XFD value should be a literal_ %1_s

Parent topic: COBCH1501 - COBCH1520


COBCH1513 GROUP expected after USE

Parent topic: COBCH1501 - COBCH1520


COBCH1514 Date format missing

Parent topic: COBCH1501 - COBCH1520


COBCH1515 Missing field name after WHEN

Parent topic: COBCH1501 - COBCH1520


COBCH1516 Condition value too long (%1_s max)

Parent topic: COBCH1501 - COBCH1520


COBCH1517 Invalid date format

Parent topic: COBCH1501 - COBCH1520


COBCH1518 Field %1_s causes duplicate data data

Parent topic: COBCH1501 - COBCH1520


COBCH1519 Too many AND_OR conditions (50 max)

Your source code has exceeded the number of AND or OR conditions in a single XFD WHEN directive, or has exceeded the number of XFD WHEN directives allowed.
Parent topic: COBCH1501 - COBCH1520


COBCH1520 Error - duplicate file name

Parent topic: COBCH1501 - COBCH1520


COBCH1521 - COBCH1540

Lists the Syntax Checking error messages from COBCH1521 through COBCH1540.

  • COBCH1521 Error - when field not found
  • COBCH1522 Error - internal XFD error 23
  • COBCH1523 Internal error - occurs inconsistency
  • COBCH1524 Error - invalid directive combination
  • COBCH1525 Error - XSL information too long
  • COBCH1526 Error - insufficient memory
  • COBCH1527 Internal error - not enough attributes (NO LONGER USED)
  • COBCH1528 File %1_s _ no matching field for condition %2_s
  • COBCH1529 Warning - directive word too long _ %1_s
  • COBCH1530 File %1_s _ variable filename requires "File" directive
  • COBCH1531 Warning - field %1_s causes duplicate database data
  • COBCH1532 Warning - field %1_s causes duplicate data
  • COBCH1533 Warning - %1_s not unique in first 30 characters
  • COBCH1534 File %1_s _ data missing from key segment %2_s
  • COBCH1535 File %1_s _ bad picture for date field %2_s
  • COBCH1536 XFD directive line continuation error - XFD directive ignored
  • COBCH1537 XFD WHEN directive mismatched parentheses
  • COBCH1538 XFD WHEN directive syntax error
  • COBCH1539 VALUE clause not allowed in conjunction with OCCURS ANY
  • COBCH1540 Only available with XMLPARSE(XMLSS) compiler option
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1521 Error - when field not found

Parent topic: COBCH1521 - COBCH1540


COBCH1522 Error - internal XFD error 23

Parent topic: COBCH1521 - COBCH1540


COBCH1523 Internal error - occurs inconsistency

Parent topic: COBCH1521 - COBCH1540


COBCH1524 Error - invalid directive combination

Parent topic: COBCH1521 - COBCH1540


COBCH1525 Error - XSL information too long

Parent topic: COBCH1521 - COBCH1540


COBCH1526 Error - insufficient memory

Parent topic: COBCH1521 - COBCH1540


COBCH1527 Internal error - not enough attributes (NO LONGER USED)

Parent topic: COBCH1521 - COBCH1540


COBCH1528 File %1_s _ no matching field for condition %2_s

Parent topic: COBCH1521 - COBCH1540


COBCH1529 Warning - directive word too long _ %1_s

Parent topic: COBCH1521 - COBCH1540


COBCH1530 File %1_s _ variable filename requires "File" directive

Parent topic: COBCH1521 - COBCH1540


COBCH1531 Warning - field %1_s causes duplicate database data

Parent topic: COBCH1521 - COBCH1540


COBCH1532 Warning - field %1_s causes duplicate data

Parent topic: COBCH1521 - COBCH1540


COBCH1533 Warning - %1_s not unique in first 30 characters

Parent topic: COBCH1521 - COBCH1540


COBCH1534 File %1_s _ data missing from key segment %2_s

Parent topic: COBCH1521 - COBCH1540


COBCH1535 File %1_s _ bad picture for date field %2_s

Parent topic: COBCH1521 - COBCH1540


COBCH1536 XFD directive line continuation error - XFD directive ignored

Parent topic: COBCH1521 - COBCH1540


COBCH1537 XFD WHEN directive mismatched parentheses

Parent topic: COBCH1521 - COBCH1540


COBCH1538 XFD WHEN directive syntax error

Parent topic: COBCH1521 - COBCH1540


COBCH1539 VALUE clause not allowed in conjunction with OCCURS ANY

Parent topic: COBCH1521 - COBCH1540


COBCH1540 Only available with XMLPARSE(XMLSS) compiler option

Parent topic: COBCH1521 - COBCH1540


COBCH1541 - COBCH1560

Lists the Syntax Checking error messages from COBCH1541 through COBCH1560.

  • COBCH1541 XML-SCHEMA %1_s missing or illegal
  • COBCH1542 ACU threading syntax is not supported
  • COBCH1543 This ACU syntax is not supported
  • COBCH1544 ACU ACCEPT_DISPLAY extension is not supported
  • COBCH1545 Feature not yet supported when compiling for JVM
  • COBCH1546 Not allowed with DELEGATE programs
  • COBCH1547 Constructors cannot have a RETURNING item
  • COBCH1548 A concatenation expression cannot be used as a receiving item
  • COBCH1549 Concatenation expression has too many operands
  • COBCH1550 FOR interface not implemented by this class
  • COBCH1551 Recursive use of TYPEDEF name
  • COBCH1552 Perform range too large or complex
  • COBCH1553 Warning - JVM classpath %1_s is ignored
  • COBCH1554 Error - More than 65535 statements in a paragraph. Cannot produce debugging information
    A paragraph in the program contains too many statements to produce a .IDY file, and therefore cannot be debugged.
  • COBCH1555 Cannot access object data declared in a containing class
    An attempt to access object data in a containing class has been made from a nested class.
  • COBCH1556 Invalid JVM runtime: Possibly due to mixing 32 and 64 bit support
    The JVM runtime could not be loaded.
  • COBCH1557 Failed to find JVM type subsystem
  • COBCH1558 Failed to start JVM
    The JVM runtime could not be loaded.
  • COBCH1559 JVM type support failed: Unexpected failure of operation during operation of type support
  • COBCH1560 JVM support not loaded: the mfjvmlib library could not be loaded
    The mfjvmlib class library could not be located.
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1541 XML-SCHEMA %1_s missing or illegal

Parent topic: COBCH1541 - COBCH1560


COBCH1542 ACU threading syntax is not supported

Parent topic: COBCH1541 - COBCH1560


COBCH1543 This ACU syntax is not supported

Parent topic: COBCH1541 - COBCH1560


COBCH1544 ACU ACCEPT_DISPLAY extension is not supported

Parent topic: COBCH1541 - COBCH1560


COBCH1545 Feature not yet supported when compiling for JVM

Parent topic: COBCH1541 - COBCH1560


COBCH1546 Not allowed with DELEGATE programs

Parent topic: COBCH1541 - COBCH1560


COBCH1547 Constructors cannot have a RETURNING item

Parent topic: COBCH1541 - COBCH1560


COBCH1548 A concatenation expression cannot be used as a receiving item

Parent topic: COBCH1541 - COBCH1560


COBCH1549 Concatenation expression has too many operands

Parent topic: COBCH1541 - COBCH1560


COBCH1550 FOR interface not implemented by this class

Parent topic: COBCH1541 - COBCH1560


COBCH1551 Recursive use of TYPEDEF name

Parent topic: COBCH1541 - COBCH1560


COBCH1552 Perform range too large or complex

Parent topic: COBCH1541 - COBCH1560


COBCH1553 Warning - JVM classpath %1_s is ignored

Parent topic: COBCH1541 - COBCH1560


COBCH1554 Error - More than 65535 statements in a paragraph. Cannot produce debugging information

A paragraph in the program contains too many statements to produce a .IDY file, and therefore cannot be debugged.

Restructure the program to reduce the number of statements in a single paragraph.

Parent topic: COBCH1541 - COBCH1560


COBCH1555 Cannot access object data declared in a containing class

An attempt to access object data in a containing class has been made from a nested class.

To access object data in a containing class, the nested class must specify the SHARING PARENT phrase.

class-id myContainingClass.
working-storage section.
01 i1 binary-long VALUE 1.
01 i2 string.

class-id myNestedClass1.
method-id myMethod1.
  set i2 to "abc".  *> this is incorrect
end method.
end class.

class-id myNestedClass2 sharing parent.
method-id myMethod2.
  set i1 to 123.  *> this is correct
end method.
end class.

end class.
Parent topic: COBCH1541 - COBCH1560


COBCH1556 Invalid JVM runtime: Possibly due to mixing 32 and 64 bit support

The JVM runtime could not be loaded.

Check that the JAVA_HOME environment variable is set to the appropriate runtime engine that your application is being compiled for.

Parent topic: COBCH1541 - COBCH1560


COBCH1557 Failed to find JVM type subsystem

Parent topic: COBCH1541 - COBCH1560


COBCH1558 Failed to start JVM

The JVM runtime could not be loaded.

Check that JAVA_HOME refers to a JDK or JRE of the same bitism as the current compilation mode. That is, if using cob32, JAVA_HOME must be 32 bit; if using cob64, JAVA_HOME must be 64 bit.

Note: Java 9 and later is 64 bit only, and so any COBOL compilation to Java byte code that uses a Java 9 JAVA_HOME must be performed in 64-bit mode.
Parent topic: COBCH1541 - COBCH1560


COBCH1559 JVM type support failed: Unexpected failure of operation during operation of type support

Parent topic: COBCH1541 - COBCH1560


COBCH1560 JVM support not loaded: the mfjvmlib library could not be loaded

The mfjvmlib class library could not be located.

Ensure the environment variable appropriate to your environment is set to locate mfjvmlib.dll correctly:

  • PATH on Windows
  • LD_LIBRARY_PATH on UNIX platforms, except AIX
  • LIBPATH on AIX
Parent topic: COBCH1541 - COBCH1560


COBCH1561 - COBCH1580

Lists the Syntax Checking error messages from COBCH1561 through COBCH1580.

  • COBCH1561S JVM support not found: are you using a supported version of the JRE?
    Trying to build a COBOL JVM project that targets a version of Java earlier than version 7 while having that version of Java installed in Eclipse.
  • COBCH1562 $ statement not recognized
    Incorrect syntax has been specified after $ in a declaration statement for a Compiler directive.
  • COBCH1563 Directive %1$s is deprecated and may be removed in future releases
    The specified Compiler directive has been deprecated and no longer has an effect on your source code.
  • COBCH1564 First parameter to an extension method must be passed BY VALUE
    The first parameter passed to an extension method must be a value parameter, not reference parameter.
  • COBCH1565 NULL value set on non-included field %1s
    The NULL XFD Compiler directive has been set on a field that does not exist in the database.
  • COBCH1566 NULL value set on key fields %1$s
    The NULL XFD Compiler directive has been set on a key field.
  • COBCH1567 VALUETYPE definition must have at least one instance field
    A valuetype must have at least one instance field in its construction.
  • COBCH1568 VALUETYPE instance field cannot have circular reference
    A field in a valuetype cannot specify a circular reference.
  • COBCH1569 Could not load ILPINVOKE file '%1$s'
    The .dll file specified by the ILPINVOKE Compiler directive does not exist or cannot be located.
  • COBCH1570 END name '%1$s' does not match corresponding header name
    The Program-ID marker and the End Program marker do not match.
  • COBCH1571 ILREF directive failed - file not found or access error
  • COBCH1572 ILREF directive has invalid type name
  • COBCH1573 ILREF directive failed - incorrect or corrupt class file format
  • COBCH1574 Reserved word missing - FROM or THROUGH expected
    An expected reserved word is missing from a statement.
  • COBCH1575 SELF and SUPER cannot be receiving items
    Incorrect syntax has been used.
  • COBCH1576 REFERENCE parameters not supported for functions in Managed COBOL
    An attempt to pass a parameter by reference into a function type has been made
  • COBCH1577 ILPINVOKE not supported with JVMGEN
    You cannot invoke a native COBOL .dll file when compiling to JVM COBOL.
  • COBCH1578 VALUETYPE instance field cannot have VALUE
    An instance field in a valuetype cannot have a VALUE clause defined.
  • COBCH1579 VALUETYPE cannot have an explicit parameter-less constructor
    Within a valuetype, you must pass a parameter into a constructor method.
  • COBCH1580 Too many END markers
    An END marker that has no corresponding definition has been found.
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1561S JVM support not found: are you using a supported version of the JRE?

Trying to build a COBOL JVM project that targets a version of Java earlier than version 7 while having that version of Java installed in Eclipse.
Parent topic: COBCH1561 - COBCH1580


COBCH1562 $ statement not recognized

Incorrect syntax has been specified after $ in a declaration statement for a Compiler directive.

Ensure that the statement syntax is as follows, also ensuring that $ appears in column 7:

$set directive-name{options}

For example:

$set sourceformat(free)
Parent topic: COBCH1561 - COBCH1580


COBCH1563 Directive %1$s is deprecated and may be removed in future releases

The specified Compiler directive has been deprecated and no longer has an effect on your source code.

You should plan to remove the directive from your source code.

Parent topic: COBCH1561 - COBCH1580


COBCH1564 First parameter to an extension method must be passed BY VALUE

The first parameter passed to an extension method must be a value parameter, not reference parameter.

To define an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.

Example:

The following extension method extends the string class, by adding a method to count the number of words in a string:

       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using by value str as string
                          returning wordCount as binary-long.
            set wordCount to str::Split(' ')::Length
       end method.
       end class.
Parent topic: COBCH1561 - COBCH1580


COBCH1565 NULL value set on non-included field %1s

The NULL XFD Compiler directive has been set on a field that does not exist in the database.

Remove the directive from the file description of the field.

Parent topic: COBCH1561 - COBCH1580


COBCH1566 NULL value set on key fields %1$s

The NULL XFD Compiler directive has been set on a key field.

You cannot use this Compiler directive on any record or alternate key fields; remove the directive from the file description of the key field.

Parent topic: COBCH1561 - COBCH1580


COBCH1567 VALUETYPE definition must have at least one instance field

A valuetype must have at least one instance field in its construction.

The following valuetype has two instance fields.

valuetype-id StudentRecord.
 01 #name string public.   *> an instance field
 01 gpa float-short public. *> another instance field
 method-id new.
  procedure division using by value nam as string,
                                  gpa as float-short.
  set #name to nam
  set self::"gpa" to gpa
 end method.
end valuetype.
Parent topic: COBCH1561 - COBCH1580
Related reference
COBCH1579 VALUETYPE cannot have an explicit parameter-less constructor
COBCH1578 VALUETYPE instance field cannot have VALUE


COBCH1568 VALUETYPE instance field cannot have circular reference

A field in a valuetype cannot specify a circular reference.

The following example contains a circular reference, which causes the error. Change the specified field type.

valuetype-id myValuetype.
  01 field-1 type myValuetype  *> the field cannot be of type myValuetype
  method-id myMethod-1.
  ...
  end method.
end valuetype.
Parent topic: COBCH1561 - COBCH1580


COBCH1569 Could not load ILPINVOKE file '%1$s'

The .dll file specified by the ILPINVOKE Compiler directive does not exist or cannot be located.
Parent topic: COBCH1561 - COBCH1580


COBCH1570 END name '%1$s' does not match corresponding header name

The Program-ID marker and the End Program marker do not match.

Amend either of the markers so that they match, then recompile.

Parent topic: COBCH1561 - COBCH1580


COBCH1571 ILREF directive failed - file not found or access error

Parent topic: COBCH1561 - COBCH1580


COBCH1572 ILREF directive has invalid type name

Parent topic: COBCH1561 - COBCH1580


COBCH1573 ILREF directive failed - incorrect or corrupt class file format

Parent topic: COBCH1561 - COBCH1580


COBCH1574 Reserved word missing - FROM or THROUGH expected

An expected reserved word is missing from a statement.

Refer to Managed COBOL language reference for expected syntax.

Parent topic: COBCH1561 - COBCH1580
Related concepts
Structural Syntax Elements - Alphabetic List


COBCH1575 SELF and SUPER cannot be receiving items

Incorrect syntax has been used.

The following example shows correct and an incorrect usage of the self:: syntax:

class-id myClass.
  01 field-a string.
  method-id myMethod.
    set self to "Micro Focus"			*> this is incorrect
    set self::field-a to "Micro Focus"		*> this is correct
  end method.
end class.

Refer to Managed COBOL language reference for expected syntax.

Parent topic: COBCH1561 - COBCH1580
Related concepts
Structural Syntax Elements - Alphabetic List


COBCH1576 REFERENCE parameters not supported for functions in Managed COBOL

An attempt to pass a parameter by reference into a function type has been made

In managed COBOL, parameters can only be passed by value for function types.

function-id myFunction.
   procedure division using by reference myParam as binary-long. *> this causes the error
   ...
end function.
function-id myFunction.
 procedure division using by value myParam as binary-long. *> this is correct
 ...
end function.
function-id myFunction.
 procedure division using myParam as binary-long. *> this is correct - by  value assumed
 ...
end function.
Parent topic: COBCH1561 - COBCH1580


COBCH1577 ILPINVOKE not supported with JVMGEN

You cannot invoke a native COBOL .dll file when compiling to JVM COBOL.
Parent topic: COBCH1561 - COBCH1580


COBCH1578 VALUETYPE instance field cannot have VALUE

An instance field in a valuetype cannot have a VALUE clause defined.

Remove the clause from the definition and recompile.

The following example contains an illegal construction for the #name instance field:

valuetype-id StudentRecord.
 01 #name string public VALUE "Mike Focus". *> remove the VALUE clause
 01 gpa float-short public.
 method-id new.
  procedure division using by value nam as string,
                                  gpa as float-short.
  set #name to nam
  set self::"gpa" to gpa
 end method.
end valuetype.
Parent topic: COBCH1561 - COBCH1580
Related reference
COBCH1579 VALUETYPE cannot have an explicit parameter-less constructor
COBCH1567 VALUETYPE definition must have at least one instance field


COBCH1579 VALUETYPE cannot have an explicit parameter-less constructor

Within a valuetype, you must pass a parameter into a constructor method.

The following valuetype has two constructors. The first is parameter-less, and thus causes the error. The second example shows the correct syntax.

valuetype-id MyClassLibrary.MyValuetype1.
01 _powerlevel binary-long.
method-id new.
procedure division.  *> this is incorrect
  set _powerLevel to 0
end method.

method-id new.
procedure division using by value powerLevel as binary-long.  *> this is correct
  set _powerLevel to powerLevel
end method.
end valuetype.
Parent topic: COBCH1561 - COBCH1580
Related reference
COBCH1578 VALUETYPE instance field cannot have VALUE
COBCH1567 VALUETYPE definition must have at least one instance field


COBCH1580 Too many END markers

An END marker that has no corresponding definition has been found.

Delete the erroneous END marker and recompile.

Parent topic: COBCH1561 - COBCH1580


COBCH1581 - COBCH1600

Lists the Syntax Checking error messages from COBCH1581 through COBCH1600.
  • COBCH1581 Could not load dependent assembly '%1$s'
    An indirectly referenced assembly has failed to load.
  • COBCH1582 ACU DESTROY statement is not supported
    The DESTROY statement is not supported in this COBOL system.
  • COBCH1583 ACU INQUIRE statement is not supported
    The INQUIRE statement is not supported in this COBOL system.
  • COBCH1584 ACU MODIFY statement is not supported
    The MODIFY statement is not supported in this COBOL system.
  • COBCH1586 Object reference not supported in thread local storage with JVMGEN
  • COBCH1587 Illegal file name '%1$s'
  • COBCH1588 Invalid ASSIGN name
  • COBCH1589 Source conversion to utf8 failed. Locale incorrect or mapping support not installed.
  • COBCH1600 Property must define at least one of GETTER or SETTER
    A property has not been defined correctly, because it is defined without a GETTER or a SETTER phrase.
Parent topic: Messages COBCH1501 to COBCH1600


COBCH1581 Could not load dependent assembly '%1$s'

An indirectly referenced assembly has failed to load.

An indirectly referenced assembly is one that is referenced from an assembly directly referenced from your project.

Parent topic: COBCH1581 - COBCH1600


COBCH1582 ACU DESTROY statement is not supported

The DESTROY statement is not supported in this COBOL system.

Remove the statement from your source code.

Parent topic: COBCH1581 - COBCH1600


COBCH1583 ACU INQUIRE statement is not supported

The INQUIRE statement is not supported in this COBOL system.

Remove the statement from your source code.

Parent topic: COBCH1581 - COBCH1600


COBCH1584 ACU MODIFY statement is not supported

The MODIFY statement is not supported in this COBOL system.

Remove the statement from your source code.

Parent topic: COBCH1581 - COBCH1600


COBCH1586 Object reference not supported in thread local storage with JVMGEN

Resolution:

Parent topic: COBCH1581 - COBCH1600


COBCH1587 Illegal file name '%1$s'

Resolution:

Parent topic: COBCH1581 - COBCH1600


COBCH1588 Invalid ASSIGN name

Resolution:

Parent topic: COBCH1581 - COBCH1600


COBCH1589 Source conversion to utf8 failed. Locale incorrect or mapping support not installed.

Resolution:

Parent topic: COBCH1581 - COBCH1600


COBCH1600 Property must define at least one of GETTER or SETTER

A property has not been defined correctly, because it is defined without a GETTER or a SETTER phrase.

The following example shows the property myProperty with both the GETTER and SETTER phrases:

property-id myProperty string.
  getter.
  set property-value to field-1.
  setter.
  set field-2 to property-value.
end property.
Parent topic: COBCH1581 - COBCH1600


Messages COBCH1601 - COBCH1700

  • COBCH1601 - COBCH1620
    Lists the Syntax Checking error messages from COBCH1601 through COBCH1620.
  • COBCH1621 - COBCH1640
    Lists the Syntax Checking error messages from COBCH1621 through COBCH1640.
  • COBCH1641 - COBCH1660
    Lists the Syntax Checking error messages from COBCH1641 through COBCH1660.
  • COBCH1661 - COBCH1680
    Lists the Syntax Checking error messages from COBCH1661 through COBCH1680.
  • COBCH1681 - COBCH1700
    Lists the Syntax Checking error messages from COBCH1681 through COBCH1700.
Parent topic: Syntax Checking Error Messages


COBCH1601 - COBCH1620

Lists the Syntax Checking error messages from COBCH1601 through COBCH1620.
  • COBCH1601 Property cannot have parameters
    The Procedure Division header within a property-id has parameters specified.
  • COBCH1602 Indexer must have at least one parameter
    The Procedure Division header within an indexer-id does not have a parameter specified.
  • COBCH1603 No indexer found for class '%1$s'
    An instance of a type that does not contain an indexer is being accessed as an array.
  • COBCH1604 Cannot inherit from interface '%1$s'
    The interface that you are trying to inherit does exist, but there is a problem with its construction.
  • COBCH1605 Entry name '%1$s' reserved for use by Micro Focus
    The specified entry point name is reserved for managed COBOL syntax.
  • COBCH1606 Syntax can only be used with LIST and DICTIONARY items
    Certain syntax can only be used on items of type LIST or DICTIONARY.
  • COBCH1607 Syntax can only be used with DICTIONARY items
    Certain syntax can only be used on items of type DICTIONARY.
  • COBCH1608 Illegal USAGE in this context
    The specified USAGE type has been used out of context.
  • COBCH1609 Property accessor visibility must be stricter than property visibility
    The visibility of a GETTER or SETTER phrase is not as strict as the visibility of its containing property.
  • COBCH1610 Cannot specify visibility on both GETTER and SETTER
    Both the GETTER and SETTER phrases of a property specify visibility.
  • COBCH1611 Can only specify accessor visibility if property has both GETTER and SETTER
    The property is missing a GETTER or SETTER phrase due to accessor visibility being specified.
  • COBCH1612 ACU picture string not supported
    You have specified an invalid picture string, for example, a mixture of symbols specified for zero suppression.
  • COBCH1613 Syntax error error not allowed
    A general syntax error has occurred.
  • COBCH1614 INSPECT TRAILING match item must be single character item
    You have specified an invalid TRAILING item in the INSPECT statement; you must specify a single character item.
  • COBCH1615 ACU statement COPY RESOURCE not supported; statement ignored
    The COPY RESOURCE statement is not supported in this COBOL system.
  • COBCH1616 Can only be used in nested class
    You have attempted to use nested-specific syntax in a class that is not nested.
  • COBCH1617 WITH COMPRESSION or WITH ENCRYPTION are only supported in ACU mode when DATACOMPRESS is off
    You have specified the WITH COMPRESSION or WITH ENCRYPTION phrase on a file in a program that also has the DATACOMPRESS Compiler directive set.
  • COBCH1618 WITH COMPRESSION or WITH ENCRYPTION are only valid for INDEX files
    You have specified the WITH COMPRESSION or WITH ENCRYPTION phrase on a file that is not an indexed file.
  • COBCH1619 Must specify one generic parameter
    The predefined LIST type must be specified with one generic parameter.
  • COBCH1620 Must specify two generic parameters
    The predefined DICTIONARY type must be specified with two generic parameters.
Parent topic: Messages COBCH1601 - COBCH1700


COBCH1601 Property cannot have parameters

The Procedure Division header within a property-id has parameters specified.

The Procedure Division header in a property-id must not have any parameters.

class-id myClass.
property-id myProp1 string.
procedure division using myField as string. *> this is incorrect
    getter.
    set property-value to "Micro Focus"
end property.

property-id myProp2 string.
procedure division.	*> this is correct
    getter.
    set property-value to "Visual COBOL"
end property.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1602 Indexer must have at least one parameter

The Procedure Division header within an indexer-id does not have a parameter specified.

You must specify at least one parameter in the Procedure Division header:

class-id myClass1.
indexer-id string.
procedure division. *> this is incorrect - no parameter specified
    getter.
    set property-value to "abc"
end indexer.
end class.

class-id myClass2.
01 myField string value "abc".
indexer-id string.
procedure division using value myParam as binary-long. *> this is correct
    getter.
    set property-value to a
end indexer.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1603 No indexer found for class '%1$s'

An instance of a type that does not contain an indexer is being accessed as an array.

A type must contain an indexer if an instance of that type is being accessed as an array, as shown in the following example:

class-id myClass1.
method-id main.
01 myField type myClass2.
    display myField[0]
end method.
end class.

class-id myClass2.
indexer-id string.		*> add an indexer to resolve the error
procedure division using value myParam as binary-long.
    getter.
    set property-value to myParam
end indexer.
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1604 Cannot inherit from interface '%1$s'

The interface that you are trying to inherit does exist, but there is a problem with its construction.

For example, the following example fails because the interface that is being inherited is empty.

class-id myClass inherits type myInterface.
...
end class.

interface-id myInterface.
end interface.

Add a method or some other valid construction to the interface to fix the error.

Parent topic: COBCH1601 - COBCH1620


COBCH1605 Entry name '%1$s' reserved for use by Micro Focus

The specified entry point name is reserved for managed COBOL syntax.

You must change the name of your entry point.

Parent topic: COBCH1601 - COBCH1620


COBCH1606 Syntax can only be used with LIST and DICTIONARY items

Certain syntax can only be used on items of type LIST or DICTIONARY.

Some syntax is specifically designed for collection types. To use this syntax, the item must be of LIST or DICTIONARY type.

Parent topic: COBCH1601 - COBCH1620
Related concepts
Structural Syntax Elements - Alphabetic List


COBCH1607 Syntax can only be used with DICTIONARY items

Certain syntax can only be used on items of type DICTIONARY.

In the following example, change the myField1 field to type DICTIONARY to be able to use the key keyword in the PERFORM statement:

class-id myClass.
01 myField1 list[string].
01 myField2 string.
method-id myMethod.
  perform varying key myField2 through myField1
  ...
  end-perform.
end method.
end class.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Structural Syntax Elements - Alphabetic List


COBCH1608 Illegal USAGE in this context

The specified USAGE type has been used out of context.

Certain USAGE types cannot be used in the procedure division header. For example:

class-id myClass1.

indexer-id string.
procedure division using i1 as COMP-3. *> this is incorrect
    getter.
    set property-value to i1.
end indexer.
end class.

class-id myClass2.
indexer-id string.
procedure division using i2 as binary-double. *> this is correct
    getter.
    set property-value to i2
end indexer.
end class.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Structural Syntax Elements - Alphabetic List


COBCH1609 Property accessor visibility must be stricter than property visibility

The visibility of a GETTER or SETTER phrase is not as strict as the visibility of its containing property.

The visibility of a GETTER or SETTER phrase must be stricter than the visibility of its containing property:

class-id myClass1.
property-id myProp1 string private.
    setter protected.  *> this is incorrect
    set property-value to "1234"
    getter.
end property.
end class.

class-id myClass2.
property-id myProp2 string public.
    setter protected.			*> this is correct
    set property-value to "5678"
    getter.
    declare myString as string.
    set myString to property-value
end property.
end class.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Properties


COBCH1610 Cannot specify visibility on both GETTER and SETTER

Both the GETTER and SETTER phrases of a property specify visibility.

You can only set the visibility of one of either the GETTER or SETTER phrases of a property, as shown in the following example:

class-id myClass1.
property-id myProp1 string public.
    setter private.
    set property-value to "1234"
    getter.
    set myString to property-value
end property.
end class.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Properties


COBCH1611 Can only specify accessor visibility if property has both GETTER and SETTER

The property is missing a GETTER or SETTER phrase due to accessor visibility being specified.

If you specify the visibility of either a GETTER or SETTER phrase, the property must contain both a GETTER and a SETTER phrase, but only one phrase can specify the visibility.

class-id myClass1.
property-id myProp1 string public.
    setter protected.			*> this is correct
    set property-value to "1234"
    getter.
    set myString to property-value
end property.
end class.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Properties


COBCH1612 ACU picture string not supported

You have specified an invalid picture string, for example, a mixture of symbols specified for zero suppression.

This error message is displayed when an invalid symbol (or combination of symbols) has been specified in the picture string when you compile with either the DIALECT"ACU" or the ACU Compiler directive.

For example, in this COBOL system, the combination of numeric and numeric edited symbols in the same picture string must follow strict logical rules:
01 edit-acc-tot1 pic Z9.9Z.	*> this is incorrect
01 edit-acc-tot2 pic 99.ZZ.	*> this is incorrect
01 edit-acc-tot3 pic ZZ.99.	*> this is correct
01 edit-acc-tot4 pic Z9.99.	*> this is correct

You must correct any picture strings that produce this error. For more information on the symbol combinations allowed in this COBOL system, see The Picture Clause.

Parent topic: COBCH1601 - COBCH1620
Related concepts
The PICTURE Clause


COBCH1613 Syntax error error not allowed

A general syntax error has occurred.
Check your source code for errors, referring to the COBOL Language Reference, if required.
Parent topic: COBCH1601 - COBCH1620
Related concepts
Introduction to the COBOL Language


COBCH1614 INSPECT TRAILING match item must be single character item

You have specified an invalid TRAILING item in the INSPECT statement; you must specify a single character item.

For example:

INSPECT long-str TALLYING my-counter for TRAILING "**".  *> this is incorrect

INSPECT long-str TALLYING my-counter for TRAILING "*".	 *> this is correct
Parent topic: COBCH1601 - COBCH1620


COBCH1615 ACU statement COPY RESOURCE not supported; statement ignored

The COPY RESOURCE statement is not supported in this COBOL system.
Parent topic: COBCH1601 - COBCH1620


COBCH1616 Can only be used in nested class

You have attempted to use nested-specific syntax in a class that is not nested.
Certain syntax is only applicable to nested classes and must be removed from any other type of class. For example, the SHARING PARENT phrase is not permitted in containing classes.
...
end class.

class-id myContainingClass SHARING PARENT	*> this is incorrect usage
  01 myContainingStr string value "Hello Managed COBOL".
  ...
  class-id myNestedClass SHARING PARENT		*> this is correct usage
    display self::myContainingStr.
  end class.
...
end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1617 WITH COMPRESSION or WITH ENCRYPTION are only supported in ACU mode when DATACOMPRESS is off

You have specified the WITH COMPRESSION or WITH ENCRYPTION phrase on a file in a program that also has the DATACOMPRESS Compiler directive set.
Remove the Compiler directive from your program.
Parent topic: COBCH1601 - COBCH1620
Related concepts
The File-Control Paragraph


COBCH1618 WITH COMPRESSION or WITH ENCRYPTION are only valid for INDEX files

You have specified the WITH COMPRESSION or WITH ENCRYPTION phrase on a file that is not an indexed file.
The WITH COMPRESSION and WITH ENCRYPTION phrases can only be specified in the SELECT statement for an indexed file.
Parent topic: COBCH1601 - COBCH1620
Related concepts
The File-Control Paragraph


COBCH1619 Must specify one generic parameter

The predefined LIST type must be specified with one generic parameter.
For example:
class-id myClass

01 myList1 LIST [string].      *> this is correct
01 myList2 LIST [float-short]. *> this is also correct
01 myList3 LIST [type myType]. *> this is also correct
01 myList4 LIST                *> this is incorrect - no param specified
01 myLIST5 LIST [string, float-short]  *>this also incorrect - too many params specified

...

end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1620 Must specify two generic parameters

The predefined DICTIONARY type must be specified with two generic parameters.
For example:
class-id myClass

01 myDict1 DICTIONARY [string].		*> this is incorrect
01 myDict2 DICTIONARY [string string].  *> this is correct

...

end class.
Parent topic: COBCH1601 - COBCH1620


COBCH1621 - COBCH1640

Lists the Syntax Checking error messages from COBCH1621 through COBCH1640.
  • COBCH1621 Must specify a method invoke expression with no parameters
    When using the method keyword to specify a method from a method group, you must not specify any parameters.
  • COBCH1622 A SIZE OF expression cannot be used as a receiving item
    You have attempted to use the SIZE OF expression as part of a receiving item.
  • COBCH1623 Anonymous method or method group cannot be cast to type name.
    An anonymous method or method group cannot be found with a valid signature for the delegate.
  • COBCH1624 Cannot implicitly convert type1 to type2.
    A SET statement cannot be completed, because you cannot convert to or from the specified type.
  • COBCH1625 Cannot convert type1 to type2.
    The casting expression cannot be completed, because you cannot convert to or from the specified type.
  • COBCH1626 Invalid test: type1 cannot be instance of type2.
    The INSTANCE OF phrase has encountered a type safety issue, and you cannot cast to or from the specified types.
  • COBCH1627 Preferred syntax uses pseudo-text delimiters (==) instead of quotes
    The REPLACING LEADING or REPLACING TRAILING phrase of the COPY statement has specified the wrong delimiters for text replacement.
  • COBCH1628 Cannot determine type of local variable
    The Compiler could not resolve the type for a DECLARE expression.
  • COBCH1629 REPLACING assumed
    A possible misspelling has been found in the REPLACING phrase of the COPY statement.
  • COBCH1631 ATTACH and DETACH statements can only be applied to events
    You can only use the attach or detach syntax on delegate fields that have the event keyword specified.
  • COBCH1632 Cannot specify ALL numeric literal
    In this COBOL system, you cannot precede a numeric literal with the keyword ALL.
  • COBCH1633 Procedure division too large or complex - try using performtype(mf)
  • COBCH1634 Extended ACCEPT/DISPLAY not allowed with a Windows GUI executable (ILSUBSYSTEM"2")
    Your Windows application has specified an extended ACCEPT or DISPLAY statement.
  • COBCH1635 Interface <interface-name> does not include member <member-name>
    A method or property has been specified using the FOR interface-name phrase, but the interface does not contain a method or property of that name.
  • COBCH1636 When compiling for managed code, this feature is supported only in procedural COBOL
    You have used syntax that is not supported in class programs. It is only supported in procedural programs.
  • COBCH1637 Illegal use of method invoke expression - Use INVOKE verb
    An inline invoke expression has been specified in a context that requires the INVOKE verb.
  • COBCH1638 Start key ambiguous; using key key-name-1 (key key-name-2 has same offset)
    A START statement KEY phrase specifies the data-name of data item that has the same offset as two or more split keys of an indexed organization file.
  • COBCH1639 Required parameters must be specified before any optional ones
    An optional parameter has been specified before a required parameter in the declaration of a method.
  • COBCH1640 Optional parameters cannot be specified with BY REFERENCE OUTPUT or PARAMS
    A reference or output parameter has been declared as optional.
Parent topic: Messages COBCH1601 - COBCH1700


COBCH1621 Must specify a method invoke expression with no parameters

When using the method keyword to specify a method from a method group, you must not specify any parameters.

See the Method Groups section of Delegates and Events for more information.

Parent topic: COBCH1621 - COBCH1640
Related concepts
Delegates and Events


COBCH1622 A SIZE OF expression cannot be used as a receiving item

You have attempted to use the SIZE OF expression as part of a receiving item.
In this COBOL system, you can only use the SIZE OF expression as a sending item. For example:
01 firstName string
01 totalLen pic 9(3).
...
add 10 to SIZE OF firstName.                *> this is incorrect
add SIZE OF firstName to totalLen.	    *> this is correct
Note: You can only use the SIZE OF expression with single-dimensional managed arrays or strings.
Parent topic: COBCH1621 - COBCH1640


COBCH1623 Anonymous method or method group cannot be cast to type name.

An anonymous method or method group cannot be found with a valid signature for the delegate.

In the following example, the error is produced because none of the myType1::m methods match the signature specified by myDelegateID.

class-id myClass.Class1.

method-id main static.
01 myDel type myDelegateID.
01 myType1 type Class2.

set myDel to method myType1::m
end method.
end class.

delegate-id myDelegateID.
  procedure division using by value s as string.
end delegate.

class-id Class2.

method-id m.
 procedure division using by value s1 as string returning n1 as binary-long.
          set n1 to size of s1 + 3
end method.

method-id m.
 procedure division using by value s1 as string s2 as string returning n1 as binary-long.
end method.
end class.

See Delegates and Events for more information.

Parent topic: COBCH1621 - COBCH1640
Related concepts
Delegates and Events


COBCH1624 Cannot implicitly convert type1 to type2.

A SET statement cannot be completed, because you cannot convert to or from the specified type.

For example:

class-id myClass1.

method-id myFirstMethod static.

 01 myFloat float-long.
 01 myString string.
 01 myInt binary-long.
 01 myObject object.
 01 myDecimal decimal.

 set myFloat to myString   *> this is incorrect
 set myFloat to myInt      *> this is correct
 set myObject to myString  *> this is correct - string derives from object
 set myDecimal to myString *> this is correct - In the .NET framwork, the System.Decimal class has an implicit conversion operator
                                                from type int (binary-long) to type System.Decimal

end method.

end class.
Parent topic: COBCH1621 - COBCH1640


COBCH1625 Cannot convert type1 to type2.

The casting expression cannot be completed, because you cannot convert to or from the specified type.
For example:
class-id myClass1.

method-id myFirstMethod static.

 01 myItem1 string.
 01 myItem2 type myClass2.
 01 myItem3 object.

 set myItem2 to myItem1 as string  *> this is incorrect unless type MyClass2 has an implicit\explicit conversion operator
                                   *> from type myClass2 to string
 set myItem1 to myItem3 as string  *> this is correct - note: this could produce an exception at runtime

end method.

end class.
Parent topic: COBCH1621 - COBCH1640


COBCH1626 Invalid test: type1 cannot be instance of type2.

The INSTANCE OF phrase has encountered a type safety issue, and you cannot cast to or from the specified types.
Parent topic: COBCH1621 - COBCH1640


COBCH1627 Preferred syntax uses pseudo-text delimiters (==) instead of quotes

The REPLACING LEADING or REPLACING TRAILING phrase of the COPY statement has specified the wrong delimiters for text replacement.
This error message is displayed when the " or ' quotation marks are used to delimit the text replacement and you have compiled with the DIALECT"ACU" or the ACU Compiler directive. Ensure you use the == delimiters when specifying the text replacement in this COBOL system, as shown below.
...
COPY "demo91.cpy" REPLACING LEADING "demo91" BY "acct".		*> this is incorrect
COPY "demo91.cpy" REPLACING LEADING ==demo91== BY ==acct==.	*> this is correct
...
Parent topic: COBCH1621 - COBCH1640


COBCH1628 Cannot determine type of local variable

The Compiler could not resolve the type for a DECLARE expression.

Declare the type explicitly.

Parent topic: COBCH1621 - COBCH1640


COBCH1629 REPLACING assumed

A possible misspelling has been found in the REPLACING phrase of the COPY statement.
Check and correct any spelling errors in your COPY statements. This error is only displayed if you are compiling with the DIALECT"ACU" or the ACU Compiler directive.
Parent topic: COBCH1621 - COBCH1640


COBCH1631 ATTACH and DETACH statements can only be applied to events

You can only use the attach or detach syntax on delegate fields that have the event keyword specified.

See the Events section of Delegates and Events for more information.

Parent topic: COBCH1621 - COBCH1640
Related concepts
Delegates and Events


COBCH1632 Cannot specify ALL numeric literal

In this COBOL system, you cannot precede a numeric literal with the keyword ALL.
In these circumstances, remove the keyword ALL from your source code.
Parent topic: COBCH1621 - COBCH1640


COBCH1633 Procedure division too large or complex - try using performtype(mf)

Parent topic: COBCH1621 - COBCH1640


COBCH1634 Extended ACCEPT/DISPLAY not allowed with a Windows GUI executable (ILSUBSYSTEM"2")

Your Windows application has specified an extended ACCEPT or DISPLAY statement.

If you are building a Windows application, you must remove any extended ACCEPT or DISPLAY statements, or change the output type of the application to Console Application.

Parent topic: COBCH1621 - COBCH1640


COBCH1635 Interface <interface-name> does not include member <member-name>

A method or property has been specified using the FOR interface-name phrase, but the interface does not contain a method or property of that name.

In the following example, the error is produced because the IBase interface does not contain a method called Advanced. To correct the error, add the Advanced method signature to the interface, or reference the correct interface.

class-id BasicImpl implements type IBase.
method-id Advanced for type IBase
procedure division using a1 as string, a2 as string, returning a3 as string.
...
end method.
end class.

interface-id IBase.
method-id Basic.
procedure division using a1 as string.
end method.
method-id Intermediate.
procedure division using a1 as string, returning a2 as string.
end method.
end interface.
Parent topic: COBCH1621 - COBCH1640
Related tasks
Methods
Interfaces


COBCH1636 When compiling for managed code, this feature is supported only in procedural COBOL

You have used syntax that is not supported in class programs. It is only supported in procedural programs.

To continue to use the syntax in managed code, move it to a procedural program and call it from within a class method.

Parent topic: COBCH1621 - COBCH1640


COBCH1637 Illegal use of method invoke expression - Use INVOKE verb

An inline invoke expression has been specified in a context that requires the INVOKE verb.

In the following example, add the verb invoke at the start of the line o::DoIt.

...
01 o object.
procedure division.
o::DoIt
...
Parent topic: COBCH1621 - COBCH1640
Related tasks
INVOKE Statement


COBCH1638 Start key ambiguous; using key key-name-1 (key key-name-2 has same offset)

A START statement KEY phrase specifies the data-name of data item that has the same offset as two or more split keys of an indexed organization file.

Each of the keys has a total length that is greater than or equal to the length of the referenced data item. In this case, it is ambiguous which key should be used for the key of reference. The first key found that satisfies the length requirement is used as indicated by first key-name in the message; the second key found, as indicated by the key-name in the parenthetical of the message, is not used in establishing the key of reference. If the second key is the desired key for the key of reference, use its split-key-name and the WITH SIZE phrase to specify a partial key to avoid any ambiguity. This message is only produced for multi-component split keys that have the same starting offset and a compatible total length.

For single component keys, that is, ones specified without a split-key-name or those listing only one component following the split-key-name and equal sign, this message is not produced. The compiler uses the last single component key that has a matching offset with the specified data-name, regardless of its length. If the data-name references a data item with a length longer than the matched key, only the part of the data item up to the key length is compared to the key at run time. This last key found is used to establish the key of reference for subsequent sequential READ statements until another START statement or READ statement with the KEY phrase is executed.

Parent topic: COBCH1621 - COBCH1640


COBCH1639 Required parameters must be specified before any optional ones

An optional parameter has been specified before a required parameter in the declaration of a method.

Specify any required parameters before you specify optional parameters in the signature. In the following example, specify p2 before p1.

class-id myClass.
method-id myMethod.
procedure division using by value p1 as string = "Hello", p2 as string.
...
end method.
end class.
Parent topic: COBCH1621 - COBCH1640


COBCH1640 Optional parameters cannot be specified with BY REFERENCE OUTPUT or PARAMS

A reference or output parameter has been declared as optional.

You can only pass an optional parameter BY VALUE.

class-id myClass.
method-id Method1.
procedure division using by reference s1 as string = "Hello".
...
end method.
end class.
Parent topic: COBCH1621 - COBCH1640


COBCH1641 - COBCH1660

Lists the Syntax Checking error messages from COBCH1641 through COBCH1660.

  • COBCH1641 Period in source filename or PROGRAM-ID in native code
    A period has been specified in the program ID of a native program.
  • COBCH1642 Positional parameters must be specified before any named parameters or property initializers
    When a method invocation expression is used, parameters specified by name must follow any purely positional parameters.
  • COBCH1643 Parameter name <param-name> specified more than once
    In a method invocation expression, the same parameter name has been specified more than once.
  • COBCH1644 Cannot use KEY phrase with WRITE statement applied to lists
    The KEY phrase has been specified for a WRITE statement that is applied to a list.
  • COBCH1645 KEY phrase missing
    A WRITE statement referencing a dictionary item must specify the KEY phrase.
  • COBCH1646 Cannot DISPLAY a void method
    A method that does not have a returning value has been specified as the object of a DISPLAY verb.
  • COBCH1647 Resolution of type <type-name1> failed dependent type <type-name2> not found
    A program has referenced type-name1, which is dependent on type-name2, but type-name2 cannot be located.
  • COBCH1648 LEFT, RIGHT, or CENTERED expected; output phrase ignored
    An OUTPUT phrase of an ACCEPT or DISPLAY statement is incomplete and therefore ignored. Add LEFT, RIGHT, or CENTERED to complete the phrase.
  • COBCH1649 Quoted PICTURE character-string is an ACUCOBOL extension
    A character-string in a PICTURE clause contains double or single quotes, which you must remove.
  • COBCH1650 Indicator column contains $ or >, but no directive follows; line ignored
    A valid directive setting statement does not precede the $ or > symbol.
  • COBCH1651 Operand must be a constant value
    A non-constant expression has been specified when a constant is required.
  • COBCH1652 Property initializers must be specified after parameters
    A property initializer has been specified before the positional parameters in an attribute specification.
  • COBCH1653 Can only specify property in attribute specification and new expression
    A property has been specified incorrectly.
  • COBCH1654 Should be elementary; MODE IS BLOCK assumed
    You have attempted to perform an ACCEPT or DISPLAY statement on a group item, but have specified an optional phrase that is only applicable to elementary items.
  • COBCH1655 Word var1 is not allowed here; ignoring word for ACUCOBOL compatibility
    A reserved word has been used in a context where it is not allowed by the language syntax.
  • COBCH1656 Incorrect syntax, VARYING expected; assuming CONTAINS
    The indicated RECORD clause has incorrect syntax.
  • COBCH1657 ACU file syntax extension is not supported
    The specified file syntax extension is not supported in Visual COBOL.
  • COBCH1658 VALUE OF FILE-ID overriding ASSIGN
    A VALUE OF FILE-ID clause in the File Description entry is overriding the external-file-reference already specified in an ASSIGN clause in the File Control entry.
  • COBCH1659 VALUE clause literal does not conform to PICTURE. Changed to zero.
    A nonnumeric value has been specified for a numeric data item. The data item is initialized to zero.
  • COBCH1660 Type is not disposable
    The item specified in the PERFORM USING statement is not disposable.
Parent topic: Messages COBCH1601 - COBCH1700


COBCH1641 Period in source filename or PROGRAM-ID in native code

A period has been specified in the program ID of a native program.

Remove the period to conform with required syntax of the program-ID of a native COBOL program.

identification division.
program-id. Prog.ram1.  *> remove the period for native COBOL programs
...
end program Program1.
Parent topic: COBCH1641 - COBCH1660


COBCH1642 Positional parameters must be specified before any named parameters or property initializers

When a method invocation expression is used, parameters specified by name must follow any purely positional parameters.

In the following example, the param p1 = "Hello" parameter must be declared after the "bye" parameter.

class-id myClass.
 method-id main static.
   invoke self::myMethod(param p1 = "Hello", "bye")
 end method.

 method-id myMethod static.
 procedure division using by value p1 as string, p2 as string.
 end method.
 end class.
Parent topic: COBCH1641 - COBCH1660


COBCH1643 Parameter name <param-name> specified more than once

In a method invocation expression, the same parameter name has been specified more than once.

In the following example, change one of the s1 parameter names to a unique name.

class-id myClass.
 method-id methodA.
   invoke self::methodB(param s1 = "Hello", param s1 = "bye")
 end method.

 method-id methodB.
 procedure division using by value s1 as string s2 as string.
 end method.
 end class.
Parent topic: COBCH1641 - COBCH1660


COBCH1644 Cannot use KEY phrase with WRITE statement applied to lists

The KEY phrase has been specified for a WRITE statement that is applied to a list.

You cannot use the KEY phrase in these circumstances, but you can use the KEY phrase with the REWRITE statement, which enables you to write to a specific location in your list.

class-id ListsClass.
method-id listsDemo.
procedure division.
declare stringList as list[string]
create stringList

perform varying i as binary-long from 1 by 1 until i > 5
               write stringList from "item " & i
end-perform

write stringlist from "New item" key 2    *> this is incorrect
rewrite stringlist from "New item" key 2  *> but this will update list at key 2

end method.

end class.
Parent topic: COBCH1641 - COBCH1660
Related tasks
WRITE Collection Statement
REWRITE Collection Statement


COBCH1645 KEY phrase missing

A WRITE statement referencing a dictionary item must specify the KEY phrase.

In the following example, the syntax for the write expression is incomplete. Specify the key phrase, such as key "key1" to correct the syntax.

class-id myClass.
method-id myMethod.
01 dict1 dictionary[string, string].
   write dict1 from "Hello"																*> add key "key1" here
   rewrite dict1 from "Goodbye" key "key1"
end method.
end class.
Parent topic: COBCH1641 - COBCH1660
Related tasks
WRITE Collection Statement
REWRITE Collection Statement


COBCH1646 Cannot DISPLAY a void method

A method that does not have a returning value has been specified as the object of a DISPLAY verb.
class-id myClass.
method-id myMethod1.
display self::myMethod2
end method.
method-id myMethod2.
end method.
end class.
Parent topic: COBCH1641 - COBCH1660


COBCH1647 Resolution of type <type-name1> failed dependent type <type-name2> not found

A program has referenced type-name1, which is dependent on type-name2, but type-name2 cannot be located.

This error occurs when the dependent type is defined in a separate .jar file that is not on the class path. Ensure the .jar files of all dependant classes, methods, types, etc are specified on the class path, using the JVMCLASSPATH directive.

Parent topic: COBCH1641 - COBCH1660


COBCH1648 LEFT, RIGHT, or CENTERED expected; output phrase ignored

An OUTPUT phrase of an ACCEPT or DISPLAY statement is incomplete and therefore ignored. Add LEFT, RIGHT, or CENTERED to complete the phrase.

ACUCOBOL-GT COBOL allows an incomplete OUTPUT phrase of the form OUTPUT, JUST, or OUTPUT JUST in an ACCEPT or DISPLAY statement. In this COBOL system, any incomplete phrases are ignored.

01 accept data-01 output just.             *> ignored
01 accept data-01 just.                    *> ignored
01 accept data-01 output just right.       *> correct
01 accept data-01 output just centered.    *> correct
Parent topic: COBCH1641 - COBCH1660


COBCH1649 Quoted PICTURE character-string is an ACUCOBOL extension

A character-string in a PICTURE clause contains double or single quotes, which you must remove.

ACUCOBOL-GT COBOL has an extension that allows the character-string in a PICTURE clause of a data description entry to be quoted with double or single quotes. In this COBOL system, the quotes should be removed to conform to standard COBOL syntax.

01 Data-01 PIC "X(5)".  *> incorrect
01 Data-02 PIC X(5).    *> correct
Parent topic: COBCH1641 - COBCH1660


COBCH1650 Indicator column contains $ or >, but no directive follows; line ignored

A valid directive setting statement does not precede the $ or > symbol.
In ACUCOBOL-GT, if your code contains a $ or > in the indicator column but no valid directive is set on that line, the line is treated as a comment line. To get the same behavior in Visual COBOL, set DIALECT"ACU".
Parent topic: COBCH1641 - COBCH1660


COBCH1651 Operand must be a constant value

A non-constant expression has been specified when a constant is required.

In the following example, the parameter in the attribute specification needs to be a constant, not the variable field s.

$set ilusing"System.Xml.Serialization"

class-id. myClass.
01 s string.
01 i binary-long attribute XmlAttribute(s).
end class.
Parent topic: COBCH1641 - COBCH1660
Related tasks
Attributes


COBCH1652 Property initializers must be specified after parameters

A property initializer has been specified before the positional parameters in an attribute specification.

In the following example, the property initializer (prop Namespace = "MyNameSpace") needs to be specified after the positional parameter ("space").

$set ilusing"System.Xml.Serialization"

class-id. myClass.
01 i binary-long attribute XmlAttribute(prop Namespace = "MyNamespace", "space").
end class.
Parent topic: COBCH1641 - COBCH1660
Related tasks
Attributes


COBCH1653 Can only specify property in attribute specification and new expression

A property has been specified incorrectly.

The syntax for setting properties (the prop or property keywords) as part of a parameter list can only be used in an attribute expression or a new expression. It cannot be used in normal method invocation.

class-id. myClass.
01 X string property.																						*> this is correct
method-id myMethod.
 invoke self::myMethod2(prop X = "Hello")  *> this is incorrect
end method.
method-id myMethod2.
...
end method.
end class.
Parent topic: COBCH1641 - COBCH1660


COBCH1654 Should be elementary; MODE IS BLOCK assumed

You have attempted to perform an ACCEPT or DISPLAY statement on a group item, but have specified an optional phrase that is only applicable to elementary items.

This error only occurs if you are compiling with one of the ACUCOBOL or RM/COBOL dialect Compiler directives. Set the MODE IS BLOCK phrase to make your source code more compatible with this COBOL system. By setting MODE IS BLOCK, the group item is treated as an elementary item.

01 group-01.
   02 field-01      pic x(10).
   02 filler        pic x(02).
   02 field-02      pic x(10).

Procedure division.

accept group-01 auto  *> correct - the auto phrase is allowed for group items
accept group-01 beep  *> incorrect - the beep phrase is not allow for group items
accept group-01 beep MODE IS BLOCK *> correct - the group-01 item is treated as an elementary item (pic x (22))
Parent topic: COBCH1641 - COBCH1660


COBCH1655 Word var1 is not allowed here; ignoring word for ACUCOBOL compatibility

A reserved word has been used in a context where it is not allowed by the language syntax.

This word is ignored by the ACUCOBOL compiler, but in Visual COBOL you should correct the syntax. In the following example, the reserved word 'all' has caused the error:

01 dash-line pic x(80) value "-"  all.

Either remove the reserved word altogether or move it to the correct location, as shown below:

01 dash-line pic x(80) value all "-".
Parent topic: COBCH1641 - COBCH1660


COBCH1656 Incorrect syntax, VARYING expected; assuming CONTAINS

The indicated RECORD clause has incorrect syntax.

The ACUCOBOL compiler incorrectly allows RECORD IS 80 CHARACTERS as an equivalent of RECORD CONTAINS 80 CHARACTERS. In Visual COBOL, you must correct the syntax. The RECORD clause can be either RECORD CONTAINS … or RECORD IS VARYING ….

This message is only produced when compiling with one of the ACUCOBOL dialect Compiler directives. Otherwise, COBCH0083 "Reserved word missing - VARYING expected." is produced instead.

Parent topic: COBCH1641 - COBCH1660
Related concepts
The RECORD Clause
File Description Entry Skeleton


COBCH1657 ACU file syntax extension is not supported

The specified file syntax extension is not supported in Visual COBOL.

The legacy syntax is supported when compiling with one of the ACUCOBOL Compiler directives, but preferred syntax exists that should be used instead, as shown in the table below. The preferred syntax does not require you to compile with one of the ACUCOBOL Compiler directives.

Legacy syntax | Preferred syntax
APPLY LOCK-HOLDING | LOCK ON MULTIPLE RECORDS phrase of the LOCK MODE clause
APPLY PRINT-CONTROL | ASSIGN TO PRINT clause
Parent topic: COBCH1641 - COBCH1660


COBCH1658 VALUE OF FILE-ID overriding ASSIGN

A VALUE OF FILE-ID clause in the File Description entry is overriding the external-file-reference already specified in an ASSIGN clause in the File Control entry.

The external-file-reference should be specified only once to avoid ambiguity. One of the two specifications should be removed from the source program. When specified in both places, the VALUE OF FILE-ID specification will be used for the file and the ASSIGN clause specification of the external-file-reference will be ignored.

input-output section.
file-control.
select f1 assign to disk f1-name-1.       *> the first external-file-reference 'f1-name-1'
...
file section.
fd f1   record contains 10 characters
           value of file-id is f1-name-2. *> the second external-file-reference 'f1-name-2'
...
Parent topic: COBCH1641 - COBCH1660


COBCH1659 VALUE clause literal does not conform to PICTURE. Changed to zero.

A nonnumeric value has been specified for a numeric data item. The data item is initialized to zero.
Parent topic: COBCH1641 - COBCH1660


COBCH1660 Type is not disposable

The item specified in the PERFORM USING statement is not disposable.

In the following example, d1 must implement the java.lang.AutoCloseable interface.

class-id myClass.
method-id myMethod.
 perform using d1 as string = "Hello" *> implement d1 as type java.lang.AutoCloseable
   continue
 end-perform.
end method.
end class.
Parent topic: COBCH1641 - COBCH1660
Related tasks
PERFORM Statement


COBCH1661 - COBCH1680

Lists the Syntax Checking error messages from COBCH1661 through COBCH1680.

  • COBCH1661 Must specify an initial value
    The PERFORM USING statement must specify an initial value for the USING operand.
  • COBCH1662 Can only specify a single expression without a local variable definition
    When using the PERFORM USING statement, multiple operands can be specified provided they are specified as locals within the statement (using AS syntax). If the PERFORM USING references an item that is already declared, then only one such operand is allowed.
  • COBCH1663 Overlapping perform range: <n> entries
    Overlapping PERFORM ranges have been detected in the source code.
  • COBCH1664 Perform range:<procedure-name1> thru <procedure-name2>
    Overlapping PERFORM ranges have been detected in the source code.
  • COBCH1665 Cannot use OCCURS DEPENDING ON with object type
    The OCCURS DEPENDING ON clause has been specified on an incompatible type.
  • COBCH1666 Iterators properties and indexers cannot have reference parameters
    You have attempted to define a by reference parameter to an iterator, property or indexer.
  • COBCH1667 Perform range end before start
    The overlapping PERFORM range, indicated by the preceding COBCH1664, is a result of the end of the PERFORM range preceding the start of the PERFORM range.
  • COBCH1668 Paragraph "procedure-name1" in perform range contains a "GO TO procedure-name2", which causes overlap
    The overlapping PERFORM range, indicated by the preceding COBCH1664, is caused by one or more GO TO statements in paragraph “procedure-name1”.
  • COBCH1669 Cannot construct an instance of abstract class <class-name>
    An attempt has been made to instantiate an abstract class.
  • COBCH1670 TYPE missing preceding class name <class-name> - assumed
    The keyword TYPE is missing from an inherits phrase.
  • COBCH1671 Not a valid dictionary iterator
    The key or value phrase of the perform syntax has been specified on a collection that is not a valid dictionary.
  • COBCH1672 Dictionary key has incompatible type
    The perform varying key phrase has been specified with a type not compatible with the definition of the dictionary.
  • COBCH1673 Dictionary value has incompatible type
    The perform varying value phrase has been specified with a type not compatible with the definition of the dictionary.
  • COBCH1674 Internal dictionary overflow. Program too large
    The program contains too many items, and has caused the compiler's internal dictionary to overflow.
  • COBCH1675 Could not find event event1
    The event referenced in an ATTACH or DETACH statement could not be found.
  • COBCH1676 Anonymous method code cannot include GO TO or out-of-line PERFORM
    The code for an anonymous method includes an out-of-line perform statement or a GO TO statement.
  • COBCH1677 Anonymous method code cannot include another anonymous method
    The code for an anonymous method includes another anonymous method.
  • COBCH1678 Two parameters have same external name param1
    The external names of two parameters specified in PROCEDURE DIVISION USING signature are the same. .
  • COBCH1679 PIC N (USAGE DISPLAY-1 or no USAGE) only allowed with runtime-encoding set to OEM
    A data item in the source code has been specified as PIC N with USAGE DISPLAY-1, or with no USAGE specified, but the RUNTIME-ENCODING Compiler directive is set incorrectly.
  • COBCH1680 Badly formatted XML comment for <item-name>. XML loader message follows
    XML syntax, used as part of the ILDOC Compiler directive, is badly formed.
Parent topic: Messages COBCH1601 - COBCH1700


COBCH1661 Must specify an initial value

The PERFORM USING statement must specify an initial value for the USING operand.

In the following example, the operand d1 must be given an initial value by the PERFORM statement. Append = "initial-value" to the PERFORM USING statement.

class-id myClass.
method-id myMethod.
 perform using d1 as type java.lang.AutoCloseable  *> add = "<init_value>" to this line
     continue
 end-perform
end method.
end class.
Parent topic: COBCH1661 - COBCH1680
Related tasks
PERFORM Statement


COBCH1662 Can only specify a single expression without a local variable definition

When using the PERFORM USING statement, multiple operands can be specified provided they are specified as locals within the statement (using AS syntax). If the PERFORM USING references an item that is already declared, then only one such operand is allowed.
class-id a.
method-id m.
01 d2 type java.lang.AutoCloseable.
  perform using d1 as type java.lang.AutoCloseable = null d2
        continue
  end-perform.
end method.
end class.
Parent topic: COBCH1661 - COBCH1680
Related tasks
PERFORM Statement


COBCH1663 Overlapping perform range: <n> entries

Overlapping PERFORM ranges have been detected in the source code.
Note: This error message is only applicable to managed COBOL, and then only when compiled with the ILSHOWPERFORMOVERLAP directive.

When an overlapping PERFORM range has been detected, this error message indicates the start of the first affected range and the number of overlapping PERFORM ranges.

Refer to COBCH1664 Perform range: <procedure-name1> thru <procedure-name2> for more details on where those overlaps occur.

$set ilshowperformoverlap
 ...
 perform a thru c.
 perform c thru f.
 perform f.
 goback.
                               *> errors are displayed as follows:
 a section.
 display "Running section a.". *> COBCH1663E Overlapping perform range: 3 entries
                               *> COBCH1664E    perform range: a thru c
 b section.
 display "Running section b.".
 c section.                    *> COBCH1664E    perform range: c thru f
 display "Running section c.".
 d section.
 display "Running section d.".
 e section.
 display "Running section e.".
 f section.                    *> COBCH1664E    perform range: f thru f
 display "Running section f.".
Parent topic: COBCH1661 - COBCH1680
Related concepts
ILSHOWPERFORMOVERLAP
Related reference
COBCH1664 Perform range:<procedure-name1> thru <procedure-name2>
COBCH1667 Perform range end before start
COBCH1668 Paragraph "procedure-name1" in perform range contains a "GO TO procedure-name2", which causes overlap


COBCH1664 Perform range:<procedure-name1> thru <procedure-name2>

Overlapping PERFORM ranges have been detected in the source code.
Note: This error message is only applicable to managed COBOL, and then only when compiled with the ILSHOWPERFORMOVERLAP directive.

The error message indicates the beginning and ending procedures of one of the overlapping PERFORM ranges indicated by COBCH1663.

When no section name is present at the beginning of the PROCEDURE DIVISION, <procedure-name1> is displayed as {procedure division entry}. When a PERFORM range extends off the end of a program, <procedure-name-1> is displayed as {end procedure division}. When a PERFORM range begins at an ENTRY statement, <procedure-name-1> is displayed as {entry ""}.

$set ilshowperformoverlap
 ...
 perform a thru c.
 perform c thru f.
 perform f.
 goback.
                               *> errors are displayed as follows:
 a section.
 display "Running section a.". *> COBCH1663E Overlapping perform range: 3 entries
                               *> COBCH1664E    perform range: a thru c
 b section.
 display "Running section b.".
 c section.                    *> COBCH1664E    perform range: c thru f
 display "Running section c.".
 d section.
 display "Running section d.".
 e section.
 display "Running section e.".
 f section.                    *> COBCH1664E    perform range: f thru f
 display "Running section f.".
Parent topic: COBCH1661 - COBCH1680
Related concepts
ILSHOWPERFORMOVERLAP
Related reference
COBCH1663 Overlapping perform range: <n> entries
COBCH1667 Perform range end before start
COBCH1668 Paragraph "procedure-name1" in perform range contains a "GO TO procedure-name2", which causes overlap


COBCH1665 Cannot use OCCURS DEPENDING ON with object type

The OCCURS DEPENDING ON clause has been specified on an incompatible type.
You cannot specify the OCCURS DEPENDING ON clause for object references. This includes the following built-in types:
  • String
  • Object
  • Decimal
  • Character
01 b-shelf string occurs 1 to 30 times depending on cab-size. *> cannot use on type string
Parent topic: COBCH1661 - COBCH1680


COBCH1666 Iterators properties and indexers cannot have reference parameters

You have attempted to define a by reference parameter to an iterator, property or indexer.

Parameters must be passed by value, not by reference, when used in iterators, properties and indexers.

class-id SimpleIndexer.
01 myArray string occurs 100.

indexer-id string.
procedure division using by reference i as binary-long.  *> i must be passed by value
getter.
set property-value to myArray[i]
setter.
set myArray[i] to property-value
end indexer.

end class.
Parent topic: COBCH1661 - COBCH1680
Related reference
Iterators
Properties
Indexers


COBCH1667 Perform range end before start

The overlapping PERFORM range, indicated by the preceding COBCH1664, is a result of the end of the PERFORM range preceding the start of the PERFORM range.
Note: This error message is only applicable to managed COBOL, and then only when compiled with the ILSHOWPERFORMOVERLAP directive.

The following example generates such an error due to the end of the range in the second PERFORM statement:

$set ilshowperformoverlap
...
perform a thru c.
perform c thru b.
goback.
                  *>  Errors are displayed as follows:
a section.        *>  COBCH1663E Overlapping perform range: 2 entries
display "In a".   *>  COBCH1664E    perform range: a thru c

b section.
display "In b".

c section.        *>   COBCH1664E    Perform range: c thru b
display "In c".   *>   COBCH1667E       perform range end before start
go to a.
Parent topic: COBCH1661 - COBCH1680
Related concepts
ILSHOWPERFORMOVERLAP
Related reference
COBCH1663 Overlapping perform range: <n> entries
COBCH1664 Perform range:<procedure-name1> thru <procedure-name2>
COBCH1668 Paragraph "procedure-name1" in perform range contains a "GO TO procedure-name2", which causes overlap


COBCH1668 Paragraph "procedure-name1" in perform range contains a "GO TO procedure-name2", which causes overlap

The overlapping PERFORM range, indicated by the preceding COBCH1664, is caused by one or more GO TO statements in paragraph “procedure-name1”.
Note: This error message is only applicable to managed COBOL, and then only when compiled with the ILSHOWPERFORMOVERLAP directive.

When a section has statements before a paragraph header and those statements (which form an unnamed paragraph) include a GO TO statement that causes a PERFORM range overlap, "procedure-name1" is displayed as "{implied first paragraph} of section-name".

In the following example, the GO TO in paragraph x1 is causing the error. One possible correction could be to change the GO TO statement to a PERFORM statement followed by a GO TO statement that refers to the desired PERFORM range end procedure. However, other PERFORM range structure problems might be the cause of the GO TO statement causing a PERFORM range overlap.

$set ilshowperformoverlap
...
01 i pic 9(4) binary value 0.

perform b1 thru e1.
perform b2 thru e2.
goback.
                 *>  Errors are displayed as follows:
b1.              *>  COBCH1663E Overlapping perform range: 2 entries
if i = 0         *>  COBCH1664E    perform range: b1 thru e1
   go to x1
end-if.
go to x2.

b2.              *>  COBCH1664E    perform range: b2 thru e2
if i = 0         *>  COBCH1668E       paragraph "x1" in perform range contains a "GO TO b1", which causes overlap
   go to x2
end-if.

x1.
display "In x1".
go to b1.

x2.
display "In x2".

e1.
display "In e1".

e2.
display "In e2".
...
Parent topic: COBCH1661 - COBCH1680
Related concepts
ILSHOWPERFORMOVERLAP
Related reference
COBCH1663 Overlapping perform range: <n> entries
COBCH1664 Perform range:<procedure-name1> thru <procedure-name2>
COBCH1667 Perform range end before start


COBCH1669 Cannot construct an instance of abstract class <class-name>

An attempt has been made to instantiate an abstract class.
You cannot instantiate a class that has been specified with the ABSTRACT keyword.
class-id myClass1.
method-id main static.
  declare obj1 as object = new myClass2
end method.
end class.
class-id myClass2 abstract.  *> cannot instantiate this class
...
end class.
Parent topic: COBCH1661 - COBCH1680


COBCH1670 TYPE missing preceding class name <class-name> - assumed

The keyword TYPE is missing from an inherits phrase.

In the following example, insert the type keyword in the inherits clause: class-id myClass2 inherits type myClass3.

class-id myClass1.
method-id main static.
 declare o as object = new myClass2
end method.
end class.
class-id myClass2 inherits myClass3.  *> TYPE missing
...
end class.
class-id myClass3.
...
end class.
Parent topic: COBCH1661 - COBCH1680


COBCH1671 Not a valid dictionary iterator

The key or value phrase of the perform syntax has been specified on a collection that is not a valid dictionary.

In the following example, the key phrase is specified on a list, not a dictionary. You must either remove the key phrase to perform the iteration, or change the definition of myCollect to a dictionary.

...
declare myCollect as list[string]
perform varying key s as string through myCollect
  display s
end-perform
...
Parent topic: COBCH1661 - COBCH1680


COBCH1672 Dictionary key has incompatible type

The perform varying key phrase has been specified with a type not compatible with the definition of the dictionary.

In the following example, a dictionary with a key of type binary-long has been specified, but the perform varying key phrase attempts to reference it as type string. You need to specify matching or compatible types.

...
declare myCollect as dictionary[binary-long, string]  *> the key specified as binary-long
perform varying key s as string through myCollect     *> and then referenced as string
 display s
end-perform
...
Parent topic: COBCH1661 - COBCH1680


COBCH1673 Dictionary value has incompatible type

The perform varying value phrase has been specified with a type not compatible with the definition of the dictionary.

In the following example, a dictionary with a value of type binary-long has been specified, but the perform varying value phrase attempts to reference it as type string. You need to specify matching or compatible types.

...
declare myCollect as dictionary[binary-long, binary-long] *> the value specified as binary-long
perform varying value s as string through myCollect       *> and then referenced as string
 display s
end-perform
...
Parent topic: COBCH1661 - COBCH1680


COBCH1674 Internal dictionary overflow. Program too large

The program contains too many items, and has caused the compiler's internal dictionary to overflow.

The definition 'items' includes procedure names, call conventions, file definitions, and all data items, including filler items (whether or not keyword FILLER is used). You should modularize the program to reduce the number of items in it.

Parent topic: COBCH1661 - COBCH1680


COBCH1675 Could not find event event1

The event referenced in an ATTACH or DETACH statement could not be found.

In the following example, the event MyEvent is missing from the class.

class-id MyClass.

method-id main static.
 attach method self::MyMethod to self::MyEvent
end method.

method-id MyMethod static.
...
end method.

end class.

Parent topic: COBCH1661 - COBCH1680
Related concepts
Delegates and Events


COBCH1676 Anonymous method code cannot include GO TO or out-of-line PERFORM

The code for an anonymous method includes an out-of-line perform statement or a GO TO statement.

In the example below, you must remove the PERFORM and the GO TO statements from the delegate declaration.

Note: In-line PERFORM statements are permitted.
class-id MyClass.
method-id main static.
01 del type MyDelegate.
set del to delegate
    perform s1           *> must be removed
    go to exit-para      *> must be removed
end-delegate
goback.
s1 section.
display "Start".
s2 section.
exit-para.
 goback.
end method.
end class.
delegate-id MyDelegate.
end delegate.
Parent topic: COBCH1661 - COBCH1680
Related concepts
Delegates and Events


COBCH1677 Anonymous method code cannot include another anonymous method

The code for an anonymous method includes another anonymous method.

In the following example, you must remove the set del to delegate end-delegate code so that the first delegate declaration doesn't include a nested anonymous method.

class-id MyClass.
method-id main static.
01 del type MyDelegate.
set del to delegate
  set del to delegate end-delegate  *> code cannot include another anon method
end-delegate
goback.
end method.
end class.
delegate-id MyDelegate.
end delegate.
Parent topic: COBCH1661 - COBCH1680
Related concepts
Delegates and Events


COBCH1678 Two parameters have same external name param1

The external names of two parameters specified in PROCEDURE DIVISION USING signature are the same. .

This situation can arise when both parameters share the same COBOL name, except that one is prefixed with the '#' character.

In the following example, change one of the parameter names in the signature.

class-id MyClass.
method-id MyMethod.
 procedure division using by value p1 as binary-long #p1 as binary-long.
end method.
end class.
Parent topic: COBCH1661 - COBCH1680


COBCH1679 PIC N (USAGE DISPLAY-1 or no USAGE) only allowed with runtime-encoding set to OEM

A data item in the source code has been specified as PIC N with USAGE DISPLAY-1, or with no USAGE specified, but the RUNTIME-ENCODING Compiler directive is set incorrectly.

If your source code contains such data items, RUNTIME-ENCODING"OEM" must be in effect, either implicitly, or by use of the RUNTIME-ENCODING"OEM" Compiler directive.

Parent topic: COBCH1661 - COBCH1680
Related reference
RUNTIME-ENCODING


COBCH1680 Badly formatted XML comment for <item-name>. XML loader message follows

XML syntax, used as part of the ILDOC Compiler directive, is badly formed.

This message is accompanied by COBCH1681, which contains details of the syntax in error.

In the following example, a closing </summary> tag is missing in the line preceding the class-id.

...
*>> <summary>
*>> My summary info...
class-id myClass.  *> insert closing </summary> above
...
Parent topic: COBCH1661 - COBCH1680
Related reference
COBCH1681 <XML Loader output>


COBCH1681 - COBCH1700

Lists the Syntax Checking error messages from COBCH1681 through COBCH1700.

  • COBCH1681 <XML Loader output>
    This is the output from the XML loader when it fails to load an XML comment. It follows the COBCH1680 message.
  • COBCH1682 XML comment has cref attribute <attrib-name> that could not be resolved
    The cref attribute specified a name that cannot be resolved to a known type or member.
  • COBCH1683 Repeated information for parameter <param-name> in XML comment for <name>
    A parameter name has been specified more than once.
  • COBCH1684 Missing information for parameter <param-name> in XML comment for <name>
    The source code contains parameter comments, but not all parameters have been specified.
  • COBCH1685 Unknown parameter name <param-name> in XML comment for <name>
    An XML comment has been specified for an unknown parameter.
  • COBCH1686 Ambiguous match for method <method-name> with this signature - will generate dynamic call
    The compiler cannot distinguish between multiple call targets.
  • COBCH1687 Only value NULL allowed here
    A level 88 condition value other than NULL has been specified for a pointer data item.
  • COBCH1688 Level 88 not allowed with value type
    A level 88 condition has been specified with an incompatible value type.
  • COBCH1689 Only valid with ODOSLIDE
    An unbounded table has been specified without the ODOSLIDE directive being set.
  • COBCH1690 Invalid use of UNBOUNDED group
    The UNBOUNDED keyword has been specified illegally.
  • COBCH1691 Internal literal pool overflow - Program too large
    The quantity and size of the literals in your program are greater than the compiler's internal limit.
  • COBCH1692 Too many DETAIL groups specified for report
    The number of DETAIL groups per report has been exceeded.
  • COBCH1699 A CONSTANT item cannot be a receiving item
    An operation has attempted to change the value of an item specified with the CONSTANT keyword.
  • COBCH1700 A CONSTANT item must have a VALUE clause
    A field has been specified with the CONSTANT keyword, but has no VALUE clause specified.
Parent topic: Messages COBCH1601 - COBCH1700


COBCH1681 <XML Loader output>

This is the output from the XML loader when it fails to load an XML comment. It follows the COBCH1680 message.

The following syntax results in the message COBCH1681 The summary start tag on line 1 position 11 does not match the end tag of 'member' line 3 position 3.

Note: The line numbers in the message are relative to start of the XML comment.
...
*>> <summary>
*>> My summary info...
class-id myClass.
...

Insert a closing </summary> tag in the line preceding the class-id to correct the error.

Parent topic: COBCH1681 - COBCH1700
Related reference
COBCH1680 Badly formatted XML comment for <item-name>. XML loader message follows


COBCH1682 XML comment has cref attribute <attrib-name> that could not be resolved

The cref attribute specified a name that cannot be resolved to a known type or member.

In the following example, the type redClass is missing, and therefore cannot be resolved. You must either remove or edit the reference, or add the type to your code.

$set ILDOC"cbloutput.xml"
 class-id new.
 *>> <summary>
 *>> Contains the name of <see cref="redClass" /><see cref="whiteClass" /><see cref="blue" />.
 *>> </summary>
 01 blue  string.
 ...
 end class.
 class-id whiteClass.
 ...
 end class.
Parent topic: COBCH1681 - COBCH1700


COBCH1683 Repeated information for parameter <param-name> in XML comment for <name>

A parameter name has been specified more than once.

In the following example, the message parameter is specified twice. You must delete one of the entries.

class-id a.
 *>> <summary>
 *>> Displays a message
 *>> </summary>
 *>> <param name="message"> The message to be displayed in the console window.</param>
 *>> <param name="message"> The message displayed.</param>
 method-id MsgOut.
 procedure division using by value #message as string.
 display #message
 end method.
 end class.

When specified correctly, the parameter comments appear on the ToolTip.

Parent topic: COBCH1681 - COBCH1700


COBCH1684 Missing information for parameter <param-name> in XML comment for <name>

The source code contains parameter comments, but not all parameters have been specified.

If you include an XML comment for one parameter, you must also include comments for all other parameters.

In the following example, you must add an XML comment for the #message2 parameter.

class-id a.
 *>> <summary>
 *>> Displays a message
 *>> </summary>
 *>> <param name="message1"> The message to be displayed in the console window.</param>

 method-id MsgOut.
 procedure division using by value #message1 as string by value #message2 as string.
 display #message1
 display #message2
 end method.
 end class.

When specified correctly, the parameter comments appear on the ToolTip.

Parent topic: COBCH1681 - COBCH1700


COBCH1685 Unknown parameter name <param-name> in XML comment for <name>

An XML comment has been specified for an unknown parameter.

In the following example, an XML comment has been specified for the #message2 parameter, but that parameter is not defined in the source code. You must delete the XML comment.

class-id a.
 *>> <summary>
 *>> Displays a message
 *>> </summary>
 *>> <param name="message1"> The message to be displayed on the first line.</param>
 *>> <param name="message2"> The message to be displayed on the second line.</param>
 method-id MsgOut.
 procedure division using by value #message1 as string.
 display #message1
 end method.
 end class.
Parent topic: COBCH1681 - COBCH1700


COBCH1686 Ambiguous match for method <method-name> with this signature - will generate dynamic call

The compiler cannot distinguish between multiple call targets.

In the following example, the call from program a cannot determine which target to call: program b or entry point b in program c. In these cases, the call is made dynamically at run-time.

program-id a.
call "b" using 1 2
end program.

program-id b.
linkage section.
 01 n1 binary-long.
 01 n2 binary-long.
procedure division using by value n1 n2.
display n1 space n2
end program b.

program-id c.
linkage section.
 01 n1 binary-long.
 01 n2 binary-long.
procedure division using by value n1 n2.
entry "b" using by value n1 n2
display n1 space n2
end program c.
Parent topic: COBCH1681 - COBCH1700


COBCH1687 Only value NULL allowed here

A level 88 condition value other than NULL has been specified for a pointer data item.

For data items of type pointer, the only valid value in an associated level 88 condition name is NULL (or NULLS).

01 my-pointer pointer.
  88 cond-value value "000000016"  *> not allowed - can only specify NULL
Parent topic: COBCH1681 - COBCH1700


COBCH1688 Level 88 not allowed with value type

A level 88 condition has been specified with an incompatible value type.

You cannot specify a level 88 condition for non-standard value types; that is, value types such as decimal, character, and value-type. However, you can specify level 88 conditions on standard value types, such as binary-long and float-short.

01 n1 decimal.             *> not allowed
  88 cond-1 value null.
01 c1 character.           *> not allowed
  00 cond-2 value null.
01 d1 type System.DateTime.*> not allowed
  88 cond-3 value null.
01 p1 type MyValueType.    *> not allowed
  88 cond-4 value null.
01 l1 float-long.          *> allowed
  88 cond-5 value null.
01 s1 binary-short.        *> allowed
  88 cond-6 value null.
end program.
valuetype-id MyValueType.
01 inst binary-long.
end valuetype.
Parent topic: COBCH1681 - COBCH1700


COBCH1689 Only valid with ODOSLIDE

An unbounded table has been specified without the ODOSLIDE directive being set.

You can only specify a table as UNBOUNDED if you have also set the ODOSLIDE Compiler directive.

Parent topic: COBCH1681 - COBCH1700


COBCH1690 Invalid use of UNBOUNDED group

The UNBOUNDED keyword has been specified illegally.

See The Occurs Clause for the syntax rules of an unbounded group.

Parent topic: COBCH1681 - COBCH1700
Related reference
The OCCURS Clause


COBCH1691 Internal literal pool overflow - Program too large

The quantity and size of the literals in your program are greater than the compiler's internal limit.
You must reduce the number and/or size of the literals in your program or split your program into smaller ones.
Parent topic: COBCH1681 - COBCH1700


COBCH1692 Too many DETAIL groups specified for report

The number of DETAIL groups per report has been exceeded.

Each report can specify no more than 254 DETAIL groups.

Parent topic: COBCH1681 - COBCH1700


COBCH1699 A CONSTANT item cannot be a receiving item

An operation has attempted to change the value of an item specified with the CONSTANT keyword.

You cannot change the value of items marked with the CONSTANT keyword.

01 field1 CONSTANT VALUE "hello".
set field1 = "goodbye" *> you cannot perform this operation on a CONSTANT item
Parent topic: COBCH1681 - COBCH1700


COBCH1700 A CONSTANT item must have a VALUE clause

A field has been specified with the CONSTANT keyword, but has no VALUE clause specified.

Add a VALUE clause to the declaration or remove the CONSTANT keyword.

...
01 field1 CONSTANT.               *> this is incorrect
01 field2 CONSTANT VALUE "Hello". *> this is correct
...
Parent topic: COBCH1681 - COBCH1700


Messages COBCH1701 - COBCH1800

  • COBCH1701 - COBCH1720
    Lists the Syntax Checking error messages from COBCH1701 through COBCH1720.
  • COBCH1721 - COBCH1740
    Lists the Syntax Checking error messages from COBCH1721 through COBCH1740.
  • COBCH1741 - COBCH1760
    Lists the Syntax Checking error messages from COBCH1741 through COBCH1760.
  • COBCH1761 - COBCH1780
    Lists the Syntax Checking error messages from COBCH1761 through COBCH1780.
  • COBCH1781 - COBCH1800
Parent topic: Syntax Checking Error Messages


COBCH1701 - COBCH1720

Lists the Syntax Checking error messages from COBCH1701 through COBCH1720.

  • COBCH1701 A CONSTANT item cannot be a group
    The CONSTANT keyword has been specified on a group item.
  • COBCH1702 The value of CONSTANT item <field1> involves circular definition
    A circular definition has been created in the value of a CONSTANT.
  • COBCH1703 CLSCompliant(false) not needed for <member> as assembly does not have CLSCompliant attribute
    The attribute CLSCompliant(true) is not set for the containing assembly, and therefore the attribute CLSCompliant(false) is not required for any of its members.
  • COBCH1704 CLSCompliant(true) not allowed for <member> as assembly does not have CLSCompliant attribute
    The attribute CLSCompliant(true) is not set for the containing assembly, and therefore this element (and other elements in the assembly) cannot claim to be CLS compliant.
  • COBCH1705 Parameter type <type> of <member> is not CLS compliant
    A parameter in the member marked as CLS compliant is not using a compliant type.
  • COBCH1706 Member type <type> of <member> is not CLS compliant
    The member marked as CLS compliant is not using a compliant type.
  • COBCH1707 Member <member> is not CLS compliant because it differs from another member only by case
    A member that is marked as CLS compliant has the same name as another member in the assembly, differing only by case.
  • COBCH1708 More than one method <method-name> exists in <class-name> requiring parameter truncation
    Method invocation has identified more than one possible target method, and those targets may result in parameter truncation.
  • COBCH1710 <class-name> has no member with name <member-name>
    A member has been referenced that does not exist.
  • COBCH1711 <class-name> has no visible method <method-name> with <number> parameter(s)
    The specified type has no method with the specified name and number of parameters.
  • COBCH1712 <class-name> has no visible instance method <method-name> with <number> parameter(s)
    The specified type has no instance method with the specified name and number of parameters.
  • COBCH1713 <class-name> has no visible static method <method-name> with <number> parameter(s)
    The specified type has no static method with the specified name and number of parameters.
  • COBCH1714 <type-name> has no visible constructor with <number> parameter(s)
    The specified type has no constructor with the specified number of parameters.
  • COBCH1715 Best visible overload found in <type-name> is <member-name> which has invalid parameter <param-num>
    The specified type has no method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.
  • COBCH1716 Best visible instance overload found in <type-name> is <method-name> which has invalid parameter <param-num>
    The specified type has no instance method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.
  • COBCH1717 Best visible static overload found in <type-name> is <member-name> which has invalid parameter <param-num>
    The specified type has no static method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.
  • COBCH1718 Best visible constructor in <type-name> is <member-name> which has invalid parameter <param-num>
    The specified type has no constructor with matching parameters. The error message shows the constructor with the best match, and indicates the parameter that fails to match.
  • COBCH1719 Must specify an EVENT
    The target of an attach or detach statement must refer to an event.
Parent topic: Messages COBCH1701 - COBCH1800


COBCH1701 A CONSTANT item cannot be a group

The CONSTANT keyword has been specified on a group item.

Only elementary items can be specified with the CONSTANT keyword.

...
01 group1 CONSTANT.                      *> this is incorrect
   03 group-field1 pic x(10).
01 field1 string CONSTANT VALUE "hello". *> this is correct
...
Parent topic: COBCH1701 - COBCH1720


COBCH1702 The value of CONSTANT item <field1> involves circular definition

A circular definition has been created in the value of a CONSTANT.

You must change the VALUE clause so that it does not refer back to itself.

In the following example, all three fields in class a contain a circular definition.

class-id a.
01 n1 binary-long PUBLIC CONSTANT VALUE TYPE a::n2.
01 n2 binary-long PUBLIC CONSTANT VALUE TYPE a::n1 + 1.
01 i1 binary-long PUBLIC CONSTANT VALUE TYPE b::i1.
method-id main STATIC.
 display n1
 display n2
end method.
end class.

class-id b.
01 i1 binary-long PUBLIC CONSTANT VALUE TYPE c::i1.
end class.

class-id c.
01 i1 binary-long PUBLIC CONSTANT VALUE TYPE a::i1.
end class.
Parent topic: COBCH1701 - COBCH1720


COBCH1703 CLSCompliant(false) not needed for <member> as assembly does not have CLSCompliant attribute

The attribute CLSCompliant(true) is not set for the containing assembly, and therefore the attribute CLSCompliant(false) is not required for any of its members.

Remove any CLSCompliant(false) attributes from assembly members.

class-id myClass.

01 myField1 binary-long signed attribute CLSCompliant(false). *> remove this attribute

method-id myMethod attribute CLSCompliant(false). *> remove this attribute
...
end method.
end class.

The rules for setting the CLSCompliant attribute:

  • Setting the attribute at the assembly level assumes that all members within it are CLS compliant, and the Compiler issues warnings where that is not the case.
  • When the attribute is set at the assembly level, set the attribute CLSCompliant(false) on individual members to suppress the warnings.
  • When the attribute is set on a method or field, it must also be set on the containing class or assembly.
  • When the attribute is set on a class, it must also be set on the containing assembly.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Assembly-Attributes Paragraph
Attribute Clause - Syntax


COBCH1704 CLSCompliant(true) not allowed for <member> as assembly does not have CLSCompliant attribute

The attribute CLSCompliant(true) is not set for the containing assembly, and therefore this element (and other elements in the assembly) cannot claim to be CLS compliant.

Set the CLSCompliant(true) attribute in the assembly-attributes paragraph, or remove the attribute from the assembly member.

class-id myClass.
assembly-attributes.             *> add these two lines
 attribute CLSCompliant(true).   *> to enable the other CLSCompliant attribs

01 myfield1 binary-long signed attribute CLSCompliant(true). *> or remove this attribute

method-id myMethod attribute CLSCompliant(true). *> and remove this attribute
...
end method.
end class.

The rules for setting the CLSCompliant attribute:

  • Setting the attribute at the assembly level assumes that all members within it are CLS compliant, and the Compiler issues warnings where that is not the case.
  • When the attribute is set at the assembly level, set the attribute CLSCompliant(false) on individual members to suppress the warnings.
  • When the attribute is set on a method or field, it must also be set on the containing class or assembly.
  • When the attribute is set on a class, it must also be set on the containing assembly.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Assembly-Attributes Paragraph
Attribute Clause - Syntax


COBCH1705 Parameter type <type> of <member> is not CLS compliant

A parameter in the member marked as CLS compliant is not using a compliant type.

You need to either change the type to one that is compliant, or set the CLSCompliant(false) attribute for the member.

class-id myClass.
assembly-attributes.
 attribute CLSCompliant(true).

method-id myMethod attribute CLSCompliant(true).                   *> set attrib to false
procedure division using by value myParam as binary-long unsigned. *> or change type of myParam
...
end method.
end class.

The rules for setting the CLSCompliant attribute:

  • Setting the attribute at the assembly level assumes that all members within it are CLS compliant, and the Compiler issues warnings where that is not the case.
  • When the attribute is set at the assembly level, set the attribute CLSCompliant(false) on individual members to suppress the warnings.
  • When the attribute is set on a method or field, it must also be set on the containing class or assembly.
  • When the attribute is set on a class, it must also be set on the containing assembly.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Assembly-Attributes Paragraph
Attribute Clause - Syntax


COBCH1706 Member type <type> of <member> is not CLS compliant

The member marked as CLS compliant is not using a compliant type.

You need to either change the type to one that is compliant, or set the CLSCompliant(false) attribute for the member.

class-id myClass.
assembly-attributes.
 attribute CLSCompliant(true).

01 myfield1 binary-long unsigned attribute CLSCompliant(true).  *> change type or set attrib to false

method-id myMethod attribute CLSCompliant(true).
...
end method.
end class.

The rules for setting the CLSCompliant attribute:

  • Setting the attribute at the assembly level assumes that all members within it are CLS compliant, and the Compiler issues warnings where that is not the case.
  • When the attribute is set at the assembly level, set the attribute CLSCompliant(false) on individual members to suppress the warnings.
  • When the attribute is set on a method or field, it must also be set on the containing class or assembly.
  • When the attribute is set on a class, it must also be set on the containing assembly.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Assembly-Attributes Paragraph
Attribute Clause - Syntax


COBCH1707 Member <member> is not CLS compliant because it differs from another member only by case

A member that is marked as CLS compliant has the same name as another member in the assembly, differing only by case.

You need to rename one of the members, or set the CLSCompliant(false) attribute on the members whose names differ only by case, and which have the same signature.

class-id myClass.
assembly-attributes.
 attribute CLSCompliant(true).

method-id myMethod.  *> add attribute CLSCompliant(false)
procedure division using by value myParam as binary-long unsigned.
...
end method.
method-id MYMethod.  *> add attribute CLSCompliant(false)
procedure division using by value myParam as binary-long unsigned.
...
end method.
end class.

The rules for setting the CLSCompliant attribute:

  • Setting the attribute at the assembly level assumes that all members within it are CLS compliant, and the Compiler issues warnings where that is not the case.
  • When the attribute is set at the assembly level, set the attribute CLSCompliant(false) on individual members to suppress the warnings.
  • When the attribute is set on a method or field, it must also be set on the containing class or assembly.
  • When the attribute is set on a class, it must also be set on the containing assembly.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Assembly-Attributes Paragraph
Attribute Clause - Syntax


COBCH1708 More than one method <method-name> exists in <class-name> requiring parameter truncation

Method invocation has identified more than one possible target method, and those targets may result in parameter truncation.

An ambiguity exists because a method invoke could be satisfied by two target methods, both of which would require possible parameter truncation. The normal search for a best method is only applicable when no parameter truncation is required.

In the following example, the n1 field of type binary-double could possibly be truncated when passed into either method and converted to either binary-char or binary-short. In this circumstance, you must ensure that the types are compatible, in a way that no truncation occurs.

class-id a.
method-id main static.
declare n1 as binary-double
invoke self::m(n1)
end method.

method-id m static.
procedure division using by value n as binary-char.
 display n
end method.

method-id m static.
procedure division using by value n as binary-short.
 display n
end method.
end class.
Parent topic: COBCH1701 - COBCH1720


COBCH1710 <class-name> has no member with name <member-name>

A member has been referenced that does not exist.

In the following example, the messageStart method is missing.

class-id myClass.
method-id main.
 display self::messageStart
end method.
method-id messageEnd returning val as string.
 set val = "End of Program."
end method.
end class.
Parent topic: COBCH1701 - COBCH1720


COBCH1711 <class-name> has no visible method <method-name> with <number> parameter(s)

The specified type has no method with the specified name and number of parameters.

In the following example, the messsgeEnd method does not take the parameter 4 that has been attempted to pass to it.

class-id myClass.
method-id main.
 display self::messageEnd(4)
end method.
method-id messageEnd returning val as string.
 set val = "End of Program."
end method.
end class.
Parent topic: COBCH1701 - COBCH1720


COBCH1712 <class-name> has no visible instance method <method-name> with <number> parameter(s)

The specified type has no instance method with the specified name and number of parameters.

In the following example, the messsgeEnd method takes two parameters, and not just the argument 4 that has been passed to it.

class-id myClass.
method-id main.
 declare myObj as type myClass
    invoke myObj::messageEnd(4)
end method.
method-id messageEnd (n as float-short s as string).
...
end method.
end class.

This message is produced in contexts when an instance method is required.

Parent topic: COBCH1701 - COBCH1720


COBCH1713 <class-name> has no visible static method <method-name> with <number> parameter(s)

The specified type has no static method with the specified name and number of parameters.

In the following example, the messsgeEnd method does not take the parameter 4 that has been attempted to pass to it.

class-id myClass.
method-id main static.
 display self::messageEnd(4)
end method.
method-id messageEnd returning val as string static.
 set val = "End of Program."
end method.
end class.

This message is produced in contexts when a static method is required.

Parent topic: COBCH1701 - COBCH1720


COBCH1714 <type-name> has no visible constructor with <number> parameter(s)

The specified type has no constructor with the specified number of parameters.

In the following example, the type axel does not contain a constructor with 1 parameter; it only contains the default constructor, which has no parameters.

class-id axel.
method-id main.
  declare a-size as string
  declare obj as type axel
  set obj to new axel(a-size)
end method.
end class.
Parent topic: COBCH1701 - COBCH1720


COBCH1715 Best visible overload found in <type-name> is <member-name> which has invalid parameter <param-num>

The specified type has no method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.

In the following example, there is no compatible match for the call to messageEnd using the arguments supplied. There is a method with the correct name and same number of parameters; however, the second parameter is not a compatible match. Either change the second argument to be compatible with a decimal type, or change the messageEnd method to accept a type compatible with a string as its second parameter.

class-id myClass.
method-id main.
 invoke self::messageEnd(4 "Installation Complete")
end method.
method-id messageEnd (s as decimal t as decimal).
...
end method.
end class.

This error is produced in a context in which either a static or an instance method would be allowed.

Parent topic: COBCH1701 - COBCH1720
Related information
Method Overloading in Managed COBOL


COBCH1716 Best visible instance overload found in <type-name> is <method-name> which has invalid parameter <param-num>

The specified type has no instance method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.

In the following example, there is no compatible match for the call to messageStart using the arguments supplied. There is a method with the correct name and same number of parameters; however, the parameter is not a compatible match. Either change the argument to be compatible with a string type, or change the messageStart method to accept a type compatible with a numeric.

class-id myClass2.
method-id main.
 declare messDisplay as type myClass2
 invoke messDisplay::messageStart(2)
end method.
method-id messageStart.
procedure division using by value s as string.
...
end method.
end class.

This error is produced in a context in which an instance method would be allowed.

Parent topic: COBCH1701 - COBCH1720
Related information
Method Overloading in Managed COBOL


COBCH1717 Best visible static overload found in <type-name> is <member-name> which has invalid parameter <param-num>

The specified type has no static method with matching parameters. The error message shows the method with the best match, and indicates the parameter that fails to match.

In the following example, there is no compatible match for the call to messageEnd using the arguments supplied. There is a method with the correct name and same number of parameters; however, the second parameter is not a compatible match. Either change the argument to a type compatible with decimal, or change the messageEnd method to accept a type compatible with string as its second parameter.

class-id myClass.
method-id main static.
 invoke self::messageEnd(4 "Installation Complete")
end method.
method-id messageEnd (s as decimal t as decimal) static.
...
end method.
end class.

This error is produced in a context in which a static method would be allowed.

Parent topic: COBCH1701 - COBCH1720
Related information
Method Overloading in Managed COBOL


COBCH1718 Best visible constructor in <type-name> is <member-name> which has invalid parameter <param-num>

The specified type has no constructor with matching parameters. The error message shows the constructor with the best match, and indicates the parameter that fails to match.

In the following example, there is no compatible match for the call to the new constructor using the argument supplied. There is a constructor with the same number of parameters; however, the parameter is not a compatible match. Either change the argument to be compatible with type string, or change the new constructor to accept a type compatible with a numeric.

class-id axel.
method-id main.
  declare obj as type axel
  set obj to new axel(3)
end method.
method-id new (s as string).
...
end method.
end class.
Parent topic: COBCH1701 - COBCH1720
Related information
Method Overloading in Managed COBOL


COBCH1719 Must specify an EVENT

The target of an attach or detach statement must refer to an event.

The target of an attach or detach statement must be an event; use the event keyword to specify an event. In the following example, the target of the attach statement is the member alarmSwitch, which has not been declared as an event.

class-id myScheduler.
01 alarmSwitch type alarmState static.  *> add the 'event' keyword
method-id main static.
  attach method self::setTime to self::alarmSwitch
end method.
method-id setTime static.
 ...
end method.
end class.

delegate-id alarmState.
 ...
end delegate.
Parent topic: COBCH1701 - COBCH1720
Related concepts
Delegates and Events


COBCH1721 - COBCH1740

Lists the Syntax Checking error messages from COBCH1721 through COBCH1740.
  • COBCH1721 <type-name> has no visible member <member-name> with no parameters
    The specified type has no visible member with the specified name that does not take any parameters.
  • COBCH1722 <type-name> has no visible instance member <member-name> with no parameters
    The specified type has no visible instance member with the specified name that does not take any parameters.
  • COBCH1723 <type-name> has no visible static member <member-name> with no parameters
    The specified type has no visible static member with the specified name that does not take any parameters.
  • COBCH1724 With JVMGEN, static method 'main' with single string array parameter cannot have a returning item
    A static main method has been specified with a single string array and a returning item.
  • COBCH1725 class-name has no visible constructor
    The specified class has no visible constructor. This message is generated when the specified class is static.
  • COBCH1726 ILSMARTLINKAGE class <class-name> has multiple definitions
    The ILSMARTLINKAGE directive has caused the generation of more than one class with the same name.
  • COBCH1727 '%1$s' is in the unreferenced assembly '%2$s'.
  • COBCH1728 <type-name1> does not have public implementation of method <method-name> of interface <type-name2>
    The specified method is missing from the class. It must exist due to the implementation of the specified interface.
  • COBCH1729 <type-name1> does not have a public implementation of property <property-name> of interface <type-name2>
    The specified property is missing from the class. It must exist due to the implementation of the specified interface.
  • COBCH1730 <type-name1> does not have a public implementation of event <event-name> of interface <type-name2>
    The specified event is missing from the class. It must exist due to the implementation of the specified interface.
  • COBCH1731 <type-name1> does not define method <method-name> of abstract class <type-name2>
    A non-abstract class inheriting from an abstract class has no implementation of the specified inherited method.
  • COBCH1732 <object-name> does not define property <property-name> of abstract class <class-name>
  • COBCH1733 <object-name> does not define event <event-name> of abstract class <class-name>
  • COBCH1734 <object-name> has reference to type <type-name> which was not found
  • COBCH1735 For UNSTRING on string objects the DELIMITED phrase must be used
    The unstring statement has been specified without the delimited phrase.
  • COBCH1736 Cannot have both VALUE and KEY phrases
  • COBCH1737 CREATE can only be used on lists, dictionaries, and types with a parameter-less constructor
    The create verb can only be used to create objects which are either defined as lists or dictionaries, or whose type has a constructor without parameters.
  • COBCH1738 ILSMARTLINKAGE class <class-name> has inconsistent definitions
  • COBCH1739 Identifier is not subordinate to the XML GENERATE identifier
  • COBCH1740 Subscripted item invalid in this context
Parent topic: Messages COBCH1701 - COBCH1800


COBCH1721 <type-name> has no visible member <member-name> with no parameters

The specified type has no visible member with the specified name that does not take any parameters.

In the following example, there is no schedStatus method that does not take a parameter:

class-id schedCheck.
method-id main.
  display self::schedStatus
end method.

method-id schedStatus (t as string).
...
end method.
end class.

For more information on the visibility of members, see Access Modifiers.

Parent topic: COBCH1721 - COBCH1740
Related concepts
Access Modifiers


COBCH1722 <type-name> has no visible instance member <member-name> with no parameters

The specified type has no visible instance member with the specified name that does not take any parameters.

In the following example, there is no compatible instance member to satisfy the display statement.

class-id schedStart.
method-id main.
 declare runSched as type schedStart
 display runSched::messageStart
end method.
method-id messageStart static.
 ...
end method.
end class.

For more information on the visibility of members, see Access Modifiers.

Parent topic: COBCH1721 - COBCH1740
Related concepts
Access Modifiers


COBCH1723 <type-name> has no visible static member <member-name> with no parameters

The specified type has no visible static member with the specified name that does not take any parameters.

In the following example, there is no compatible static member to satisfy the display statement.

class-id schedStart.
method-id main.
 display type schedStart::messageStart
end method.
method-id messageStart.
 ...
end method.
end class.

For more information on the visibility of members, see Access Modifiers.

Parent topic: COBCH1721 - COBCH1740
Related concepts
Access Modifiers


COBCH1724 With JVMGEN, static method 'main' with single string array parameter cannot have a returning item

A static main method has been specified with a single string array and a returning item.

For compatibility with Java 1.7, you should either remove the returning item from the method definition, or rename the method.

Parent topic: COBCH1721 - COBCH1740


COBCH1725 class-name has no visible constructor

The specified class has no visible constructor. This message is generated when the specified class is static.

Example:

In the following example, no constructor is defined.

       class-id a.
       method-id main static.
           display new b
       end method.
       end class.
       class-id b static.
       end class.
Parent topic: COBCH1721 - COBCH1740


COBCH1726 ILSMARTLINKAGE class <class-name> has multiple definitions

The ILSMARTLINKAGE directive has caused the generation of more than one class with the same name.

In the following example, compilation would result in two classes named grp1. To fix the error, rename one of the 01 level items.

$set ilsmartlinkage
 program-id a.
 linkage section.
 01 grp1.  *> rename one of these items
    03 nam pic x(20).
 procedure division using grp1.
  ...
 end program.

 program-id b.
 linkage section.
 01 grp1.  *> rename one of these items
    03 num pic 9(9).
 procedure division using grp1.
  ...
 end program.
Parent topic: COBCH1721 - COBCH1740
Related concepts
Exposing COBOL Linkage Data as Managed Types
ILSMARTLINKAGE


COBCH1727 '%1$s' is in the unreferenced assembly '%2$s'.

Resolution:

Parent topic: COBCH1721 - COBCH1740


COBCH1728 <type-name1> does not have public implementation of method <method-name> of interface <type-name2>

The specified method is missing from the class. It must exist due to the implementation of the specified interface.

In the following example, class myScheduler implements interface IAlarm, but does not contain an implementation of setTime. You must add a method setTime for the implementation to be satisfied.

class-id myScheduler implements type IAlarm.
01 alarmTime string property.
01 alarmSwitch type alarmState event.
end class.

delegate-id alarmState.
 ...
end delegate.

interface-id IAlarm.
01 alarmTime string property.
01 alarmSwitch type alarmState event.
method-id setTime.
 ...
end method.
end interface.
Parent topic: COBCH1721 - COBCH1740
Related concepts
Interfaces


COBCH1729 <type-name1> does not have a public implementation of property <property-name> of interface <type-name2>

The specified property is missing from the class. It must exist due to the implementation of the specified interface.

In the following example, class myScheduler implements interface IAlarm, but does not contain an implementation of alarmTime. You must add a property named alarmTime for the implementation to be satisfied.

class-id myScheduler implements type IAlarm.
01 alarmSwitch type alarmState event.
method-id setTime.
 ...
end method.
end class.

delegate-id alarmState.
 ...
end delegate.

interface-id IAlarm.
01 alarmTime string property.
01 alarmSwitch type alarmState event.
method-id setTime.
 ...
end method.
end interface.
Parent topic: COBCH1721 - COBCH1740
Related concepts
Interfaces


COBCH1730 <type-name1> does not have a public implementation of event <event-name> of interface <type-name2>

The specified event is missing from the class. It must exist due to the implementation of the specified interface.

In the following example, class myScheduler implements interface IAlarm, but does not contain an implementation of alarmSwitch. You must add an event named alarmSwitch for the implementation to be satisfied.

class-id myScheduler implements type IAlarm.
01 alarmTime string property.
method-id setTime.
 ...
end method.
end class.

delegate-id alarmState.
 ...
end delegate.

interface-id IAlarm.
01 alarmTime string property.
01 alarmSwitch type alarmState event.
method-id setTime.
 ...
end method.
end interface.
Parent topic: COBCH1721 - COBCH1740
Related concepts
Interfaces


COBCH1731 <type-name1> does not define method <method-name> of abstract class <type-name2>

A non-abstract class inheriting from an abstract class has no implementation of the specified inherited method.

In the following example, class Dog inherits from the abstract class Animal, but does not have the required implementation of the abstract method makeNoise. Add makeNoise to the Dog class for the inheritance to be satisfied.

class-id. Animal abstract.
method-id makeNoise abstract.
end method.
end class.

class-id Dog inherits type Animal.
...
end class.
Parent topic: COBCH1721 - COBCH1740


COBCH1732 <object-name> does not define property <property-name> of abstract class <class-name>

Parent topic: COBCH1721 - COBCH1740


COBCH1733 <object-name> does not define event <event-name> of abstract class <class-name>

Parent topic: COBCH1721 - COBCH1740


COBCH1734 <object-name> has reference to type <type-name> which was not found

Parent topic: COBCH1721 - COBCH1740


COBCH1735 For UNSTRING on string objects the DELIMITED phrase must be used

The unstring statement has been specified without the delimited phrase.
In Managed COBOL, the delimited phrase must be specified when referencing string objects.
01 prodname string value "Micro Focus - Visual COBOL".
01 compname string.
unstring prodname into compname                  *> incorrect
unstring prodname delimited by "-" into compname *> correct
Parent topic: COBCH1721 - COBCH1740
Related concepts
UNSTRING Statement


COBCH1736 Cannot have both VALUE and KEY phrases

Parent topic: COBCH1721 - COBCH1740


COBCH1737 CREATE can only be used on lists, dictionaries, and types with a parameter-less constructor

The create verb can only be used to create objects which are either defined as lists or dictionaries, or whose type has a constructor without parameters.
Parent topic: COBCH1721 - COBCH1740
Related concepts
CREATE Collection Statement


COBCH1738 ILSMARTLINKAGE class <class-name> has inconsistent definitions

Parent topic: COBCH1721 - COBCH1740


COBCH1739 Identifier is not subordinate to the XML GENERATE identifier

Parent topic: COBCH1721 - COBCH1740


COBCH1740 Subscripted item invalid in this context

Parent topic: COBCH1721 - COBCH1740


COBCH1741 - COBCH1760

Lists the Syntax Checking error messages from COBCH1741 through COBCH1760.
  • COBCH1744 Source line <number> truncated after <max> bytes
    The source line indicated by <number> has exceeded the maximum source line length supported by the compiler, and has resulted in non-space bytes being truncated.
  • COBCH1745 Referenced assembly '%1$s' does not have a strong name
  • COBCH1746 Identifier with OCCURS clause in data description is invalid in this context
  • COBCH1747 Only properties and events allowed in interface data division.
    A data item that is not declared as a property or event has been declared in the data division.
  • COBCH1748 Source and target are the same variable
    A move statement specifies the same variable as the source and the target.
  • COBCH1749 keyword not allowed with constructors
    The program contains a keyword specified in a constructor declaration. This is not allowed.
  • COBCH1750 keyword not allowed with iterators
    The program contains the keyword specified in an iterator declaration. This is not allowed.
  • COBCH1751 Operand '%1$s' incompatible with SUPPRESS WHEN %2$s
  • COBCH1752 type-name has no visible member member-name with no parameters, for delegate parameter use METHOD keyword
    No member member-name exists with no parameters.
  • COBCH1753 Best visible method found in '%1$s' is '%2$s', which does not have named parameters
  • COBCH1754 Best visible constructor in '%1$s' is 'new%2$s', which does not have named parameters
  • COBCH1755 type-name cannot be addressed from current namespace namespace-name
    The program contains an internal type in a given namespace (or package name) that is referenced by other types in a different namespace. This is not allowed when compiling for JVM. An internal type can only be referenced by other types in that same namespace.
  • COBCH1756 The chained constructor must not include references to instance or method-local data
    The program contains a chained constructor reference that attempts to pass local variables or instance fields as parameters. This is not allowed.
  • COBCH1757 Reference modified object (string or array) cannot be a receiving item
    The program specifies a reference-modified string object as a receiving item. This is not allowed.
  • COBCH1758 A static method or property cannot have the OVERRIDE clause
    The OVERRIDE clause has been specified on a static method or property.
  • COBCH1759 Static method or property <object-name> should have the REDEFINE clause - assumed
    The REDEFINE clause is missing from the specified object; it must be applied, and is therefore assumed.
  • COBCH1760 REDEFINE on instance method or property is not supported when compiling for JVM
    The REDEFINE keyword has been specified on an instance method or property; this is not supported when being compiled for JVM COBOL.
Parent topic: Messages COBCH1701 - COBCH1800


COBCH1744 Source line <number> truncated after <max> bytes

The source line indicated by <number> has exceeded the maximum source line length supported by the compiler, and has resulted in non-space bytes being truncated.

As of 2014, the value of <max> is always 256. The indicated source line needs to be split into two or more lines, none of which may exceed <max> bytes in length. When a source line is truncated, this frequently causes additional syntax errors unless the truncation happens in a comment line or after the start of an in-line comment.

Note: This error message is usually shown just preceding the line that was truncated.
Parent topic: COBCH1741 - COBCH1760


COBCH1745 Referenced assembly '%1$s' does not have a strong name

Resolution:

Parent topic: COBCH1741 - COBCH1760


COBCH1746 Identifier with OCCURS clause in data description is invalid in this context

Resolution:

Parent topic: COBCH1741 - COBCH1760


COBCH1747 Only properties and events allowed in interface data division.

A data item that is not declared as a property or event has been declared in the data division.

Resolution:

Remove the data item from the data division, or recode it as a property or event; then recompile.

Example:

In the following example, the MyString definition is neither a property nor an event and is therefore not allowed.

       interface-id IMyInterface.
       01 MyString string public.
       end interface.
Parent topic: COBCH1741 - COBCH1760


COBCH1748 Source and target are the same variable

A move statement specifies the same variable as the source and the target.

Resolution:

Recode the statement as required; then recompile.

Example:

In the following example, the move statement specifies the x1 variable as both the source and the target, which is not allowed.

      $set warning(2)
       01 x1 pic x(10).
           move x1 to x1
Parent topic: COBCH1741 - COBCH1760


COBCH1749 keyword not allowed with constructors

The program contains a keyword specified in a constructor declaration. This is not allowed.

Resolution:

Modify the code to correct or otherwise eliminate the offending keyword; then recompile.

Example:

In the following example, the new keyword is not allowed.

       class-id a static.
       method-id new extension.
       end method.
       end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1750 keyword not allowed with iterators

The program contains the keyword specified in an iterator declaration. This is not allowed.

Resolution:

Modify the code to relocate the keyword outside of the iterator declaration or otherwise modify the offending keyword; then recompile.

Example:

In the following example, an illegal keyword is specified in an iterator declaration.

       class-id a abstract.
       iterator-id MyIterator abstract yielding s as string.
       end iterator.
       end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1751 Operand '%1$s' incompatible with SUPPRESS WHEN %2$s

Resolution:

Parent topic: COBCH1741 - COBCH1760


COBCH1752 type-name has no visible member member-name with no parameters, for delegate parameter use METHOD keyword

No member member-name exists with no parameters.

Resolution:

If the intention is to pass this method as a parameter to another method expecting a delegate, then use the keyword METHOD as in the example.

Example:

       class-id a.
       method-id main static.
           invoke M2(M1)             *> Error
           invoke M2(method M1)      *> ok
       end method.

       method-id M1 (s as string) static.
       end method.

       method-id M2 (del as type Del) static.
       end method.
       end class.

       delegate-id Del (s as string)
       end delegate.
Parent topic: COBCH1741 - COBCH1760


COBCH1753 Best visible method found in '%1$s' is '%2$s', which does not have named parameters

Resolution:

Parent topic: COBCH1741 - COBCH1760


COBCH1754 Best visible constructor in '%1$s' is 'new%2$s', which does not have named parameters

Resolution:

Parent topic: COBCH1741 - COBCH1760


COBCH1755 type-name cannot be addressed from current namespace namespace-name

The program contains an internal type in a given namespace (or package name) that is referenced by other types in a different namespace. This is not allowed when compiling for JVM. An internal type can only be referenced by other types in that same namespace.

Resolution:

Modify the code to correct the type and namespace references as required; then recompile.

Example:

The following example shows an internal type, Package 2.B, referenced by a type in a different namespace:

       class-id package1.A.
       method-id main static.
           invoke type package2.B::Meth1
       end method.
       end class.
       class-id package2.B internal.
       method-id Meth1 static.
       end method.
       end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1756 The chained constructor must not include references to instance or method-local data

The program contains a chained constructor reference that attempts to pass local variables or instance fields as parameters. This is not allowed.

Resolution:

Modify the code to eliminate references from the chained contructor to instance or method-local data; then recompile.

Example:

In the following example, the S1 field is declared within the same method as is attempting to pass it as a parameter.

       class-id A.
       01 _name string.
       01 _otherName string.
       method-id new(s as string).
           set _name to s
       end method.
       method-id new
       01 s1 string.
           invoke self::new(s1)
       end method.
       end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1757 Reference modified object (string or array) cannot be a receiving item

The program specifies a reference-modified string object as a receiving item. This is not allowed.

Resolution:

Modify the code such that the reference-modified object is no longer a receiving item; then recompile.

Example:

In the following example, the S1 string receives an array value.

       class-id a.
       method-id main static.
           declare s1 as string = "ABCDEFGHIJ"
           *>move "XYZ" to s1[3:3]
           declare bytearray1 = table of byte (1 2 3 4 5 6 7 8)
           declare bytearray2 = table of byte (11 22 33)
           move bytearray2 to bytearray1[4:3]
           perform varying i as byte through bytearray1
               display i
           end-perform
       end method.
       end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1758 A static method or property cannot have the OVERRIDE clause

The OVERRIDE clause has been specified on a static method or property.

You cannot override a static method or property. You must either remove the OVERRIDE clause, or remove the STATIC keyword from the method or property indicated.

class-id Canine inherits type Animal.
01 aSize string STATIC PROPERTY OVERRIDE.  *> cannot override this property
method-id FeedHabit STATIC OVERRIDE.       *> cannot override this method
...
end method.
end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1759 Static method or property <object-name> should have the REDEFINE clause - assumed

The REDEFINE clause is missing from the specified object; it must be applied, and is therefore assumed.

In the following example, as the Canine class inherits from a class that already contains a property or method of the same name, the REDEFINE clause is the only clause that can be applied to the items in the Canine class, and is therefore assumed.

class-id Animal.
01 aSize string STATIC PROPERTY.
method-id FeedHabit STATIC.
...
end method.
end class.

class-id Canine inherits type Animal.
01 aSize string STATIC PROPERTY.     *> REDEFINE assumed
method-id FeedHabit STATIC.          *> REDEFINE assumed
...
end method.
end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1760 REDEFINE on instance method or property is not supported when compiling for JVM

The REDEFINE keyword has been specified on an instance method or property; this is not supported when being compiled for JVM COBOL.

You must remove the REDEFINE keyword from the required declaration. In the following example, the syntax is not valid when compiled for JVM COBOL.

class-id Animal.
01 animCat string 	PROPERTY.
method-id animFeed.
...
end method.
end class.

class-id Bear inherits type Animal.
01 animCat string PROPERTY REDEFINE.  *> remove REDEFINE keyword
method-id animFeed REDEFINE.          *> remove REDEFINE keyword
...
end method.
end class.
Parent topic: COBCH1741 - COBCH1760


COBCH1761 - COBCH1780

Lists the Syntax Checking error messages from COBCH1761 through COBCH1780.
  • COBCH1761 Feature not yet supported for managed COBOL - ignored
    The syntax is not yet supported for managed COBOL, and has been ignored.
  • COBCH1762 A parameter with open type cannot be passed by reference or output
    An attempt has been made to declare a parameter with open type as either a reference or output parameter; a parameter with open type may only be passed by value.
  • COBCH1763 Field or property <item-name> is more visible than its type <type-name>
    The visibility of the specified field or property is not compatible with the visibility of its declared type.
  • COBCH1764 Method <method-name> is more visible than return type <type-name>
    The visibility of the specified method is not compatible with the visibility of its declared return type.
  • COBCH1765 Method <method-name> is more visible than parameter type <type-name>
    The visibility of the specified method is not compatible with the visibility of the declared type of one of its parameters.
  • COBCH1766 Reference modification of objects is only allowed on strings and single dimensional arrays
    Reference modification has been attempted on an object that is neither a string nor a single dimensional array.
  • COBCH1767 NLS-CURRENCY-LENGTH directive requires NLS directive
    The NLS-CURRENCY-LENGTH Compiler directive has been set without the NLS Compiler directive.
  • COBCH1768 NLS is not supported with JVMGEN or ILGEN
    The NLS Compiler directive has been specified for a managed COBOL program.
  • COBCH1769 Nested Program-id name is not unique
    The source code has two or more nested programs that have the same name.
  • COBCH1770 <type-name> has no visible method <method-name>
    The type specified in the method invocation expression does not contain the named method.
  • COBCH1771 <type-name> has no visible instance method <method-name>
    The type specified in the method invocation expression does not contain an instance method with a compatible signature.
  • COBCH1772 <type-name> has no visible static method <method-name>
    The type specified in the method invocation expression does not contain a static method with a compatible signature.
  • COBCH1773 ORGANIZATION and RECORD DELIMITER clauses have incompatible options; RECORD DELIMITER ignored
    The RECORD DELIMITER clause in the file control entry specifies a record delimiting technique that conflicts with the technique specified in the ORGANIZATION clause of the same file control entry.
  • COBCH1775 The alphabet-name clause referenced by the CODE-SET clause must not specify the literal phrase
    The Special-Names paragraph contains an alphabet-name that is set to a literal value.
  • COBCH1776 PROPERTY ignored for JVM attributes
  • COBCH1777 Methods and constructors ignored for JVM attributes
  • COBCH1778 <type-name> has no visible method <method-name> with specified parameter name(s)
    There is no such method found with the specified parameter name(s).
  • COBCH1779 <type-name> has no visible instance method <method-name> with specified parameter name(s)
    There is no such method found with the specified parameter name(s). The context implies that the required method is an instance method.
  • COBCH1780 <type-name> has no visible static method <method-name> with specified parameter name(s)
    There is no such method found with the specified parameter name(s). The context implies that the required method is a static method.
Parent topic: Messages COBCH1701 - COBCH1800


COBCH1761 Feature not yet supported for managed COBOL - ignored

The syntax is not yet supported for managed COBOL, and has been ignored.

You do not need to remove the code from your program, but the application may not behave as expected if you rely on it.

Parent topic: COBCH1761 - COBCH1780


COBCH1762 A parameter with open type cannot be passed by reference or output

An attempt has been made to declare a parameter with open type as either a reference or output parameter; a parameter with open type may only be passed by value.

An open type is a type based on a generic parameter, or an array of an open type, or a generic type where one of the generic arguments is itself an open type.

In the following example item1 and item2 are passed by reference. To fix the error, they must be passed by value.

$set ilusing(java.lang.Comparable)
 class-id GenericMath.
 method-id main static.
 01 n1 binary-double.
 01 n2 binary-double.

  set n1 to 999
  set n2 to 100
  display n1 space n2
  display self::Min[binary-double](n1 n2)
  display self::Max[binary-double](n1 n2)
  goback.
  end method.

 method-id Min using T static.
 constraints.
  constrain T implements type java.lang.Comparable.
 procedure division using by reference item1 as T item2 as T  *> generic params NOT passed by value
                      returning res as T.
  if item1::compareTo(item2) < 0
    set res to item1
  else
    set res to item2
  end-if
 end method.
Parent topic: COBCH1761 - COBCH1780


COBCH1763 Field or property <item-name> is more visible than its type <type-name>

The visibility of the specified field or property is not compatible with the visibility of its declared type.

If both the item and the type specify access modifiers, they must match, or at least the type be more visible than the item. See Access Modifiers for more information.

In the following example, you must change one of the access modifiers to match the other, or remove the modifiers completely (in which case, PUBLIC visibility is assumed).

class-id Animal.
01 aType type Canine PUBLIC.
class-id Canine PRIVATE.
...
end class.
end class.
Parent topic: COBCH1761 - COBCH1780
Related concepts
Access Modifiers


COBCH1764 Method <method-name> is more visible than return type <type-name>

The visibility of the specified method is not compatible with the visibility of its declared return type.

If both the method and the return type specify access modifiers, they must match, or at least the return type be more visible than the method. See Access Modifiers for more information.

In the following example, you must change one of the access modifiers to match the other, or remove the modifiers completely (in which case, PUBLIC visibility is assumed).

class-id Animal.
method-id giveVax PUBLIC.
procedure division returning ret as Type vaxType.
...
end method.
class-id vaxType PRIVATE.
...
end class.
end class.
Parent topic: COBCH1761 - COBCH1780
Related concepts
Access Modifiers


COBCH1765 Method <method-name> is more visible than parameter type <type-name>

The visibility of the specified method is not compatible with the visibility of the declared type of one of its parameters.

If both the method and the parameter specify access modifiers, they must match, or at least the parameter type be more visible than the method. See Access Modifiers for more information.

In the following example, you must change one of the access modifiers to match the other, or remove the modifiers completely (in which case, PUBLIC visibility is assumed).

class-id Animal.
method-id getAge PUBLIC.
procedure division using by value dYears as type convAge.
end method.
class-id convAge PRIVATE.
...
end class.
end class.
Parent topic: COBCH1761 - COBCH1780
Related concepts
Access Modifiers


COBCH1766 Reference modification of objects is only allowed on strings and single dimensional arrays

Reference modification has been attempted on an object that is neither a string nor a single dimensional array.

The following example shows reference modification attempted on an invalid object type.

...

declare dt = java.util.Date::Now
display dt[1:6]  *> remove content in the parentheses
...
Parent topic: COBCH1761 - COBCH1780


COBCH1767 NLS-CURRENCY-LENGTH directive requires NLS directive

The NLS-CURRENCY-LENGTH Compiler directive has been set without the NLS Compiler directive.

You must also set the NLS Compiler directive to enable this behavior.

Parent topic: COBCH1761 - COBCH1780
Related concepts
NLS
NLS CURRENCY LENGTH


COBCH1768 NLS is not supported with JVMGEN or ILGEN

The NLS Compiler directive has been specified for a managed COBOL program.

The National Locale Support that this Compiler directive enables is not supported in either .NET COBOL or JVM COBOL. Remove the directive from your source code.

Parent topic: COBCH1761 - COBCH1780
Related concepts
NLS
NLS CURRENCY LENGTH


COBCH1769 Nested Program-id name is not unique

The source code has two or more nested programs that have the same name.

Ensure each nested program has a unique program-id name.

Program-id ContainingProgram.
...
Program-id Nested1.
...
End Program Nested1.
Program-id Nested2.   *> rename one of these programs
...
End Program Nested2.
Program-id Nested2.   *> rename one of these programs
...
End Program Nested2.
End Program ContainingProgram.
Parent topic: COBCH1761 - COBCH1780


COBCH1770 <type-name> has no visible method <method-name>

The type specified in the method invocation expression does not contain the named method.

In the following example, there is no method named bonusPay in the bonusPout class. Update the method invocation expression to state the correct method name.

class-id bonusPout.
method-id main STATIC.
declare myDel as type myDelegate
set myDel to method self::bonusPay
end method.

method-id calcBonus (by value sal1 as binary-long by value sal2 as binary-long) returning finalB as binary-long.
...
end method.
method-id calcBonus (by value sal1 as binary-long) returning finalB as binary-long.
...
end method.
method-id calcBonus.
...
end method.
end class.
delegate-id myDelegate.
end delegate.
Parent topic: COBCH1761 - COBCH1780


COBCH1771 <type-name> has no visible instance method <method-name>

The type specified in the method invocation expression does not contain an instance method with a compatible signature.

In the following example, none of the methods in the runBonus object are a compatible match because they are static. The last method would be compatible if it were an instance method; therefore, remove the STATIC keyword from its signature to ensure a match.

class-id bonusPout.
method-id main STATIC.
declare myDel as type myDelegate
declare runBonus as type bonusPout.
set myDel to method runBonus::calcBonus
end method.

method-id calcBonus (by value sal1 as binary-long by value sal2 as binary-long) returning finalB as binary-long STATIC.
...
end method.
method-id calcBonus (by value sal1 as binary-long) returning finalB as binary-long STATIC.
...
end method.
method-id calcBonus STATIC.
...
end method.
end class.
delegate-id myDelegate.
end delegate.
Parent topic: COBCH1761 - COBCH1780


COBCH1772 <type-name> has no visible static method <method-name>

The type specified in the method invocation expression does not contain a static method with a compatible signature.

In the following example, none of the methods in the bonusPout type are a compatible match because they are instance methods. The last method would be compatible if it were a static method; therefore, add the static keyword to its signature to ensure a match.

class-id bonusPout.
method-id main STATIC.
declare myDel as type myDelegate
set myDel to method type bonusPout::calcBonus
end method.

method-id calcBonus (by value sal1 as binary-long by value sal2 as binary-long) returning finalB as binary-long.
...
end method.
method-id calcBonus (by value sal1 as binary-long) returning finalB as binary-long.
...
end method.
method-id calcBonus.
...
end method.
end class.
delegate-id myDelegate.
end delegate.
Parent topic: COBCH1761 - COBCH1780


COBCH1773 ORGANIZATION and RECORD DELIMITER clauses have incompatible options; RECORD DELIMITER ignored

The RECORD DELIMITER clause in the file control entry specifies a record delimiting technique that conflicts with the technique specified in the ORGANIZATION clause of the same file control entry.

When there is a conflict, the RECORD DELIMITER clause is ignored.

To resolve the conflict, take one of the appropriate actions:

  • Remove the RECORD DELIMITER clause.
  • Remove the record delimiting technique (LINE or BINARY options) from the ORGANIZATION clause.
  • Remove the ORGANIZATION clause (thus implying SEQUENTIAL).
  • Make the techniques agree; that is,
    • RECORD DELIMITER IS LINE-SEQUENTIAL and ORGANIZATION IS LINE SEQUENTIAL
    • RECORD DELIMITER IS BINARY-SEQUENTIAL and ORGANIZATION IS BINARY SEQUENTIAL (RECORD DELIMITER IS BINARY-SEQUENTIAL is also compatible with ORGANIZATION IS RECORD SEQUENTIAL)
Parent topic: COBCH1761 - COBCH1780
Related concepts
The RECORD DELIMITER Clause
The File Control Entry


COBCH1775 The alphabet-name clause referenced by the CODE-SET clause must not specify the literal phrase

The Special-Names paragraph contains an alphabet-name that is set to a literal value.

When the alphabet-name clause is used in the CODE-SET clause of the File Control description, it cannot be set to a literal value; you must change the value or remove the CODE-SET clause from the File Control description.

Configuration section.
Special-Names.
ALPHABET my-alpha is 66 67 68    *> you must correct the value
...
FD out-fil CODE-SET is my-alpha  *> or remove from FD
...
Parent topic: COBCH1761 - COBCH1780
Related concepts
The CODE-SET Clause
The Special-Names Paragraph


COBCH1776 PROPERTY ignored for JVM attributes

The ATTRIBUTE-ID syntax is used to define attributes. Such attribute definitions may include properties and methods: these are ignored when compiling for JVM, but are included in the attribute class when compiling for .NET.

       attribute-id MyAttribute.
       01 Prop string property.
       end attribute.
Parent topic: COBCH1761 - COBCH1780


COBCH1777 Methods and constructors ignored for JVM attributes

The ATTRIBUTE-ID syntax is used to define attributes. Such attribute definitions may include properties and methods: these are ignored when compiling for JVM, but are included in the attribute class when compiling for .NET.
       attribute-id MyAttribute.
       method-id AttributeMethod.
       end method.
       end attribute.
Parent topic: COBCH1761 - COBCH1780


COBCH1778 <type-name> has no visible method <method-name> with specified parameter name(s)

There is no such method found with the specified parameter name(s).

In the following example, there is no method with the named parameter param1. Either code a method that contains a named parameter called param1, or in this instance, rename the parameter paramx.

class-id runAlarm.
   method-id sSet.
     invoke self::runSet(parameter param1 = "Alarm Set")
   end method.
   method-id runSet(paramx as string).
      display paramx
   end method.
end class.
Parent topic: COBCH1761 - COBCH1780


COBCH1779 <type-name> has no visible instance method <method-name> with specified parameter name(s)

There is no such method found with the specified parameter name(s). The context implies that the required method is an instance method.

In the following example, there is no instance method with the named parameter param1. Either code an instance method that contains a named parameter called param1, or in this instance, rename the parameter paramx.

class-id runAlarm.
   method-id aSet.
           declare a1 = new runAlarm
     invoke a1::runSet(parameter param1 = "Alarm Set")
   end method.
   method-id runSet(paramx as string).
      display paramx
   end method.
end class.
Parent topic: COBCH1761 - COBCH1780


COBCH1780 <type-name> has no visible static method <method-name> with specified parameter name(s)

There is no such method found with the specified parameter name(s). The context implies that the required method is a static method.

In the following example, there is no static method with the named parameter param1. Either code a static method that contains a named parameter called param1, or in this instance, rename the parameter paramx.

class-id runAlarm.
   method-id sSet.
     invoke type runAlarm::runSet(parameter param1 = "Alarm Set")
   end method.
   method-id runSet(paramx as string) static.
      display paramx
   end method.
end class.
Parent topic: COBCH1761 - COBCH1780


COBCH1781 - COBCH1800

  • COBCH1781 <type-name> has no visible constructor with specified parameter name(s)
    There is no such constructor found with the specified parameter name(s).
  • COBCH1782 <type-name> has no visible method <method-name> for which generic parameter type(s) could be inferred
  • COBCH1783 <type-name> has no visible instance method <method-name> for which generic parameter type(s) could be inferred
  • COBCH1784 <type-name> has no visible static method <method-name> for which generic parameter type(s) could be inferred
  • COBCH1785 For inline signature, parameters must be followed immediately by optional RETURNING or YIELDING
    An inline method signature has been specified incorrectly, or in the wrong order.
  • COBCH1786 Data name contains invalid character(s)
  • COBCH1787 Data-name <name> at line <line-no> in the <description-name> is not declared; implicit definition created
    A forward-referenced data-name was not declared in the source program. The compiler has created an implicit definition for the data item that is compatible with the reference.
  • COBCH1788 Exception: <exception-message>
  • COBCH1789 Matching member in inherited <type-name> is non-virtual
  • COBCH1790 Illegal use of 'void' type
  • COBCH1791 ILOUTPUT name <output-path> does not exist or is not a valid directory
  • COBCH1792 <type-name> has no visible method <method-name> for which generic parameter type(s) conform to constraints
  • COBCH1793 <type-name> has no visible instance method <method-name> for which generic parameter type(s) conform to constraints
  • COBCH1794 <type-name> has no visible static method <method-name> for which generic parameter type(s) conform to constraints
  • COBCH1795 Found non-static 'main' method with string array parameter - cannot be a main program
  • COBCH1796 A get/set property cannot override a get property
  • COBCH1797 A get/set property cannot override a set property
  • COBCH1798 A get property in a non-abstract class cannot override an abstract get/set property
  • COBCH1799 A get property cannot override a set property
  • COBCH1800 A set property in a non-abstract class cannot override an abstract get/set property
Parent topic: Messages COBCH1701 - COBCH1800


COBCH1781 <type-name> has no visible constructor with specified parameter name(s)

There is no such constructor found with the specified parameter name(s).

In the following example, there is no constructor with the named parameter param1. Either code an constructor that contains a named parameter called param1, or in this instance, rename the parameter paramx.

class-id runAlarm
method-id aSet.
  declare a1 as type runAlarm = new runAlarm(parameter param1 = "Alarm Set")
end method.
method-id new (paramx as string).
   display paramx
end method.
end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1782 <type-name> has no visible method <method-name> for which generic parameter type(s) could be inferred

No such method was found for which the generic parameter types could be inferred. It may be necessary to specify the generic parameters explicitly.
      $set sourceformat(variable)
       class-id Main.

       method-id M.
           invoke GenericMethod(1, 1)                 *> This line causes an error
           invoke GenericMethod[binary-long](1, 1)    *> This line does not
       end method.

       method-id GenericMethod using T (p1 as binary-long, p2 as binary-long).
           display p1 space p2
           goback
       end method.

       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1783 <type-name> has no visible instance method <method-name> for which generic parameter type(s) could be inferred

No such method was found for which the generic parameter types could be inferred. It may be necessary to specify the generic parameters explicitly. The context implies that the required method is an instance method.
      $set sourceformat(variable)
       class-id Main.

       method-id M static.
           declare o = new Main
           invoke o::GenericMethod(1, 1)                  *> This line causes an error
           invoke o::GenericMethod[binary-long](1, 1)     *> This line does not
       end method.

       method-id GenericMethod using T (p1 as binary-long, p2 as binary-long).
           display p1 space p2
           goback
       end method.

       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1784 <type-name> has no visible static method <method-name> for which generic parameter type(s) could be inferred

No such method was found for which the generic parameter types could be inferred. It may be necessary to specify the generic parameters explicitly. The context implies that the required method is a static method.
      $set sourceformat(variable)
       class-id Main.

       method-id main() static.
           invoke GenericMethod(1, 1)                  *> This line causes an error
           invoke GenericMethod[binary-long](1, 1)     *> This line does not
       end method.

       method-id GenericMethod using T (p1 as binary-long, p2 as binary-long) static.
           display p1 space p2
           goback
       end method.

       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1785 For inline signature, parameters must be followed immediately by optional RETURNING or YIELDING

An inline method signature has been specified incorrectly, or in the wrong order.

When specifying an inline method signature, any RETURNING or YIELDING phrase must immediately follow the parenthesized parameter specification; for example:

method-id SplitTime (split-1 as decimal, split-2 as decimal)
                                    returning diff as decimal public.
...
end method.
Parent topic: COBCH1781 - COBCH1800


COBCH1786 Data name contains invalid character(s)

Resolution:

Parent topic: COBCH1781 - COBCH1800


COBCH1787 Data-name <name> at line <line-no> in the <description-name> is not declared; implicit definition created

A forward-referenced data-name was not declared in the source program. The compiler has created an implicit definition for the data item that is compatible with the reference.

The implicit definition does not have the external attribute except for the cases when the PADDING CHARACTER clause is associated with an external file or an OCCURS DEPENDING ON clause is associated with an external table.

The forward-referenced data-name may come from one of the following:

  • CRT STATUS clause
  • CURSOR clause
  • FILE STATUS clause
  • RELATIVE KEY phrase
  • PADDING CHARACTER clause
  • LINAGE clause
  • FOOTING, TOP, and BOTTOM phrases of the LINAGE clause
  • RECORD VARYING DEPENDING ON clause
  • VALUE OF CLAUSE
  • OCCURS DEPENDING ON clause

Definitions for the external-file-name data-name in the ASSIGN clause and the data-name in the VALUE OF FILE-ID clause are implicitly created without producing this error.

Parent topic: COBCH1781 - COBCH1800


COBCH1788 Exception: <exception-message>

In the case where an assembly referenced in an ilref directive failed to load, this message records the exception which was the root cause of the load failure. This message may also be used in other contexts to communicate such exception information.
Parent topic: COBCH1781 - COBCH1800


COBCH1789 Matching member in inherited <type-name> is non-virtual

Indicates the specific case where, although an inherited type of the current type does have a public implementation of the method, this method is non-virtual (and therefore is ineligible as a method implementing an interface).

Error COBCH1728 ("type-name1 does not have public implementation of method method-name of interface type-name2") is also produced with this error.

In the following example, this error is returned for System.Windows.Forms.Control:

      $set ilref"System.Windows.Forms"
       class-id MainView
                 inherits type System.Windows.Forms.Form
                 implements type IMainView.

       end class.

       interface-id IMainView public.

       method-id Show.
       end method.

       end interface.
Parent topic: COBCH1781 - COBCH1800
Related reference
COBCH1728 <type-name1> does not have public implementation of method <method-name> of interface <type-name2>


COBCH1790 Illegal use of 'void' type

The type java.lang.void cannot be used as a data type or parameter type, etc. The only context in which these void types are allowed is in a TYPE OF phrase.
       class-id a.
       01 v1 type System.Void.                    *> This line causes an error
       01 t1 object value type of System.Void.    *> This line does not
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1791 ILOUTPUT name <output-path> does not exist or is not a valid directory

An invalid or non-existent directory name has been specified in the ILOUTPUT directive. For example:
      $set iloutput("This directory does not exist")
           display "Hello world"
Parent topic: COBCH1781 - COBCH1800
Related reference
ILOUTPUT


COBCH1792 <type-name> has no visible method <method-name> for which generic parameter type(s) conform to constraints

No such method was found for which the generic parameter types conform to constraints.

In the following example, COBCH1792 ("'type a' has no visible method 'M2' for which generic parameter type(s) conform to constraints") is returned:

       class-id a.
       method-id M1.
           invoke M2("Hello")
       end method.
       method-id M2 using T (param1 as T).
       constraints.
           constrain T is value type.
       end method.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1793 <type-name> has no visible instance method <method-name> for which generic parameter type(s) conform to constraints

No such method was found for which the generic parameter types conform to constraints. The context implies that the required method is an instance method.

In the following example, COBCH1793 ("'type a' has no visible instance method 'M2' for which generic parameter type(s) conform to constraints") is returned:

       class-id a.
       method-id M1.
           declare o = new type a
           invoke o::M2("Hello")
       end method.
       method-id M2 using T (param1 as T).
       constraints.
           constrain T is value type.
       end method.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1794 <type-name> has no visible static method <method-name> for which generic parameter type(s) conform to constraints

No such method was found for which the generic parameter types conform to constraints. The context implies that the required method is a static method.

In the following example, COBCH1794 ("'type a' has no visible static method 'M2' for which generic parameter type(s) conform to constraints") is returned:

       class-id a.
       method-id M1 static.
           invoke type a::M2("Hello")
       end method.
       method-id M2 static using T (param1 as T).
       constraints.
           constrain T is value type.
       end method.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1795 Found non-static 'main' method with string array parameter - cannot be a main program

The program has been compiled as a main program, but contains an instance method called 'main' with a single parameter whose type is an array of strings.
Parent topic: COBCH1781 - COBCH1800


COBCH1796 A get/set property cannot override a get property

A property with both get and set accessors cannot override a get property in an inherited class.

In the following example, this error is returned for PropG1:

       class-id a public abstract.
       property-id PropG1 string abstract.
       getter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property override.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1797 A get/set property cannot override a set property

A property with both get and set accessors cannot override a set property in an inherited class.

In the following example, this error is returned for PropG1:

       class-id a public abstract.
       property-id PropG1 string abstract.
       setter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property override.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1798 A get property in a non-abstract class cannot override an abstract get/set property

A get property in a non-abstract class cannot override an abstract property with both get and set accessors.
Parent topic: COBCH1781 - COBCH1800


COBCH1799 A get property cannot override a set property

A get property cannot override a set property.

In the following example, this error is returned for PropG1:

       class-id a public abstract.
       property-id PropG1 string abstract.
       setter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property no set override.
       end class.
Parent topic: COBCH1781 - COBCH1800


COBCH1800 A set property in a non-abstract class cannot override an abstract get/set property

A set property in a non-abstract class cannot override an abstract property with both get and set accessors.
Parent topic: COBCH1781 - COBCH1800


Messages COBCH1801 - COBCH1900

  • COBCH1801 - COBCH1820
    Lists the Syntax Checking error messages from COBCH1801 through COBCH1820.
  • COBCH1821 - COBCH1840
    Lists the Syntax Checking error messages from COBCH1821 through COBCH1840.
  • COBCH1841 - COBCH1880
    Lists the Syntax Checking error messages from COBCH1841 through COBCH1880.
  • COBCH1881 - COBCH1900
    Lists the Syntax Checking error messages from COBCH1881 through COBCH1900.
Parent topic: Syntax Checking Error Messages


COBCH1801 - COBCH1820

Lists the Syntax Checking error messages from COBCH1801 through COBCH1820.
  • COBCH1801 A set property cannot override a get property
  • COBCH1802 A table initializer expression cannot be a receiving item
  • COBCH1803 USAGE BINARY Length specifier cannot be less than 1 or greater than 16
    A data item declared as USAGE BINARY that contains a length specifier has specified an incorrect value.
  • COBCH1804 A non-BINARY usage should not have a length specifier
    A non-BINARY usage data item has been declared with a length specifier.
  • COBCH1805 A STATIC class cannot have PROTECTED members
    The program contains a static class that includes protected members. This is not allowed.
  • COBCH1806 Feature not supported in selected charset
  • COBCH1807 SET SIZE UP DOWN can only be used for single dimensional tables
    The program contains the syntax SET SIZE OF table-name UP/DOWN BY … that is not within a single-dimensional array. This is not allowed.
  • COBCH1808 SORT operand is not an array
    The program contains a SORT statement that doesn't reference a sort file or an array. This is not allowed.
  • COBCH1809 keyword is not a suitable SORT key type - does not implement IComparable Comparable interface
    When sorting a managed array, if the type of the sort key (or of the array element if no key is explicitly specified) is final, meaning that it cannot be sub-typed, then that type must implement the java.lang.Comparable interface when compiling for JVM. If the type is not final, and if that type does not implement the correct interface, then the sort might cause an exception at run time.
  • COBCH1810 Cannot specify a namespace in nested type names
    The program includes a nested class, the name of which contains a namespace, for example, the period (.) character. This is not allowed.
  • COBCH1811 Cannot specify '+' character in type names
    The program contains a type name that includes the + (plus sign) character in the specification of a nested type. This is not allowed.
  • COBCH1812 Operand is not a condition name (level 88 item)
    The program contains an operand that is not a level 88 item (condition name). For example, if the first operand in a SET statement is a condition name, then all other targets must also be condition names.
  • COBCH1813 class-name does not have public implementation of indexer indexer-name of interface interface-name
    The class indicated is declared as implementing an interface including an indexer, and that indexer is not implemented by the class.
  • COBCH1814 The RETURNING phrase is not allowed with PROPERTY-ID and INDEXER-ID
    A RETURNING phrase has been specified in the method signature of a property or an indexer.
  • COBCH1815 The expression is always of the specified type type-name
    The program contains an INSTANCE OF type-name condition specified for a value type operand, and the operand type and type-name are the same. This is not allowed.
  • COBCH1816 Anonymous method can only be used where a suitable delegate type can be inferred.
    The program contains an anonymous method used in a context other than that which can be mapped onto a suitable delegate type. This is not allowed.
  • COBCH1817 Method group can only be used where a suitable delegate type can be inferred.
    The program contains a method group used where no suitable delegate type can be inferred.
  • COBCH1818 Cannot be used with anonymous method
    Syntax found in an anonymous method is illegal.
  • COBCH1819 This syntax is not available with this version of Java - requires Java 8 or above
  • COBCH1820 A STATIC class cannot inherit from another class or implement an interface
    The program contains a static class, for example, a class that contains no instance members, that inherits from another class or from an implement interface. This is not allowed.
Parent topic: Messages COBCH1801 - COBCH1900


COBCH1801 A set property cannot override a get property

A set property cannot override a get property.

In the following example, this error is returned for PropG1:

       class-id a public abstract.
       property-id PropG1 string abstract.
       getter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property no get override.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1802 A table initializer expression cannot be a receiving item

A TABLE OF expression cannot be used as a receiving item.

In the following example, this error is returned for the MOVE command.

       class-id Class3 public.

       method-id main.
       procedure division.
          move null to table of string("new-string")
       end method.

       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1803 USAGE BINARY Length specifier cannot be less than 1 or greater than 16

A data item declared as USAGE BINARY that contains a length specifier has specified an incorrect value.

Correct the declaration to fall within the permitted bounds.

01 valid-item   pic 9(4) USAGE BINARY(3)
01 invalid-item pic 9(4) USAGE BINARY(17)
Parent topic: COBCH1801 - COBCH1820
Related concepts
The USAGE Clause


COBCH1804 A non-BINARY usage should not have a length specifier

A non-BINARY usage data item has been declared with a length specifier.

You must remove the length specifier from the declaration.

Note: A length specifier, within the valid parameters of 1 to 16 inclusively, may be permitted on a USAGE COMP item if it is being treated as BINARY usage. This is achieved by explicitly setting the COMP"BINARY" directive, or by using a dialect (such as DIALECT"MF" or DIALECT"ACU") that sets it.
Parent topic: COBCH1801 - COBCH1820
Related concepts
The USAGE Clause
COMP


COBCH1805 A STATIC class cannot have PROTECTED members

The program contains a static class that includes protected members. This is not allowed.

Resolution:

Remove the PROTECTED specification or otherwise adjust the code to eliminate the error; then recompile.

Example:

In the following example, the M1 method is protected.

       class-id A static.
       method-id M1 static protected.
       end method.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1806 Feature not supported in selected charset

Resolution:

Parent topic: COBCH1801 - COBCH1820


COBCH1807 SET SIZE UP DOWN can only be used for single dimensional tables

The program contains the syntax SET SIZE OF table-name UP/DOWN BY … that is not within a single-dimensional array. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the SET SIZE OF syntax is used in a two-dimensional array.

           declare myArray as byte occurs 3 5
           set size of myArray up by 4 20
Parent topic: COBCH1801 - COBCH1820


COBCH1808 SORT operand is not an array

The program contains a SORT statement that doesn't reference a sort file or an array. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the SORT statement references a field. It must reference an array.

           declare s1 as string = "Hello"
           sort s1                        *> Error - s1 is not an array
           declare array = table of byte(5 4 3 2 1)
           sort array                     *> ok - will sort the elements of the array
           perform varying i as byte through array
               display i
           end-perform
Parent topic: COBCH1801 - COBCH1820


COBCH1809 keyword is not a suitable SORT key type - does not implement IComparable Comparable interface

When sorting a managed array, if the type of the sort key (or of the array element if no key is explicitly specified) is final, meaning that it cannot be sub-typed, then that type must implement the java.lang.Comparable interface when compiling for JVM. If the type is not final, and if that type does not implement the correct interface, then the sort might cause an exception at run time.

Resolution:

Correct the code; then recompile.

Example:

The following example shows incorrect coding that throws a run-time error, and that throws a compile time error.

           declare array1 as Type A occurs 2
           set array1(1) to new A
           set array1(2) to new A
           sort array1       *> Compiles cleanly but gives error at run time
           declare array2 as Type B occurs 2
           set array2(1) to new B
           set array2(2) to new B
           sort array2       *> Gives compile time error
       end program.
       class-id A.
       end class.
       class-id B final.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1810 Cannot specify a namespace in nested type names

The program includes a nested class, the name of which contains a namespace, for example, the period (.) character. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example, shows a nested class, class-id c.d., that contains a namespace (.) in a nested type name.

       class-id a.b.
       class-id c.d.
       end class.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1811 Cannot specify '+' character in type names

The program contains a type name that includes the + (plus sign) character in the specification of a nested type. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, you must rename the class without using the plus (+) sign.

       class-id a+b.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1812 Operand is not a condition name (level 88 item)

The program contains an operand that is not a level 88 item (condition name). For example, if the first operand in a SET statement is a condition name, then all other targets must also be condition names.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the x1 operand is not defined as an 88-level item. You must redefine it as an 88-level item to use it as is coded in the example's set statement.

       01 x1 pic x.
       88 c1 value "A".

           set c1 x1 to true
Parent topic: COBCH1801 - COBCH1820


COBCH1813 class-name does not have public implementation of indexer indexer-name of interface interface-name

The class indicated is declared as implementing an interface including an indexer, and that indexer is not implemented by the class.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the string indexer is not implemented.

       interface-id IIndexer.
       indexer-id string (i as binary-long).
       getter.
       end indexer.
       end interface.

       class-id a implements type IIndexer.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1814 The RETURNING phrase is not allowed with PROPERTY-ID and INDEXER-ID

A RETURNING phrase has been specified in the method signature of a property or an indexer.

You must remove the RETURNING phrase from the signature; instead use property-value for the return value in the indexer's getter method. For example:

indexer-id string.
   procedure division using by value idx as binary-long,
                      returning return-str as string.    *> remove this phrase
   getter.
   set return-str to "return-value"                      *> and this line
   set property-value to "property-value"
   goback
end indexer.
Parent topic: COBCH1801 - COBCH1820


COBCH1815 The expression is always of the specified type type-name

The program contains an INSTANCE OF type-name condition specified for a value type operand, and the operand type and type-name are the same. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the INSTANCE OF references the dt operand as type string, but it is defined as a type System.DateTime.

       01 dt type System.DateTime.
       01 i1 binary-long.
           if dt instance of string *>type System.DateTime
               display "Pass"
           end-if
Parent topic: COBCH1801 - COBCH1820


COBCH1816 Anonymous method can only be used where a suitable delegate type can be inferred.

The program contains an anonymous method used in a context other than that which can be mapped onto a suitable delegate type. This is not allowed.

Resolution:

Correct the code such that the anonymous method is used, for example, as a source in a MOVE or SET statement where the target is an object of delegate type, or where it is used as an argument to a method that expects a delegate type; then recompile.

Example:

In the following example, the anonymouse display method is not mapped onto a suitable delegate type, but uses a literal instead.

         display
               delegate
                   display "Hello"
               end-delegate
Parent topic: COBCH1801 - COBCH1820


COBCH1817 Method group can only be used where a suitable delegate type can be inferred.

The program contains a method group used where no suitable delegate type can be inferred.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the methods defined in the group do not accommodate the use of a delegate type.

       class-id a.
       method-id main static.
         display method M1
       end method.
       method-id M1 static.
       end method.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1818 Cannot be used with anonymous method

Syntax found in an anonymous method is illegal.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the RETURNING RET STRING syntax is illegal and should be RETURNING RET TO STRING-ARRAY[0].

       class-id a.
       method-id main static.
           declare d as type System.Func[string]
           set d to
                delegate(params string-array as string occurs any returning ret as string
                     *>set ret to string-array[0]
                end-delegate
       end method.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1819 This syntax is not available with this version of Java - requires Java 8 or above

Resolution:

Parent topic: COBCH1801 - COBCH1820


COBCH1820 A STATIC class cannot inherit from another class or implement an interface

The program contains a static class, for example, a class that contains no instance members, that inherits from another class or from an implement interface. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the B class inherits from another class, A.

       class-id a.
       end class.
       class-id b static inherits type a.
       end class.
Parent topic: COBCH1801 - COBCH1820


COBCH1821 - COBCH1840

Lists the Syntax Checking error messages from COBCH1821 through COBCH1840.
  • COBCH1821 An extension method must have at least one parameter
    The program defines an extension method that has no parameters. This is not allowed.
  • COBCH1822 Cannot INVOKE a cast expression
    The program contains a cast expression (AS type-name) that is the object of an INVOKE statement. This is not allowed.
  • COBCH1833 Cannot have instance of STATIC class, or FINAL class without constructor
    The program declares an instance of a static class, or of a final class that has no constructor. This is not allowed.
  • COBCH1834 class-name does not implement indexer indexer-signature of abstract class abstract-class-name
    The program contains a non-abstract class of class-name that is declared as inheriting an abstract class of abstract-class-name that includes an abstract indexer of indexer-signature, and that indexer is not overridden by the class. This is not allowed.
  • COBCH1835 class-name does not have public implementation of get accessor for property property-name of interface interface-name
    The program contains the class specified, which is declared as implementing an interface including a property with a getter, and that getter is not implemented by the class.
  • COBCH1836 class-name does not have public implementation of set accessor for property property-name of interface interface-name
    The program contains the class specified, which is declared as implementing an interface including a property with a setter, and that setter is not implemented by the class.
  • COBCH1837 class-name does not have public implementation of get accessor for indexer indexer-signature of interface interface-name
    The specified class is declared as implementing an interface including an indexer with a getter, and that getter is not implemented by the class.
  • COBCH1838 class-name does not have public implementation of set accessor for indexer indexer-signature of interface interface-name
    The specified class is declared as implementing an interface including an indexer with a setter, and that setter is not implemented by the class.
  • COBCH1839 <type-name> does not implement get accessor for property <property-name> of abstract class <type-name>
  • COBCH1840 <type-name> does not implement set accessor for property <property-name> of abstract class <type-name>
Parent topic: Messages COBCH1801 - COBCH1900


COBCH1821 An extension method must have at least one parameter

The program defines an extension method that has no parameters. This is not allowed.

Resolution:

Add at least one parameter to the extension method, which is required because it is treated as a pseudo-instance variable when the method is called.

Example:

In the following example, The M2 extension method has no parameter but is invoked such that a parameter is required.

       class-id a static.
       method-id M1 extension.
       end method.
       method-id M2 extension (s as string)
       end method.
       method-id main static.
           declare s as string
           invoke s::M2        *> First parameter of M2 treated as pseudo-instance variable
       end method.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1822 Cannot INVOKE a cast expression

The program contains a cast expression (AS type-name) that is the object of an INVOKE statement. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the INVOKE statement contains a cast expression.

       class-id a.
       method-id main static.
           declare s = self::M1        *> ok, returns string containing "Hello"
           display s
           invoke self::M1 as string   *> not allowed
       end method.
       method-id M1 static returning s as string.
           set s to "Hello"
       end method.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1833 Cannot have instance of STATIC class, or FINAL class without constructor

The program declares an instance of a static class, or of a final class that has no constructor. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, static class A has no constructor.

       class-id a static.
       method-id main static.
           declare o as type a = null
       end method.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1834 class-name does not implement indexer indexer-signature of abstract class abstract-class-name

The program contains a non-abstract class of class-name that is declared as inheriting an abstract class of abstract-class-name that includes an abstract indexer of indexer-signature, and that indexer is not overridden by the class. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       class-id a abstract.
       indexer-id string (i as binary-long) abstract.
       getter.
       end indexer.
       end class.

       class-id b inherits type a.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1835 class-name does not have public implementation of get accessor for property property-name of interface interface-name

The program contains the class specified, which is declared as implementing an interface including a property with a getter, and that getter is not implemented by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       interface-id IProperty.
       property-id MyProp string.
       getter.
       setter.
       end property.
       end interface.

       class-id a implements type IProperty.
       property-id MyProp string.
       setter.
       end property.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1836 class-name does not have public implementation of set accessor for property property-name of interface interface-name

The program contains the class specified, which is declared as implementing an interface including a property with a setter, and that setter is not implemented by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       interface-id IProperty.
       property-id MyProp string.
       getter.
       setter.
       end property.
       end interface.

       class-id a implements type IProperty.
       property-id MyProp string.
       getter.
       end property.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1837 class-name does not have public implementation of get accessor for indexer indexer-signature of interface interface-name

The specified class is declared as implementing an interface including an indexer with a getter, and that getter is not implemented by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       interface-id IIndexer.
       indexer-id string (i as binary-long).
       getter.
       setter.
       end indexer.
       end interface.

       class-id a implements type IIndexer.
       indexer-id string (i as binary-long).
       setter.
       end indexer.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1838 class-name does not have public implementation of set accessor for indexer indexer-signature of interface interface-name

The specified class is declared as implementing an interface including an indexer with a setter, and that setter is not implemented by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       interface-id IIndexer.
       indexer-id string (i as binary-long).
       getter.
       setter.
       end indexer.
       end interface.

       class-id a implements type IIndexer.
       indexer-id string (i as binary-long).
       getter.
       end indexer.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1839 <type-name> does not implement get accessor for property <property-name> of abstract class <type-name>

In the following example, COBCH1839 ("'type b' does not implement get accessor for property 'PropG1' abstract class 'type a'") is returned:
       class-id a public abstract.
       property-id PropG1 string abstract.
       getter.
       setter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property with no get override.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1840 <type-name> does not implement set accessor for property <property-name> of abstract class <type-name>

In the following example, COBCH1840 ("'type b' does not implement set accessor for property 'PropG1' abstract class 'type a'") is returned:
       class-id a public abstract.
       property-id PropG1 string abstract.
       getter.
       setter.
       end property.
       end class.

       class-id b inherits type a.
       01 PropG1        string public property with no set override.
       end class.
Parent topic: COBCH1821 - COBCH1840


COBCH1841 - COBCH1880

Lists the Syntax Checking error messages from COBCH1841 through COBCH1880.
  • COBCH1841 class-name does not implement get accessor for indexer indexer-signature of abstract class abstract-class-name
    The non-abstract class specified is declared as inheriting an abstract class including an abstract indexer with a getter, and that getter is not overridden by the class.
  • COBCH1842 class-name does not implement set accessor for indexer indexer-signature of abstract class abstract-class-name
    The non-abstract class specified is declared as inheriting an abstract class including an abstract indexer with a setter, and that setter is not overridden by the class.
  • COBCH1843 keyword not allowed with properties and indexers
    The specified keyword is not allowed when defining a property or indexer.
  • COBCH1844 class-name is inaccessible due to its visibility attributes
    The visibility attributes of the specified class indicate that it cannot be used in the current context.
  • COBCH1845 Illegal combination of CONSTRAIN phrases
    The program contains a CONSTRAIN syntax for a generic parameter, but the CONTRAIN syntax uses an illegal combination of phrases.
  • COBCH1846 name is not a generic parameter for this type or method
    The specified name is not a generic parameter for this type.
  • COBCH1847 Could not find main method method-name
    The specified static method name or procedural COBOL program name was not found.
  • COBCH1848 ILMAIN directive ignored - static main method found with string array parameter
    The program contains a static method named ‘main’ that uses a single parameter that is also a string array. When compiling for JVM, this causes the ILMAIN directive to be ignored.
  • COBCH1849 class-name has interfaces interface-name-1 and interface-name-2, which are different closures of the same generic type
    The program contains a class that implements two different closures of the same generic interface. This is not allowed when compiling for JVM.
  • COBCH1850 Only permitted default value is NULL
    The program specifies a default value other than NULL for a parameter of type object. NULL is the only allowable value.
  • COBCH1851 keyword not allowed with operators
    The program contains the specified keyword when declaring an operator. This is not allowed.
  • COBCH1852 Operators must specify a RETURNING item
    The program declares an operator but does not specify the required RETURNING phrase.
  • COBCH1853 Illegal attribute parameter type
    The program contains an attribute whose property or parameter has an illegal type.
  • COBCH1854 Cannot ACCEPT a floating-point operand with extended ACCEPT/DISPLAY
    The program contains a floating point operand in an ACCEPT statement using extended accept/display syntax. This is not allowed.
  • COBCH1855 SYNC statement cannot specify a value type
    The program contains a SYNC statement that refers to a reference type instead of a value type. This is not allowed.
  • COBCH1856 Generic method cannot include out-of-line PERFORM
    The program contains a generic method that uses an out-of-line PERFORM statement. This is not allowed; however a generic method can use an inline PERFORM statement.
  • COBCH1857 Cannot specify implicit and explicit conversions with same source and target types
    The program contains either an explicit or an implicit conversion operator with the same source and target type. Neither of these are allowed.
  • COBCH1858 Preceding TRY block includes EXIT ITERATOR - CATCH not allowed
    The program contains a TRY block in an iterator that includes an EXIT ITERATOR statement, and that same TRY block also has an associated CATCH. The associated CATCH in this scenario is not allowed; only FINALLY is permitted.
  • COBCH1859 Cannot have EXIT ITERATOR inside CATCH or FINALLY block
    The program contains an iterator that includes a TRY or FINALLY block with an EXIT ITERATOR statement. This is not allowed.
  • COBCH1860 LENGTH OF not supported - use SIZE OF with single dimensional managed arrays, strings or collections
    the LENGTH OF operator is not allowed with object types.
  • COBCH1861 CURRENCY SIGN IS clause is not supported in combination with NATIONAL NUMERIC edited item
  • COBCH1862 NLS-CURRENCY-LENGTH directive is not supported in combination with NATIONAL NUMERIC edited item
  • COBCH1863 ILSMARTLINKAGE cannot be used with complex variable length groups, which do not contain the OCCURS DEPENDING ON item
    The program contains ILSMARTLINKAGE that uses a complex variable-length group (this could be a group containing multiple OCCURS DEPENDING ON items, or in which the OCCURS DEPENDING ITEM is not the last item at its level within the group), and the object of the OCCURS DEPENDING ON is not itself part of the group, and when the program is compiled with the ODOSLIDE directive. This is not allowed.
  • COBCH1864 Directive NORTKEY is for native COBOL only
  • COBCH1865 Cannot use object references in FILE SECTION
    The program declares an object reference in the file section. This is not allowed when compiling for managed code.
  • COBCH1866 Directive directive-name not supported in managed code
    The program has been compiled for managed code and includes the specified directive, which is not supported in managed code.
  • COBCH1867 ROUNDED not allowed with operands of this type
    The program contains a ROUNDED phrase used as a target of an inappropriate type, for example, a target defined as of type decimal.
  • COBCH1868 ALLOCATE RETURNING phrase required
  • COBCH1869 XML PARSE processing procedure may execute STOP RUN, GOBACK or EXIT PROGRAM
    The program contains an XML PARSE statement whose processing procedure includes, STOP RUN, GOBACK or EXIT PROGRAM. These are not allowed.
  • COBCH1870 Cannot use XML PARSE in programs with non-standard PERFORM logic
    The program contains an XML PARSE statement that uses a PERFORMTYPE other than ANSI where a non-standard PERFORM, such as a recursive PERFORM, is present. This is not allowed when compiled to managed code.
  • COBCH1871 OPTIONAL may only be specified in prototype definitions - ignored
  • COBCH1872 AS IF can only be used with a reference type or a nullable type
    The program contains an AS IF operator that targets a type for which no null value is available. This is not allowed. The AS IF operator can only be used to target types for which a suitable null value is available, meaning reference types or nullable value types.
  • COBCH1873 Nested COPY REPLACING not supported
    The program includes a copy file that has been copied in using a COPY REPLACING statement that itself contains another COPY REPLACING. This is not allowed when compiling for an IBM dialect.
  • COBCH1874 Data item or typedef has same name as existing typedef data-name
    The program contains an existing typedef name used as the name of a new data item. This is not allowed.
  • COBCH1875 Feature not yet supported when compiling for JVM - statement ignored
    The program contains a statement that is not supported for JVM code, for example, the IMPLEMENTS phrase on the STATIC header.
  • COBCH1876 Could not find .NET framework library 'mscorlib'
  • COBCH1877 Invalid use of BASED clause
  • COBCH1878 Not allowed with ASYNC-VOID methods
    The program contains an illegal phrase used with an ASYNC-VOID method.
  • COBCH1879 Type or member is marked as obsolete message-text
    A type or member has the Obsolete attribute with the specified message text.
  • COBCH1880 DECLARE cannot follow non-standard ENTRY statement
    The program contains a DECLARE statement used following an entry statement that occurs within a compound statement, for example, following an IF but before the corresponding period (.) or END-IF. This is not allowed.
Parent topic: Messages COBCH1801 - COBCH1900


COBCH1841 class-name does not implement get accessor for indexer indexer-signature of abstract class abstract-class-name

The non-abstract class specified is declared as inheriting an abstract class including an abstract indexer with a getter, and that getter is not overridden by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       class-id a abstract.
       indexer-id string (i as binary-long) abstract.
       getter.
       setter.
       end indexer.
       end class.

       class-id b inherits type a.
       indexer-id string (i as binary-long) override.
       setter.
       end indexer.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1842 class-name does not implement set accessor for indexer indexer-signature of abstract class abstract-class-name

The non-abstract class specified is declared as inheriting an abstract class including an abstract indexer with a setter, and that setter is not overridden by the class.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       class-id a abstract.
       indexer-id string (i as binary-long) abstract.
       getter.
       setter.
       end indexer.
       end class.

       class-id b inherits type a.
       indexer-id string (i as binary-long) override.
       getter.
       end indexer.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1843 keyword not allowed with properties and indexers

The specified keyword is not allowed when defining a property or indexer.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the T keyword is not allowed.

       class-id a.
       property-id Prop string using T.
       getter.
       end property.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1844 class-name is inaccessible due to its visibility attributes

The visibility attributes of the specified class indicate that it cannot be used in the current context.

Resolution:

Correct the code; then recompile.

Example:

In the following example, display new is devined as Outer+Middle, but the class NS.Outer references Inner.

       class-id NS.Prog.
       method-id main(args as string occurs any) static.
       procedure division.
               display new Outer+Middle()
       end method.
       end class.

       class-id NS.Outer.
           class-id Middle private.
               class-id Inner protected.
               end class.
           end class.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1845 Illegal combination of CONSTRAIN phrases

The program contains a CONSTRAIN syntax for a generic parameter, but the CONTRAIN syntax uses an illegal combination of phrases.

Resolution:

Correct the code; then recompile.

Example:

In the following example, IS REFERENCE TYPE combined with IS VALUE TYPE is illegal.

       class-id GenericClass using T.
       constraints.
           constrain T is reference type
                       is value type.
       end class.

       class-id A.
       end class.
       class-id B.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1846 name is not a generic parameter for this type or method

The specified name is not a generic parameter for this type.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the class uses the T paremeter, but references the U parameter.

       class-id GenericClass using T.
       constraints.
           constrain U is reference type.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1847 Could not find main method method-name

The specified static method name or procedural COBOL program name was not found.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

      $set ilmain(Hello)
       class-id Err1847.
       method-id main static.
           display "Hello"
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1848 ILMAIN directive ignored - static main method found with string array parameter

The program contains a static method named ‘main’ that uses a single parameter that is also a string array. When compiling for JVM, this causes the ILMAIN directive to be ignored.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the main static method uses a single parameter that is a string array; therefore, the ILMAIN directive is ignored when compiling for JVM.

      $set ilmain(Hello)
       class-id Err1848.
       method-id Hello static.
           display "In Hello method"
       end method.
       method-id main static (args as string occurs any).
           display "In main method"
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1849 class-name has interfaces interface-name-1 and interface-name-2, which are different closures of the same generic type

The program contains a class that implements two different closures of the same generic interface. This is not allowed when compiling for JVM.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the I1 interface is implemented as both a type string and a type binary-long.

       interface-id I1 using T.
       end interface.
       class-id Class1 implements type I1[string] type I1[binary-long].
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1850 Only permitted default value is NULL

The program specifies a default value other than NULL for a parameter of type object. NULL is the only allowable value.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the default value of the o object is "Hello", which is not legal. The value of the o parameter in this context must be NULL.

       class-id Error1850.
       method-id Meth1(o as object = "Hello")
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1851 keyword not allowed with operators

The program contains the specified keyword when declaring an operator. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example shows a scenario that would cause this error to be thrown.

       class-id A.
       operator-id + redefine (o1 as type A, o2 as type A) returning ret as type A.
       end operator.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1852 Operators must specify a RETURNING item

The program declares an operator but does not specify the required RETURNING phrase.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the returning phrase is missing from the operator declaration.

       class-id A.
       operator-id + (o1 as type A, o2 as type A).
       end operator.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1853 Illegal attribute parameter type

The program contains an attribute whose property or parameter has an illegal type.

Resolution:

Correct the code; then recompile.

Example:

In the following example, MyAttribute references parameter A, which is also defined as a type.

       attribute-id MyAttribute.
       01 Prop1 type A property.
       method-id new (parm1 as type A).
       end method.
       end attribute.

       class-id A attribute MyAttribute(new A).
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1854 Cannot ACCEPT a floating-point operand with extended ACCEPT/DISPLAY

The program contains a floating point operand in an ACCEPT statement using extended accept/display syntax. This is not allowed.

Resolution:

Correct the ACCEPT statement; then recompile.

Example:

In the following example, the ACCEPT statement uses extended syntax with a floating-point operand, F1.

       01 f1 comp-2.
           accept f1 at 0501
Parent topic: COBCH1841 - COBCH1880


COBCH1855 SYNC statement cannot specify a value type

The program contains a SYNC statement that refers to a reference type instead of a value type. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the SYNC O1 statement correctly uses a reference type; however, the SYNC I1 statement incorrectly references a value type.

       class-id a.
       method-id main static.
           declare o1 as object = "Hello"
           declare i1 as binary-long = 3
           sync o1         *> ok, o1 is a reference type
               continue
           end-sync
           sync i1         *> error, i1 is binary-long, which is a value type
               continue
           end-sync
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1856 Generic method cannot include out-of-line PERFORM

The program contains a generic method that uses an out-of-line PERFORM statement. This is not allowed; however a generic method can use an inline PERFORM statement.

Resolution:

Correct the code; then recompile.

Example:

In the following example, PERFORM S1 is an out-of-line PERFORM statement. The following PERFORM statement is inline and therefore legal.

       class-id a.
       method-id GenericMethod using T (param1 as T).
           perform s1         *> Error
           perform 5 times    *> ok
               display param1
           end-perform
           goback
           .
       s1 section.
           display param1
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1857 Cannot specify implicit and explicit conversions with same source and target types

The program contains either an explicit or an implicit conversion operator with the same source and target type. Neither of these are allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, both the IMPLICIT and EXPLICIT operands use STRING as both the source and target type.

       class-id A.
       operator-id implicit (param1 as type A) returning ret as string.
           set ret to param1::ToString
       end operator.
       operator-id explicit (param1 as type A) returning ret as string.
           set ret to param1::ToString
       end operator.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1858 Preceding TRY block includes EXIT ITERATOR - CATCH not allowed

The program contains a TRY block in an iterator that includes an EXIT ITERATOR statement, and that same TRY block also has an associated CATCH. The associated CATCH in this scenario is not allowed; only FINALLY is permitted.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the first TRY block is incorrect and the second is correct.

       class-id A.
       iterator-id MyIterator yielding ret as string.
           try
               set ret to "A"
               exit iterator
               set ret to "B"
               exit iterator
           catch                           *> Error
               display "Caught exception"
           end-try
           try
               set ret to "C"
               exit iterator
               set ret to "D"
               exit iterator
           finally                         *> ok
               display "In finally block"
           end-try
       end iterator.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1859 Cannot have EXIT ITERATOR inside CATCH or FINALLY block

The program contains an iterator that includes a TRY or FINALLY block with an EXIT ITERATOR statement. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

In the following example, both TRY blocks are in error as each one includes EXIT ITERATOR.

       class-id A.
       iterator-id MyIterator yielding ret as string.
           try
               continue
           catch
               display "Caught exception"
               set ret to "A"
               exit iterator                           *> Error
           end-try
           try
               continue
           finally
               display "In finally block"
               set ret to "C"
               exit iterator                           *> Error
           end-try
       end iterator.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1860 LENGTH OF not supported - use SIZE OF with single dimensional managed arrays, strings or collections

the LENGTH OF operator is not allowed with object types.

Resolution:

Correct the code; then recompile. If you want to get the logical size of a managed array, string, or collection object, use SIZE OF.

Example:

The following example shows where SIZE OF should be used in lieu of LENGTH OF, as indicated.

           declare array1 = table of ("AAA" "BB" "C")
           display length of array1                         *> Error
           display size of array1                           *> ok
           declare s1 as string = "Hello"
           display length of s1                             *> Error
           display size of s1                               *> ok
           declare dict1 as dictionary[string, string]
           create dict1
           write dict1 from "X" key "X"
           write dict1 from "Y" key "Y"
           display length of dict1                          *> Error
           display size of dict1                            *> ok
           declare o1 as object
           display length of o1                             *> Error
           display size of o1                               *> Error, not a suitable type
Parent topic: COBCH1841 - COBCH1880


COBCH1861 CURRENCY SIGN IS clause is not supported in combination with NATIONAL NUMERIC edited item

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1862 NLS-CURRENCY-LENGTH directive is not supported in combination with NATIONAL NUMERIC edited item

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1863 ILSMARTLINKAGE cannot be used with complex variable length groups, which do not contain the OCCURS DEPENDING ON item

The program contains ILSMARTLINKAGE that uses a complex variable-length group (this could be a group containing multiple OCCURS DEPENDING ON items, or in which the OCCURS DEPENDING ITEM is not the last item at its level within the group), and the object of the OCCURS DEPENDING ON is not itself part of the group, and when the program is compiled with the ODOSLIDE directive. This is not allowed.

Resolution:

Correct the code and recompile as before, or recompile without the ODOSLIDE directive.

Example:

In the following example, the $SET statement includes ODOSLIDE, which causes this error to be thrown when coupled with the multiple OCCURS DEPENDING ON syntax shown.

      $set ilsmartlinkage odoslide
       working-storage section.
       01 i1 binary-long value 3.
       01 i2 binary-long value 4.
       linkage section.
       01 l1.
           03 x1 pic x(10) occurs 1 to 10 depending on i1.
           03 x2 pic x(10) occurs 1 to 10 depending on i2.
       procedure division using l1.
           display l1
Parent topic: COBCH1841 - COBCH1880


COBCH1864 Directive NORTKEY is for native COBOL only

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1865 Cannot use object references in FILE SECTION

The program declares an object reference in the file section. This is not allowed when compiling for managed code.

Resolution:

Correct the code to remove the object reference declaration from the file section and recompile as before, or recompile for native code instead of managed code.

Example:

The following example shows the R1 object declared in the FD.

       select f1 assign "MyFile".
       fd f1.
       01 r1 object.
Parent topic: COBCH1841 - COBCH1880


COBCH1866 Directive directive-name not supported in managed code

The program has been compiled for managed code and includes the specified directive, which is not supported in managed code.

Resolution:

Recompile the code without the specified directive, or recompile for native code.

Example:

In the following example, the COMP5BYTEORDER directive is set to PORTABLE, which is not supported for managed code.

      $set comp5byteorder(portable)
       01 i1 pic 9(9) comp-5 value 3.
           display i1
Parent topic: COBCH1841 - COBCH1880


COBCH1867 ROUNDED not allowed with operands of this type

The program contains a ROUNDED phrase used as a target of an inappropriate type, for example, a target defined as of type decimal.

Resolution:

Correct the code; then recompile.

Example:

In the following example, the ROUNDED phrase is used for a target defined as a decimal.

       01 d1 decimal.

           compute d1 rounded = 4 / 3
           display d1
Parent topic: COBCH1841 - COBCH1880


COBCH1868 ALLOCATE RETURNING phrase required

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1869 XML PARSE processing procedure may execute STOP RUN, GOBACK or EXIT PROGRAM

The program contains an XML PARSE statement whose processing procedure includes, STOP RUN, GOBACK or EXIT PROGRAM. These are not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example shows illegal use of STOP RUN and GOBACK.

       Identification division.
       Program-id. CHK0201A.
       Data division.
       Working-storage section.
       1 dummy-buffer pic x(100) value spaces.
       1 xml-document.
           2 pic x(22) value '<?xml version="1.0" ?>'.
           2 pic x(39) value '<!--This document is just an example-->'.
           2 pic x(10) value '<sandwich>'.
           2 pic x(36) value '<bread type="baker's best "/>'.
           2 pic x(38) value '<?spread please use real mayonnaise ?>'.
           2 pic x(28) value '<meat>Ham &turkey</meat>'.
           2 pic x(35) value '<filling>Cheese,lettuce,tomato,etc.'.
           2 pic x(10) value '</filling>'.
           2 pic x(34) value '<![CDATA[ We should add a <relish>'.
           2 pic x(21) value 'element in future!]]>'.
           2 pic x(29) value '<listprice>$4.99 </listprice>'.
           2 pic x(25) value '<discount>0.10</discount>'.
           2 pic x(11) value '</sandwich>'.
       1 xml-document-length  pic 999.

       Procedure division.
       mainline section.
           XML PARSE xml-document PROCESSING PROCEDURE xml-handler
           ON EXCEPTION
              display 'XML document error ' XML-CODE
           NOT ON EXCEPTION
              display 'XML document successfully parsed'
           END-XML
           stop run.

       xml-handler section.
           evaluate XML-EVENT
           when 'START-OF-ELEMENT'
                display 'Start elementtag:<' xml-text '>'
           when 'CONTENT-CHARACTERS'
                display 'Content characters:<' xml-text '>'
           when 'END-OF-ELEMENT'
                display 'End elementtag:<' xml-text '>'
           when 'START-OF-DOCUMENT'
                compute xml-document-length = function length(xml-text)
                display 'Start of document:length=' xml-document-length
           when 'END-OF-DOCUMENT'
                display 'End of document.'
           when 'VERSION-INFORMATION'
                display 'Version:<' xml-text '>'
           when 'ENCODING-DECLARATION'
                display 'Encoding:<' xml-text '>'
           when 'STANDALONE-DECLARATION'
                display 'Standalone:<' xml-text '>'
           when 'ATTRIBUTE-NAME'
                display 'Attribute name:<' xml-text '>'
           when 'ATTRIBUTE-CHARACTERS'
                display 'Attribute value characters:<' xml-text '>'
           when 'ATTRIBUTE-CHARACTER'
                display 'Attribute value character:<' xml-text '>'
           when 'START-OF-CDATA-SECTION'
                display 'Start of CData:<' xml-text '>'
           when 'END-OF-CDATA-SECTION'
                display 'End of CData:<' xml-text '>'
           when 'CONTENT-CHARACTER'
                display 'Content character:<' xml-text '>'
           when 'PROCESSING-INSTRUCTION-TARGET'
                display 'PI target:<' xml-text '>'
           when 'PROCESSING-INSTRUCTION-DATA'
                display 'PI data:<' xml-text '>'
           when 'COMMENT'
                display 'Comment:<' xml-text '>'
           when 'EXCEPTION'
               compute xml-document-length = function length (xml-text)
               display 'Exception ' XML-CODE 'at offset'
               xml-document-length
           when other
               display 'Unexpected XML event:' XML-EVENT
           end-evaluate
           goback
           .
Parent topic: COBCH1841 - COBCH1880


COBCH1870 Cannot use XML PARSE in programs with non-standard PERFORM logic

The program contains an XML PARSE statement that uses a PERFORMTYPE other than ANSI where a non-standard PERFORM, such as a recursive PERFORM, is present. This is not allowed when compiled to managed code.

Resolution:

Recompile for managed code, or correct the code and recompile as before.

Example:

The following example shows XML PARSE used with recursive PERFORM logic.

      $set performtype(osvs)
       Identification division.
       Program-id. CHK0201A.
       Data division.
       Working-storage section.
       1 i1 binary-long.
       1 dummy-buffer pic x(100) value spaces.
       1 xml-document.
           2 pic x(22) value '<?xml version="1.0" ?>'.
           2 pic x(39) value '<!--This document is just an example-->'.
           2 pic x(10) value '<sandwich>'.
           2 pic x(36) value '<bread type="baker's best "/>'.
           2 pic x(38) value '<?spread please use real mayonnaise ?>'.
           2 pic x(28) value '<meat>Ham &turkey</meat>'.
           2 pic x(35) value '<filling>Cheese,lettuce,tomato,etc.'.
           2 pic x(10) value '</filling>'.
           2 pic x(34) value '<![CDATA[ We should add a <relish>'.
           2 pic x(21) value 'element in future!]]>'.
           2 pic x(29) value '<listprice>$4.99 </listprice>'.
           2 pic x(25) value '<discount>0.10</discount>'.
           2 pic x(11) value '</sandwich>'.
       1 xml-document-length  pic 999.

       Procedure division.
       mainline section.
           perform s1
           XML PARSE xml-document PROCESSING PROCEDURE xml-handler
           ON EXCEPTION
              display 'XML document error ' XML-CODE
           NOT ON EXCEPTION
              display 'XML document successfully parsed'
           END-XML
           .
       s1 section.
           add 1 to i1
           if i1 < 4
               perform s1

           .
       xml-handler section.
           evaluate XML-EVENT
           when 'START-OF-ELEMENT'
                display 'Start elementtag:<' xml-text '>'
           when 'CONTENT-CHARACTERS'
                display 'Content characters:<' xml-text '>'
           when 'END-OF-ELEMENT'
                display 'End elementtag:<' xml-text '>'
           when 'START-OF-DOCUMENT'
                compute xml-document-length = function length(xml-text)
                display 'Start of document:length=' xml-document-length
           when 'END-OF-DOCUMENT'
                display 'End of document.'
           when 'VERSION-INFORMATION'
                display 'Version:<' xml-text '>'
           when 'ENCODING-DECLARATION'
                display 'Encoding:<' xml-text '>'
           when 'STANDALONE-DECLARATION'
                display 'Standalone:<' xml-text '>'
           when 'ATTRIBUTE-NAME'
                display 'Attribute name:<' xml-text '>'
           when 'ATTRIBUTE-CHARACTERS'
                display 'Attribute value characters:<' xml-text '>'
           when 'ATTRIBUTE-CHARACTER'
                display 'Attribute value character:<' xml-text '>'
           when 'START-OF-CDATA-SECTION'
                display 'Start of CData:<' xml-text '>'
           when 'END-OF-CDATA-SECTION'
                display 'End of CData:<' xml-text '>'
           when 'CONTENT-CHARACTER'
                display 'Content character:<' xml-text '>'
           when 'PROCESSING-INSTRUCTION-TARGET'
                display 'PI target:<' xml-text '>'
           when 'PROCESSING-INSTRUCTION-DATA'
                display 'PI data:<' xml-text '>'
           when 'COMMENT'
                display 'Comment:<' xml-text '>'
           when 'EXCEPTION'
               compute xml-document-length = function length (xml-text)
               display 'Exception ' XML-CODE 'at offset'
               xml-document-length
           when other
               display 'Unexpected XML event:' XML-EVENT
           end-evaluate
           .
Parent topic: COBCH1841 - COBCH1880


COBCH1871 OPTIONAL may only be specified in prototype definitions - ignored

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1872 AS IF can only be used with a reference type or a nullable type

The program contains an AS IF operator that targets a type for which no null value is available. This is not allowed. The AS IF operator can only be used to target types for which a suitable null value is available, meaning reference types or nullable value types.

Resolution:

Correct the code; then recompile.

Example:

The following example shows the correct use of AS and the incorrect use of AS IS.

       class-id A.
       method-id main static.
           declare o1 as object = type System.DateTime::Now
           declare dt1 = o1 as type System.DateTime       *> ok, will unbox o1
           declare dt2 = o1 as if type System.DateTime    *> Error, as there is no null value
           display dt1
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1873 Nested COPY REPLACING not supported

The program includes a copy file that has been copied in using a COPY REPLACING statement that itself contains another COPY REPLACING. This is not allowed when compiling for an IBM dialect.

Resolution:

Correct the code and recompile as before, or recompile for a dialect other than an IBM dialect.

Example:

In the following example, the dialect is set for IBM ENTCOBOL, and the PROCEDURE DIVISION copies in a copy file using COPY REPLACING. In this example, assume that the COPY1 copy file also contains a COPY REPLACING.

      $set dialect(entcobol)
       id division.
       program-id err1873.
       data division.
       working-storage section.
       01 x1 pic x(10).
       procedure division.
           copy "copy1" replacing ==move== by ==mov==.
Parent topic: COBCH1841 - COBCH1880


COBCH1874 Data item or typedef has same name as existing typedef data-name

The program contains an existing typedef name used as the name of a new data item. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example shows the X1 data item defined twice.

       01 x1 binary-long typedef.
       01 x1 pic x(10) value "Hello".
           display x1
Parent topic: COBCH1841 - COBCH1880


COBCH1875 Feature not yet supported when compiling for JVM - statement ignored

The program contains a statement that is not supported for JVM code, for example, the IMPLEMENTS phrase on the STATIC header.

Resolution:

Correct the code; then recompile.

Example:

The following example, shows an IMPLEMENTS phrase on a STATIC header.

       class-id A.
       static implements type IMyInterface.
       end static.
       end class.
       interface-id IMyInterface.
       end interface.
Parent topic: COBCH1841 - COBCH1880


COBCH1876 Could not find .NET framework library 'mscorlib'

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1877 Invalid use of BASED clause

Resolution:

Parent topic: COBCH1841 - COBCH1880


COBCH1878 Not allowed with ASYNC-VOID methods

The program contains an illegal phrase used with an ASYNC-VOID method.

Resolution:

This could be caused by the presence of a YIELDING phrase in the method header for an ASYNC-VOID method. In any case, correct the code; then recompile.

Example:

In the following example, an illegal YIELDING phrase is used in the method header for an ASYNC-VOID method.

       class-id A.
       method-id MethodAsync async-void yielding ret as string.
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1879 Type or member is marked as obsolete message-text

A type or member has the Obsolete attribute with the specified message text.

Resolution:

Correct the code; then recompile.

Example:

The following example shows incorrect use of the Obselete attribute.

       class-id A.
       method-id main static.
           declare o1 = new B
           invoke o1::Meth1
       end method.
       end class.

       class-id B attribute System.Obsolete ("This is an obsolete type causing warning").
       method-id Meth1 attribute System.Obsolete ("This is an obsolete method causing error", true).
           display "In Meth1"
       end method.
       end class.
Parent topic: COBCH1841 - COBCH1880


COBCH1880 DECLARE cannot follow non-standard ENTRY statement

The program contains a DECLARE statement used following an entry statement that occurs within a compound statement, for example, following an IF but before the corresponding period (.) or END-IF. This is not allowed.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       01 i1 binary-long.
           if i1 = 1
       entry "StrangeEntryPoint"
              declare i2 as binary-long = 3
              display i1
           end-if
Parent topic: COBCH1841 - COBCH1880


COBCH1881 - COBCH1900

Lists the Syntax Checking error messages from COBCH1881 through COBCH1900.

  • COBCH1881S With JVMSOURCEBASE, source file must contain only one outer type
  • COBCH1882S Type name does not correspond to source file name and location
  • COBCH1883S Source file is not in location specified by JVMSOURCEBASE directive
  • COBCH1886 Invalid use of ANY LENGTH item
    An item defined with the ANY LENGTH clause has been used incorrectly within the Procedure Division.
  • COBCH1887 The maximum length in RECORD VARYING clause must be greater than minimum length
  • COBCH1888 Typedef is defined differently in another external program
    A typedef definition of the same name, but with a conflicting definition, has been located in another external program.
  • COBCH1889 License failure: <failure-message>
    A valid license could not be obtained during compilation.
  • COBCH1890 Record length of USING file > record length of SD. Truncation may occur at execution time.
    When performing a SORT or MERGE operation, truncation may occur because the record length specified in the input file is greater than the record length specified in the sort file.
  • COBCH1891 Record length of SD > record length of GIVING file. Truncation may occur at execution time.
    When performing a SORT or MERGE operation, truncation may occur because the record length specified in the sort file is greater than the record length specified in the output file.
  • COBCH1892 JSON PARSE INTO identifier contained a pointer, index or USAGE DISPLAY-1 data-item
  • COBCH1894 No type found with namespace namespace-name
    The program declares a namespace using the ILUSING directive, but no type with that namespace has been found within the referenced assemblies. This is a warning only.
  • COBCH1895 Communication Facility not supported
  • COBCH1896 No matching >>IF - ignored
    There was no opening >>IF keyword found for either the >>ELSE or >>END-IF keywords.
  • COBCH1897 No matching >>EVALUATE - ignored
    There was no opening >>EVALUATE keyword found for either the >>WHEN or >>END-EVALUATE keywords.
  • COBCH1898 Incompatible conditional compilation expressions
    An expression within one of the ISO2002 conditional compilation directives contains incorrect logic.
  • COBCH1899 Invalid conditional compilation directive
    Incorrect syntax specified for the IF or EVALUATE directives.
  • COBCH1900 Internal error - Code generation of SCREEN SECTION exceeded 65535 bytes
    An internal limit has been reached for the SCREEN SECTION, due to a very large amount of CONTROL clauses in conjunction with a large number of LINES and attributes.
Parent topic: Messages COBCH1801 - COBCH1900


COBCH1881S With JVMSOURCEBASE, source file must contain only one outer type

Reported when one source file has two types inside. For example:

       class-id com.microfocus.example.MyFirstClass public.
       end class.

       class-id com.microfocus.example.MySecondClass public.
       end class.
Parent topic: COBCH1881 - COBCH1900


COBCH1882S Type name does not correspond to source file name and location

Reported when a source file is located in a path that does not matche the package name parts of the top level type. For example, MyClass.cbl is located at com\microfocus\example\MyClass.cbl and the top level type package is declared as:

       class-id com.microfocus.notmatchingpart.MyClass public.
       end class.
Parent topic: COBCH1881 - COBCH1900


COBCH1883S Source file is not in location specified by JVMSOURCEBASE directive

Reported when a source file is located in some path but the top-level type does not belong to a package. For example, MyClass.cbl is located in com\microfocus\example\MyClass.cbl and the top level type does not belong to any package:

       class-id MyClass public.
       end class.
Parent topic: COBCH1881 - COBCH1900


COBCH1886 Invalid use of ANY LENGTH item

An item defined with the ANY LENGTH clause has been used incorrectly within the Procedure Division.

This occurs when such an item is given addressability via a SET ADDRESS OF statement. Refer to The ANY LENGTH Clause for more information on its usage.

Parent topic: COBCH1881 - COBCH1900
Related reference
The ANY LENGTH Clause


COBCH1887 The maximum length in RECORD VARYING clause must be greater than minimum length

Resolution:

Parent topic: COBCH1881 - COBCH1900


COBCH1888 Typedef is defined differently in another external program

A typedef definition of the same name, but with a conflicting definition, has been located in another external program.

You should ensure that typedef names are unique, or if the same name is used more than once within a compilation unit, the definitions must be identical.

Parent topic: COBCH1881 - COBCH1900


COBCH1889 License failure: <failure-message>

A valid license could not be obtained during compilation.

The message displayed may include <failure-message> depending on the nature of the failure.

Parent topic: COBCH1881 - COBCH1900


COBCH1890 Record length of USING file > record length of SD. Truncation may occur at execution time.

When performing a SORT or MERGE operation, truncation may occur because the record length specified in the input file is greater than the record length specified in the sort file.
You should amend the record length of either the input file or the sort file, as stated in the syntax rules for the SORT and MERGE statements. The SORT statement rule reads:
  • If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
Parent topic: COBCH1881 - COBCH1900
Related reference
The SORT Statement
The MERGE Statement


COBCH1891 Record length of SD > record length of GIVING file. Truncation may occur at execution time.

When performing a SORT or MERGE operation, truncation may occur because the record length specified in the sort file is greater than the record length specified in the output file.
You should amend the record length of either the sort file or the output file, as stated in the syntax rules for the SORT and MERGE statements. The SORT statement rule reads:
  • If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
Parent topic: COBCH1881 - COBCH1900
Related reference
The SORT Statement
The MERGE Statement


COBCH1892 JSON PARSE INTO identifier contained a pointer, index or USAGE DISPLAY-1 data-item

Resolution:

Parent topic: COBCH1881 - COBCH1900


COBCH1894 No type found with namespace namespace-name

The program declares a namespace using the ILUSING directive, but no type with that namespace has been found within the referenced assemblies. This is a warning only.

Resolution:

Optionally correct the code; then recompile.

Example:

The following example shows code that would throw this warning.

      $set ilusing"My.Funny.Namespace" warning(2)
           display "Pass"
Parent topic: COBCH1881 - COBCH1900


COBCH1895 Communication Facility not supported

Resolution:

Parent topic: COBCH1881 - COBCH1900


COBCH1896 No matching >>IF - ignored

There was no opening >>IF keyword found for either the >>ELSE or >>END-IF keywords.

Refer to the ISO2002 Conditional Compilation section, and in particular Appendix A - Examples of Conditional Compilation, for full details on the >>IF syntax.

Parent topic: COBCH1881 - COBCH1900
Related reference
ISO2002 Conditional Compilation
Appendix A - Examples of Conditional Compilation


COBCH1897 No matching >>EVALUATE - ignored

There was no opening >>EVALUATE keyword found for either the >>WHEN or >>END-EVALUATE keywords.

Refer to the ISO2002 Conditional Compilation section, and in particular Appendix A - Examples of Conditional Compilation, for full details on the >>EVALUATE syntax.

Parent topic: COBCH1881 - COBCH1900
Related reference
ISO2002 Conditional Compilation
Appendix A - Examples of Conditional Compilation


COBCH1898 Incompatible conditional compilation expressions

An expression within one of the ISO2002 conditional compilation directives contains incorrect logic.
There are a number of reason that could cause this error, such as a compilation variable being defined as a numeric and then evaluated as an alphanumeric (or vice versa), or a variable within the expression being previously subjected to the OFF phrase. Check and correct your logic within the conditional compilation directive or the definition of the variable.
Parent topic: COBCH1881 - COBCH1900
Related reference
ISO2002 Conditional Compilation
Appendix A - Examples of Conditional Compilation


COBCH1899 Invalid conditional compilation directive

Incorrect syntax specified for the IF or EVALUATE directives.
Refer to the ISO2002 Conditional Compilation section, and in particular Appendix A - Examples of Conditional Compilation, for full details on the >>IF and >>EVALUATE syntax.
Parent topic: COBCH1881 - COBCH1900
Related reference
ISO2002 Conditional Compilation
Appendix A - Examples of Conditional Compilation


COBCH1900 Internal error - Code generation of SCREEN SECTION exceeded 65535 bytes

An internal limit has been reached for the SCREEN SECTION, due to a very large amount of CONTROL clauses in conjunction with a large number of LINES and attributes.

If you reach this limit, you must reduce the number of items in the SCREEN SECTION.

Parent topic: COBCH1881 - COBCH1900


COBCH1901 - COBCH1940

Lists the Syntax Checking error messages from COBCH1901 through COBCH1940.
  • COBCH1921 Compilation constant already defined - use OVERRIDE to assign new value
    A constant used within the ISO2002 conditional compilation mechanism has been defined more than once.
  • COBCH1922 - Length exceeds maximum for conditional compilation literal - truncated to 80 characters
    A literal used in one of the ISO2002 conditional compilation directives has exceeded the maximum length of 80 characters.
  • COBCH1923 Interface interface-name-1 is more visible than inherited interface interface-name-2
    The program declares an interface that inherits from another interface, and this interface is more visible than the inherited one.
  • COBCH1924 The AWAIT expression must reference a Task object
    The AWAIT expression does not reference a Task object. A Task object is an expression of type T, where T is usually either System.Threading.Tasks.Task or its generic form of System.Threading.Tasks.TaskTResult.
  • COBCH1925 The AWAIT expression does not return anything
    The AWAIT expression has been used in a context where a returned value is expected, but the awaited task does not yield a result.
  • COBCH1926 An AWAIT expression cannot be used within a SYNC block
    An AWAIT expression has been used within a SYNC block. This is not allowed.
  • COBCH1927 An AWAIT expression can only be used within an ASYNC method
    The AWAIT expression has been used in a location outside of an ASYNC method.
  • COBCH1928 One or more required parameters have not been specified
    A required parameter is missing from the method invocation.
  • COBCH1929 Feature only supported when compiling for managed code
    When compiling for native code, the code being compiled contains syntax for a feature that is supported only when compiling managed code.
  • COBCH1930 Feature only supported when compiling for JVM
    When compiling for .NET managed code or native code, the code being compiled contains syntax for a feature that is supported only when compiling for JVM managed code.
  • COBCH1931 Syntax can only be used with LIST, DICTIONARY and SET items
    Syntax within the code has been used incorrectly.
  • COBCH1932 Cannot use KEY phrase with sets
    The code contains a KEY phrase that is used with a SET type. This is not allowed.
  • COBCH1935 CONSTRAIN has already been specified for this generic parameter
    The code contains a CONSTRAIN phrase that has been specified more than once for a specific generic parameter. This is not allowed.
  • COBCH1936 parameter-name is not a generic parameter for this method
    The referenced parameter-name is not a generic parameter allowed for the method.
Parent topic: Syntax Checking Error Messages


COBCH1921 Compilation constant already defined - use OVERRIDE to assign new value

A constant used within the ISO2002 conditional compilation mechanism has been defined more than once.

If the constant must be defined more than once, use the OVERRIDE phrase; for example:

...
  >>DEFINE VAR1 as 40
  >>DEFINE VAR1 as 35 OVERRIDE
...
Parent topic: COBCH1901 - COBCH1940
Related reference
The DEFINE Directive


COBCH1922 - Length exceeds maximum for conditional compilation literal - truncated to 80 characters

A literal used in one of the ISO2002 conditional compilation directives has exceeded the maximum length of 80 characters.

The literal will be truncated to the first 80 characters when used within the source code if left as it is.

Parent topic: COBCH1901 - COBCH1940
Related reference
ISO2002 Conditional Compilation


COBCH1923 Interface interface-name-1 is more visible than inherited interface interface-name-2

The program declares an interface that inherits from another interface, and this interface is more visible than the inherited one.

Resolution:

Correct the code; then recompile.

Example:

The following example shows code that would throw this error.

       interface-id IInterface1 internal.
       end interface.
       interface-id IInterface2 public  inherits type IInterface1.
       end interface.
Parent topic: COBCH1901 - COBCH1940


COBCH1924 The AWAIT expression must reference a Task object

The AWAIT expression does not reference a Task object. A Task object is an expression of type T, where T is usually either System.Threading.Tasks.Task or its generic form of System.Threading.Tasks.TaskTResult.

Resolution:

Edit the AWAIT expression to reference a Task object of type T as described above. As an alternative to an expression of type T, you could use any other type that includes a GetAwaiter method with a return type A that implements the System.Runtime.CompilerServices.ICriticalNotifyCompletion interface, and has an IsCompleted property returning a condition-value, and a GetResult method. The return type of this GetResult method should be void if A is a non-generic method, and otherwise the same as the first generic parameter of A.

Example:

The following example shows an AWAIT expression:

       class-id A.
       method-id MethodAsync async yielding ret as string.
           set ret to await "Hello"
       end method.
       end class.
Parent topic: COBCH1901 - COBCH1940


COBCH1925 The AWAIT expression does not return anything

The AWAIT expression has been used in a context where a returned value is expected, but the awaited task does not yield a result.

Resolution:

Correct the code to return a value.

Example:

The following example shows both correct and incorrect code as indicated:

      $set ilusing"System"
      $set ilusing "System.Threading.Tasks"
      $set sourceformat(variable)
       class-id A.
       method-id Main static.
           *> Demo 1
           invoke type Console::WriteLine("Awaiting call to long operation:");
           declare withAwaitAtCallTask = WithAwaitAtCallAsync()
           invoke withAwaitAtCallTask::Wait()
       end method.

       method-id WithAwaitAtCallAsync() private static async.
           invoke await type Task::Delay(1000);                *> Ok, Delay does not yield anything
           declare s as string = await type Task::Delay(1000); *> Error
       end method.
       end class.
Parent topic: COBCH1901 - COBCH1940


COBCH1926 An AWAIT expression cannot be used within a SYNC block

An AWAIT expression has been used within a SYNC block. This is not allowed.

Resolution:

Correct the code to place the AWAIT expression within an ASYNC method.

Example:

The following example shows an AWAIT expression incorrectly used within a SYNC block, and also an AWAIT expression shown correctly within an ASYNC method.

      $set ilusing"System"
      $set ilusing "System.Threading.Tasks"
      $set sourceformat(variable)
       class-id A.
       method-id Main static.
           *> Demo 1
           invoke type Console::WriteLine("Awaiting call to long operation:");
           declare withAwaitAtCallTask = WithAwaitAtCallAsync()
           invoke withAwaitAtCallTask::Wait()
       end method.

       method-id WithAwaitAtCallAsync() private static async.
           declare o as object = "Hello"
           sync on o
               invoke await type Task::Delay(1000);
           end-sync
       end method.
       end class.
Parent topic: COBCH1901 - COBCH1940


COBCH1927 An AWAIT expression can only be used within an ASYNC method

The AWAIT expression has been used in a location outside of an ASYNC method.

Resolution:

Correct the code to place the AWAIT expression within an ASYNC method.

Example:

The following example shows an AWAIT expression used incorrectly outside of an ASYNC method:

      $set ilusing"System"
      $set ilusing "System.Threading.Tasks"
      $set sourceformat(variable)
       class-id A.
       method-id Main static.
               invoke await type Task::Delay(1000);
       end method.
       end class.
Parent topic: COBCH1901 - COBCH1940


COBCH1928 One or more required parameters have not been specified

A required parameter is missing from the method invocation.

Resolution:

Correct the code to add required parameters.

Example:

The following example shows both correct and erroneous code as indicated:

      $set sourceformat(variable)
       class-id ParamBug.
       method-id Main static.
       procedure division using by value args as string occurs any.
           invoke AssertFormat(                  *> Ok, all required parameters specified
               22,                               *> parameter a
               param sf = type CType::Default,
               param p = "Optional object",
               param b = 3)
           invoke AssertFormat(                  *> Error, required parameter b not passed
               22,
               param c = type CType::Default,
               param p = "Optional object")
           goback.
       end method.
       method-id AssertFormat private static.
       procedure division using by value a as binary-long     *> Required parameter
                                         b as binary-long     *> Required parameter
                                         c as type CType = type CType::Default   *> Optional
                                         p as object = null                      *> Optional
                                         sf as type CType = type CType::Default. *> Optional
       end method.
       end class.

       enum-id CType.
       78 #Default.
       end enum.
Parent topic: COBCH1901 - COBCH1940


COBCH1929 Feature only supported when compiling for managed code

When compiling for native code, the code being compiled contains syntax for a feature that is supported only when compiling managed code.

Resolution:

Either remove the offending code or recompile for managed code.

Example:

The following example shows code that produces this error when compiled for native code:

       01 x1 pic x(20).
          move type System.String::Concat("Hello" " everyone") to x1
          display x1
Parent topic: COBCH1901 - COBCH1940


COBCH1930 Feature only supported when compiling for JVM

When compiling for .NET managed code or native code, the code being compiled contains syntax for a feature that is supported only when compiling for JVM managed code.

Resolution:

Either remove the offending code or recompile for JVM managed code.

Example:

The following example shows the DEFAULT phrase used within an ENUM definition, which produces this error when compiled for other than JVM code:

       enum-id MyEnum.
       78 red value 1.
       78 yellow value 2.
       78 green value 3.
       78 black value 255 default.
       end enum.
Parent topic: COBCH1901 - COBCH1940


COBCH1931 Syntax can only be used with LIST, DICTIONARY and SET items

Syntax within the code has been used incorrectly.

Resolution:

Correct the code to properly match syntax with the items referenced.

Example:

In the following example, the CONTAINS syntax references a string; however, CONTAINS cannot be used with a string type.

           declare s as string = "Hello"
           if s contains "e"     *> Error the 'contains' syntax is not applicable to strings
               display "Pass"
           end-if
Parent topic: COBCH1901 - COBCH1940


COBCH1932 Cannot use KEY phrase with sets

The code contains a KEY phrase that is used with a SET type. This is not allowed.

Resolution:

Correct the code to correctly use a SET type with the KEY phrase.

Example:

The following example shows the KEY phrase used incorrectly with the WRITE statement, which is not a SET type:

      $set ilref(System)
           declare set1 as set[string]
           create set1
           write set1 from "Hello" key "Hello"
Parent topic: COBCH1901 - COBCH1940


COBCH1935 CONSTRAIN has already been specified for this generic parameter

The code contains a CONSTRAIN phrase that has been specified more than once for a specific generic parameter. This is not allowed.

Resolution:

Correct the code to specify the CONSTRAIN phrase just once for a given generic parameter. Multiple constraints expressed in the same CONSTRAIN clause are allowed.

Example:

The following example shows the CONSTRAIN phrase used both incorrectly and correctly, as indicated:

       class-id GenericClass1 using T.
       constraints.
           constrain T is reference type
           constrain T inherits type A.   *> Error only one CONSTRAIN per generic parameter
       end class.
       class-id GenericClass2 using T.
       constraints.
           constrain T is reference type  *> ok, a single constrain can express multiple constraints
                       inherits type A.
       end class.

       class-id A.
       end class.
Parent topic: COBCH1901 - COBCH1940


COBCH1936 parameter-name is not a generic parameter for this method

The referenced parameter-name is not a generic parameter allowed for the method.

Resolution:

Correct the code to specify a valid parameter with the method.

Example:

The following example shows invalid use of the U parameter with in the method:

       class-id GenericClass using T.
       method-id M2 using U (parm as U).
       constraints.
           constrain T is reference type.
       end method.
       end class.

       class-id A.
       end class.
       class-id B.
       end class.
Parent topic: COBCH1901 - COBCH1940


Messages COBCH2001 and above

  • COBCH2nnn directive incompatible with flagging dialect
    The directive setting causes behavior different from that of the dialect for which flagging was selected. It is processed as requested.
Parent topic: Syntax Checking Error Messages


COBCH2nnn directive incompatible with flagging dialect

The directive setting causes behavior different from that of the dialect for which flagging was selected. It is processed as requested.

Messages of this type occur if you have set the FLAGCD directive. Each directive that can be reported has a different error number between 2000 and 2199.

Parent topic: Messages COBCH2001 and above


Code Generation Error Messages

Code Generation messages are output when the compiler is producing generated code. Some are environment dependent, so your particular environment might not support them all. When you select an error message number, the text and severity of each message is described, the error or problem that causes the message is described, and advice is given on how to prevent it.

  • Key to Code Generation Error Messages
  • COBOP001 - COBOP080
    Lists all Code Generation error messages, including COBOP001 through COBOP080
Parent topic: COBOL


Key to Code Generation Error Messages

Code generation messages have the following format:

NCG Error at INT Code Address - address
*ErrorCode message

where the variables are:

address | The address in the intermediate code at which the error occurred. Most errors of this type cause the code generator to display the source line in error, provided that the program was compiled with the ANIM directive, and the .idy and source files are available in the current directory. If it does not, you can relate it to your program source by compiling the program with the REF directive and referring to the source listing.
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.
  • The severity of the error.
message | A description of the cause of the error.

The severity returned in ErrorCode can take one of the following values:

F | Fatal. In the unlikely event that one of these errors occurs, contact Technical Support to solve the problem.
R | Recoverable. This ends code generation, as you must correct the error.
C | Cautionary. This tells you either that you have specified an invalid combination of directives or that PERFORM statements cannot be optimized. It does not end code generation or prevent the generated code being executed.
Parent topic: Code Generation Error Messages


COBOP001 - COBOP080

  • COBOP001 Internal error. Contact Technical Support. (Recoverable)
  • COBOP002 Attempted to redefine symbol name (Recoverable)
    The external data item or entry name name clashes with another external symbol of the same name.
  • COBOP003 Ran out of memory during optimization. Generate program using NOOPT. (Recoverable)
    The OPT Compiler directive was specified and the Compiler ran out of memory during the code generation phase.
  • COBOP006 Read failure on input file, not intermediate code or wrong version (Recoverable)
    One of the following has occurred:
  • COBOP009 Ran out of memory during code generation. Split program into smaller units
  • COBOP012 Dictionary or dynamic paging error (Fatal)
    The disk is probably full.
  • COBOP013 Illegal intermediate code (at nnnnnn in seg mm) (Recoverable)
    You are trying to create generated code from intermediate code that has been corrupted.
  • COBOP014 Too many IF levels (Recoverable)
    You have nested IF statements beyond the maximum of 254 levels.
  • COBOP019 Program checked with non-optimal alignment. Optimal alignment is opt-align (Cautionary)
  • COBOP028 Segmented program - GNTANIM ignored (Cautionary)
    You have tried to debug a .gnt file that was generated from a program containing segments.
  • COBOP035 INT code not produced with ANIM (Cautionary)
    You must use the ANIM directive when creating intermediate code.
  • COBPOP37 Generated code module too large (limit = nn bytes)
  • COBOP039 Errors detected during creation of intermediate code (Recoverable)
    You are trying to generate code from intermediate code that was found to contain severe errors when it was submitted to your COBOL system.
  • COBOP040 Bad program-id or entry name (Recoverable)
    The name you have given in the PROGRAM-ID clause or the ENTRY...USING phrase, or as the root of the input file-name, cannot be handled correctly by your system assembler.
  • COBOP054 Parameter type cannot be passed by value (Recoverable)
    Only those COMP-5 items that are 4 bytes or smaller can be passed by value.
  • COBOP055 Opcodes file corrupt or unknown machine type (Recoverable)
    Your $COBDIR/ncg.ops file has become corrupted.
  • COBOP056 Option not implemented: "option name" (Recoverable)
    This language option is not supported on your environment.
  • COBOP065 Read failure on idy file
  • COBOP066 Write failure on .IDY file (Recoverable)
    Either the disk is full or the .idy file produced by the checker has been marked read-only.
  • COBOP068 IDY file not found - SOURCEASM ignored (Cautionary)
  • COBOP069 Source file not found - SOURCEASM ignored (Cautionary)
  • COBOP075 Call-convention not supported (Recoverable)
  • COBOP077 Generated code module too large (limit = limit bytes) (Recoverable)
  • COBOP078 Too many code relocations (limit = limit, actual = limit (Recoverable)
  • COBOP079 Too many data relocations (limit = limit, actual = limit (Recoverable)
  • COBOP080 Too many symbol table entries (limit = limit, actual = limit (Recoverable)
Parent topic: Code Generation Error Messages


COBOP001 Internal error. Contact Technical Support. (Recoverable)

Parent topic: COBOP001 - COBOP080


COBOP002 Attempted to redefine symbol name (Recoverable)

The external data item or entry name name clashes with another external symbol of the same name.

Resolution:

Change one of the names.

Parent topic: COBOP001 - COBOP080


COBOP003 Ran out of memory during optimization. Generate program using NOOPT. (Recoverable)

The OPT Compiler directive was specified and the Compiler ran out of memory during the code generation phase.

Resolution:

Re-compile your program using the NOOPT Compiler directive.

Parent topic: COBOP001 - COBOP080


COBOP006 Read failure on input file, not intermediate code or wrong version (Recoverable)

One of the following has occurred:
  • The input file you have specified is not an intermediate code file.
  • The intermediate code file was produced by a version of your COBOL system that is not compatible with your current version.
  • Your input file is corrupt.

Resolution:

Ensure that you specify an intermediate code file.

Parent topic: COBOP001 - COBOP080


COBOP009 Ran out of memory during code generation. Split program into smaller units

Resolution:

You need to split your program into smaller units.

Parent topic: COBOP001 - COBOP080


COBOP012 Dictionary or dynamic paging error (Fatal)

The disk is probably full.

Resolution:

If the disk is full, make more space available. If you receive this message and your disk is not full, contact Technical Support.

Parent topic: COBOP001 - COBOP080


COBOP013 Illegal intermediate code (at nnnnnn in seg mm) (Recoverable)

You are trying to create generated code from intermediate code that has been corrupted.

nnnnnn is an intermediate code address; mm is an intermediate code segment number.

Resolution:

Resubmit your source code to your COBOL system to try to obtain valid intermediate code.

Parent topic: COBOP001 - COBOP080


COBOP014 Too many IF levels (Recoverable)

You have nested IF statements beyond the maximum of 254 levels.

Resolution:

Change your program so you do not have a nest of more than 254 conditions.

Parent topic: COBOP001 - COBOP080


COBOP019 Program checked with non-optimal alignment. Optimal alignment is opt-align (Cautionary)

Resolution:

No resolution is necessary as this message indicates that the code produced will still perform as expected but is not optimized. If you do not want to receive this message the next time you compile the program, ensure you set the ALIGN directive to its optimal setting.

Parent topic: COBOP001 - COBOP080


COBOP028 Segmented program - GNTANIM ignored (Cautionary)

You have tried to debug a .gnt file that was generated from a program containing segments.

Resolution:

Remove any segments from your original program.

Parent topic: COBOP001 - COBOP080


COBOP035 INT code not produced with ANIM (Cautionary)

You must use the ANIM directive when creating intermediate code.
Parent topic: COBOP001 - COBOP080


COBPOP37 Generated code module too large (limit = nn bytes)

Resolution:

Split your program into smaller bits.

Parent topic: COBOP001 - COBOP080


COBOP039 Errors detected during creation of intermediate code (Recoverable)

You are trying to generate code from intermediate code that was found to contain severe errors when it was submitted to your COBOL system.

Resolution:

Correct all the severe errors in your source code.

Parent topic: COBOP001 - COBOP080


COBOP040 Bad program-id or entry name (Recoverable)

The name you have given in the PROGRAM-ID clause or the ENTRY...USING phrase, or as the root of the input file-name, cannot be handled correctly by your system assembler.

Resolution:

Change the name to comply with your operating system's rules for a function-name.

Parent topic: COBOP001 - COBOP080


COBOP054 Parameter type cannot be passed by value (Recoverable)

Only those COMP-5 items that are 4 bytes or smaller can be passed by value.

Resolution:

Ensure that any COMP-5 items are no larger than 4 bytes.

Parent topic: COBOP001 - COBOP080


COBOP055 Opcodes file corrupt or unknown machine type (Recoverable)

Your $COBDIR/ncg.ops file has become corrupted.

Resolution:

Reinstall your ncg.ops file.

Parent topic: COBOP001 - COBOP080


COBOP056 Option not implemented: "option name" (Recoverable)

This language option is not supported on your environment.
Parent topic: COBOP001 - COBOP080


COBOP065 Read failure on idy file

The reason for this might be one of the following:

  • Insufficient read permissions for the file.
  • The file does not exist.
Parent topic: COBOP001 - COBOP080


COBOP066 Write failure on .IDY file (Recoverable)

Either the disk is full or the .idy file produced by the checker has been marked read-only.

Resolution:

Delete any files you no longer need, or mark the .idy file read/write.

Parent topic: COBOP001 - COBOP080


COBOP068 IDY file not found - SOURCEASM ignored (Cautionary)

Parent topic: COBOP001 - COBOP080


COBOP069 Source file not found - SOURCEASM ignored (Cautionary)

Parent topic: COBOP001 - COBOP080


COBOP075 Call-convention not supported (Recoverable)

Parent topic: COBOP001 - COBOP080


COBOP077 Generated code module too large (limit = limit bytes) (Recoverable)

Parent topic: COBOP001 - COBOP080


COBOP078 Too many code relocations (limit = limit, actual = limit (Recoverable)

Parent topic: COBOP001 - COBOP080


COBOP079 Too many data relocations (limit = limit, actual = limit (Recoverable)

Parent topic: COBOP001 - COBOP080


COBOP080 Too many symbol table entries (limit = limit, actual = limit (Recoverable)

Parent topic: COBOP001 - COBOP080


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


Key to Run-Time System Error Messages

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

Run-time system error messages have the following format:

ErrorCode Description

where the parameters are:

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

There are two types of run-time error:

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

Comments:

If the RTS is unable to write an error message to the screen (for example, when running in a Windows service), then the run-time error message will instead be sent to the Windows Application event log.

Parent topic: Run-time System Error Messages


COBRT001 - COBRT020

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


COBRT001 Insufficient buffer space (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT002 File not open when access attempted (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT003 Serial mode error (Recoverable)

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

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

Resolution:

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

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

Parent topic: COBRT001 - COBRT020


COBRT004 Illegal file name (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT005 Illegal device specification (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT006 Index structure corrupt (Recoverable)

The index of your data file has become corrupt, and although it still may be accessible, you should rebuild it.

Resolution:

Use the Rebuild utility to rebuild the corrupt index. Use the options /d and /e when rebuilding the file; for example:
rebuild filename1,filename2 /d /e
and then rename filename2 to filename1.
Note: Other rebuild parameters may be required, depending on your data file.
Parent topic: COBRT001 - COBRT020


COBRT007 Disk space exhausted (Fatal)

The disk is full.

Resolution:

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

Parent topic: COBRT001 - COBRT020


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

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT009 Directory not found (Recoverable)

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

Resolution:

Create the directory if it does not already exist. If the directory is full, either delete any files that you no longer need or, if your operating system supports this, redirect your program's file operations to alternative storage. Alternatively, specify a different drive or directory for your file operations.

Parent topic: COBRT001 - COBRT020


COBRT010 File name not supplied (Recoverable)

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

Resolution:

Specify the external file-name.

Parent topic: COBRT001 - COBRT020


COBRT011 Process limit reached (Fatal)

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

Resolution:

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

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

Parent topic: COBRT001 - COBRT020


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

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT013 File not found (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT014 Too many files open simultaneously (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT015 Too many indexed files open (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT016 Too many device files open (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT017 Record error: probably zero length (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


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

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


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

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT020 Device or resource busy (Recoverable)

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

Resolution:

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

Parent topic: COBRT001 - COBRT020


COBRT021 - COBRT040

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


COBRT021 File is a directory (Fatal)

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

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

Resolution:

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

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

Parent topic: COBRT021 - COBRT040


COBRT022 Illegal or impossible access mode for OPEN (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT023 Illegal or impossible access mode for CLOSE (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT024 Disk input-output error (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT025 Operating system data error (Fatal)

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

Resolution:

Recode your program.

Parent topic: COBRT021 - COBRT040


COBRT026 Block I-O error (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT027 Device not available (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT028 No space on device (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT029 Attempt to delete open file (Recoverable)

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

Resolution:

Close the file before performing the DELETE FD operation.

Parent topic: COBRT021 - COBRT040


COBRT030 File system is read-only (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT031 Not owner of file (Recoverable)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


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

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

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

Resolution:

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

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

Parent topic: COBRT021 - COBRT040


COBRT033 Physical I-O error (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT034 Incorrect mode or file descriptor (Recoverable)

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

Resolution:

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

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

Parent topic: COBRT021 - COBRT040


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

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT036 File already exists (Recoverable)

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

Resolution:

Recode your program to eliminate this mistake.

Parent topic: COBRT021 - COBRT040


COBRT037 File access denied (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT038 Disk not compatible (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT039 File not compatible (Fatal)

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT040 National Language initialization not set up correctly (Fatal)

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

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

Resolution:

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

Parent topic: COBRT021 - COBRT040


COBRT041 - COBRT060

  • COBRT041 Corrupt index file (Recoverable)
    Your run-time system does not recognize the control information for an indexed file and as the index has been corrupted in some way the data in the file is no longer accessible by your system. This error is recoverable in the sense that it can be trapped but should you receive it, you can do little except to close any open files and stop your program's run.
  • COBRT042 Attempt to write on broken pipe (Recoverable)
    One of the following has occurred:
  • COBRT043 File information missing for indexed file (Fatal)
    The most likely reason for this error is that the names of either the data part or the index part of the file are not consistent with the setting of the IDXNAMETYPE FIle Handler configuration option.
  • COBRT044 Attempt to OPEN an NLS file in a non-NLS program (Fatal)
    The logical file-name is preceded by "%NLS%", but the program which OPENS the file has been compiled without the NLS directive set: the OPEN fails.
  • COBRT045 Attempt to OPEN an NLS file using incompatible language definition (Fatal)
    The NLS control information for a file in your program does not match the same NLS control information in the header of your index file. Alternatively, your index file has become corrupted.
  • COBRT047 Indexed structure overflow (Fatal)
    The structure of your indexed file contains a fault. You have probably tried to put another entry in the index when there is no room for it. This may be because you have reached the maximum number of duplicate keys.
  • COBRT048 Attempt to divide by zero (Fatal)
    You are executing a program that is trying to perform a divide by zero.
  • 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)
  • COBRT096 Invalid use of fork() (Fatal)
    You have called the operating system's fork() API in a process that has called COBOL functionality, or has multiple threads, and then called some COBOL functionality in the child process.
  • COBRT097 Acu library routine is and will remain unimplemented
    The source code contains an ACUCOBOL-GT library routine that is not (or will ever be) supported in Visual COBOL.
  • COBRT098 The library routine is not available in Visual COBOL (<routine-name>) Please contact Micro Focus Customer Care for information
    The source code contains an ACUCOBOL-GT library routine that is not currently supported in Visual COBOL.
  • COBRT099 Illegal operation in SORT/MERGE module (Fatal)
    A SORT or MERGE module has received a RELEASE operation outside the Input procedure, or a RETURN operation either outside the Output procedure, or before the Input procedure has terminated correctly.
  • COBRT100 Invalid file operation (Fatal)
    You have tried a file operation which violates a general rule of COBOL in some way. The most likely cause of this error is that you have tried a rewrite on a sequential file opened I-O, or on a relative file with access mode sequential also opened I-O, without preceding it with a successful read NEXT.
Parent topic: Run-time System Error Messages


COBRT081 Key already exists in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

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

Parent topic: COBRT081 - COBRT100


COBRT082 CALL convention not supported (Fatal)

The CALL convention you have specified is not supported.

Resolution:

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

Parent topic: COBRT081 - COBRT100


COBRT086 Remote file system failure (Fatal)

The network connection to a remote file system has been lost. Please check you connectivity to the remote system.

Parent topic: COBRT081 - COBRT100


COBRT096 Invalid use of fork() (Fatal)

You have called the operating system's fork() API in a process that has called COBOL functionality, or has multiple threads, and then called some COBOL functionality in the child process.

If a process has used COBOL functionality, it can only safely call fork() if the child then safely calls one of the exec() set of APIs. If an error occurs in the child, it should call _exit(), not exit().

When the fork() API is called, the operating system only creates one thread in the child process. If the parent had multiple threads at the time of the fork(), thread synchronisation objects, such as mutexes, may have been locked in another thread, which could lead to deadlocks in the child if the child used those thread synchronisation objects.

The child process can only call COBOL functionality if all of the following are true:
  • The parent has a single thread when the fork() API is called.
  • The parent process does not call any COBOL functionality, either before or after the fork().
  • The child process calls cobinit().
Parent topic: COBRT081 - COBRT100


COBRT097 Acu library routine is and will remain unimplemented

The source code contains an ACUCOBOL-GT library routine that is not (or will ever be) supported in Visual COBOL.

Remove the call from your source code to avoid the error.

Refer to ACUCOBOL-GT Library Routines for a list of supported library routines, or browse the Library Routines section of the documentation to see if there is a Micro Focus equivalent routine that you can use instead.

Parent topic: COBRT081 - COBRT100


COBRT098 The library routine is not available in Visual COBOL (<routine-name>) Please contact Micro Focus Customer Care for information

The source code contains an ACUCOBOL-GT library routine that is not currently supported in Visual COBOL.

Remove the call from your source code to avoid the error.

It may be supported in the future, and so you should contact Customer Care to register your need for it, especially if you cannot code around the issue.

Refer to ACUCOBOL-GT Library Routines for a list of supported library routines, or browse the Library Routines section of the documentation to see if there is a Micro Focus equivalent routine that you can use instead.

Parent topic: COBRT081 - COBRT100


COBRT099 Illegal operation in SORT/MERGE module (Fatal)

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

Resolution:

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

Parent topic: COBRT081 - COBRT100


COBRT100 Invalid file operation (Fatal)

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

Resolution:

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

Parent topic: COBRT081 - COBRT100


COBRT101 - COBRT120

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


COBRT101 Illegal operation on an indexed file (Fatal)

This is the result of an internal system error.

Resolution:

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

Parent topic: COBRT101 - COBRT120


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

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

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT103 Parameter cannot be passed BY VALUE (Fatal)

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:

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

Parent topic: COBRT101 - COBRT120


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

The version numbers for these components do not match.

Resolution:

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

Parent topic: COBRT101 - COBRT120


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

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

Resolution:

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

Parent topic: COBRT101 - COBRT120


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

Memory access violation has been detected by your operating system.

One possible cause is when an attempt has been made to access the record area, but it has not yet been allocated because a file is not yet in the OPEN state; see the HOSTFD directive for more details.

Parent topic: COBRT101 - COBRT120
Related concepts
HOSTFD


COBRT115 Unexpected signal (Fatal)

A signal the run-time system was not expecting has been caught.
Parent topic: COBRT101 - COBRT120


COBRT116 Cannot allocate memory (Fatal)

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

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT117 Bad collating sequence (Fatal)

This is an internal system error.

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT118 Symbol not found (Fatal)

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


COBRT119 Symbol redefined (Fatal)

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

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

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

Resolution:

You can recode your application to remove the naming duplication.

Parent topic: COBRT101 - COBRT120


COBRT120 Symbol string table of zero size (Fatal)

You probably have a malformed object file.

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT121 - COBRT140

  • COBRT121 Symbol is not in TEXT section (Fatal)
    You have tried to call a subprogram that is not an executable program.
  • COBRT122 Coblongjmp() called below level of cobsavenv() (Fatal)
    You might have returned control to a higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called. Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM hierarchy as cobsavenv was.
  • COBRT123 Unknown relocation type (Fatal)
    You are using incompatible versions of the object file and the COBOL run-time library.
  • COBRT124 Communication failure during I/O request to the central file handler
  • COBRT125 All locks/ current transactions canceled due to exceeding time limit
  • COBRT126 Record size exceeds system limit (Fatal)
    One of the following has occurred:
  • COBRT127 coblongjmp() called from a different thread to cobsetjmp() (Fatal)
    You have called coblongjmp() in a different thread from the corresponding call to cobsetjmp(). coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().
  • 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.
  • 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


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


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 (Fatal)
    A subscript which you have used in your program is out of the defined range, that is, it is either less than one or it is greater than the number of occurrences of the item.
  • COBRT154 PERFORM nested too deeply (Fatal)
    This error usually results if you have used GO TO to jump out of the range of a PERFORM rather than to jump to an EXIT statement at the end of its range.
  • COBRT155 Illegal command line (Fatal)
    The run-time system does not recognize as valid the command line format you have specified.
  • COBRT156 Too many parentheses in compute statement (Fatal)
    You have coded a COMPUTE statement which is too complex for your system to handle successfully.
  • COBRT157 Not enough program memory: object file too large to load (Recoverable)
    Either your program is too large for the available memory space, or the stack is full.
  • COBRT158 Attempt to REWRITE to a line-sequential file (Recoverable)
    You have used the REWRITE statement in conjunction with a file whose organization is line sequential. The REWRITE statement cannot be used with line sequential files.
  • COBRT159 Malformed line-sequential file (Recoverable)
    A line-sequential file which you are trying to access is corrupt in some way.
  • COBRT160 Overlay loading error (Recoverable)
    An error has occurred while trying to load the intermediate code for an independent segment. The segment is either missing or corrupted in some way.
Parent topic: Run-time System Error Messages


COBRT141 File already open - cannot be opened (Recoverable)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT142 File not open - cannot be closed (Recoverable)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT144 Boundary violation (Recoverable)

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

Resolution:

Recode your program.

Parent topic: COBRT141 - COBRT160


COBRT146 No current record defined for sequential read (Recoverable)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT151 Random read on sequential file (Recoverable)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT153 Subscript out of range (Fatal)

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

Resolution:

You should recode your program.

Parent topic: COBRT141 - COBRT160


COBRT154 PERFORM nested too deeply (Fatal)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT155 Illegal command line (Fatal)

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

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

Alternatively, you have set an invalid COBSW value.

Resolution:

Rerun your application with a valid command line.

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

Reset COBSW to a valid value.

Parent topic: COBRT141 - COBRT160


COBRT156 Too many parentheses in compute statement (Fatal)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


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

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT159 Malformed line-sequential file (Recoverable)

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

Resolution:

Rerun your program using the backup copy of that file.

Parent topic: COBRT141 - COBRT160


COBRT160 Overlay loading error (Recoverable)

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

Resolution:

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

Parent topic: COBRT141 - COBRT160


COBRT161 - COBRT180

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


COBRT161 Illegal intermediate code (Fatal)

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

Resolution:

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

or:

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

Parent topic: COBRT161 - COBRT180


COBRT162 Arithmetic overflow or underflow (Fatal)

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

Resolution:

You should recode your program to avoid this illegal operation.

Parent topic: COBRT161 - COBRT180


COBRT163 Illegal character in numeric field (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT164 Run-Time subprogram not found (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT165 Version number incompatibility (Fatal)

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


COBRT166 Recursive COBOL CALL is illegal (Fatal)

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

Resolution:

You should recode your program.

Parent topic: COBRT161 - COBRT180


COBRT167 Too many USING items (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT168 Stack overflow (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT169 Illegal configuration information (Fatal)

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

Resolution:

Check that Adis is configured correctly.

Parent topic: COBRT161 - COBRT180


COBRT170 System program not found (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT171 Japanese operations illegal with this RTS (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


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

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

Resolution:

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

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

Parent topic: COBRT161 - COBRT180


COBRT174 Imported file not found (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


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

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

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

Resolution:

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

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

Parent topic: COBRT161 - COBRT180


COBRT176 Illegal intersegment reference (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT177 Attempt to cancel program failed (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


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

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT180 End-of-file marker error (Fatal)

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

Resolution:

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

Parent topic: COBRT161 - COBRT180


COBRT181 - COBRT200

  • COBRT181 Invalid parameter error (Fatal)
    A parameter 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.
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
Related concepts
HOSTFD


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. Perhaps two logins on the same UNIX system are trying to cross-session debug the same program file.
  • COBRT236 Debugged program has terminated unexpectedly (Fatal)
    A program you are debugging has terminated without following the standard run-time system shut-down process. The termination was probably either initiated by the user or caused by a severe run-time error.
  • COBRT237 Unable to initialize debugged process (Fatal)
    The Debugger has encountered system limits in starting your program. The debugged program cannot start because of either insufficient memoryor too many processes running on the UNIX system .
  • COBRT238 STOP RUN encountered during GNT animation (Informational)
    The Debugger has encountered a STOP RUN statement while debugging your .gnt code program.
  • COBRT239 Shared run-time system initialization failure (Informational)
    You are calling a COBOL module from a non-COBOL program, and have not initialized the shared run-time system.
  • COBRT240 Object reference not valid (Fatal)
    You have tried to use an object reference that contains an incorrect or non-existent object handle.
Parent topic: Run-time System Error Messages


COBRT221 Internal sort error (Fatal)

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT222 Merge files out of sequence (Fatal)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT223 NLS language expansion error (Fatal)

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

Resolution:

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

SORTNLSEXPAND calculates the output buffer given the input buffer.

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

The default values for both is 6.

Parent topic: COBRT221 - COBRT240


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. Perhaps two logins on the same UNIX system are trying to cross-session debug the same program file.

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT236 Debugged program has terminated unexpectedly (Fatal)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT237 Unable to initialize debugged process (Fatal)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT238 STOP RUN encountered during GNT animation (Informational)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT239 Shared run-time system initialization failure (Informational)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT240 Object reference not valid (Fatal)

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

Resolution:

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

Parent topic: COBRT221 - COBRT240


COBRT241 - COBRT260

  • COBRT241 Cannot instantiate an abstract class (Fatal)
    You have tried to create an instance of a class that has been declared ABSTRACT. Such classes cannot be instantiated.
  • COBRT242 Could not resolve DoesNotUnderstand message (Fatal)
    The run-time system could not resolve the DoesNotUnderstand message. This is usually because you have defined a class in such a way that this method cannot be found.
  • COBRT243 Class could not be loaded <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.
  • 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


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


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


COBOL Preprocessor Error Messages

Note:

The COBOL Preprocessor is supported for native COBOL only.

Click on a number below for a description of the error message along with causes of the error and action you can take.

  • COBCP001 Undefined internal error - contact Technical Support
    An internal processing error occurred.
  • COBCP101 Illegal command line
    One or more directive was rejected.
  • COBCP102 Compiler level set to 1; some features disabled
  • COBCP103 Open fail: filename
    CP was unable to find the source file.
  • COBCP104 Open fail: filename
    CP was unable to create a trace file.
  • COBCP105 Call to stacked preprocessor name failed
    The preprocessor specified using the CP directive PREPROCESS could not be found.
  • COBCP106 Stacked preprocessor returned an error
    The stacked preprocessor failed to initialise correctly
  • COBCP107 Unable to open a heap
    An internal error prevented a heap from being opened.
  • COBCP200 Internal stack full - contact your support representative
    An internal processing error occurred.
  • COBCP201 File error - contact Technical Support
    An internal processing error occurred.
  • COBCP202 Copybook filename not found
    A COPY statement referenced a file that could not be located.
  • COBCP203 Nested REPLACING is not allowed
    A COPY REPLACING statement was found while another was still being processed.
  • COBCP204 Statement begins in wrong area of source
    The statement starts either in area A when it should have started in area B, or in area B when it should have started in area A.
  • COBCP205 HTML splitter error err-code
    An internal processing error occurred on an EXEC HTML statement.
  • COBCP206 Bad format of COPY statement - COPY ignored
    A COPY statement was incorrectly constructed, for example, not followed by a period.
  • COBCP207 REPLACE results will not be sent to any other preprocessors
  • COBCP207 REPLACE results will not be sent to any other preprocessors
Parent topic: COBOL
Parent topic: Integrated Preprocessor Interface


COBCP001 Undefined internal error - contact Technical Support

An internal processing error occurred.
Note:

The Integrated Preprocessor is supported for native COBOL only.

Resolution:

Inform Technical Support.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP101 Illegal command line

One or more directive was rejected.

Resolution:

If explicitly invoking CP, correct the command line and resubmit. If CP is invoked by another preprocessor, inform the appropriate vendor.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP102 Compiler level set to 1; some features disabled

Parent topic: COBOL Preprocessor Error Messages


COBCP103 Open fail: filename

CP was unable to find the source file.

Resolution:

Correct the filename and resubmit the command.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP104 Open fail: filename

CP was unable to create a trace file.

Resolution:

Ensure that the file is not already in use; there is sufficient disk space, the drive is not write protected.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP105 Call to stacked preprocessor name failed

The preprocessor specified using the CP directive PREPROCESS could not be found.

Resolution:

Ensure that the preprocessor exists and can be invoked. If the name is incorrect then either correct the command line if CP was explicitly invoked or see the appropriate product documentation if CP was invoked by another preprocessor.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP106 Stacked preprocessor returned an error

The stacked preprocessor failed to initialise correctly

Resolution:

For CP, none. Fix the error reported by the stacked preprocessor.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP107 Unable to open a heap

An internal error prevented a heap from being opened.

Resolution:

Inform Technical Support.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP200 Internal stack full - contact your support representative

An internal processing error occurred.

Resolution:

Inform Technical Support.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP201 File error - contact Technical Support

An internal processing error occurred.

Resolution:

Inform technical support.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP202 Copybook filename not found

A COPY statement referenced a file that could not be located.
Note:

The Integrated Preprocessor is supported for native COBOL only.

Resolution:

Correct the program source and resubmit.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP203 Nested REPLACING is not allowed

A COPY REPLACING statement was found while another was still being processed.
Note:

The Integrated Preprocessor is supported for native COBOL only.

Resolution:

Correct the program source and resubmit.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP204 Statement begins in wrong area of source

The statement starts either in area A when it should have started in area B, or in area B when it should have started in area A.
Note:

The Integrated Preprocessor is supported for native COBOL only.

Resolution:

Recode the statement to be in the correct area of source.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP205 HTML splitter error err-code

An internal processing error occurred on an EXEC HTML statement.

Resolution:

Inform Technical Support, specifying err-code.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP206 Bad format of COPY statement - COPY ignored

A COPY statement was incorrectly constructed, for example, not followed by a period.

Resolution:

Correct the program source and resubmit.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


COBCP207 REPLACE results will not be sent to any other preprocessors

Informational message. Contact Micro Focus SupportLine if there are other preprocessors in the stack and you encounter any subsequent issues.

Parent topic: COBOL Preprocessor Error Messages
Parent topic: COBOL Preprocessor Error Messages


Explanation of Error Codes

The ErrorCode portion of an error message is made up as follows:

  • subproduct - three characters indicating the subproduct that found the error. Possible values for subproduct are:
    COB | COBOL Compiler
    IDE | Integrated Development Environment
    SQL | SQL preprocessor
  • function - two characters indicating the function that subproduct was performing when the error was found. function can be one of the following:
    AN | Debugging
    CH | Syntax checking
    CM | Compiling
    CP | Command processing
    DM | Dialog Manager
    EF | File handling
    ID | Interface handling
    IS | Installation
    LK | Linking
    OP | Optimization
    PR | Integrated preprocessor
    RT | Run-time emulation
    SQ | SQL pre-processing
    ST | Sorting
    YS | Internal system errors
    UT | Miscellaneous utility operations
  • message-no - the number of the error.
  • sev - one character indicating the severity of the error. This varies depending on the type of error.
Parent topic: COBOL


Data Related

Look in the sections below to find the error messages produced by the area of the product you are working with.

  • Data File Converter Error Messages
Parent topic: Error Messages
Related information
Database Connectors Error Messages
DB2 ECM Error Messages
File Status Codes
Extended File Status Codes
OpenESQL Preprocessor Error Messages
Rebuild Error, Information and Warning Messages
RM/COBOL File Status Codes
XML File Status Codes


Data File Converter Error Messages

For numbers above 500, subtract 500 and then look for that number in the Run-time System Error Messages topic.

  • DFC1 - DFC11
    Lists the Data File Converter error messages from DFC1 through DFC11.
  • DFC101 - DFC139
    Lists the Data File Converter error messages from DFC101 through DFC139.
  • DFC143 - DFC169
    Lists the Data File Converter error messages from DFC143 through DFC169.
  • DFC173 - DFC188
    Lists the Data File Converter error messages from DFC173 through DFC188.
  • DFC190 - DFC196
    Lists the Data File Converter error messages from DFC190 through DFC196.
  • DFC451 - DFC469
    Lists the Data File Converter error messages from DFC451 through DFC469.
  • DFC470 - DFC491
    Lists the Data File Converter error messages from DFC470 through DFC491.
Parent topic: Data Related


DFC1 - DFC11

  • DFC1 Error reading structure
    CONV was unable to correctly read the structure file.
  • DFC2 Error selecting structure
    CONV was unable to correctly select a structure for the current record.
  • DFC5 Error writing structure
    An error occurred when writing the adjusted structure for the current record.
  • DFC7 Error – no structure found on heap
    The structure file specified in the conversion details is empty.
  • DFC10 Error -- not enough memory
    Not enough free memory was available to continue the conversion.
  • DFC11 Error checking conditions
    An error occurred when testing the conditions on the current record.
Parent topic: Data File Converter Error Messages


DFC1 Error reading structure

CONV was unable to correctly read the structure file.

Resolution:

Ensure that the structure file is valid or that enough free memory is available.

Parent topic: DFC1 - DFC11


DFC2 Error selecting structure

CONV was unable to correctly select a structure for the current record.

Resolution:

Ensure that you correctly defined the structure file and that it contains a default structure.

Parent topic: DFC1 - DFC11


DFC5 Error writing structure

An error occurred when writing the adjusted structure for the current record.

Resolution:

Ensure that the data is not corrupted and that the structure file specified in the conversion details is correct.

Parent topic: DFC1 - DFC11


DFC7 Error – no structure found on heap

The structure file specified in the conversion details is empty.

Resolution:

Redefine a structure file and restart the conversion.

Parent topic: DFC1 - DFC11


DFC10 Error -- not enough memory

Not enough free memory was available to continue the conversion.

Resolution:

Either copy the necessary conversion files to another partition and restart the conversion ensuring that the path information has been updated, or free some space in the current directory.

Parent topic: DFC1 - DFC11


DFC11 Error checking conditions

An error occurred when testing the conditions on the current record.

Resolution:

Redefine a structure file, ensuring that the conditions are valid.

Parent topic: DFC1 - DFC11


DFC101 - DFC139

  • DFC101 Error reading structure file
  • DFC102 Error selecting correct structure
  • DFC105 Error resolving OCCURS DEPENDING ON in structure file
  • DFC107 Error – no structures found in structure file
  • DFC108 Record layout field exceeds record length
    A field within the selected record layout exceeds the length of the record read from the input file.
  • DFC128 No record layout matches record
  • DFC130 Invalid key in input file
    The key information specified for the input file is incompatible with the keys in the file.
  • DFC131 Error opening input file
    CONV was unable to successfully open the input file.
  • DFC132 Error reading input file
    CONV was unable to read the current record of the input file.
  • DFC133 Error opening output file
    CONV was unable to successfully open the output file.
  • DFC134 Error writing output file
    CONV was unable to successfully write the current record to the output file.
  • DFC136 Insufficient memory for loading data
    Not enough free memory was available to continue the conversion.
  • DFC137 Current record length > maximum
    The current record read from the input file has a length greater than the maximum record length specified for that file.
  • DFC138 Warning – Duplicate key, record overwritten
    A record with a duplicate key was found and the corresponding output was overwritten. Note that some data information has been lost.
  • DFC139 Input file not 'real' mainframe report format
    The file specified as the input file contains ANSI carriage control characters and was therefore not generated on the mainframe. Alternatively, you did not supply the correct parameters when you converted the file.
Parent topic: Data File Converter Error Messages


DFC101 Error reading structure file

Parent topic: DFC101 - DFC139


DFC102 Error selecting correct structure

Parent topic: DFC101 - DFC139


DFC105 Error resolving OCCURS DEPENDING ON in structure file

Parent topic: DFC101 - DFC139


DFC107 Error – no structures found in structure file

Parent topic: DFC101 - DFC139


DFC108 Record layout field exceeds record length

A field within the selected record layout exceeds the length of the record read from the input file.

Resolution:

Ensure that the record layout definition matches the data file being converted. Recreate the record layout file with the correct record layouts and ensure the record layout selection conditions are valid.

Parent topic: DFC101 - DFC139


DFC128 No record layout matches record

Resolution:

Ensure the record layout file contains a record description for all record types within the input file. A default record layout can be used if this provides an appropriate record description.

Parent topic: DFC101 - DFC139


DFC130 Invalid key in input file

The key information specified for the input file is incompatible with the keys in the file.

Resolution:

Ensure that the key information read from the file header corresponds to that specified in the conversion details or that the file has not been corrupted.

Parent topic: DFC101 - DFC139


DFC131 Error opening input file

CONV was unable to successfully open the input file.

Resolution:

Ensure that the file details given for the input file are correct.

Parent topic: DFC101 - DFC139


DFC132 Error reading input file

CONV was unable to read the current record of the input file.

Resolution:

Ensure that the file details given, in particular the record length information, are correct.

Parent topic: DFC101 - DFC139


DFC133 Error opening output file

CONV was unable to successfully open the output file.

Resolution:

Ensure that the file details given for the output file are correct and that a file with the same name is not used by another process.

Parent topic: DFC101 - DFC139


DFC134 Error writing output file

CONV was unable to successfully write the current record to the output file.

Resolution:

Ensure that the output file details are correct and that, in particular, the current record in the input file is shorter than the maximum record length of the output file.

Parent topic: DFC101 - DFC139


DFC136 Insufficient memory for loading data

Not enough free memory was available to continue the conversion.

Resolution:

Either copy the necessary conversion files to another partition and restart the conversion ensuring that the path information has been updated, or free some space in the current directory.

Parent topic: DFC101 - DFC139


DFC137 Current record length > maximum

The current record read from the input file has a length greater than the maximum record length specified for that file.

Resolution:

Either check that the file has not been corrupted or reset the maximum record length to the correct value. Remember to also adjust the maximum record length of the output file.

Parent topic: DFC101 - DFC139


DFC138 Warning – Duplicate key, record overwritten

A record with a duplicate key was found and the corresponding output was overwritten. Note that some data information has been lost.
Parent topic: DFC101 - DFC139


DFC139 Input file not 'real' mainframe report format

The file specified as the input file contains ANSI carriage control characters and was therefore not generated on the mainframe. Alternatively, you did not supply the correct parameters when you converted the file.

Resolution:

Either specify it as an EBCDIC line sequential file if that is correct, or use MFEXTMAP"PRINTER".

Reconvert the file, ensuring that you specify Mainframe Report Format in the Organization field, and EBCDIC in the Data Format field of the Convert - Input screen. In the Convert - Output screen, the Format field is automatically set to PC Print Format when you select Mainframe Report Format in the Convert - Input screen.

Parent topic: DFC101 - DFC139


DFC143 - DFC169

  • DFC143 Occurs Depending On value outside range
    During the conversion of a structure containing an OCCURS DEPENDING ON (ODO), the value of the ODO variable in the current record was outside the specified minimum and maximum values in the structure.
  • DFC150 Input record length cannot be zero or > 64K
    The input file maximum record length specified was either 0 or greater than 64K.
  • DFC151 Output record length cannot be zero or > 64K
    The output file maximum record length specified was either 0 or greater than 64K.
  • DFC152 Maximum record length cannot be < minimum length in input file
    The maximum record length specified was less than the minimum in the input file.
  • DFC153 Minimum record length must be > zero in input file
    An attempt was made to set the input file minimum record length to a negative value.
  • DFC154 Maximum record length must be > zero in input file
    An attempt was made to set the input file maximum record length to a negative value.
  • DFC159 Profile file not found
    An attempt was made to load a non-existent profile file.
  • DFC160 Error opening profile file
    CONV was unable to open the profile file specified.
  • DFC161 Invalid profile file format
    CONV was unable to read the profile file.
  • DFC162 Error on output file during conversion
    A file error was encountered when writing to the output file during conversion.
  • DFC163 Error on input file during conversion
    A file error was encountered when reading from the input file during conversion.
  • DFC168 No input file-name specified
    No input file name was specified.
  • DFC169 No output file-name specified
Parent topic: Data File Converter Error Messages


DFC143 Occurs Depending On value outside range

During the conversion of a structure containing an OCCURS DEPENDING ON (ODO), the value of the ODO variable in the current record was outside the specified minimum and maximum values in the structure.

Resolution:

Ensure that the data has been generated with the data structure used to create the .str file or check that the data has not been corrupted.

Parent topic: DFC143 - DFC169


DFC150 Input record length cannot be zero or > 64K

The input file maximum record length specified was either 0 or greater than 64K.

Resolution:

Set it to a valid non-zero value.

Parent topic: DFC143 - DFC169


DFC151 Output record length cannot be zero or > 64K

The output file maximum record length specified was either 0 or greater than 64K.

Resolution:

Set it to a valid non-zero value.

Parent topic: DFC143 - DFC169


DFC152 Maximum record length cannot be < minimum length in input file

The maximum record length specified was less than the minimum in the input file.

Resolution:

Reset the record length value(s) that are in error.

Parent topic: DFC143 - DFC169


DFC153 Minimum record length must be > zero in input file

An attempt was made to set the input file minimum record length to a negative value.

Resolution:

Set the input file minimum record length to a positive value.

Parent topic: DFC143 - DFC169


DFC154 Maximum record length must be > zero in input file

An attempt was made to set the input file maximum record length to a negative value.

Resolution:

Set the input file maximum record length to a positive value.

Parent topic: DFC143 - DFC169


DFC159 Profile file not found

An attempt was made to load a non-existent profile file.

Resolution:

Ensure that the correct location and name were given.

Parent topic: DFC143 - DFC169


DFC160 Error opening profile file

CONV was unable to open the profile file specified.

Resolution:

Ensure that the file is not being used by another process or has not been corrupted.

Parent topic: DFC143 - DFC169


DFC161 Invalid profile file format

CONV was unable to read the profile file.

Resolution:

Ensure that the file was correctly generated by CONV or WFL, and if necessary regenerate it.

Parent topic: DFC143 - DFC169


DFC162 Error on output file during conversion

A file error was encountered when writing to the output file during conversion.

Resolution:

Check the file details and the amount of memory available.

Parent topic: DFC143 - DFC169


DFC163 Error on input file during conversion

A file error was encountered when reading from the input file during conversion.

Resolution:

Check the file details and the amount of memory available.

Parent topic: DFC143 - DFC169


DFC168 No input file-name specified

No input file name was specified.

Resolution:

Ensure that a file name is passed either in the profile file or as a separate parameter.

Parent topic: DFC143 - DFC169


DFC169 No output file-name specified

Resolution:

Ensure that a file name is passed either in the profile file or as a separate parameter.

Parent topic: DFC143 - DFC169


DFC173 - DFC188

  • DFC173 Input file not found
  • DFC174 Structure file not found
  • DFC176 Invalid batch process type
  • DFC178 Maximum input record length allowed 133
  • DFC179 Must specify structure file
  • DFC180 Maximum input record length allowed 133
  • DFC182 Maximum record length cannot be < minimum length in output file
  • DFC183 Minimum record length must be > zero in output file
  • DFC184 Maximum record length must be > zero in output file
  • DFC185 Output file key must lie within record boundaries
  • DFC187 Output file key length cannot be zero or exceed 64K
  • DFC188 Output file key length cannot exceed record length
Parent topic: Data File Converter Error Messages


DFC173 Input file not found

Resolution:

Ensure that the location and name specified are correct or that the file is where you think it is.

Parent topic: DFC173 - DFC188


DFC174 Structure file not found

Resolution:

Ensure that a structure file has been generated, and that its location and name are correct.

Parent topic: DFC173 - DFC188


DFC176 Invalid batch process type

Parent topic: DFC173 - DFC188


DFC178 Maximum input record length allowed 133

Resolution:

Respecify a record length of 133 or less.

Parent topic: DFC173 - DFC188


DFC179 Must specify structure file

Resolution:

Call Structure Selector to define a structure file, load it into the conversion details, and restart the conversion.

Parent topic: DFC173 - DFC188


DFC180 Maximum input record length allowed 133

Resolution:

Respecify a record length of 133 or less.

Parent topic: DFC173 - DFC188


DFC182 Maximum record length cannot be < minimum length in output file

Resolution:

Reset the record length value(s) that are in error.

Parent topic: DFC173 - DFC188


DFC183 Minimum record length must be > zero in output file

Resolution:

Set the minimum record length to a positive value.

Parent topic: DFC173 - DFC188


DFC184 Maximum record length must be > zero in output file

Resolution:

Set the maximum record length to a positive value

Parent topic: DFC173 - DFC188


DFC185 Output file key must lie within record boundaries

Resolution:

Reset the key information or increase the minimum record length of the file.

Parent topic: DFC173 - DFC188


DFC187 Output file key length cannot be zero or exceed 64K

Resolution:

Set the key length to a valid non-zero value.

Parent topic: DFC173 - DFC188


DFC188 Output file key length cannot exceed record length

Resolution:

Reset the key information or increase the minimum record length of the file.

Parent topic: DFC173 - DFC188


DFC190 - DFC196

  • DFC190 Maximum output record length allowed 133
  • DFC191 Maximum output record length allowed 133
  • DFC194 BTRIEVE not found or accessible
  • DFC195 Rebuild only applies to ISAM files
  • DFC196 Output file-name cannot be same as input file-name
Parent topic: Data File Converter Error Messages


DFC190 Maximum output record length allowed 133

Resolution:

Respecify a record length of 133 or less.

Parent topic: DFC190 - DFC196


DFC191 Maximum output record length allowed 133

Resolution:

Respecify a record length of 133 or less.

Parent topic: DFC190 - DFC196


DFC194 BTRIEVE not found or accessible

Resolution:

Ensure that Btrieve is loaded and restart the conversion.

Parent topic: DFC190 - DFC196


DFC195 Rebuild only applies to ISAM files

Resolution:

Ensure that the file you are loading is the correct one.

Parent topic: DFC190 - DFC196


DFC196 Output file-name cannot be same as input file-name

Resolution:

Use a different output file-name.

Parent topic: DFC190 - DFC196


DFC451 - DFC469

  • DFC451 Profile file not found
  • DFC452 Invalid option for Batch process
  • DFC453 Invalid option for Edit mode
  • DFC454 Invalid profile details
  • DFC455 Cannot create profile file
  • DFC462 Invalid option for Input file - Format
  • DFC463 Invalid option for Input file - Organization
  • DFC464 Invalid option for Input file -- Record format
    The option defined for the input file Record-Format parameter is invalid
  • DFC465 Invalid option for Input file -- Character set
    The option defined for the input file Character-Set parameter is invalid
  • DFC466 Invalid option for Input file -- Floating point
    The option defined for the input file Floating-Point parameter is invalid.
  • DFC467 Invalid option for Input file – Minimum record length
  • DFC468 Invalid option for Input file – Maximum record length
  • DFC469 Invalid option for Input file -- Compression flag
    The option defined for the input file Data Compression parameter is invalid.
Parent topic: Data File Converter Error Messages


DFC451 Profile file not found

Resolution:

Correct the path or filename of the profile file.

Parent topic: DFC451 - DFC469


DFC452 Invalid option for Batch process

Resolution:

Correct the profile using one of the following options:

  • Convert-file
  • Rebuild-index
  • Rebuild-index-and-data
  • None
Parent topic: DFC451 - DFC469


DFC453 Invalid option for Edit mode

Resolution:

Correct the profile using one of the following options:

  • Quick
  • Full
Parent topic: DFC451 - DFC469


DFC454 Invalid profile details

Resolution:

Workbench File Loader profiles are fixed format, and as the profile has been edited, you need to verify details against a profile created by Workbench File Loader and correct the error. Alternatively, use File Converter to create a new profile with the required details.

Parent topic: DFC451 - DFC469


DFC455 Cannot create profile file

Resolution:

Ensure you have the correct file access permissions. If the file exists, check that it is not being used by any other process or user.

Parent topic: DFC451 - DFC469


DFC462 Invalid option for Input file - Format

Resolution:

Correct the profile using one of the following options:

  • Micro Focus
  • IDXFORMAT(4)
  • Btrieve
  • C-ISAM
  • LEVEL-II
Parent topic: DFC451 - DFC469


DFC463 Invalid option for Input file - Organization

Resolution:

Correct the profile using one of the following options:

  • Sequential
  • Line-sequential
  • Indexed
  • Mainframe-Report-ANSI
  • Relative
  • Mainframe-Report-mach
  • VRECGEN
  • PC-Print
Parent topic: DFC451 - DFC469


DFC464 Invalid option for Input file -- Record format

The option defined for the input file Record-Format parameter is invalid

Resolution:

Correct the profile using one of the following options:

  • Fixed
  • Variable
Parent topic: DFC451 - DFC469


DFC465 Invalid option for Input file -- Character set

The option defined for the input file Character-Set parameter is invalid

Resolution:

Correct the profile using one of the following options:

  • ASCII
  • EBCDIC
Parent topic: DFC451 - DFC469


DFC466 Invalid option for Input file -- Floating point

The option defined for the input file Floating-Point parameter is invalid.

Resolution:

Correct the profile using one of the following options:

  • IEEE
  • 370
Parent topic: DFC451 - DFC469


DFC467 Invalid option for Input file – Minimum record length

Resolution:

Correct the profile, ensuring that the minimum length is defined.

Parent topic: DFC451 - DFC469


DFC468 Invalid option for Input file – Maximum record length

Resolution:

Correct the profile, ensuring that the maximum length is defined.

Parent topic: DFC451 - DFC469


DFC469 Invalid option for Input file -- Compression flag

The option defined for the input file Data Compression parameter is invalid.

Resolution:

Correct the profile using one of the following options:

  • On
  • Off
Parent topic: DFC451 - DFC469


DFC470 - DFC491

  • DFC470 Invalid option for Input file -- Key field list
    The Prime-key or Alt-key key definition parameter format is invalid.
  • DFC471 Invalid option for Input file -- Key flag list
    The Prime-key or Alt-key key flags list contains invalid options.
  • DFC482 Invalid option for Output file - Format
  • DFC483 Invalid option for Output file - Organization
  • DFC484 Invalid option for Output file -- Record format
    The option defined for the output file Record-Format parameter is invalid
  • DFC485 Invalid option for Output file -- Character set
    The option defined for the output file Character-Set parameter is invalid
  • DFC486 Invalid option for Output file -- Floating point
    The option defined for the output file Floating-Point parameter is invalid.
  • DFC487 Invalid option for Output file -- Minimum record length
    The value defined for the output file Min-Rec-Length parameter is invalid or missing.
  • DFC488 Invalid option for Output file – Maximum record length
  • DFC489 Invalid option for Output file -- Compression flag
    The option defined for the output file Data Compression parameter is invalid.
  • DFC490 Invalid option for Output file -- Key field list
    The Prime-key or Alt-key key definition parameter format is invalid.
  • DFC491 Invalid option for Output file -- Key flag list
    The Prime-key or Alt-key key flags list contains invalid options.
Parent topic: Data File Converter Error Messages


DFC470 Invalid option for Input file -- Key field list

The Prime-key or Alt-key key definition parameter format is invalid.

Resolution:

Correct the profile, ensuring that the key definition parameters use the following format:

Prime-key | 1:5
Alt-key 1 | 10:5
Alt-key 2 | 30:10, 50:10, 70:10
Parent topic: DFC470 - DFC491


DFC471 Invalid option for Input file -- Key flag list

The Prime-key or Alt-key key flags list contains invalid options.

Resolution:

Correct the profile, ensuring the key flag list parameters are from the following list:

d | Allow duplicates
s | Sparse character set
cd | Compression on duplicates
cl | Compression on leading spaces
ct | Compression on trailing spaces

and use the following format:

Prime-key | 1:5
Alt-key 1 | 10:5
 | d, ct
Alt-key 2 | 30:10, 50:10, 70:10
 | s, cl
Parent topic: DFC470 - DFC491


DFC482 Invalid option for Output file - Format

Resolution:

Correct the profile using one of the following options:

  • Micro Focus
  • IDXFORMAT(4)
  • Btrieve
  • C-ISAM
  • LEVEL-II
Parent topic: DFC470 - DFC491


DFC483 Invalid option for Output file - Organization

Resolution:

Correct the profile using one of the following options:

  • Sequential
  • Line-sequential
  • Indexed
  • Mainframe-Report-ANSI
  • Relative
  • Mainframe-Report-mach
  • VRECGEN
  • PC-Print
Parent topic: DFC470 - DFC491


DFC484 Invalid option for Output file -- Record format

The option defined for the output file Record-Format parameter is invalid

Resolution:

Correct the profile using one of the following options:

  • Fixed
  • Variable
Parent topic: DFC470 - DFC491


DFC485 Invalid option for Output file -- Character set

The option defined for the output file Character-Set parameter is invalid

Resolution:

Correct the profile using one of the following options:

  • ASCII
  • EBCDIC
Parent topic: DFC470 - DFC491


DFC486 Invalid option for Output file -- Floating point

The option defined for the output file Floating-Point parameter is invalid.

Resolution:

Correct the profile using one of the following options:

  • IEEE
  • 370
Parent topic: DFC470 - DFC491


DFC487 Invalid option for Output file -- Minimum record length

The value defined for the output file Min-Rec-Length parameter is invalid or missing.

Resolution:

Correct the profile, ensuring that the minimum length is defined.

Parent topic: DFC470 - DFC491


DFC488 Invalid option for Output file – Maximum record length

Resolution:

Correct the profile, ensuring that the maximum length is defined.

Parent topic: DFC470 - DFC491


DFC489 Invalid option for Output file -- Compression flag

The option defined for the output file Data Compression parameter is invalid.

Resolution:

Correct the profile using one of the following options:

  • On
  • Off
Parent topic: DFC470 - DFC491


DFC490 Invalid option for Output file -- Key field list

The Prime-key or Alt-key key definition parameter format is invalid.

Resolution:

Correct the profile, ensuring that the key definition parameters use the following format:

Prime-key | 1:5
Alt-key 1 | 10:5
Alt-key 2 | 30:10, 50:10, 70:10
Parent topic: DFC470 - DFC491


DFC491 Invalid option for Output file -- Key flag list

The Prime-key or Alt-key key flags list contains invalid options.

Resolution:

Correct the profile, ensuring the key flag list parameters are from the following list:

d | Allow duplicates
s | Sparse character set
cd | Compression on duplicates
cl | Compression on leading spaces
ct | Compression on trailing spaces

and use the following format:

Prime-key | 1:5
Alt-key 1 | 10:5
 | d, ct
Alt-key 2 | 30:10, 50:10, 70:10
 | s, cl
Parent topic: DFC470 - DFC491


ACUCOBOL

Look in the sections below to find the error messages produced by the area of the product you are working with.

Parent topic: Error Messages
Related information
ACUCOBOL-GT Windowing Error Messages
Summary of error messages in XML Extensions


Enterprise

Look in the sections below to find the error messages produced by the area of the product you are working with.

Parent topic: Error Messages
Related reference
Enterprise Server Error Messages
Related information
Directory Server Error Messages


Licensing

Look in the sections below to find the error messages produced by the area of the product you are working with.

  • Licensing Error Messages
    Messages you might encounter when working with licensing.
Parent topic: Error Messages


File Handling Reference

  • Compiler Directives - File Handling
    There are a number of Compiler directives that affect file handling.
  • File Handler
  • 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.
  • File Structures
    View the structure of each available file format.
  • Library Routines
    There are a number of library routines that you can call to perform file handling functions.
  • Limits
    There are a number of limits that affect file handling operations in this COBOL system.
  • 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.
  • Run-time Switches
    There are a number of run-time switches that you can set that affect file handling operations.
  • 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.
Parent topic: General Reference
Related reference
Fileshare Guide


Compiler Directives - File Handling

For information on the Compiler directives that affect file handling see the topic File Handling.

Parent topic: File Handling Reference
Related reference
File Handling


File Handler

  • 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.
  • Data Structures
    View the structure of data as it is stored in the FCD.
  • Operation Codes
    View the standard and special operation codes for all file organizations.
Parent topic: File Handling Reference


Configuration File

The default filename for the File Handler configuration file is extfh.cfg but you can use a different filename by setting the EXTFH environment variable. For example:

EXTFH=/mydir/test.cfg
export EXTFH
sets the filename to /mydir/test.cfg.

The File Handler searches for the configuration file in the following order:

  1. The file specified by the EXTFH variable.
  2. The file $COBDIR/etc/extfh.cfg.
  3. The file extfh.cfg in the current directory.
  • 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 Handler


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
Related reference
Configuration File Options


FOLDER tag

Settings that apply to all files in a specific folder are listed under the FOLDER tag, for example:

[FOLDER:usr/files/acufiles]
FILESUFFIX=dat

[FOLDER:C:/files/rmfiles]
IDXFORMAT=21

sets all files in usr/files/acufiles that do not have a suffix to .dat, and all indexed files in usr/files/rmfiles to an IDXFORMAT of 21.

Note: When searching along a path, if a FOLDER tag exists for a stage, settings at that stage are applied, with any conflicting settings overwritten by a subsequent stage. Using the example above, if there was also a FOLDER tag for usr/files that sets IDXFORMAT 2, the subsequent setting of IDXFORMAT 21 would overwrite this.
Parent topic: Format of the Configuration File
Related reference
Configuration File Options


Extension tag

Settings that apply to files of the same file extension are listed under the specific extension tag, for example:

[*.DAT]
IDXFORMAT=2

sets all files with a .DAT extension to an IDXFORMAT of 2.

Parent topic: Format of the Configuration File
Related reference
Configuration File Options


INTERNAL tag

The settings for an individual file override the global settings. If you just specify the filename, it must be the resolved filename, that is, the filename that the File Handler uses after it has completed its filename mapping process. Alternatively, you can prefix the filename with the keyword INTERNAL, to signify that the filename is the name that is used in the SELECT clause; the settings will then be applied to the file that is identified at the conclusion of the filename mapping process. For example, if the ASSIGN mode is dynamic, and you code:

.
[INTERNAL:$myfile/outfile.dat]
IDXFORMAT=8

where myfile is an environment variable holding the name of the directory where the folder is located, the settings will be applied to outfile.dat in that directory.

If the ASSIGN mode is external, and you had:

SELECT MYDATA ASSIGN TO EXTERNAL REALDATA

you could code:

[INTERNAL:REALDATA]

where any options which follow apply to the file to which the logical name "REALDATA" is mapped.

If, however, you have:

.
SELECT MYDATA ASSIGN TO '/directory/subdirectory/datadirectory/myfile'

you cannot use the INTERNAL option in the configuration file. The literal value in the SELECT statement must be replicated [inside square brackets] in the configuration file.

Filenames can use paths and DD_mappings but not wildcards or logic names. If you set the File Handler configuration option BASENAME=ON, you can specify filenames without paths. Note that the name of a file must match the mapped name in your program.

Parent topic: Format of the Configuration File
Related reference
Configuration File Options


Filename tag

Settings that apply to a specific file are listed under the specific filename tag; for example:

[file1.dat]
IDXFORMAT=17
[file2.dat]
IDXFORMAT=21

sets file1.dat to IDXFORMAT 17 and file2.dat to IDXFORMAT 21.

Comments:

To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.

When you use the filename tag, the path to the current directory is assumed, and if a FOLDER tag exists for any folder along the path, settings for that tag are applied. For example, if you have the following file assignment:

SELECT myFile ASSIGN TO 'file1.dat'

and your application is run in the directory usr/files/mffiles, then if you have FOLDER tags for the following locations in your configuration file, the settings in them are applied:

  • usr
  • usr/files
  • usr/files/mffiles
Parent topic: Format of the Configuration File
Related reference
Path and filename tag
BASENAME
Configuration File Options


Path and filename tag

You can explicitly specifiy a file using the path and filename tag; for example:

[usr/acufiles/file1.dat]
IDXFORMAT=17
[usr/rmfiles/file1.dat]
IDXFORMAT=21

sets file1.dat in usr/files/acufiles to IDXFORMAT 17 and file1.dat in usr/files/rmfiles to IDXFORMAT 21.

Note: To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.
Parent topic: Format of the Configuration File
Related reference
Filename tag
BASENAME
Configuration File Options


Example

According to the order that the options are applied, the following excerpt of the File Handler configuration file:
[XFH-DEFAULT]
IDXFORMAT=2
[*.dat]
IDXFORMAT=8
[FOLDER:C:\\files\\acu]
IDXFORMAT=17
results in myfile.dat, located in c:\files\acu, being set to IDXFORMAT 17.
Parent topic: Format of the Configuration File


Configuration File Options

The following options can be set in the File Handler configuration file.

  • 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.
  • 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.
  • 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.
  • WRITELINE
    The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.
  • WRITETHRU
    The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.
Parent topic: Configuration File


ACUFH

Enables or disables the use of the ACU file handler (ACUFH).

Data files detected to be of ACUCOBOL-GT type are directed to ACUFH; data files detected to not be of ACUCOBOL-GT type are processed as normal.

Syntax:

ACUFH = { ON } { OFF }

Parameters:

ON
All types of ACUCOBOL-GT data file are handled by the ACUFH.
OFF
No data files are handled by the ACUFH, even if INTEROP=ACU or IDXFORMAT=17 is set.

Properties:

Default: ON

Comments:

To use ACUFH when running under Enterprise Server, you must also set ESACUFH=ON; this option is OFF by default.

Parent topic: Configuration File Options
Related reference
ESACUFH


ASCIIMAINFRAMEPRINT

The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.

Syntax:

ASCIIMAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Printer Control Characters are in ASCII when CHARSET is set to ASCII.
OFF
Printer Control Characters are in EBCDIC where CHARSET is set to ASCII.

Properties:

Default: OFF

Comments:

You use an entry in the File Handler Configuration File (EXTFH.cfg) to enable the printer control characters to be ASCII when the CHARSET is set to ASCII:

[xfh-default]
 ASCIIMAINFRAMEPRINT=ON

The default value is OFF.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


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
Related reference
Filename tag
Path and filename tag


C$FORMAT

The C$FORMAT option determines the default file format for actions performed using the C$COPY, C$DELETE, and RENAME file handling library routines.

Syntax:

C$FORMAT = format

Parameters:

format
The file format used for operations performed by the library routines C$COPY, C$DELETE, and RENAME. Must be one of:
0
Default format for the operating system (identical to 8)
1
C-ISAM
3
Micro Focus default indexed file format
4
Optimized format for fast duplicate key handling
5
Reserved
6
Reserved
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
Large indexed file format with separate index file
13
Reserved
14
Heap file
15
ESDS
16
Extended ESDS
17
Vision
18
Microsoft SQL Server
19
Oracle
20
DB2
21
RM
22-255
Reserved

Properties:

Default: 17

Comments:

You can specifiy this option in [XFH-DEFAULT] or any other section of the configuration file.

When you call one of the file handling routines, IDXFORMAT defaults to the value of C$FORMAT, but can then be overriden if specified in the file handling configuration file.

Parent topic: Configuration File Options


COMMITFLUSH

In the context of a program that is not using Fileshare, the COMMITFLUSH option specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as record locks to be released.

Syntax:

COMMITFLUSH = { ON } { OFF }

Parameters:

ON
The COMMIT and ROLLBACK statements cause all file updates to be flushed to disk.
OFF
The COMMIT and ROLLBACK statements do not cause all file updates to be flushed to disk.

Properties:

Default: OFF

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


CONCATNAME

The CONCATNAME option determines whether filenames including the plus ('+') character are to be interpreted as normal filenames, or as file concatenations.

A concatenated file should be opened only for input and should have organization SEQUENTIAL or LINE SEQUENTIAL. It is made up of separate components whose names are separated by the '+' character. On reading sequentially through such a file, when the end of one component is reached and another component is available, the next read will automatically return the first record of that component. On reaching the end of the last component, the AT END status is returned.

Syntax:

CONCATNAME = { ON } { OFF }

Parameters:

ON
Names including the '+' character are treated as concatenated files; for example, the name file1+file2 is treated as the concatenation of files file1 and file2.
OFF
Names including the '+' character are created as normal filenames.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


CONVERTDBSPACE

The CONVERTDBSPACE option enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.

Syntax:

CONVERTDBSPACE = { ON } { OFF }

Parameters:

ON
Convert DBCS spaces to ASCII when reading a line sequential file.
OFF
Do not convert DBCS spaces.

Properties:

Default: OFF
Parent topic: Configuration File Options


CONVERTEUCKATAKANA

The CONVERTEUCKATAKANA option enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.

Syntax:

CONVERTEUCKATAKANA = { ON } { OFF }

Parameters:

ON
Convert EUC single-width double-byte characters to their double-width Katakana equivalents.
OFF
Do not convert EUC characters.

Properties:

Default: OFF
Parent topic: Configuration File Options


CONVERTSTATUS

The CONVERTSTATUS option specifies the name of a program that is called after the File Handler has finished processing to map returned status values for emulation purposes.

Syntax:

CONVERTSTATUS = program

Parameters:

program
The name of the program to be called. Three such programs are built into the product:
rmstat
The rmstat program emulates status values returned by RM/COBOL.
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
Related information
Data Compression


DATAFILE

The DATAFILE option maps the filename passed to an OPEN statement onto another name.

Syntax:

DATAFILE = name

Parameters:

name
Name to be mapped to filename; can include full path information.

Properties:

Default: none
Parent topic: Configuration File Options


ESACUFH

Enables or disables the use of the ACUCOBOL-GT file handler (ACUFH) for data file operations running under Enterprise Server.

Syntax:

ESACUFH = { ON } { OFF }

Parameters:

ON
All types of ACUCOBOL-GT data file, running under Enterprise Server are handled by the ACUFH.
Note: ACUFH=ON must also be set before this setting takes effect.
OFF
No data files running under Enterprise Server are handled by the ACUFH, even if INTEROP=ACU or IDXFORMAT=17 is set.

Properties:

Default: OFF

Comments:

If this option is set to OFF, file operations for IDXFORMATs 17-21 are disabled.

Parent topic: Configuration File Options
Related reference
ACUFH


EXPANDPOSITIONING

When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), the first character of the record area can hold carriage control information. The EXPANDPOSITIONING option determines whether the written record includes this carriage control information.

Syntax:

EXPANDPOSITIONING = { ON } { OFF }

Parameters:

ON
Use the first character to determine carriage control before stripping the character from the output.
OFF
Write out the whole record, including the carriage control information.

Properties:

Default: OFF
Parent topic: Configuration File Options


EXPANDTAB

The EXPANDTAB option determines whether to expand TAB characters encountered in line sequential or line advancing files during a READ operation into the equivalent number of spaces.

Syntax:

EXPANDTAB = { ON } { OFF }

Parameters:

ON
Expand TAB characters into the equivalent number of spaces.
OFF
Leave TAB characters unchanged.

Properties:

Default: ON
Parent topic: Configuration File Options


EXTENDEDESDS

The EXTENDEDESDS option enables you to create extended ESDS files.

Syntax:

EXTENDEDESDS = { ON } { OFF }

Parameters:

ON
When set, new ESDS files are created as extended ESDS files. An extended ESDS file is not limited to 4GB, and therefore you can use extended relative byte addressing with it (see the EXTENDEDESDSXRBA option).
OFF
When set, new ESDS files are created as standard ESDS files.

Properties:

Default: OFF

Comments:

This option is synonymous with option IDXFORMAT"16".

Parent topic: Configuration File Options
Related reference
EXTENDEDESDSXRBA


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 or IDXFORMAT"16", before the EXTENDEDESDSXRBA setting takes effect.

Parent topic: Configuration File Options
Related reference
EXTENDEDESDS


FASTREAD

The FASTREAD option specifies whether or not the File Handler performs extra checking to ensure data integrity when reading an indexed file.

Syntax:

FASTREAD = { ON } { OFF }

Parameters:

ON
Do not perform extra checking.
OFF
Perform extra checking to ensure data integrity.

Properties:

Default: ON

Comments:

To increase the efficiency of reads on fixed length, non-compressed indexed files, set FASTREAD to ON.

Parent topic: Configuration File Options


FHREDIR

The FHREDIR option specifies whether a remote server using Fileshare can handle files.

Syntax:

FHREDIR = { ON } { OFF }

Parameters:

ON
Use Fileshare to access files on a remote server.
OFF
Do not use Fileshare.

Properties:

Default: OFF

Comments:

If FHREDIR is set to OFF, the File Handler examines the name at open time to determine whether the file is to be handled locally.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Take care with this option. If it is in effect when Fileshare is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.

Parent topic: Configuration File Options


FILECASE

The FILECASE option enables you to adjust the case of data file names.

Syntax:

FILECASE = { 0 } { 1 } { 2 } { 3 } { 4 }

Parameters:

0
Data file names are not changed
1
Data file names are changed to lower case, including directory (path) elements
2
Data file names are changed to upper case, including directory (path) elements
3
Data file names are changed to lower case, excluding directory (path) elements
4
Data file names are changed to upper case, excluding directory (path) elements

Properties:

Default: 0

Examples:

FILECASE=2  *> e.g. cust_acc\fy11.dat becomes CUST_ACC\FY11.DAT
FILECASE=3  *> e.g. CUST_ACC\FY11.dat becomes CUST_ACC\fy11.dat

Comments:

Translation occurs before the filename is mapped with the values in COBDATA or before the FILESUFFIX option is applied. You should make sure that those variables specify the correct case.

Parent topic: Configuration File Options


FILESUFFIX

The FILESUFFIX option specifies the file extension to be used for files that do not explicitly specify one. This option is switched on/off according to file organization, by using the IDXNAMETYPE, SEQNAMETYPE, LSEQNAMETYPE, and RELNAMETYPE configuration options.

Syntax:

FILESUFFIX = suffix

Parameters:

suffix
The file extension to append to a filename that does not explicitly specify one.

Properties:

Default: Not set
Parent topic: Configuration File Options
Related reference
SEQNAMETYPE
LSEQNAMETYPE
IDXNAMETYPE
RELNAMETYPE


FILEMAXSIZE

The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets.

This also affects locking mechanisms: programs sharing the same file all need to use the same FILEMAXSIZE settings to ensure semaphores and record locks are handled correctly, thereby avoiding potential file corruption in shared files.

Syntax:

FILEMAXSIZE = { 4 } { 8 }

Parameters:

4
Limits file addressibility to 32-bit values, which is compatible with earlier versions of Micro Focus products.
8
Allows up to 64-bit values for file addressing on Windows platforms when accessing the NTFS file system, but changes the underlying record locking mechanism. Therefore, if you are sharing very large files (greater than 1Gb in size) all programs accessing the file must use FILEMAXSIZE set to 8 to avoid possible corruption problems.

Properties:

Default: 8

Comments:

Note: Do not set FILEMAXSIZE to 8 under any of the following circumstances:
  • You are running applications on an operating system which does not support a 64-bit file system.
  • You are running applications that access FAT file systems, since such file systems do not support file addressibility greater than 32-bit file addressing.
  • If any accessing program needs to access a shared file in a 32-bit file system.
  • You are sharing files with applications using earlier versions of the Micro Focus COBOL product that only supported 32-bit file access.

Set FILEMAXSIZE to 4 in these scenarios.

All applications accessing a file must run with the File Handler configured with the same value for FILEMAXSIZE.

If you are requesting 64-bit file access to an unknown remote file system, ensure you set the remote_64bit_access tunable.

Only 32-bit (4GB) support is provided for Novell systems.

Parent topic: Configuration File Options


FILEPOINTERSIZE

For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.

Syntax:

FILEPOINTERSIZE = { 6 } { 8 }

Parameters:

6
Use 6 bytes, allowing for files up to 256 terabytes.
8
Use 8 bytes, allowing for files over 256 terabytes.

Properties:

Default: 6

Comments:

The FILEPOINTERSIZE=8 option uses up more space to store file pointers. Therefore, the resulting file size might increase slightly.

Parent topic: Configuration File Options


FSIDXINTEGRITY

In the context of a Fileshare system, the FSIDXINTEGRITY option causes any changed nodes held within the File Handlers index cache (as configured with the INDEXCOUNT option) to be written to disk before Fileshare returns status information to the client program. This option improves the integrity of indexed files processed by Fileshare at the expense of a small amount of additional file I/O.

Syntax:

FSIDXINTEGRITY = { ON } { OFF }

Parameters:

ON
Changes to the File Handler's index cache are written to disk before Fileshare returns control the client program.
OFF
Changes to the File Handler's index cache are written to disk when space is needed for other operations.

Properties:

Default: ON

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


IDXDATBUF

The IDXDATBUF option determines the size of buffer used when accessing the data portion of a file with organization INDEXED.

Syntax:

IXDATBUF = { integer } { 0 }

Parameters:

integer
Round up the value that you enter to the next power of 2 that is greater or equal.
0
Do not use buffering.

Properties:

Default: 0

Comments:

A non-zero value can be beneficial while the file is being created. Otherwise, you might not achieve a gain in performance; in fact, performance can be degraded.

For those files where index and data are held in the same physical file, this option has no effect.

Parent topic: Configuration File Options


IDXFORMAT

The IDXFORMAT option specifies the format to use when creating or opening indexed files.

Syntax:

IDXFORMAT = integer

Parameters:

0
Default format for the operating system (identical to 8)
1
C-ISAM
3
Micro Focus default indexed file format
4
Optimized format for fast duplicate key handling
5
Reserved
6
Reserved
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
Large indexed file format with separate index file
13
Reserved
14
Heap file
15
ESDS
16
Extended ESDS
17
Vision
18
Microsoft SQL Server
19
Oracle
20
DB2
21
RM
22-255
Reserved

Properties:

Default: 0

Comments:

By default, IDXFORMATs 17-21 are unavailable under Enterprise Server. You must ensure the ACUFH and ESACUFH configuration options are both set to ON to use these formats.

You can set IDXFORMATs 17-21 under all tags in the configuration file except the [XFH-DEFAULT] tag.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override IDXFORMAT.

If you are using Fileshare, IDXFORMATs 17 and 21 do not provide transaction processing capabilities by default. You must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

Rebuild will not take the setting of this configuration option into account when generating a new file. Refer to the Rebuild Options /t topic in the Reference section for further information.

You can also set the index format using the IDXFORMAT Compiler directive, which will override the setting specified in the file handler configuration file.

Parent topic: Configuration File Options
Related reference
ACUFH
ESACUFH


IDXNAMETYPE

The IDXNAMETYPE option specifies the format of the filename type for both the data file and, if present, the index file.

Syntax:

IDXNAMETYPE = { 0 } { 1 } { 2 } { 3 }

Parameters:

0
Leave the filename of the data file the same. For the index file, discard any extension and add the extension .idx.
1
Leave the filename of the data file the same. For the index file, add the extension .idx.
2
For the data file, add the extension .dat. For the index file, add the extension .idx.
3
For the data file, use the extension in the FILESUFFIX variable if there is no extension. For the index file, add the extension .idx.

Properties:

Default: 1

Comments:

IDXNAMETYPE only affects the data file for Vision files.

The name of the index file (if present) is derived from that of the data file. For example, if the data file name presented to the File Handler is abc.def, the options shown above give the following data and index filenames:

0 | abc.def and abc.idx
1 | abc.def and abc.def.idx
2 | abc.def.dat and abc.def.idx

If the data file name is abc and FILESUFFIX=dat, the following data and index filenames are given for IDXNAMETYPE=3:

3 abc.dat and abc.idx
Parent topic: Configuration File Options
Related reference
INTEROP
FILESUFFIX


IGNORELOCK

The IGNORELOCK option specifies whether to ignore locks.

Syntax:

IGNORELOCK = { ON } { INPUT } { OFF }

Parameters:

ON
Ignore all locks.
INPUT
Ignore locks only when reading files open for input.
OFF
Do not ignore locks.

Properties:

Default: OFF
Parent topic: Configuration File Options


INDEXCOUNT

The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.

Syntax:

INDEXCOUNT = node-count

Parameters:

node-count
The number of nodes to be cached. It can be any value between 4 and 255.

Properties:

Default: 32
Parent topic: Configuration File Options


INDEXFILE

The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.

Syntax:

INDEXFILE = name

Parameters:

name
The name of the index file.

Properties:

Default: The name of the index file is derived from the name of the data file by adding the extension .idx (see also IDXNAMETYPE).
Parent topic: Configuration File Options
Related information
IDXNAMETYPE


INSERTNULL

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.

Syntax:

INSERTNULL = { ON } { OFF }

Parameters:

ON
Insert NULL characters before non-printable characters. Strip out NULL characters during READ operations.
OFF
Do not insert NULL characters before non-printable characters. Do not strip out NULL characters during READ operations.

Properties

Default: ON

Comments:

INSERTNULL takes precedence over the N run-time switch.

If you do not set INSERTNULL, the setting of the N run-time switch determines whether or not NULL characters are inserted before non-printable characters.

Parent topic: Configuration File Options


INSERTTAB

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.

Syntax:

INSERTTAB = { ON } { OFF }

Parameters:

ON
Replace sequences of spaces with TAB characters.
OFF
Do not replace sequences of spaces with TAB characters.

Properties:

Default: OFF

Comments:

The setting of the T switch can affect the default setting.

Parent topic: Configuration File Options
Related information
EXPANDTAB


INTEROP

The INTEROP option determines which file handler is used for all file organizations in a given folder.

Syntax:

INTEROP = {ACU} {RM}

Parameters:

Note: These options are case sensitive.
ACU
All Vision file organizations in the specified folder (and sub-folders) use Vision, the ACUCOBOL-GT file handler.
RM
All file organizations in the specified folder (and sub-folders) use RMFM, the RM/COBOL file handler.

Example:

In the following excerpt of the configuration file, all file organizations in the folder usr/files/acufiles use the Vision file handler, and all file organizations in the folder usr/files/rmfiles use the RMFM file handler:

[XFH-DEFAULT]
[FOLDER:usr/files/acufiles]
INTEROP=ACU

[FOLDER:usr/files/rmfiles]
INTEROP=RM

Comments:

ACUFH must be set ON for this option to have an effect. Under Enterprise Server, ESACUFH must also be set to ON for this option to have an effect.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override IDXFORMAT.

If you are only handling indexed files, you can also use the IDXFORMAT settings of 17 for Vision files and 21 for RM files.

INTEROP does not affect database file organizations.

The values for this option must be entered in upper case; invalid values are ignored.

Take care when applying this option to a folder, as the specified file handler attempts to open any file organizations found on the folder's (and sub-folders') path. Files that are not compatible will produce unwanted behavior. Ensure that only valid files are found on the specified path.

Parent topic: Configuration File Options
Related reference
IDXNAMETYPE
ACUFH
ESACUFH


KEYCHECK

The KEYCHECK option specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.

Syntax:

KEYCHECK = { ON } { OFF }

Parameters:

ON
All key definitions must match; otherwise a 3/9 error is returned.
OFF
Open the file, regardless of whether key definitions match or not. Any explicit reference, in the program, to a key which does not match an actual key in the file,results in an error at the time of reference.

Properties:

Default: ON
Parent topic: Configuration File Options


KEYCOMPRESS

The KEYCOMPRESS option specifies the type of key compression in use.

Syntax:

KEYCOMPRESS = integer

Parameters:

0
Key compression is not in use.
1
Duplicater key compression is in use.
2
Leading character compression is in use.
4
Trailing space compression is in use.
8
Trailing null compression is in use.

Properties:

Default: 0

Comments:

To specify a combination of the various types of compression, add together the appropriate numbers. For example, 3 specifies duplicate key compression and leading character compression.

Note:
  • Trailing space compression and trailing null compression are mutually exclusive.
  • The KEYCOMPRESS parameter affects key compression for all indexes belonging to the file.
Parent topic: Configuration File Options
Related information
Key Compression


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 concepts
Configuring Tracing and Logging
Related reference
LOGFILENAME
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.

Use the program cobfhprint to create and display a text version of the log file:

cobfhprint filename
Parent topic: Configuration File Options
Related concepts
Configuring Tracing and Logging
Related reference
LOG


LSEQNAMETYPE

The LSEQNAMETYPE option determines if the FILESUFFIX option is used for line sequential files that do not explicitly specify a file extension.

Syntax:

LSEQNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to line sequential files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to line sequential files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


LSFILETERM

The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.

Syntax:

LSFILETERM = { ON } OFF

Parameters:

ON
Interpret x"1a" characters as EOF markers.
OFF
Ignore EOF characters and continue reading until the physical end of file.

Properties:

Default: OFF

Comments:

This option corresponds to bit h"10" of the fcd-flags-2 field in the File Control Description (FCD).

Parent topic: Configuration File Options


LSRECDELIM

The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.

Syntax:

LSRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for line sequential files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for line sequential files.

Properties:

Default: 0A .
Parent topic: Configuration File Options


MAINFRAMEPRINT

For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).

Syntax:

MAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Use mainframe printer file format.
OFF
Do not use mainframe printer file format.

Properties:

Default: OFF
Parent topic: Configuration File Options


NAMEOPTIONS

The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.

Syntax:

NAMEOPTIONS = { ON } { OFF }

Parameters:

ON
The name you pass to the OPEN statement can contain File Handler options enclosed in round or square brackets. For example:
fil1[PRINTER]
OFF
The name you pass to the OPEN statement cannot contain File Handler options.

Properties:

Default: OFF

Comments:

If set to OFF, the brackets and the characters they enclose are considered as part of the file name.

Note:
  • This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.
  • This parameter is provided for compatibility with older products - you should use it only if you require compatibility with Micro Focus Workbench V4.0.
Parent topic: Configuration File Options


NFSFILELOCK

The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.

Syntax:

NSFILELOCK = { ON } { OFF } { HP }

Parameters:

ON
Enables programs to detect record and file locks on UNIX NFS file systems.
OFF
Windows applications cannot detect record and file locks on UNIX NFS systems.
HP
Specify HP if you are accessing Hewlett-Packard systems.

Properties:

Default: OFF
Parent topic: Configuration File Options


NODESIZE

The NODESIZE option specifies the size of the index nodes to use for an indexed file.

Syntax:

NODESIZE = size_of_node

Parameters:

size_of_node
Use the following minimum NODESIZE values depending on the length of your keys:
Key Length in Bytes | Minimum NODESIZE Value in Bytes
Less than 51 | 512
51 through 100 | 1024
101 through 512 | 4096
513 through 4080 | 16384

Properties:

Default: The minimum NODESIZE value for the key length, except that for key lengths less than 50 bytes, the default is 1024.

Comments:

In most circumstances you should allow the File Handler to work out the appropriate default node size. However, if file size is an issue, smaller node sizes do result in a smaller index file, but you should be aware that they also increase processing time as the tree depth is greater.

Parent topic: Configuration File Options


NOSEQCHECK

The NOSEQCHECK option disables sequence-checking of keys in indexed files.

Setting this option ON enables records to be written in any order to indexed files opened in sequential access mode. Otherwise records must be written in ascending order of prime key.

Syntax:

NOSEQCHECK = { ON } { OFF }

Parameters:

ON
Do not check the sequence of prime keys when writing to an indexed file with ACCESS SEQUENTIAL.
OFF
Return status 21 if prime keys are written out of sequence to an indexed file with ACCESS SEQUENTIAL.

Properties:

Default: OFF

Comments:

Note:

Micro Focus strongly suggest that you control the order in which records are written to indexed files within the program itself, by using the ACCESS SEQUENTIAL or ACCESS DYNAMIC syntax, and avoid using the NOSEQCHECK configuration option.

Parent topic: Configuration File Options


OPENINPUTSHARED

The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.

Syntax:

OPENINPUTSHARED = { ON } { OFF }

Parameters:

ON
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
Related reference
FILESUFFIX


RELRECDELIM

The RELRECDELIM option specifies the characters to be used as the record delimiter in fixed-length relative files.

Syntax:

RELRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for fixed-length relative files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for fixed-length relative files.

Properties:

Default: 0A.
Parent topic: Configuration File Options


RETRYLOCK

The RETRYLOCK option indicates whether you wish to retry a READ operation that fails because the record is locked.

Syntax:

RETRYLOCK = { ON } { OFF } { NOSTATUS } { integer }

Parameters:

ON
Retry the operation until no lock is encountered.
OFF
Do not attempt a retry.
NOSTATUS
Retry the operation for those files for which no status field is defined.
integer
Specify the number of attempts or the number of seconds for which you wish to retry the operation before a locked record status is returned. The RETRYTIME option controls the meaning of integer; for more information see the topic RETRYTIME.

Properties:

Default: OFF

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
RETRYOPEN
RETRYTIME


RETRYOPEN

The RETRYOPEN option indicates whether you wish to retry an I/O operation that fails because the file is locked.

Syntax:

RETRYOPEN = { ON } { ON } { integer }

Parameters:

ON
Retry the operation until no lock is encountered.
OFF
Do not attempt a retry.
integer
Specify the number of attempts or the number of seconds for which you wish to retry the operation before a locked record status is returned. The RETRYTIME option controls the meaning of integer; for more information see the topic RETRYTIME

Properties:

Default: OFF

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
RETRYLOCK
RETRYTIME


RETRYTIME

The RETRYTIME option specifies whether the integer given in the RETRYLOCK and RETRYOPEN options specifies the number of attempts or the number of seconds.

Syntax:

RETRYTIME = { ON } { OFF }

Parameters:

ON
The integer specifies the number of seconds.
OFF
The integer specifies the number of attempts.

Properties:

Default: OFF

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
RETRYLOCK
RETRYOPEN


RUNITLOCKDETECT

The RUNITLOCKDETECT option specifies whether the File Handler checks whether a record has been locked by a separate OPEN statement issued from within the same run unit.

Syntax:

RUNITLOCKDETECT = { ON } { OFF }

Parameters:

ON
Detect record locks.
OFF
Do not detect record locks.

Properties:

Default: ON

Comments:

Locks set within a given run unit are detected, even if RUNITLOCKDETECT is on , if this is supported by the operating system.

Parent topic: Configuration File Options


SEARCHONCREATE

The SEARCHONCREATE parameter determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created. This option applies only to files which are opened with OPEN OUTPUT.

Syntax:

SEARCHONCREATE = { ON } { OFF }

Parameters:

ON
The path will be searched for the file and, if found, the directory where it is found will be used for the creation of the new file.
OFF
The file will be created in the first directory on the search path.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


SEQDATBUF

The SEQDATBUF option determines the size of buffer to use when accessing a file with organization SEQUENTIAL.

Syntax:

SEQDATBUF = integer

Parameters:

integer
Round up the value that you enter to the next power of 2. The minimum value is 4096 bytes.

Properties:

Default: 4096 bytes
Parent topic: Configuration File Options


SEQNAMETYPE

The SEQNAMETYPE option determines if the FILESUFFIX option is used for sequential files that do not explicitly specify a file extension.

Syntax:

SEQNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


SKIPLOCK

The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.

Syntax:

SKIPLOCK = { ON } { OFF }

Parameters:

ON
Advance the current record pointer when a locked record is encountered.
OFF
Do not advance the current record pointer.

Properties:

Default: OFF
Parent topic: Configuration File Options


SPACEFILL

The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.

Syntax:

SPACEFILL = { ON } { OFF }

Parameters:

ON
Fill the area with spaces.
OFF
Do not fill the area with spaces.

Properties:

Default: ON
Parent topic: Configuration File Options


STARTUNLOCK

The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.

Syntax:

STARTUNLOCK = { ON } { OFF }

Parameters:

ON
A START operation will clear any existing lock for files specified with single record locking.
OFF
A START operation will not clear any existing lock for files specified with single record locking.

Properties:

Default: OFF

Comments:

This option is provided only for compatibility. Micro Focus recommend you do not change it.

Parent topic: Configuration File Options


STRIPSPACE

The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Syntax:

STRIPSPACE = { ON } { OFF }

Parameters:

ON
Remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
OFF
Do not remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Properties:

Default: ON
Parent topic: Configuration File Options


SUPPRESSADV

The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Syntax:

SUPPRESSADV = { ON } { OFF }

Parameters:

ON
Ignore the ADVANCING phrase of the WRITE statement for record sequential files.
OFF
Do not ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACE

The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.

Syntax:

TRACE = { ON } { OFF }

Parameters:

ON
Set tracing on either for the individual file or, if specified under the [XFH-DEFAULT] tag, for all files.
OFF
Do not produce a trace file.

Properties:

Default: OFF
Parent topic: Configuration File Options
Related concepts
Configuring Tracing and Logging


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
Related concepts
Configuring Tracing and Logging


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
Related concepts
Configuring Tracing and Logging


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


Data Structures

  • File Control Description (FCD)
  • Global Information Area
  • Key Definition Area
  • Component Definition Area
Parent topic: File Handler


File Control Description (FCD)

The fields contained in the FCD are shown in the following table. The fields do not necessarily appear in this order; the order is defined in the copybook or xfhfcd3.cpy. For flags, the description refers to when the bit is set on. Bit 7 is the most significant (leftmost) bit. Unused bits are reserved for future use.

Refer to the Operation Codes section to display details of how each operation uses these fields.
fcd-file-status (fcd-status-key-1, fcd-status-key-2)
Type: pic x
User file status. After every operation except a COMMIT or ROLLBACK operation, this field is updated with a standard file status value telling you the status of the operation. See also fcd-access-mode and fcd-status-type.
fcd-length
Type: pic xx comp-x
Length of FCD. For FCD3 only.
fcd-version
Type: pic x comp-x
Version number. Values can be:
0 | FCD2
1 | FCD3
fcd-organization
Type: pic x comp-x
File organization. Values can be:
0 | Line sequential
1 | Sequential
2 | Indexed
3 | Relative
fcd-access-mode
Type: pic x comp-x
User status and access mode indicators.

User status is indicated by bit 7. The bit is set if you have defined a file status. Defining a file status can affect how some operations (such as RETRYLOCK) are performed. When calling the File Handler directly, this bit should be set. However, file status is obtained directly from fcd-file-status.

Access mode is indicated by bits 6 through 0:

0 | Sequential access mode
4 | Random access mode
8 | Dynamic access mod
fcd-open-mode
Type: pic x comp-x
Open mode:
0 | INPUT
1 | OUTPUT
2 | I/O
3 | EXTEND
128 | File is closed

You must set this field to 128 before opening a file.

fcd-recording-mode
Type: pic x comp-x
Recording mode:
0 | Fixed
1 | Variable
fcd-file-format
Type: pic x comp-x
File format:
0 | Default format
1 | C-ISAM
2 | Level II V2.5 COBOL
3 | IDXFORMAT"3"
4 | IDXFORMAT"4"
8 | IDXFORMAT"8"
11 | Mainframe print file
12 | IDXFORMAT"12"
14 | Heap file
15 | ESDS
fcd-device-flag
Type: pic x comp-x
Device flag:
0 | Normal
1 | Device
2 | Stdin
3 | Stdout
4 | stderr
5 | Badname
6 | Input pipe
7 | Output pipe
8 | I/O pipe
9 | Library
10 | Disk file
11 | Null
12 | Disk redir
13 | No map
fcd-lock-action
Type: pic x comp-x
Reserved.
fcd-data-compress
pic x comp-x
Data compression routine indicator:
0 | No compression
1-127 | Micro Focus data compression routine number (1= CBLDC001)
128 -255 | User-defined data compression routine number (128=USRDC128)
fcd-blocking
Type: pic x comp-x
Node length in bytes:
0 | Node length determined by system
1 | 512
2 | 1024
4 | 4096
6 | 16384
fcd-idxcache-size
Type: pic x comp-x
Number of index nodes held in cached memory. The number specified should be between 4 and 255. When set to 0, a default of 16 is used.
fcd-percent
Type: pic x comp-x
Percentage indicator
fcd-block size
Type: pic x comp-x
Block size for data records in bytes:
0 | No blocking
12 | 4096
13 | 8192
14 | 16384
15 | 32768
16 | 65536

For indexed and relative files, non-zero settings can degrade performance.

fcd-flags-1
Type: pic x comp-x
Bit 7 | Mainframe compatibility bit. When set, file characteristics are not required to match those specified in program.
Bit 5 | READ and START operations will return the key (only) in the record area
Bit 1 | TRACE=ON
Bit 0 | Reserved
fcd-flags-2
pic x comp-x
Bit 0 sets CONVERTDBSPACE=ON
fcd-mvs-flags
pic x comp-x
Mainframe emulation flags
Bit 2 | File is implicit file (ACCEPT or DISPLAY)
Bit 1 | AMODE(31) is on
Bit 0 | AMODE(24) is on
fcd-status-type
pic x comp-x
Status type:
Bit 7 | Set on for ANSI'85 COBOL file status by default, set off for ANSI'74 COBOL file status
Bit 6 | SPACEFILL=OFF
Bit 5 | STRIPSPACE=OFF
Bit 4 | EXPANDTAB=OFF
Bit 3 | LSRECDELIM=0D0A
Bit 2 | INSERTTAB=ON
Bit 1 | INSERTNULL=ON
Bit 0 | Reserved

Bits 1 and 2 are set or unset by the File Handler at open time, depending on the settings of the N and T RTS switches. These bits can be set or unset after an OPEN operation to override the N and T RTS switches. Bit 3 means 'Use the other sort of line sequential record delimiter'.

fcd-other-flags
Type: pic x comp-x
Bit 7 | OPTIONAL file (OPEN INPUT)
Bit 6 | IGNORELOCK=ON
Bit 5 | Not OPTIONAL (OPEN I/O and EXTEND)
Bit 4 | Filename is EXTERNAL
Bit 3 | Reserved
Bit 2 | NODETECTLOCK directive enabled
Bit 1 | Multiple reel file (record sequential)
Bit 0 | Line advancing file (record sequential)
fcd-trans-log
Type: pic x comp-x
Bit 7 | OPENINPUTSHARED=ON
Bit 5 | READSEMA=OFF
Bit 4 | EXPANDPOSITIONING=ON
Bit 1 | FASTREAD=OFF
Bit 0 | SUPPRESSADV=ON
fcd-lock-types
Type: pic x comp-x
Bit 7 | Interlanguage locking (LOCKTYPE 1 or 2)
Bit 6 | SHARING WITH READ ONLY
Bit 5 | Separate lock file (LOCKTYPE 2)
Bit 4 | RUNITLOCKDETECT=OFF
Bit 3 | Use NFS file locking
Bit 2 | Use NFS file locking with HP compatibility
fcd-fs-flags
Type: pic x comp-x
Fileshare flags:
Bit 7 | Transaction logging
Bit 3 | Trace OPEN and CLOSE operations
fcd-config-flags
Type: pic x comp-x
Bit 7 | WRITETHRU
Bit 6 | Use relative byte address
Bit 5 | Update current record pointer
Bit 4 | For FCD2 use fcd-reladdr-big for relative byte address instead of fcd-reladdr-offset
Bit 1 | Call status conversion routine
Bit 0 | Set if IGNORELOCK required
fcd-misc-flags
Type: pic x comp-x
Miscellaneous flags:
Bit 7 | HOSTFD option (record areas allocated at OPEN time)
Bit 1 | File defined with EXTERNAL syntax
Bit 0 | File closed with lock
fcd-config-flags2
Type: pic x comp-x
Bit 7 | Use EBCDIC collating sequence
Bit 6 | Set if file is to have WRITE AFTER ADVANCING
Bit 5 | Set if file is to have WRITE BEFORE ADVANCING
Bit 4 | ADV specified
Bit 3 | Ignore minimum length checking on variable-length files
fcd-lock-mode
Type: pic x comp-x
Lock mode flags for shareable files:
Bit 7 | Lock on multiple records
Bit 6 | WRITELOCK directive enabled
Bit 5 | RETRYOPEN=ON
Bit 4 | SKIPLOCK =ON
Bit 3 | RETRYLOCK=ON
Bit 2 | Lock mode MANUAL
Bit 1 | Lock mode AUTOMATIC
Bit 0 | Lock mode EXCLUSIVE
fcd-shr2
Type: pic x comp-x
Miscellaneous flags:
Bit 1 | RETRYTIME=ON
Bit 0 | STARTUNLOCK=ON
fcd-nls-id
Type: pic xx comp-x
NLS identifier
fcd-fs-file-id
Type: pic xx comp-x
Reserved
fcd-retry-open-count
Type: pic xx comp-x
RETRYOPEN count field
fcd-name-length
Type: pic xx comp-x
Length of filename
fcd-idxname-length
Type: pic xx comp-x
Reserved
fcd-retry-count
Type: pic xx comp-x
Retry count (used when RETRYLOCK is on)
fcd-key-id
Type: pic xx comp-x
Key-of-reference (indexed files), used for random READ operations. To specify the prime key, set this field to zero. For example, to specify the first alternate key defined, use a value 1; the second alternate key defined use value 2.
fcd-line-count
Type: pic xx comp-x
Line count (sequential files): the number of lines to skip when writing a file. For example:

WRITE AFTER ADVANCING line-count LINES

fcd-use-give
Type: pic xx comp-x
Reserved
fcd-key-length
Type: pic xx comp-x
Effective key length. When using a START operation on indexed files, you can specify only the leading part of a key instead of the whole key. You should set this field to the number of bytes to be used in the comparison. It must be greater than zero, and no bigger than the key being used.
fcd-current-rec-len
Type: pic x(2) comp-x for FCD2; pic x(4) comp-x for FCD3
Current record length (in bytes)
fcd-min-rec-length
Type: pic x(4) comp-x
Minimum record length (in bytes)
fcd-max-rec-length
Type: pic x(4) comp-x
Maximum record length (in bytes)
fcd-session-id
Type: pic x(4) comp-x
Process-id of the locking process on UNIX systems when using FCD3. This is only available for non-transactional files, and does not apply when using Fileshare. On Windows platforms, this is reserved.
fcd-reladdr-offset
Type: pic x(4) comp-x for FCD2; pic x(8) comp-x for FCD3
Relative byte address. (See also fcd-config-flags, bit 4). The value of this field is undefined following the OPEN statement.
fcd-reladdr-big
Type: pic x(8) comp-x
An eight-byte relative byte address. For FCD2, this is a separate field. For FCD3, it redefines fcd-reladdr-offset. Provided for compatibility between FCD2 and FCD3.
fcd-max-rel-key
Type: pic x(8) comp-x
Maximum size of relative key
fcd-relative-key
Type: pic x(8) comp-x
Relative key.

This field is also used, for indexed files, to hold the number of records in the file. It is set following an OPEN.

fcd-handle
Type: pointer
File handle
fcd-record-address
Type: pointer
Pointer to the record area
fcd-filename-address
Type: pointer
Pointer to the filename area
fcd-idxname-address
Type: pointer
Reserved
fcd-key-def-address
Type: pointer
Pointer to key definition block
fcd-col-seq-address
Type: pointer
Pointer to a collating sequence (null if none is used)
fcd-fildef-address
Type: pointer
Reserved
fcd-dfsort-address
Type: pointer
Reserved
Parent topic: Data Structures
Related information
Operation Codes


Global Information Area

All unused or reserved areas must be initialized to binary zeros.

Offset | Type | Description of the Field
0 | pic xx comp-x | Length of the key definition block
2 | pic xxxx comp-x | Reserved
6 | pic xx comp-x | Number of keys
8 | pic xxxxxx comp-x | Reserved
Parent topic: Data Structures


Key Definition Area

All unused or reserved areas must be initialized to binary zeros.

Offset | Type | Description of the Field
0 | pic xx comp-x | Component count. For ordinary keys, the component count is 1. For split keys, the component count is the number of components making up the split key.
2 | pic xx comp-x | Offset to first component definition area for this key. This offset is relative to the start of the global information area, starting at 0.
4 pic x comp-x Key flags:
  • Bit 7 - Reserved
  • Bit 6 - Duplicates allowed
  • Bit 5 - Reserved
  • Bit 4 - Set to indicate that this is the prime key. If this is not set for any key, the File Handler assumes that the first key is the prime key.
  • Bit 3 - Reserved
  • Bit 2 - Reserved
  • Bit 1 - Sparse key. See offset 6.
  • Bit 0 - Reserved
5 pic x comp-x Compression flags:
  • Bits 7 - 4 Reserved
  • Bit 3 - Compression of trailing nulls
  • Bit 2 - Compression of trailing spaces
  • Bit 1 - Compression of leading characters
  • Bit 0 - Compression of duplicates
6 | pic x comp-x | Sparse character. If bit 1 of the key flags (offset 4) is set, the key is suppressed if it is entirely made up of this character.
7 | pic x(9) comp-x | Reserved
Parent topic: Data Structures


Component Definition Area

All unused or reserved areas must be initialized to binary zeros.

Offset | Type | Description
0 pic x comp-x
  • bit 7 (x"80") indicates duplicates to be returned in order
  • bit 6 (x"40") indicates DESCENDING key component
This byte is valid only if you compiled the program used to create the file with IXNUMKEY.
1 | pic x comp-x | bit 7 (x"80") indicates that the field is NUMERIC
If bit 7 is set (numeric):
  • 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 7 is set and 5 is set (non-DISPLAY field), bits 0 and 1 are used as follows:
  • 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
  • bit 2 (value x"04") indicates floating point
If bit 7 is set and bit 5 is not set, (DISPLAY field) but bit 6 is set (SIGNED), bits 0 and 1 are used as follows:
  • 0 - indicates SIGN TRAILING INCLUDED
  • 1 - indicates SIGN TRAILING SEPARATE
  • 2 - indicates SIGN LEADING INCLUDED
  • 3 - indicates SIGN LEADING SEPARATE
If bit 7 is not set (non-numeric):
  • Bit 1 is set if the collating sequence specified in the FCD is to be applied to this field.
2 | pic xxxx comp-x | Offset of component in the record (starting at 0).
6 | pic xxxx comp-x | Length of the component (in bytes).
Parent topic: Data Structures


Operation Codes

  • Standard Operation Codes
  • Special Operation Codes
Parent topic: File Handler


Standard Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Standard Operation Codes - Overview
  • CLOSE
  • COMMIT
  • DELETE
  • DELETE FILE
  • OPEN
  • READ
  • REWRITE
  • ROLLBACK
  • START
  • STEP
  • UNLOCK
  • WRITE
Parent topic: Operation Codes


Standard Operation Codes - Overview

Standard operation codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.
CLOSE | Terminates the processing of a file.
COMMIT | Releases all record locks in all files held by a run unit.
DELETE | Logically removes a record from a file.
DELETE FILE | Physically removes the specified file from the physical devices on which it resides.
OPEN | Initiates the processing of files. It also performs checking and/or writing of labels and other I/O operations.
READ | For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.
ROLLBACK | Releases all record locks in all files held by a run unit.
START | Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.
STEP | Steps to the next physical record.
UNLOCK | Releases all record locks held by a run unit on a named file.
WRITE | Writes a new record to a file.
REWRITE | Replaces an existing record.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Standard Operation Codes


CLOSE

Terminates the processing of files and reels/units with optional rewind and locking where appropriate. For record sequential files, the terms "reel" and "unit" are interchangeable; the treatment of sequential disk files is logically equivalent to the treatment of a file on tape or similar sequential media.
Opcode | Operation | File Type
80 | CLOSE | L S R I
81 | CLOSE WITH LOCK | L S R I
82 | CLOSE WITH NO REWIND | L S
84 | CLOSE REEL/UNIT | L S
85 | CLOSE REEL/UNIT FOR REMOVAL | L S
86 | CLOSE REEL/UNIT WITH NO REWIND | L S

Input Fields

None

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


COMMIT

Releases all record locks in all files held by this run unit.
Opcode | Operation | File Types
DC | COMMIT (Unlock all files) | L S R I

Input Fields

None

Output Fields

None

Comments

This operation code requires an FCD for one of the files, but it can be completely empty except for fcd-version specifiying whether FCD2 or FCD3 is in use.

Parent topic: Standard Operation Codes


DELETE

Logically removes a record from a disk file.
Opcode | Operation | File Types
F7 | DELETE | vS R I

Input Fields:

fcd-relative-key | Relative key of record to remove (R)
fcd-record-address | Pointer to the record area of the record to remove (I)

Output Fields:

fcd-file status File status
Parent topic: Standard Operation Codes


DELETE FILE

Physically removes the specified file from the physical devices on which it resides.

Opcode | Operation | File Types
F8 | DELETE FILE | L S R I

Input Fields:

Filename area |
fcd-organization | File organization
fcd-name-length | Filename length
fcd-file-format | File format
fcd-filename-address | Pointer to the filename area

Output Fields:

fcd-file status File status
Parent topic: Standard Operation Codes


OPEN

Initiates the processing of a file. It also performs checking and writing of labels and other I/O operations.

Opcode | Operation | File Types
00 | OPEN INPUT | L S R I
01 | OPEN OUTPUT | L S R I
02 | OPEN I-O | L S R I
03 | OPEN EXTEND | L S R I
04 | OPEN INPUT WITH NO REWIND | L S
05 | OPEN OUTPUT WITH NO REWIND | L S
08 | OPEN INPUT REVERSED | L S

Input Fields:

Filename area |
Key definition block |
fcd-organization | File organization
fcd-access-mode | Access mode
fcd-open-mode | Open mode
fcd-name-length | Length of filename
fcd-lock-mode | Lock mode flags
fcd-other-flags | Other flags
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)
fcd-data-compress | Data compression
fcd-locktypes | Type of file locks

Output Fields:

fcd-file status | File status
fcd-open-mode | Open mode
fcd-handle | Pointer to the file; use for all subsequent accesses to this file

Comments:

You must have set up a key definition block for this file if it is an indexed file.

You can assign several FCDs to the same physical file and have them all open at the same time. The operating system counts it as just one open file. The physical file is not closed until every logical file assigned to it has been closed.

Parent topic: Standard Operation Codes


READ

For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.

Opcode | Operation | File Types
8D | READ(sequential) WITH NO LOCK | L S R I
D8 | READ (sequential) WITH LOCK | L S R I
D9 | READ (sequential) WITH KEPT LOCK | L S R I
F5 | READ (sequential) | L S R I
8C | READ PREVIOUS WITH NO LOCK | R I
DE | READ PREVIOUS WITH LOCK | R I
DF | READ PREVIOUS WITH KEPT LOCK | R I
F9 | READ PREVIOUS | R I
8E | READ (random) WITH NO LOCK | R I
DA | READ (random) WITH LOCK | R I
DB | READ (random) WITH KEPT LOCK | R I
F6 | READ (random) | R I
8F | READ (direct) WITH NO LOCK | L S R I
D6 | READ (direct) WITH LOCK | L S R I
D7 | READ (direct) WITH KEPT LOCK | L S R I
C9 | READ (direct) | L S R I
F1 | READ (position) | L S R I

Input Fields:

fcd-relative-key | Relative record number (R) if READ random or direct
fcd-key-id | Key identifier (I)
fcd-record-address | Pointer to the record area

Output Fields:

fcd-file status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


REWRITE

Replaces an existing record in a file.

Opcode | Operation | File Types
F4 | REWRITE | L S R I

Input Fields:

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-record-address | Pointer to the record area

Output Fields:

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


ROLLBACK

Releases all record locks in all files held by this run unit.

Opcode | Operation | File Types
DD | ROLLBACK (unlocks all files) | L S R I

Input Fields:

None

Output Fields:

None

Comments:

This operation code requires an FCD for one of the files, but it can be completely empty except for fcd-version specifiying whether FCD2 or FCD3 is in use.

Parent topic: Standard Operation Codes


START

Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.

Opcode | Operation | File Types
E8 | START equal to full length prime key | R I
E9 | START equal to (any key/record number) | R I
EA | START greater than (>) | R I
EB | START not less than (>=) | R I
FE | START less than (<) | R I
FF | START less than or equal to (<=) | R I

Input Fields:

fcd-relative key | Relative record number (R)
fcd-key id | Key identifier (I)
fcd-key-length | Effective key length (I)
fcd-record-address | Pointer to the record area

Output Fields:

fcd-file status File status
Parent topic: Standard Operation Codes


STEP

Steps to the next, previous, first or last physical record in the file . This operation enables very fast access to a record.

Opcode | Operation | File Types
90 | STEP NEXT WITH NO LOCK | L S R I
91 | STEP PREVIOUS WITH NO LOCK | L S R I
92 | STEP FIRST WITH NO LOCK | L S R I
93 | STEP LAST WITH NO LOCK | L S R I
CA | STEP NEXT | L S R I
CB | STEP PREVIOUS | L S R I
CC | STEP FIRST | L S R I
CD | STEP LAST | L S R I
CE | STEP LAST WITH LOCK | L S R I
CF | STEP LAST WITH KEPT LOCK | L S R I
D0 | STEP FIRST WITH LOCK | L S R I
D1 | STEP FIRST WITH KEPT LOCK | L S R I
D2 | STEP PREVIOUS WITH LOCK | L S R I
D3 | STEP PREVIOUS WITH KEPT LOCK | L S R I
D4 | STEP NEXT WITH LOCK | L S R I
D5 | STEP NEXT WITH KEPT LOCK | L S R I

Input Fields:

fcd-record-address Pointer to the record area

Output Fields:

fcd-file-status File status

Comments:

STEP operations are a method of sequentially retrieving records in a relative or indexed file without having to read via a key or relative record number. Generally, this is a faster method of accessing data in the file.

A STEP NEXT operation returns the record that is physically stored immediately after the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP PREVIOUS operation returns the record that is physically stored immediately before the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP FIRST operation returns the record at the beginning of the file.

A STEP LAST operation returns the record at the end of the file.

If you are using relative byte addressing and you have specified that the current record pointer should be updated to the record you have just accessed, STEP operations are relative to this new position.

The relative byte address is returned on every STEP operation, so if you need to update the current record pointer to the record just retrieved, you can use the READ (direct) operation using the address returned.

Note:

The current record pointer is not affected by STEP operations.

Parent topic: Standard Operation Codes


UNLOCK

Releases all record locks held by the run unit on a named file.

Opcode | Operation | File Types
0E | UNLOCK | L S R I

Input Fields:

None

Output Fields:

fcd-file-status File status
Parent topic: Standard Operation Codes


WRITE

Writes a new record to a file.

For sequential files, it can also be used for vertical positioning of lines in a logical page.

Opcode | Operation | File Types
E1 | WRITE BEFORE | L S
E2 | WRITE AFTER | L S
E3 | WRITE BEFORE TAB | L S
E4 | WRITE AFTER TAB | L S
E5 | WRITE BEFORE PAGE | L S
E6 | WRITE AFTER PAGE | L S
EC | WRITE BEFORE mnemonic-name | S
ED | WRITE AFTER mnemonic-name | S
F3 | WRITE | L S R I

Input Fields:

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-line-count | Line count (WRITE only) (S)
fcd-record-address | Pointer to the record area

Output Fields:

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


Special Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Special Operation Codes - Overview
  • File Information
  • Create Index File
  • Get Next Record
  • Add Key Value
  • Re-index File
  • Flush File
  • Unlock Record
Parent topic: Operation Codes


Special Operation Codes - Overview

Special operation codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.

File Information | Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the Key Definition Block.
Get Next Record | Gets the next physical record from the data file part of an indexed file.
Add Key Value | Adds a key value to the index file part of an indexed file.
Re-index File | Re-indexes the file using a supplied key definition block.
Flush File | Flushes all data for a specific file to disk.
Unlock Record | Unlocks a specific record in a file.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Special Operation Codes


File Information

Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the key definition block.

Opcode | Operation | File Types
06 | Return file information | I vS vR

Input Fields:

fcd-organization | File organization (can be x"FF")
fcd-name-length | Length of filename
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)

Output Fields:

Key definition block (I) |
fcd-file-status | File status
fcd-organization | File organization
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-reladdr-offset or fcd-reladdr-big | File size
fcd-data-compress | Data compression routine

It is your responsibility to ensure that you have enough space allocated for the key definition block to hold all the information returned. Failure to allocate enough space causes corruption of some data areas.

For variable-length sequential files and variable-length relative files, no key definition information exists.

If you can set the organization byte of the FCD to x"FF" before using this operation code, an attempt is made to determine the file type and return with the relevant information set. This mode of operation is not recommended if you use any fixed-length sequential files as it might be impossible to determine the difference between the first record of a fixed-length sequential file and the header of a variable-length sequential file. If the file type cannot be determined, the error code 9/161 is returned.

Parent topic: Special Operation Codes


Create Index File

Creates a new .idx file, containing only header information for the file to allow new indexes to be added.

Opcode | Operation | File Types
07 | Open new index | I

Input Fields:

As OPEN.

Output Fields:

As OPEN

Parent topic: Special Operation Codes


Get Next Record

Gets the next physical record from the data file part of an indexed file.

Opcode | Operation | File Types
08 | Get next record | I

Input Fields:

fcd-record-address Pointer to the record area

Output Fields:

fcd-file-status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Special Operation Codes


Add Key Value

Adds a key value to the index file part of an indexed file.

Opcode | Operation | File Types
09 | Add key value | I

Input Fields:

fcd-key-id | Key identifier
fcd-record-address | Pointer to the record area

Output Fields:

fcd-file-status File status
Parent topic: Special Operation Codes


Re-index File

Re-indexes the file using a supplied key definition block.

Opcode | Operation | File Types
0B | Re-index file | I

Input Fields:

Offset 64 Pointer to key definition block.

Output Fields:

None
Parent topic: Special Operation Codes


Flush File

Flushes all data for a specific file to disk.

Opcode | Operation | File Types
0C | Flush File | L S R I

Input Fields:

None

Output Fields:

fcd-file-status File status
Parent topic: Special Operation Codes


Unlock Record

Unlocks a specific record in a file.

Opcode | Operation | File Types
0F | Unlock record | I

Input Fields:

fcd-record-address Pointer to the record area

Output Fields:

fcd-file-status File status
Parent topic: Special Operation Codes


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 if ISAM is utilized.
If Database Connector interfaces are utilized, data has been duplicated in the secondary key.
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
Related information
Data Related


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


File Structures

  • Files without Headers
  • Files with Headers
Parent topic: File Handling Reference


Files without Headers

  • Line Sequential File Structure
  • Printer Sequential File Structure
  • Fixed Format Record Sequential File
  • Fixed Format Relative File
Parent topic: File Structures


Line Sequential File Structure

Line sequential files are designed to enable you to read source or text files created with the system editor. As such, the structure is operating system dependent but typically contains variable length records with trailing spaces removed. In a line sequential file, each record in the file is separated from the next by a record delimiter.

Line Sequential File Structure

For files created on UNIX systems the default record delimiter is the line feed character specified by the single byte x"0A". For files created on DOS or Windows the default record delimiter is the carriage return/line feed character specified by the byte pair x"0D0A". Files created using this COBOL system on UNIX can be read on DOS and Windows, and vice versa. If you set the INSERTNULL configuration option to OFF, you must make sure that any COMP or COMP-3 data does not contain bytes with a value of x"0A" (record delimiter), x"09" (tab) or x"0D" (carriage return).

Parent topic: Files without Headers
Related information
Data Compression


Printer Sequential File Structure

Printer sequential is the structure of files that are destined for a printer, either directly or by spooling to a disk file. The structure of these files reflects what is required to drive a printer and is independent of the operating system.

A printer sequential file consists of a sequence of print records with zero or more vertical positioning characters (such as line-feed) between print records.

A print record consists of zero or more printable characters and is terminated by a carriage return (x"0D").

Printer Sequential File Structure

Parent topic: Files without Headers
Related information
Data Compression


Fixed Format Record Sequential File

In a fixed format record sequential file, each record immediately follows the previous record in the file. Each record is the same length as the maximum length record.

Record Sequential File with Fixed Length Records

Parent topic: Files without Headers
Related information
Data Compression


Fixed Format Relative File

A relative file with fixed-length records is the same as a record sequential file with fixed-length records, except that each record is followed by a record marker which has the value x"0D0A" if the record is present and x"0D00" if the record has been deleted.

Relative File with Fixed Length Records

Parent topic: Files without Headers
Related information
Data Compression


Files with Headers

  • Standard File Header
  • Standard Record Header
  • Variable Format Record Sequential File
  • Variable Format Relative Structure
  • Micro Focus Format Indexed Files
Parent topic: File Structures


Standard File Header

The first record in every variable structure file is a system record called the file header. This is normally 128 bytes in length and takes the following form:

Offset | Size | Description
0 4 Length of the file header. The first 4 bits are always set to 3 (0011 in binary) indicating that this is a system record. The remaining bits contain the length of the file header record, unless the file is an indexed file type that does not include a separate index file (such as IDXFORMAT8); for those types of file, see Index File - File Header. If the maximum record length is less than 4095 bytes, the length is 126 and is held in the next 12 bits; otherwise it is 124 and is held in the next 28 bits. Hence, in a file where the maximum record length is less than 4095 bytes, this field contains x"30 7E 00 00". Otherwise, this field contains x"30 00 00 7C".

An exception to this is the header of C-ISAM files, for which the field contains "30 00 03 FC".

4 | 2 | Database sequence number, used by add-on products.
6 | 2 | Integrity flag. Indexed files only. If this is non-zero when the header is read, it indicates that the file is corrupt.
8 | 14 | Creation date and time in YYMMDDHHMMSSCC format.
22 | 14 | For internal use.
36 | 2 | For internal use.
38 | 1 | For internal use.
39 1 Organization:
  1. Sequential
  2. Indexed
  3. Relative
40 | 1 | For internal use.
41 1 Data compression routine number:
0
No compression
1
CBLDC001
2-127
Reserved for internal use
128-255
User-defined compression routine number
42 | 1 | For internal use.
43 | 1 | Indexed files only - type of indexed file.
44 | 4 | For internal use.
48 1 Recording mode:
0
Fixed format
1
Variable format

For indexed files, the recording mode field of the .idx file takes precedence.

49 | 5 | For internal use.
54 | 4 | Maximum record length. Example: with a maximum record of length 80 characters, this field will contain x"00 00 00 50".
58 | 4 | Minimum record length. Example: with a minimum record length of 2 characters, this field will contain x"00 00 00 02".
62 | 46 | For internal use.
108 | 4 | Version and build data for the indexed file handler creating the file.
112 | 16 | For internal use.
Parent topic: Files with Headers
Related reference
Types of Indexed File
Related information
Data Compression


Standard Record Header

Each record in a variable structure file is preceded by a two- or four-byte record header. The first four bits of this indicate the status of the record, for example, a value of 0100 means that this record is a normal user data record.

The remainder of the record header contains the length of the record. For all files where the maximum record size is less than 4095 bytes (excluding the record header), the record header is two bytes long. For all other files, the record header is four bytes long.

The record header for each record starts at an address which is an exact multiple of the data alignment value for the file type (see the topic Types of Indexed File for details of data alignment values). Consequently, a record may be followed by up to n padding characters, usually spaces. These padding characters are not included in the record length.

First four bits | Record type
1 (0001) | A system record. This indicates a duplicate occurrence record in the data file.
2 (0010) | Deleted record (available for reuse via the free space list).
3 (0011) | System record.
4 (0100) | Normal user data record.
5 (0101) | Reduced user data record (indexed files only). The area immediately following the data, as indicated by the length in the header, indicates length between the end of the data record plus any padding characters and the start of the next record header. This information is contained in either a 2-byte or 4-byte field (see the topic Types of Indexed File for details).
6 (0110) | Pointer record (indexed files only). The first n bytes following the record header contain the offset in the file to the location of the user data record, where n is the file pointer size for the indexed file type (see the topic Types of Indexed File for details).
7 (0111) | User data record referenced by a pointer record.
8 (1000) | Reduced user data record referenced by a pointer record.
9 (1001) | Reserved for future use
10 (1010) | Mid-transaction user data record (As 4 except the record is from a Fileshare transaction which has not yet been COMMITed)
11 (1011) | Mid-transaction reduced user data record (as 5 except the record is from a Fileshare transaction which has not yet been COMMITed)
12 (1100) | Mid-transaction user data record referenced by a pointer record (as 7 except the record is from a Fileshare transaction which has not yet been COMMITed)
13 (1101) | Mid-transaction reduced user data record referenced by a pointer record (as 8 except the record is from a Fileshare transaction which has not yet been COMMITed)
Parent topic: Files with Headers
Related reference
Types of Indexed File
Related information
Data Compression


Variable Format Record Sequential File

In a variable format record sequential file each record written is preceded by a record header containing the length of the record.

Padding characters can follow a record to ensure that the next record starts on a four-byte boundary. Records that are four bytes or smaller are padded to a minimum of eight bytes.

The file contains a standard file header record.

Variable Format Record Sequential File Structure

Parent topic: Files with Headers
Related reference
Standard Record Header
Related information
Data Compression


Variable Format Relative Structure

A relative file with variable-length records follows the basic variable structure but each record is placed into a fixed-length slot, the length of the slot being the length of the longest record defined, plus the header and terminator characters.

The record header for each record contains the length of the logical record written, not the length of the physical fixed-length slot.

Relative File with Variable Length Records

Parent topic: Files with Headers
Related information
Data Compression


Micro Focus Format Indexed Files

  • Types of Indexed File
  • Index File
  • Data File
Parent topic: Files with Headers


Types of Indexed File

This COBOL system supports more than one type of indexed file. The tables below illustrate the different types available and the features that they support.

Table 1. Indexed Files - Features Supported
 | Supports Files Logically >4 Gb | Fast Updates on Files with Multiple Duplicate Keys | Maximum Occurrences of Duplicate Key Value | Support for Variable Length Records and Compression | Separate Index File
IDXFORMAT"1" | No | No | 65535 | No | Yes
IDXFORMAT"2" | No | No | 65535 | No | Yes
IDXFORMAT"3" | No | No | 65535 | Yes | Yes
IDXFORMAT"4" | No | Yes | 4 G | Yes | Yes
IDXFORMAT"8" | Yes | Yes | 4 G | Yes | No
IDXFORMAT"12" | Yes | Yes | 4 G | Yes | Yes
Table 2. Indexed Files - Physical Characteristics
 | Duplicate Occurrence Records | Data Record Alignment | File Pointer Size (bytes) | Residue Length Field | Index Node Includes Record Header
IDXFORMAT"1" | No | 1 | 4 | n/a | No
IDXFORMAT"2" | No | 1 | 4 | n/a | No
IDXFORMAT"3" | No | 4 | 4 | 2 | No
IDXFORMAT"4" | Yes | 4 | 4 | 2 | No
IDXFORMAT"8" | Yes | 8 | 6 | 4 | Yes
IDXFORMAT"12" | Yes | 8 | 6 | 4 | Yes
Parent topic: Micro Focus Format Indexed Files
Related information
Data Compression


Index File

  • Index Files - Overview
  • Index File - File Header
  • Index File - Free Space Record
  • Index File - Key Information Record
  • Index File - Index Node Record
Parent topic: Micro Focus Format Indexed Files


Index Files - Overview

An index file comprises:

  • File header record

    The file header contains information about the file and points to the first free space record and the key information record.

  • Free space records

    Free space records are used to maintain a list of free records in the index file and the data file.

  • Key information record

    The key information record contains details of every key defined for the file, and, for each key, points to its root index node.

  • Index node record

    For each key defined, a complete and independent index is constructed. It consists of a tree of index node records which contain actual key values. Every key value in a node will point either to a subordinate index node record or to the actual data record associated with the key.

The records in an index file are always the same length, whether they are index nodes, file header or key information records. The size of the records is determined at the time the file is created and cannot be changed subsequently.

Parent topic: Index File
Related information
Data Compression


Index File - File Header

The file header is located at offset 0 within the index file. The first 128 bytes are the same as a standard variable structure file header, except for the fields below.

Offset | Size | Description
0 4 The first 4 bits are always set to 3 (0011 in binary), indicating that this is a system record. The remaining bits contain the size of the nodes in the index, which is calculated using the nodesize configuration option minus the 2 bytes used here to specify system record and node size.

For example, the default value of nodesize is 1024, therefore, the first 4 bits in this case would be x"30FE.

4 | 2 | Database sequence number, used by add-on products.
6 | 2 | Integrity flag. Indexed files only. If this is non-zero when the header is read, it indicates that the file is corrupt.
8 | 14 | Creation date and time in YYMMDDHHMMSSCC format.
22 | 14 | For internal use.
36 | 2 | For internal use.
38 | 1 | For internal use.
39 | 1 | Always contains value 2 for indexed organization.
40 | 1 | For internal use.
41 1 Data compression routine number:
0
No compression
1
CBLDC001
2-127
Reserved for internal use
128-255
User-defined compression routine number
42 | 1 | For internal use.
43 | 1 | Indexed files only - type of indexed file.
44 | 4 | For internal use.
48 1 Recording mode:
0
Fixed format
1
Variable format

For indexed files, the recording mode field of the .idx file takes precedence.

49 | 5 | For internal use.
54 | 4 | Maximum record length. Example: with a maximum record of length 80 characters, this field will contain x"00 00 00 50".
58 | 4 | Minimum record length. Example: with a minimum record length of 2 characters, this field will contain x"00 00 00 02".
62 | 14 | Always contains zeros.
76 | 1 | Reserved. Set to 4.
77 | 31 | Always contains zeros.
108 | 4 | Version and build data for the indexed file handler creating the file.
112 | 8 | For internal use.
120 | 8 | Offset of logical end of the index file.

The remainder of the file header contains the following fields:

Offset | Size | Description
128 | 8 | Offset of logical end of the data file.
136 | 1 | Value 2.
137 | 1 | Value 2.
138 | 1 | Value 4.
139 | 1 | Value 4.
140 | 2 | Contains the number of keys defined for the file.
142 | 1 | Value 0, or 1 if duplicate occurrence records are present. See the topic Types of Indexed File for details.
143 | 1 | Value 2 or 4. Number of bytes used for occurrence numbers in indices where duplicates are permitted.
144 | 8 | Offset of the first key information record.
152 | 8 | Offset of the free space record for the data file. For fixed format files, this is a record in the index file of the same format as the index free space record, but the addresses point to free records in the data file. For variable format files, this is the address in the data file of the data free space record. This record has a different structure to the index free space record.
160 | 8 | Offset of the first free space record in the index file.
168 | 4 | Value zeros.
172 | 4 | Index file record length (node size).
176 | 8 | A unique sequence number used to compare the state of a file against specific transaction log entries during the rollback recovery process.
184 | 328 | Reserved. Value zeros. For node size 512.
 | 840 | Reserved. Value zeros. For node size 1024.
 | 3912 | Reserved. Value zeros. For node size 4096.
Parent topic: Index File
Related concepts
Types of Indexed File


Index File - Free Space Record

The free space record points to the location of free records in the index file or data file (fixed-length files only). Continuation records of the same size and structure are created as needed, each pointing to the next continuation record.

The first free space record is pointed to by the file header.

A free space record contains:

Size | Description
2 | Record header. Present only if index nodes have record header (see the topic Types of Indexed File).
2
Bit 15
Security Flag. Value should match value of trailing security flag.
Bits 14-0
Pointer to the end of the last free record address entry, relative to the start of this record.
file-pointer-size | Offset of free space continuation record. Zero if no further continuation records.
file-pointer-size | Offset of a free record in the index file.
...
file-pointer-size | Offset of a free record in the index file.
2
Bit 15
Security flag. Value should match value of leading security flag.
Bits 14-0
Reserved. Value x"7F".

The size of file-pointer-size varies according to the type of indexed file. See the topic Types of Indexed File for details.

Parent topic: Index File
Related concepts
Types of Indexed File


Index File - Key Information Record

The key information record describes the physical characteristics of all the keys used in the file, including the length of each key; where the key is defined within the data record; whether duplicates are permitted, and so on. Within the key information record structure is a sub-structure, the key block. A key block is created for each key defined. The first key block always describes the primary key. Subsequent key blocks define the alternate keys in the order specified when the file was created. If the key information record is not big enough to hold key blocks for all the keys defined, equal sized continuation records are created, each pointing to the next, until all the keys have been defined.

The key information record contains:

Size | Description of the field
2 | Record header. Present only if index nodes have record header. See the topic the topic Types of Indexed File for details.
2
Bit 15
Security flag. Value 0.
Bits 14-0
Pointer to the end of the last key block entry in this record, relative to the start of this record.
file-pointer-size | Address of continuation record. Zero if no further continuation records.
n | Key block for primary key
... ...one for each alternate key in the file
n | Key block
1 | Reserved. Value x"FF".
1 | Reserved. Value x"7E".

For all indexed file formats except IDXFORMAT"8" or IDXFORMAT"12", the key block contains:

Size | Description of the field
2 | Length of this entry in bytes.
4 | Address of the root index node record for this key.
1 Key compression:
Bit 2
Compression of trailing spaces.
Bit 1
Compression of leading characters.
Bit 0
Compression of duplicates.
5 | Key component block
... ...if the key is split, one block per component
5 | Key component block

For IDXFORMAT"8" and IDXFORMAT"12" files, the key block contains:

Size | Description of the field
2 | Length of this entry in bytes.
1 | Sparse key character.
13 | Reserved.
1 Key compression:
Bit 3
Compression of trailing nulls.
Bit 2
Compression of trailing spaces.
Bit 1
Compression of leading characters.
Bit 0
Compression of duplicates.
1 Key flags:
Bit 6
Duplicates permitted.
Bit 1
Sparse key.
6 | Key component block
... ...if the key is split, one block per component
6 | Key component block

For all indexed file formats except IDXFORMAT"8" or IDXFORMAT"12", the key component block contains:

Size | Description of the field
2
Bit 15
Duplicates permitted flag. If set, duplicates are permitted.
Bits 14-0
Length of component in bytes.
2 | Offset of component within data record, starting at 0.
1 | Component type. Value zeros.

For IDXFORMAT"8" and IDXFORMAT"12" files, the key component block contains:

Size | Description of the field
2 | Length of component in bytes.
2 | Offset of component within data record, starting at 0.
1 Component flags:
Bit 6
Descending
1 Component type:
Bit 7
Numeric.
Bit 6
Signed.
Bits 5-0
If not numeric:

0 – alphanumeric

If numeric:

h"00" – DISPLAY (SIGN TRAILING INCLUDED)

h"01" – DISPLAY (SIGN TRAILING SEPARATE)

h"02" – DISPLAY (SIGN LEADING INCLUDED)

h"03" – DISPLAY (SIGN LEADING SEPARATE)

h"20" – COMP

h"21" – COMP-3

h"22" – COMP-X

h"23" – COMP-5

h"24" – FLOAT

Parent topic: Index File
Related concepts
Types of Indexed File


Index File - Index Node Record

For each key defined, a complete and independent index is constructed which consists of a tree of index node records. Each index node record contains actual key values associated with data records written to the indexed file. Every key value in a node will point either to a subordinate index node record or, if it is a leaf node, to the data record associated with the key.

The top level node record is called the root.

The default node size is 1024 bytes, but can change depending on the largest key size defined for the file. If the largest key is greater than 238 bytes, the node size will be 4096 bytes.

Note: It is possible to change the default node size by setting the XFHNODE environment variable to one of 512, 1024 (the default) or 4096 bytes. However, if you set XFHNODE to 512 and the largest key value is greater than 120 bytes, the value of XFHNODE will be overwritten by 1024. Also, if you set XFHNODE to 512 or 1024 and the largest key value is greater than 248, the value of XFHNODE will be overwritten by 4096. The setting of XFHNODE is only effective at the time that the file is created - you cannot alter the node size of an existing file.

The index node record contains:

Size | Description of the field
2
Bit 15
Security flag. Value should match value of trailing security flag.
Bits 14-0
Pointer to the end of the last key value block in this record, relative to the start of this record.
n | Key value block
...
n | Key value block
1 Index number.

The value is the same for all nodes belonging to the same index tree. Contains zero if this is the primary key.

1
Bit 7
Security flag. Value should match value of leading security flag.
Bits 6-0
Level of this node. Leaf nodes are level 0.

The key value block contains:

Size | Description of the field
1 | Present only when compression of leading characters is enabled. Contains a count of leading characters identical to those in the previous key. It will always be 0 for the first key in a node.
1 | Present only when compression of trailing spaces is enabled. Contains a count of trailing spaces for this key value.
n | Key value.
duplicate-occurrence | Optional. Duplicate occurrence number. See the topic Types of Indexed File for details. This field is present only if duplicates are allowed for this key. It contains the duplicate occurrence count. The first key stored that is a duplicate has this field set to 1. Second duplicate has this field set to 2, and so on.
file-pointer-size
Most significant bit
Reserved if duplicate key compression is enabled. Set if the next Key-Value Block is a duplicate of this one.
Remainder
Address of the data record in the data file if this is a leaf node; otherwise, the address of the subordinate index node record in the index file.
Parent topic: Index File
Related concepts
Types of Indexed File


Data File

  • Indexed File - Data File Structure
Parent topic: Micro Focus Format Indexed Files


Indexed File - Data File Structure

The data file part of an indexed file contains all the data records.

Information about free records in the data file is maintained so that space created by deleting records can be re-used, preventing the file from growing too quickly.

In a fixed-format indexed file, this information is held in a free space record in the index file. This record has the same structure as the index free space record, but the addresses point to data file records.

In a variable-format indexed file, the information is held in a system record in the data file. All records are a multiple of the data record alignment size. For each slot length, a chain is maintained for all slots of that length that are free. The start of the chain for all lengths is maintained in the data free space record in the data file. This system record is always the same length as the maximum slot length or possible maximum compressed length (a record's length may increase when it is compressed) for the file. Each free slot pointed to contains, in the first n bytes after the record header, the address of the next free slot of the same length. For the last slot in the chain, this address contains zero.

The data free space record contains:

Offset | Size | Description of the field
0 | 2/4 | Record header.
2/4 | 4 | Offset of the first free data slot of length 8 bytes.
6/8 | 4 | Offset of the first free data slot of length 12 bytes.
... |  |
n | 4 | Offset of the first free data slot of maximum length.
Parent topic: Data File


Library Routines

For information on the library routines that perform file handling functions see the topic File and Filename Routines.

Parent topic: File Handling Reference
Related reference
File and Filename Routines


Limits

There are a number of limits that affect file handling operations in this COBOL system.

  • Limits - Overview
  • File Handling - COBOL Compiler Limits
  • File Handling - Run-time Limits
  • File Size Limits - General
  • Indexed File Size Limits
  • Sequential and Relative File Size Limits
  • File Handling - Operating System Limits
Parent topic: File Handling Reference


Limits - Overview

The following limits affect file handling:

  • COBOL run-time limits
  • File size limits
  • Indexed file size limits
  • Sequential and relative file size limits
  • Operating system limits

The limits associated with the COBOL Compiler cannot be exceeded. However, at run time, the operating system or hardware can affect the operation of the COBOL run-time, thereby imposing limits that are lower than those of the Compiler. In addition, the particular configuration of the operating system or hardware environment can directly impose limits that are lower than those of both the Compiler and the run-time.

Parent topic: Limits
Related information
File Handling - COBOL Compiler Limits
File Handling - Run-time Limits
File Size Limits - General
Indexed File Size Limits
Sequential and Relative File Size Limits
File Handling - Operating System Limits


File Handling - COBOL Compiler Limits

Remember that run-time limits and operating system limits may be lower than those of the COBOL Compiler.

Index key Limits

Per file (including split-key components) | 255 keys
Length of any one key, including split-key | 1016 bytes (performance best below 512)
Number of components in a split key | 62
Number of alternate keys: | 252

SORT/MERGE Operation Limits

Number of SORT input files: 128
Parent topic: Limits


File Handling - Run-time Limits

You should be aware that run-time limits may be lower than those imposed by the COBOL Compiler.

File sizes (number of records)

All file organizations No specifiable limit; depends on record size and file size

Index keys (numbers)

Records added with the same duplicate key value in:
 | IDXFORMAT 3 and C-ISAM | 65,535
 | With IDXFORMAT"4", IDXFORMAT"8", or IDXFORMAT"12" directive | 4,294,967,297
Components in a split key: With IDXFORMAT"4", IDXFORMAT"8", or IDXFORMAT"12" directive
 | (using Micro Focus format file) | 62
 | (using C-ISAM format file) | 8

Record sizes

All file types 62 KB

Sort keys

Sort key size | 4096
Number of sort keys | 64
Parent topic: Limits


File Size Limits - General

The following limits affect file size in general:
  • 32-bit Windows platforms impose a file size limit of 4 Gbytes.
  • 64-bit Windows platforms allow for very large file sizes.
  • Some UNIX platforms impose a file size limit of 2 Gbytes.
Note: Even on UNIX platforms that support larger file sizes, the default kernel settings frequently impose a 2 Gbyte limit.
Parent topic: Limits


Indexed File Size Limits

The following file size limits affect indexed files. The default (where IDXFORMAT=0) is IDXFORMAT 8.

To create files of a different format, use the IDXFORMAT extfh.cfg or compiler directive setting. To convert existing files to other formats, use the Rebuild utility.

IDXFORMAT | Exclusive (#) | Exclusive with duplicate key compression on | Shared with default locking | FILEMAXSIZE set to
1 | 4 Gb | 2 Gb | 1 Gb | 4 or 8
2 | 4 Gb | 2 Gb | 1 Gb | 4 or 8
3 | 4 Gb | 2 Gb | 1 Gb | 4 or 8
4 | 4 Gb | 2 Gb | 1 Gb | 4 or 8
8 and 12 | 4 Gb | 2 Gb | 1 Gb | 4
8 and 12 | 256 Tb | 128 Tb | 256 Tb | 8

where:

  • (#) = either accessing files exclusively or accessing shared files with the extfh.cfg or compiler directive setting of LOCKTYPE 1 or 2. That is, file size is not affected when using LOCKTYPE 1 or 2.
  • FILEMAXSIZE is an extfh.cfg setting that defaults to 8
  • For IDXFORMAT 8 or IDXFORMAT 12 files only, if you increase the extfh.cfg setting FILEPOINTERSIZE to 8, you increase file size limits to:
    IDXFORMAT | Exclusive (#) | Exclusive with duplicate key compression on | Shared with default locking | FILEMAXSIZE set to
    8 and 12 | 16 Eb | 8 Eb | 4 Eb | 8
Note:
  • The above figures are determined by the pointer size used to address the file. For example:
    32 bits = 2^32 = 4,294,967,296 bytes = 4 Gb (Gigabytes)
    48 bits = 2^48 = 281,474,976,710,656 bytes = 256 Tb (Terabytes)
    64 bits = 2^64 = 18,446,744,073,709,551,616 bytes = 16 Eb (Exabytes or MegaTerabytes)
  • LOCKTYPE settings of 1 and 2 were specifically introduced in order to avoid the file size limit imposed by sharing files.
  • If you set FILEMAXSIZE to 8, IDXFORMAT 8 and IDXFORMAT 12 both support very large files with the default locking mechanism. Therefore, you are recommended to use IDXFORMAT 8 or IDXFORMAT 12 for large files rather than any of the other formats which also require LOCKTYPE 1 or 2 for large files. (LOCKTYPE=1 has the disadvantage of not allowing locked data to be read at all while LOCKTYPE=2 has the disadvantage of using up an extra file handle for the .LCK file that contains the locks).
Parent topic: Limits
Related reference
FILEMAXSIZE
IDXFORMAT
FILEPOINTERSIZE
LOCKTYPE


Sequential and Relative File Size Limits

The following file size limits affect sequential (including line sequential) and relative files:

Exclusive | Shared | FILEMAXSIZE set to
4 Gb | 1 Gb | 4
8 MTb | 4 MTb | 8

where FILEMAXSIZE is a File Handler configuration file setting that defaults to 8.

Parent topic: Limits
Related reference
FILEMAXSIZE


File Handling - Operating System Limits

The operating system and hardware configuration impose direct limits which can be lower than those imposed by either the COBOL Compiler or the COBOL run-time.

You must check your operating system and hardware to discover the actual values for any limits, but the following table lists items that you should consider:

  • Record locks
  • File locks
  • Length of contents of DD_ environment variables
  • File and record sizes
  • Files open simultaneously
  • Filename size and format

You should also be aware that the number and size of index keys can be limited if you are using a non-standard file handler and that the number and size of sort keys can be limited if you are using a non-standard SORT module.

Parent topic: Limits


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.

Note: On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character (or two hyphen characters in the case of //q and //v).

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.

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
Related information
Example of Reorganizing an Indexed File


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
Related information
Data Related


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


Run-time Switches

The following run-time switches affect file handling:
L2 - Record Terminator Switch
The record terminator switch specifies the character to be used as a record terminator in line sequential files. When -L2 (the default) is used, x"0A" is treated as the record terminator. When +L2 is used, x"0D0A" is treated as the record terminator.

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 on either Windows or UNIX systems, 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.

N - Null Switch
When +N is used (which is the default), all characters less than x"1B" are preceded by a null byte (x"00"). If -N is used, characters less that x"1B" are treated as control characters; for example, x"1A" is treated as the end-of-file marker. If a file is created from an application running with -N, the file must be read back with an application running the same way; the same is true for files created from applications running with +N.
T - Tab Switch
The tab switch is set off (-T) by default. The tab switch compresses extra spaces to tab characters (x"09"), for line sequential files. This saves space in the file. If you write a file with +T set, you must use +T when reading the file and if you write a file with -T set, you must use -T when reading the file.
Parent topic: File Handling Reference
Related reference
L2 run-time switch
N run-time switch
T run-time switch


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:

  • SORTCOMPRESS
    Determines whether to compress each record in a SORT operation.
  • SORTSCHEME
    To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.
  • SORTSPACE
    Determines the amount of memory allocated to internal workspace for SORT operations.
  • SORTTEMPSPACE
    Determines the amount of temporary memory allocated for SORT operations.
  • SORTTYPE
    Determines the method for reading and writing files during SORT operations.
  • TEMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


SORTCOMPRESS

Determines whether to compress each record in a SORT operation.

When SORTCOMPRESS is set, run-length encoding of sort records results in much better performance when records contain multiple repeated characters.

Parameters

0
No compression.
Any number not equal to 0
Compression of records.

The default value is 0.

Example

SORTCOMPRESS=5
Parent topic: SORT Environment Variables
Related concepts
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME


SORTSCHEME

To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.

You should consider setting this environment variable if the total size of files in your SORT operation is over 1GB.

Parameters

0
During a SORT operation, temporary files are created to hold the non-key data portions of a record that are greater than 1024 bytes.
1

During a SORT operation, non-key data portions of a record are held in memory depending on the size of SORTSPACE:

Size of SORTSPACE | Maximum non-key data portion held in memory
1MB or greater | 5KB
4MB or greater | 12KB
8MB or greater | 28KB
16MB or greater | 62KB
Note: In general, the non-key data portion is the size of the record minus the size of the key data.

The default value is 0.

Example

SORTSCHEME=1
Parent topic: SORT Environment Variables
Related concepts
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTCOMPRESS


SORTSPACE

Determines the amount of memory allocated to internal workspace for SORT operations.

Typically, increasing SORTSPACE will improve the overall performance of SORT operations. This can be improved further by the use of SORTSCHEME when the files to be sorted are over 1GB.

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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSCHEME
SORTCOMPRESS


SORTTEMPSPACE

Determines the amount of temporary memory allocated for SORT operations.

If you cannot set SORTSPACE to allocate enough contiguous memory for a SORT operation, set SORTTEMPSPACE to the required amount, and then set SORTSPACE to a smaller value. Memory is then allocated in chunks of the size specified by SORTSPACE, until it has allocated the value set by SORTTEMPSPACE.

We recommend that you use SORTTEMPSPACE only if you are receiving COBRT105 Memory allocation error (Fatal) errors.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTTYPE

Determines the method for reading and writing files during SORT operations.

Parameters

0 or 1
SORT operations use CBL_ routines, where possible, which improves performance.
2
SORT operations use the file handler, so that format modifications are picked up from the extfh.cfg file.

The default value is 0.

Example

SORTTYPE=2
Parent topic: SORT Environment Variables
Related concepts
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


TEMPDIR/ TMP/ TEMP

Determines where the run-time system of the directory stores paging files.

By default, the paging files are stored in the current directory.

Parameters

pathname
Specify the pathname for the paging files, using the correct environment variable for your operating system:
Platform | Environment variable
UNIX | TMPDIR
Windows or other | TMP (or TEMP if TMP is not set)

Example

TMPDIR=/home/temp	*> UNIX
TMP=C:\temp		 *> WINDOWS
Parent topic: SORT Environment Variables
Related concepts
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


Mfsort Error Messages

Select the range containing your message number:

  • Messages 0001 to 0099
  • Messages 0100 to 0199
  • Messages 0200 to 0399
Parent topic: Sorting Files


Messages 0001 to 0099

Select the number of the message you require details about:

  • SORT014U Status = value
  • SORT015U Command statement error(s) detected
    The sort will not execute because of errors found during the parsing of the command.
  • SORT019I Key length truncated to 4096 bytes
  • SORT020U SORT(EXTSM) failed - sort engine status = Value
    An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.
  • 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
  • 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


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


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 Visual COBOL
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 Visual COBOL
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.

Parent topic: Messages 0200 to 0399


SORT399I End of Micro Focus MFJSORT Utility

Parent topic: Messages 0200 to 0399


Integrated Preprocessor Interface

  • Overview - Integrated Preprocessor Interface
  • Invoking a Preprocessor
  • Writing a Preprocessor
  • CP Preprocessor
  • COBOL Preprocessor Error Messages
Parent topic: General Reference


Overview - Integrated Preprocessor Interface

Note: The Integrated Preprocessor is supported for native COBOL only.

Language preprocessors (also known as precompilers) are used to convert non-standard COBOL, or non-COBOL code embedded in COBOL, into a form that the Compiler can process.

A non-integrated preprocessor takes as input a source file, reads and parses it, and produces a modified source file which is then passed as input to the COBOL compiler. This has the following disadvantages:

  • There are two steps involved in compiling a program
  • There can be no integration between the Compiler and editor; for example if an error occurs during compilation there is no possibility of the editor highlighting the original source line in error
  • Listing output and debugging tools do not show the original source program

These factors can significantly lengthen the development cycle.

The Integrated Preprocessor Interface overcomes these problems by enabling the preprocessor to mark the relationship between the original source code and the modified form. Although the Compiler will actually process the modified COBOL, it will only ever show the original code.

The Integrated Preprocessor Interface enables a preprocessor to read source files and pass modified source lines to the Compiler. This makes the interface completely general purpose. The disadvantage of this approach is that the preprocessor itself has to handle COBOL constructs such as continuation, copybook expansion and the effects of REPLACE and REPLACING. Micro Focus provides the CP preprocessor, which can handle REPLACE and REPLACING, although this does require that COPY statements conform to normal COBOL syntax rules. If, by comparison, the Compiler read source files and passed single tokens to the preprocessor, restrictions such as the format of a token and the syntax of a COPY (or equivalent) statement would be imposed.

The underlying code that is actually compiled might be significantly different from the original. You might therefore notice that:

  • The debugger cannot query a data item, as the data item does not exist in the underlying code.
  • The debugger does not reference lines that were modified by the preprocessor, as the compiler does not process these lines and is unaware of their contents.
  • An accurate cross reference listing is not produced by the XREF Compiler because information for code inserted by the preprocessor is not shown, even if the original source line referenced the same data items.
  • Certain directives, most notably FLAG and language switches such as MF, cause the Compiler to reject or flag code produced by a preprocessor, whether integrated or not. The Integrated Preprocessor Interface eases the task of preventing such problems by:
    • Never flagging lines inserted by a preprocessor
    • Enabling the preprocessor to query Compiler directive settings.

    A preprocessor can generate lines containing $SET statements to switch directive settings, but this might cause problems, especially if your code uses names for data items that conflict with reserved words in the language selected by the preprocessor.

A supplied preprocessor reads and expands source files (including copybooks), and returns additional information to other preprocessors in the stack about the effect of REPLACE and REPLACING.

Parent topic: Integrated Preprocessor Interface
Related reference
The COPY Statement
The REPLACE Statement
Related information
Invoking a Preprocessor
Writing a preprocessor - overview
CP Preprocessor


Invoking a Preprocessor

Note: The Integrated Preprocessor is supported for native COBOL only.

The preprocessor is invoked by the Compiler, which is directed to do so by using the PREPROCESS directive. The general form of the directive is:

>>--.---.-.----.-PREPROCESS-.-"name".----------------.-.------.-.><
    +-/-+ |    +-P----------+       +-preproc-params-+ +-ENDP-+ |
          |                                                     |
          +-NO-.-PREPROCESS-.-----------------------------------+
               +-P----------+

where the parameters are:

name | The name of the preprocessor
preproc-params | One or more of the optional preprocessor parameters

You specify the directive when compiling a file you want preprocessed.

All parameters on the command line following the PREPROCESS directive and up to the end of the line, or the ENDP directive, are passed to the preprocessor without examination.

Note: It is advisable to use the ENDP COBOL directive to terminate the directives to pass to the preprocessor. Directives placed after ENDP pass to the COBOL compiler. Therefore, without the ENDP directive, compiler directives may continue to pass to the preprocessor rather than to the COBOL compiler.

In a similar manner to other Compiler directives, the PREPROCESS directive can be either placed in a directives file or included in a $SET statement within the source code. It should not be specified in more than one place. If it is in a $SET statement, it must be the first line in the source file.

Invoking Multiple Preprocessors

Multiple preprocessors are invoked by passing a preprocess directive to the preprocessor so that it calls the next preprocessor. It is the responsibility of the first preprocessor to call the second; this can then call a third, and so on. Preprocessors that are not written to allow this stack method can only be used as the last preprocessor in the stack.

To invoke several preprocessors, stack the directive:

   +---------------------------------------+
   V                                       |
>>----preprocess"name"-.----------------.--+---><
                       +-preproc-params-+

For information on writing preprocessors to be used in this way, see the topic Multiple Preprocessors.

Parent topic: Integrated Preprocessor Interface
Related reference
The COPY Statement
The REPLACE Statement
Related information
Multiple Preprocessors


Writing a Preprocessor

  • Writing a preprocessor - overview
  • Definition of the Interface Between the Compiler and a Preprocessor
  • Preprocessor Response Codes
  • Source Modification
  • Multiple Preprocessors
  • Considerations When Writing a Preprocessor
Parent topic: Integrated Preprocessor Interface


Writing a preprocessor - overview

Restriction: The Integrated Preprocessor is supported for native COBOL only.

This topic explains how to write an integrated preprocessor and describes the interface used to pass information between a preprocessor and the Compiler.

Although a preprocessor could be written in a language other than COBOL, the following description assumes that it is written in COBOL.

The Integrated Preprocessor Interface works on the simple concept that preprocessing is a form of editing. The preprocessor marks each line of the source code as:

  • Unchanged
  • Inserted - that is, as new lines
  • Modified - that is, old lines that are not to be compiled

When compiling a COBOL program, the compiler calls the preprocessor instead of directly reading the source file and receives the code line by line from the preprocessor.

For your preprocessor to function correctly during a background syntax check in the IDE, it must conform to the preprocessor stacking protocol detailed in the section Multiple Preprocessors.

The operation of the debugger depends on a mapping of each line of object code onto each line of source code. The marking of source lines described above allows this mapping to be valid even though the object code does not match the source code.

Important: The background parse feature requires a stacked preprocessor. If the preprocessor is not stacked there will be no real-time updating of errors in the editor views. Errors can also occur.

Users of non-stacked preprocessors should turn off background parsing in the Preferences dialog box by clicking Window > Preferences > Micro Focus > COBOL > Editor and deselecting Background parsing.

Testing a Preprocessor

The preprocessor program should be compiled in the same manner as any other program you want to debug.

After compiling your preprocessor program for debugging, you use the debugger as though you want to debug the Compiler itself, that is debug COBOL. You will not see the Compiler debugged, since it is not compiled for debugging, but you will see any programs it calls that have been compiled for debugging, such as your preprocessor.

When debugging preprocessed generated statements, which include WHEN / CATCH / ELSE / END-??? tokens, the debugger does not step on these tokens themselves, but rather the first statement afterwards. This is the case even if the preprocessor has explicitly asked for a verb step\stop; you can only step on actual verbs in preprocessed code.

Parent topic: Writing a Preprocessor


Definition of the Interface Between the Compiler and a Preprocessor

Note: The Integrated Preprocessor is supported for native COBOL only.

Preprocessor Parameters

Three parameters are passed across the interface:

mode-flag | Used to pass control information
buffer | Used for text information (source lines and filenames)
response | Used to indicate the type of source line in the buffer

Use the following data structure to pass these parameters:

 01 mode-flag      pic 9(2) comp-x.
 01 buffer         pic x(n).
 01 response.
   03 response-status    pic 9(2) comp-x.
   03 response-code-1    pic 9(4) comp-x.
   03 filler redefines response-code-1.
     05 filler             pic x.
     05 resp-main          pic 9(2) comp-x.
   03 response-code-2    pic 9(4) comp-x.
   03 filler redefines response-code-2.
     05 filler             pic x.
     05 resp-more          pic 9(2) comp-x.

The Initial Call

The initial call is made to the preprocessor at the point where the Compiler would normally open the source file. The mode-flag parameter is set to 0 and the name of the source file is placed in buffer. If the Compiler was able to locate the source file, the filename contains the full path and file extension. If it was not able to do so, the name is as specified on the command line. The preprocessor preserves the contents of the buffer in this initial call.

In addition, the initial call initiates a handshaking process so that the Compiler and preprocessor can determine their respective levels of support. This enables new functionality to be built into the preprocessor interface while at the same time ensuring that this new functionality is not made use of unless both the Compiler and preprocessor support it. The Compiler does not pass any information to the preprocessor unless it has been told that the preprocessor is able to process it; similarly the preprocessor should not make any requests of the Compiler unless it has been told that it can do so. The process has been designed so that older Compilers and preprocessors continue to work even though they do not take account of the handshaking process.

When the Compiler calls the preprocessor, response-code-2 is used to inform the preprocessor of its support level. When the preprocessor returns to the Compiler, it uses the same parameter for its support level. As features are added the support levels are incremented; each level includes the support in the levels before it. To ensure that old Compilers are supported, the value 8224 is a special case - it indicates that the parameter was not initialized and represents the "base level". Similarly, an old preprocessor that does not set a support level does not change the parameter value, so all values of 32767 or lower are treated as the "base level".

Features in the base levels are explained in the following sections. Features not in the base level are highlighted with a warning. The following is a summary:

Compiler support levels

response-code-2 | Feature
8224 | Base level
0 | response-code-1 contains length of buffer
1 | resp-main of 14 supported
2 | Compiler understands preprocessor support level; and tells the preprocessor to abort
3 | resp-main of 17 supported
4 | resp-main of 18 supported

Preprocessor support levels

response-code-2 | Feature
32767 or less | Base level
32768 | Compiler might tell the preprocessor to abort
32769 | Support for conditional compilation. Note: The preprocessor must accept and act on a MODE-FLAG value of 3 by returning source lines untouched and marked as original source lines. It must continue to do this while MODE-FLAG has this value.
Not base level: | The Compiler puts the length of buffer in response-code-1. The preprocessor can return source lines up to this length. If response-code-2 is 8224 then the preprocessor should assume the length is 80 bytes.

The preprocessor should open the file and return zero in response-status to indicate success, or 255 to indicate a failure.

The operating system command line contains any directives to the preprocessor, terminated by spaces. These directives are specified in the Compiler command line, directives files or $SET statements and follow the PREPROCESS directive itself.

The directives are used to pass information from the command line to the integrated preprocessor and are defined by the designer of the preprocessor. The preprocessor should not expect the directives it receives to be separated by only one space character. The command line format matches that of the PREPROCESS directive and each preprocessor directive (including the first) can be preceded by one or more spaces.

Subsequent Calls

Subsequent calls request a line of source code until the preprocessor indicates that the last line has been reached.

In these calls, the Compiler sets mode-flag to 1 and response-status to 0, except as documented in the topic Handling COPY Statements. The preprocessor returns information in buffer, resp-main and resp-more as defined in the next section.

If there is an error, response-status should be set to a nonzero value (the remaining fields might be left undefined).

The first byte of response-code-1 and response-code-2 are reserved for future use and must always be set to zero on return.

The simplest way to achieve this is to set response-code-1 and response-code-2 to zero before setting resp-main and resp-more.

If you wish to modify the source code, you should note that the original source code lines should always be passed back before their replacement line(s). In addition, lines that are continued over several lines of source code must be treated as one block; it is not possible to modify part of the logical line.

Not base level: If the Compiler sets mode-flag to 2 then it is about to terminate before the preprocessor indicates that the end of the source has been reached. On this call the preprocessor should perform any clean-up operations it needs to do (such as deleting temporary work files). If the preprocessor is stacked, that is it invokes other preprocessors, it should also call the next preprocessor with the same parameter values and then CANCEL that preprocessor.
Parent topic: Writing a Preprocessor


Preprocessor Response Codes

Restriction: The Integrated Preprocessor is supported for native COBOL only.

After the initial call to the preprocessor, subsequent calls return with one of the following:

  • Source lines, which might be marked as:
    • Unchanged
    • Old (to be treated as commented out)
    • New
    • COPY statements
  • With other requests, such as:
    • Increment an error count
    • Return a directive setting

The value in resp-main is used to signify what is being returned; additional information might be placed in resp-more and/or buffer. The values of resp-main are:

Value | Description
0 | The source file has been completely processed and there is no further input. buffer and resp-more are ignored.
1 | buffer contains a new line that was added by the preprocessor and which was not in the original source code. resp-more optionally contains the position of the verb in the original source line that is being replaced. The line added by the preprocessor must not be a comment.
2 | buffer contains a line in the original source code which is to be ignored by the Compiler. resp-more is ignored.
3 | buffer contains a line in the original source code which contains the start of a COPY statement that is about to be expanded by the preprocessor. resp-more contains the position of the statement on the line.
4 | buffer contains a line in the original source code which contains the continuation of a COPY statement. resp-more is ignored.
5 | buffer contains a warning message inserted by the preprocessor. This must have the format of a comment line (that is, the value "*" in the indicator area of the source line). resp-more is ignored.
6 | An unrecoverable error has occurred; this forces the Compiler to abort and enter the COBOL Editor. In such a case, a message of up to 70 characters might be written to buffer and this is displayed on the bottom line of the Editor. resp-more is ignored.
7 | An error has occurred; this forces the Compiler to increment its internal error count. All error classes might be specified by using resp-more. The contents of buffer are ignored.
8 | This value is generated by the CP Preprocessor.
9 | This value is used when the CP Preprocessor is in use.
10 | Identical to 11, below.
11 | buffer contains a new line added by the preprocessor which contains the start of a COPY statement that is about to be expanded by the preprocessor. It is used when the COPY statement is not unique on a line or the original text was not a COBOL COPY statement. resp-more contains the position of the COPY statement on the line.
12 | buffer contains a new line added by the preprocessor which contains the continuation of a COPY statement. resp-more is ignored.
13 | Causes the Compiler to return information about its directive settings. The required directive might optionally be placed in buffer; resp-more is ignored.
Not base level:14 | This value is similar to 10 and 11 above, except that it indicates that the original source contained -INC or ++INCLUDE.
Not base level:17 | An error has been detected. buffer contains a message that the Checker outputs.
Not base level:18

Buffer contains a data name to be marked as modified by the immediately preceding preprocessed line. The data name may be qualified and resp-more contains the column information for the reference.

IDE tooling will now reflect the reference in the same way as data names on lines not modified by the preprocessor.

Multiple references may be specified by returning a resp-main value of 18 multiple times.

32 | buffer contains a line from the original source code which has not been modified by the preprocessor.
33 - 64 | These values are generated by the CP preprocessor.
128 | The end of a copybook has been reached. buffer must be empty.
  • Inserting Source Lines
  • Generating Preprocessor Error Messages
  • Querying Directive Settings
  • Handling COPY Statements
Parent topic: Writing a Preprocessor
Related reference
The COPY Statement
The REPLACE Statement
Related information
CP Preprocessor


Inserting Source Lines

Note:

The Integrated Preprocessor is supported for native COBOL only.

When resp-main contains the value 1, resp-more is used to indicate the position in the original source of the replaced non-COBOL verb as follows.

Value | Description
nn | The number of the column containing the first character of the non-COBOL verb being replaced by the current line. The line(s) containing the non-COBOL verb would have previously been marked by returning the value of 2 in resp-main; if there was more than one line, the verb is assumed to be on the first of them.
0 | No verb replacement is taking place.
For example, if the original source contains:
   exec abc
   do something useful
   end-exec

and these three lines are replaced by:

  call abc_something_useful

then the value of nn gives the position of the EXEC statement.
Parent topic: Preprocessor Response Codes


Generating Preprocessor Error Messages

Note: The Integrated Preprocessor is supported for native COBOL only.

Not base level

If the preprocessor encounters an error when processing the source code it can return the text of a message to be output.

This message is displayed in the same way as other Compiler messages according to the WARNING and ERRQ directives, and it is also highlighted in the source code.

To generate an error, a preprocessor must pass through the source line in error. The error message is passed with the following settings:

resp-main | 17
resp-more | Value indicating the severity:
1 | Informational
2 | Warning
3 | Error
4 | Severe error
Value | Severity
buffer | The text of the message. If the message text starts with the string OFFSETnnn (case is important) and a space, the error at the position specified by nnn is flagged. nnn is a three byte numeric number. The string is not displayed as part of the message.
1 | Unrecoverable error
2 | Severe error
3 | Error
4 | Warning
5 | Informational
6 | Flag count

The function resp-main=17 should only be used once one or more user source lines have been returned to the Checker by the preprocessor.

Note: in some circumstances using this feature highlights errors later than normal. This happens when the Compiler is reading ahead in the source to look for continuation and so on. If the Compiler receives and processes an error request from a preprocessor, and then determines that the error was on a line before the read-ahead, the line flagged by the prerocessor is highlighted.

All levels

An older technique for handling error conditions is still available. This requires the preprocessor to handle the actual display of the error message and so is less well integrated. We do not recommend this technique.

If the preprocessor encounters an error when processing the source code, it can communicate this to the Compiler so that the error is treated as a syntax error. There are two ways to do this:

  • Set resp-main to the value 5 and place a comment line in buffer; the comment is inserted in the list file.
  • Set resp-main to the value 6; the Compiler terminates.

The value in resp-more specifies the column number in which the error was found. It is used when positioning the cursor on return to the Editor.

It is also possible to force the Compiler to increment its internal error counts in conjunction with one of the two operations described above. This is done by setting resp-main to the value 7 and specifying which error count is to be increased in resp-more. Possible values for resp-more are:

Value | Severity
1 | Unrecoverable error
2 | Severe error
3 | Error
4 | Warning
5 | Informational
6 | Flag count

Increasing the unrecoverable error count causes the Compiler to abort immediately. The contents of buffer are ignored.

It is the responsibility of the preprocessor to output error messages to the user before forcing the Compiler to either abort or increment the error counts. This should not be confused with the message that can be inserted in the list file which is for informational purposes only.

Parent topic: Preprocessor Response Codes


Querying Directive Settings

Note:

The Integrated Preprocessor is supported for native COBOL only.

When resp-main contains the value 13, buffer must contain either spaces or the name of a specific directive setting that is required. When the processor is next called, buffer contains the value of a directive setting. When the value 13 is first returned, the Compiler builds up a list of all of its directive settings and returns one value from it. Subsequent returns of this value return further values from this list. If a value other than 13 is returned at any point, further returns of value 13 cause the list to be generated again. The list of directives is generated in alphabetical order; once all directive settings have been returned, further calls yield spaces. If buffer contains spaces the first, or next, directive setting is returned; if buffer contains the name of a directive, the Compiler skips forward through its list to the specified directive. Only syntax-check phase directives are returned in this way.

Parent topic: Preprocessor Response Codes


Handling COPY Statements

Restriction: The Integrated Preprocessor is supported for native COBOL only.

If the preprocessor is not interested in the contents of a copybook, it can pass the COPY statement unmodified through to the Compiler, where it is expanded.

Only valid COBOL constructs can be passed in this way. Any non-COBOL constructs can be commented out and replaced by a valid COPY statement which the Compiler then expands.

In both of these cases, the preprocessor has no opportunity to read and process the copybook itself.

The Compiler expands all forms of COPY statement that it would expand with no preprocessor present, whether passed back as unchanged or modified lines. The following are supported:

  • Simple COPY statement
  • COPY ... REPLACING statements
  • COPY copy-filename OF/IN library-name
  • COPY statements spread over several lines
  • Nested COPY statements
  • ++INCLUDE
  • -INC

If the preprocessor does want to examine the copybook contents, it must either expand the copybook itself, or use the CP preprocessor. The contents of the copybook itself are returned to the Compiler in the same manner as the lines in the main source file; however, the COPY statement itself receives special handling.

In the simplest case, when the COPY statement is the only statement on one or more lines, and specifies the full filename (including the extension and path if necessary), the first of these lines is passed to the Compiler marked with resp-main set to 3 and resp-more set to the column number of the start of the COPY, and all subsequent lines are passed with resp-main set to 4.

If the location of the file specified in the COPY statement is resolved by adding a filename extension or path, or if the COPY is not unique on the line(s), or is not a regular COBOL COPY statement, it is necessary to comment out (mark with resp-main set to 2) all lines containing the COPY statement and then pass through all other lines as inserted. Inserted COPY statements that the preprocessor is expanding must conform to the normal syntax rules for COBOL, and be marked with:

  • resp-main set to 11 or 14
  • resp-more set to nn (where nn is the position of the start of the COPY statement) for the first line
  • resp-main set to 12 for all subsequent lines

For example, if the source contains:

01 item-a. copy "cpy-fil.cpy".

This is first returned with resp-main set to 2 to indicate that this is a line that is about to be replaced. On the next call, the preprocessor returns:

01 item-a.

with resp-main set to 1 to indicate that this is a replacement line. On the next call, the preprocessor returns:

copy "copy-fil.cpy".

This time, resp-main is set to 11 to indicate this is a replacement line containing the COPY statement alone. resp-more is set to 20, the position of the word COPY on the original source line.

Note that when a COPY statement is returned to the Compiler, whether to be expanded by the preprocessor or Compiler, the Compiler parses it and checks for REPLACING. This REPLACING affects all lines in this and nested copybooks. The name specified in this COPY statement is read and stored for use by the Debugger. It is strongly recommended that the name be enclosed in quotes so that no unwanted case folding occurs when reading the name as, on platforms where case is significant, the Debugger might not be able to locate the file.
Not base level: resp-main=14 is used when the original word was not a COBOL COPY statements, for example ++INCLUDE or -INC. Some Compiler directives can be specified in $SET statements before any COBOL source but not after. Such statements might follow ++INCLUDE but not COPY. Use of resp-main=14 allows a ++INCLUDE to be expanded whilst at the same time allowing such directives to be set subsequently.

Value 128 should only be used for resp-main when the preprocessor has finished expanding a copybook. If it is not, the Compiler aborts the compilation. The value 0 should be used at the end of the main source file.

COPY statements in Identification Division comment entries are not always expanded. If a preprocessor signals that it is about to expand a copybook (resp-main set to 3 or 11) at a point where this is not valid, the Compiler sets response-status to non-zero on the next call to the preprocessor. The preprocessor should abandon the copybook immediately and send the end-of-copybook marker (resp-main set to 128) as though the copybook were empty.

The CP preprocessor expands copybooks so that other preprocessors do not have to do so. It generates lines as documented above.

Parent topic: Preprocessor Response Codes
Related reference
The COPY Statement
The REPLACE Statement


Source Modification

Note:

The Integrated Preprocessor is supported for native COBOL only.

A number of COBOL commands exist to modify a source file. The REPLACE verb (ANSI'85 verb) is not supported by the Compiler when a preprocessor is active and must be handled by the preprocessor. The CP preprocessor returns information to other preprocessors about the effect of REPLACE.

Parent topic: Writing a Preprocessor
Related reference
The REPLACE Statement


Multiple Preprocessors

Note:

The Integrated Preprocessor is supported for native COBOL only.

Several preprocessors can be active simultaneously on the same source program. They are arranged in a stack so that the Compiler calls the top preprocessor in the stack, this preprocessor calls the next preprocessor and so on to the preprocessor at the bottom of the stack which actually reads the source code. Each line of source is then passed through every preprocessor in turn until it reaches the top of the stack and is passed to the Compiler. In order for this to work, the preprocessor must obey some additional rules.

The Compiler writes directives to the command line when it makes the initial call to a preprocessor. The preprocessor reads this command line and, if it finds a PREPROCESS directive, invokes the preprocessor named in it. It also passes any parameters following the directive to the invoked preprocessor by writing these in turn to the command line and continues the hand-shaking process described in this section.

As preprocessor directives to the Compiler are terminated by the ENDP directive or the end of the line, multiple PREPROCESS directives must all appear on the same line in a directives file.

The interface between two preprocessors is identical to that between the Compiler and preprocessor specified above, thus it is possible to use a stackable preprocessor in both stacked and unstacked situations. A preprocessor which has not been designed to be stackable must be stacked at the end of the stack where it is directly reading the source code.

If you are stacking another preprocessor on top of the CP preprocessor, to enable support for conditional compilation, it must support the following:

  • The preprocessor's handshaking support level needs to be increased to 32769.
  • The preprocessor must accept and act on a MODE-FLAG value of 3 by returning source lines untouched and marked as original source lines. It must continue to do this while MODE-FLAG has this value.

In most cases, preprocessors act on discrete sets of syntax and all produce valid COBOL syntax, so it is unlikely that more than one preprocessor will want to process a particular source line. However, it is possible that preprocessors in a stack represent language levels so that a source line is edited several times by the different preprocessors on its route through the stack to the Compiler. In this case, care must be taken to read the information in the response field so that the relationship between the source code and the code that finally reaches the Compiler is maintained. The order in which the stacking takes place should also be chosen carefully if code altered by one preprocessor is also to be successfully modified by a second preprocessor.

Parent topic: Writing a Preprocessor
Related reference
The COPY Statement
The REPLACE Statement


Considerations When Writing a Preprocessor

Note:

The Integrated Preprocessor is supported for native COBOL only.

Any change made to source code can conflict with either the user selected COBOL dialect or data names. With care, any potential problems can easily be avoided.

  • Conflicts with user selected COBOL dialect.

    If the user code conforms to a dialect that does not support features that the preprocessor needs to make use of, there are two issues to be overcome. Firstly, non-conforming code would be flagged; secondly the required reserved words might not be in the dictionary.

    In order to overcome the problem of flagging, no lines that are inserted by a preprocessor are ever flagged by the Compiler. To make all required reserved words available, a preprocessor could generate a $SET statement to specify, for example, the ANS85 directive.

    However, this would have some unwelcome side-effects: the behavior of some statements would be changed, and valid data names would be rejected as they would now be reserved words instead.

    A better technique would be to determine which words are actually needed and selectively add only these using the ADDRSV directive. For example, if only the reserved word FUNCTION is needed, it can be added using the ADDRSV(FUNCTION) directive. This, however, would still causes problems if the user code declared FUNCTION as a data name, and the best solution of all is to use the ADDSYN directive, and chose an alternative word to FUNCTION that is unlikely to be used by the user.

    For example, generate the directive ADDSYN "FUNCTION" = "PREPGEN--FUNCTION" and thereafter use PREPGEN--FUNCTION instead of FUNCTION when generating code.

    Note:

    Using the ADDSYN technique might confuse any preprocessors that subsequently process the source.

  • Conflicts with data names.

    If a preprocessor needs to create data for its own use, it should chose names that are unlikely to conflict with user chosen names. As in the case above, selecting a name like PREPGEN--USERID is unlikely to conflict with a user selected name, but USERID alone might well cause problems.

  • UNIX environments

    UNIX is case-sensitive. In your call statements, you need to use the correct case. For example, a CALL (XXX) statement results in a RTS173 error if the program is named xxx.cbl.

Parent topic: Writing a Preprocessor


CP Preprocessor

Note: The Integrated Preprocessor is supported for native COBOL only.

The CP preprocessor is designed to be used as a stacked preprocessor. It reads and expands source files (including copybooks), plus it returns additional information to the other preprocessors in the stack about the effect of REPLACE and REPLACING. It thus removes these quite complex functions from other preprocessors.

The CP preprocessor has the following restrictions:

  • It only recognizes normal COBOL tokens and COPY statements
  • It does not show the effect of BASIS

For the CP preprocessor to perform its function and pass expanded source files to another preprocessor (such as COBSQL) the specification of CP must be nested within the specification of the other preprocessor. For example:

P(COBSQL) END-COBSQL P(CP) COMP5=YES ENDP
  • Copybook Expansion
  • REPLACE Notification
  • CP Directives
Parent topic: Integrated Preprocessor Interface
Related concepts
Using the CP Preprocessor to Expand Copybooks
Related information
Preprocessor Response Codes
COBOL Preprocessor Error Messages
FLAG
MF, MFLEVEL
The REPLACE Statement
The COPY Statement


Copybook Expansion

Restriction: The Integrated Preprocessor is supported for native COBOL only.

When the CP preprocessor encounters a COPY statement it marks the source lines as documented in the topic Handling COPY Statements, and reads through the copybook. It locates the copybooks using the same pathnames and file extensions as the Compiler would.

If a copybook cannot be located, the CP preprocessor comments out the COPY statement and generates appropriate error messages. If there is an error in parsing the statement, the preprocessor ignores the statement and carries on parsing tokens from the point of the error. If other preprocessors receive an unmodified COPY statement they can assume that the CP preprocessor was unable to handle it; they should leave it and let the Compiler generate an error message.

Parent topic: CP Preprocessor


REPLACE Notification

Note:

The Integrated Preprocessor is supported for native COBOL only.

So that other preprocessors are able to get a view of the source files as the Compiler would after the effect of REPLACE and REPLACING, the preprocessor returns additional lines as documented here. Note, however, that the Compiler still performs this REPLACING itself except as noted below. The additional lines are passed for information only.

If the preprocessor ever detects that a line will be modified, it will add 32 to the value of resp-main it returns. The line or lines thus marked will be followed by one or more lines marked with the value of 8 in resp-main, containing what would be in the line after it was modified. As these changes are for information only, other preprocessors receiving the lines should pass these values back out again for any other preprocessors in the stack; when the Compiler receives lines marked with values in the range 33 to 64 it subtracts 32, and it ignores lines marked with an 8.

If a preprocessor wishes to modify a line affected in this way, it should do so as normal, however it should mark the new line with a 9 rather than a 1 to inform the Compiler that this new, inserted, line does not need to be tested for the effect of REPLACE or REPLACING.

Parent topic: CP Preprocessor
Related reference
The COPY Statement
The REPLACE Statement


CP Directives

Note: The Integrated Preprocessor is supported for native COBOL only.

The CP preprocessor accepts a number of directives. In order to keep the command line short, these exist in an abbreviated form in addition to the full name. After looking at the command line in the usual way, CP also looks at the environment variable CPDIR for directives.

  • ANYCOPYCASE
    Attempts additional case-sensitive searches for copybooks when a normal search method fails.
  • CONFIRM, C
    Specifies whether directives are to be shown on the screen if accepted.
  • EXEC-IGNORE-TRAILING
    Causes trailing text after an EXEC INCLUDE .. END-EXEC statement in the data division to be ignored.
  • EXECPERIOD
    Controls whether a period following END-EXEC is treated as part of that statement when there are separating spaces, lines or comments.
  • LIMITED-SEARCH, LS
    Limits searches for copybooks to the directories specified by the COPCPY environment variable. By using this directive, and making a careful choice of both directories in the COBCPY environment variable and file extensions in the COPYEXT directive, the number of file searches can be greatly reduced.
  • PREPROCESS, P
    Stacks another preprocessor (that is, specifies that the source input to this preprocessor is to come from another preprocessor rather than the source file itself).
  • SQL, S
    Specifies whether EXEC SQL INCLUDE is to be treated as a COPY statement.
  • TRACE, T
    Specifies whether to create a trace file, and optionally specifies the name of the file to be used. If the filename is omitted, it is created as progname.cpt, where progname is the basename of the main source file.
  • WARNINGS, WARNING, W
    Specifies whether warnings about directive settings are to be shown on screen
  • SY
    Reserved for use with COBSQL; this directive should only be used as documented in the chapter COBSQL in your Database Access book.
Parent topic: CP Preprocessor
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


ANYCOPYCASE

Attempts additional case-sensitive searches for copybooks when a normal search method fails.
Restriction: The Integrated Preprocessor is supported for native COBOL only.

Syntax:

>>------.----.--ANYCOPYCASE-------><
        +-NO-+

Properties:

Default: NOANYCOPYCASE

Comments:

If the normal search method for a copybook has failed, then with this option turned on CP will retry with the name specified in the source converted to uppercase. If still no match is found, then it will try a further time with the name converted to lower-case. The name will be tried with the full usual search methodology. Note that the case conversion affects precisely what is specified in the source, so will include paths and extensions if specified there; however, it will not affect COBCPY paths or COPYEXT directive values, where the specified case will always be preserved.

Parent topic: CP Directives


CONFIRM, C

Specifies whether directives are to be shown on the screen if accepted.

Syntax:

Note: The Integrated Preprocessor is supported for native COBOL only.
>>-----.----.--CONFIRM---------------><
       +-NO-+

Properties:

Default: NOCONFIRM
Parent topic: CP Directives
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


EXEC-IGNORE-TRAILING

Causes trailing text after an EXEC INCLUDE .. END-EXEC statement in the data division to be ignored.
Restriction: The Integrated Preprocessor is supported for native COBOL only.

Syntax:

>>------.----.--EXEC-IGNORE-TRAILING-------><
        +-NO-+

Properties:

Default: NOEXEC-IGNORE-TRAILING
Parent topic: CP Directives


EXECPERIOD

Controls whether a period following END-EXEC is treated as part of that statement when there are separating spaces, lines or comments.
Restriction: The Integrated Preprocessor is supported for native COBOL only.

Syntax:

>>---EXECPERIOD"arg"---><

Parameters:

arg
arg must be one of:
INCLUDE
Always includes the period as part of the EXEC statement.
EXCLUDE
Always excludes the period from the EXEC statement.
SMART
Includes the period for EXECs in the DATA DIVISION. Excludes the period for EXECs in the PROCEDURE DIVISION.

Properties:

Default: EXECPERIOD"SMART"

Comments:

Periods that immediately follow END-EXEC are always treated as part of the EXEC statement.

An example of when this directive is important is when a paragraph or section header follows the EXEC statement, as the header requires a preceding terminating period.

Parent topic: CP Directives


LIMITED-SEARCH, LS

Limits searches for copybooks to the directories specified by the COPCPY environment variable. By using this directive, and making a careful choice of both directories in the COBCPY environment variable and file extensions in the COPYEXT directive, the number of file searches can be greatly reduced.

Syntax:

Restriction: The Integrated Preprocessor is supported for native COBOL only.
>>------.----.--LIMITED-SEARCH-------><
        +-NO-+

Properties:

Default: NOLIMITED-SEARCH

Comments:

This directive limits searches for copybooks to the directories specified by the COPCPY environment variable.

This can reduce compilation time. If the directive is set:

  • Copybooks are searched for in the directories specified by COBCPY, omitting the directory where the source is located
  • The copybook extension specified by the OSEXT directive is not used in the search (any extensions specified by COPYEXT are used, however)
Parent topic: CP Directives
Related information
OSEXT
MF, MFLEVEL
COPYEXT
Copybook Location


PREPROCESS, P

Stacks another preprocessor (that is, specifies that the source input to this preprocessor is to come from another preprocessor rather than the source file itself).

Syntax:

Note:

The Integrated Preprocessor is supported for native COBOL only.

>>--.--PREPROCESS"name"-.----------------.--.--><
    |                   +-preproc-params-+  |
    +-NO-PREPROCESS-------------------------+

Parameters:

name | The name of the preprocessor
preproc-params | One or more of the optional preprocessor parameters

Properties:

Default: NOPREPROCESS
Parent topic: CP Directives
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


SQL, S

Specifies whether EXEC SQL INCLUDE is to be treated as a COPY statement.

Syntax:

Note:

The Integrated Preprocessor is supported for native COBOL only.

>>-----.----.--SQL-------------------><
       +-NO-+

Properties:

Default: SQL
Parent topic: CP Directives
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


TRACE, T

Specifies whether to create a trace file, and optionally specifies the name of the file to be used. If the filename is omitted, it is created as progname.cpt, where progname is the basename of the main source file.

Syntax:

Note:

The Integrated Preprocessor is supported for native COBOL only.

>>--.--TRACE----.-"filename"--.--.---><
    |           +-------------+  |
    +--NO--TRACE-----------------+

Properties:

Default: NOTRACE
Parent topic: CP Directives
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


WARNINGS, WARNING, W

Specifies whether warnings about directive settings are to be shown on screen

Syntax:

Note:

The Integrated Preprocessor is supported for native COBOL only.

>>-----.----.--WARNINGS--------------><
       +-NO-+

Properties:

Default: WARNING
Parent topic: CP Directives
Related information
FLAG
MF, MFLEVEL
The COPY Statement
The REPLACE Statement
COBOL Preprocessor Error Messages


SY

Reserved for use with COBSQL; this directive should only be used as documented in the chapter COBSQL in your Database Access book.
Note: The Integrated Preprocessor is supported for native COBOL only.
Parent topic: CP Directives


Java Artifacts

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Micro Focus Resource Adapters
Parent topic: General Reference


Micro Focus Resource Adapters

  • COBOL Resource Adapter
Parent topic: Java Artifacts


COBOL Resource Adapter

  • COBOL Connector Class Usage Scenarios
    Describes transactional and non-transactional scenarios for using J2EE connectors between EJBs and Enterprise Server.
  • COBOL Resource Adapter Utility
    Describes the COBOL Resource Adapter utility, which can be used to change certain parameter values for Micro Focus COBOL resource adapters.
  • NullSearch Utility
    Describes the NullSearch utility, used to identify null-value fields in custom record classes.
Parent topic: Micro Focus Resource Adapters


COBOL Connector Class Usage Scenarios

The following are examples of using J2EE connectors between EJBs and Enterprise Server in both transactional and non-transactional scenarios:

Scenario 1: Non-transactional
EJB Communication | Stateless
Enterprise Server Communication | Stateless
Use
Invoke a COBOL procedure where there is no state to be maintained for the EJB or the SEP between it and the next COBOL procedure invocation.
Example
getInvoiceDetails(String invoiceNumber) returns just the invoice details for the specified string. Multiple calls to this procedure do not require state.
Implementation
During EJB generation from the IMTK, use JNDI to get an EJB based on the service interface name. Internally this calls the Resource Adapter, which then calls COBOL.
Scenario 2: Non-transactional
EJB Communication | Stateful
Enterprise Server Communication | Stateful
Use
Invoke one or more COBOL procedures where the state must be maintained in the EJB and the SEP, meaning that each invocation accessed the same SEP. You can also convert a non-transactional stateful invocation into a stateless invocation by storing the state for each invocation in a database rather than in the program. The application design dictates whether or not it is necessary to maintain the state in the program or if it can also be maintained in a database.
Example
When you add an item to a shopping cart, it places the item into the cart with other items placed there previously. When you purchase all items in the shopping cart, this completes the sale. In this scenario, you can keep all items in the shopping cart in working storage and use it across multiple invocations.
Implementation
Invoke a COBOL procedure where there is no state to be maintained for the EJB or the SEP between it and the next COBOL procedure invocation. However, after using the stateful bean, the end user must invoke a remove procedure to dispose of the transient SEP created exclusively to interact with the EJB, and remove the stateful EJB from the container.
Scenario 3: Transactional
EJB Communication | Stateful
Enterprise Server Communication | Stateless
Use
Use this scenario when you want transactional interaction without extending the SEP life beyond the xa_commit/xa_rollback. The SEP is automatically disposed of after xa_commit/xa_rollback.
Implementation
Remove the EJB for every transaction and create a new one for the next transaction.
Scenario 4: Transactional
EJB Communication | Stateful
Enterprise Server Communication | Stateful
Use
Use this scenario when you want transactional interaction that keeps the SEP life beyond the xa_commit/xa_rollback.
Implementation
Remove the EJB after all work is completed.
Parent topic: COBOL Resource Adapter


COBOL Resource Adapter Utility

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

The COBOL Resource Adapter utility enables you to change the values of the following parameters for any Micro Focus COBOL resource adapter that uses them:

  • ServerHost
  • ServerPort
  • Trace
  • SecureGUID
  • ReadTimeoutInSeconds
  • EnterpriseServerSocketCloseDueToInactivity

The utility is executed by a shell script, ravaluesupdater, and runs from the command line. The ravaluesupdater utility file is located by default in your $COBDIR/javaee directory.

To run the COBOL Resource Adapter utility

  1. Open a terminal window.
  2. Change to the $COBDIR/javaee directory.
  3. Enter bash ravaluesupdater.sh.
  4. Follow the prompts to change appropriate parameter values.
Parent topic: COBOL Resource Adapter


NullSearch Utility

The NullSearch utility identifies null-value fields in custom record classes passed to Enterprise Server at runtime. Null-value fields are invalid, preventing the runtime from executing.

Scenario for using NullSearch

If even one null-value field in a custom record mapping is passed to Enterprise Server, the run-time returns the following generic error message:

Sorry cannot have a null as value. Run the NullSearch utility.

The NullSearch utility identifies which fields have a null value, and can be especially helpful when your custom record mapping contains a large number of fields. For example, suppose customer record A has an inner class B that contains an array of 1000 elements of type String. One of those String elements has a value of null, triggering the above-referenced error message at run time. Without the NullSearch utility, you would have to manually identify the offending field.

To use the NullSearch utility

We provide the NullSearch utility as a Java .jar file named nullSearch.jar, which is called from a Java program. nullSearch.jar is located by default in your $COBDIR/javaee directory.

To use nullSearch.jar:

  1. Add nullSearch.jar to your system classpath environment variable, and depending on which class is extended by the custom record you want to search, also add the appropriate .jar file as cited below in addition to nullSearch.jar:
    Extended Class | .jar File
    com.microfocus.cobol.connector.cci.CustomRecord | mfejblib.jar
    com.microfocus.cobol.lang.CustomRecord | mfcobolpure.jar
  2. In a Java program, create a com.microfocus.tools.NullSearch object that calls the parseFields method. In the following example Java program, custom_record is the name of your custom record:
    public class testSearch {
        public static void main(String[] args){
                custom_record field = new custom_record();
                Object[] params = field.getParameters();
                com.microfocus.tools.NullSearch search = new com.mf.NullSearch();
                search.parseFields(params);
        }
}
  3. Execute the java program.
  4. Search the output for the keyword null.
    The output is organized as a list of enumerated fields identified by class. In the following example, the null field 1.0.2 is identified as the second field in class classA$classE, subclass [LclassF$classG$classH;:
    Field 0 is: classA$classB
Field 0.20 is: classA$classB$classC
Field 0.24 is: classA$classB$classD
Field 1 is: classA$classE
Field 1.0 is: [LclassF$classG$classH;
Field 1.0.2 is null
Parent topic: COBOL Resource Adapter


Language Environment (LE) Support

Language environment is a set of standard callable routines and run-time options that can be used in any application that is written in a programming language that supports LE. It is intended to facilitate the development of mixed-language applications.

This system emulates a subset of LE for COBOL. See Callable Services for details of this subset. For a full description of LE, see the IBM Language Environment Programming Reference and IBM Language Environment Programming Guide.

  • Enable Language Environment (LE) Support
  • LE Callable Services
  • LE Run-Time Options
  • LE Error Conditions
  • LE Run-Time Options Error Messages
  • LE Country Codes
Parent topic: General Reference


Enable Language Environment (LE) Support

You enable Language Environment (LE) support by using either the INITCALL"MFLEINIT" Compiler directive, or by adding a call to MFLEINIT in your code. The method used depends on how you intend to use the support.

Enterprise Server (Excluding JCL)

For all other applications running in Enterprise Server, set the environment variable ES_LE370_SUPPORT=Y.

JVM Managed COBOL

The Language Environment utilities are also available in managed code applications. To use them, include the mfle370.jar file on the classpath.
  • On Windows:
    • For 32-bit environments use the mfle370.jar file located at $COBDIR\bin.
    • For 64-bit environments you must use a 64-bit JVM. The mfle370.jar file is located at $COBDIR\bin64.
  • On UNIX:
    • For 32-bit environments use the mfle370.jar file located at $COBDIR/lib.
    • For 64-bit environments you must use a 64-bit JVM. The mfle370_64.jar file is located at $COBDIR/lib.
In your JVM COBOL program, include the Compiler option ILUSING"com.microfocus.le370". For a Java program include the statement import com.microfocus.le370.*;.
Parent topic: Language Environment (LE) Support


LE Callable Services

  • Bit Manipulation Services
  • Condition-Handling Services
  • Date and Time Services
  • Dynamic-Storage Services
  • Dynamic File Allocation Services
  • General Services
  • Initialization and Termination Services
  • Locale Services
  • Math Services
  • Message-Handling Services
  • National Locale Support Services
Parent topic: Language Environment (LE) Support


Bit Manipulation Services

The following table shows the LE bit manipulation services that are supported by this COBOL system.

Routine | Description | Supported?
CEESICLR | Bit clear | Yes
CEESISET | Bit set | Yes
CEESISHF | Bit shift | Yes
CEESITST | Bit test | Yes
Note:

The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.

Parent topic: LE Callable Services


Condition-Handling Services

The following table shows the LE condition-handling callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEE3CIB | Return pointer to Condition Information Block | No *
CEE3GRN | Get name of routine that incurred condition | No *
CEE3GRO | Get offset of condition | No *
CEE3SPM | Query/modify LE/370 Hardware Condition Enablement | No *
CEE3SRP | Set resume point | No *
CEEDCOD | Decompose a condition token | Yes
CEEGPID | Retrieve the LE/370 version and platform ID | Yes
CEEGQDT | Retrieve q_data_token | No *
CEEHDLR | Register user-written condition handler | No *
CEEHDLU | Unregister user-written condition handler | No *
CEEITOK | Return initial condition token | No *
CEEMRCE | Move resume cursor explicit | No *
CEEMRCR | Move resume cursor | No *
CEENCOD | Construct a condition token | Yes
CEESGL | Signal a condition | No *
Note:
  • Calls to unsupported routines marked by '*' are accepted but no action occurs. In the FEED_BACK condition (FC) code, the severity is set to 4, the message number to 9999, and the facility-ID to MFX.
  • Calls to unsupported routines marked by '**' are not accepted and if used in a COBOL program result in the fatal run-time system error 173 ("Called program file not found in drive/directory").
Parent topic: LE Callable Services


Date and Time Services

The following table shows the LE date and time callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEECBLDY | Convert date to COBOL Lilian format | Yes
CEEDATE | Convert Lilian date to character format | Yes
CEEDATM | Convert seconds to a character timestamp | Yes
CEEDAYS | Convert date to Lilian format | Yes
CEEDYWK | Calculate day of week from Lilian date | Yes
CEEGMT | Get current Greenwich Mean Time (GMT) | Yes
CEEGMTO | Get difference between GMT and local time | Yes
CEEISEC | Convert integers to seconds | Yes
CEELOCT | Get the current local date or time | Yes
CEEQCEN | Get the century window | Yes
CEESCEN | Set the century window | Yes
CEESECI | Convert seconds to integers | Yes
CEESECS | Convert timestamp to number of seconds | Yes
CEEUTC | Get Coordinated Universal Time (alias of CEEGMT) | Yes
Note:

The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.

Parent topic: LE Callable Services


Dynamic-Storage Services

The following table shows the LE dynamic-storage callable services that are supported by this COBOL system

Routine | Description | Supported?
CEE3RPH | Set report heading | No *
CEECRHP | Create new additional heap | Yes
CEECZST | Reallocate (change size of) storage | Yes
CEEDSHP | Discard heap | Yes
CEEFRST | Free heap storage | Yes
CEEGTST | Get heap storage | Yes
Note:
  • Calls to unsupported routines marked by '*' are accepted but no action occurs. In the FEED_BACK condition (FC) code, the severity is set to 4, the message number to 9999, and the facility-ID to MFX.
  • The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.
Parent topic: LE Callable Services


Dynamic File Allocation Services

The following table shows the LE dynamic file allocation services that are supported by this COBOL system.

Routine | Description | Supported?
PUTENV | Dynamically allocate a missing DD | Yes
SETENV | Dynamically allocate a missing DD | Yes
Note:
  • The optional parameters (such as SHR, NEW, OLD. LRECL and DSORG) are supported to the same level they are supported for the TSO ALLOCATE command.
  • If you use PUTENV or SETENV with parameters that are not compatible with the TSO ALLOCATE command, the call is rejected and the return code is set to a non-zero value.
  • You must specify the entry point "SETENV" in uppercase characters on Unix platforms. This is to avoid a clash with the "setenv" OS API of the platform which is in lowercase.
Parent topic: LE Callable Services


General Services

The following table shows the LE general callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEE3DMP | Generate dump | No *
CEE3PRM | Query parameter string | Yes
CEE3USR | Set/query user area fields | Yes
CEERAN0 | Calculate uniform random numbers | Yes
CEETDLI | Invoke IMS | Yes
CEETEST | Invoke debug tool | No *
Note:
  • Calls to unsupported routines marked by '*' are accepted but no action occurs. In the FEED_BACK condition (FC) code, the severity is set to 4, the message number to 9999, and the facility-ID to MFX.
  • Calls to unsupported routines marked by '**' are not accepted and if used in a COBOL program result in the fatal run-time system error 173 ("Called program file not found in drive/directory").
  • The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.
Parent topic: LE Callable Services


Initialization and Termination Services

The following table shows the LE initialization and termination callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEE3ABD | Terminate enclave with an abend Note: For programs running under JCL, you can also use the equivalent CALL "ILBOABNO" using abend-code syntax, which does not require LE Support to be enabled. | Yes
CEE3GRC | Get the enclave return code | No *
CEE3SRC | Set the enclave return code | No *
Note:
  • Calls to unsupported routines marked by '*' are accepted but no action occurs. In the FEED_BACK condition (FC) code, the severity is set to 4, the message number to 9999, and the facility-ID to MFX.
  • The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system
Parent topic: LE Callable Services


Locale Services

The following table shows the LE locale callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEEFMON | Format monetary string | No **
CEEFTDS | Format time and date into a character string | No **
CEELCNV | Query locale numeric conventions | No **
CEEQDTC | Query locale date and time format | No **
CEEQRYL | Query the active locale environment | No **
CEESCOL | Compare collation weights of two strings | No **
CEESETL | Set locale operating environment | No **
CEESTXF | Transform strong characters into collation weights | No **
Note:

Calls to unsupported routines marked by '**' are not accepted and if used in a COBOL program result in the fatal run-time system error 173 ("Called program file not found in drive/directory").

Parent topic: LE Callable Services


Math Services

The following table shows the LE math callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEESxABS | Absolute value |
 | CEESDABS | 64-bit double floating-point number | Yes
 | CEESEABS | 64-bit double floating-point complex number | No **
 | CEESIABS | 32-bit binary integer | Yes
 | CEESQABS | 128-bit extended floating-point number | No **
 | CEESRABS | 128-bit extended floating-point complex number | No **
 | CEESSABS | 32-bit single floating-point number | Yes
 | CEESTABS | 32-bit single floating-point complex number | No **
CEESxACS | Arccosine |
 | CEESDACS | 64-bit double floating-point number | Yes
 | CEESQACS | 128-bit extended floating-point number | No **
 | CEESSACS | 32-bit single floating-point number | Yes
 | CEESDASN | 64-bit double floating-point number | Yes
 | CEESQASN | 128-bit extended floating-point number | No **
 | CEESSASN | 32-bit single floating-point number | Yes
CEESxATH | Hyperbolic arctangent |
 | CEESDATH | 64-bit double floating-point number | Yes
 | CEESEATH | 64-bit double floating-point complex number | No **
 | CEESQATH | 128-bit extended floating-point number | No **
 | CEESRATH | 128-bit extended floating-point complex number | No **
 | CEESSATH | 32-bit single floating-point number | Yes
 | CEESTATH | 32-bit single floating-point complex number | No **
CEESxATN | Arctangent |
 | CEESDATN | 64-bit double floating-point number | Yes
 | CEESEATN | 64-bit double floating-point complex number | No **
 | CEESQATN | 128-bit extended floating-point number | No **
 | CEESRATN | 128-bit extended floating-point complex number | No **
 | CEESSATN | 32-bit single floating-point number | Yes
 | CEESTATN | 32-bit single floating-point complex number | No **
CEESxAT2 | Arctangent of two arguments |
 | CEESDAT2 | 64-bit double floating-point number | Yes
 | CEESQAT2 | 128-bit extended floating-point number | No **
 | CEESSAT2 | 32-bit single floating-point number | Yes
CEESxCOS | Cosine |
 | CEESDCOS | 64-bit double floating-point number | Yes
 | CEESECOS | 64-bit double floating-point complex number | No **
 | CEESQCOS | 128-bit extended floating-point number | No **
 | CEESRCOS | 128-bit extended floating-point complex number | No **
 | CEESSCOS | 32-bit single floating-point number | Yes
 | CEESTCOS | 32-bit single floating-point complex number | No **
CEESxCSH | Hyperbolic cosine |
 | CEESDCSH | 64-bit double floating-point number | Yes
 | CEESECSH | 64-bit double floating-point complex number | No **
 | CEESQCSH | 128-bit extended floating-point number | No **
 | CEESRCSH | 128-bit extended floating-point complex number | No **
 | CEESSCSH | 32-bit single floating-point number | Yes
 | CEESTCSH | 32-bit single floating-point complex number | No **
CEESxCTN | Cotangent |
 | CEESDCTN | 64-bit double floating-point number | Yes
 | CEESQCTN | 128-bit extended floating-point number | No **
 | CEESSCTN | 32-bit single floating-point number | Yes
 | CEESDDIM | 64-bit double floating-point number | Yes
 | CEESIDIM | 32-bit binary integer | Yes
 | CEESQDIM | 128-bit extended floating-point number | No **
 | CEESSDIM | 32-bit single floating-point number | Yes
CEESxDVD | Division | No **
CEESxERC | Error function complement | No **
CEESxERF | Error function | No **
 | CEESDEXP | 64-bit double floating-point number | Yes
 | CEESEEXP | 64-bit double floating-point complex number | No **
 | CEESQEXP | 128-bit extended floating-point number | No **
 | CEESREXP | 128-bit extended floating-point complex number | No **
 | CEESSEXP | 32-bit single floating-point number | Yes
 | CEESTEXP | 32-bit single floating-point complex number | No **
CEESxGMA | Gamma function | No **
CEESxIMG | Imaginary part of complex | No **
CEESxINT | Truncation |
 | CEESQINT | 128-bit extended floating-point number | No **
 | CEESSINT | 32-bit single floating-point number | Yes
 | CEESDINT | 64-bit double floating-point number | Yes
CEESxLG1 | Logarithm base 10 |
 | CEESDLG1 | 64-bit double floating-point number | Yes
 | CEESQLG1 | 128-bit extended floating-point number | No **
 | CEESSLG1 | 32-bit single floating-point number | Yes
CEESxLG2 | Logarithm base 2 |
 | CEESDLG2 | 64-bit double floating-point number | Yes
 | CEESQLG2 | 128-bit extended floating-point number | No **
 | CEESSLG2 | 32-bit single floating-point number | Yes
CEESxLOG | Logarithm base e |
 | CEESDLOG | 64-bit double floating-point number | Yes
 | CEESELOG | 64-bit double floating-point complex number | No **
 | CEESQLOG | 128-bit extended floating-point number | No **
 | CEESRLOG | 128-bit extended floating-point complex number | No **
 | CEESSLOG | 32-bit single floating-point number | Yes
 | CEESTLOG | 32-bit single floating-point complex number | No **
CEESxMOD | Modular arithmetic |
 | CEESDMOD | 64-bit double floating-point number | Yes
 | CEESIMOD | 32-bit binary integer | Yes
 | CEESQMOD | 128-bit extended floating-point number | No **
 | CEESSMOD | 32-bit single floating-point number | Yes
CEESxNIN | Nearest integer | Yes
CEESxNWN | Nearest whole number | Yes
 | CEESDSGN | 64-bit double floating-point number | Yes
 | CEESISGN | 32-bit binary integer | Yes
 | CEESQSGN | 128-bit extended floating-point number | No **
 | CEESSSGN | 32-bit single floating-point number | Yes
CEESxSIN | Sine |
 | CEESDSIN | 64-bit double floating-point number | Yes
 | CEESESIN | 64-bit double floating-point complex number | No **
 | CEESQSIN | 128-bit extended floating-point number | No **
 | CEESRSIN | 128-bit extended floating-point complex number | No **
 | CEESSSIN | 32-bit single floating-point number | Yes
 | CEESTSIN | 32-bit single floating-point complex number | No **
CEESxSNH | Hyperbolic sine |
 | CEESDSNH | 64-bit double floating-point number | Yes
 | CEESESNH | 64-bit double floating-point complex number | No **
 | CEESQSNH | 128-bit extended floating-point number | No **
 | CEESRSNH | 128-bit extended floating-point complex number | No **
 | CEESSSNH | 32-bit single floating-point number | Yes
 | CEESTSNH | 32-bit single floating-point complex number | No **
CEESxSQT | Square root |
 | CEESDSQT | 64-bit double floating-point number | Yes
 | CEESESQT | 64-bit double floating-point complex number | No **
 | CEESQSQT | 128-bit extended floating-point number | No **
 | CEESRSQT | 128-bit extended floating-point complex number | No **
 | CEESSSQT | 32-bit single floating-point number | Yes
 | CEESTSQT | 32-bit single floating-point complex number | No **
 | CEESDTAN | 64-bit double floating-point number | Yes
 | CEESETAN | 64-bit double floating-point complex number | No **
 | CEESQTAN | 128-bit extended floating-point number | No **
 | CEESRTAN | 128-bit extended floating-point complex number | No **
 | CEESSTAN | 32-bit single floating-point number | Yes
 | CEESTTAN | 32-bit single floating-point complex number | No **
CEESxTNH | Hyperbolic tangent |
 | CEESDTNH | 64-bit double floating-point number | Yes
 | CEESETNH | 64-bit double floating-point complex number | No **
 | CEESQTNH | 128-bit extended floating-point number | No **
 | CEESRTNH | 128-bit extended floating-point complex number | No **
 | CEESSTNH | 32-bit single floating-point number | Yes
 | CEESTTNH | 32-bit single floating-point complex number | No **
CEESxXPx | Exponential (**) |
 | CEESDXPD | 64-bit double floating-point raised to a 64-bit double floating-point | Yes
 | CEESEXPE | 64-bit double floating-point complex raised to a 64-bit double floating-point complex | No **
 | CEESDXPI | 64-bit double floating-point number raised to a 32-bit binary integer | Yes
 | CEESEXPI | 64-bit double floating-point complex number raised to a 32-bit binary integer | No **
 | CEESIXPI | 32-bit binary integer raised to a 32-bit binary integer | Yes
 | CEESQXPI | 128-bit extended floating-point number raised to a 32-bit binary integer | No **
 | CEESRXPI | 128-bit extended floating-point complex number raised to a 32-bit binary integer | No **
 | CEESSXPI | 32-bit single floating-point number raised to a 32-bit binary integer | Yes
 | CEESTXPI | 32-bit single floating-point complex number raised to a 32-bit binary integer | No **
 | CEESRXPR | 128-bit extended floating-point complex raised to a 128-bit extended floating-point complex | No **
 | CEESQXPQ | 128-bit extended floating-point raised to a 128-bit extended floating-point | No **
 | CEESTXPT | 32-bit single floating-point complex raised to a 32-bit single floating-point complex | No **
 | CEESSXPS | 32-bit single floating-pointing point raised to a 32-bit single floating-point | Yes
Note:

Calls to unsupported routines marked by '**' are not accepted and if used in a COBOL program result in the fatal run-time system error 173 ("Called program file not found in drive/directory").

Parent topic: LE Callable Services


Message-Handling Services

The following table shows the LE message-handling callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEECMI | Store and load message-insert data | No *
CEEMGET | Get a message | No *
CEEMOUT | Dispatch a message | Yes
CEEMSG | Get, format, and dispatch a message | No *
Note:
  • Calls to unsupported routines marked by '*' are accepted but no action occurs. In the FEED_BACK condition (FC) code, the severity is set to 4, the message number to 9999, and the facility-ID to MFX.
  • The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.
Parent topic: LE Callable Services


National Locale Support Services

The following table shows the LE national locale support callable services that are supported by this COBOL system.

Routine | Description | Supported?
CEE3CTY | Set/query default country | Yes
CEE3LNG | Set/query national language | Yes
CEE3MCS | Get default currency symbol | Yes
CEE3MDS | Get default decimal separator | Yes
CEE3MTS | Get default thousands separator | Yes
CEEFMDA | Get default date format | Yes
CEEFMDT | Get default date and time format | Yes
CEEFMTM | Get default time format | Yes
Note: The FLGS data item in the FEED_BACK condition (FC) token is not set or used by this COBOL system.
Parent topic: LE Callable Services


LE Run-Time Options

  • Supported LE Run-time Options
  • Unsupported LE Run-time Options
  • Specifying LE Run-time Options
Parent topic: Language Environment (LE) Support


Supported LE Run-time Options

The following table shows the LE run-time options that are supported by this COBOL system and gives other useful information about using them.

Option | Can be specified by parameter string? | Default
ALl31 | Yes | OFF
COUNTRy | Yes | US
Heap | Yes | 32K, 32K, ANYWHERE, KEEP, 8K, 4K
MSGFile | Yes | SYSOUT
NATlang | Yes | ENU
RPTOpts | No | OFF
RPTStg | No | OFF
STOrage | Yes | NONE, NONE, NONE, 8K
UPSI | Yes | 00000000
Note:
  • The shortest abbreviation you can use for each run-time option is shown in capital letters.
  • Specifying an invalid option results in error CEE3611I ("The run-time option option was an invalid run-time option").
  • Specifying an invalid suboption results in error CEE3616I ("The string string was not a valid suboption of the run-time option option").
Parent topic: LE Run-Time Options


Unsupported LE Run-time Options

The following table shows valid but unsupported run-time options. Specifying any of these options results in error MFX9999I ("The run-time option option is not supported in this release").

ABPERC | ERRCOUNT | PUNUNIT
ABTERMENC | ERRUNIT | RDRUNIT
AIX | FILEHIST | RECPAD
AIXBLD | FLOW, NOFLOW | NORTEREUS
ANYHEAP | INQPCOPN | SIMVRD
AUTOTASK | INTERRUPT | STACK
BELOWHEAP | LIBSTACK | TERMTHDACT
CBLOPTS | MSGQ | TEST
CBLPSHPOP | NONIPTSTACK | THREADHEAP
CHECK | OCSTATUS | TRACE
DEBUG | PC | TRAP
DEPTHCONDLMT | PLITASKCOUNT | USRHDLR
ENVAR | POSIX | VCTRSAVE
 | PRTUNIT | XUFLOW
Note: The CBLQDA run-time option is supported via an environment variable (MF_CBLQDA); see File Handling and Dataset Environment Variables for more information.

The following list shows LE run-time options that are valid but only supported by the C language or in a mainframe environment. Specifying any of these options results in error CEE3618I ("The run-time option option was not valid from the invocation command ").

ARGPARSE | EXECOPS | REDIR
ENV | PLIST | RTEREUS
Parent topic: LE Run-Time Options
Related information
Supported LE Run-time Options


Specifying LE Run-time Options

You can specify LE run-time options in a configuration file specified by the MFLECONFIG environment variable. MFLECONFIG must specify the filename, including path, of a text file that contains the run-time options you want to use. For example:

MFLECONFIG=/home/templates/prod/le1.cfg
export MFLECONFIG

You must specify each run-time option on a line of its own in the configuration file. The syntax for each option is the same as that defined in the IBM Language Environment Programming Reference.

You can use the IBM-defined abbreviations for the run-time options. The shortest abbreviation you can use for each run-time option is shown in capital letters in Supported LE Run-time Options. For example, you can abbreviate MSGFILE to MSGFIL, MSGFI or MSGF, but MSG will not be recognized.

The IBM-defined default values are used for any supported run-time options that you do not specify in the configuration file.

Parent topic: LE Run-Time Options


LE Error Conditions

The following table lists the error conditions detected by LE support in this COBOL system.

Error condition | Routines | Message | Severity
Heap storage control information damaged | CEECRHP, CEECZST, CEEDSHP, CEEFRST, CEEGTST | CEE0802I | 4
Unsupported routine |  | MFX9999I | 4
Invalid case code | CEENCOD | CEE0401I | 3
Invalid control code | CEENCOD | CEE0402I | 3
Invalid security code | CEENCOD, CEEDCOD | CEE0403I | 3
Invalid facility-ID | CEENCOD | CEE0404I | 3
Invalid destination code | CEEMOUT | CEE0451I | 3
Heap identifier not recognized | CEEDSHP, CEEGTST | CEE0803I | 3
Initial size value invalid | CEECRHP | CEE0804I | 3
Increment size value invalid | CEECRHP | CEE0805I | 3
Option value not recognized | CEECRHP | CEE0806I | 3
Requested storage size not positive | CEECZST, CEEGTST | CEE0808I | 3
Storage address not recognized | CEECZST, CEEFRST | CEE0810I | 3
Invalid attempt to discard initial heap | CEEDSHP | CEE0812I | 3
Insufficient storage available | CEECRHP, CEEGTST | CEE0813I | 3
UCT/GMT offset not available | CEEGMT,CEEUTC | CEE2502I | 3
UCT/GMT offset not available | CEEGMTO | CEE2503I | 3
Input seconds not in range | CEEDATM, CEESECI | CEE2505I | 3
Insufficient data | CEECBLDY | CEE2507I | 3
Hours value not recognized | CEEISEC, CEESECS | CEE2510I | 3
Day value not recognized | CEEISEC | CEE2511I | 3
Lilian date not within range | CEEDATE, CEEDYWK | CEE2512I | 3
Year value not recognized | CEEISEC | CEE2514I | 3
Milliseconds value not recognized | CEEISEC | CEE2515I | 3
Date value not recognized | CEECBLDY | CEE2517I | 3
Invalid picture string | CEECBLDY | CEE2518I | 3
Seconds value not recognized | CEEISEC | CEE2519I | 3
Date string not matching picture | CEEBLDY | CEE2520I | 3
Invalid seed value | CEERAN0 | CEE2524I | 3
Local time not available from the system | CEELOCT | CEE2531I | 3
Only one language on stack | CEE3LNG | CEE3450I | 3
Invalid language | CEE3LNG | CEE3451I | 3
Function not recognized | CEE3LNG | CEE3452I | 3
Only one country code on stack | CEE3CTY | CEE3455I | 2
Invalid country code | CEE3CTY | CEE3456I | 3
Invalid function | CEE3CTY | CEE3457I | 3
Illegal century value | CEESCEN | MFX9999I | 3
Parameter string longer than 80 bytes | CEE3PRM | CEE3649I | 1
Parent topic: Language Environment (LE) Support


LE Run-Time Options Error Messages

The COBOL system can produce the following error messages while checking the syntax of a parameter string specifying run-time options.

  • MFX9999I The run-time option option is not supported in this release
    A run-time option has been specified which is defined in Language Environment but is not supported by this COBOL system.
  • CEE3601I The string string was found where a delimiter was expected following a quoted suboption for the run-time option option
    A quoted suboption must be followed by a comma, right parenthesis, or space.
  • CEE3602I An end quote delimiter did not occur before the end of the run-time option string
    A start quote, either single or double, does not have a matching end quote.
  • CEE3603I The character character is not a valid run-time option delimiter
    Options must be separated by either a space or a comma.
  • CEE3605I The string string was found where a delimiter was expected following the suboptions for the run-time option option
    Suboptions that are enclosed within parentheses must be followed by either a space or a comma.
  • CEE3606I The string string was too long and was ignored
    The maximum number of characters permitted for an option or suboption has been exceeded.
  • CEE3607I The end of the suboption string did not contain a right parenthesis
    A left parenthesis does not have a matching right parenthesis.
  • CEE3608I The following messages pertain to the invocation command run-time options
    The messages that follow this one, up to the next message of this type with a different source, refer to the run-time options specified on the invocation command.
  • CEE3610I The run-time option old-option was mapped to the run-time option le-option
    old-option was an option from a previous release that was supported by Language Environment for compatibility.
  • CEE3611I The run-time option option was an invalid run-time option
    An option has been specified which is not a valid option or is an option that is recognized by Language Environment for compatibility with a previous release.
  • CEE3612I Too many suboptions were specified for the run-time option option
    The number of suboptions exceeds the maximum number that can be specified for the specified option. The excess suboptions are ignored.
  • CEE3614I An invalid character occurred in the numeric string string of the run-time option option
    A numeric value does not contain all decimal numeric characters.
  • CEE3615I The installation default for the run-time option option could not be overridden
  • CEE3616I The string string was not a valid suboption of the run-time option option
    A suboption has been specified which is not one of the suboptions defined for the specified option.
  • CEE3617I The number number of the run-time option option exceeded the range of -2147483648 to 2147483647
    A numeric value is outside the range of -2147483648 to 2147483647.
  • CEE3618I The run-time option option was not valid from the invocation command
    A run-time option has been specified which is not valid on the invocation command.
  • CEE3619I The value value was not a valid MSGQ number
  • CEE3622I The option option quoted suboption string string was not one character long
    The only valid length for STORAGE suboptions within quotes is one.
  • CEE3623I The UPSI option suboption string string was not eight characters long
    The only valid length for the value of the UPSI suboption is eight.
  • CEE3633W The total length of the combined ENVAR strings exceeded 250 characters
    The total length of the combined ENVAR strings exceeded the maximum limit of 250 characters.
  • CEE3634I The number number of the run-time option option exceeded the range of -32768 to 32767
    number exceeded the range of -32768 to 32767.
  • CEE3635I The string string was not a valid RECFM suboption specification for run-time option option
    The RECFM suboption value must be F, FA, FB, FBA, FBS, FBSA, U, UA, V, VA, VB, or VBA.
  • CEE3636I The value number exceeded the maximum allowable LRECL or BLKSIZE of 32760 bytes
    The value of the LRECL or BLKSIZE suboption cannot be greater than 32760.
  • CEE3637I The number number specified in the suboption suboption of the run-time option option is not a valid hexadecimal number in the range 0 to FFFFFFFF
    An invalid hexadecimal numeral was specified or the range of the number exceeds 0 to FFFFFFFF.
  • CEE3638I The table size of size, specified in the TRACE run-time option, exceeds the maximum allowed value of 16777215
    size exceeded the maximum allowed value of 16777215.
Parent topic: Language Environment (LE) Support
Related information
Supported LE Run-time Options


MFX9999I The run-time option option is not supported in this release

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3601I The string string was found where a delimiter was expected following a quoted suboption for the run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3602I An end quote delimiter did not occur before the end of the run-time option string

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3603I The character character is not a valid run-time option delimiter

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3605I The string string was found where a delimiter was expected following the suboptions for the run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3606I The string string was too long and was ignored

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3607I The end of the suboption string did not contain a right parenthesis

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3608I The following messages pertain to the invocation command run-time options

Resolution:

No response is required.

Parent topic: LE Run-Time Options Error Messages


CEE3610I The run-time option old-option was mapped to the run-time option le-option

Resolution:

Consult the appropriate migration guide for a list of options supported for the language. Change the run-time options string to use the le-option instead.

Parent topic: LE Run-Time Options Error Messages


CEE3611I The run-time option option was an invalid run-time option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3612I Too many suboptions were specified for the run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3614I An invalid character occurred in the numeric string string of the run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3615I The installation default for the run-time option option could not be overridden

Resolution:

Correct the run-time options to not specify this option.

Parent topic: LE Run-Time Options Error Messages


CEE3616I The string string was not a valid suboption of the run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3617I The number number of the run-time option option exceeded the range of -2147483648 to 2147483647

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3618I The run-time option option was not valid from the invocation command

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3619I The value value was not a valid MSGQ number

Resolution:

Correct the value in the run-time options string to be greater than zero.

Parent topic: LE Run-Time Options Error Messages


CEE3622I The option option quoted suboption string string was not one character long

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3623I The UPSI option suboption string string was not eight characters long

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3633W The total length of the combined ENVAR strings exceeded 250 characters

Resolution:

Reduce the total length of the ENVAR strings to less than the 250-character maximum.

Parent topic: LE Run-Time Options Error Messages


CEE3634I The number number of the run-time option option exceeded the range of -32768 to 32767

Resolution:

Correct the run-time options string to be within the range of -32768 to 32767.

Parent topic: LE Run-Time Options Error Messages


CEE3635I The string string was not a valid RECFM suboption specification for run-time option option

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3636I The value number exceeded the maximum allowable LRECL or BLKSIZE of 32760 bytes

Resolution:

Correct the run-time options string.

Parent topic: LE Run-Time Options Error Messages


CEE3637I The number number specified in the suboption suboption of the run-time option option is not a valid hexadecimal number in the range 0 to FFFFFFFF

Resolution:

Correct the run-time options string to be a valid hexadecimal number in the range of 0 to FFFFFFFF.

Parent topic: LE Run-Time Options Error Messages


CEE3638I The table size of size, specified in the TRACE run-time option, exceeds the maximum allowed value of 16777215

Resolution:

Correct the TRACE run-time options to not exceed the maximum of 16777215.

Parent topic: LE Run-Time Options Error Messages


LE Country Codes

The following table lists the two-character codes for the countries that are supported by the COUNTRY run-time option and by the callable routine CEE3CTY. The only effect of these codes is to set the national currency symbol for the application.

Country | Code
Afghanistan | AF
Albania | AL
Algeria | DZ
Andorra | AD
Angola | AO
Antigua and Barbuda | AG
Argentina | AR
Australia | AU
Austria | AT
Bahamas | BS
Bahrain | BH
Bangladesh | BD
Barbados | BB
Belgium | BE
Benin | BJ
Bermuda | BM
Bolivia | BO
Bosnia/Herzegovina | BA
Botswana | BW
Brazil | BR
Brunei Darussalam | BN
Bulgaria | BG
Burkina Faso | BF
Burma | BU
Canada | CA
Cayman Islands | KY
Chad | TD
Chile | CL
China, Peoples Republic of | CN
China, Republic of | TW
Colombia | CO
Costa Rica | CR
Croatia | HR
Cuba | CU
Cyprus | CY
Czech Republic | CZ
Czechoslovakia | CS
Denmark | DK
Dominican Republic | DO
Ecuador | EC
Egypt | EG
El Salvador | SV
Estonia | EE
Ethiopia | ET
Finland | FI
France | FR
Gabon | GA
Gambia | GM
Germany | DE
Ghana | GH
Greece | GR
Guatemala | GT
Guinea-Bissau | GW
Guyana | GY
Haiti | HT
Honduras | HN
Hong Kong | HK
Hungary | HU
Iceland | IS
India | IN
Indonesia | ID
Iran | IR
Iraq | IQ
Ireland | IE
Israel | IL
Italy | IT
Jamaica | JM
Japan | JP
Jordan | JO
Kenya | KE
Korea, Republic of | KR
Kuwait | KW
Latvia | LV
Lebanon | LB
Lesotho | LS
Liberia | LR
Libya | LY
Liechtenstein | LI
Lithuania | LT
Luxembourg | LU
Macau | MO
Macedonia | MK
Madagascar | MG
Malawi | MW
Malaysia | MY
Mali | ML
Mauritania | MR
Mauritius | MU
Mexico | MX
Monaco | MC
Morocco | MA
Mozambique | MZ
Namibia | NA
Netherlands | NL
Netherlands Antilles | AN
New Caledonia | NC
New Zealand | NZ
Nicaragua | NI
Niger | NE
Nigeria | NG
Norway | NO
Oman | OM
Pakistan | PK
Panama | PA
Papua New Guinea | PG
Paraguay | PY
Peru | PE
Philippines | PH
Poland | PL
Portugal | PT
Puerto Rico | PR
Qatar | QA
Romania | RO
Russia | RU
Saint Lucia | LC
Saudi Arabia | SA
Senegal | SN
Seychelles | SC
Sierra Leone | SL
Singapore | SG
Slovakia | SK
Slovenia | SI
Somalia | SO
South Africa | ZA
Spain | ES
Sri Lanka | LK
Sudan | SD
Surinam | SR
Swaziland | SZ
Sweden | SE
Switzerland | CH
Syria | SY
Tanzania | TZ
Thailand | TH
Togo | TG
Tunisia | TN
Turkey | TR
Uganda | UG
USSR | SU
United Arab Emirates | AE
United Kingdom | GB
United States | US
Uruguay | UY
Vanatu | VU
Venezuela | VE
Western Samoa | WS
Yemen | YE
Yugoslavia | YU
Zaire | ZR
Zambia | ZM
Zimbabwe | ZW
Parent topic: Language Environment (LE) Support


Library Routines

  • Library Routines - Key
  • Application Subsystem Routines
  • Bit-packing Routines
  • Byte-stream File Routines
  • Character Set Conversion Routines
  • Consolidated Tracing Facility Routines
  • Container-Managed Services Routines
  • Debugging Routines
  • Display Attribute Routines
  • Enhanced ACCEPT and DISPLAY Syntax Routines
  • Exit and Error Procedure Routines
  • File and Filename Routines
  • Keyboard Routines
  • Logical Operator Routines
  • Memory Allocation Routines
  • Multi-threading Routines
  • National Locale Support (NLS) Library Routines
  • Operating System Information Routines
  • Portability Routines
  • Program Canceling Routines
  • Program Information Routines
  • Run unit handling routines
  • Screen Routines
  • State Maintenance Routines
  • Text Routines
  • Unit Testing Routines
  • Virtual Heap Routines
  • Windows Routines
  • Miscellaneous Routines
  • Alphabetical List of Library Routines
Parent topic: General Reference


Library Routines - Key

Descriptions for all of the call-by-name routines appear alphabetically. Each description contains the routine name and function and the following entries (as appropriate):

Syntax:

Shows the CALL statement you could use to call the routine.

The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.)

status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5.

The name of the routine must be coded in upper case.

Parameters:

Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.

If you want your parameters to be validated when your program is compiled, use the call prototye definition. (We recommend that you use the call prototype method.) Otherwise, use the PICTURE clause.

We provide the files cbltypes.cpy, which contains all types required by the system library routines, and cblproto.cpy, which contains all prototypes of the types used by the system library routines.

On Entry:

Indicates which of the parameters shown are passed on entry

On Exit:

Indicates which of the parameters shown are returned on exit

Where bits of one or more bytes are referenced, bit 0 is the least significant (rightmost) bit.

Comments:

Provides any additional information necessary for the successful use of the routine

Parent topic: Library Routines


Application Subsystem Routines

This routine enables you to logically group a number of programs. This enables you to cancel these programs, the subsystem, with a single statement.

  • CBL_SUBSYSTEM
    Declares or deallocates subsystems.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_SUBSYSTEM

Declares or deallocates subsystems.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SUBSYSTEM" using     function-code
                               parameter
                     returning status-code

Parameters

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
Contains one of the following:

0: Declare subsystem

1: Cancel subsystem

2: Remove from subsystem

parameter
Group predefined as cblt-subsys-params containing:
01 cblt-subsys-params     typedef.
  03 cblte-ssp-handle     cblt-x2-compx. *> pic x(2) comp-x.
  03 cblte-ssp-name-len   cblt-x2-compx. *> pic x(2) comp-x.
  03 cblte-ssp-name       cblt-x1.       *> Occurs depending on
                                         *> cblte-ssp-name-len. pic x(n).
status-code
See Library Routines - Key.

On Entry:

function-code
The subfunction number.
With function-code = 0:
cblte-ssp-name-len
The length of subsystem program-name field.
cblte-ssp-name
The subsystem program-name (space-terminated).
cblte-ssp-handle
The subsystem handle returned by a function 0 call.
With function-code = 2:
dummy-param
Value 0.

On Exit:

With function-code = 0:
cblte-ssp-handle
The subsystem handle.

Comments:

A subsystem is defined to be a specified COBOL program in an application, plus any subprograms subsequently called by programs already in the subsystem that do not already belong to any other subsystems.

With function-code = 0:
This function declares a subsystem. The routine returns a subsystem handle. If the program is not already loaded, the function loads it. If an error occurs in finding or loading the program, a subsystem handle of zero is returned.
A program belonging to a subsystem is only deallocated (that is, deleted from memory), when either it is canceled by the CANCEL verb, or the program cancels the entire subsystem using function-code=1, or the application executes a STOP RUN or CHAIN statement. The main program of a subsystem should not be canceled with the CANCEL statement unless all other programs in the subsystem have already been canceled. Any imported .dll files are automatically removed from memory when the .dll file which imports them is cancelled.
If the program is a .dll file, it must have been called previously if it is to be used to declare a subsystem.
With function-code = 1:
This function cancels all programs in the specified subsystem. On UNIX, the default cancel mode is physical cancel, which can be changed with the subsystem_cancel_mode runtime tunable.
If any program in the subsystem is still active, that program is released from the subsystem and is not canceled. Any imported .dll files are automatically removed from memory when the .dll file which imports them is cancelled.
With function-code = 2:
This function removes the program that called it from any subsystem the program is in. To ensure a program is never included in any subsystem, call this function at the start of each entry in to the program.
Parent topic: Application Subsystem Routines
Parent topic: Alphabetical List of Library Routines
Related reference
subsystem_cancel_mode


Bit-packing Routines

  • X"F4"
    Packs the least significant bits in eight bytes into a single byte.
  • X"F5"
    Unpacks the bits in a byte into eight bytes.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


X"F4"

Packs the least significant bits in eight bytes into a single byte.

Syntax:

call x"F4" using byte
                 array

Parameters:

 | Using call prototype (see Key) | Picture
byte | cblt-x1-compx | pic x comp-x.
array | cblt-x1-compx occurs 8 | pic x comp-x occurs 8

On Entry:

array The bits to be packed.

On Exit:

byte The packed byte.

Comments:

The routine takes the eight bytes from array and uses the least significant bit of each byte to form byte. The first occurrence in array becomes the most significant bit of byte (bit 7).

00000001 00000001 00000000 00000000 00000001 00000000 00000001 00000001
       |        |        |        |        |        |        |        |
       |        |        |        |+-------+        |        |        |
       |        |        +-------+||+---------------+        |        |
       |        +---------------+||||+-----------------------+        |
       +-----------------------+||||||+-------------------------------+
                               ||||||||
                               vvvvvvvv
                               11001011
Parent topic: Bit-packing Routines
Parent topic: Alphabetical List of Library Routines


X"F5"

Unpacks the bits in a byte into eight bytes.

Syntax:

call x"F5" using byte
                 array

Parameters:

 | Using call prototype (see Key) | Picture
byte | cblt-x1-compx | pic x comp-x.
array | cblt-x1-compx occurs 8 | pic x comp-x occurs 8

On Entry:

byte The byte to be unpacked

On Exit:

array The unpacked bits

Comments:

The routine takes the eight bits of byte and moves them to the corresponding occurrence within array

                               10110011
                               ||||||||
       +-----------------------+||||||+-------------------------------+
       |        +---------------+||||+-----------------------+        |
       |        |        +-------+||+---------------+        |        |
       |        |        |        |+-------+        |        |        |
       v        v        v        v        v        v        v        v
00000001 00000000 00000001 00000001 00000000 00000000 00000001 00000001
Parent topic: Bit-packing Routines
Parent topic: Alphabetical List of Library Routines


Byte-stream File Routines

The byte-stream file routines enable you to read and write data files without the need to adhere to COBOL record definitions.

For all these routines, if the routine is successful the RETURN-CODE register is set to zero. If the routine fails, the RETURN-CODE register contains a file status value indicating the failure. This file status is always the standard ANSI'74 file status value. If no ANSI'74 file status is defined for the error, an extended file status is returned (9/nnn where nnn is the run-time system error number).

For this to work you should use RETURN-CODE and not have a RETURNING clause. If RETURN-CODE is nonzero after calling a byte-stream routine, move it to a PIC XX COMP-X data item to process it as a file status. For example:

 01 file-stat      pic xx comp-x.
 01    redefines file-stat.
     03 fs-byte-1  pic x.
     03 fs-byte-2  pic x comp-x.
   . . .
     call "CBL_xxx_FILE" using <parameters>
     if return-code not = 0
        move return-code to file-stat
           . . .

At this point fs-byte-1 contains "9" and fs-byte-2 contains the run-time system error number.

  • CBL_CLOSE_FILE
    Closes a file opened for byte-stream operations.
  • CBL_CREATE_FILE
    Creates a new file and leaves it open for byte-stream operations.
  • CBL_FLUSH_FILE
    Ensures all file buffers for a file are written to disk. This includes both run-time system buffers and operating system buffers.
  • CBL_GET_RECORD_LOCK
    Obtains a record lock on a file.
  • CBL_OPEN_FILE
    Opens an existing file for byte-stream operations.
  • CBL_READ_FILE
    Reads bytes from a file.
  • CBL_TEST_RECORD_LOCK
    Tests for an existing record lock on a file.
  • CBL_WRITE_FILE
    Writes bytes to a file.
  • Byte-stream File Handling Routines - Example
Parent topic: Library Routines
Related information
Byte-stream File Handling Routines - Example
Alphabetical List of Library Routines


CBL_CLOSE_FILE

Closes a file opened for byte-stream operations.

Syntax:

call "CBL_CLOSE_FILE" using  file-handle

Parameters:

 | Using call prototype (see Key) | Picture
file-handle | cblt-bytestream-handle | pic x(4) comp-5.

On Entry:

file-handle The file handle returned when the file was opened.

On Exit:

None.

Comments:

Any byte-stream file open when a STOP RUN is executed is automatically closed. Any record locks owned by the run-unit are released by a call to this routine.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_CREATE_FILE

Creates a new file and leaves it open for byte-stream operations.

Syntax:

call "CBL_CREATE_FILE" using filename
                             access-mode
                             deny-mode
                             device
                             file-handle

Parameters:

 | Using call prototype (see Key) | Picture
filename | pic x(n). | pic x(n).
access-mode | cblt-x1-compx | pic x comp-x.
deny-mode | cblt-x1-compx | pic x comp-x.
device | cblt-x1-compx | pic x comp-x.
file-handle | cblt-bytestream-handle | pic x(4) comp-5.

On Entry:

filename
Space- or null-terminated filename of the file to be opened. You can use embedded environment variables and library names in filename.
access-mode
Defines access mode:
1 | Read only
2 | Write only (deny-mode must be 0)
3 | Read/write
64 | File can be greater than 4GB. Combine this value with the required access; for example, for read/write access of such files, set 67.
deny-mode
Defines deny mode:
0 | Deny both read and write (exclusive)
1 | Deny write
2 | Deny read
3 | Deny neither read nor write
device
Reserved for future use (must be 0).

On Exit:

file-handle
Returns a file handle for a successful open.

Comments:

The success of the call can be checked by examining the RETURN-CODE special register.

You can use embedded environment variables and library names in filename.

If you are requesting 64-bit file access to an unknown remote file system, ensure you set the remote_64bit_access tunable.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Byte-stream File Routines
Special Registers
Filenames


CBL_FLUSH_FILE

Ensures all file buffers for a file are written to disk. This includes both run-time system buffers and operating system buffers.

Syntax:

call "CBL_FLUSH_FILE" using file-handle

Parameters:

file-handle
Call prototype: cblt-bytestream-handle
Picture: pic x(4) comp-5.

On Entry:

file-handle
The file handle returned when the file was opened (by CBL_OPEN_FILE).

On Exit:

RETURN-CODE
Indicates whether the routine was successful:
0 | Success
-1 | Buffers might not have been flushed
Other | Two-byte file status code indicating the error

Comments

On some operating systems it is not possible to flush the file buffers. In this case, the appropriate status code is returned.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_RECORD_LOCK

Obtains a record lock on a file.

Note: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_GET_RECORD_LOCK" using file-handle
                                 record-offset
                                 record-length
                                 reserved

Parameters

 | Using call prototype (see Key) | Picture
file-handle | cblt-bytestream-handle | pic x(4) comp-5.
record-offset | cblt-x4-compx | pic x(4) comp-x.
record-length | cblt-x4-compx | pic x(4) comp-x.
reserved | cblt-x2-compx | pic x(2) comp-x.
return-code | cblt-x2-compx | pic x(2) comp-x.

On Entry:

file-handle
The handle returned from a successful CBL_OPEN_FILE or CBL_CREATE_FILE call.
record-offset
The offset from the start of the file to the first byte to be locked.
record-length
The number of bytes to lock, starting from record-offset.
reserved
Reserved - must be zero.

On Exit:

return-code
One of the following codes:
0 | Successful lock
1 | Lock is already owned by this run-unit
9/nnn | File status code indicating an error condition
Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_OPEN_FILE

Opens an existing file for byte-stream operations.

Syntax:

call "CBL_OPEN_FILE" using filename
                           access-mode
                           deny-mode
                           device
                           file-handle

Parameters:

 | Using call prototype (see Key) | Picture
filename | pic x(n). | pic x(n).
access-mode | cblt-x1-compx. | pic x comp-x.
deny-mode | cblt-x1-compx. | pic x comp-x.
device | cblt-x1-compx. | pic x comp-x.
file-handle | cblt-bytestream-handle. | pic x(4) comp-5.

On Entry:

filename
Space- or null-terminated filename of the file to be opened. You can use spacey filenames if you put double quotation marks around them. You can use embedded environment variables and library names in filename; for more information see the chapter Filenames in yourFile Handling book.
access-mode
Defines access mode:
1 | Read only
2 | Write only (deny-mode must be 0)
3 | Read/write
64 | File can be greater than 4GB. Combine this value with the required access; for example, for read/write access of such files, set 67.
deny-mode
Defines deny mode:
0 | Deny both read and write (exclusive)
1 | Deny write
2 | Deny read
3 | Deny neither read nor write
device
Reserved for future use (must be 0).

On Exit:

file-handle
Returns a file handle for a successful open.

Comments:

The success of the call can be checked by examining RETURN-CODE.

If you are requesting 64-bit file access to an unknown remote file system, ensure you set the remote_64bit_access tunable.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_FILE

Reads bytes from a file.

Syntax:

call "CBL_READ_FILE" using file-handle
                           file-offset
                           byte-count
                           flags
                           buffer

Parameters:

 | Using call prototype (see Key) | Picture
file-handle | cblt-bytestream-handle | pic x(4) comp-5.
file-offset | cblt-x8-compx | pic x(8) comp-x.
byte-count | cblt-x4-compx | pic x(4) comp-x.
flags | cblt-x1-compx | pic x comp-x.
buffer | pic x(n). | pic x(n).

On Entry:

file-handle
The file handle returned when the file was opened.
file-offset
The offset in the file at which to read. This field is limited to a maximum value of x"00FFFFFFFF" unless bit 4 of the access-mode flag is set when the file is opened using CBL_OPEN_FILE or CBL_CREATE_FILE.
byte-count
The number of bytes to read.
flags
This parameter can take the following values:
0 | Standard read
128 | Return the current file size in file-offset

On Exit:

file-offset
Contains the current file size on return if flags is set to 128 on entry.
buffer
The buffer into which the bytes are read. It is your responsibility to ensure that the buffer is large enough to hold the number of bytes to be read.

Comments:

The success of the call can be checked by examining RETURN-CODE.

When using this routine to read a file that is contained in a .lbr file, the end-of-file status is not returned. To ensure you only read the file you want, obtain the size of the file first (set flags to 128), and only read up to that size.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_TEST_RECORD_LOCK

Tests for an existing record lock on a file.

Note: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_TEST_RECORD_LOCK using file-handle
                                 record-offset
                                 record-length
                                 reserved

Parameters:

 | Using call prototype (see Key) | Picture
file-handle | cblt-bytestream-handle | pic x(4) comp-5.
record-offset | cblt-x4-compx | pic x(4) comp-x.
record-length | cblt-x4-compx | pic x(4) comp-x.
reserved | cblt-x2-compx | pic x(2) comp-x.
return-code | cblt-x2-compx | pic x(2) comp-x.

On Entry:

file-handle
The handle returned from a successful CBL_OPEN_FILE or CBL_CREATE_FILE call.
record-offset
The offset from the start of the file to the first byte to be tested for a lock.
record-length
The number of bytes to test for a lock, starting from record-offset.
reserved
Reserved - must be zero.

On Exit:

return-code
One of the following values:
0 | Record not locked
1 | Lock already owned by run-unit
9/nnn | File status code indicating an error condition
Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_FILE

Writes bytes to a file.

Syntax:

call "CBL_WRITE_FILE" using  file-handle
                            file-offset
                            byte-count
                            flags
                            buffer

Parameters:

 | Using call prototype (see Key) | Picture
file-handle | cblt-bytestream-handle | pic x(4) comp-5.
file-offset | cblt-x8-compx | pic x(8) comp-x.
byte-count | cblt-x4-compx | pic x(4) comp-x.
flags | cblt-x1-compx | pic x comp-x.
buffer | pic x(n). | pic x(n).

On Entry:

file-handle
The file handle returned when the file was opened.
file-offset
The offset in the file at which to write. This field is limited to a maximum value of x"00FFFFFFFF" unless bit 4 of the access-mode flag is set when the file is opened using CBL_OPEN_FILE or CBL_CREATE_FILE.
byte-count
The number of bytes to write.

Putting a value of zero in this field causes the file to be truncated or extended to the size specified in the file-offset field.

flags
This parameter can take the following value:
0: standard write
buffer
The buffer from which the bytes are written. It is your responsibility to ensure that the buffer is large enough to hold the number of bytes to be written.

On Exit:

None

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: Byte-stream File Routines
Parent topic: Alphabetical List of Library Routines


Byte-stream File Handling Routines - Example

The following example program contains routines to open and close files to be processed as byte-stream files, one for input, one for output and to read and write individual bytes using buffering.

Source Code

$SET ANS85
copy "cblproto.cpy".
program-id.
*==========================================================*

 working-storage section
 78 fals value 0
 78 tru  value 1.

*----------------------------------------------------------*
* WS for byte-stream handling

 78 in-buff-len      value 4096.

 01 in-buff          pic x(in-buff-len).

 01 infilename       pic x(64).
 01 infile-handle    cblt-bytestream-handle.
 01 infile-offset    cblt-x8-compx value 0.
 01 infile-len       cblt-x8-compx.

 01 in-buff-ptr      pic x(2) comp-x.
 01 in-buff-end      cblt-x4 comp-x value in-buff-len.

 78 out-buff-len     value 4096.

 01 out-buff         pic x(out-buff-len).

 01 outfilename      pic x(64).
 01 outfile-handle   cblt-bytestream-handle.
 01 outfile-offset   cblt-x8-compx value 0.
 01 outfile-len      cblt-x8-compx.

 01 out-buff-ptr     pic x(2) comp-x.
 01 out-buff-end     cblt-x4-compx value in-buff-len.

 01 bs-misc.
     03 eof-flag         pic x comp-x value fals.
         88 eof              value tru.
     03 last-block-flag  pic x comp-x value fals.
         88 last-block       value tru.
     03 display-put-flag pic x comp-x value fals.
         88 display-put      value tru false fals.

     03 next-byte.
         05 next-byte-n  cblt-x1-compx
     03 save-byte        pic x.

 01 k-0              cblt-x1-compx value 0.
 01 k-1              cblt-x1-compx value 1.
 01 k-2              cblt-x1-compx value 2.
 01 k-128            cblt-x1-compx value 128.

*----------------------------------------------------------*

*==========================================================*
 procedure division.
 aa-control section.
     perform ca-initial.
     perform cc-process.
     perform ce-final
     .

 aa-990-exit.
     exit program
     stop run
     .

 ca-initial section.
     move "inbyte.dat" to infilename
     move "outbyte.dat" to outfilename
     perform open-in-file
     perform open-out-file
     .

 cc-process section.

* Examine each byte, and process as required when the
* appropriate byte is found (as identified by the when
* clause)

     perform get-byte
     perform until eof
         evaluate next-byte
          when .......

          when other
             perform put-byte
             perform get-byte
         end-evaluate
     end-perform
     .

 ce-final section.
     perform close-in-file
     perform close-out-file
     .

*----------------------------------------------------------*
* Input byte-stream file code

 open-in-file section.
     call "CBL_OPEN_FILE" using infilename
                                k-1
                                k-0
                                k-0
                                infile-handle
     if return-code not = 0
         display "Open failed: "
                 infilename
         stop run
     end-if

* Find length of input file.
     call "CBL_READ_FILE" using infile-handle
                                infile-offset
                                in-buff-end
                                k-128
                                in-buff
     move infile-offset to infile-len
     move 0 to infile-offset
     move in-buff-len to in-buff-ptr
     add 1 to in-buff-ptr
     move fals to last-block-flag
     move fals to eof-flag
     .

 get-byte section.
     if in-buff-ptr = in-buff-end
         if last-block
             set eof to true
             move x"ff" to next-byte
         else
             perform get-next-block
             if in-buff-end = 0
                 set eof to true
                 move x"ff" to next-byte
             end-if
         end-if
     end-if

     if not eof
         move in-buff (in-buff-ptr : 1) to next-byte
         add 1 to in-buff-ptr
*        display next-byte
*            with no advancing
     end-if
     .

 get-previous-byte section.
     if in-buff-ptr = 2
         subtract 2 from in-buff-ptr
     else
         perform get-previous-block
     end-if
     perform get-byte
     .

 get-next-block section.
     call "CBL_READ_FILE" using infile-handle
                                infile-offset
                                in-buff-end
                                k-0
                                in-buff
     end-call
     move 1 to in-buff-ptr
     add in-buff-end to infile-offset
     if infile-offset = infile-len
         subtract infile-len from infile-offset
         subtract infile-offset from in-buff-end
         move tru to last-block-flag
     end-if
     .

 get-previous-block section.
     if last-block
         move fals to last-block-flag
         move in-buff-len to in-buff-end
         add infile-len to infile-offset
     end-if
     subtract in-buff-end from infile-offset
     call "CBL_READ_FILE" using infile-handle
                         infile-offset
                         in-buff-end
                         k-0
                         in-buff
     end-call
     move in-buff-len to in-buff-ptr
     .
 close-in-file section.
     call "CBL_CLOSE_FILE" using infile-handle
     .

*==========================================================*
* Output byte-stream file code

 open-out-file section.
     call "CBL_CREATE_FILE" using outfilename
                                k-2
                                k-0
                                k-0
                                outfile-handle

     if return-code not = 0
         display "Open failed: "
                 outfilename
         stop run
     end-if
     move 1 to out-buff-ptr
     .

 put-byte section.
     if display-put
         display next-byte
             with no advancing
     end-if
     move next-byte to out-buff (out-buff-ptr:1)
     add 1 to out-buff-ptr
     if out-buff-ptr = out-buff-len
         perform write-block
         move 1 to out-buff-ptr
     end-if
     .

 write-block section.
     call "CBL_WRITE_FILE" using outfile-handle
                                 outfile-offset
                                 out-buff-end
                                 k-0
                                 out-buff
     end-call
     add out-buff-end to outfile-offset
     .

 close-out-file section.
     if out-buff-ptr = 1
         move out-buff-ptr to out-buff-end
         subtract 1 from out-buff-end
         perform write-block
     end-if
     call "CBL_CLOSE_FILE" using outfile-handle
     .
Parent topic: Byte-stream File Routines


Character Set Conversion Routines

The character set conversion routines convert characters between the OEM and ANSI character sets..

  • _CODESET
    Converts a string between the EBCDIC and ASCII character sets.
  • CBL_CODESET_SET_MAPPING
    Enables you to change the codeset in effect.
  • CBL_STRING_CONVERT
    Converts a string from one character encoding to another.
  • PC_WIN_CHAR_TO_OEM
    Translates a buffer of ANSI characters into the OEM character set.
  • PC_WIN_OEM_TO_CHAR
    Translates a buffer of OEM characters into the ANSI character set.
  • PC_WIN_SET_CHARSET
    Specifies the character set to be used by the case conversion routines CBL_TOUPPER and CBL_TOLOWER.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


_CODESET

Converts a string between the EBCDIC and ASCII character sets.

Syntax:

call "_CODESET" using  function-code, length, string
                               returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
function-code |  | pic 9(2) comp-x
length |  | pic 9(9) comp-x
string |  | pic x(n)
status-code | See Library Routines - Key |

On Entry:

function-code
The type of conversion. Can be one of:
0 | Convert EBCDIC to ASCII
1 | Convert ASCII to EBCDIC
length
The number of characters in the string to convert.
string
The string to convert.

On Exit:

string
The converted string.
status-code
Indicates success or failure of the conversion.

Comments:

You cannot use this routine in a program that is compiled with a mainframe dialect, because it uses COMP-X data types, which are not supported on the mainframe.

Parent topic: Character Set Conversion Routines
Parent topic: Alphabetical List of Library Routines
Related reference
CBL_CODESET_SET_MAPPING


CBL_CODESET_SET_MAPPING

Enables you to change the codeset in effect.

Syntax:

CALL "CBL_CODESET_SET_MAPPING" using  by reference   mfcodeset
                               returning   status-code

Parameters:

mfcodeset
pic x(n) - null- or space-terminated.
status-code
See Library Routines - Key

On Entry:

mfcodeset
A supported country code.

Comments:

Use this routine before you perform any conversions using the _CODESET library routine.

Parent topic: Character Set Conversion Routines
Parent topic: Alphabetical List of Library Routines
Related reference
_CODESET
Supported Country Codes


CBL_STRING_CONVERT

Converts a string from one character encoding to another.

Syntax:

call "CBL_STRING_CONVERT" using by reference in-string
                                by value in-length
                                by value in-encoding
                                by reference out-string
                                by reference out-length
                                by value out-encoding
                                by value flags
                                by reference reserved
                                returning status-code.

Parameters:

in-string
Picture: pic x(n)
in-length
Picture: pic x(4) comp-5
in-encoding
Picture: pic x(4) comp-5
out-string
Picture: pic x(n)
out-length
Picture: pic x(4) comp-x
out-encoding
Picture: pic x(4) comp-5
flags
Picture: pic x(4) comp-5
reserved
Picture: pic x(4) comp-x
status-code
See Library Routines - Key

On Entry:

in-string
The source string to convert.
in-length
The length of the source string.
in-encoding
The encoding type of the source string. Must be one of:
Value | Encoding
0 | UTF-8
1 | UTF-16 (native)
2 | UTF-16 (portable)
3 | ASCII/MBCS characters (current locale)
4 | EBCDIC character (CHARSET"EBCDIC" encoding)
5 | ASCII/MBCS characters (current locale)
out-length
Maximum buffer length available for the converted string.
If the value is zero on entry, the call returns the size of the buffer required for the conversion only, and does not perform the actual conversion.
out-encoding
The encoding type of the converted string. Must be one of:
Value | Encoding
0 | UTF-8
1 | UTF-16 (native)
2 | UTF-16 (portable)
3 | ASCII/MBCS characters (current locale)
4 | EBCDIC character (CHARSET"EBCDIC" encoding)
5 | ASCII/MBCS characters (current locale)
flags
Reserved - must be set to zero.
reserved
Must be set to zero.

On Exit:

out-string
The converted string. If out-string is not large enough to contain the converted data, an error occurs.
If any character in in-string does not have an equivalent character in the output encoding, then it will be converted to a system dependent replacement character
Note: This should only possibly occur when converting from a UTF encoding to an ASCII or EBCDIC character.
out-length
The actual buffer length of out-string (the converted string).
status-code
The result of the conversion. Will be one of:
Value | Result
0 | success
1 | target buffer too small
2 | out of memory
3 | unsupported conversion
Parent topic: Character Set Conversion Routines
Parent topic: Alphabetical List of Library Routines


PC_WIN_CHAR_TO_OEM

Translates a buffer of ANSI characters into the OEM character set.

Syntax:

call "PC_WIN_CHAR_TO_OEM" using     srcbuff
                                    tgtbuff
                          by value  srclen
                                    tgtlen
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
srcbuff | pic x(n). | pic x(n).
tgtbuff | pic x(n). | pic x(n).
srclen | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
tgtlen | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

srcbuff | Buffer of ANSI characters to be converted.
srclen | Length of srcbuff. If this parameter is zero, then srcbuff is a null-terminated string all of which will be converted.
tgtlen | Length of tgtbuff.

On Exit:

tgtbuff Buffer of OEM characters converted from the ANSI input. This parameter must be at least as long as the number of characters in srcbuff. If srcbuff and tgtbuff are the same buffer, then the characters will be converted in place in the buffer.

Comments:

If status-code is non-zero, then the call failed due to the target buffer being of insufficient size.

Parent topic: Character Set Conversion Routines


PC_WIN_OEM_TO_CHAR

Translates a buffer of OEM characters into the ANSI character set.

Syntax:

call "PC_WIN_OEM_TO_CHAR" using     srcbuff
                                    tgtbuff
                          by value   srclen
                                    tgtlen
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
srcbuff | pic x(n). | pic x(n).
tgtbuff | pic x(n). | pic x(n).
srclen | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
tgtlen | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

srcbuff | Buffer of OEM characters to be converted.
srclen | Length of srcbuff. If this parameter is zero, then srcbuff is a null-terminated string all of which will be converted.
tgtlen | Length of tgtbuff.

On Exit:

tgtbuff Buffer of ANSI characters converted from the OEM input. This parameter must be at least as long as the number of characters in srcbuff. If srcbuff and tgtbuff are the same buffer, then the characters will be converted in place in the buffer.

Comments:

If status-code is non-zero, then the call failed due to the target buffer being of insufficient size.

Parent topic: Character Set Conversion Routines


PC_WIN_SET_CHARSET

Specifies the character set to be used by the case conversion routines CBL_TOUPPER and CBL_TOLOWER.

Syntax:

call "PC_WIN_SET_CHARSET" using
                          by value  charset
                          returning previous-charset

Parameters:

 | Using call prototype (see Key) | Picture
charset | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
previous-charset | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

charset The character set to use (0 - ANSI, 1 - OEM).

On Exit:

previous-charset The previous value of the character set.
Parent topic: Character Set Conversion Routines
Parent topic: Text Routines


Consolidated Tracing Facility Routines

These routines enable you to make use of the Consolidated Tracing Facility infrastructure in your applications.

  • CBL_CTF_COMP_PROPERTY_GET
    Returns a named property value for a component.
  • CBL_CTF_COMP_PROPERTY_SET
    Specifies a value for a component's property.
  • CBL_CTF_DEST
    Specifies an output destination by associating (or disassociating) an emitter with (or from) a component or the default emitter list.
  • CBL_CTF_EMITTER_PROPERTY_GET
    Returns a named property value for an emitter.
  • CBL_CTF_EMITTER_PROPERTY_SET
    Sets a named property value for an emitter.
  • CBL_CTF_LEVEL
    Specifies the trace level to be used for a specific component, or the default trace level if a component identifier is not specified.
  • CBL_CTF_TRACE
    Outputs an event to one or more output destinations.
  • CBL_CTF_TRACER_GET
    Returns a tracer handle that can be passed to other tracing routines to identify a component.
  • CBL_CTF_TRACER_LEVEL_GET
    Returns a tracer's current threshold trace level.
  • CBL_CTF_TRACER_NOTIFY
    Installs or uninstalls a tracer configuration callback function.
  • Consolidated Tracing Facility Return Codes
Parent topic: Library Routines
Related information
Introduction to the Consolidated Tracing Facility
Consolidated Tracing Facility Return Codes
Alphabetical List of Library Routines


CBL_CTF_COMP_PROPERTY_GET

Returns a named property value for a component.

Syntax:

call "CBL_CTF_COMP_PROPERTY_GET" using by value     flags
                                       by reference component-id
                                       by reference property-name
                                       by reference property-vallen
                                       by reference property-value
                                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bit 0
Value | Meaning
0 | Return a string value. Use bit 1 to determine the string terminator.
1 | Return an integer value. Ignore bit 1.
Bit 1
Value | Meaning
0 | Return the value as a space-terminated string.
1 | Return the value as a null-terminated string.
Bits 2-28
Reserved for future use. Must be 0.
Bit 29
Value | Meaning
0 | property-name is space-terminated.
1 | property-name is null-terminated.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component whose property value is to be returned. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
property-name
Space- or null-terminated (depending on the setting of bit 29) case-insensitive property whose value is to be returned.
property-vallen
Length of the property-value buffer in which the property's value is to be returned. The routine will fail if the buffer is too small for the value to be returned. property-vallen is ignored if the value is being returned as an integer.
property-value
If set to null, specifies that the routine is to return (in property-vallen) the length of the buffer required in to hold the property specified by property-name.

On Exit:

property-vallen
Length of returned string value in the property-value buffer, not including the termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen is set to the required buffer length. property-vallen is not set if the value is being returned as an integer.
property-value
Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer.
status-code
One of:
  • 78-CTF-RET-BUFFER-TOO-SMALL
  • 78-CTF-RET-INVALID-COMP-NAME
  • 78-CTF-RET-INVALID-PROP-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-PROPERTY-NOT-FOUND
  • 78-CTF-RET-SUCCESS
  • 78-CTF-RET-VALUE-NOT-INTEGER

Example:

Acquire a tracer handle to trace "mycomp" component events, and get two "mycomp" property values; one a null-terminated string value, one an integer value:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-id    pic x(7) value "mycomp ".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
01 tracer-handle   pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NAME-NULL-TERM
move length of prop-string to prop-len

call "CBL_CTF_COMP_PROPERTY_GET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop1 "
                                       by reference prop-len
                                       by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE

call "CBL_CTF_COMP_PROPERTY_GET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop2 "
                                       by value 0
                                       by reference prop-integer
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_COMP_PROPERTY_SET

Specifies a value for a component's property.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CTF_COMP_PROPERTY_SET" using by value     flags
                                       by reference component-id
                                       by reference property-name
                                       by reference property-value
                                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bit 0
Value | Meaning
0 | Specify a string value. Use bit 1 to determine the string terminator.
1 | Specify an integer value. Ignore bit 1.
Bit 1
Value | Meaning
0 | String value is space-terminated.
1 | String value is null-terminated.
Bits 2-28
Reserved for future use. Must be 0.
Bit 29
Value | Meaning
0 | property-name is space-terminated.
1 | property-name is null-terminated.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component identifier. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
property-name
Space- or null-terminated (depending on the setting of bit 29) case-insensitive property whose value is to be returned.
property-value
Buffer containing the property value to be set. This is either a pic x( n) field for a value being specified as a string, or a pic x(4) comp-5 field for a value being set as an integer.

On Exit:

status-code
One of:
  • 78-CTF-RET-INVALID-COMP-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-INVALID-PROP-NAME
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

Use CBL_CTF_COMP_PROPERTY_SET to set a named property value for the component identified by component-id. If a property with the same name already exists for the component, its value is replaced with the new value. This routine provides equivalent functionality to the mftrace.comp.component-name#property configuration file entry.

Example:

To acquire a tracer handle to trace "mycomp" component events, and set two "mycomp" property values; one a null-terminated string value, the other an integer value:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-id    pic x(7) value "mycomp ".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-string     pic x(100).
01 tracer-handle   pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NAME-NULL-TERM
move "xxxx" & x"00" to prop-string

call "CBL_CTF_COMP_PROPERTY_SET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop1 "
                                       by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE
move 100 to prop-integer

call "CBL_CTF_COMP_PROPERTY_SET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop2 "
                                       by reference prop-integer
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_DEST

Specifies an output destination by associating (or disassociating) an emitter with (or from) a component or the default emitter list.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CTF_DEST" using by value     flags
                          by reference component-id
                          by reference emitter-name
                             returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
emitter-name | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bit 0
Value | Meaning
0 | Associate the emitter-name with component-id
1 | Disassociate the emitter-name with component-id
Bit 1
Value | Meaning
0 | Inherit emitters from parent.
1 | Do not inherit emitters from parent. This is ignored if bit 0 is set, or if the default emitter list is specified.
Bits 2-27
Reserved for future use. Must be 0.
Bit 28
Value | Meaning
0 | emitter-name is space-terminated.
1 | emitter-name is null-terminated.
Bit 29
Reserved for future use. Must be 0.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component identifier. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
emitter-name
Space- or null-terminated (depending on the setting of bit 28) case-insensitive property whose value is to be returned.

On Exit:

status-code
One of:
  • 78-CTF-RET-EMITTER-NOT-FOUND
  • 78-CTF-RET-INVALID-COMP-NAME
  • 78-CTF-RET-INVALID-EMITTER-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

CBL_CTF_DEST provides equivalent functionality to the mftrace.dest and mftrace.dest.component-name configuration file entries.

There is always at least one entry in the default emitter list. When the last entry is removed from the default list, the TextFile emitter is implicitly added to it. If a component's emitter list becomes empty, it implicitly inherits its parent's emitters even if bit 1 of flags is set indicating that it does not inherit.

Example:

 copy "cbltypes.cpy".
 copy "mfctf.cpy".

 01 component-name  pic x(4).
 01 emitter-name    pic x(10).
 01 flags           pic x(4) comp-5.

*> 1) Add TextFile to the default trace emitter list.

 ...
 move "TextFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD

 call "CBL_CTF_DEST" using by value flags
                          by value 0
                          by reference emitter-name
 ...

*> 2) Remove TextFile from the default trace emitter list.

 ...
 move "TextFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-REMOVE

 call "CBL_CTF_DEST" using by value flags
                           by value 0
                           by reference emitter-name
 ...

*> 3) Associate the BinFile trace emitter with the RTS component.
*>    The RTS component will inherit the default trace emitters.

 ...
 move "RTS" to component-name
 move "ES" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD b-or
                 78-CTF-FLAG-COMPID-STRING

 call "CBL_CTF_DEST" using by value flags
                           by reference component-name
                           by reference emitter-name
 ...

*> 4) Make the BinFile trace emitter the only emitter the
*>    RTS component will use; that is, the RTS component will
*>    not inherit the default trace emitters.

 ...
 move "RTS" to component-name
 move "BinFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD b-or
                 78-CTF-FLAG-DEST-NOINHERIT
                 78-CTF-FLAG-COMPID-STRING

 call "CBL_CTF_DEST" using by value flags
                           by reference component-name
                           by reference emitter-name
 ...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_EMITTER_PROPERTY_GET

Returns a named property value for an emitter.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CTF_EMITTER_PROPERTY_GET" using by value     flags
                                          by reference emitter-name
                                          by reference property-name
                                          by reference property-vallen
                                          by reference property-value
                                             returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bit 0
Value | Meaning
0 | Return a string value. Use bit 1 to determine the string terminator.
1 | Return an integer value. Ignore bit 1.
Bit 1
Value | Meaning
0 | Return the value as a space-terminated string.
1 | Return the value as a null-terminated string.
Bits 2-27
Reserved for future use. Must be 0.
Bit 28
Value | Meaning
0 | emitter-name is space-terminated.
1 | emitter-name is null-terminated.
Bit 29
Value | Meaning
0 | property-name is space-terminated.
1 | property-name is null-terminated.
Bits 30-31
Reserved for future use. Must be 0.
emitter-name
Space- or null-terminated (depending on the setting of bit 28) case-insensitive emitter name.
property-name
Space- or null-terminated (depending on the setting of bit 29) case-insensitive property whose value is to be returned.
property-vallen
Length of the property-value buffer in which the property's value is to be returned. The routine will fail if the buffer is too small for the value to be returned. property-vallen is ignored if the value is being returned as an integer.
property-value
If set to null, specifies that the routine is to return (in property-vallen) the length of the buffer required in to hold the property specified by property-name.

On Exit:

property-vallen
Length of returned string value in the property-value buffer, not including the termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen is set to the required buffer length. property-vallen is not set if the value is being returned as an integer.
property-value
Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer.
status-code
One of:
  • 78-CTF-RET-BUFFER-TOO-SMALL
  • 78-CTF-RET-EMITTER-NOT-FOUND
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-PROPERTY-NOT-FOUND
  • 78-CTF-RET-SUCCESS
  • 78-CTF-RET-VALUE-NOT-INTEGER

Example:

Get two property values associated with the "myemitter" emitter; one a null-terminated string value, one an integer value:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 emitter-name    pic x(10) value "myemitter".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NULL-TERM
move length of prop-string to prop-len

call "CBL_CTF_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "prop1 "
                                    by reference prop-len
                                    by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE

call "CBL_CTF_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "prop2 "
                                    by value 0
                                    by reference prop-integer
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_EMITTER_PROPERTY_SET

Sets a named property value for an emitter.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CTF_EMITTER_PROPERTY_SET" using by value     flags
                                          by reference emitter-name
                                          by reference property-name
                                          by reference property-value
                                             returning

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bit 0
Value | Meaning
0 | String value. Use bit 1 to determine the string terminator.
1 | Integer value. Ignore bit 1.
Bit 1
Value | Meaning
0 | String value is a space-terminated.
1 | String value is a null-terminated.
Bits 2-27
Reserved for future use. Must be 0.
Bit 28
Value | Meaning
0 | emitter-name is space-terminated.
1 | emitter-name is null-terminated.
Bit 29
Value | Meaning
0 | property-name is space-terminated.
1 | property-name is null-terminated.
Bits 30-31
Reserved for future use. Must be 0.
emitter-name
Space- or null-terminated (depending on the setting of bit 28) case-insensitive emitter name.
property-name
Space- or null-terminated (depending on the setting of bit 29) case-insensitive property whose value is to be returned.
property-value
Buffer containing the property value to be set. This is either a pic x(n) field for a value being specified as a string, or a pic x(4) comp-5 field for a value being set as an integer.

On Exit:

status-code
One of:
  • 78-CTF-RET-EMITTER-NOT-FOUND
  • 78-CTF-RET-INVALID-EMITTER-NAME
  • 78-CTF-RET-INVALID-PROPERTY-NAME
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

If a property with the same name already exists for the specified emitter, its value is replaced by the new value.

Example:

To set two property values associated with the "myemitter" emitter; one a null-terminated string value, one an integer value:

copy "cbltypes.cpy".
copy "mfctf.cpy".
01 emitter-name pic x(10) value "myemitter".
01 flags        pic x(4) comp-5.
01 prop-integer pic x(4) comp-5.
01 prop-string  pic x(100).
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NULL-TERM
move "xxx" & x"00" to prop-string
call "CBL_CTF_EMITTER_PROPERTY_SET" using by value flags
                                          by reference emitter-name
                                          by reference "prop1 "
                                          by reference prop-string
...
compute prop-flags = 78-CTF-FLAG-PROP-INT-VALUE
move 100 to prop-integer
call "CBL_CTF_EMITTER_PROPERTY_GET" using by value flags
                                          by reference emitter-name
                                          by reference "prop2 "
                                          by reference prop-integer
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_LEVEL

Specifies the trace level to be used for a specific component, or the default trace level if a component identifier is not specified.

Syntax:

call "CBL_CTF_LEVEL" using by value     flags
                           by value     trace-level
                           by reference component-id
                              returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
trace-level | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bits 0-29
Reserved for future use. Must be 0.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
trace-level
Sets the default trace threshold level. One of:
  • 78-CTF-FLAG-LEVEL-DEBUG
  • 78-CTF-FLAG-LEVEL-INFO
  • 78-CTF-FLAG-LEVEL-WARN
  • 78-CTF-FLAG-LEVEL-ERROR
  • 78-CTF-FLAG-LEVEL-FATAL
component-id
Component whose property value is to be returned. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.

On Exit:

status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-INVALID-TRACE-LEVEL
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

CBL_CTF_LEVEL provides equivalent functionality to the mftrace.level and mftrace.level.component-name configuration file entries.

Example:

 copy "cbltypes.cpy".
 copy "mfctf.cpy".

*> 1) Set the default trace threshold level to be DEBUG

 ...
 call "CBL_CTF_LEVEL" using by value 0
                            by value 78-CTF-FLAG-LEVEL-DEBUG
                            by reference " "
 ...

*> 2) Set the WARNING tracing threshold level for the MF.RTS component.
*>    Any component inheriting from the MF.RTS component (such as
*>    MF.RTS.ERR and MF.RTS.MEM) will also use the WARNING tracing
*>    threshold level. All other trace-enabled components will use the
*>    INFO tracing threshold level.

 ...
 call "CBL_CTF_LEVEL" using by value 0
                            by value 78-CTF-FLAG-LEVEL-INFO
                            by reference " "

 call "CBL_CTF_LEVEL" using by value 0
                            by value 78-CTF-FLAG-LEVEL-WARN
                            by reference "MF.RTS "
 ...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_TRACE

Outputs an event to one or more output destinations.

Syntax:

call "CBL_CTF_TRACE" using by value     flags
                           by reference component-id
                           by reference trace-event
                              returning status-code

Parameters

flags
Call prototype:cblt-x4-comp5
Picture: pic x(4) comp-5.
component-id
Call prototype: pic x(n)
Picture: pic x(n).
trace-event
Group predefined as cblt-trc-event containing:
01 cblt-trc-event              typedef.
  03 cblte-trcevt-version      cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-flags        cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-event-id     cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-level        cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-data-count   cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-event-len    cblt-pointer.	 *> pointer
  03 cblte-trcevt-event-type   cblt-pointer.  *> pointer
  03 cblte-trcevt-event-data   cblt-pointer.  *> pointer
status-code
See Library Routines - Key.

On Entry:

flags
Control flags:
Bits 0-11
Reserved for future use. Must be 0.
Bit 12
Value | Meaning
0 | Output event data only if the component is enabled for tracing, and if the event level specified by cblte-trcevt-level is greater or equal to the tracing level configured for the component.
1 | Force the output of the event if the component is enabled for tracing. cblte-trcevt-level and the tracing level configured for the component are ignored.
Bit 13
Value | Meaning
0 | cblte-trcevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-trcevt-event-len and cblte-trcevt-event-type arrays need to be defined.
1 | cblte-trcevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-trcevt-event-len and cblte-trcevt-event-type need to be defined.
Bits 14-29
Reserved for future use. Must be 0.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component identifier. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
cblte-trcevt-version
Structure version. Must be 0.
cblte-trcevt-flags
Control flags. Must be 0.
cblte-trcevt-event-id
Component-specific event identifier used to identify the type of event being output.
cblte-trcevt-event-level
Tracing level of the event being output.
cblte-trcevt-data-count
Number of trace data items, indicating the number of elements in the cblte-trcevt-event-len, cblte-trcevt-event-type, and cblte-trcevt-event-data arrays. This can be 0.
cblte-trcevt-event-len
Pointer to an array of 4-byte comp-5 items. Each array element indicates the length of the corresponding trace data item in the cblte-trcevt-event-data array. This can be NULL if cblte-trcevt-data-count is 0.
cblte-trcevt-event-type
Pointer to an array of 4-byte comp-5 items. Each array element indicates the type of the corresponding trace data item in the cblte-trcevt-event-data array. This can be NULL if cblte-trcevt-data-count is 0.
Value | Type
0 | Binary
1 | Text (local encoding)
2 | Address
3 | COMP-5
4 | COMP-X
5 | UTF8
6 | Signed COMP-5
7 | Signed COMP-X
Any value other than the ones specified above is treated as type 0 (binary).
cblte-trcevt-event-data
Pointer to an array of pointer items. Each array element addresses a trace data item of the type and length indicated by the corresponding element in the cblte-trcevt-event-type and cblte-trcevt-event-len arrays respectively. This can be NULL if cblte-trcevt-data-count is 0.
For address type items, the array element is the address value; not a pointer to the address value.

On Exit:

status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-INVALID-TRACE-LEVEL
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-NOT-TRACE-ENABLED
  • 78-CTF-RET-NOT-TRACING-LEVEL
  • 78-CTF-RET-OUTPUT-ERROR
  • 78-CTF-RET-SUCCESS

Comments:

CBL_CTF_TRACE() outputs the specified event identified by cblte-trcevt-event-id to one or more output destinations provided that the event level specified in level is greater or equal to that configured for the component.

Example:

copy "cbltypes.cpy".
copy "mfctf.cpy".

78 78-EVENT-TYPE-A      value 1.
78 78-EVENT-TYPE-B      value 2.

01 component-id         pic x(7) value "mycomp ".
01 flags                pic x(4) comp-5.
01 trace-event          cblt-trc-event.
01 trace-event-lengths  pic x(4) comp-5 occurs 1.
01 trace-event-pointers pointer occurs 1.
01 trace-event-types    pic x(4) comp-5 occurs 1.
01 trace-info           pic x(10).
01 tracer-handle        pic x(4) comp-5.

...
move low-values to trace-event

set cblte-trcevt-event-len of trace-event to
    address of trace-event-lengths(1)
set cblte-trcevt-event-type of trace-event to
    address of trace-event-types(1)
set cblte-trcevt-event-data of trace-event
    to address of trace-event-pointers(1)

*> 1) Acquire a tracer handle to trace "mycomp" component events,
*>    then output two informational events; one with event data,
*>    one without.

call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle
...
move 0 to flags
move 78-CTF-FLAG-LEVEL-INFO to cblte-trcevt-level of trace-event
move 78-EVENT-TYPE-A to cblte-trcevt-event-id of trace-event
move 1 to cblte-trcevt-data-count of trace-event
move length of trace-info to trace-event-lengths(1)
move 78-TRACE-EVENT-TYPE-TEXT to trace-event-types(1)
set trace-event-pointers(1) to address of trace-info

call "CBL_CTF_TRACE" using by value flags
                           by reference tracer-handle
                           by reference trace-event
...
move 78-EVENT-TYPE-B to cblte-trcevt-event-id of trace-event
move 0 to cblte-trcevt-data-count of trace-event

call "CBL_CTF_TRACE" using by value flags
                           by reference tracer-handle
                           by reference trace-event
...

*> 2) Output two informational events for the "mycomp" component
*>    without acquiring a tracer handle

...
move 78-CTF-FLAG-COMPID-STRING to flags
move 78-CTF-FLAG-LEVEL-INFO to cblte-trcevt-level of trace-event
move 78-EVENT-TYPE-A to cblte-trcevt-event-id of trace-event
move 1 to cblte-trcevt-data-count of trace-event
move length of trace-info to trace-event-lengths(1)
move 78-TRACE-EVENT-TYPE-TEXT to trace-event-types(1)
set trace-event-pointers(1) to address of trace-info

call "CBL_CTF_TRACE" using by value flags
                           by reference component-id
                           by reference trace-event
...
move 78-EVENT-TYPE-B to cblte-trcevt-event-id of trace-event
move 0 to cblte-trcevt-data-count of trace-event

call "CBL_CTF_TRACE" using by value flags
                           by reference component-id
                           by reference trace-event
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_TRACER_GET

Returns a tracer handle that can be passed to other tracing routines to identify a component.

Syntax:

call "CBL_CTF_TRACER_GET" using by value     flags
                                by reference component-name
                                by reference tracer-handle
                                   returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-name | pic x(n) | pic x(n)
tracer-handle | cblt-x4-comp5 | pic x(4) comp-5
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bits 0-29
Reserved for future use. Must be 0.
Bit 30
Value | Meaning
0 | component-name is space-terminated.
1 | component-name is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Reserved for future use. Must be 0.
component-name
Space- or null-terminated (depending on the setting of bit 30) case-insensitive component identifier string.

On Exit:

tracer-handle
Tracer handle to be specified to the other tracing routines.
status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

Components should call this routine to acquire a tracer handle before performing any tracing operations. The handle acquired by a call to this routine can be used in calls to routines such as CBL_CTF_COMP_PROPERTY_GET, CBL_CTF_COMP_PROPERTY_SET, CBL_CTF_LEVEL, CBL_CTF_DEST, CBL_CTF_TRACER_LEVEL_GET and CBL_CTF_TRACER_NOTIFY.

Note: It is possible to trace events without first acquiring a tracer handle by specifying a component identifier string instead of a tracer handle. However, specifying a component identifier has an impact on performance because the component identifier is validated each time it is used, so we recommend that you use a tracer handle returned from a call to this routine instead.

Example:

To acquire a tracer handle to trace "mycomp" component events:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-name  pic x(7) value “mycomp”.
01 tracer-handle   pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-name
                                by reference tracer-handle
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines


CBL_CTF_TRACER_LEVEL_GET

Returns a tracer's current threshold trace level.

Syntax:

call "CBL_CTF_TRACER_LEVEL_GET" using by value     flags
                                      by reference component-id
                                      by reference trace-level
                                         returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
trace-level | cblt-x4-comp5 | pic x(4) comp-5
status-code | See Library Routines - Key |

On Entry:

flags
Control flags:
Bits 0-29
Reserved for future use. Must be 0.
Bit 30
Value | Meaning
0 | component-id is space-terminated.
1 | component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value | Meaning
0 | component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 | component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component identifier. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
The default trace level is returned if a NULL or empty string is specified.

On Exit:

trace-level
Value indicating the tracer's threshold trace level:
Value | Level
0 | Debug
1 | Info
2 | Warn
3 | Error
4 | Fatal
0xFFFFFFFF | Not enabled for tracing
status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

You typically call this routine before performing any costly trace data formatting that CBL_CTF_TRACE might involve.

If you have used CBL_CTF_TRACER_NOTIFY to install a callback function to process any changes made to the tracer's configuration, you only need to call CBL_CTF_TRACER_LEVEL_GET during trace initialization and in the callback function when the threshold trace level changes.

When a component needs to check for the current threshold trace level it can check the variable into which CBL_CTF_TRACER_LEVEL_GET has previously returned the threshold value.

Example:

To acquire a tracer handle to trace "mycomp" component events, and then use CBL_CTF_TRACER_LEVEL_GET to determine whether the component is configured to trace information level events before performing the trace operation:

copy "cbltypes.cpy".
copy "mfctf.cpy".

78 78-EVENT-TYPE-A      value 1.

01 component-name       pic x(7) value "mycomp".
01 flags                pic x(4) comp-5.
01 trace-event          cblt-trc-event.
01 trace-level          pic x(4) comp-5.
01 tracer-handle        pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-name
                                by reference tracer-handle
...
call "CBL_CTF_TRACER_LEVEL_GET" using by value 0
                                      by reference component-name
                                      by reference trace-level

if 78-CTF-FLAG-LEVEL-INFO >= trace-level
      set up trace-info
      compute flags = 78-CTF-FLAG-LEVEL-INFO

      call “CBL_CTF_TRACE” using by value flags
                                 by reference tracer-handle
                                 by reference trace-event
end-if
...
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Tracing Examples
CBL_CTF_TRACER_NOTIFY
Consolidated Tracing Facility Routines
Consolidated Tracing Facility Return Codes


CBL_CTF_TRACER_NOTIFY

Installs or uninstalls a tracer configuration callback function.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CTF_TRACE_NOTIFY" using by value     install-function
                                  by reference notif-install
                                     returning status-code

Parameters

install-function
Call prototype (see Key):cblt-x4-comp5
Picture: pic x(4) comp-5.
notif-install
Group predefined as cblt-trc-notif-install containing:
01 cblt-trc-notif-install    typedef.
  03 cblte-tni-version       cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-tni-handle        cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-tni-callback      cblt-ppointer. *> procedure pointer
status-code
See Library Routines - Key.

On Entry:

install-function
The operation to be performed:
0 | Install a callback
1 | Uninstall a callback
cblte-tni-version
Parameter block version number. Must be 0.
cblte-tni-handle
Handle of component tracer (returned from a call to CBL_CTF_TRACER_GET) for which a callback is to be installed or uninstalled.
cblte-tni-callback
Callback function to install (if install-function is 0) or uninstall (if install-function is 1).

On Exit:

status-code
One of:
  • 78-CTF-RET-FAILURE
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

A tracer configuration callback function is installed by a component to allow it to be notified when any configuration change to the associated tracer occurs, such as a threshold level change, or property value change.

The interface to the callback function is as follows:

entry "callback-func" using by value     tracer-handle
                            by value     notification-type
                            by reference notification-param

where tracer-handle and notification-type are pic x(4) comp-5 items, and notification-param is a pic x(n). All parameters are input only. The callback function should set return-code to 0 on completion.

Notification Type 0
A property value change has occurred. notification-param is the address of a cblt-trc-notif-prop-change item with the following structure:
Field | Picture | Call Prototype
cblte-tnpc-version | pic x(4) comp-5 | cblt-x4-comp5
cblte-tnpc-flags | pic x(4) comp-5 | cblt-x4-comp5
cblte-tnpc-namelen | pic x(4) comp-5 | cblt-x4-comp5
cblte-tnpc-vallen | pic x(4) comp-5 | cblt-x4-comp5
cblte-tnpc-valint | pic x(4) comp-5 | cblt-x4-comp5
cblte-tnpc-name | pointer | cblt-pointer
cblte-tnpc-value | pointer | cblt-pointer

Version types (cblte-tnpc-version): 0 = structure version

Control flags (cblte-tnpc-flags):
Bit 0
Value | Meaning
0 | Value is a character string.
1 | Value is a pic x(4) comp-5 integer.
Bits 1-31
Reserved for future use.
Notification Type 1
A trace level change has occurred. notification-param is the address of a pic x(4) comp-5 item indicating the new trace level.

Example:

To acquire a tracer handle to trace "mycomp" component events and install a callback to handle threshold level and property change notifications:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-id       pic x(7) value "mycomp".
01 install-params     cblt-trc-notif-install.

linkage section.
01 lk-tracer-handle            pic x(4) comp-5.
01 lk-notif-type               pic x(4) comp-5.
01 lk-notif-param              pic x.
01 lk-notif-param-level        redefines lk-notif-param
                               pic x(4) comp-5.
01 lk-notif-param-property     redefines lk-notif-param
                               cblt-trc-notif-prop-change
....
*>
*> Acquire tracer handle
*>
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle

...

*>
*> Install callback function
*>
move low-values to install-params
move tracer-handle to cblte-tni-handle of install-params
set cblte-tni-callback of install-params to entry "my-callback"

call "CBL_CTF_TRACER_NOTIFY" using by value 0
                                   by reference install-params
...
goback.
*>
*> The callback function to handle trace level and property
*> changes
*>
entry "my-callback" using by value lk-tracer-handle
                          by value lk-notif-type
                          by value lk-notif-param.
evaluate lk-notif-type
    when 78-TRC-NOTIF-TYPE-LEVEL-CHANGE
        ....

    when 78-TRC-NOTIF-TYPE-PROP-CHANGE
        ....
end-evaluate

move 0 to return-code
goback.
Parent topic: Consolidated Tracing Facility Routines
Parent topic: Alphabetical List of Library Routines
Related information
CBL_CTF_TRACER_GET
Consolidated Tracing Facility Routines
Consolidated Tracing Facility Return Codes


Consolidated Tracing Facility Return Codes

Calls to the Consolidated Tracing Facility library routines return one of the following return codes. These return codes are provided in the mftypes.cpy copybook for COBOL programs, and mftypes.h include file for C programs.

Value | Name (COBOL) | Name (C) | Description
-1 | 78-CTF-RET-FAILURE | CTF_RET_FAILURE | Unspecified failure
0 | 78-CTF-RET-SUCCESS | CTF_RET_SUCCESS | Success
1 | 78-CTF-RET-INVALID-TRACE-HANDLE | CTF_RET_INVALID_TRACE_HANDLE | Invalid trace handle specified
2 | 78-CTF-RET-INVALID-TRACE-LEVEL | CTF_RET_INVALID_TRACE_LEVEL | Invalid trace level specified
3 | 78-CTF-RET-NOT-TRACE-ENABLED | CTF_RET_NOT_TRACE_ENABLED | Component not enabled for tracing
4 | 78-CTF-RET-NOT-TRACING-LEVEL | CTF_RET_NOT_TRACING_LEVEL | Specified event level less than threshold level configured for the component
5 | 78-CTF-RET-NOT-ENOUGH-MEMORY | CTF_RET_NOT_ENOUGH_MEMORY | Memory allocation error
6 | 78-CTF-RET-OUTPUT-ERROR | CTF_RET_OUTPUT_ERROR | Error outputting to one or more output destinations
7 | 78-CTF-RET-PROPERTY-NOT-FOUND | CTF_RET_PROPERTY_NOT_FOUND | Property not found
8 | 78-CTF-RET-BUFFER-TOO-SMALL | CTF_RET_BUFFER_TOO_SMALL | Buffer length too small
9 | 78-CTF-RET-VALUE-NOT-INTEGER | CTF_RET_VALUE_NOT_INTEGER | Value is not an integer
10 | 78-CTF-RET-EMITTER-NOT-FOUND | CTF_RET_EMITTER_NOT_FOUND | Emitter not found
11 | 78-CTF-RET-INVALID-EVENT-HANDLE | CTF_RET_INVALID_EVENT_HANDLE | Invalid event handle specified
12 | 78-CTF-RET-ZERO-LENGTH-DATA | CTF_RET_ZERO_LENGTH_DATA | Zero length data specified
13 | 78-CTF-RET-INVALID-PROP-NAME | CTF_RET_INVALID_PROP_NAME | Invalid property name specified
14 | 78-CTF-RET-INVALID-COMP-NAME | CTF_RET_INVALID_COMP_NAME | Invalid component name specified
15 | 78-CTF-RET-INVALID-EMITTER-NAME | CTF_RET_INVALID_EMITTER_NAME | Invalid emitter name specified
16 | 78-CTF-RET-INVALID-PROGRAM-NAME | CTF_RET_INVALID_PROGRAM_NAME | Invalid program name specified
17 | 78-CTF-RET-CALLBACK-NOT-FOUND | CTF_RET_CALLBACK_NOT_FOUND | Callback doesn’t exist
18 | 78-CTF-RET-CALLBACK-EXISTS | CTF_RET_CALLBACK_EXISTS | Callback already exists
19 | 78-CTF-RET-INVALID-FUNCTION-CODE | CTF_RET_INVALID_FUNCTION_CODE | Invalid function code specified
20 | 78-CTF-RET-INVALID-SLOT-ID | CTF_RET_INVALID_SLOT_ID | Invalid slot identifier specified
Parent topic: Consolidated Tracing Facility Routines


Container-Managed Services Routines

  • CBL_SRV_SERVICE_FLAGS_GET
    Enables a program running within a COBOL container as part of a service to determine the service's execution characteristics.
  • CBL_SRV_SERVICE_FLAGS_SET
    Enables a program running within a COBOL container as part of a service to set one or more the service's execution characteristics.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_SRV_SERVICE_FLAGS_GET

Enables a program running within a COBOL container as part of a service to determine the service's execution characteristics.

Syntax:

call CBL_SRV_SERVICE_FLAGS_GET using by reference service-flags
                                        returning status-code

Parameters

service-flags
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

None

On Exit:

service-flags
Service control flags:
Bit 0
Value | Meaning
0 | None
1 | Commit transactional resources during successful service termination
Bit 1
Value | Meaning
0 | None
1 | Rollback transactional resources during successful service termination.
Bits 0 and 1 are treated as a bit pair and only relate to container-managed services. If neither bit is set, at service termination the run-time system will commit transactional resources if the service completes successfully, otherwise it will rollback transactional resources. The API will never return with both bits 0 and 1 set.
Bits 2-30
Reserved for future use
Bit 31
Value | Meaning
0 | The service has not dirtied the COBOL container.
1 | The service has dirtied the COBOL container and will result in the SEP being terminated following service termination.
status-code
0 | Success
1015 | Not running within the COBOL container

Example

copy "cblproto.cpy".

...

78 78-SERVICE-FLAG-COMMIT            value h"00000001".
78 78-SERVICE-FLAG-ROLLBACK          value h"00000002".
78 78-SERVICE-FLAG-DIRTY-CONTAINER   value h"80000000".

01 service-flags   pic x(4) comp-5.

...

call "CBL_SRV_SERVICE_FLAGS_GET" using
                                 by reference service-flags

if return-code = 0
    display "Running as a service" upon console

    if service-flags b-and
       78-SERVICE-FLAG-COMMIT not = 0
        display "Service will commit"
    end-if

    if service-flags b-and
       78-SERVICE-FLAG-ROLLBACK not = 0
        display "Service will rollback"
    end-if

    if service-flags b-and
       78-SERVICE-FLAG-DIRTY-CONTAINER not = 0
        display "Service will dirty the container"
    end-if
else
    display "Not running as a service" upon console
end-if

...
Parent topic: Container-Managed Services Routines
Parent topic: Alphabetical List of Library Routines


CBL_SRV_SERVICE_FLAGS_SET

Enables a program running within a COBOL container as part of a service to set one or more the service's execution characteristics.

Syntax:

call CBL_SRV_SERVICE_FLAGS_SET using by value service-flags-mask
                                     by value service-flags
                                    returning status-code

Parameters

service-flags-mask
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
service-flags
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

service-flags-mask
Mask that specifies the bit flags to be changed:
Bit 0
Value | Meaning
0 | None
1 | Commit transactional resources during successful service termination
Bit 1
Value | Meaning
0 | None
1 | Rollback transactional resources during successful service termination.
service-flags
Service control flags:
Bit 0
Value | Meaning
0 | None
1 | Commit transactional resources during successful service termination
Bit 1
Value | Meaning
0 | None
1 | Rollback transactional resources during successful service termination.

Bits 0 and 1 are treated as a bit pair and only relate to container-managed services. If neither bit is set, at service termination the run-time system will commit transactional resources if the service completes successfully, otherwise it will rollback transactional resources.

Attempting to set both bits 0 and 1 will be treated as an error; attempting to set either bit 0 or bit 1 by an application-managed service will also be treated as an error.

Bits 2-30
Reserved for future use
Bit 31
Value | Meaning
0 | The service has not dirtied the COBOL container.
1 | The service has dirtied the COBOL container and will result in the SEP being terminated following service termination.

On Exit:

status-code
0 | Success
1009 | Invalid parameter passed to the API
1015 | Not running within the COBOL container
1016 | Can only set commit/rollback flags when container managed

Example

copy "cblproto.cpy".

...

78 78-SERVICE-FLAG-COMMIT            value h"00000001".
78 78-SERVICE-FLAG-ROLLBACK          value h"00000002".
78 78-SERVICE-FLAG-DIRTY-CONTAINER   value h"80000000".

01 service-flags        pic x(4) comp-5.
01 service-flags-mask   pic x(4) comp-5.

...

*>
*> Clear the "rollback" flag.
*> Set the "commit" and "dirty container" flags
*>

compute service-flags-mask = 78-SERVICE-FLAG-COMMIT b-or
                             78-SERVICE-FLAG-ROLLBACK b-or
                             78-SERVICE-FLAG-DIRTY-CONTAINER
compute service-flags = 78-SERVICE-FLAG-COMMIT b-or
                        78-SERVICE-FLAG-DIRTY-CONTAINER

call "CBL_SRV_SERVICE_FLAGS_SET" using
                                 by value service-flags-mask
                                 by value service-flags

...
Parent topic: Container-Managed Services Routines
Parent topic: Alphabetical List of Library Routines


Debugging Routines

  • CBL_CREATE_CORE
    Enables a COBOL program to invoke a core dump on demand (that is, without encountering a run-time error).
  • CBL_DEBUGBREAK
    Enables a COBOL program to invoke Animator.
  • CBL_DEBUG_START
    Enables a COBOL program to initiate advanced remote debugging, live recording, or cross-session debugging.
  • CBL_DEBUG_STOP
    Enables a COBOL program to stop or suspend animation, or terminate a live recording.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_CREATE_CORE

Enables a COBOL program to invoke a core dump on demand (that is, without encountering a run-time error).

Syntax:

call "CBL_CREATE_CORE" using by value     flags
                             by value     core-param
                             by reference filename
                             returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5. | pic x(4) comp-5.
core-param | cblt-x4-comp5. | pic x(4) comp-5.
filename |  | pic x(n).
status-code | See Library Routines - Key |

On Entry:

flags
Must be set to zero, which indicates that a core file will be produced.
core-param
Sets the process ID for which to create a core file. A value of zero creates a core file from the current process. If you specify a value other than zero, that running process must be owned by the same user as owns the calling process.
filename

This is a null-terminated string representing the name of the core file.

You can specify the following strings within the filename, which will be substituted when the core file is created.

%%
Single %
%d
The date when the core dump was produced, in the format yyyymmdd
%f
The basename of the program for which the core dump was produced
%p
The process ID of the program for which the core dump was produced
%t
The time when the core dump was produced, in the format hhmmss

If a filename is not supplied (that is, this parameter is set to a NULL pointer), then the core_filename tunable value is used for the name of the file. If that tunable is not set either, the filename defaults to a platform default of core or core.<pid>.

On Exit:

status-code
status-code | Meaning
0 | Success
1 | Bad command line
2 | Invalid process ID
3 | Need to enable full core support
4 | Not supported on this platform
5 | Cannot execute OS core dump command
6 | Cannot create core file
7 | Invalid core file produced

Examples:

The following example will create a core file for the current process. The file will be called "myDump":

01 flags pic x(4) comp-5 value 0.
01 process pic x(4) comp-5 value 0.
01 filename pic x(7) value "myDump" & x"00".
call "CBL_CREATE_CORE" using by value flags
                             by value process
                             by reference filename.

This example will create a core file for COBOL application running in a separate process, though started by the same user, with process id 18655, called "myDump.18655":

01 flags pic x(4) comp-5 value 0.
01 process pic x(4) comp-5 value 18655.
01 filename pic x(100) value "myDump.%p" & x"00".
call "CBL_CREATE_CORE" using by value flags
                             by value process
                             by reference filename.
Parent topic: Debugging Routines
Parent topic: Alphabetical List of Library Routines


CBL_DEBUGBREAK

Enables a COBOL program to invoke Animator.
Restriction: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_DEBUGBREAK"

Parameters:

None.

Comments:

You can use this call to invoke Animator. If the program is not being debugged when it calls CBL_DEBUGBREAK, it starts Animator and then comes to a halt, as if you had been debugging it already and then pressed the interrupt key.

If the program was already being debugged when it called CBL_DEBUGBREAK, then debugging comes to a halt in that debugger, as if you had pressed the interrupt key.

The routine returns a value in RETURN-CODE of 0 if the call was successful, or non-zero if it tried to invoke a debugger but failed.

Parent topic: Debugging Routines
Parent topic: Alphabetical List of Library Routines
Related information
Debugging a CGI Application


CBL_DEBUG_START

Enables a COBOL program to initiate advanced remote debugging, live recording, or cross-session debugging.
Note: This routine is supported for native COBOL only.

Syntax:

CALL "CBL_DEBUG_START" using  by value      flags
                                            timeout
                              by reference  identifier
                              returning     status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
timeout | cblt-os-ssize | pic s9(9) comp-5 or pic s9(18) comp-5 (64-bit native programs only)
identifier |  | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
Controls how animation starts. You can set the following bits:
Bit | Meaning
0 Action if no cross-session or remote Animator process waiting for the specified identifier, and the specified timeout has elapsed.
0
Attempt to match with a cross-session or remote Animator process waiting to attach to any process; if no such process is waiting, start local debugging using character Animator (UNIX only) or Just-In-Time debugging.
1
Return an error status.
1 When debugging should start.
0
Start debugging immediately.
1
Start debugging when the next debuggable entry point is entered; this is the first statement in the next animatable COBOL program called, or the first statement in the next piece of animatable COBOL code called using an ENTRY statement.
2 | Initiates a live recording.
timeout
Timeout, in milliseconds, to wait for a cross-session or remote Animator process to start. A timeout of 0 means do not wait; a timeout of -1 means wait indefinitely.
identifier
A unique string that identifies which waiting Animator process to attach to, or if live recording is active (flags, bit 2), the string identifies the name of the live recording file to be used. The string must be space- or null-terminated.

Comments:

Use this call to initiate remote animation or cross-session animation. If the program is not being debugged when it calls CBL_DEBUG_START, the identifier string is used to work out which Animator process to attach to.

If you want to use advanced remote debugging, set the identifier string to the same value as the unique string provided to your COBOL development system command line that initiates remote debugging.

If you want to use cross session debugging, set the identifier string to the same value as the COBANIMSRV environment variable in the other Animator session.

If you leave the identifier string blank, then standard cross-session animation rules are used as follows:

  • If the COBANIMSRV environment variable is set its value is used as the identifier string.
  • If it is not set, the program attaches to any Animator process started in the same directory.

If there is a corresponding Animator process waiting then the program comes to halt and starts being debugged. The program halts immediately if bit 1 of flags is set. If it is not set, execution halts when the next debuggable entry point is reached.

If there is no corresponding Animator process waiting then the program suspends for the number of milliseconds specified in timeout or until an Animator process starts. A timeout of 0 means the call returns immediately, without suspending. A timeout of -1 causes the program to suspend, without timeout, until the Animator process starts.

If there is still no corresponding Animator process to attach to at the end of the timeout period, then the action depends on the setting of bit 0 of flags. If it is set, then the call returns an error status and execution continues. If it is unset, then a local Animator process is started.

If the program was already being debugged when it called CBL_DEBUG_START, then that debug session, whilst obeying the flags, comes to a halt in Animator - that is, if bit 1 of flags is set to 1, the current session stops when the next debuggable entry point is entered.

The routine returns value 0 if the call was successful, or non-zero if it tried to invoke Animator but failed.

If both the debugging and the live recording flag bits are set when you call CBL_DEBUG_START, live recording takes precedence. If you are already debugging a process that attempts to start live recording, that call will fail; as will a call to start debugging if you are already live recording.

Parent topic: Debugging Routines
Parent topic: Alphabetical List of Library Routines


CBL_DEBUG_STOP

Enables a COBOL program to stop or suspend animation, or terminate a live recording.
Note: This routine is supported for native COBOL only.

Syntax:

CALL "CBL_DEBUG_STOP" using  by value    flags
                               returning status-code

Parameters:

flags
Using call prototype (see Key) : cblt-os-flags
Picture: pic x(4) comp-5 (or pic x(8) comp-5 for 64-bit native programs only)
status-code
See Library Routines - Key

On Entry:

flags
Controls how animation stops. You can set the following bits:
Bit | Meaning
0 | Animator detaches.
1 | Animator terminates.

Comments:

If the process is being recorded by live recorder, the recording process is stopped and the recording file is saved.

If the program is being debugged when it calls CBL_DEBUG_STOP, then animation stops. The effect on Animator and the program that called CBL_DEBUG_STOP depends on the settings of bits 0 and 1 of flags:

Bit 0 | Bit 1 | Meaning
0 | 0 | Execution of the calling program continues without animation until a subsequent event, such as a breakpoint, STOP RUN or CBL_DEBUG_START, is encountered. This is equivalent to pressing Z (for Zoom) in Animator.
0 | 1 | Animator and the calling program both exit. This is equivalent to exiting Animator using the Quit option.
1 | 0 | Animator detaches from the program and waits for a subsequent CBL_DEBUG_START with the same identifier string. Execution of the calling program continues without animation. Note: The detach call is asynchronous, and therefore, there is a risk that the process calls CBL_DEBUG_START again before Animator is back in its wait state. To ensure this does not happen, you can call CBL_DEBUG_START with a timeout of -1 (to wait indefinitely).
1 | 1 | Animator detaches from the program and exits. Execution of the calling program continues without animation. This is equivalent to exiting Animator using the Detach option.

If the program is not being debugged when it calls CBL_DEBUG_STOP, then execution continues as if the routine had not been called.

Parent topic: Debugging Routines
Parent topic: Alphabetical List of Library Routines


Display Attribute Routines

Restriction: These routines are not currently supported in the .NET environment.

These routines enable you to make use of generic attributes -- screen attributes which are portable across different environments and different types of terminals.

Screens displayed from a program using generic attributes are the same or as close as possible whether running on an IBM PC under Windows or a serial terminal under UNIX.

A generic attribute is a single byte which is an index into the generic attribute table. This table contains information about character attributes (for example, bold or underline), foreground color and background color for each of the indexes used. The two color items are in turn indexes into the colormap -- a table of red, green and blue (RGB) values specific to the screen hardware in use.

Colormaps can be read-only or read-write. Read-only colormaps do not allow dynamic changes of RGB values from one color to another; only the colors in the system supplied colormap can be used. Even for read-write colormaps, there is no guarantee that a requested color can be exactly produced by the hardware.

For routines which use a table parameter, you can either pass the first element in the table, or build up the table in dynamically allocated memory and pass its address.

The routines set RETURN-CODE as follows:

0 | Operation successful
1 | Named color not found in color database
2 | Colormap index out of range
3 | Attribute index out of range
4 | No exact match found
5 | Environment does not allow virtual colormap
6 | Could not allocate virtual colormap
7 | No virtual colormap in use

User Attribute Routines

The User attribute is initially off for each program. Once it is enabled, some of the various methods which you can use to display text upon the screen; for example, DISPLAY ... UPON CRT, screen I/O subprograms and the enhanced ACCEPT and DISPLAY syntax all use this attribute. The ANSI form of the DISPLAY and ACCEPT statements (using the UPON CONSOLE phrase) uses the User attribute only if one of the other DISPLAY or ACCEPT methods has been used previously.

The User attribute affects the results of enhanced DISPLAY and ACCEPT syntax operations only once Adis has been requested to set up the attribute. Such a request can be made by performing an enhanced ACCEPT or DISPLAY using an attribute. For example:

     display spaces upon crt with highlight

The User attribute, if turned on, is used when displaying text upon the screen and supersedes any Screen attribute set for the character positions being used in the display.

Use of the X"A7" routine can result in code that is not portable to other environments. You can provide generic color support by using the generic attribute routines.

When using WRITE to CON:, the output always goes directly to the default window.

If the User attribute is not enabled, the Screen attribute currently set for that character position is unaltered.

DISPLAY ... UPON CRT-UNDER forces highlighting if the User attribute is set on. DISPLAY SPACE UPON CRT clears the screen to the User attribute for each screen position.

  • CBL_SCR_ALLOCATE_COLOR
    Finds an entry in the colormap for each of one or more given RGB values.
  • CBL_SCR_ALLOCATE_VC_COLOR
    Sets one or more specified virtual colormap entries to the RGB values supplied.
  • CBL_SCR_CREATE_VC
    Creates a virtual colormap and copies the contents of the system colormap to it.
  • CBL_SCR_DESTROY_VC
    Destroys a virtual colormap, causing the run-time system to revert to using the system colormap.
  • CBL_SCR_GET_ATTR_INFO
    Returns information about the attribute system for the environment.
  • CBL_SCR_GET_ATTRIBUTES
    Gets the character attribute code, and foreground and background colormap indexes for one or more entries in the attribute table.
  • CBL_SCR_NAME_TO_RGB
    Converts a single named color into an RGB value.
  • CBL_SCR_QUERY_COLORMAP
    Returns the RGB value for one or more colormap entries.
  • CBL_SCR_RESTORE
    Restores an area of the character-mode screen previously saved with a call to the CBL_SCR_SAVE call-by-name routine.
  • CBL_SCR_RESTORE_ATTRIBUTES
    Restores the attribute table to the saved values that are associated with the specified buffer handle.
  • CBL_SCR_SAVE
    Saves away an area of the screen (text and attributes) for subsequent restoration.
  • CBL_SCR_SAVE_ATTRIBUTES
    Saves the current settings of the attribute table.
  • CBL_SCR_SET_ATTRIBUTES
    Defines the character attribute, and foreground and background colormap indexes associated with each of one or more COBOL attribute values (attribute table indexes).
  • X"A7" functions 6 and 7
    Reads and sets user attribute.
  • X"A7" function 16
    Turns the user attribute on or off.
  • X"A7" functions 20 and 21
    Reads and sets system attributes.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_SCR_ALLOCATE_COLOR

Finds an entry in the colormap for each of one or more given RGB values.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_ALLOCATE_COLOR" using     table-count
                                        RGB-values
                                        color-attribute
                                        non-exact-match
                              returning status-code

Parameters

table-count
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
RGB-values
Group predefined as cblt-generic-attr-rgb-values containing:
01 cblt-generic-attr-rgb-values  typedef.
  03 cblte-garv-red-value        cblt-x2-compx.	         *> pic x(2) comp-x.
  03 cblte-garv-green-value      cblt-x2-compx. 	        *> pic x(2) comp-x.
  03 cblte-garv-blue-value       cblt-x2-compx.          *> pic x(2) comp-x.
  03 cblte-garv-filler           cblt-x1-compx occurs 2. *> pic x(2).
color-attribute
Call prototype: cblt-x4-compx occurs ntimes
Picture: pic x4 occurs ntimes.
non-exact-match
Call prototype: cblt-x4-compx occurs ntimes
Picture: pic x occurs ntimes.
status-code
See Library Routines - Key.

On Entry:

table-count | The number of colors requested.
 | The table of color(s) to search for or add to the colormap.

On Exit:

color-attribute | The table of indexes to the colormap corresponding to the colors requested. This can be an existing colormap entry, or an unallocated read-write colormap entry set to the requested color.
non-exact-match | The table of flags indicating whether or not the corresponding occurrence of color-attribute represents an exact match. Zero if the match was exact, otherwise nonzero.
table-count | The number of colors successfully allocated. This is normally the number requested but is less if the call was not entirely successful.
RGB-values | The table of RGB values actually used during the search, truncated to suit the environment.
cblte-garv-filler | Unused.

Comments:

The RGB value can either be specified as a literal or be obtained using a call to the CBL_SCR_NAME_TO_RGB routine. The algorithm for determining the nearest match is environment-defined.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_ALLOCATE_VC_COLOR

Sets one or more specified virtual colormap entries to the RGB values supplied.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_ALLOCATE_VC_COLOR" using     table-count
                                           color-attribute
                                           RGB-values
                                 returning status-code

Parameters

table-count
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
color-attribute
Call prototype (see Key): cblt-x4-compx occurs ntimes
Picture: pic x4 occurs ntimes.
RGB-values
Group predefined as cblt-generic-attr-rgb-values containing:
01 cblt-generic-attr-rgb-values  typedef.
  03 cblte-garv-red-value        cblt-x2-compx.	         *> pic x(2) comp-x.
  03 cblte-garv-green-value      cblt-x2-compx. 	        *> pic x(2) comp-x.
  03 cblte-garv-blue-value       cblt-x2-compx.          *> pic x(2) comp-x.
  03 cblte-garv-filler           cblt-x1-compx occurs 2. *> pic x(2).
status-code
See Library Routines - Key.

On Entry:

table-count | The number of colors to allocate.
color-attribute | The table of indexes to the locations in the virtual colormap in which to store the specified RGB values.
RGB-values | The table of color(s) to add to the virtual colormap.

On Exit:

table-count | The number of colors successfully allocated. This is normally the number requested but is less if the call was not entirely successful.
RGB-values | The table of RGB values actually used during the search, truncated to suit the environment.
cblte-garv-filler | Unused.

Comments:

The RGB values can either be specified as a literal or be obtained using a call to the CBL_SCR_NAME_TO_RGB routine.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_CREATE_VC

Creates a virtual colormap and copies the contents of the system colormap to it.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_CREATE_VC" returning status-code

Parameters:

status-code See Library Routines - Key

On Entry:

None

On Exit:

None

Comments:

The run-time system can only have one virtual colormap, and it is used in preference to the system colormap as long as it exists.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_DESTROY_VC

Destroys a virtual colormap, causing the run-time system to revert to using the system colormap.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_DESTROY_VC" returning status-code

Parameters:

status-code See Library Routines - Key

On Entry:

None

On Exit:

None

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_GET_ATTR_INFO

Returns information about the attribute system for the environment.
Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_GET_ATTR_INFO" using      attribute-info
                             returning status-code

Parameters

RGB-values
Group predefined as cblt-generic-attr-rgb-values containing:
01 cblt-generic-attr-information   typedef.
  03 cblte-gai-display-class       cblt-x1-compx.	 *> pic x comp-x.
  03 cblte-gai-colormap-size       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-gai-colormap-flags      cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-gai-bits-per-gun        cblt-x1-compx. 	*> pic x comp-x.
status-code
See Library Routines - Key.

On Entry:

None

On Exit:

cblte-gai-display-class
The class of the environment:
1 | Monochrome
2 | Read-only colormap
3 | Read/write colormap
4 | Read-only decomposed colormap
5 | Read/write decomposed colormap
cblte-gai-colormap-size
Number of entries on the colormap.
cblte-gai-colormap-flags
Bits set as follows:
Bit 0
1 | The colormap is read-write.
0 | The colormap is read-only.
Bit 1
1 | Environment allows virtual colormaps to be created.
0 | Environment does not allow virtual colormaps to be created.
Bit 2
1 | Reading back attributes read back the values written
0 | Read back what is currently on the screen
cblte-gai-bits-per-gun
Number of significant bits of the RGB values that are actually used to drive the hardware. A value of zero indicates that the number of bits is unknown for the environment. If different guns have different numbers of significant bits the lowest number of bits is used.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines
Related information
Display Attribute Routines


CBL_SCR_GET_ATTRIBUTES

Gets the character attribute code, and foreground and background colormap indexes for one or more entries in the attribute table.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_GET_ATTRIBUTES" using     table-count
                                        attribute-index
                                        attribute-value
                              returning status-code

Parameters

table-count
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
attribute-index
Call prototype (see Key): cblt-x1-compx occurs n times.
Picture: pic x comp-x occurs n times.
attribute-value
Group predefined as cblt-generic-attr-value containing:
01 cblt-generic-attr-value           typedef.
  03 cblte-gav-foreground-color-attr cblt-x4-compx. 	        *> pic x(4) comp-x.
  03 cblte-gav-background-color-attr cblt-x4-compx. 	        *> pic x(4) comp-x.
  03 cblte-gav-character-attribute   cblt-x1-compx. 	        *> pic x  comp-x.
  03 cblte-gav-filler                cblt-x1-compx occurs 3. *> pic x(3).
status-code
See Library Routines - Key.

On Entry:

table-count | The number of attribute table entries to query.
attribute-index | The table of indexes of the entries to query.

On Exit:

table-count | The number of entries successfully queried. This is normally the number requested but is less if the call was not entirely successful.
attribute-value | The table of attribute values corresponding to the indexes supplied.
cblte-gav-filler | Unused.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_NAME_TO_RGB

Converts a single named color into an RGB value.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_NAME_TO_RGB" using     color-name
                                     RGB-values
                           returning status-code

Parameters

color-name
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
RGB-values
Group predefined as cblt-generic-attr-rgb-values containing:
01 cblt-generic-attr-rgb-values  typedef.
  03 cblte-garv-red-value        cblt-x2-compx.	         *> pic x(2) comp-x.
  03 cblte-garv-green-value      cblt-x2-compx. 	        *> pic x(2) comp-x.
  03 cblte-garv-blue-value       cblt-x2-compx.          *> pic x(2) comp-x.
  03 cblte-garv-filler           cblt-x1-compx occurs 2. *> pic x(2).
status-code
See Library Routines - Key.

On Entry:

color-name-len | The number of characters in the name.
color-name-buf | The color name to be converted.

On Exit:

RGB-values | The RGB value to which the named color is converted.
filler | Unused.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_QUERY_COLORMAP

Returns the RGB value for one or more colormap entries.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_QUERY_COLORMAP" using     table-count
                                        color-attribute
                                        RGB-values
                              returning status-code

Parameters

table-count
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
color-attribute
Call prototype (see Key): cblt-x4-compx occurs n times
Picture: pic x(4) comp-x occurs n times.
RGB-values
Group predefined as cblt-generic-attr-rgb-values containing:
01 cblt-generic-attr-rgb-values  typedef.
  03 cblte-garv-red-value        cblt-x2-compx.	         *> pic x(2) comp-x.
  03 cblte-garv-green-value      cblt-x2-compx. 	        *> pic x(2) comp-x.
  03 cblte-garv-blue-value       cblt-x2-compx.          *> pic x(2) comp-x.
  03 cblte-garv-filler           cblt-x1-compx occurs 2. *> pic x(2).
status-code
See Library Routines - Key.

On Entry:

table-count | The number of entries to query.
color-attribute | The table of one or more colormap indexes to query.

On Exit:

RGB-values | The table of RGB values corresponding to the table indexes.
table-count | The number of entries successfully queried. This is normally the number requested but is less if the call was not entirely successful.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_RESTORE

Restores an area of the character-mode screen previously saved with a call to the CBL_SCR_SAVE call-by-name routine.

Note: This routine is supported for native COBOL only.

Syntax:

call NoReturnCode "CBL_SCR_RESTORE" using by value     flags
                                                       handle

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5. | pic x(4) comp-5.
handle | cblt-pointer. | usage pointer.

On Entry:

flags | Currently, this must always be zero.
handle | A "save-handle" previously returned by a call to the CBL_SCR_SAVE call-by-name routine. This handle can be NULL, in which case the call does nothing.

On Exit:

handle Is untouched, but invalid. It must not be passed again to CBL_SCR_RESTORE unless it has subsequently been re-assigned a valid "save-handle" by a further call to the CBL_SCR_SAVE routine. We recommend that you set this pointer to NULL immediately on return from CBL_SCR_RESTORE. The area of the screen saved when the call to CBL_SCR_SAVE which returned handle was made is written, in the same position, to the screen.

Comments:

Because the flags parameter is passed BY VALUE, it may be specified as a numeric literal. For example, "BY VALUE 0 SIZE 4".

This call returns no status value. Therefore, it must be called using a suitable call-convention (as suggested in the syntax description) that you have defined in the special-names section. A suitable convention for this purpose is 4.

CBL_SCR_RESTORE has advantages over writing areas of the screen directly:

  • There is no need to have wasteful buffer space allocated in the working-storage section of your program.
  • Using any single-byte attribute method to write the screen (for example CBL_READ_SCR_ATTRS) requires indirection through the Generic Attributes system and thus a best-match guess has to be made for attributes not in the current palette. On certain systems (for example, UNIX, where the default palette is monochrome yet color displays through ADIS are possible) the result of writing the attributes back to the screen can yield very inaccurate results. This call attempts to minimize this effect by actually saving an internal representation of the screen contents and therefore removing the possibility of information loss.
  • This call is very fast.

It is valid to change the mode of the screen (for example, switch the screen to 132-column mode) after saving an area of the screen with CBL_SCR_SAVE providing that the mode is restored to the previous setting before calling CBL_SCR_RESTORE. Failure to do so will result in undefined results.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_RESTORE_ATTRIBUTES

Restores the attribute table to the saved values that are associated with the specified buffer handle.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_RESTORE_ATTRIBUTES" using     handle
                                  returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
handle | cblt-pointer | usage pointer.
status-code | See Library Routines - Key

On Entry:

handle The handle returned on the associated call to CBL_SCR_SAVE_ATTRIBUTES.

On Exit:

None

Comments:

This routine restores the COBOL attribute table to the saved values that are associated with handle. Resources that have been used to save the table are freed.

If the handle is null, the call is ignored. If the handle is invalid or is a handle to a table that has already been restored, results are undefined.

On return, handle is set to null in order to prevent multiple restores of the same attribute table settings.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_SAVE

Saves away an area of the screen (text and attributes) for subsequent restoration.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_SAVE" using by value       flags
                                         top-line
                                         bottom-line
                               returning handle.

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5. | pic x(4) comp-5.
top-line | cblt-x4-comp5. | pic x(4) comp-5.
bottom-line | cblt-x4-comp5. | pic x(4) comp-5.
handle | cblt-pointer. | usage pointer.

On Entry:

flags | Currently, this must always be zero.
top-line | The line nearest the top of the screen of the area to be saved. Line 1 is the top line.
bottom-line | The line nearest the bottom of the screen of the area to be saved. Line 1 is the top line.

The area between the top-line and bottom-line inclusive is saved. Therefore, if top-line and bottom-line are equivalent, a single line of the screen is saved.

Note that specifying zero as a top-line or bottom-line means that parameter will be considered to be the last line on the screen. This saves you from having to know the size of the screen if, for instance, you wished to save the whole screen.

The logical value of top-line must be equal or less than the logical value of bottom-line.

On Exit:

handle Contains either a "save handle", which can be subsequently passed to the CBL_SCR_RESTORE call-by-name routine, or the value NULL, meaning that the save operation could not be performed (because of bad parameters, or possibly lack of memory).

Comments:

Because the three parameters are passed BY VALUE, any or all of them may be specified with numeric literals. For example, "BY VALUE 12 SIZE 4".

CBL_SCR_SAVE has advantages over reading areas of the screen directly:

  • There is no need to have wasteful buffer space allocated in the working-storage section of your program.
  • Using any single-byte attribute method to write the screen (for example CBL_READ_SCR_ATTRS) requires indirection through the Generic Attributes system and thus a best-match guess has to be made for attributes not in the current palette.
  • This call is very fast.

If handle is not subsequently passed to the CBL_SCR_RESTORE routine, any core memory that may have been allocated to save the screen information in will be lost. Repeated failure to call CBL_SCR_RESTORE with handles returned will therefore result in a memory leak.

It is invalid to pass handle to any routine other than CBL_SCR_RESTORE.

Examples:

To save the screen in its entirety, whatever its size:

call "CBL_SCR_SAVE" using by value 0 size 4
                                   1 size 4
                                   0 size 4
                         returning handle.

To save just the last line of the screen:

call "CBL_SCR_SAVE" using by value 0 size 4
                                   0 size 4
                                   0 size 4
                         returning handle.

To save the top three lines of the screen:

call "CBL_SCR_SAVE" using by value 0 size 4
                                   1 size 4
                                   3 size 4
                         returning handle.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_SAVE_ATTRIBUTES

Saves the current settings of the attribute table.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_SAVE_ATTRIBUTES" using     handle
                               returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
handle | cblt-pointer | usage pointer.
status-code | See Library Routines - Key

On Entry:

None

On Exit:

handle The handle of the internal buffer used to save the attributes.

Comments:

This routine saves the current COBOL attribute table in an internal buffer. The handle is set to a value that identifies this buffer, and no meaning should be attached to the value of handle.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


CBL_SCR_SET_ATTRIBUTES

Defines the character attribute, and foreground and background colormap indexes associated with each of one or more COBOL attribute values (attribute table indexes).

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_SET_ATTRIBUTES" using      table-count
                                         attribute-index
                                         attribute-value
                               returning status-code

Parameters

table-count
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
attribute-index
Call prototype (see Key): cblt-x1-compx occurs n times.
Picture: pic x comp-x occurs n times.
attribute-value
Group predefined as cblt-generic-attr-value containing:
01 cblt-generic-attr-value           typedef.
  03 cblte-gav-foreground-color-attr cblt-x4-compx.         	*> pic x(4) comp-x.
  03 cblte-gav-background-color-attr cblt-x4-compx.         	*> pic x(4) comp-x.
  03 cblte-gav-character-attribute   cblt-x1-compx.         	*> pic x  comp-x.
  03 cblte-gav-filler                cblt-x1-compx occurs 3.	*> pic x(3).
status-code
See Library Routines - Key.

On Entry:

table-count | The number of attributes to set.
attribute-index | The table of indexes in the attribute table.
attribute-value | The table of attribute descriptions corresponding to the table of indexes.

On Exit:

table-count | The number of attributes successfully set. This is normally the number requested but is less if the call was not entirely successful.
cblte-gav-filler | Unused.
Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


X"A7" functions 6 and 7

Reads and sets user attribute.
Restriction: This routine is supported in native COBOL only.

Syntax:

call x"A7" using     function-code
                     user-attribute
           returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
user-attribute | cblt-x1-compx | pic x comp-x.
status-code | See Library Routines - Key

On Entry:

function-code
Defines the action:
6 | Read user attribute
7 | Set user attribute
user-attribute
For function 7, the value to set the user attribute.

On Exit:

user-attribute
For function 6, the value of the current user attribute.

Comments:

You should use the same caution when using this routine as when using any other, using only regular COBOL syntax wherever possible.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


X"A7" function 16

Turns the user attribute on or off.
Restriction: This routine is supported in native COBOL only.

Syntax:

call x"A7" using function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx | pic x comp-x.

On Entry:

function-code
Value 16.
parameter
Indicates the action wanted:
0 | Turns the user attribute on
1 | Turns the user attribute off

On Exit:

None

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


X"A7" functions 20 and 21

Reads and sets system attributes.
Restriction: This routine is supported in native COBOL only.

Syntax:

call X"A7" using     function-code
                     sys-attr-array
           returning status-code

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
sys-attr-array
Group containing:
01 sys-attr-array
  03 sys-attr   cblt-x1-compx occurs 16   *> pic x comp-x occurs 16 times.
status-code
See Library Routines - Key

On Entry:

function-code
Defines the action:
20 | Read system attributes
21 | Set system attributes
sys-attr-array
Contains the system attributes to set. The attributes are used for:
sys-attr-1 | Invisible
sys-attr-2 | Reverse video
sys-attr-3 | Normal
sys-attr-4 | Highlighted
sys-attr-5 | Normal underlined
sys-attr-6 | Highlighted underlined
sys-attr-7 | System normal
sys-attr-8 | Flashing highlighted
sys-attr-9 | Unused
sys-attr-10 | User reverse
sys-attr-11 | User normal
sys-attr-12 | User highlighted
sys-attr-13 | Unused
sys-attr-14 | Unused
sys-attr-15 | Unused
sys-attr-16 | Operating system normal

On Exit:

sys-attr-array
Contains the system attributes read.

Comments:

System attributes are used by some parts of the system to display screens in various colors or shades (depending on the type of screen). This means that by changing the system attributes, you can colorize displays to a particular choice. These calls can be used if you use components such as Panels which require attribute values as part of their parameters.

If you want to alter any of the attributes you should first read the current setting of the attributes, update the attribute array with any changes you want to make and then set the attributes. Doing things this way ensures that you do not affect the settings of any of the attributes which you are not interested in.

Parent topic: Display Attribute Routines
Parent topic: Alphabetical List of Library Routines


Enhanced ACCEPT and DISPLAY Syntax Routines

These routines affect the behavior of the enhanced ACCEPT and DISPLAY statements in a program. Enhanced ACCEPT and DISPLAY statements are handled by a run-time system module called Adis.

  • X"AF" function 1
    Sets various configurable features of Adis, including enabling or disabling individual user function, Adis or data keys, or a series of consecutive keys at run-time.
  • X"A7" function 18
    Makes console I/O redirectable.
  • X"AF" function 22
    Sounds the terminal alarm.
  • X"AF" function 26
    Gets a character from the keyboard.
  • X"AF" Function 81
    Enables SCREEN SECTION ACCEPT and DISPLAY statements to inherit Keisen attributes written by preceding CBL_ calls.
Parent topic: Library Routines


X"AF" function 1

Sets various configurable features of Adis, including enabling or disabling individual user function, Adis or data keys, or a series of consecutive keys at run-time.

Syntax:

call x"AF" using function-code
                 parameter-block

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter-block
Group containing:
01 parameter-block
  03 key-setting    cblt-x1-compx   *> pic x comp-x.
  03 sub-fn-code    cblt-x1-compx   *> pic x comp-x.
  03 first-key-id   cblt-x1-compx   *> pic x comp-x.
  03 number-of-keys cblt-x1-compx   *> pic x comp-x.

On Entry:

function-code
Value 1.
sub-fn-code
One of:
1 | Enable/disable user function keys and compatibility keys
2 | Enable/disable Adis control keys and other configurables
3 | Enable/disable data keys
4 | Enable/disable shift keys
5 | Enable/disable lock keys

On Exit:

parameter
Bit settings indicating the type of screen as follows:

Comments:

Features are enabled or disabled until explicitly changed by another call to x"AF" or until the application terminates. The initial state of user function keys depends on the run-time operating system (see Standard Adis Key Functions for details). Calls to enable or disable functions keys are additive. For example, if you call x"AF" to enable function key F1 and then make another call to enable F10, both keys are enabled.

See Enhanced ACCEPT/DISPLAY Syntax for full details of the Adis features and parameters.

Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Alphabetical List of Library Routines


X"A7" function 18

Makes console I/O redirectable.

Syntax:

call X"A7" using function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx | pic x comp-x.

On Entry:

function-code
Value 18
parameter
Action to perform:
0 | Disable DOS-style console I/O
1 | Enable DOS-style console I/O

On Exit:

None

Comments:

Normally the run-time system uses the BIOS to read the keyboard, and writes direct to the video map for all displays. This routine makes the run-time system use operating system functions instead. This means the operator can use the operating system facilities for re-directing keyboard input and screen output.

Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


X"AF" function 22

Sounds the terminal alarm.

Syntax:

call x"AF" using function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
parameter | pic x | pic x

On Entry:

function-code | Value 22.
parameter | Reserved

On Exit:

None

Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


X"AF" function 26

Gets a character from the keyboard.

Syntax:

call x"AF" using function-code
                 key-status

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
key-status
Group containing:
01 key-status
  03 key-type    pic x.         *> pic x.
  03 key-code-1  cblt-x1-compx  *> pic x comp-x.
  03 key-code-2  cblt-x1-compx  *> pic x comp-x.

On Entry:

function-code
Value 26.

On Exit:

key-type
The type of key read, as follows:
1 | User-defined function key
2 | Adis function key
3 | Data key
9 | Error
key-code-1
When key-type is 1 or 2, contains the number of the key; 0-127 for user-defined and 0-39 for Adis. See the chapter Adis Configuration Utility (AdisCF) in your Programmer's Guide to Creating User Interfaces for more details on function keys.

When key-type is 3, contains the ASCII code of the key pressed.

When key-type is 9, contains an error code:
8 | A disabled character has been keyed, and key-code-2 contains the character.
9 | An invalid keystroke (more than one byte) has occurred.

Comments:

This routine also causes the COBOL screen handling system to be invoked.

Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Alphabetical List of Library Routines


X"AF" Function 81

Enables SCREEN SECTION ACCEPT and DISPLAY statements to inherit Keisen attributes written by preceding CBL_ calls.

This function enables SCREEN SECTION ACCEPT and DISPLAY statements to inherit Keisen attributes written by preceding CBL_ calls.

Syntax:

call x"AF" using function-code
                 parameter

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter
Call prototype: cblt-x1-compx
Picture: pic x comp-x.

On Entry:

function-code
Value 81
parameter
Action to perform:
0 | Prevent Keisen attributes being inherited
1 | Enable Keisen attributes to be inherited

On Exit:

None

Comments:

To use this function, you must add the following code to your program.

In the Working Storage section:

78 Inherit-Keisen value 81.
01 adis-function  pic 99 comp-x.
01 adis-flag-on   pic 99 comp-x value 1.
01 adis-flag-off  pic 99 comp-x value 0.

In the Procedure division:

MOVE Inherit-Keisen TO adis-function
CALL X"AF" USING adis-function adis-flag-on
Parent topic: Enhanced ACCEPT and DISPLAY Syntax Routines
Parent topic: Alphabetical List of Library Routines


Exit and Error Procedure Routines

The exit and error procedure routines enable you to register your own routines which are executed by the run-time system when your application terminates, either normally or abnormally.

  • CBL_ERROR_PROC
    Installs or removes an error procedure to be invoked automatically when a run-time system error occurs.
  • CBL_EXIT_PROC
    Installs or removes a closedown procedure to be invoked automatically when the application terminates.
  • CBL_GET_EXIT_INFO
    Enables an application to determine under what circumstances an exit procedure has been invoked.
  • CBL_RUNTIME_ERROR
    Forces the application to terminate with a run-time error condition.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_ERROR_PROC

Installs or removes an error procedure to be invoked automatically when a run-time system error occurs.

Syntax:

call "CBL_ERROR_PROC" using     install-flag
                                install-addrs
                      returning status-code

Parameters:

install-flag
Call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
install-addrs
Call prototype (see Key): cblt-ppointer
Picture: usage procedure-pointer.
status-code
See Library Routines - Key

On Entry:

install-flag
The operation to be performed:
0: Install error procedure
1: De-install error procedure
install-addrs
Address of error procedure to install or de-install.

On Exit:

None

Comments:

In the .NET environment, error procedures are only executed for an RTS exception that has not been handled by the application.

You can install several error procedures for an application by repeated calls of this routine.

Once an error procedure has been posted, subsequent attempts to install that error procedure are silently ignored until it is removed either implicitly (for example, during error processing) or explicitly (by calling CBL_ERROR_PROC with install-flag set to "1").

An error procedure can be written in any language. If it is in COBOL, install-addrs must be the address of an entry point. You can obtain this address using the statement:

  set install-addrs to entry entry-name

An error procedure in COBOL can include any legal COBOL, including CALL statements.

When an error occurs the installed procedures are executed, starting with the most recently installed and ending with the first one installed. When all have been processed, the RTS error handling procedure is then started.

If you don't want any other error procedures, including the run-time system error handling, to be executed after terminating your error procedure, set RETURN-CODE to zero.

If a program containing an error procedure is canceled, the error procedure is removed.

An error procedure installed in one program can be removed by another program.

An error procedure can install an error procedure.

If an error procedure is installed during error processing (either by itself, or by another error procedure) then it is executed when the error procedure that installed it returns, assuming that it doesn't return with a ZERO return code.

If an RTS error occurs in an error procedure, the procedure is terminated. The RTS then processes the new RTS error, starting with the next error procedure, if there is one.

You must ensure that the procedure-pointer you use to install the procedure is valid.

An error procedure belongs to the run-unit from which it was installed. So the error procedure is executed only by the run-unit that installed it.

Pressing interrupt does not cause any error procedures to be called.

If the error procedure is defined as an entry point in a program that itself could give an error, you must ensure that the program has a Local-Storage Section. This ensures that the program is reentrant and the run-time system will not give error 166 ("Recursive COBOL call is illegal") when trying to execute the error procedure.

Parameter Passed to the Error Procedure

When an installed error procedure is called, the characters containing the relevant RTS error message is passed as a parameter.

You should define this parameter in the Linkage Section as PIC X(325), and include it in the USING phrase of the entry to the error procedure. An example of the RTS error message string follows:
Load Error : file 'prog-name'\n
error code: 173, pc=0, call=-1, seg=0\n
173  Called program file not found in drive/directory\n\0
where \n is a new-line character and \0 is a null (x"00") terminator. This format is described in your Error Messages.
Example
The following is an example of installing an error procedure, and the skeleton of the error procedure that is called if an error occurs.
 working-storage section.
 01 install-flag     pic x comp-x value 0.
 01 install-address  usage procedure-pointer.
 01 status-code      pic 9(4) comp value zeros.

 local-storage section.

 linkage section.
 01 err-msg  pic x(325).

 procedure division.
     set install-address to entry "err-proc".
     call "CBL_ERROR_PROC" using  install-flag
                                  install-address
                                  returning status-code.

 ...
 ...

* Error procedure:
 entry "err-proc" using err-msg.

* Process err-msg to find out the error number.
* Act accordingly.
 ...

* Terminate, but allow other error procedures to be executed.
     move 1 to return-code
     exit program
     stop run.
Parent topic: Exit and Error Procedure Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Exit and Error Procedure Routines


CBL_EXIT_PROC

Installs or removes a closedown procedure to be invoked automatically when the application terminates.

Syntax:

call "CBL_EXIT_PROC" using     install-flag
                               install-params
                     returning status-code

Parameters

install-flag
Call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
install-params
Group predefined as cblt-exit-params containing:
01 cblt-exit-params            typedef.
  03 cblte-ep-install-addr     cblt-ppointer.	*> usage procedure-pointer.
  03 cblte-ep-install-priority cblt-x1-compx.	*> pic x comp-x
status-code
See Library Routines - Key.

On Entry:

install-flag
The operation to be performed:
0 | Install closedown procedure with default priority of 64
1 | De-install closedown procedure
2 | Query priority of installed closedown procedure
3 | Install closedown procedure with given priority
cblte-ep-install-addrs
Address of closedown procedure to install, de-install or query.
cblte-ep-install-priority
When install-flag is 3, contains the priority of the closedown procedure being installed, in range 0 to 127. Otherwise, ignored.

On Exit:

cblte-ep-install-priority
When install-flag is set to 2, returns the priority of the selected procedure.

Comments:

The installed closedown procedure is executed whether the application finishes normally (with a STOP RUN) or abnormally (for example, with a keyboard interrupt or RTS error). You can install several closedown procedures for an application by repeated calls of this routine.

A closedown procedure can be written in any language. If it is in COBOL, cblte-ep-install-addrs must be the address of an entry point. You can obtain this address using the statement:

  set install-addrs to entry "entry-name"

A closedown procedure in COBOL can include any legal COBOL, including call statements. The closedown procedure terminates when the main program in the procedure executes an EXIT PROGRAM or GOBACK or when a STOP RUN statement is executed.

A closedown procedure does not have any parameters passed to it when it is called.

Every closedown procedure installed has a priority. This priority determines the order in which the procedures are executed - procedures with the lowest values are processed first. If several procedures have the same priority, they are executed in reverse order of installation - that is the last one installed is executed first.

Procedures installed without a priority (install-flag = 0) are given the default priority of 64. To set your own priority, set install-flag = 3 and set the priority to a value in the range 0 to 127. Priorities 128 to 256 are reserved for use by the COBOL system. You must not set a priority higher than 127 unless your program is a user-written file handler, in which case it must be 200.

If a closedown procedure has already been installed, an attempt to install again fails. However, if the priority used on the second attempt is different to that used when it was installed, its priority is changed. RETURN-CODE is set to zero.

Use install-flag = 2 to find the priority of a previously installed procedure. This returns the priority in cblte-ep-install-priority if it is found The procedure is identified by its cblte-ep-install-addrs. If the procedure cannot be found, RETURN-CODE is set nonzero.

Parent topic: Exit and Error Procedure Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_EXIT_INFO

Enables an application to determine under what circumstances an exit procedure has been invoked.

Syntax:

call "CBL_GET_EXIT_INFO" using     param-block
                         returning status-code

Parameters

param-block
Group predefined as cblt-exit-info-params containing
01 cblt-exit-info-params    typedef.
  03 cblte-gei-size         cblt-x4-comp5. 	*> pic x(4) comp-5 value 16.
  03 cblte-gei-return-code  cblt-x4-comp5. 	*> pic x(4) comp-5.
  03 cblte-gei-rts-error    cblt-x4-comp5. 	*> pic x(4) comp-5.
  03 cblte-gei-exit-flags   cblt-x4-comp5. 	*> pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

cblte-gei-size
The size of parameter block including this field (must be set to 16).

On Exit:

cblte-gei-return-code
Current value of RETURN-CODE.
cblte-gei-rts-error
Error number of the run-time system error that caused termination (zero if none).
cblte-gei-exit-flags
A 32-bit word providing additional termination information:
Bit 0
0 | Not running under Debugger
1 | Running under Debugger
Bit 1
Escaped from Debugger
Bit 2
Terminated due to STOP RUN
Bit 3
0 | Terminated in COBOL
1 | Terminated in non-COBOL
Bit 4
Terminated due to the interrupt key being pressed (for example, CTRL+C), or some other similar mechanism for terminating a program
Bit 5
Exit procedure invoked during thread termination
Bits 6-31
Reserved for future use - set to 0
status-code
0 | Success.
1006 | API called from outside of exit procedure.
1009 | Invalid parameter passed to API.

Comments:

This routine must only be called from within an exit procedure that has been installed using CBL_EXIT_PROC.

A typical use of this routine would be in database applications which need to be able to determine under what circumstances an exit procedure has been invoked. Database applications would typically need to be able to determine whether the exit procedure had been invoked due to a normal or abnormal run-time system termination. This routine would enable them to decide whether to commit or rollback.

Parent topic: Exit and Error Procedure Routines
Parent topic: Alphabetical List of Library Routines


CBL_RUNTIME_ERROR

Forces the application to terminate with a run-time error condition.

Syntax:

CALL “CBL_RUNTIME_ERROR”  using by value error-flags
                                by reference error-message

Parameters:

 | Using call prototype (see Key) | Picture
error-flags | cblt-x4-comp5 | pic x(4) comp-5.
error-message | pic x(n) | pic x(n).

On Entry:

error-flags | Must be zero.
error-message | An optional null-terminated error message to be outputted after a run-time message. To produce no additional message, pass the reserved word OMITTED instead.

On Exit:

None.

Comments:

The call will terminate the application with a run-time error COBRT150 Program abandoned at user request, with the error-message text appended, if supplied.

Parent topic: Exit and Error Procedure Routines
Parent topic: Alphabetical List of Library Routines


File and Filename Routines

The File and Filename routines enable you to manipulate filenames.

A filename is split up into three discrete parts: path, basename and extension. Using the following example - d:\dir1\dir2\file.dat - the path is d:\dir1\dir2, the basename is file, and the extension is dat.

Filenames can be either space-terminated or null-terminated. Space-terminated filenames are terminated by a space character, and if they contain any embedded spaces, the whole filename should be enclosed in double quotation marks. Null-terminated filenames have any double quotes stripped out, but retain any embedded spaces.

The routines in this section can work with filenames up to 65,535 characters long, but your environment and run-time system will impose a limit on what filename lengths can actually be used on a file system.

  • CBL_CFGREAD_DYNFH
    The CBL_CFGREAD_DYNFH option determines whether the File Handler should reread its configuration file for configurable custom file handlers.
  • CBL_CFGREAD_EXTFH
    Forces the File Handler to reread its configuration file.
  • CBL_CHANGE_DIR
    Changes the current directory.
  • CBL_CHECK_FILE_EXIST
    Checks whether a file exists and if it does, returns details of when the file was last modified.
  • CBL_COPY_FILE
    Copies a file.
  • CBL_CREATE_DIR
    Creates a subdirectory.
  • CBL_DELETE_FILE
    Deletes a file.
  • CBL_DELETE_DIR
    Deletes a directory. The directory is deleted only if it is empty.
  • CBL_DIR_SCAN_END
    Terminates a search operation.
  • CBL_DIR_SCAN_READ
    Searches for the next entry in the file system using a search handle returned by a previous CBL_DIR_SCAN_START.
  • CBL_DIR_SCAN_START
    Initializes a search for a file or directory.
  • CBL_GET_CURRENT_DIR
    Returns the current directory.
  • CBL_FILENAME_CONVERT
    Converts a filename between space-terminated and null-terminated format.
  • CBL_FILENAME_MAX_LENGTH
    Returns the maximum size of a filename that the run-time system and the current operating system can handle. This size does not include any terminators (null or space).
  • CBL_JOIN_FILENAME
    Forms a filename by joining together its component parts; that is, the pathname, basename and extension.
  • CBL_LOCATE_FILE
    This routine has two uses. It can be used to expand an environment variable in a file specification, where the environment variable contains a list of several paths. It can also determine whether an OPEN INPUT statement using a particular file specification finds the file in a library file or as a separate disk file.
  • CBL_RENAME_FILE
    Changes the name of a file.
  • CBL_SPLIT_FILENAME
    Splits a filename into its component parts; that is, the pathname, basename and extension.
  • mFFH
    Initializes the File Handler.
  • MFFH_MODIFY_DISABLE
    Disables all File Handler trace modification set by previous MFFH_MODIFY_TRACE calls.
  • MFFH_MODIFY_TRACE
    Modifies some FCD fields, to save directly accessing the FCD. You can use this call whether you are issuing standard COBOL I/O statements or calling the File Handler explicitly using the API.
  • PC_FIND_DRIVES
    Returns all valid drives on a PC.
  • PC_READ_DRIVE
    Returns the current default drive letter.
  • PC_SET_DRIVE
    Sets the default drive letter.
  • X"91" function 46
    Enables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.
  • X"91" function 47
    Disables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.
  • X"91" function 48
    Enables insertion of tab characters in line sequential files.
  • X"91" function 49
    Disables insertion of tab characters in line sequential files.
  • Interpreting the return code as a file status code
  • Filename Routines - Example
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_CFGREAD_DYNFH

The CBL_CFGREAD_DYNFH option determines whether the File Handler should reread its configuration file for configurable custom file handlers.
Restriction: This routine is supported in native COBOL only.

By calling CBL_CFGREAD_DYNFH when the environment variable DYNREDIR is set to DYNCONFIG, the File Handler is forced to reread the configuration file.

Syntax:

call "CBL_CFGREAD_DYNFH"

On Exit:

The return code is set to a non-zero value if errors occurred.

Comments:

When the File Handler rereads the configuration file, it ignores any striping parameters in the file.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related reference
Configuration File


CBL_CFGREAD_EXTFH

Forces the File Handler to reread its configuration file.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_CFGREAD_EXTFH" using     filename
                      returning status-code

Parameters:

filename | pic x(n).
status-code | See Library Routines - Key

On Entry:

filename The file to look for. The name can contain a path, and must be terminated by a space. If the filename is null (x"00"), the File Handler looks for the file using the standard search order (see the topic Searching Conventions Used for Calling Programs).

On Exit:

None.

Comments:

When the File Handler rereads the configuration file, it ignores any striping parameters in the file.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_CHANGE_DIR

Changes the current directory.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_CHANGE_DIR" using     pathname
                      returning status-code

Parameters:

pathname | pic x(n).
status-code | See Library Routines - Key

On Entry:

pathname Relative or absolute pathname terminated by space or null (x"00"). This must be no longer than the number of characters allowed by your operating system and must be valid from the directory that is current when the routine is called.

On Exit:

None.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_CHECK_FILE_EXIST

Checks whether a file exists and if it does, returns details of when the file was last modified.

Syntax:

call "CBL_CHECK_FILE_EXIST"  using    filename
                                      file-details
                            returning status-code

Parameters

filename
Picture: pic x(n).
file-details
Group predefined as cblt-fileexist-buf containing
01 cblt-fileexist-buf        typedef.
  03 cblte-fe-filesize       cblt-x8-compx. *> pic x(8) comp-x.
  03 cblte-fe-date.
    05 cblte-fe-day          cblt-x1-compx. *> pic x comp-x.
    05 cblte-fe-month        cblt-x1-compx. *> pic x comp-x.
    05 cblte-fe-year         cblt-x2-compx. *> pic x(2) comp-x.
  03 cblte-fe-time.
    05 cblte-fe-hours        cblt-x1-compx. *> pic x comp-x.
    05 cblte-fe-minutes      cblt-x1-compx. *> pic x comp-x.
    05 cblte-fe-seconds      cblt-x1-compx. *> pic x comp-x.
    05 cblte-fe-hundreths   cblt-x1-compx. *> pic x comp-x.
status-code
See Library Routines - Key.

On Entry:

filename
The file to look for. The name can contain a path, and is terminated by a space. If no path is given, the current directory is assumed.

This routine does not work with filenames containing wildcard characters.

On Exit:

cblte-fe-filesize
The size of the file in bytes.
cblte-fe-filedate
The date the file was created.
cblte-fe-filetime
The time the file was created.

Comments:

CBL_CHECK_FILE_EXIST is not stripe-aware. If you use this routine on a file for which striping is enabled, the details returned refer to the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

You can check the success of the call by examining RETURN-CODE.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
Interpreting the return code as a file status code
File and Filename Routines


CBL_COPY_FILE

Copies a file.

Syntax:

call "CBL_COPY_FILE" using     filename1
                               filename2
                     returning status-code

Parameters:

filename1
pic x(n).
filename2
pic x(n).
status-code
See Library Routines - Key

On Entry:

filename1
The file to copy. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed.
filename2
The name of the new file. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed.

On Exit:

None.

Comments:

This routine does not work with filenames containing wildcard characters.

CBL_COPY_FILE is not stripe-aware. If you use this routine on a file for which striping is enabled, the details returned refer to the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

You can check the success of the call by examining RETURN-CODE. See the topic Interpreting the Return Code as a File Status Code for more details.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Interpreting the return code as a file status code
File and Filename Routines


CBL_CREATE_DIR

Creates a subdirectory.

Syntax:

All the directories in the given path, except the last, must already exist.

call "CBL_CREATE_DIR" using     pathname
                      returning status-code

Parameters:

pathname
pic x(n).
status-code
See Library Routines - Key

On Entry:

pathname
Relative or absolute pathname terminated by space or null (x"00").

On Exit:

None.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
File and Filename Routines


CBL_DELETE_FILE

Deletes a file.

Syntax:

call "CBL_DELETE_FILE" using     filename
                       returning status-code

Parameters:

filename | pic x(n).
status-code | See Library Routines - Key

On Entry:

filename The file to delete. The name can contain a pathname, and is terminated by a space. If no path is given, the current directory is assumed.

This routine does not work with filenames containing wildcard characters.

On Exit:

None.

Comments:

You cannot use wildcard characters in filenames.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

CBL_DELETE_FILE is not stripe-aware. If you use this routine on a file for which striping is enabled, the details returned refer to the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration of your File Handling book..

You can check the success of the call by examining RETURN-CODE. See the topic Interpreting the Return Code as a File Status Code for more details.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_DELETE_DIR

Deletes a directory. The directory is deleted only if it is empty.

Syntax:

call "CBL_DELETE_DIR" using      pathname
                      returning status-code

Parameters:

pathname | pic x(n).
status-code | See Library Routines - Key

On Entry:

pathname Relative or absolute pathname terminated by space or null (x"00").

On Exit:

None.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_DIR_SCAN_END

Terminates a search operation.

Syntax:

CALL "CBL_DIR_SCAN_END" using  by reference   handle
                                  returning   search-status

Parameters:

handle
Usage pointer
search-status
See Library Routines - Key

On Entry:

handle
Set by CBL_DIR_SCAN_START. This field identifies the search operation that is to be terminated.

On Exit:

handle
Undefined
search-status
Return status:
0 | Success
1 | Unable to start search
2 | Invalid search handle
3 | Search finished
127 | Other error

Comments:

You must call CBL_DIR_SCAN_END to release system resources. You might be unable to start additional searches if you fail to release resources at the end of a scan operation.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
CBL_DIR_SCAN_START
CBL_DIR_SCAN_READ


CBL_DIR_SCAN_READ

Searches for the next entry in the file system using a search handle returned by a previous CBL_DIR_SCAN_START.

Syntax:

CALL "CBL_DIR_SCAN_READ" using  by reference   handle
                                               entry
                                   returning   search-status

Parameters:

handle
usage pointer.
entry
Group item containing the following subordinate items:
01 entry-data.
        03 entry-data-attribute cblt-x4-comp5. *> pic x(4) comp-5
        03 entry-data-date-stamp.
           05 stamp-year   cblt-x4-comp5. *> pic x(4) comp-5
           05 stamp-month  cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-day    cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-hour   cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-minute cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-sec    cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-msec   cblt-x2-comp5. *> pic x(2) comp-5
           05 stamp-dst    cblt-x1-comp5. *> pic x comp-5
           05 stamp-size   cblt-x8-comp5. *> pic x(8) comp-5
           05 entry-data-name.
              07 name-length  cblt-x2-comp5. *> pic x(2) comp-5
              07 name-text    pic x(max-len).
status-code
See Library Routines - Key.

On Entry:

handle
Set by CBL_DIR_SCAN_START. This field identifies the search operation. Search parameters cannot be changed for a given handle.
name-length
The length of the entry-name field.

On Exit:

entry-data-attribute
Describes the properties of the entry found. Valid values are:
Value | Bit Set | Meaning
1 | 0 | File found
2 | 1 | Directory found
4 | 2 | The entry found is not a file or a directory
8 | 3 | The entry is readable
16 | 4 | The entry is writable
32 | 5 | The entry is hidden
If the entry found is a file, any of bits 3, 4 and 5 may be set, to indicate whether or not the file is readable and so on. These bits may be set if the entry found is not a file, but the meaning in this case is undefined.
Note that this is a return field. The flags in bits 0 to 2 reflect the entry's properties and may not be the same as the search attributes.
entry-data-date-stamp
This group field holds the date and time that the entry was last written.
Attribute | Description
year | Current year minus 1900
month | Month, 0-11; January = 0
day | Day of month, 1-31
hour | Hour of day, 0-23
minute | Minute
second | Seconds
millisec | Milliseconds. On some systems millisec is set to zero
dst | Daylight saving time flag: 0 means that daylight saving was not in operation; 1 means that daylight saving was in operation when the entry was last written; 255 means that the daylight savings setting is unknown.
stamp-size
The size of the file in bytes.
name-text
The name of the entry found. By default, with the native Windows Run-Time System this is the filename only, and for the native UNIX and the managed Run-Time Systems it is the filename and the file path. The native Windows Run-Time System will return a path if bit 2 of the flags parameter is set for CBL_DIR_SCAN_START.
search-status
Return status:
0 | Success
1 | Unable to start search
2 | Invalid search handle
3 | Search finished
127 | Other error

Comments:

Errors associated with an entry-name field that is too small for the result will be ignored. If you do not supply a large enough field, the result will be truncated to fit. If you supply a field that is shorter than name-length you will corrupt memory.

Example:

The following example works for both UNIX and Windows environments:

      $SET FOLDCOPYNAME"LOWER"
      *
      * Environment variable COBCPY must be set as follows:
      *
      * Unix:
      * COBCPY=$COBDIR/cpylib:$COBCPY
      * export COBCPY
      *
      * Windows:
      * set COBCPY=%COBDIR%\cpylib;%COBCPY%
      *
       copy cblproto.
       identification division.
       program-id. dirdemo.
       data division.
       working-storage section.
      * Variables for CBL_DIR_SCAN_BEGIN
      * Some used by other CBL_DIR_SCAN_ routines.
      * The handle.
        01 dir-handle     pointer.
      * The pattern.  I chose a null terminator instead of
      * specified length.
        01 dir-name-pattern.
          10 dir-name-pattern-length     cblt-x2-comp5 value zero.
          10 dir-name-pattern-text       pic x(2048).
      * The terminator.
        01 pattern-terminator         pic x value low-values.
      * Search attributes.
        01 search-attributes     cblt-x4-comp5 value zero.
          78 find-file         value 1.
          78 find-directory    value 2.
          78 find-neither      value 4.
      * Flags
        01 dirflags             cblt-os-flags.
          78 escape-seq       value 1.
          78 wildcards        value 2.
        01 search-status        pic xx   comp-5.
      * Variables for CBL_DIR_SCAN_READ
      * The entry.
        01 entry-data.
          10 entry-data-attribute cblt-x4-comp5.
          10 entry-data-date-stamp.
             20 stamp-year   cblt-x4-comp5.
             20 stamp-month  cblt-x2-comp5.
             20 stamp-day    cblt-x2-comp5.
             20 stamp-hour   cblt-x2-comp5.
             20 stamp-minute cblt-x2-comp5.
             20 stamp-sec    cblt-x2-comp5.
             20 stamp-msec   cblt-x2-comp5.
             20 stamp-dst    cblt-x1-comp5.
             20 stamp-size   cblt-x8-comp5.
          10 entry-data-name.
             20 name-length  cblt-x2-comp5 value 50.
             20 name-text    pic x(50).
      * Variables for CBL_DIR_SCAN_END
      * No additional data items required.
      * Command line argument data area
        01 arg-pos              pic 9 value 1.
        01 arg-text             pic x(2048) value spaces.
      * Variables to make program Unix/Windows universal
        01 default-path pic x(7).
          78 win-path  value 'C:\xyz'.
          78 unix-path value '/var'.
      * Parameter block for CBL_GET_OS_INFO, ignoring all but OS type
        01 osinfo.
          10 osinfo-length pic x(2) comp-x value 23.
          10 os-type pic x comp-x.
          10 osinfo-junk pic x(25).
      * OTHER VARIABLES
        01 attrib-work          pic x    comp-5.
        01 attrib-text          pic x(10).
        01 nonblank-len         pic 9(9).
        01 terminator-position  pic 9(9).
        01 return-val           cblt-rtncode.
        procedure division.
      * Find out whether this is Unix or Windows,
      * and set default path appropriately.
        call 'CBL_GET_OS_INFO' using osinfo
                              returning return-val.
        if os-type = 128 or os-type = 129
      * Unix
        move unix-path to default-path
        else
      * Windows, OS/2, or DOS.
        move win-path to default-path.
      * Check for directory specification on command line.
        display arg-pos upon argument-number.
        accept arg-text from argument-value.
        if arg-text = spaces
          move default-path to dir-name-pattern-text
        else
          move arg-text to dir-name-pattern-text.
      * Find the nonblank length and append string terminator.
        perform varying nonblank-len
          from function length(dir-name-pattern-text)
          by -1 until
             dir-name-pattern-text(nonblank-len:1) <> space
          or
             nonblank-len = 1.
        add 1 to nonblank-len giving terminator-position.
        move pattern-terminator
                to dir-name-pattern-text(terminator-position:1).
      * Set desired search attributes by name.
        compute search-attributes =
          find-file +
          find-directory +
          find-neither.
        move zero to dirflags.
      * Start the scan -- similar to opening a file.
        call 'CBL_DIR_SCAN_START' using
                                 dir-handle
                                 dir-name-pattern
                                 search-attributes
                                 dirflags
                                       returning
                                 search-status.
      * Read to end, similar to reading a file.
        perform walk-dir thru walk-dir-exit until
                                  search-status <> zero.
      * At end or upon error, end the scan, similar to closing a file.
        call 'CBL_DIR_SCAN_END' using
                               dir-handle
                                   returning
                               search-status.
      * End the program.
        display 'That''s all!'.
        goback.
        walk-dir.
      * Initialize name-text; function does not right-pad to length.
        move spaces to name-text.
      * Do the read.
        call 'CBL_DIR_SCAN_READ' using
                         dir-handle
                         entry-data
                              returning
                         search-status.
        if search-status <> zero exit paragraph.
      * Remove all but the two rightmost bits of result.
        move function MOD(entry-data-attribute, 3) to attrib-work.
      * Format result display.
        evaluate attrib-work
          when 1 move 'File' to attrib-text
          when 2 move 'Directory' to attrib-text
          when other move '???' to attrib-text.
        display 'Next entry is: '
              attrib-text ' ' name-text(1:name-length).
        walk-dir-exit.
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_DIR_SCAN_START

Initializes a search for a file or directory.

Syntax:

CALL "CBL_DIR_SCAN_START" using  by reference   handle
                                                pattern
                                 by value       search-attribute
                                                flags
                                 returning      search-status

Parameters:

handle
usage pointer.
pattern
A group item containing the following subordinate items:
01 pattern
  03 pattern-length   cblt-x2-comp5. *> pic x(2) comp-5
  03 pattern-content  pic x(n)
search-attribute
Call prototype: cblt-x4-comp5
Picture: pic x(4) comp-5
search-status
See Library Routines - Key

On Entry:

pattern-length
Length of pattern string in the pattern-content field. It is associated with the handle and cannot be changed during a scan. A length of zero indicates a null-terminated pattern-content field. You can set pattern-length to less than the length of the pattern-content field, but not to more.
pattern-content
String for name searches. It is associated with the handle and cannot be changed during a scan. Can contain a full or partial directory path with or without a filename or just a filename. Elements in a path must be separated by "/". Null-terminated strings are recognised if the null is before the end of the string as provided in pattern-length, or if pattern-length is set to zero. If you set bit 1 of flags, the filename can contain wildcard characters: "*" means any arbitrary sequence of characters and "?" means any single character. If you set bit 0 flags the pling character "!" is available for use as an escape character. For more information about using wildcards and escape characters see the section Comments below.
search-attribute
Can be used to specify file properties to be searched for. It is associated with the handle and cannot be changed during a scan. Valid values are:
Value | Bit Set | Meaning
1 | 0 | Search for a file.
2 | 1 | Search for a directory.
4 | 2 | Search for any entry that is neither a file or a directory.
Bits above those specified are ignored. Bits 0 to 2 are always combined by OR, for example, to search for either a file or a directory set bits 0 and 1 (value 3). To search for all types of entry set bits 0, 1 and 2 (value 7).
flags
You can set one of the following values:
Value | Bit Set | Meaning
1 | 0 | Turns on processing of escape sequences in pattern-content. The default is no processing of escape sequences.
2 | 1 | Turns on the use of wildcards in the pattern-content field. Wildcards have significance as such only if this option is set.
4 | 2 | Turns on the inclusion of the path in returned filenames. By default, the Windows native Run-Time System does not return paths and the UNIX native Run-Time System and the managed Run-Time System do.
Bits above those specified are ignored. To turn on both processing of escape characters and the use of wildcards set both bits 0 and 1 (value 3).

On Exit:

handle
Reference for this search. Once you have specified search parameters and obtained a handle, you cannot change the parameters.
search-status
Return status:
0 | Success
1 | Unable to start search
2 | Invalid search handle
3 | Search finished
127 | Other error

Comments:

You can use wildcards only in the filename part of the pattern to search against, for example:

main/rts/mf*.h

You cannot use them in the directory name or instead of a drive letter.

You can use escape sequences in patterns, to force the inclusion of any of the following characters:

"\", "/", "!", "*", "?".

To use an escape sequence, enter the escape sequence character, pling ("!"), followed by the character you wish to escape. For example:

"abc?" requests any files in the current folder beginning with "abc" and having only one more character in the name.

"abc!?" requests a file in the current folder with the name "abc?".

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_CURRENT_DIR

Returns the current directory.

Syntax:

call "CBL_GET_CURRENT_DIR" using by value flags
                           by value       name-length
                           by reference   directory-name
                           returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
name-length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
directory-name | pic x(n). | pic x(n).
status-code | See Library Routines - Key.

On Entry:

flags
Reserved. Must be set to zero.
name-length
The size, in bytes, of the directory-name parameter. This parameter must be at least as big as the longest directory name that can be returned.

On Exit:

directory-name
Contains the current working directory in space-terminated format. If the directory name contains embedded spaces then it will be returned delimited by a pair of double quotes. This parameter must be large enough to also hold these quotes.
status-code
A return code:
0 | Success. directory-name contains the current working directory.
128 | The size of directory-name specified by name-length is not large enough to hold the name of the current working directory.
129 | The flags parameter is not set to zero.

Comments:

This routine ensures that name-length is at least as long as the current directory name that is to be returned. If it is not, the routine returns with status-code set to 128. If the flags parameter is not set to zero the routine returns with status-code set to 129.

The name-length parameter is not checked by this routine. It is the responsibility of the calling program to specify a valid name-length and directory-name combination (that is, to ensure that directory-name is at least name-length bytes long). Use the BY VALUE LENGTH OF directory-name SIZE 4" construct to pass the name-length parameter.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_FILENAME_CONVERT

Converts a filename between space-terminated and null-terminated format.

Syntax:

call 'CBL_FILENAME_CONVERT' using  fnc-func
                                   filename-in
                                   filename-out
                         by value  fnc-in-length
                         by value  fnc-out-length
                         returning fnc-ret

Parameters

fnc-func
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
filename-in
Using call prototype (see Key): pic x(n).
Picture: pic x(n).
filename-out
Using call prototype (see Key): pic x(n).
Picture: pic x(n).
fnc-in-length
Using call prototype (see Key): cblt-os-size
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
fnc-out-length
Using call prototype (see Key): cblt-os-size
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
fnc-ret
Using call prototype (see Key): cblt-rtncode

On Entry:

fnc-func
Defines how the conversion will proceed:
Bit 0
0 | Convert from space-terminated to null-terminated format.
1 | Convert from null-terminated to space-terminated format.
Bit 1
0 | If bit 0 is set to 0, the length of filename-in is determined using the space-termination character at the end of the filename.
1 | If bit 0 is set to 0, fnc-in-length exactly determines the length of filename-in. All characters are treated as part of the filename.
Bit 2
0 | Do not fold filename to upper case.
1 | Fold filename to upper case.
Bit 3
0 | Behavior determined by bits 0 to 2.
1 | Bits 0 to 2 are ignored, and the length of filename-in is determined by scanning the filename as a space-terminated filename. You can also specify a list of other termination characters; see below.
Bits 4-7
Reserved. Must be set to zero.
filename-in
Input filename.
filename-out
If bit 3 of fnc-func is set to 1, a list of characters that if encountered unquoted terminate the filename. If there are no additional characters, then a null pointer should be passed.
filename-in-length
Length of filename-in.
filename-out-length
If bit 3 of fnc-func is set to 0, the size of the buffer for the converted filename.

If bit 3 of fnc-func is set to 1, the number of characters in filename-out (if supplied).

On Exit:

filename-out
If bit 3 of fnc-func is set to 0, the converted filename. If filename-in is invalid, this parameter is set to an empty filename (a null if bit 0 was set to 0, else a space).
fnc-ret
If 0, an error occurred, otherwise, the length of the space terminated name that was either input or output.

Comments:

A space-terminated filename consists of a filename terminated by a space character. If the filename contains any embedded spaces then they should be escaped by including the whole filename between a pair of double quotes.

A null-terminated filename has any double quotes stripped out, but retains any embedded spaces.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_FILENAME_MAX_LENGTH

Returns the maximum size of a filename that the run-time system and the current operating system can handle. This size does not include any terminators (null or space).

Syntax:

call "CBL_FILENAME_MAX_LENGTH" returning max-length.

Parameters

 | Using call prototype (see Key) | Picture
max-length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

None.

On Exit:

max-length Maximum size of filename that the run-time system and the current operating system can handle, not including a terminator (null or space).
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_JOIN_FILENAME

Forms a filename by joining together its component parts; that is, the pathname, basename and extension.

Syntax:

call "CBL_JOIN_FILENAME" using     sj-param
                                   join-buffer
                                   path-buffer
                                   basename-buffer
                                   extension-buffer
                         returning status-code

Parameters

sj-param
Group predefined as cblt-splitjoin-buf containing:
01 cblt-splitjoin-buf                typedef.
  03 cblte-sj-param-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-join-flag1       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-split-join-flag2       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-device-offset          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-device-length          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-offset        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-length        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-offset       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-length       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-total-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-buf-len          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-join-buf-len           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-first-component-length cblt-x2-compx. 	*> pic x(2) comp-x.
join-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
path-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
basename-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
extension-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
status-code
See Library Routines - Key.

On Entry:

cblte-sj-param-length
Length of sj-param in bytes, including the two bytes for cblte-sj-param-length. The normal value for cblte-sj-param-length is 24.
cblte-sj-split-join-flag1
Can be set as follows:
Bit 1
1 | Strings are null-terminated
0 | Strings are space-terminated
Bit 0
1 | The new filename is folded to upper case
0 | The original case is preserved
cblte-sj-split-join-flag2
Can be set as follows:
Bit 2
1 | If bit 1 of cblte-sj-split-join-flag1 is set to 0, then this indicates that the length of each filename component is given exactly by cblte-sj-path-length, cblte-sj-basename-length and cblte-sj-extension-length. This flag can be used when there are known significant spaces in one of the filename components. If bit 1 of cblte-sj-split-join-flag1 is 1, then this is ignored,
0 | Length of filename components is determined by bit 1 of cblte-sj-split-join-flag1.
Bit 1
Reserved
Bit 0
Reserved
cblte-sj-device-offset
Offset of the start of the path in path-buffer, indexed from one.
cblte-sj-device length
Length of path if not space- or null-terminated.
cblte-sj-basename-offset
Offset of the start of the basename in basename-buffer, indexed from one.
cblte-sj-basename-length
Length of basename if not space- or null-terminated.
cblte-sj-extension-offset
Offset of the start of the extension in extension-buffer, indexed from one.
cblte-sj-extension-length
Length of extension if not space- or null-terminated.
path-buffer
Pathname.
basename-buffer
Basename.
extension-buffer
Extension.
cblte-sj-join-buf-len
Length of join-buffer.

On Exit:

cblte-sj-total-length
Total number of characters in the filename.
join-buffer
The joined-up filename.
status-code
Return status:
0 | Success
1 | Filename too big for join-buffer
4 | Illegal filename

Comments:

The new filename is formed by concatenating the following:

  • The first cblte-sj-device-length bytes (starting from cblte-sj-device-offset) of path-buffer
  • The first cblte-sj-basename-length bytes (starting from cblte-sj-basename-offset) of basename-buffer
  • The first cblte-sj-extension-length bytes (starting from cblte-sj-extension-offset) of extension-buffer

It is placed in join-buffer with length cblte-sj-total-length.

This routine can be made to fold to upper case by setting the least significant bit (bit 0) of cblte-sj-split-join-flag1. If this bit is not set, the case is preserved.

This routine can accept either null-terminated or space-terminated strings. Setting the second least significant bit (bit 1) of cblte-sj-split-join-flag1 results in the routine expecting null-terminated strings. If this bit is not set, space-terminated strings are expected.

The path, basename and extension fields can be shorter than the lengths specified by cblte-sj-path-length, cblte-sj-basename-length, and cblte-sj-extension-length respectively, if they are terminated with either a space or a null, depending on the setting bit 1 of cblte-sj-split-join-flag1.

path-buffer, basename-buffer, extension-buffer, and join-buffer do not have to be four distinct buffers. This means that this routine can be used with CBL_SPLIT_FILENAME to replace one component of a filename.

If path-buffer is not empty and does not have a trailing backslash (\) or forwardslash (/) or colon (:) and basename-buffer is not empty, the routine inserts a forwardslash between the path and basename in join-buffer.

If extension is ".", the string returned in join-buffer has an extension of spaces; that is, the filename has a trailing period (.).

If cblte-sj-total-length is less than cblte-sj-join-buf-len, the characters after the end of the filename are nulls or spaces depending on bit 1 of cblte-sj-split-join-flag1.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_LOCATE_FILE

This routine has two uses. It can be used to expand an environment variable in a file specification, where the environment variable contains a list of several paths. It can also determine whether an OPEN INPUT statement using a particular file specification finds the file in a library file or as a separate disk file.

Syntax:

call "CBL_LOCATE_FILE" using     user-file-spec
                                 user-mode
                                 actual-file-spec
                                 exist-flag
                                 path-flag
                       returning status-code

Parameters:

user-file-spec
Using call prototype (see Key): pic x(n)
Picture: pic x(n).
user-mode
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
actual-file-spec
Using call prototype (see Key), a group item defined as :
01 actual-file-spec.
   03 buffer-len   cblt-x2-compx.
   03 buffer       pic x(n).
Picture, a group item defined as :
01 actual-file-spec.
   03 buffer-len   pic x(2) comp-x.
   03 buffer       pic x(n).
exist-flag
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
path-flag
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
status-code
See Library Routines - Key

On Entry:

user-file-spec
Contains the filename specification; this can include an embedded environment variable or library name. The string can be space- or null-terminated, depending on bit 7 of user-mode.
Note: For filenames that contain spaces, enclose them in double quotation marks (").
user-mode
Specifies the action to perform on user-file-spec:
Bit pair 0 and 1 (value 0, 1, or 2)
00 Check whether the file exists in a library or as a separate disk file.

If user-file-spec includes an embedded environment variable, the file is searched for along each path specified in that variable.

If the file is found, actual-file-spec on exit contains the file specification with the environment variable expanded to the successful path. Otherwise, actual-file-spec on exit contains the file specification with the environment variable expanded to the first path it contained.

01 | If user-file-spec includes an environment variable, actual-file-spec on exit contains the file specification with the environment variable expanded to the first path it contained. The file is not searched for.
10 | If user-file-spec includes an environment variable, actual-file-spec on exit contains the file specification with the environment variable expanded to the next path it contained. The file is not searched for. This option should only be used after a successful call with the first two bits of user-mode set to 1 (01) or 2 (10). See path-flag below.
11 | Reserved. Must not be used.
Bits 2-6
Reserved. Must be set to zeroes.
Bit 7
Determines the terminator type:
0 | user-file-spec and actual-file-spec are both space-terminated.
1 | user-file-spec and actual-file-spec are both null-terminated.
path-flag
If the first two bits of user-mode are set to 2 (10), this data item should contain the value that was returned in this item from the previous call where the first two bits of user-mode were either 1 (01) or 2 (10).
buffer-len
Size of buffer.

On Exit:

buffer
Buffer to contain the resolved file specification, as described under user-mode. If the resolved file specification is larger than the size specified by buffer-len, the contents of buffer remain unchanged and status-code is set accordingly.
exist-flag
If user-mode = 0, this data item on exit shows whether the file specified in user-file-spec exists.
0 | File not found or not searched for
1 | File was found in a library that was already open
2 | File was found in a library specified in user-file-spec
3 | File was found as a separate disk file
If user-mode is not 0 this data item is always 0 on exit.
path-flag
Shows whether user-file-spec contained an embedded environment variable that has been expanded in actual-file-spec.
0 | actual-file-spec does not include an expanded environment variable
>0 | actual-file-spec contains an expanded environment variable
status-code
Return status:
0 | Success
1 | The environment variable does not exist
2 | There is no next path
3 | The resolved filename is too large for the buffer
4 | Resulting filename is illegal
255 | Other error

Comments:

CBL_LOCATE_FILE is not stripe-aware. If you use this routine on a striped file, the routine locates the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, refer to File Striping.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

Example:

The user-file-spec can take the form:

Standard filename: | path/filename.ext
Embedded environment variable: | $envname/filename.ext
Embedded library name: | path/lbr-name.lbr/filename.ext
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


CBL_RENAME_FILE

Changes the name of a file.

Syntax:

call "CBL_RENAME_FILE" using     old-filename
                                 new-filename
                       returning status-code

Parameters:

old-filename
pic x(n).
new-filename
pic x(n).
status-code
See Library Routines - Key.

On Entry:

old-filename
The file to rename. The name can contain a pathname, and is terminated by a space. If no path is given, the current directory is assumed.

This routine does not work with filenames containing wildcard characters.

new-filename
The new name, terminated by a space. If old-filename contains a pathname, this must contain the same pathname. Some operating systems do not allow you to rename a file if a file of the name in new-filename already exists

On Exit:

None

Comments:

CBL_RENAME_FILE is not stripe-aware. If you use this routine on a striped file, the routine renames the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

You can check the success of the call by examining RETURN-CODE. See the topic Interpreting the return code as a file status code for more details.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Interpreting the return code as a file status code
File and Filename Routines


CBL_SPLIT_FILENAME

Splits a filename into its component parts; that is, the pathname, basename and extension.

Syntax:

call "CBL_SPLIT_FILENAME" using     sj-param
                                    split-buffer
                          returning status-code

Parameters

sj-param
Group defined as cblt-splitjoin-buf containing:
01 cblt-splitjoin-buf                typedef.
  03 cblte-sj-param-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-join-flag1       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-split-join-flag2       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-device-offset          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-device-length          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-offset        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-length        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-offset       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-length       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-total-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-buf-len          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-join-buf-len           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-first-component-length cblt-x2-compx. 	*> pic x(2) comp-x.
split-buffer
Call prototype: pic x(n).
Picture: pic x(n).
status-code
See Library Routines - Key

On Entry:

param-length
Length of sj-param in bytes, including the two bytes for cblte-sj-param-length. The normal value for cblte-sj-param-length is 24.
splitjoin-flg1
Bit 1
1 | The strings are null-terminated
0 | The strings are space-terminated
Bit 0
1 | The new filename is folded to upper case
0 | The original case is preserved.
split-buf-len
Length of split-buffer
split-buffer
The string to split.

On Exit:

cblte-sj-splitjoin-flg2
Bit | Meaning
2 | Set if there is a significant space in the filename
1 | Set if there is a wildcard in the path
0 | Set if there is a wildcard in basename or extension
cblte-sj-path-strt
Start of pathname in split-buffer, from one.
cblte-sj-path-len
Length of pathname; zero if there is none. This includes any following colon (:).
cblte-sj-basename-strt
Start of basename in split-buffer, from one.
cblte-sj-basename-len
Length of basename; zero if there is none. This does not include the following period (.).
cblte-sj-extension-strt
Start of extension in split-buffer, from one.
cblte-sj-extension-len
Length of extension; zero if there is none. This does not include the preceding period (.).
cblte-sj-total-length
Total number of characters in the string.
cblte-sj-first-path-len
Number of characters up to and including the first backslash (\) or slash (/) or colon (:); if split-buffer contains none of these, this parameter = cblte-sj-path-len.
split-buffer
If bit 0 of cblte-sj-splitjoin-flg1 is set then this routine folds to upper case. If bit 1 of cblte-sj-splitjoin-flg1 is unset and split-buffer was a quoted name, possibly containing embedded spaces/quotes, then any unrequired quote characters are removed.
status-code
Return status:
0 | Success
4 | Illegal filename

Comments:

This routine can be made to fold to upper case by setting the least significant bit (bit 0) of cblte-sj-splitjoin-flg1. If this bit is not set, the case is preserved.

This routine can accept either null-terminated or space-terminated strings. Setting the second least significant bit (bit 1) of cblte-sj-splitjoin-flg1 results in the routine expecting null-terminated strings. If this bit is not set, space-terminated strings are expected.

If there are two or more periods (.) in the filename (not counting periods (.) in the pathname), the extension returned consists of the characters between the last period (.) and the end of the filename. The basename contains everything up to, but not including, the last period (.).

To make a distinction between filenames with no extension and filenames with spaces extension (that is, basenames whose last character is a period (.)), if the extension is spaces cblte-sj-extension-len is 1 and cblte-sj-extension-strt points to the last period (.).

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


mFFH

Initializes the File Handler.

Restriction: This routine is supported in native COBOL only.

Syntax:

call mFFH using      opcode

Parameters:

opcode pic x(2) comp-x

On Entry:

opcode | pic x(2) comp-x
opcode | h"0000" , the standard File Handler operation code that initializes the File Handler.

On Exit:

None.

Comments:

You need to use this call only if your program includes calls to MFFH_MODIFY_TRACE before any usage of COBOL I/O statements. You must use it before the first call to any MFFH_ routine.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines
Related information
MFFH_MODIFY_TRACE
MFFH_MODIFY_DISABLE
mFFH


MFFH_MODIFY_DISABLE

Disables all File Handler trace modification set by previous MFFH_MODIFY_TRACE calls.

Note: This routine is supported for native COBOL only.

Syntax:

call "MFFH_MODIFY_DISABLE"

Parameters:

None.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


MFFH_MODIFY_TRACE

Modifies some FCD fields, to save directly accessing the FCD. You can use this call whether you are issuing standard COBOL I/O statements or calling the File Handler explicitly using the API.
Note: This routine is supported for native COBOL only.

Syntax:

call "MFFH_MODIFY_TRACE" using      l-FCD-modifiers

Parameters:

l-FCD-modifiers.
Group item containing:
01 l-FCD-modifiers
   03 1-FCD-mod-enable  pic x comp-x.
   03 l-FCD-mod-flag    pic x(4) comp-x.
reserved pic x(8).

On Entry:

l-FCD-mod-enable
1 | Set modifier flag on
2 | Set modifier flag off
3 | Unset modifier - does not affect FCDs already modified
l-FCD-mod-flag
h"1102" | Modifies the trace bit in fcd-flags-1
h"1808" | Modifies the OPEN/CLOSE trace bit in fcd-fs-flags

On Exit:

None.

Comments:

You must have initialized the File Handler by calling mFFH before you can call MFFH_MODIFY_TRACE.

The success of the call can be checked by examining RETURN-CODE.

Once a modification is set up, it is applied to every FCD passing into the File Hander until the modification is cleared.

Examples:

This example enables tracing for all files.

    move 1 to l-FCD-mod-enable
    move h"1102" to l-FCD-mod-flag
    call "MFFH_MODIFY_TRACE" using l-FCD-modifiers.

This example disables tracing for all files.

    move 2 to l-FCD-mod-enable
    move h"1102" to l-FCD-mod-flag
    call "MFFH_MODIFY_TRACE" using l-FCD-modifiers.

This example stops the tracing bit being modified from now on for all files. What was set, stays set.

    move 3 to l-FCD-mod-enable
    move h"1102" to l-FCD-mod-flag
    call "MFFH_MODIFY_TRACE" using l-FCD-modifiers.

This example enables OPEN/CLOSE tracing for all files.

    move 1 to l-FCD-mod-enable
    move h"1808" to l-FCD-mod-flag
    call "MFFH_MODIFY_TRACE" using l-FCD-modifiers.
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


PC_FIND_DRIVES

Returns all valid drives on a PC.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "PC_FIND_DRIVES" using      drive-info
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
drive-info | cblt-x4-compx | pic x(4) comp-x.
status-code | See Library Routines - Key

On Entry:

None

On Exit:

drive-info | The 26 least-significant bits correspond to drives A: through Z:, with A: represented by bit 0 (the least significant bit) and Z: represented by bit 25. The corresponding bit is set for each drive that is present.
status-code | Status code.
Parent topic: File and Filename Routines


PC_READ_DRIVE

Returns the current default drive letter.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "PC_READ_DRIVE" using     drive
                     returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
drive | cblt-x1-compx | pic x.
status-code | See Library Routines - Key

On Entry:

None

On Exit:

drive Drive letter, upper or lower case.
Parent topic: File and Filename Routines


PC_SET_DRIVE

Sets the default drive letter.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "PC_SET_DRIVE" using     drive
                    returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
drive | cblt-x1-compx | pic x.
status-code | See Library Routines - Key

On Entry:

drive Drive letter, upper or lower case.

On Exit:

None

Parent topic: File and Filename Routines


X"91" function 46

Enables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | FD name of file

On Entry:

function-code | Value 46
parameter | The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

If you want to include non-ASCII data in a file then you must enable null insertion. This function lets you enable null insertion for individual files regardless of the setting of the run-time switch N.

Example:

 fd payroll-file
      ...
     call x"91" using result
                      function-code
                      payroll-file
Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 47

Disables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | FD name of file

On Entry:

function-code | Value 47
parameter | The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

This function lets you disable null insertion for individual files regardless of the setting of the run-time switch N.

This function cannot be used if the file is declared as EXTERNAL.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 48

Enables insertion of tab characters in line sequential files.

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | FD name of file

On Entry:

function-code | Value 48
parameter | The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

On input all tab characters are expanded to the correct number of spaces, while on output to disk, multiple spaces before a tab stop position are contracted to a tab character. This function lets you enable tab insertion for individual files regardless of the setting of the run-time tab compression switch T.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 49

Disables insertion of tab characters in line sequential files.

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | FD name of file

On Entry:

function-code | Value 49
parameter | The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

On input all tab characters are expanded to the correct number of spaces, while on output to disk, multiple spaces before a tab stop position are contracted to a tab character. This function lets you disable tab insertion for individual files regardless of the setting of the run-time tab compression switch T.

Parent topic: File and Filename Routines
Parent topic: Alphabetical List of Library Routines


Interpreting the return code as a file status code

If any of the routines

  • CBL_CHECK_FILE_EXIST
  • CBL_COPY_FILE
  • CBL_CREATE_FILE
  • CBL_DELETE_FILE
  • CBL_OPEN_FILE
  • CBL_READ_FILE
  • CBL_RENAME_FILE
  • CBL_WRITE_FILE
  • CBL_CHANGE_DIR
  • CBL_CREATE_DIR
  • CBL_DELETE_DIR
  • CBL_READ_DIR

fails, the RETURN-CODE register contains a file status value indicating the failure. This file status is always the standard ANSI'74 file status value. If no ANSI'74 file status is defined for the error, an extended file status is returned (9/nnn where nnn is the run-time system error number).

You should, therefore, use RETURN-CODE and not a RETURNING clause. If RETURN-CODE is non-zero after calling one of these routines, you must process it as a file status, for example:

 01 file-status      pic xx comp-x.
 01 redefines file-status.
     03 fs-byte-1  pic x.
     03 fs-byte-2  cblt-x1-compx
   . . .
     call "CBL_xxx_xxx" using parameters
     if return-code not = 0
        move return-code to file-status
           . . .

At this point fs-byte-1 contains "9" and fs-byte-2 contains the run-time system error number.

Parent topic: File and Filename Routines


Filename Routines - Example

************************************************************
*                                                          *
*         (C) Micro Focus International Ltd 2000           *
*                                                          *
*                     SPLTJOIN.CBL                         *
*                                                          *
*  This program demonstrates the use of the routines that  *
*  enable you to separate a filename into its component    *
*  strings (CBL_SPLIT_FILENAME), and to join strings       *
*  together to form a filename (CBL_JOIN_FILENAME).        *
*                                                          *
************************************************************

 identification division.
 program-id. SPLTJOIN.
 environment division.
 data division.
 working-storage section.

 copy "cbltypes.cpy".

 78 environ          value "dos".

 01 split-buffer                     pic x(65).
 01 split-params                          cblt-splitjoin-buf.
*    03  cblte-sj-param-length            cblt-x2-compx value 24.
*    03  cblte-sj-split-join-flag1        cblt-x1-compx value 0.
*    03  cblte-sj-split-join-flag2        cblt-x1-compx.
*    03  cblte-sj-device-offset           cblt-x2-compx.
*    03  cblte-sj-device-length           cblt-x2-compx.
*    03  cblte-sj-basename-offset         cblt-x2-compx.
*    03  cblte-sj-basename-length         cblt-x2-compx.
*    03  cblte-sj-extension-offset        cblt-x2-compx.
*    03  cblte-sj-extension-length        cblt-x2-compx.
*    03  cblte-sj-total-length            cblt-x2-compx.
*    03  cblte-sj-split-buf-len           cblt-x2-compx value 65.
*    03  cblte-sj-join-buf-len            cblt-x2-compx value 65.
*    03  cblte-sj-first-component-length  cblt-x1-compx.

 01 join-buffer              pic x(65).
 01 path-buffer              pic x(65).
 01 basename-buffer          pic x(65).
 01 extension-buffer         pic x(3) value "cbl".

 procedure division.

* Set up lengths
     move 65 to cblte-sj-split-buf-len
                cblte-sj-join-buf-len

* Set flag for space-terminated, fold to upper
     move 1 to cblte-sj-split-join-flag1

$if environ = "unix"
     move "/dir/file.ext" to split-buffer
$else
     move "a:\dir\file.ext" to split-buffer

$end
     move 1 to cblte-sj-split-join-flag1
     move 24 to cblte-sj-param-length
     call "CBL_SPLIT_FILENAME" using split-params
                                     split-buffer

* This sets up most of the parameters you need for a join

* The join below replaces the original extension in
* split-buffer with the extension in extension-buffer, and
* puts the result in join-buffer.
     move 1 to cblte-sj-extension-offset
     move 3 to cblte-sj-extension-length
     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    split-buffer
                                    split-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/DIR/FILE.CBL" then
$else
     if join-buffer = "A:\DIR\FILE.CBL" then
$end
         display "first test passed"
     else
         display "first test failed"
     end-if

* It is harder to set up a join without doing a split first,
* but this is what you would need to do.

     move 1 to cblte-sj-device-offset
               cblte-sj-basename-offset
               cblte-sj-extension-offset

     move length of path-buffer to cblte-sj-device-length
     move length of basename-buffer
                                to cblte-sj-basename-length
     move length of extension-buffer
                                to cblte-sj-extension-length
     move length of join-buffer to cblte-sj-join-buf-len

     move 0 to cblte-sj-split-join-flag1
     move 24 to cblte-sj-param-length

$if environ = "unix"
     move "/path" to path-buffer
$else
     move "c:\path" to path-buffer
$end
     move "basename" to basename-buffer

     move "ext" to extension-buffer

     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    path-buffer
                                    basename-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/path/basename.ext" then
$else
     if join-buffer = "c:\path\basename.ext" then
$end
         display "second test passed"
     else

         display "second test failed"
     end-if
  stop run.
Parent topic: File and Filename Routines


Keyboard Routines

Restriction: These routines are supported for native COBOL only.
Note: The CBL_keyboard routines do not work with the x"AF" keyboard routines.
  • CBL_GET_KBD_STATUS
    Checks whether there is a character waiting to be read from the keyboard.
  • CBL_READ_KBD_CHAR
    Waits until a character is typed and then reads it with no echo.
  • X"B0" function 0
    Creates a function-key table.
  • X"B0" function 2
    Tests the status of the Shift, Alt, Ctrl and Lock keys.
  • X"B0" function 4
    Disables keyboard interrupts (Ctrl+Break).
  • Keyboard Routines - Example
Parent topic: Library Routines
Related information
Keyboard Routines - Example
Alphabetical List of Library Routines


CBL_GET_KBD_STATUS

Checks whether there is a character waiting to be read from the keyboard.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_GET_KBD_STATUS" using     key-status
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
key-status | cblt-x1-compx | pic x comp-x.
status-code | See Library Routines - Key

On Entry:

None

On Exit:

key-status
The status of the keyboard:
0 | No character available
1 | Character available

Comments:

Some UNIX implementations do not allow you to poll the keyboard in this way. See the documentation supplied with your UNIX system to determine if this is the case in your implementation.

This routine should be preceded by an enhanced ACCEPT or DISPLAY statement (see the chapter Adis in your Character User Interfaces) or by calling one of the CBL_ display routines (see the topic Screen Routines). Otherwise, the behavior is undefined.

Unpredictable results can occur if the user attempts to use both X"AF" and CBL_ keyboard routines. This is because X"AF" invokes ADIS to perform the required keyboard function and ADIS uses the CBL_ keyboard routines.

Parent topic: Keyboard Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_KBD_CHAR

Waits until a character is typed and then reads it with no echo.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_READ_KBD_CHAR" using     char
                         returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
char | cblt-x1-compx. | pic x.
status-code | See Library Routines - Key.

On Entry:

None

On Exit:

char The character that was typed, in ASCII.

Comments:

This routine should be preceded by an enhanced ACCEPT or DISPLAY statement (see the chapter Adis in your Character User Interfaces book) or by calling one of the CBL_ display routines. Otherwise the behaviour is undefined.

Parent topic: Keyboard Routines
Parent topic: Alphabetical List of Library Routines


X"B0" function 0

Creates a function-key table.

Note: This routine is supported for native COBOL only.

Syntax:

call X"B0" using function-code
                 key-table

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
key-table
Group containing:
01 key-table
  03 key-pressed     cblt-x1-compx   *> pic x comp-x.
  03 key-entry-list                  *> Group item defined as one iteration
                                     *> of the following for each key to be
                                     *> detected:
    05 key-entry-len cblt-x1-compx   *> pic x comp-x.
    05 key-entry     pic x(n)        *> pic x(n)
  03 key-list-end    cblt-x1-compx   *> pic x comp-x.

On Entry:

function-code | Contains 0.
key-entry-len | The length of key-entry in bytes (1 or 2).
key-entry | The code sequence produced by the required key.
key-list-end | Contains 0.

On Exit:

key-pressed The table entry matching the key used, or zero if no match is made.

Comments:

An ACCEPT statement normally recognizes as control keys only the keys used in data entry and is terminated by the Enter key; any other control key is rejected with a beep. Other control keys and function keys can be made available by calling this library routine.

This routine declares a table of key-code sequences, one for each additional key which is to be recognized. Details of the code sequences sent by each key are available in the IBM Personal Computer Technical Reference Manual.

After the routine has been called, an ACCEPT statement is terminated by the Enter key or by any one of the keys whose code sequence matches an entry in the table. The first byte of the table then contains a number indicating which entry in the table has been matched; zero indicates that the Enter key was used. If the Enter key has an entry in the table, the entry number of that key is returned rather than zero.

The routine can be called with different tables as often as you require. If the current table is changed (for example, if a key is changed or the length increased), then you don't need to call the routine again.

A table used by a particular program remains enabled for that program until it is superseded by another call to this routine, regardless of how many times this routine is called by other programs in your suite.

You must explicitly set up a table for each program in your suite of programs that uses this facility; passing the table in the Linkage Section is not sufficient.

As long as you know the key-code sent, you can define any key in the table. For example, a table entry with length of 1 and a key-code of pic X VALUE "C" causes the letter C to end an ACCEPT. You could, therefore, use such a key to "break-out" of an ACCEPT, perform your own processing, and return to the ACCEPT statement. The effect of this is that you have redefined the effect of that particular key.

The result byte is set both on termination of an ACCEPT and on each call to the routine when a key in the defined table has been pressed. When this occurs, the character code, x"0D" is returned to the CBL_READ_KBD_CHAR routine, and the result byte indicates which key in the table has been pressed. This means that, you can use CBL_READ_KBD_CHAR to read any single keystroke, including function keys.

For a complete list of code sequences sent by keys, see the technical reference manual for your personal computer.

Any keys defined by this call take precedence over those defined with AdisCF.

The function key table set up by AdisCF and used by call x"AF" is separate from the function key table used by call x"B0". Both can be enabled at the same time with all key sequences in the x"B0" table causing the carriage return x"0D" character to be returned to Adis.

Parent topic: Keyboard Routines
Parent topic: Alphabetical List of Library Routines


X"B0" function 2

Tests the status of the Shift, Alt, Ctrl and Lock keys.
Note: This routine is supported for native COBOL only, and only on Windows platforms.

Syntax:

call X"B0" using function-code
                 status-block

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
status-block
Group containing:
01  status-block
  03 status-inds  pic x           *> pic x
  03 status-id    cblt-x1-compx   *> pic x comp-x.
  03 status-res   pic x(6)        *> pic x(6)

On Entry:

function-code
Value 2.
status-id
Must be set to 2. It is overwritten by the call, so must be reset to 2 before each call.
status-res
Reserved.

On Exit:

status-inds
Contains bit settings indicating the status of the keys (1=key pressed, 0=key not pressed) in the following order:
bit 7 | Ins
bit 6 | Caps Lock
bit 5 | Num Lock
bit 4 | Scroll Lock
bit 3 | Alt
bit 2 | Ctrl
bit 1 Shift (left key only)
Restriction: Console applications cannot distinguish between the left and right Shift keys, and so bit 0 is always returned when either Shift key is pressed. (The restriction does not apply to GUI applications.)
bit 0 | Shift (right key only)

Comments:

For the Alt, Ctrl and Shift keys, the routine returns a 1 only if the key is actually pressed when the routine is called; for the other keys, the relevant bit is alternately set and unset each time the key is pressed.

Effective use of function 2 requires that the call is repeated at very frequent intervals.

Parent topic: Keyboard Routines
Parent topic: Alphabetical List of Library Routines


X"B0" function 4

Disables keyboard interrupts (Ctrl+Break).

Note: This routine is supported for native COBOL only.

Syntax:

call X"B0" using function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx | pic x comp-x.

On Entry:

function-code | Value 4.
parameter | Value 1.

On Exit:

None

Comments:

This routine disables keyboard interrupts for the rest of the application. It should be called before any subprograms are called.

Parent topic: Keyboard Routines
Parent topic: Alphabetical List of Library Routines


Keyboard Routines - Example

The following code is an example of how to use the function key call together with CBL_READ_KBD_CHAR:

 procedure division.
     ...
* Set up function key list
     call x"B0" using B0-function
                      B0-parameter-block
     ...
* Read a character from the keyboard
     call "CBL_READ_KBD_CHAR" using char
     if char = x"0D"

* A key defined in the function key table was pressed
         evaluate B0-return-byte
           when 1
            ...
           when 2
            ...
         end-evaluate
     else
         if char = x"00"
* A function key not defined in the table was pressed
             call "CBL_READ_KBD_CHAR" using char
* char contains the key's scan code
            ...
         else
* char contains a character
            ...
         end-if
     end-if.
Parent topic: Keyboard Routines


Logical Operator Routines

The logic routines carry out logic operations on bits. Apart from CBL_NOT, all these operations have two operands.

If the length is specified as a literal and there is no RETURNING clause then native code is optimized to generate inline code.

In the two-operand routines, interchanging the two operands, source and target, does not change the result except in CBL_IMP. However, the result is always stored in the second operand, target.

If length is longer than either data item, bytes following that data item are used, up to the length specified.

The parameter length can be replaced by the syntax:

        length of source

or:

        length of target

assuming all the bytes of the data item are to be used.

Logical AND and OR operations can also be carried out using the VALUE clause.

RETURN-CODE is not affected by these routines.

  • CBL_AND
    Does a logical AND between the bits of two data items.
  • CBL_EQ
    Does a logical EQUIVALENCE between the bits of two data items.
  • CBL_IMP
    Does a logical IMPLIES between the bits of two data items.
  • CBL_NOT
    Does a logical NOT on the bits of a data item.
  • CBL_OR
    Does a logical OR between the bits of two data items.
  • CBL_XOR
    Does a logical XOR between the bits of two data items.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_AND

Does a logical AND between the bits of two data items.

Syntax:

call "CBL_AND" using    source
                        target
               by value length

Parameters:

 | Using call prototype (see Key) | Picture
source | cblt-x1-compx | Any data item.
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal, pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

source | One of the data items to AND.
target | The other data item to AND.
length | The number of bytes of source and target to AND. Positions in target beyond this are unchanged.

On Exit:

target The result.

Comments:

The routine starts at the left-hand end of source and target and ANDs the bits together, storing the result in target. The truth table for this is:

source | target | result
0 | 0 | 0
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


CBL_EQ

Does a logical EQUIVALENCE between the bits of two data items.

Syntax:

call "CBL_EQ" using    source
                       target
              by value length

Parameters:

 | Using call prototype (see Key) | Picture
source | cblt-x1-compx | Any data item.
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

source | One of the data items to EQUIVALENCE.
target | The other data item to EQUIVALENCE.
length | The number of bytes of source and target to EQUIVALENCE. Positions in target beyond this length are unchanged.

On Exit:

target The result.

Comments:

The routine starts at the left-hand end of source and target and EQUIVALENCEs the bits together, storing the result in target. The truth table for this is:

source | target | result
0 | 0 | 1
0 | 1 | 0
1 | 0 | 0
1 | 1 | 1
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


CBL_IMP

Does a logical IMPLIES between the bits of two data items.

Syntax:

call "CBL_IMP" using    source
                        target
               by value length

Parameters:

 | Using call prototype (see Key) | Picture
source | cblt-x1-compx | Any data item.
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal, pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

source | One of the data items to IMPLIES.
target | The other data item to IMPLIES.
length | The number of bytes of source and target to IMPLIES. Positions in target beyond this are unchanged.

On Exit:

target The result.

Comments:

The routine starts at the left-hand end of source and target and IMPLIES the bits together, storing the result in target. The truth table for this is:

source | target | result
0 | 0 | 1
0 | 1 | 1
1 | 0 | 0
1 | 1 | 1
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


CBL_NOT

Does a logical NOT on the bits of a data item.

Syntax:

call "CBL_NOT" using    target
               by value length

Parameters:

 | Using call prototype (see Key) | Picture
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal, pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

target The data to operate on.

On Exit:

target | The data with the bits inverted.
length | The number of bytes of target to change. Positions beyond this are unchanged.

Comments:

The routine starts at the left-hand end of target and inverts bits. The truth table for this is:

before | after
0 | 1
1 | 0
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


CBL_OR

Does a logical OR between the bits of two data items.

Syntax:

call "CBL_OR" using    source
                       target
              by value length

Parameters:

 | Using call prototype (see Key) | Picture
source | cblt-x1-compx | Any data item.
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal or pic x(4) comp-5. or pic x(8) comp-5 (64-bit native programs only)

On Entry:

source | Source data to OR into the target data.
target | Target data to be ORed with the source data.
length | The number of bytes of source and target to OR. Positions in target beyond this are unchanged.

On Exit:

target The result of Oring source with target.

Comments:

The routine starts at the left-hand end of source and target and ORs the bits together, storing the result in target. The truth table for this is:

source | target | result
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


CBL_XOR

Does a logical XOR between the bits of two data items.

Syntax:

call "CBL_XOR" using    source
                        target
               by value length

Parameters:

 | Using call prototype (see Key) | Picture
source | cblt-x1-compx | Any data item.
target | cblt-x1-compx | Any data item.
length | cblt-os-size | Numeric literal, pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

source | One of the data items to exclusive-OR.
target | The other data item to exclusive-OR.
length | The number of bytes of source and target to exclusive-OR. Positions in target beyond this are unchanged.

On Exit:

target The result.

Comments:

The routine starts at the left-hand end of source and target and exclusive-ORs the bits together, storing the result in target. The truth table for this is:

source | target | result
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0
Parent topic: Logical Operator Routines
Parent topic: Alphabetical List of Library Routines


Memory Allocation Routines

  • CBL_ALLOC_MEM
    Dynamically allocates memory, and can associate allocated heap data with a thread and/or the calling program.
  • CBL_ALLOC_DYN_MEM
    Dynamically allocates memory, and can associate it with the calling program.
  • CBL_ALLOC_SHMEM
    Dynamically allocates shared memory.
  • CBL_ALLOC_THREAD_MEM
    Allocates thread-specific heap memory.
  • CBL_FREE_DYN_MEM
    Frees dynamically allocated memory allocated by the CBL_ALLOC_DYN_MEM routine.
  • CBL_FREE_MEM
    Frees dynamically allocated memory.
  • CBL_FREE_SHMEM
    Frees dynamically allocated shared memory.
  • CBL_FREE_THREAD_MEM
    Frees dynamically allocated thread-specific heap memory.
  • CBL_MEM_STRATEGY
    Changes the memory strategy for an application dynamically.
  • CBL_MEM_VALIDATE
    Validates memory allocations, monitored freed memory, and, if the operating system supports it, compacts memory heaps.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_ALLOC_MEM

Dynamically allocates memory, and can associate allocated heap data with a thread and/or the calling program.

Syntax:

call "CBL_ALLOC_MEM" using     mem-pointer
                     by value  mem-size
                     by value  flags
                     returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer. Must be level 01.
mem-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
status-code | See Library Routines - Key |

On Entry:

mem-size
The number of bytes of memory to allocate.
flags
The type of memory required. You can set the following bits:
Bit 0 | Allocate this memory as shared.
Bit 1 | Reserved. Must be set to zero.
Bit 2 | Allocate this memory independently from any calling program. If bit 3 is set it will be freed automatically when the calling thread ends. If bit 3 is unset it will be freed when the run-unit ends.
Bit 3 | Allocate this memory as thread local. If bit 2 is unset and there is a direct or indirect (in a mixed language environment) calling COBOL program, it will be freed when the calling program is canceled or the thread ends - whichever comes first.
Remaining bits | Reserved. Must be set to 0.

On Exit:

mem-pointer
A pointer to the memory allocated. The allocated memory is not initialized.

Comments:

The memory allocated is not initialized to any value.

Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.

If the memory has been allocated by a thread, it is freed when the calling thread terminates.

The maximum size of nonshared memory is restricted only by your operating system.

The maximum size of shared memory is restricted by the operating system and the run-time system. The run-time tunable, shared_memory_segment_size, can be used to set the maximum size. The size for shared memory allocated using this routine is limited to a maximum of around 64000 bytes.

Bit 1 and bit 2 or bit 3 are mutually exclusive. This is checked and error 181 returned otherwise. If there is no calling program (directly or indirectly in a mixed language environment) bit 2 is ignored.

If bit 2 is not set all standard memory allocated by CBL_ALLOC_MEM is freed when the program that allocated it is canceled (logically or physically), if there is a COBOL program that is directly or indirectly the caller.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_ALLOC_DYN_MEM

Dynamically allocates memory, and can associate it with the calling program.

Syntax:

call "CBL_ALLOC_DYN_MEM" using     mem-pointer
                         by value  mem-size
                                   flags
                         returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer. Must be level 01.
mem-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

mem-size
The number of bytes of memory to allocate.
flags
The type of memory required. You can set the following bits:
Bits 0-1 | Reserved. Must be set to 0.
Bit 2 | Allocate this memory independently from any calling program.
Remaining bits | Reserved. Must be set to 0.

On Exit:

mem-pointer
A pointer to the memory allocated. The allocated memory is not initialized.
status-code
0 | Successful allocation
157 | Unable to allocate memory
181 | Contradictory flags specification

Comments:

The memory allocated is not initialized to any value.

The maximum size of this allocated memory is restricted only by your operating system.

If bit 2 is not set the memory allocated by CBL_ALLOC_DYN_MEM is freed when the program that allocated it is canceled (logically or physically), if there is a COBOL program that is directly or indirectly the caller. If bit 2 is set, this memory is freed when the run unit terminates, if it has not been previously freed by CBL_FREE_DYN_MEM.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_ALLOC_SHMEM

Dynamically allocates shared memory.

Syntax:

call "CBL_ALLOC_SHMEM" using     mem-pointer
                       by value  mem-size
                       by value  flags
                       returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer. Must be level 01.
mem-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags | pic x(4) comp-5
status-code | See Library Routines - Key |

On Entry:

mem-size
The number of bytes of memory to allocate.
flags
Must be set to zero.

On Exit:

mem-pointer
A pointer to the memory allocated. The allocated memory is not initialized.
status-code
0 | Successful allocation
157 | Unable to allocate memory

Comments:

The memory allocated is not initialized to any value.

Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.

The maximum size of shared memory is restricted by the operating system and the run-time system. The run-time tunable, shared_memory_segment_size, can be used to set the maximum size. The size for shared memory allocated using this routine is limited to a maximum of around 64000 bytes.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_ALLOC_THREAD_MEM

Allocates thread-specific heap memory.

Syntax:

call "CBL_ALLOC_THREAD_MEM" using      mem-pointer
                            by value  mem-size
                            by value  flags
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer. Must be level 01.
mem-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

mem-size
The number of bytes of memory to allocate.
flags
Bits 0-1 | Reserved. Must be set to 0.
Bit 2 | Allocate this memory independently from any calling program.
Remaining bits | Reserved. Must be set to 0.

On Exit:

mem-pointer
A pointer to the memory allocated. The allocated memory is not initialized.
status-code
0 | Successful allocation
157 | Unable to allocate memory
181 | Contradictory flags specification

Coments:

If bit 2 is not set the memory allocated by CBL_ALLOC_THREAD_MEM is freed when the program that allocated it is canceled (logically or physically), if there is a COBOL program that is directly or indirectly the caller.

If bit 2 is set, this memory is freed when the thread that allocated it terminates, if it has not been previously freed by CBL_FREE_THREAD_MEM.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_FREE_DYN_MEM

Frees dynamically allocated memory allocated by the CBL_ALLOC_DYN_MEM routine.

Syntax:

call "CBL_FREE_DYN_MEM" using by value mem-pointer
                        returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer. Must be level 01.
status-code | See Library Routines - Key

On Entry:

mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_DYN_MEM.

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_DYN_MEM routine.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_FREE_MEM

Frees dynamically allocated memory.

Syntax:

call "CBL_FREE_MEM" using by value mem-pointer
                    returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer.
status-code | See Library Routines - Key

On Entry:

mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_MEM.

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_MEM routine.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_FREE_SHMEM

Frees dynamically allocated shared memory.

Syntax:

call "CBL_FREE_SHMEM" using by value    mem-pointer
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer. Must be level 01. | usage pointer. Must be level 01.
status-code | See Library Routines - Key

On Entry:

mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_SHMEM.

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_SHMEM routine.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_FREE_THREAD_MEM

Frees dynamically allocated thread-specific heap memory.

Syntax:

call "CBL_FREE_THREAD_MEM" using by value mem-pointer
                           returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
mem-pointer | cblt-pointer | usage pointer.
status-code | See Library Routines - Key

On Entry:

mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_THREAD_MEM.

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_THREAD_MEM routine.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_MEM_STRATEGY

Changes the memory strategy for an application dynamically.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_MEM_STRATEGY" using by value     func
                              by reference flags
                              returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
func | cblt-x4-comp-5 | pic x(4) comp-5.
flags | cblt-x4-comp-5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

func
0 | Get memory strategy
1 | Set memory strategy
2 | Get number of freed memory blocks being checked
3 | Set number of freed memory blocks to be checked
flags
If func is set to 1, flags indicates the memory strategy to set, as follows:
Bit 0
0 | No action
1 | Check bytes strategy: prepend and append check bytes to each memory allocation
Bit 1
0 | No action
1 | Check freed memory strategy: monitor for subsequent corruption the last n memory blocks freed, where n is the current value as set when func is set to 3
Bit 2
0 | No action
1 | Reuse strategy: allow freed memory being monitored for corruption to be used to satisfy allocation requests
Bits 3-29
Reserved for future use. Must be set to zero.
Bit 30
0 | No action
1 | Compatibility strategy: maintain compatibility with previous versions of the run-time system
Bit 31
0 | No action
1 | Validate strategy: validate memory each time an allocation or free operation occurs
If func is set to 3, flags indicates the number of freed memory blocks to be monitored for corruption.

On Exit:

flags
If func is set to 0, flags indicates the current memory strategy,as follows:
Bit 0
0 | No action
1 | Check bytes strategy: prepend and append check bytes to each memory allocation
Bit 1
0 | No action
1 | Check freed memory strategy: monitor for subsequent corruption the last n memory blocks freed, where n is the current value as set when func is set to 3
Bit 2
0 | No action
1 | Reuse strategy: allow freed memory being monitored for corruption to be used to satisfy allocation requests
Bits 3-29
Reserved for future use. Set to zero.
Bit 30
0 | No action
1 | Compatibility strategy: maintain compatibility with previous versions of of the run-time system
Bit 31
0 | No action
1 | Validate strategy: validate memory each time an allocation or free operation occurs
If func is set to 2, flags indicates the number of freed memory blocks being monitored for corruption.
status-code
Status of operation:
0 | All memory allocations are intact
1000 | Insufficient memory to perform request
1009 | Invalid parameter specified

Comments:

Use this routine to change the memory strategy for an application from within the application. It provides the same functionality as that provided by the memory_strategy and memory_free_check_size run-time tunables.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


CBL_MEM_VALIDATE

Validates memory allocations, monitored freed memory, and, if the operating system supports it, compacts memory heaps.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_MEM_VALIDATE" using by value     flags
                              by reference param
                              returning    status-code

Parameters:

flags
Using call prototype (see Key): cblt-x4-comp-5
Picture: pic x(4) comp-5.
param
Group predefined as :
01 cblt-mem-validate-param
   03 cblte-mv-version    cblt-x4-comp-5    *> pic x(4) comp-5.
   03 cblte-mv-flags      cblt-x4-comp-5    *> pic x(4) comp-5.
   03 cblte-mv-type       cblt-x4-comp-5    *> pic x(4) comp-5.
   03 cblte-mv-size       cblt-os-size    		*> 32-bit: pic x(4) comp-5.
                                                                                64-bit: pic x(8) comp-5.
   03 cblte-mv-address    cblt-pointer      *> pointer

On Entry:

flags
Validation control flags:
Bit 0
0 | No action
1 | Validate all memory allocations
Bit 1
0 | No action
1 | Validate all freed memory
2-30 | Reserved for future use. Must be set to zero.
Bit 31
0 | No action
1 | Compact memory
cblte-mv-version
Parameter block version; must be zero.

On Exit:

param
Fields are set only if the routine returns 1000
cblte-mv-flags
Information flags:
Bit 0
0 | cblte-mv-address not set
1 | cblte-mv-address contains address of corrupted memory block
Bit 1
0 | cblte-mv-address is user data address
1 | cblte-mv-address is memory header address
Bit 2
0 | cblte-mv-size not set
1 | cblte-mv-size contains size of corrupt memory block
Bit 3
0 | cblte-mv-type not set
1 | cblte-mv-type contains type of corrupt memory block
Bit 4
0 | Corruption in allocated memory
1 | Corruption in freed memory
Bit 5
0 | Corruption detected by run-time system
1 | Corruption detected by operating system
Bits 6-31
Reserved for future use.
status-code
Status of operation:
0 | All memory allocations are intact
1000 | Memory corruption detected
1009 | Invalid parameter specified

Comments:

Use this routine to validate memory allocations, monitored freed memory, and, if the operating system supports it, to compact memory heaps. Use this routine in preference to the validate memory strategy, set using the memory_strategy run-time tunable.

If you set the Compact memory flag, the routine attempts to compact memory to the extent that the operating system allows. There is no information flag setting that indicates the result.

Example:

       program-id. CblMemValidateExample as "CblMemValidateExample".

       environment division.
       configuration section.

       data division.
       working-storage section.
       01 cbl-mem-flags pic x(4) comp-5 value zero.
        01 cbl-mem-params.
           05  cbl-mem-version pic x(4) comp-5 value zero.
           05  cbl-mem-mv-flags pic x(4) comp-5 value zero.
           05  cbl-mem-mv-type pic x(4) comp-5 value zero.
           05  cbl-mem-mv-size pic x(4) comp-5 value zero.
           05  cbl-mem-mv-addr usage pointer value null.
       01 cbl-mem-return-code pic x(2) comp-5 value zero.
       01 any-key pic x.

       procedure division.

      *Call directly setting the bits
           call 'CBL_MEM_VALIDATE' using by value H'00000001'
                                         by reference cbl-mem-params
                                   returning cbl-mem-return-code.
           display 'CBL_MEM_VALIDATE setting bits returned: '
                   cbl-mem-return-code.

      *Same call using variable to set flags
       move 1 to cbl-mem-flags
           call 'CBL_MEM_VALIDATE' using by value cbl-mem-flags
                                         by reference cbl-mem-params
                                   returning cbl-mem-return-code.
           display 'CBL_MEM_VALIDATE using variable returned: '
                   cbl-mem-return-code.
       accept any-key.

           goback.

       end program CblMemValidateExample.
Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


Multi-threading Routines

Call-by-name library routines provide a programming interface through which you can implement and control multi-threading in your applications.

  • Thread-control Routines
  • Synchronization routines
  • Routines for Handling Thread-specific Data
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines
RETURN-CODE Values For Thread-control Routines
RETURN-CODE Values For Thread-specific Data Handling Routines


Thread-control Routines

  • CBL_THREAD_CREATE
    Creates a thread from a named entry point.
  • CBL_THREAD_CREATE_P
    Creates a thread from a procedure pointer.
  • CBL_THREAD_DETACH
    Frees thread resources when the thread terminates.
  • CBL_THREAD_EXIT
    Terminates the current thread.
  • CBL_THREAD_IDDATA_ALLOC
    Allocates an id-data area for the current thread.
  • CBL_THREAD_IDDATA_GET
    Returns a pointer to the id-data area for the specified thread.
  • CBL_THREAD_KILL
    Kills the specified thread, terminating it abnormally and detaching all resources associated with it.
  • CBL_THREAD_LIST_END
    Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_NEXT to obtain a list of all currently existing threads that the run-time system knows about. It is required to terminate a CBL_THREAD_LIST_START.
  • CBL_THREAD_LIST_NEXT
    Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about. The CBL_THREAD_LIST_NEXT call takes returns the next item in the list of threads.
  • CBL_THREAD_LIST_START
    Used in conjunction with CBL_THREAD_LIST_NEXT and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about.
  • CBL_THREAD_LOCK
    Locks most functions of the thread-handling routines.
  • CBL_THREAD_PROG_LOCK
    With CBL_THREAD_PROG_UNLOCK, provides a single pre-initialized synchronization object per calling COBOL program
  • CBL_THREAD_PROG_UNLOCK
    With CBL_THREAD_PROG_LOCK, provides a single pre-initialized synchronization object per calling COBOL program
  • CBL_THREAD_RESUME
    Resumes a thread that was or will be suspended by CBL_THREAD_SUSPEND.
  • CBL_THREAD_SUSPEND
    Suspends the current thread.
  • CBL_THREAD_SELF
    Stores the thread identifier of the current thread.
  • CBL_THREAD_SLEEP
    Causes the calling thread to give up control to the processor for the given number of milliseconds.
  • CBL_THREAD_UNLOCK
    Unlocks most functions of the thread handling routines.
  • CBL_THREAD_WAIT
    Waits for completion of the specified non-detached thread, or returns immediately if the thread has already completed.
  • CBL_THREAD_YIELD
    Yields the rest of the current thread's timeslice.
  • RETURN-CODE Values For Thread-control Routines
  • Using the Program Thread-locking Routines
  • Using CBL_THREAD_SELF to Check Operating System
Parent topic: Multi-threading Routines
Related information
Alphabetical List of Library Routines


CBL_THREAD_CREATE

Creates a thread from a named entry point.

Syntax:

call "CBL_THREAD_CREATE" using by reference entry-name
                         by reference       thread-param
                         by value           param-size
                         by value           flags
                         by value           priority
                         by value           stack-size
                         by reference       thread-id

Parameters:

 | Using call prototype (see Key) | Picture
entry-name | pic x(n) space or null terminated | pic x(n) space or null terminated
thread-param | pic x(n) space or null terminated | Any data item.
param-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
priority | cblt-sx4-comp5 | pic s9(9) comp-5
stack-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
thread-id | cblt-pointer | usage pointer.

On Entry:

entry-name
Space or null terminated name for the thread
thread-param
Parameter passed to the new thread
param-size
Set to one of the following values:
0 | Only the address of thread-param is passed as the parameter to the entry point in the new thread without any copying of data values
>0 | The value of thread-param is copied for a length of param-size and the address of this copy area is passed to the new thread. The value of thread-param will still be intact for the created thread, even if the creating thread changes or deallocates thread-param immediately after the CBL_THREAD_CREATE call.
flags
A number, in which the bits can be set as follows:
Bit 0
0 | Detach thread immediately when the thread terminates.
1 | Do not detach thread immediately. Even when the thread has terminated, its resources are not freed until the thread is detached.
Bit 1
0 | Thread priority is relative (-100 to +100).
1 | Thread priority is absolute (0 to 100).
Bit 2
0 | Any monitors or mutexes locked by this thread when the thread terminates can cause a run-time system error.
1 | An error will not be issued if monitors or mutexes are locked when the thread terminates
Bit 3
0 Create active
1 Create suspended
Restriction: This is deprecated in the JVM environment
Bit 4
Restriction: This bit is not supported in JVM COBOL.
0 | Multi-threaded Apartment model (MTA)
1 | Single threaded Apartment model (STA)
Remaining bits
Reserved
priority
Set the priority. Normally, the priority is in the range -100 to+100 and is relative to the current thread's priority. Values of -1 and +1 indicate the smallest decrement/increment that gives the thread a lower/higher priority than the caller (unless the caller already has the lowest/highest possible priority). If a negative/positive value would take the thread's priority lower/higher than is possible, then the lowest/highest value is used. If bit 1 of flags is set to 1, then the priority is an absolute value 0 to 100.
stack-size
Tell the run-time system how big a stack to give the new thread. A value of 0 causes a sensible default to be used. If the parameter appears to be invalid, the run-time system will either ignore it, or return an error indicating an invalid value was provided.

On Exit:

thread-id
A thread identifier.
return-code
A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

The entry point specified can be implemented in any language.

If the call succeeds and a new thread is created, its thread identifier is stored in thread-id and the RETURN-CODE is set to 0. This is true even if the thread is created detached, however in this case the caller should take care to ensure that the new thread still exists before using the thread-id in any other call.

If the call fails thread-id is set to NULL and an error number is set in RETURN-CODE.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
RETURN-CODE Values For Thread-control Routines
Routines for Handling Thread-specific Data
Multi-threading Routines
RETURN-CODE Values For Thread-specific Data Handling Routines


CBL_THREAD_CREATE_P

Creates a thread from a procedure pointer.

Syntax:

call "CBL_THREAD_CREATE_P" using  by value entry-point
                           by reference    thread-param
                           by value        param-size
                           by value        flags
                           by value        priority
                           by value        stack-size
                           by reference    thread-id

Parameters:

 | Using call prototype (see Key) | Picture
entry-point | cblt-ppointer | usage procedure-pointer.
thread-param | pic x(n) null or space terminated | Any data item.
param-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
priority | cblt-sx4-comp5 | pic s9(9) comp-5
stack-size | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
thread-id | cblt-pointer | usage pointer.

On Entry:

entry-point
Procedure-pointer set to the appropriate entry point of program to execute.
thread-param
Parameter passed to the new thread
param-size
Set to one of the folllowing:
0 | Only the address of thread-param is passed as the parameter to the entry point in the new thread without any copying of data values
>0 | The value of thread-param is copied for a length of param-size and the address of this copy area is passed to the new thread. The value of thread-param will still be intact for the created thread, even if the creating thread changes or deallocates thread-param immediately after the CBL_THREAD_CREATE call.
flags
A number in which the bits can be set as follows:
Bit 0
0 | Detach thread immediately when the thread terminates.
1 | Do not detach thread immediately. Even when the thread has terminated, its resources are not freed until thread is detached.
Bit 1
0 | Thread priority is absolute (0 to 100).
1 | Thread priority is relative (-100 to +100).
Bit 2
0 | Any monitors or mutexes locked by this thread when the thread terminates can cause a run-time system error.
1 | An error will not be issued if monitors or mutexes are locked when the thread terminates
Bit 3
0 Create active
1 Create suspended
Restriction: This is deprecated in the JVM environment
Bit 4
Restriction: This bit is not supported in JVM COBOL.
0 | Multi-threaded Apartment model (MTA)
1 | Single threaded Apartment model (STA)
Remaining bits
Reserved.
priority
Sets the priority. Normally, the priority is in the range -100 to+100 and is relative to the current thread's priority. Values of -1 and +1 indicate the smallest decrement/increment that gives the thread a lower/higher priority than the caller (unless the caller already has the lowest/highest possible priority). If a negative/positive value would take the thread's priority lower/higher than is possible, then the lowest/highest value is used. If bit 1 of flags is set to 1, then the priority is an absolute value 0 to 100.
stack-size
Tells the run-time system how big a stack to give the new thread. A value of 0 causes a sensible default to be used. If the parameter appears to be invalid, the run-time system will either ignore it, or return an error indicating an invalid value was provided.

On Exit:

thread-id
A thread identifier.
return-code
A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

The entry point specified can be implemented in any language.

If the call succeeds and a new thread is created, its thread identifier is stored in thread-id and the RETURN-CODE is set to 0. This is true even if the thread is created detached, however in this case the caller should take care to ensure that the new thread still exists before using the thread-id in any other call.

If the call fails thread-id is set to NULL and an error number is set in RETURN-CODE.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
RETURN-CODE Values For Thread-control Routines
Routines for Handling Thread-specific Data
Multi-threading Routines
RETURN-CODE Values For Thread-specific Data Handling Routines


CBL_THREAD_DETACH

Frees thread resources when the thread terminates.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_THREAD_DETACH" using by value thread-id

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

CBL_THREAD_DETACH enables a thread's resource to be freed when that thread terminates. When a thread is created (non-detached) a handle is returned to the creator. That handle can be used to wait for a thread, retrieve a return-code from the thread, inspect a thread's state, and so on. If a thread terminates, that handle is still valid until a WAIT or DETACH is done; that is, resources are still allocated to the (terminated) thread. If a thread is detached then all resources from a terminated thread are freed immediately; if the thread is still active those resources are marked to be freed when the thread terminates.

Behavior is undefined if:

  • thread-id is undefined
  • Two threads attempt to call CBL_THREAD_WAIT and/or CBL_THREAD_DETACH for the same thread at the same time

If successful, RETURN-CODE is set to 0. If unsuccessful, the call will attempt to return an error number. However, because some behaviors are undefined, a call that fails could result in a run-time system error.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_EXIT

Terminates the current thread.

Syntax:

call "CBL_THREAD_EXIT" using by value return-value

Parameters:

 | Using call prototype (see Key) | Picture
return-value | cblt-pointer | usage pointer.

On Entry:

None.

On Exit:

return-value | Value returned from the thread processing
return-code | A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

In a thread created by CBL_THREAD_CREATE, this call has the same effect as executing STOP RUN RETURNING return-value from a COBOL program, or cobexit() from a program in another language. This function can also be called from a program in another programming language, in preference to using cobexit().

This call will fail, returning an error code, if the current thread was not created with CBL_THREAD_CREATE.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_IDDATA_ALLOC

Allocates an id-data area for the current thread.

Syntax:

CBL_THREAD_IDDATA_ALLOC using by reference iddata
                        by value  iddatasize

Parameters:

 | Using call prototype (see Key) | Picture
iddata | cblt_pointer | pic x(n).
iddatasize | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

iddata | Id-data area for the current thread
iddatasize | Size of the id-data area. If it is zero, the thread will have no id-data area.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines.

Comments:

This call allocates an id-data area for the current thread, and registers it so that a further call to CBL_THREAD_IDDATA_GET with this thread's handle will return the pointer to this data area. A call to CBL_THREAD_LIST_START or CBL_THREAD_LIST_NEXT can also be used to retrieve the pointer to this data area.

If there was already an id-data area for this thread, the old one is freed and replaced by the new one. This will not happen if the call fails; typically this occurs if there is not enough memory to allocate the new id-data area.

If the iddata parameter is passed as 'by value 0' then any area allocated is initialized to low-values. Otherwise iddata provides the initialization data for the memory area allocated.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_IDDATA_GET

Returns a pointer to the id-data area for the specified thread.

Syntax:

call "CBL_THREAD_IDDATA_GET" using by reference iddata-ptr
                             by value           thread-id

Parameters:

 | Using call prototype (see Key) | Picture
iddata-ptr | cblt-pointer | usage pointer.
thread-id | cblt-pointer | usage pointer.

On Entry:

iddata-ptr | Pointer tp the id-data area for the specified thread
thread-id | Pointer to the thread identifier

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

Returns a pointer to the id-data area for the specified thread or NULL if no id-data area has been allocated to date.

thread-id might be NULL, in which case a pointer to the current thread's id-data area is returned.

If another thread's id-data area is retrieved by this function the user should make sure that any attempts to access it in all threads are protected by some form of locking (for example, by using CBL_THREAD_LOCK and CBL_THREAD_UNLOCK to frame all accesses to it).

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_KILL

Kills the specified thread, terminating it abnormally and detaching all resources associated with it.

Syntax:

call "CBL_THREAD_KILL" using by value thread-id

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

This routine can only be used to kill a thread that was created with CBL_THREAD_CREATE, and not threads created in other ways.

If the target thread has already completed, but was not detached, this call simply detaches it and discards any return value.

This call can be used with thread-id set to the current thread. In this case its effect is the same as CBL_THREAD_EXIT with a NULL return value.

Behavior is undefined:

  • If thread-id is invalid
  • For any thread that has a call to CBL_THREAD_WAIT for the killed thread
Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_LIST_END

Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_NEXT to obtain a list of all currently existing threads that the run-time system knows about. It is required to terminate a CBL_THREAD_LIST_START.

Syntax:

call "CBL_THREAD_LIST_END"

Parameters:

None.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

If unsuccessful, this routine returns an error number in RETURN_CODE. However, because some behaviors are undefined, a call to this routine that fails could result in a run-time system error.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_LIST_NEXT

Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about. The CBL_THREAD_LIST_NEXT call takes returns the next item in the list of threads.

Syntax:

call "CBL_THREAD_LIST_NEXT" using by reference thread-id
                            by reference       thread-state
                            by reference       thread-iddata

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.
thread-state | cblt-x4-compx | pic x(4) comp-x.
thread-iddata | cblt-pointer | usage pointer.

On Entry:

None

On Exit:

thread-id
First thread identifier in this routine's internal list
thread-state
The state of the thread:
Bit 0
0 | Not detached
1 | Detached
Bit 1
0 | Not suspended.
1 | Suspended by CBL_THREAD_SUSPEND
Bit 2
0 | Thread is not the main thread.
1 | Thread is from a program in another language, and is known to the run-time system, or is the main thread
Bits 3-31
Undefined; could be any value
thread-iddata
A pointer to the thread's id-data, if that data area exists (otherwise NULL). id-data is specified by the routine CBL_THREAD_ALLOC_IDDATA.
return-code
A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

Only information on existing threads, that is, threads that have not terminated, is returned. This routine will not return a thread-id for a thread that has terminated but has not been detached.

If thread-id is NULL then the first item in the list is returned (but there must have been a previous CBL_THREAD_LIST_START call).

Behavior is undefined if thread-id is invalid.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_LIST_START

Used in conjunction with CBL_THREAD_LIST_NEXT and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about.

Syntax:

call "CBL_THREAD_LIST_START" using by reference thread-id
                             by reference       thread-state
                             by reference       thread-iddata

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.
thread-state | cblt-x4-compx | pic x(4) comp-x.
thread-iddata | cblt-pointer | usage pointer.

On Entry:

None.

On Exit:

thread-id
First thread identifier in this routine's internal list.
thread-state
The state of the thread:
Bit 0
0 | Not detached
1 | Detached
Bit 1
0 | Not suspended.
1 | Suspended by CBL_THREAD_SUSPEND
Bit 2
0 | Thread is not the main thread.
1 | Thread is from a program in another language, and is known to the run-time system, or is the main thread
Bits 3-31
Undefined; could be any value
thread-iddata
A pointer to the thread's id-data, if that data area exists (otherwise NULL). id-data is specified by the routine CBL_THREAD_ALLOC_IDDATA.
return-code
A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

Only information on existing threads, that is, threads that have not terminated, is returned. This routine will not return a thread-id for a thread that has terminated but has not been detached.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_LOCK

Locks most functions of the thread-handling routines.

Syntax:

call "CBL_THREAD_LOCK"

Parameters:

None.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

This routine can also be used to synchronize access to global or external data, id-data and error handling.

Any thread that obtains a CBL_THREAD_LOCK must not exit before doing a CBL_THREAD_UNLOCK.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_PROG_LOCK

With CBL_THREAD_PROG_UNLOCK, provides a single pre-initialized synchronization object per calling COBOL program

Syntax:

call "CBL_THREAD_PROG_LOCK"

Parameters:

None.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

This function, in conjunction with CBL_THREAD_PROG_UNLOCK, provides a single pre-initialized synchronization object per calling COBOL program. This makes it especially useful for initializing any program local data items or synchronization objects.

Example:

Example

These functions must be called either directly or indirectly from a COBOL program. The calling COBOL program is the one with which the lock is associated.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_PROG_UNLOCK

With CBL_THREAD_PROG_LOCK, provides a single pre-initialized synchronization object per calling COBOL program

Syntax:

call "CBL_THREAD_PROG_UNLOCK"

Parameters:

None.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

This function, in conjunction with CBL_THREAD_PROG_LOCK, provides a single pre-initialized synchronization object per calling COBOL program. This makes it especially useful for initializing any program local data items or synchronization objects.

Example:

Example

These functions must be called either directly or indirectly from a COBOL program. The calling COBOL program is the one with which the lock is associated.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_RESUME

Resumes a thread that was or will be suspended by CBL_THREAD_SUSPEND.

Syntax:

call "CBL_THREAD_RESUME" using by value thread-id

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

If the specified thread is suspended when a call to this routine is made, then RETURN-CODE is set to 0. If the specified thread was not suspended then the RETURN-CODE is set to the negative value of the number of times the target thread will have to call CBL_THREAD_SUSPEND before its execution is actually suspended.

Behavior is undefined if thread-id is invalid.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_SUSPEND

Suspends the current thread.

Syntax:

call "CBL_THREAD_SUSPEND" using by value thread-id

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

If thread-id is NULL or is the current thread, this routine suspends the current thread until another thread does a CBL_THREAD_RESUME on it. If successful, RETURN_CODE is set to 0. If one or more CBL_THREAD_RESUME routines have already targeted this thread then RETURN_CODE is set to the negative value of the number of further times CBL_THREAD_SUSPEND will have to be called before the thread is actually suspended.

Otherwise, the call returns a non-zero (positive) error code.

You cannot suspend threads other than the current thread.

Behavior is undefined if thread-id is invalid.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_SELF

Stores the thread identifier of the current thread.

Syntax:

call "CBL_THREAD_SELF" using by reference thread-id

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

The run-time system returns the thread identifier and stores it in thread-id.

You can check that the run-time system under which your program is running supports multi-threading by a call to CBL_THREAD_SELF.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines
Related tasks
Using CBL_THREAD_SELF to Check Operating System


CBL_THREAD_SLEEP

Causes the calling thread to give up control to the processor for the given number of milliseconds.

Syntax:

call "CBL_THREAD_SLEEP" using by value milliseconds

Parameters:

 | Using call prototype (see Key) | Picture
milliseconds | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

milliseconds Number of milliseconds

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

If the operating system does not support yielding a thread for millisecond granularity, then the units are scaled to a granularity that the operating system supports. The scaling is performed rounding to the nearest operating system supported unit.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_UNLOCK

Unlocks most functions of the thread handling routines.

Syntax:

call "CBL_THREAD_UNLOCK"

Parameters:

None.

On Exit:

return-code A value indicating success or otherwise. See RETURN-CODE Values For Thread-control Routines

Comments:

This routine can also be used to synchronize access to global or external data, id-data and error handling.

Any thread that obtains a CBL_THREAD_LOCK must not exit before doing a CBL_THREAD_UNLOCK.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_WAIT

Waits for completion of the specified non-detached thread, or returns immediately if the thread has already completed.

Syntax:

call "CBL_THREAD_WAIT" using by value thread-id
                       by reference   thr-return
                       returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
thread-id | cblt-pointer | usage pointer.
thr-return | cblt-pointer | usage pointer.

On Entry:

thread-id A pointer to the thread identifier

On Exit:

thr-return | The thread's return value.
status-code | See RETURN-CODE Values For Thread-control Routines

Comments:

The behavior of this routine is undefined if:

  • thread-id is invalid.
  • thread-id specifies a previously detached thread.
  • Two threads attempt to use CBL_THREAD_WAIT and/or CBL_THREAD_DETACH on the same thread at the same time.
  • While in a CBL_THREAD_WAIT, the target thread is killed by CBL_THREAD_KILL.

If the routine is successful, the thread's return value is stored in thr-return, the target thread is detached, and the call returns 0.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


CBL_THREAD_YIELD

Yields the rest of the current thread's timeslice.

Syntax:

call "CBL_THREAD_YIELD"

Parameters:

None.

On Exit:

return-code A value indicating whether the routine has succeeded or not. See RETURN-CODE Values For Thread-control Routines

Comments:

If possible this routine yields to other threads in the same process, but might yield to a thread in a different process.

Parent topic: Thread-control Routines
Parent topic: Alphabetical List of Library Routines


RETURN-CODE Values For Thread-control Routines

The following values are provided as RETURN-CODE values from the thread-control routines:

0 | No error was encountered.
1000 | Memory allocation error.
1001 | The thread is invalid. The handle is not a valid handle for the synchronization object, and no operations are valid on it. It is possible that the handle specified was once valid but it has been closed and memory reused.
1002 | The thread has been closed. No operations are valid on this handle. The handle was once valid but has since been closed.
1003 | The thread is detached. CBL_THREAD_DETACH cannot detach the thread since it has already been detached. CBL_THREAD_WAIT cannot wait on the thread since it has already been detached.
1004 | Too many threads. CBL_THREAD_CREATE cannot create another thread since too many threads exist in the system already.
1005 | The stack size is invalid. CBL_THREAD_CREATE cannot create this thread as the operating system will not allow the provided stack size to be used.
1006 | Invalid operation. CBL_THREAD_CREATE cannot create a thread while the system is deinitializing. or: An invalid thread-control routine was attempted on a thread that was not created with CBL_THREAD_CREATE. or: CBL_THREAD_PROG_LOCK was not called directly or indirectly from a COBOL program.
1007 | A system error was encountered. The last operation caused a system error in low level object manipulation.
1008 | Threading not supported in this run-time system. A threaded application attempted to use a multi-threading routine while running with a non-threaded run-time system.
1009 | Invalid parameter passed into a multi-threading library routine. A parameter has been detected that is not within the valid range, or that is inconsistent with the library routine.
1010 | No resources available. A semaphore or mutex cannot be acquired because its count is zero and the user requested no automatic wait. or: An event is not posted and the user has no wait on the CBL_EVENT_WAIT call.
1011 | Program or entry-point name not found. The program or entry-point name specified to CBL_THREAD_CREATE was not found, or there was an error loading it.
Parent topic: Thread-control Routines


Using the Program Thread-locking Routines

The following code at the entry to a program ensures that only the first thread entering a program will initialize data and all following threads will have that preinitialized data available:

if  first-time = 0
         call "cbl_thread_prog_lock"
        if  first-time = 0
             initialize my-data-division
            move 1 to first-time
        end-if
        call "cbl_thread_prog_unlock"
    end-if

Note the double check of the first-time variable. The first check is an optimization that avoids the overhead of locking the program if we know for sure that it has already been initialized.

Parent topic: Thread-control Routines


Using CBL_THREAD_SELF to Check Operating System

You can use CBL_THREAD_SELF to check that the operating system supports multi-threading as follows:

call 'cbl_thread_self' using thread-id
     on exception
         *> no cbl_thread api support
     end-call
     if  return-code = 1008
         *> running in a single threaded only rts
     end-if
Parent topic: Thread-control Routines
Related reference
CBL_THREAD_SELF


Synchronization routines

Mutexes, semaphores, monitors and events can be used to synchronize threads. Synchronization objects are named, and the name is visible throughout the system, not just in the creating process.

  • Synchronization routines - monitors
  • Synchronization routines - semaphores
  • Synchronization routines - mutexes
  • Synchronization routines - events
  • RETURN-CODE Values For Synchronization Routines
Parent topic: Multi-threading Routines


Synchronization routines - monitors

  • Monitors - General Notes
  • CBL_MONITOR_BROWSE
    Acquires the specified monitor's browse capability for the current thread, blocking until that capability can be acquired.
  • CBL_MONITOR_BROWSE_TO_READ
    Converts monitor browse capability already acquired by the current thread to read capability.
  • CBL_MONITOR_BROWSE_TO_WRITE
    Converts monitor browse capability already acquired by the current thread to write capability, blocking until this can be achieved.
  • CBL_MONITOR_CLOSE
    Closes the supplied monitor handle.
  • CBL_MONITOR_OPEN_INTRA
    Creates a monitor synchronization object for thread synchronization within one process.
  • CBL_MONITOR_READ
    Acquires the specified monitor's read capability for the current thread/process, blocking until that capability can be acquired.
  • CBL_MONITOR_RELEASE
    Releases any lock currently applied to the specified monitor by CBL_MONITOR_WRITE, CBL_MONITOR_READ or CBL_MONITOR_BROWSE.
  • CBL_MONITOR_UNBROWSE
    Releases the monitor's browse capability that was acquired by CBL_MONITOR_BROWSE or CBL_MONITOR_WRITE_TO_BROWSE.
  • CBL_MONITOR_UNREAD
    Releases the monitor's read capability that was acquired by CBL_MONITOR_READ or CBL_MONITOR_BROWSE_TO_READ.
  • CBL_MONITOR_UNWRITE
    Releases the monitor's write capability that was acquired by CBL_MONITOR_WRITE or CBL_MONITOR_BROWSE_TO_WRITE.
  • CBL_MONITOR_WRITE
    Acquires the specified monitor's write capability for the current thread, blocking until that capability can be acquired.
  • CBL_MONITOR_WRITE_TO_BROWSE
    Converts monitor write capability already acquired by the current thread to browse capability.
Parent topic: Synchronization routines


Monitors - General Notes

A monitor is a synchronization object which can be locked for read, browse, and write operations. This type of synchronization is typically used to protect a data structure in which different threads might want to read and write.

A monitor can only be used as an intra-process synchronization object.

Any monitors created or opened using the library routines are automatically closed when the run-time system terminates (for example, as a consequence of a STOP RUN).

A write lock locks out all other read, browse, and write locks. Typically, a write lock is used when writing to the data structure.

A browse lock locks out other write and browse locks, but allows simultaneous read locks. Typically, a browse lock is used when reading a data structure with a view to writing to it depending on the results of the read. To this end, a function is provided to convert a browse lock to a write lock without letting in any other writers.

A read lock only locks out write locks. Typically, a read lock is used when reading a data structure without any intention of writing to it.

If a thread has acquired a lock, the results of attempting to acquire a further lock before that original lock has been released are undefined except in the case where a conversion to or from a browse lock is performed.

Parent topic: Synchronization routines - monitors


CBL_MONITOR_BROWSE

Acquires the specified monitor's browse capability for the current thread, blocking until that capability can be acquired.

Syntax:

call "CBL_MONITOR_BROWSE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If the thread terminates abnormally, all monitors acquired by that thread are released. If the thread terminates normally with monitors acquired, then either these are released or a run-time system error is given, depending on the flag setting when the thread was created with CBL_THREAD_CREATE.

Behavior is undefined if monitor-handle is invalid.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_BROWSE_TO_READ

Converts monitor browse capability already acquired by the current thread to read capability.

Syntax:

call "CBL_MONITOR_BROWSE_TO_READ" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if:

  • No previous browse lock was obtained by this thread on the specified monitor
  • monitor-handle is invalid.
Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_BROWSE_TO_WRITE

Converts monitor browse capability already acquired by the current thread to write capability, blocking until this can be achieved.

Syntax:

call "CBL_MONITOR_BROWSE_TO_WRITE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if:

  • No previous browse lock was obtained by this thread on the specified monitor
  • monitor-handle is invalid.
Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_CLOSE

Closes the supplied monitor handle.

Syntax:

call "CBL_MONITOR_CLOSE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If this process is the last process that has a handle to the monitor, then the monitor is destroyed.

Behavior is undefined if monitor-handle is invalid.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_OPEN_INTRA

Creates a monitor synchronization object for thread synchronization within one process.

Syntax:

call "CBL_MONITOR_OPEN_INTRA" using by reference monitor-handle
                              by value           open-flags

Parameters

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.
open-flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

open-flags
A value indicating the priority algorithm used to grant locks:
Bit 0
0 | Readers and writers have interleaved priority; that is, if a write request is issued, any further read requests will block until the first write request is granted and finished
1 | Read requests always have priority, possibly leading to writer starvation.
Remaining bits
Reserved and should be set to zero.

On Exit:

monitor-handle
The monitor handle.
return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If open-flags bit 0 is set to 0, and nested read locks are requested, then single thread deadlock is possible.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_READ

Acquires the specified monitor's read capability for the current thread/process, blocking until that capability can be acquired.

Syntax:

call "CBL_MONITOR_READ" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If the thread terminates abnormally, all monitors acquired by that thread are released. If the thread terminates normally with monitors acquired, then either these are released or a run-time system error is given, depending on the flag setting when the thread was created with CBL_THREAD_CREATE.

Behavior is undefined if monitor-handle is invalid.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_RELEASE

Releases any lock currently applied to the specified monitor by CBL_MONITOR_WRITE, CBL_MONITOR_READ or CBL_MONITOR_BROWSE.

Syntax:

call "CBL_MONITOR_RELEASE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If the thread terminates abnormally, all monitors acquired by that thread are released. If the thread terminates normally with monitors acquired, then either these are released or a run-time system error is given, depending on the flag setting when the thread was created with CBL_THREAD_CREATE.

Behavior is undefined if either monitor-handle is invalid or no previous lock was obtained by this thread on the specified monitor.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_UNBROWSE

Releases the monitor's browse capability that was acquired by CBL_MONITOR_BROWSE or CBL_MONITOR_WRITE_TO_BROWSE.

Syntax:

call "CBL_MONITOR_UNBROWSE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if either monitor-handle is invalid or no previous browse lock was obtained by this thread on the specified monitor.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_UNREAD

Releases the monitor's read capability that was acquired by CBL_MONITOR_READ or CBL_MONITOR_BROWSE_TO_READ.

Syntax:

call "CBL_MONITOR_UNREAD" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer. | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if either monitor-handle is invalid or no previous browse lock was obtained by this thread on the specified monitor.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_UNWRITE

Releases the monitor's write capability that was acquired by CBL_MONITOR_WRITE or CBL_MONITOR_BROWSE_TO_WRITE.

Syntax:

call "CBL_MONITOR_UNWRITE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer. | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if either monitor-handle is invalid or no previous browse lock was obtained by this thread on the specified monitor.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_WRITE

Acquires the specified monitor's write capability for the current thread, blocking until that capability can be acquired.

Syntax:

call "CBL_MONITOR_WRITE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer. | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If the thread terminates abnormally, all monitors acquired by that thread are released. If the thread terminates normally with monitors acquired, then either these are released or a run-time system error is given, depending on the flag setting when the thread was created.

Behavior is undefined if monitor-handle is invalid.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


CBL_MONITOR_WRITE_TO_BROWSE

Converts monitor write capability already acquired by the current thread to browse capability.

Syntax:

call "CBL_MONITOR_WRITE_TO_BROWSE" using by value monitor-handle

Parameters:

 | Using call prototype (see Key) | Picture
monitor-handle | cblt-pointer. | usage pointer.

On Entry:

monitor-handle The monitor handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if either monitor-handle is invalid or no previous browse lock was obtained by this thread on the specified monitor.

Parent topic: Synchronization routines - monitors
Parent topic: Alphabetical List of Library Routines


Synchronization routines - semaphores

  • Semaphores - General Notes
  • CBL_SEMAPHORE_ACQUIRE
    Acquires one of the resources represented by the semaphore by decrementing the associated count.
  • CBL_SEMAPHORE_CLOSE
    Closes the specified semaphore.
  • CBL_SEMAPHORE_OPEN_INTRA
    Creates an intra-process semaphore.
  • CBL_SEMAPHORE_RELEASE
    Releases one of the resources represented by the semaphore by incrementing the associated count.
Parent topic: Synchronization routines


Semaphores - General Notes

Semaphores can be used for thread synchronization within the same process.

A semaphore is a synchronization object which has a count associated with it, typically representing the available number of some limited resource. A thread acquires one of these resources by using the acquire call; if none of the resources is available, the call either blocks or returns with an error depending on a "wait" option. If a resource is available (the count is non-zero), the count is decremented and the call returns with no error.

A thread releases a resource using the release call, which increments the count; if other threads are blocked because no resources are available (the count is zero), one of them is released. The others remain blocked because in the process of releasing the first one, the count is decremented back to zero.

Parent topic: Synchronization routines - semaphores


CBL_SEMAPHORE_ACQUIRE

Acquires one of the resources represented by the semaphore by decrementing the associated count.

Syntax:

call "CBL_SEMAPHORE_ACQUIRE" using by value semaphore-handle
                                   by value flags
                                  [by value timeout]

Parameters:

 | Using call prototype (see Key) | Picture
semaphore-handle | cblt-pointer | usage pointer
flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
timeout |  | pic x(4) comp-5

On Entry:

semaphore-handle
Semaphore handle.
flags
A value that determines the action of the routine if the count is zero:
Bit 0
0 Block the thread/process until the count is non-zero, then the count is decremented and the call returns.
1

If no timeout is supplied (i.e. bit 1 = 0) then return immediately, no decrement

If timeout supplied (i.e. bit 1=1 ) then block until count is non-zero or timeout duration has expired. If the timeout expires, return error code 1010 ("no resources available"), else decrement count and return

Bit 1
0 | No timeout parameter supplied
1 | Timeout parameter is supplied and used if bit 0=1
Remaining bits
Reserved. Must be set to zero.
timeout
The timeout value in milliseconds. A value of zero returns immediately. This parameter is mandatory if bit 1=1 for the flags parameter; otherwise, it is optional.

On Exit:

return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

Behavior is undefined if semaphore-handle is invalid.

Parent topic: Synchronization routines - semaphores
Parent topic: Alphabetical List of Library Routines


CBL_SEMAPHORE_CLOSE

Closes the specified semaphore.

Syntax:

call "CBL_SEMAPHORE_CLOSE" using by value semaphore-handle

Parameters:

semaphore-handle pointer

On Entry:

semaphore-handle Semaphore handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

The semaphore is destroyed.

Behavior is undefined if semaphore-handle is invalid.

Parent topic: Synchronization routines - semaphores
Parent topic: Alphabetical List of Library Routines


CBL_SEMAPHORE_OPEN_INTRA

Creates an intra-process semaphore.

Syntax:

call "CBL_SEMAPHORE_OPEN_INTRA" using by reference semaphore-handle
                                by value           semaphore-start
                                by value           open-flags

Parameters:

 | Using call prototype (see Key) | Picture
semaphore-handle | cblt-pointer | usage pointer.
semaphore-start | cblt-x4-comp5 | pic x(4) comp-5.
open-flags | cblt-os-flags | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

semaphore-start | Initial count for the semaphore.
open-flags | Reserved. Should be set to zero.

On Exit:

semaphore-handle | Semaphore handle.
return-code | A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

None.

Parent topic: Synchronization routines - semaphores
Parent topic: Alphabetical List of Library Routines


CBL_SEMAPHORE_RELEASE

Releases one of the resources represented by the semaphore by incrementing the associated count.

Syntax:

call "CBL_SEMAPHORE_RELEASE" using by value semaphore-handle

Parameters:

 | Using call prototype (see Key) | Picture
semaphore-handle | cblt-pointer | usage pointer.

On Entry:

semaphore-handle Semaphore handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

If the count was zero before the increment, and some other threads are blocked in a CBL_SEMAPHORE_ACQUIRE call waiting for the count to become non-zero, then one of those threads is released, so it can decrement the count and return from CBL_SEMAPHORE_ACQUIRE.

Behavior is undefined if semaphore-handle is invalid.

Parent topic: Synchronization routines - semaphores
Parent topic: Alphabetical List of Library Routines


Synchronization routines - mutexes

Mutexes, semaphores, monitors and events can be used to synchronize threads. Synchronization objects are named, and the name is visible throughout the system, not just in the creating process.

  • Mutexes - General Notes
  • CBL_MUTEX_ACQUIRE
    Acquires a mutex for the specified thread.
  • CBL_MUTEX_CLOSE
    Closes the specified mutex.
  • CBL_MUTEX_OPEN_INTRA
    Create an intra-process mutex.
  • CBL_MUTEX_RELEASE
    Releases the specified mutex.
Parent topic: Synchronization routines


Mutexes - General Notes

Mutexes can be used for thread synchronization within the same process.

Mutexes are implemented where possible by calling the operating system directly, thus they give lower level functionality than monitors.

A mutex is a synchronization object which at any one time zero or one thread "owns". If a thread has acquired a mutex, and another thread requests it, depending on a "wait" option, the second thread either returns without acquiring the mutex, or blocks until the first thread has released it. If several threads are blocked waiting for the mutex, only one of them is unblocked; all the others continue to wait.

Parent topic: Synchronization routines - mutexes


CBL_MUTEX_ACQUIRE

Acquires a mutex for the specified thread.

Syntax:

call "CBL_MUTEX_ACQUIRE" using by value mutex-handle
                               by value nowait-flag

Parameters:

 | Using call prototype (see Key) | Picture
mutex-handle | cblt-pointer. | usage pointer.
nowait-flag | cblt-os-flags. | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

mutex-handle
Mutex handle
nowait-flag
A number that determines what happens if the mutex cannot be acquired immediately:
Bit 0
0 | The routine blocks the thread/process until the mutex can be acquired .
1 | The routine returns immediately with a non-zero return value.
Remaining bits
Reserved. Must be set to zero.

On Exit:

return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

Behavior is undefined if mutex-handle is invalid.

Parent topic: Synchronization routines - mutexes
Parent topic: Alphabetical List of Library Routines


CBL_MUTEX_CLOSE

Closes the specified mutex.

Syntax:

call "CBL_MUTEX_CLOSE" using by value mutex-handle

Parameters:

 | Using call prototype (see Key) | Picture
mutex-handle | cblt-pointer. | usage pointer.

On Entry:

mutex-handle Mutex handle

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

The mutex is destroyed.

Behavior is undefined if mutex-handle is invalid.

Parent topic: Synchronization routines - mutexes
Parent topic: Alphabetical List of Library Routines


CBL_MUTEX_OPEN_INTRA

Create an intra-process mutex.

Syntax:

call "CBL_MUTEX_OPEN_INTRA" using by reference mutex-handle
                            by value           open-flags

Parameters:

 | Using call prototype (see Key) | Picture
mutex-handle | cblt-pointer. | usage pointer.
open-flags | cblt-os-flags. | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)

On Entry:

open-flags
A value that determines how the mutex is to be opened:
Bit 0
0 | Mutex is not acquired by the current thread at creation.
1 | Mutex is acquired by the current thread at creation.
Remaining bits
Reserved. Set to zero

On Exit:

mutex-handle
Mutex handle
return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

mutex-handle is local to the process.

Parent topic: Synchronization routines - mutexes
Parent topic: Alphabetical List of Library Routines


CBL_MUTEX_RELEASE

Releases the specified mutex.

Syntax:

call "CBL_MUTEX_RELEASE" using by value mutex-handle

Parameters:

 | Using call prototype (see Key) | Picture
mutex-handle | cblt-pointer. | usage pointer.

On Entry:

mutex-handle Mutex handle

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines.

Comments:

If one or more threads are blocked in a CBL_MUTEX_ACQUIRE routine waiting for this mutex, one of them unblocks and returns from its call with the mutex acquired.

Behavior is undefined if either the current thread has not acquired the mutex or mutex-handle is invalid.

Parent topic: Synchronization routines - mutexes
Parent topic: Alphabetical List of Library Routines


Synchronization routines - events

  • Events - General Notes
  • CBL_EVENT_CLEAR
    Clears the specified event.
  • CBL_EVENT_CLOSE
    Closes the supplied event handle.
  • CBL_EVENT_OPEN_INTRA
    Creates an intra-process event.
  • CBL_EVENT_POST
    Posts the specified event.
  • CBL_EVENT_WAIT
    Waits for the event to be posted.
Parent topic: Synchronization routines


Events - General Notes

Events can be used for thread synchronization within the same process.

Events are implemented where possible by calling the operating system directly, thus they give lower level functionality than monitors.

An event is a synchronization object which can be posted and cleared by different threads. A thread may wait for an event to become posted; if there are several threads waiting when the event becomes posted, all the threads are then allowed to continue.

Parent topic: Synchronization routines - events


CBL_EVENT_CLEAR

Clears the specified event.

Syntax:

call "CBL_EVENT_CLEAR" using by value event-handle

Parameters:

 | Using call prototype (see Key) | Picture
event-handle | cblt-pointer | usage pointer.

On Entry:

event-handle The event handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

The routine has no effect if the event was already clear.

Behavior is undefined if event-handle is invalid.

Parent topic: Synchronization routines - events
Parent topic: Alphabetical List of Library Routines


CBL_EVENT_CLOSE

Closes the supplied event handle.

Syntax:

call "CBL_EVENT_CLOSE" using by value event-handle

Parameters:

 | Using call prototype (see Key) | Picture
event-handle | cblt-pointer | usage pointer.

On Entry:

event-handle The event handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

The event is destroyed.

Behavior is undefined if event-handle is invalid.

Parent topic: Synchronization routines - events
Parent topic: Alphabetical List of Library Routines


CBL_EVENT_OPEN_INTRA

Creates an intra-process event.

Syntax:

call "CBL_EVENT_OPEN_INTRA" using by reference event-handle
                            by value           open-flags

Parameters:

event-handle
Call prototype (see Key): cblt-pointer
Picture: usage pointer.
open-flags
Call prototype (see Key): cblt-os-flags
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only).

On Entry:

open-flags
A number specifying how the event is to be created:
Bit 0
0 | The event is created not posted.
1 | The event is created posted.
Remaining bits
Reserved. Should be set to zero.

On Exit:

event-handle
The event handle
return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

event-handle is local to the process.

Parent topic: Synchronization routines - events
Parent topic: Alphabetical List of Library Routines


CBL_EVENT_POST

Posts the specified event.

Syntax:

call "CBL_EVENT_POST" using by value event-handle

Parameters:

 | Using call prototype (see Key) | Picture
event-handle | cblt-pointer | usage pointer.

On Entry:

event-handle The event handle.

On Exit:

return-code A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

If any threads are waiting for the event to be posted in the CBL_EVENT_WAIT call, they are all allowed to run and hence return from their CBL_EVENT_WAIT calls. The call has no effect if the event was already posted. The call returns zero for success.

Behavior is undefined if event-handle is invalid.

Parent topic: Synchronization routines - events
Parent topic: Alphabetical List of Library Routines


CBL_EVENT_WAIT

Waits for the event to be posted.

Syntax:

call "CBL_EVENT_WAIT" using by value event-handle
                      by value       nowait-flag

Parameters:

event-handle
Call prototype (see Key): cblt-pointer
Picture: usage pointer.
nowait-flag
Call prototype (see Key): cblt-os-flags
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only).

On Entry:

event-handle
The event handle.
nowait-flag
A value that specifies the action to take if the event has not been posted:
Bit 0
0 | The thread blocks until the event is posted, and then returns.
1 | The call returns immediately with an error value
Remaining bits
Reserved. Must be set to zero.

On Exit:

return-code
A value of 0 indicates that the call was successful. Any other value indicates an error. See RETURN-CODE Values For Synchronization Routines

Comments:

If the event is already posted, the call returns immediately.

Behavior is undefined if event-handle is invalid.

Parent topic: Synchronization routines - events
Parent topic: Alphabetical List of Library Routines


RETURN-CODE Values For Synchronization Routines

The following values are provided as RETURN-CODE values from the synchronization routines:

0 | No error was encountered.
1000 | Memory allocation error.
1001 | The thread is invalid. The handle is not a valid handle for the synchronization object, and no operations are valid on it. It is possible that the handle specified was once valid but it has been closed and memory reused.
1002 | The thread has been closed. No operations are valid on this handle. The handle was once valid but has since been closed.
1003 | The thread is detached. CBL_THREAD_DETACH cannot detach the thread since it has already been detached. CBL_THREAD_WAIT cannot wait on the thread since it has already been detached.
1004 | Too many threads. CBL_THREAD_CREATE cannot create another thread since too many threads exist in the system already.
1005 | The stack size is invalid. CBL_THREAD_CREATE cannot create this thread as the operating system will not allow the provided stack size to be used.
1006 | Invalid operation. CBL_THREAD_CREATE cannot create a thread while the system is deinitializing. or: An invalid thread-control routine was attempted on a thread that was not created with CBL_THREAD_CREATE. or: CBL_THREAD_PROG_LOCK was not called directly or indirectly from a COBOL program.
1007 | A system error was encountered. The last operation caused a system error in low level object manipulation.
1008 | Threading not supported in this run-time system. A threaded application attempted to use a multi-threading routine while running with a non-threaded run-time system.
1009 | Invalid parameter passed into a multi-threading library routine. A parameter has been detected that is not within the valid range, or that is inconsistent with the library routine.
1010 | No resources available. A semaphore or mutex cannot be acquired because its count is zero and the user requested no automatic wait. or: An event is not posted and the user has no wait on the CBL_EVENT_WAIT call.
1011 | Program or entry-point name not found. The program or entry-point name specified to CBL_THREAD_CREATE was not found, or there was an error loading it.
Parent topic: Synchronization routines


Routines for Handling Thread-specific Data

The easiest way to handle thread-local data is to use a Thread-Local-Storage Section in your program. It is assumed that you understand the Thread-Local Storage facility.

Library routines are also provided to give you control over the way in which thread-specific data is handled. These routines enable your program to:

  • Allocate thread-local data from the dynamic heap
  • Access thread-local data from an initialized thread-storage handle

Allocating Thread-local Data From the Dynamic Heap

You can allocate thread-local data from the dynamic heap via CBL_ALLOC_MEM or the modular CBL_ALLOC_THREAD_MEM. The advantage of this form of allocation is that multiple memory blocks of varying sizes can be allocated and associated with a thread and/or program.

CBL_ALLOC_MEM can associate allocated heap data with a thread and the calling program. depending on the setting of the input parameters. CBL_ALLOC_THREAD_MEM always associates any allocated heap data with a thread, and optionally the calling program.

Memory allocated by these routines is automatically cleaned-up when the thread terminates.

Note that any pointer to thread-local storage returned by these calls should be saved in a Thread-Local Storage defined pointer, so that its value can be retrieved on subsequent calls to the program that allocated the thread-local storage area. Saving the returned pointer in a Working-Storage defined pointer and subsequently using that value causes the thread local heap area to be shared among threads and is bad programming practice.

Accessing Thread-local Data From an Initialized Thread-storage Handle

Routines are supplied that enable a program to access thread-local data from an initialized thread-storage handle. This handle is returned by the CBL_TSTORE_CREATE routine. Memory is returned by CBL_TSTORE_GET using a specific handle. The memory is of a fixed size and is the same across all invocations of CBL_TSTORE_GET within that thread. These routines provide, in essence, a distinct thread-local-storage area for each initialized handle.

  • CBL_TSTORE_CLOSE
    Closes a handle returned by CBL_TSTORE_CREATE.
  • CBL_TSTORE_CREATE
    Creates a handle for and specifies the size of a thread-storage area. These values can be used in subsequent calls to CBL_TSTORE_GET. The new thread-storage area is initialized to zeroes.
  • CBL_TSTORE_GET
    Gets a pointer to the thread-specific memory specified by CBL_TSTORE_CREATE.
  • Thread-specific Data Handling Routines - Example
  • RETURN-CODE Values For Thread-specific Data Handling Routines
Parent topic: Multi-threading Routines
Related information
Alphabetical List of Library Routines
Multi-threading Routines
Thread-control Routines
RETURN-CODE Values For Thread-control Routines
Synchronization Routines
Routines for Handling Thread-specific Data


CBL_TSTORE_CLOSE

Closes a handle returned by CBL_TSTORE_CREATE.

Syntax:

call "CBL_TSTORE_CLOSE" using by value tstore-handle

Parameters:

 | Using call prototype (see Key) | Picture
tstore-handle | cblt-pointer | usage pointer.

On Entry:

tstore-handle The thread-storage handle

Comments:

This routine closes a handle to a thread-storage area that was returned by CBL_TSTORE_CREATE, freeing all allocated memory for all threads.

You should ensure that this routine is called in single-threaded mode by forcing single-threaded behavior within a monitor lock, or by calling it only when initializing the application in single-threaded mode.

Parent topic: Routines for Handling Thread-specific Data
Parent topic: Alphabetical List of Library Routines


CBL_TSTORE_CREATE

Creates a handle for and specifies the size of a thread-storage area. These values can be used in subsequent calls to CBL_TSTORE_GET. The new thread-storage area is initialized to zeroes.

Syntax:

call "CBL_TSTORE_CREATE" using    tstore-handle
                         by value tstore-size
                         by value tstore-flags

Parameters:

 | Using call prototype (see Key) | Picture
tstore-handle | cblt-pointer | usage pointer.
tstore-size | cblt-os-size | picture x(4) comp-5 or pic x(8) comp-5 (64-bit native only)
tstore-flags | cblt-os-flags | picture x(4) comp-5 or pic x(8) comp-5 (64-bit native only)

On Entry:

tstore-size
Size of thread-storage area that will be returned to every thread that calls CBL_TSTORE_GET using the returned handle.
tstore-flags
The type of thread-storage area required:
Bit | Meaning
0 | Reserved, should be set to 0
1 | Reserved, should be set to 0
2 0: Allocate a thread-storage handle. The handle is not independent of the calling program, and is deallocated automatically when the calling program is canceled.

1: Allocate a thread-storage handle that is independent from any calling program. If this bit is set the thread-storage handle will be closed at the end of the run-unit

Remaining bits | Reserved, should be set to 0

On Exit:

tstore-handle
The thread-storage handle.
return-code
Indicates success or otherwise of the routine:
0 | Successful allocation
1000 | Unable to allocate thread storage handle

Comments:

CBL_TSTORE_CREATE specifies the size of the memory block that will be returned by any subsequent calls to CBL_TSTORE_GET and, optionally, associates that handle with the calling program so that when the calling program is canceled the returned handle is automatically closed. In any event the returned handle will be closed at termination of the run-unit or a call to CBL_TSTORE_CLOSE, whichever comes first.

If this thread-storage handle is not associated with a program, then the thread-storage handle is closed at the end of the run-unit.

You should ensure that this routine is called in single-threaded mode by forcing single-threaded behavior within a monitor lock, or by calling it only when initializing the application in single-threaded mode.

Parent topic: Routines for Handling Thread-specific Data
Parent topic: Alphabetical List of Library Routines


CBL_TSTORE_GET

Gets a pointer to the thread-specific memory specified by CBL_TSTORE_CREATE.

Syntax:

call "CBL_TSTORE_GET" using by value tstore-handle
                                     tstore-ptr

Parameters:

 | Using call prototype (see Key) | Picture
tstore-handle | cblt-pointer | usage pointer
tstore-ptr | cblt-pointer | usage pointer

On Entry:

tstore-handle
A non-null handle. This is the handle returned by CBL_TSTORE_CREATE.

On Exit:

tstore-ptr
A pointer to a memory block of the size specified by CBL_TSTORE_CREATE. This pointer is unique to this thread.
return-code
Indicates success or otherwise of the routine:
0 | Success
1000 | Could not get the memory block requested
1001 | Bad handle
1002 | Closed handle

Comments:

Returns a pointer to a block of memory of the size specified by CBL_TSTORE_CREATE. This pointer is unique for each calling thread. A block of memory containing all zeroes indicates that CBL_TSTORE_GET has been run for the first time.

A value is returned in RETURN-CODE, indicating success or otherwise of the routine:

Parent topic: Routines for Handling Thread-specific Data
Parent topic: Alphabetical List of Library Routines


Thread-specific Data Handling Routines - Example

This program initializes a thread-storage handle and then starts off several threads which each use the handle to access thread local data. Consistency checks are made within each entry to ts-test, on termination of each thread and on termination of the run-unit. This program takes advantage of the Thread-Local-Storage Section, external data items, exit procedures and basic synchronization to achieve this function.

Source Code

       $set reentrant sourceformat(free)
        copy "cblproto.cpy".

        ************************************************************
        * tstore-main                                              *
        * Main routine to initialize tables and kick off threads   *
        *                                                          *
        ************************************************************

        program-id. 'tstore'.
        environment division.
        special-names. command-line is cmdln.

        working-storage section.
        78 THREAD-COUNT VALUE 5.

        01 tstore-handle    cblt-pointer is external.
        01 foo-item         pic 9(9) value 0.
        01 thredid          pic xxxx comp-5.
        01 thread-handle    cblt-pointer occurs THREAD-COUNT.
        01 thread-entry     cblt-ppointer.
        01 thread-return    cblt-ppointer.

        thread-local-storage section.
        01 filler.
          05 tl-count pic x value 'x'.
          05 tl-ptr   cblt-pointer.

        linkage section.
        01 tstore-item.
           05 filler       pic x.
              88 TSTORE-INIT VALUE 'Y'.
           05 tstore-count pic 999.

        procedure division.
       *>
       *> Initialize thread table and set up for clean exit
       *>
        call "CBL_TSTORE_CREATE" using         tstore-handle
                            by value length tstore-item
                            by value        h"04"

        call 'ts-get'           using tl-ptr
        set address of tstore-item to tl-ptr
        move THREAD-COUNT   to tstore-count
        set thread-entry    to entry "ts-entry"
        move 1    to thredid
        perform THREAD-COUNT times
         call "CBL_THREAD_CREATE_P" using by value thread-entry
           by reference thredid
           by value     length of thredid
           by value     0
           by value     0
           by value     0
           by reference thread-handle(thredid)
         if return-code not = 0
             call 'CBL_THREAD_PROG_LOCK'
             display "FAIL: Cannot create thread"
             call 'CBL_THREAD_PROG_UNLOCK'
             stop run
         end-if
         add 1 to thredid
        end-perform

        move 1 to thredid

        perform THREAD-COUNT times
         call "CBL_THREAD_WAIT" using by value thread-handle(thredid)
                                      by reference thread-return

         add 1 to thredid
        end-perform

        call "CBL_TSTORE_CLOSE" using by value tstore-handle

        stop run.

        end program 'tstore'.

        ************************************************************
        *                                                          *
        * ts-entry                                                 *
        * Root entry point for threads created by application      *
        *                                                          *
        ************************************************************
        program-id. 'ts-entry'.
        working-storage section.
         78 REP-COUNT VALUE 5.

        01 tl-ptr   cblt-pointer.

        linkage section.
        01 lnk-thredid.
           05 lnk-thread-id pic xxxx comp-5.

        01 tstore-item.
           05 filler pic x.
             88 TSTORE-INIT VALUE 'Y'.
           05 tstore-count pic 999.

        procedure division using lnk-thredid.
        thread-section.
        perform REP-COUNT times
         call 'ts-test' using lnk-thread-id
        end-perform

        call 'ts-get'  using tl-ptr
        set address of tstore-item to tl-ptr

        call "CBL_THREAD_PROG_LOCK"
        if tstore-count not = REP-COUNT
         display "FAIL: Thread storage rep-count BAD"
        else
         display "PASS: Thread storage rep-count good"
        end-if
        call "CBL_THREAD_PROG_UNLOCK"
        exit program.
        end program 'ts-entry'.

        ************************************************************
        *                                                          *
        * ts-test                                                  *
        * Routine to get a thread storage area and increment its   *
        * count                                                    *
        *                                                          *
        ************************************************************
        program-id. 'ts-test'.

        working-storage section.
        01 global-count pic 99999 value 0.

        thread-local-storage section.
        01 tl-ptr     cblt-pointer.
        01 tl-count   pic 999 value 0.

        linkage section.
        01 lnk-thredid  pic xxxx comp-5.

        01 tstore-item.
           05 filler   pic x.
              88 TSTORE-INIT VALUE 'Y'.
           05 tstore-count  pic 999.
        procedure division using lnk-thredid.
        thread-section.
        call 'ts-get'   using tl-ptr
        set address of tstore-item    to tl-ptr
        add 1       to tstore-count
        add 1       to tl-count

       if tstore-count not = tl-count
         display "ERROR: inconsistent thread local data"
         stop run
       end-if

       call "CBL_THREAD_PROG_LOCK"
       add 1 to global-count
       display "MESSAGE: thread-test has been called " tstore-count
         " by thread " lnk-thredid
       display "MESSAGE: thread-test has been called " global-count " globally "
       call "CBL_THREAD_PROG_UNLOCK"

       exit program.

       end program 'ts-test'.

       ************************************************************
       * ts-get                                                   *
       * Common routine to get and initialize the thread storage  *
       * area allocated by CBL_TSTORE_GET                         *
       *                                                          *
       ************************************************************
       program-id. 'ts-get'.
       data division.
       working-storage section.
       01 tstore-handle cblt-pointer external.

       thread-local-storage section.
       01 tl-ptr    cblt-pointer.

       linkage section.
       01 tstore-item.
          05 filler       pic x.
             88 TSTORE-INIT VALUE 'Y'.
          05 tstore-count pic 999.
       01 lnk-ptr usage pointer.

       procedure division using lnk-ptr.
       call "CBL_TSTORE_GET" using by value     tstore-handle
                                 by reference tl-ptr
       if tl-ptr = NULL
         display "FAIL: Error in getting thread " &
                 "storage data"
         stop run
       end-if
       set address of tstore-item to tl-ptr
       if not TSTORE-INIT
         move 0 to tstore-count
       end-if
       set tstore-init to true
       set lnk-ptr to tl-ptr

       exit program.

       end program 'ts-get'.
Parent topic: Routines for Handling Thread-specific Data


RETURN-CODE Values For Thread-specific Data Handling Routines

The following values are provided as RETURN-CODE values from the thread-specific data handling routines:

0 | No error was encountered.
1000 | Memory allocation error.
1001 | Thread-storage handle is invalid. No operations are valid on this thread-storage handle. It is possible that the handle specified was once valid but it has been closed and the memory reused.
1002 | Thread-storage handle is invalid. The thread storage handle has previously been closed and is no longer valid.
1009 | Invalid parameter passed into a thread-specific data-handling library routine. A parameter has been detected as being out of valid ranges or inconsistent with the library routine.
1010 | Resource busy. A synchronization object was still locked upon thread termination and when the thread was created the user requested an error to be reported if this condition occurred.
Parent topic: Routines for Handling Thread-specific Data


National Locale Support (NLS) Library Routines

Restriction: These routines are supported in native COBOL only.
  • CBL_NLS_CLOSE_MSG_FILE
    Closes a National Locale Support (NLS) message file.
  • CBL_NLS_COMPARE
    Compares two strings.
  • CBL_NLS_INFO
    Gets/sets national language information.
  • CBL_NLS_OPEN_MSG_FILE
    Open a National Locale Support (NLS) message file.
  • CBL_NLS_READ_MSG
    Reads a message from a National Locale Support (NLS) message file.
Parent topic: Library Routines


CBL_NLS_CLOSE_MSG_FILE

Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_CLOSE_MSG_FILE" using    msg-file-handle
                              returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
msg-file-handle | cblt-x4-compx | pic x(4).
status-code | See Library Routines - Key

On Entry:

msg-file-handle
The identifying handle returned when the message file was opened.

On Exit:

status-code
0 | Success
404 | Invalid msg-file-handle

Comments:

This routine enables you to close a National Locale Support (NLS) message file that had been previously opened using the CBL_NLS_OPEN_MSG_FILE routine.

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: National Locale Support (NLS) Library Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
NLS
NLS Message-file Handling Routines


CBL_NLS_COMPARE

Compares two strings.
Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_COMPARE" using        string1
                                    string2
                       by value     string1-length
                       by value     string2-length
                       by reference result-byte
                       returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture
string1 | pic x(n). | pic x(n).
string2 | pic x(n). | pic x(n).
string1-length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
string2-length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
result-byte | cblt-sx1-comp5 | pic s9(2) comp-5.
status-code | See Library Routines - Key |

On Entry:

string1
The first string.
string2
The second string.
string1-length
Length of the first string.
string2-length
Length of the second string.

On Exit:

result-byte
Result of the comparison:
0 | The two strings are the same
-1 | string1 < string2
+1 | string1 > string2
status-code
Indicates whether the routine was successful:
0 | Success
105 | Memory allocation error
Parent topic: Using NLS Library Routines in Your Programs
Parent topic: National Locale Support (NLS) Library Routines
Parent topic: Alphabetical List of Library Routines


CBL_NLS_INFO

Gets/sets national language information.
Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_INFO" using     function-code
                              info-category
                              info-buffer
                    returning status-code

Parameters:

function-code
Call prototype (see Key): cblt-x1-compx.
Picture: pic x comp-x.
Contains one of the following:
1 | Get national language information
2 | Set national language information
info-category
Call prototype (see Key): cblt-x1-compx.
Picture: pic x comp-x.
info-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
status-code
See Library Routines - Key

On Entry:

With function-code = 1
info-category
Category of information to get from the NLS module:
1 | Currency symbol
2 | Thousands separator
3 | Decimal separator
With function-code = 2
info-category
Category of information to set:
1 | Currency symbol
2 | Thousands separator
3 | Decimal separator
info-buffer
Information to set (null-terminated). The thousands and decimal separators are each one character long. The currency symbol is up to 10 characters long.

On Exit:

With function-code = 1
info-category
Category of information to get from the NLS module:
1 | Currency symbol
2 | Thousands separator
3 | Decimal separator
status code
Indicates whether the routine was successful:
0 | Success
164 | Invalid parameter specified
200 | Internal error
With function-code = 2
info-category
Category of information to set:
1 | Currency symbol
2 | Thousands separator
3 | Decimal separator
info-buffer
Information to set (null-terminated). The thousands and decimal separators are each one character long. The currency symbol is up to 10 characters long.
status code
Indicates whether the routine was successful:
0 | Success
164 | Invalid parameter specified
200 | Internal error

Comments:

This routine enables you to both get and set information about the national language. With function-code = 2 (set information) the change made applies only to the program that made the call.

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: National Locale Support (NLS) Library Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
NLS
NLS Message-file Handling Routines


CBL_NLS_OPEN_MSG_FILE

Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_OPEN_MSG_FILE" using     msg-filename
                                       msg-filename-ln
                                       msg-file-handle
                             returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
msg-filename | pic x(n). | pic x(n).
msg-filename-ln | cblt-x1-compx. | pic x comp-x.
msg-file-handle | cblt-x4-compx. | pic x(4).
status-code | See Library Routines - Key.

On Entry:

msg-filename
The name of the message file to be opened.
msg-filename-ln
The length of msg-filename.

On Exit:

msg-file-handle
The identifying handle.
status-code
Indicates whether the routine was successful:
0 | Success
403 | Resulting message too long
405 | Illegal or empty supplied file name
If status-code contains a value other than these, it is the number of a run-time error message.

Comments:

This routine opens an NLS message catalog returning an identifying handle that you can use with the CBL_NLS_READ_MSG and CBL_NLS_CLOSE_MSG_FILE routines.

Message catalogs are searched for in the directories specified in the $NLSPATH environment variable. If $NLSPATH contains the %L element, the user can choose the language in which they want messages by setting the %LC_MESSAGES or $LANG environment variables at run-time. You create message catalogs using the gencat command.

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: National Locale Support (NLS) Library Routines
Parent topic: Alphabetical List of Library Routines


CBL_NLS_READ_MSG

Restriction: National Locale Support is only supported for native COBOL code.

Syntax:

call "CBL_NLS_READ_MSG" using     msg-file-handle
                                  full-msg-number
                                  msg-ins-struct
                                  msg-buffer
                        returning status-code

Parameters

msg-file-handle
Call prototype (see Key): cblt-x4-compx .
Picture: pic x(4).
full-msg-number
Group predefined as cblt-nls-msg-params containing:
01 cblt-nls-msg-params          typedef.
  03 cblte-nmpb-set-number      cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-number          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-max-buffer-len  cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-nmpb-actual-msg-len  cblt-x2-compx. 	*> pic x(n) comp-x.
  03 cblte-nmpb-flags           cblt-x2-compx. 	*> pic x(2) comp-x.
msg-ins-struct
Group predefined as cblt-nls-msg-ins-struct containing:
01 cblt-nls-msg-ins-struct      typedef.
  03 cblte-nmis-ins-count       cblt-x2-compx.  *> pic x(2) comp-x.
  03 cblte-nmis-ins-pointer     cblt-pointer.   *> usage pointer.
                                                *> Occurs depending on ins-count.
msg-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
status-code
See Library Routines - Key.

On Entry:

msg-file-handle
The identifying handle of the message file to fetch the message from.
cblte-nmnp-set-number
The set in the message file to fetch the message from.
cblte-nmnp-number
The message number in the message set to fetch the message from.
cblte-nmis-ins-count
The number of portions of text to insert in the message.
cblte-nmis-ins-pointer
A pointer to a null-terminated portion of text to insert in the message.
cblte-nmb-buff-len
The length of msg-buff-text.

On Exit:

cblte-nmb-buff-text
The returned text (null-terminated).
status-code
Indicates whether the routine was successful:
0 | Success
40 | NLS module not initialized
401 | Message set not found
402 | Message not found in set
403 | Message too long for message text buffer
404 | Invalid msg-file-handle
If status-code contains a value other than these, it is the number of a run-time error message.

Comments:

In each message catalog, messages can be divided into sets. Each message in a set has an identifying message number. Message catalogs are explained in more detail in the section Writing NLS Message Files in the chapter Internationalization Support in the book Program Development.

This routine also enables you to insert portions of text in a message fetched from the message catalog, replacing any %s formatting sequences in the original message. There must not be more %s formatting sequences than cblte-nmis-ins-count.

The inserted portions of text can be inserted in the order appropriate to the rules of the grammar for the national language. This is achieved using the %n$s formatting syntax, where n is the nth cblte-nmis-ins-pointer. The value of n must not exceed cblte-nmis-ins-count.

Parent topic: Using NLS Library Routines in Your Programs
Parent topic: National Locale Support (NLS) Library Routines
Parent topic: Alphabetical List of Library Routines


Operating System Information Routines

  • CBL_GET_OS_INFO
    Returns information about the operating system environment.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_GET_OS_INFO

Returns information about the operating system environment.

Syntax:

call "CBL_GET_OS_INFO" using     parameter-block
                       returning status-code

Parameters

parameter-block
Group predefined as cblt-os-info-params containing
01 cblt-os-info-params               typedef.
  03 cblte-osi-length                cblt-x2-compx.	 *> pic x(2) comp-x value 28.
  03 cblte-osi-os-type               cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-osi-os-version            cblt-x4-compx. 	*> pic x(4) comp-x.
  03 cblte-osi-dbcs-support          cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-osi-char-coding           cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-osi-country-id            cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-code-page             cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-process-type          cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-osi-rts-capabilities      cblt-x4-compx. 	*> pic x(4) comp-x.
  03 cblte-osi-product               cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-product-version       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-product-revision      cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-product-sp            cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-osi-fixpack               cblt-x2-compx. 	*> pic x(2) comp-x.
status-code
See Library Routines - Key.

On Entry:

cblte-osi-os-length
Length of the information expected to be returned.

On Exit:

cblte-osi-os-length
Length of the information returned; this can be less than or equal to the length on entry
cblte-osi-os-type
131 for Windows systems, 128 for COBOL systems on UNIX
cblte-osi-os-version
Use is specific to the operating system. Can include information such as chip type and the operating system version number. For Windows the third and fourth bytes contain the minor and major release operating system version numbers respectively.
cblte-osi-dbcs-support
DBCS support flag:
Bit 0
0 | if DBCS validation unsupported
1 | if DBCS validation supported
Bit 1
0 | if PIC N data-type unsupported
1 | if PIC N data-type supported
cblte-osi-char-coding
Character encoding:
0 | ASCII
1 | Shift-JIS
2 | EUC Japan
3 | BIG-5 (Traditional Chinese)
4 | 5550 (Traditional Chinese)
5 | GB (Simplified Chinese)
6 | KS-CODE (Korean)
7 | PC-CODE (Korean)
8 | EUC Taiwan
9 | Other EUC locales
cblte-osi-country-id

Reserved; set to zero.

cblte-osi-code-page

Reserved; set to zero.

cblte-osi-process-type

Reserved; undefined.

cblte-osi-rts-capabilities
Characteristics of run-time system. Set as follows:
Bit | Description
0

multi-threaded rts

1 | Mainframe offloading capabilities
2 | 64-bit capability; the run-time system supports the running of 64-bit applications
3 | Indicates whether the program is running under the control of Enterprise Server
4 | Indicates that the run-time system is running in Enterprise Server mode
5 | Indicates whether the program is running under the CLR (Common Language Runtime)
6 | Indicates whether the program is running under a JVM (Java Virtual Machine)
7 Indicates whether the program is running within a Docker container.
Restriction: This bit is not applicable to managed COBOL programs.
8 | Indicates whether this is a single bit-ism native platform
9-23 | Reserved for future use and will be set to 0 by this routine
24 | Indicates whether the program is running in Microsoft SQL Server (.NET only)
25 | Indicates whether the program is running in Microsoft Azure (.NET only)
26 | Indicates whether the program is running in an Enterprise Java Bean (JVM only)
27-31 | Reserved for future use and will be set to 0 by this routine
cblte-osi-product
Product identifier:
0 | Unknown (backward compatibility)
1 | Server Express
2 | Net Express
3 | Mainframe Express (up to V3.0)
4 | Mainframe Express (V3.01 or later)
5 | Visual COBOL
cblte-osi-product-version
Product version, for example, for the COBOL development system 4.0, this field would be set to 4
cblte-osi-product-revision
Product revision, for example, for the COBOL development system 4.5, this field would be set to 5
cblte-osi-product-sp
Product service pack level, for example, for Server Express 4.0 Service Pack 1, this field would be set to 1
cblte-osi-fixpack
On Windows this field indicates the RTS fixpack version, for example, for the COBOL development system 4.0 RTS09N40 FixPack, this field would be set to 9. On UNIX, where individual component fixpacks are not provided, this field indicates the product fixpack version.
Parent topic: Operating System Information Routines
Parent topic: Alphabetical List of Library Routines


Portability Routines

Restriction: This routine is supported for native COBOL only.

This routine is provided to help you make existing applications portable to other environments. It should not be used in new applications where alternative mechanisms are provided.

  • CBL_SCR_SET_PC_ATTRIBUTES
    Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_SCR_SET_PC_ATTRIBUTES

Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.
Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SCR_SET_PC_ATTRIBUTES" returning status-code

Parameters:

status-code See Library Routines - Key

On Entry:

None

On Exit:

status-code See Library Routines - Key
status-code The return status:
0
Successful.
1
Successful, but one or more colors not exact.
2
Failed.

Comments:

Using this routine is equivalent to setting the entire IBM-PC attribute table using the generic attribute routines. It is provided to enable you to apply generic attributes to existing programs, making their attribute handling portable. However, this routine is inefficient because it defines every possible attribute. For new applications use the generic attribute routines and define only the attributes you need.

Parent topic: Portability Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Display Attribute Routines
Portability Routines


Program Canceling Routines

  • CBL_CANCEL
    Cancels a COBOL program.
  • CBL_CANCEL_PROC
    Provides control over program cancels.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_CANCEL

Cancels a COBOL program.

Syntax:

call "CBL_CANCEL"  using by value     flags
                         by reference program-name
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5250 | pic x(4) comp-5
program-name | pic x(n) | pic x(n)
status-code | See Library Routines - Key |

On Entry:

flags
The type of cancel behavior required. You can set the following bits:
Bit pair 0/1 (value 1/2)
logical/physical flags
00 | Perform the default CANCEL behavior
01 | Physically cancel the program
10 | Logically cancel the program if possible, otherwise physically cancel it.
11 | Reserved. Must not be used.
Bit 2 (value 4)
Reserved. Must not be used.
Bit 3 (value 8)
Prevent .dll code and shared object code from being physically canceled as part of a logical cancel operation.
0 | Physically cancel .dll code and shared object code as part of a logical cancel operation
1 | Do not physically cancel .dll code and shared object code as part of a logical cancel operation
program-name
The space- or null-terminated name of the program you want to cancel. The name can contain spaces as long as it starts with a double quote character (").

On Exit:

None.

Comments:

This routine provides finer run-time control of program cancelation than the COBOL CANCEL statement. It always returns zero, whether or not it was successful.

Any imported .dll files are automatically removed from memory when the .dll file which imports them is cancelled.

Parent topic: Program Canceling Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
File and Filename Routines


CBL_CANCEL_PROC

Provides control over program cancels.

Syntax:

call "CBL_CANCEL_PROC" using by value function
                       by reference   parameter-block
                       by value       cblte-cppb-userdata-length
                       returning      status-code

Parameters

function
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
parameter-block
Group predefined as cblt-cancel-proc-params containing
01 cblt-cancel-proc-params      typedef.
    03 cblte-cppb-version       cblt-x4-comp5. *> pic x(4) comp-5 value 0.
    03 cblte-cppb-flags         cblt-x4-comp5. *> pic x(4) comp-5.
    03 cblte-cppb-callback      cblt-ppointer  *> usage procedure-pointer.
    03 cblte-cppb-handle        cblt-pointer   *> usage pointer.
    03 cblte-cppb-userdata      cblt-pointer   *> usage pointer.
    03 cblte-cppb-priority      cblt-x4-comp5. *> pic x(4) comp-5.
cblte-cppb-userdata-length
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

function
Can be set to one of the following:
0 | Installs a cancel-routine at the default priority of 64:
1 | Installs a cancel-routine at a specified priority. See the section Comments.
2 | Enables a program to change the priority of a previously installed cancel routine:
3 | Enables a cancel-registration to be de-installed without causing the cancel-routine to be called.
4 | Enables a cancel-registration to be de-installed after causing the cancel-routine to be called. Note that the cancel-routine can detect if it is being called because of a de-install rather than a real CANCEL.
All other values are reserved for future expansion.
cblte-cppb-version
The "version" number of the parameter block. The parameter block described here must have this field set to zero.
cblte-cppb-flags
None defined at present. Must be set to zero.
cblte-cppb-callback
If function is set to:
0, 1 | The cancel-routine to install.
2-4 | Ignored.
cblte-cppb-handle
If function is set to:
0, 1 | The program-handle of the program to which to attach the cancel-routine, or NULL. See the discussion on program-handles in the section Comments.
2 | The handle of the cancel-routine to modify registration.
3, 4 | The handle returned from when function was set to either 0 or 1. This is the handle of the cancel-routine to de-register.
user-data
If function is set to:
0, 1 | User-defined data area. See discussion on user-data areas in the section Comments.
2-4 | Ignored.
user-data-length
If function is set to:
0, 1 | The length of the cblte-cppb-userdata block, or zero. See discussion on user-data areas in the section Comments.
2-4 | Ignored.

On Exit:

cblte-cppb-version
Ignored.
flags
Ignored.
cblte-cppb-callback
Ignored.
cblte-cppb-handle
If function is set to:
0, 1 | The handle for the cancel-registration, or NULL.
2 | Ignored.
3, 4 | NULL.
cblte-cppb-userdata
Ignored.
cblte-cppb-priority
Ignored.
status-code
0000 | Success - The operation was performed as requested.
1000 | Memory allocation error processing request.
1001 | Bad handle passed to API (Registration-handle).
1007 | System error (that is, any error not listed here).
1009 | Bad parameter passed (in function, param, and so on).

Comments

This routine provides a mechanism by which a COBOL program can receive notification of an impending cancel of either itself, or another COBOL program.

Such notification enables a COBOL program to finalize its use of, and deallocate, any resources it has allocated during its existence that are not already handled automatically by the COBOL run-time system or the operating system. These resources are normally those provided by the operating system or run-time system, but could also be some resource provided by another module in the application itself.

The COBOL run-time system performs notifications by processing a list (the cancel-list) which it has associated with the program being canceled. Therefore, to enable a notification, the COBOL run-time system must be instructed to create an entry in the cancel-list. Managing entries in cancel-lists is the purpose of CBL_CANCEL_PROC.

To create an entry in the cancel-list, CBL_CANCEL_PROC needs to know three things:

  • The program which, when canceled, triggers the notification. This program is identified by a program-handle (set on entry by the parameter cblte-cppb-handle).
  • The cblte-cppb-callback to call. The cblte-cppb-callback is the entry point called when the program is canceled.
  • A cancel-priority. This is the priority for this notification.

This information is provided to the run-time system by setting the parameter function to 0 or 1. By doing this, you create an entry in the cancel-list associated with the program cblte-cppb-handle. The entry specifies that the cblte-cppb-callback should be called when notification is due. The position in the list is determined by the value of cancel-priority.

The entry in the cancel-list created can be referenced using the value returned by the registration call in the cblte-cppb-handle parameter on exit. This enables a program to modify the registration at a later time, using this routine with function set to 2, 3 or 4; for example, you can change the priority of the registration, or remove it from the list.

A program-handle is a unique value which the COBOL run-time system associates with a cancelable entity. Therefore, all entry-points in a COBOL program share the same program-handle, as cancelling any entry-point in a COBOL program cancels all entry points in that program.

There are two basic methods of using the CBL_CANCEL_PROC routine, and the amount of work a program needs to do in order to obtain the correct program-handle depends on which method is necessary.

Local registration

When a program wishes to receive a notification that it is to be canceled, it can make a local registration - usually in its "first time in" code. For this method of registration, the program need only pass NULL as a program-handle. The CBL_CANCEL_PROC routine then automatically locates the correct program-handle and creates an entry in the correct list.

Usually, the cblte-cppb-callback specified in a local registration is an entry-point in the registering program (though it doesn't have to be).

An example would be a program which allocated some resource directly from the operating system and which needed the opportunity to deallocate it before being canceled.

Service registrations

This is a slightly more complicated type of registration, and is used when a service program (that is, a program which manages a resource on behalf of other COBOL programs) needs to receive notification that one of its clients is being canceled. For this method of registration, the program-handle should be obtained using a call to the CBL_GET_PROGRAM_INFO routine. The parameters to CBL_PROGRAM_INFO depend on what functionality you require. The most usual usage would be to get the program-handle of the calling program using function 2 of the CBL_GET_PROGRAM_INFO routine.

Usually, the cblte-cppb-callback specified in a service registration is an entry-point in the service program (though it doesn't have to be).

An example would be a file-handler module which opens and manages files on behalf of several other COBOL programs; when a given program is canceled, all files opened on behalf of that program must be closed automatically according to the semantics of COBOL.

Notice that this example could also be handled by including a local registration in each program which opens a file, which simply closes its files. However, such an approach would be prone to error, does not conform to COBOL semantics, and is very untidy.

When using the CBL_CANCEL_PROC routine for a service program, it is important that when an applicable resource is relinquished by the client program, the notification for it is removed from the cancel-list of that client program. This should be done by setting function to 3 or 4. To make this efficient, the service program could store the program-handle, returned when function is set to 0 or 1, within the resource structure, so that it can be easily located to be passed back as the registration-handle when function is set to 3 or 4.

If the service program fails to de-register a registration using function 3 or 4, a spurious notification will occur when the client program is eventually canceled, leading to unpredictable results.

If the cancel routine cancels other programs, those programs should not themselves have a CBL_CANCEL_PROC installed.

In addition to the three mandatory pieces of information required by CBL_CANCEL_PROC (that is, program-handle, cblte-cppb-callback and cancel-priority; function set to 0 or 1) set using , it can accept an optional fourth, cblte-cppb-userdata.

User Data Areas

By using the cblte-cppb-userdata parameter, a program registering a cblte-cppb-callback can specify a parameter to be passed to the cblte-cppb-callback when it is notified that a program has been canceled. You can specify a different cblte-cppb-userdata parameter for each registration, or the same cblte-cppb-userdata field can be specified for multiple registrations. In addition, you can specify that the cblte-cppb-userdata parameter is copied (and the copy passed to the cblte-cppb-callback as a parameter), by specifying a non-zero cblte-cppb-userdata-length parameter.

This facility is extremely useful when used by a service program - the service program does not need to manage a list to associate a client program with a service "handle", but can receive the service "handle" directly as a parameter to the cblte-cppb-callback provided it passed the "handle" to the CBL_CANCEL_PROC registration process as a cblte-cppb-userdata parameter.

Specifying a non-zero cblte-cppb-userdata-length parameter

This should typically be used only for small cblte-cppb-userdata areas. If the cblte-cppb-userdata-length parameter is set to non-zero, the specified number of bytes are copied from the address in the cblte-cppb-userdata parameter, and that copy is retained in the list entry. When the program associated with the relevant program-handle is canceled, the cblte-cppb-callback receives the copy of the cblte-cppb-userdata area as a parameter. The copy is deleted automatically by the COBOL run-time system after the cblte-cppb-callback has returned.

It should be noted that the CBL_CANCEL_PROC routine knows nothing about the structure of the cblte-cppb-userdata area passed to it, and only copies a flat memory block. For instance, items of USAGE POINTER embedded within the block will be copied, but the memory to which they point will not.

Implementation of a CANCEL routine

This section describes how to implement a cancel routine suitable for installing with CBL_CANCEL_PROC.

 working-storage section.
 01 cancel-status   pic x(4) comp-5.

 linkage section.
 01 cancel-reason   pic x(4) comp-5.
 01 cancel-flags    pic x(4) comp-5.
 01 prog-id      usage pointer.
 01 cblte-cppb-userdata       usage pointer.

 procedure division.
 entry "user-cblte-cppb-callback" using by value cancel-reason
                             by value       cancel-flags
                             by value       prog-id
                             by value       cblte-cppb-userdata.
 cblte-cppb-callback section.
 cblte-cppb-callback-para.
*> This is where the code which handles the CANCEL-notification goes.
*> The cblte-cppb-userdata field specified in the registration is passed
*> to us here, along with the program-id of the program being canceled.
*> If this routine is handling registrations which specified a
*> cblte-cppb-userdata-field length of zero, then the memory pointed to
*> by cblte-cppb-userdata may also need to be freed before returning.

 exit program returning cancel-status.

The cancel-reason parameter describes the reason for the CANCEL. When set:

Bit 0 (value 1) | CANCEL is due to STOP RUN processing.
Bit 6 (value 64) | CANCEL is due to DEINSTALL (CBL_CANCEL_PROC called with function set to 4).

All other bits are reserved and should be ignored.

The cancel-flags parameter is currently reserved and should be ignored.

Parent topic: Program Canceling Routines
Parent topic: Alphabetical List of Library Routines


Program Information Routines

Restriction: This routine is supported for native COBOL only.

The program information routine enables you to get information about a program.

  • CBL_GET_PROGRAM_INFO
    Returns information for a named program, or a program in the current call stack.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_GET_PROGRAM_INFO

Returns information for a named program, or a program in the current call stack.
Restriction: Functions 8 and 10 of this routine (return number of arguments) are supported for native COBOL only.

Syntax:

call "CBL_GET_PROGRAM_INFO" using by value function
                            by reference   param-block
                            by reference   return-buf
                            by reference   return-buf-len
                            returning      status-code

Parameters

function
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
param-block
Group predefined as cblt-prog-info-params containing
 01 cblt-prog-info-params   typedef.
   03 cblte-gpi-size        cblt-x4-comp5.   *> pic x(4) comp-5.
   03 cblte-gpi-flags       cblt-x4-comp5.   *> pic x(4) comp-5.2.
   03 cblte-gpi-handle      cblt-pointer.    *> usage pointer.
   03 cblte-gpi-prog-id     cblt-pointer.    *> usage pointer.
   03 cblte-gpi-attrs       cblt-x4-comp5.   *> pic x(4) comp-5.
return-buf
Call prototype (see Key): cblt-prog-info-arg-info
Picture: pic x(n).
return-buf-len
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

function
Specifies the function to be performed:
0
Note: This function is supported for COBOL programs only.
Return status information for the current program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the current program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

1 Return status information for named program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the named program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

2
Note: This function is supported for COBOL programs only.
Return status information for the program that called the program currently associated with cblte-gpi-handle. This function requires that cblte-gpi-handle has been set up using functions 0 or 1. The program associated with cblte-gpi-handle is updated to the calling program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

3 | Close a previously created cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been created using function 0 or 1. A call with this function must be made when cblte-gpi-handle is finished with.
4 | Find the first entry point of the program currently associated with cblte-gpi-handle. cblte-gpi-handle must have been set up using function 0 or 1. Once a call with this function has been made, you can repeatedly use this routine with function set to 5 to retrieve all remaining entry points in the program. Once all of the required entry points have been returned, you can use this routine with function set to 6 to terminate the entry-point search.
5 | Find the next entry point of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been used to initiate the find first/next entry-point sequence.
6 | Terminate the entry-point search. It requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been called to initiate the find first/next entry-point sequence.
7 | Return the full program-name of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1.
8
Note: This function is supported for native COBOL programs only.
Return the number of arguments the program currently associated with cblte-gpi-handle was called with. This information can only be returned if the program is on the current call stack.
9 | Reserved.
10 | Return the path and program name, or the program name only for the program currently associated with cblte-gpi-handle. This function depends on whether bit 5 is set in cblte-gpi-flags.
cblte-gpi-size
The size of the parameter block including this field. This should be set to a value of 20 on 32-bit systems, or 28 on 64-bit systems.
cblte-gpi-flags
A 32-bit word indicating what information is to be returned:
Bit 0
Determines whether functions 0 and 1 return cblte-gpi-handle. For all other functions, this bit is ignored.
0 | Do not return cblte-gpi-handle (if function is set to 0 or 1)
1 | Return cblte-gpi-handle (if function is set to 0 or 1)
Bit 1
Determines whether functions 0 and 2 should return the program's basename in name-buf as part of the program status information.
0 | Do not return basename of program (if function is set to 0 or 2)
1 | Return basename of program in name-buf (if function is set to 0 or 2)
Bit 2
Determines whether basenames and full program names that are input or returned in name-buf should be in null-terminated or space- terminated format.
0 | All input and output names are space-terminated
1 | All input and output names are null-terminated.
Bit 3
Determines whether functions 0, 1 and 2 should return the program's attributes in cblte-gpi-attr.
0 | Do not return program attributes in cblte-gpi-attr.
1 | Return program attributes in cblte-gpi-attr.
Bit 4
Determines whether function 2 should return information for all programs.
0 | Do not return program information.
1 | Return program information.
Bit 5
Determines whether function 10 should return the full path to the loaded module associated with cblte-gpi-handle.
0 | Return full path.
1 | Return program name only.
Bits 6-31
Reserved for future use - must be set to 0.
cblte-gpi-handle
A handle created by function 0 or 1.
(Must be specified for functions 2-10.)
return-buf
If function is set to:
0 The basename of the program for which information is required.
8 A group predefined as
01 RETURN-BUF.
     05 cblte-gpiai-size        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-argc        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-reserved1   pointer value null.
     05 cblte-gpiai-reserved2   pointer value null.

cblte-gpiai-size must be set to either 16 on 32-bit systems or 24 on 64-bit systems.

return-buf-len
The length of return-buf. If this is too small for the information being returned, the routine fails.

On Exit:

cblte-gpi-handle
The handle returned by functions 0 and 1, which must be used for all other functions.
cblte-gpi-prog-id
Unique identifier for the program currently associated with cblte-gpi-handle.
cblte-gpi-attr
Attributes of the program currently associated with cblte-gpi-handle.
Bit 0
0 | Program not compiled using AMODE"24" Compiler directive.
1 | Program compiled using the AMODE"24" Compiler directive .
Bit 1
0 | Program not compiled using AMODE"31" Compiler directive.
1 | Program compiled using the AMODE"31" Compiler directive .
Bit 2
0 | Program compiled using the CHARSET(ASCII) Compiler directive.
1 | Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3
Note: This bit is only applicable to COBOL programs.
0 | Program not compiled using the ANS85 Compiler directive.
1 | Program compiled using the ANS85 Compiler directive.
Bit 4
Note: This bit is only applicable to COBOL programs.
0 | Program not compiled using the VSC2 Compiler directive.
1 | Program compiled using the VSC2 Compiler directive (this Compiler directive is supported in native code only).
Bit 5
Note: This bit is only applicable to COBOL programs.
0 | Program not compiled using the OSVS Compiler directive.
1 | Program compiled using the OSVS Compiler directive (this Compiler directive is supported in native code only).
Bit 6
Note: This bit is only applicable to COBOL programs.
0 | Program not compiled using the DATA"24" Compiler directive.
1 | Program compiled using the DATA"24" Compiler directive.
Bit 7
Note: This bit is only applicable to COBOL programs.
0 | Program not compiled using the DATA-CONTEXT Compiler directive.
1 | Program compiled using the DATA-CONTEXT Compiler directive.
Bits 8-10
000 | COBOL or unknown language.
001 | PL/I.
010 to 111 | Reserved.
Bit 11
Note: This bit is only applicable to PL/I programs.
0 | Little-endian.
1 | Big-endian.
Bits 12-24
Reserved for future use - must be set to 0.
Bit 25
Note: This bit is only applicable to COBOL programs.
0 | Program is not an application controller.
1 | Program is an application controller.
Bit 26
Note: This bit is only applicable to COBOL programs.
0 | Program is not a system program.
1 | Program is a system program.
Bit 27
Note: This bit is only applicable to COBOL programs.
0 | Program is not a .390 assembler program.
1 | Program is a .390 assembler program.
Bit 28
Note: This bit is only applicable to COBOL programs.
0 | Program is not a member of a subsystem.
1 | Program is a member of a subsystem.
Bit 29
Note: This bit is only applicable to COBOL programs.
0 | Program exists in current call stack.
1 | Program does not exist in current call stack.
Bit 30
Note: This bit is only applicable to COBOL programs.
0 | Program is not canceled.
1 | Program is canceled.
Bit 31
0 | Program is COBOL.
1 | Program is non-COBOL.
return-buf
If function was set to:
0, 2 | The basename that was requested.
4, 5 | The entry point name that was requested.
7 | The full program name that was requested.
8 The call parameter information that was requested, where cblte-gpiai-argc contains the number of arguments the program was called with.

cblte-gpiai-reserved1 and cblte-gpiai-reserved2 remain set to NULL.

10 | The path and program name, or the program name only for the program currently associated with cblte-gpi-handle.
return-buf-len
Length of the name returned in name-buf, or required buffer length if the status-code is 1013.
status-code
Status of operation:
0 | Success.
500 | End of information (returned by function 2 when there is no caller of the currently associated program, or by function 5 when no more entry points exist).
1000 | Memory allocation error.
1001 | Invalid cblte-gpi-handle input.
1006 | Invalid operation on handle (returned by function 8 if the program associated with cblte-gpi-handle is not on the call stack).
1009 | Invalid parameter.
1011 | Program or entry name not found.
1013 | Buffer too small for information to be returned.
Parent topic: Program Information Routines
Parent topic: Alphabetical List of Library Routines


Run unit handling routines

The multiple run-unit routines enable you to make use of the Concurrency support provided with this system.

  • CBL_ABORT_RUN_UNIT
    Aborts the current run unit irrespective of the state of existing threads.
  • CBL_CULL_RUN_UNITS
    Clears any dead run units.
  • CBL_EXEC_RUN_UNIT
    Creates a synchronous or asynchronous run unit.
  • CBL_GET_SHMEM_PTR
    Reads a named value.
  • CBL_MANAGED_SESSION_GET_USERDATA
    Retrieves user data saved in the current RunUnit.
  • CBL_MANAGED_SESSION_SET_USERDATA
    Sets user data in the current RunUnit.
  • CBL_PUT_SHMEM_PTR
    Creates or updates a named value.
  • CBL_YIELD_RUN_UNIT
    Yields the remainder of a run-unit's time-slice.
Parent topic: Library Routines


CBL_ABORT_RUN_UNIT

Aborts the current run unit irrespective of the state of existing threads.

Syntax:

call 'CBL_ABORT_RUN_UNIT' using by value ret-value

Parameters:

 | Using call prototype (see Key) | Picture
ret-value | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

ret-value Return-code to be returned to the operating system by this run unit when it terminates.

Comments:

In a single-threaded application or run-time system this call is equivalent to the following syntax:

stop run returning ret-value

In a multi-threaded application STOP RUN waits for all existing threads to exit before terminating the run unit. CBL_ABORT_RUN_UNIT, however, does not wait for any existing thread to exit. It cancels all running threads and then terminates the run unit, returning control to the operating system.

Note: We recommend that you use this call only when a serious problem has been detected in the application. Calling this routine in a multi-threaded application could cause severe problems, as threads might be terminated in the middle of critical file operations.
Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_CULL_RUN_UNITS

Clears any dead run units.

Syntax:

call "CBL_CULL_RUN_UNITS"

Parameters:

None.

Comments:

This routine clears any run units that have been terminated by a STOP RUN or kill, but have not yet been removed.

Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_EXEC_RUN_UNIT

Creates a synchronous or asynchronous run unit.

Syntax:

call "CBL_EXEC_RUN_UNIT" using        command-line
                         by value     command-line-len
                         by reference run-unit-id
                         by value     stack-size
                         by value     flags
                         returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture
command-line | pic x(n). | pic x(n).
command-line-len | cblt-os-size. | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
run-unit-id | cblt-x8-comp5. | pic x(8) comp-5.
stack-size | cblt-os-size. | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
flags | cblt-os-flags. | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key

On Entry:

command-line
The command passed to the new run unit. This should be the program-name followed by any parameters.
line-length
The length of the command line.
stack-size
This parameter is ignored.
flags
A word indicating how the new run unit is created as follows:
Bit 0
0 | CBL_EXEC_RUN_UNIT returns to the caller immediately after creating the child process.
1 | CBL_EXEC_RUN_UNIT waits for the new run unit to complete before returning to the caller.
Bit 1
0 | The newly created run unit inherits all COBOL and run-time switches, environment variables and open libraries as they exist in the caller at the time of creation.
1 | The newly created run unit only inherits all environment variables as they exist in the caller at the time of creation.
Bit 2
0 The newly created run unit inherits the caller's console for screen I/O. Only one member of the coru should access this console at a time, otherwise unpredictable results may be encountered.
Note: A coru is a set of run units containing the initial run unit and all run units created from it.
1 The newly created run unit has a new console for terminal I/O allocated to it. This console is independent from the parent and can be used for screen I/O.
Remaining bits
Reserved - must be set to 0.

On Exit:

run-unit-id
If bit 0 of flags is not set, the OS process ID of the new run unit. If bit 0 of flags is set, this value is unchanged.
status-code
Status of operation:
0 | Success
157 | Out of memory
181 | Invalid parameter
255 | A run-time error occurred in the run unit, or the called program was not found
Other non-zero | Returned error code from the executed program

Comments:

The run unit that makes the call is known as the parent, while the run unit created is known as the child. When the child is created it inherits certain attributes from its parent. The attributes inherited by the child are copies of the attributes in the parent at the exact time of the call; any changes made to the attributes of the parent after the call are not reflected in the child's attributes. Similarly, any changes made to the child's attributes are not reflected in the parent's attributes.

Bit 1 flag controls which attributes of the parent are inherited by the child.

In the .NET environment, the run unit created by this command does not inherit any COBOL or run-time switches, or environment variables. CBL_EXEC_RUN_UNIT does not open libraries for the run unit it creates.

The set of run units containing the initial run unit and all run units created from it is known as the coru.

You should be aware of the following when using run units:

  • All COBOL programs in the child are in their initial state.
  • Data can be shared between run units by allocating it as shared memory using CBL_ALLOC_MEM or CBL_ALLOC_SHMEM, and then passing the address of this memory between the run units using CBL_PUT_SHMEM_PTR and CBL_GET_SHMEM_PTR
  • Open files and heaps are never inherited from the parent.
  • Screen I/O from one run unit can interfere with that from another run unit causing unexpected results. This is particularly a problem on UNIX but can also be an issue on Windows if the console is being shared by two or more processes. Avoid screen I/O operations from more than one concurrent run unit.

On platforms that enable you to create executable files that have either a 32-bit address space, or a 64-bit address space, the run units comprising a coru must use the appropriate address space.

If a 32-bit run-unit creates a 64-bit run unit, no attributes are shared between the run units; this is also true if a 64-bit run unit creates a 32-bit run unit. In either case, the mismatching child run unit is treated as an initial run unit of a new coru.

Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_SHMEM_PTR

Reads a named value.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call "CBL_GET_SHMEM_PTR" using     node-value
                                   node-name
                         returning status-code

Parameters

node-value
Call prototype (see Key): cblt-pointer
Picture: usage pointer.
node-name
Group predefined as cblt-node-name containing:
01  cblt-node-name          typedef.
  03 cblte-nname-name-len   cblt-x1-comp5. *> pic x comp-5 value n.
  03 cblte-nname-name-text  cblt-x1.       *> occurs depending cblte-nname-name-len.
                                           *> pic x(n) value "name".
status-code
See Library Routines - Key.

On Entry:

cblte-nname-name-len
The length of name.
cblte-nname-name-text
The value assigned to node-name.

On Exit:

node-value
The value of the named value.

Comments:

Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_MANAGED_SESSION_GET_USERDATA

Retrieves user data saved in the current RunUnit.

Syntax:

call "CBL_MANAGED_SESSION_GET_USERDATA" using by value user-dataname
                                        returning user-data.

Parameters:

user-dataname
picture clause: string
user-data
picture clause: object

On entry:

user-dataname
The name of the user data either set via the CBL_MANAGED_SESSION_SET_USERDATA library routine, or the RunUnit::SetUserData method.

On exit:

user-data
The user data saved in the current RunUnit.

Example:

The following example demonstrates the use of CBL_MANAGED_SESSION_GET_USERDATA and CBL_MANAGED_SESSION_SET_USERDATA from within a RunUnit.

The COBOL program that utilizes the library routines:

program-id. "GetUserDataExample".
procedure division.
*> retrieves a user data object called message from the
*> current rununit
declare msg as string
call "CBL_MANAGED_SESSION_GET_USERDATA" using
                                         by value "message"
                                         returning msg
end-call.

*> creates a new user data object that contains the
*> original object   "OK"
set msg to msg & " - OK"
call "CBL_MANAGED_SESSION_SET_USERDATA" using
                                          by value "reply"
                                          by value msg
end-call.
goback.

And the Java program that calls the COBOL program from within a RunUnit:

import com.microfocus.cobol.runtimeservices.*;

class demoUserData {
       public static void main(String[] args) {
           RunUnit ru = new RunUnit();
           try
           {
           ru.SetUserData("message","PASS: CBL_MANAGED_SESSION_GET_USER_DATA");
           ru.Call("GetUserDataExample");
           System.out.println(ru.GetUserData("reply"));
           }
           finally
           {
           ru.StopRun();
           }
       }
}
Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_MANAGED_SESSION_SET_USERDATA

Sets user data in the current RunUnit.

Syntax:

call "CBL_MANAGED_SESSION_SET_USERDATA" using by value user-dataname
                                              by value user-data.

Parameters:

user-dataname
picture clause: string
user-data
picture clause: object

On entry:

user-dataname
The name of the user data either set via the CBL_MANAGED_SESSION_SET_USERDATA library routine, or the RunUnit::SetUserData method.
user-data
Managed object to be associated with user-dataname.

On exit:

None.

Example:

The following example demonstrates the use of CBL_MANAGED_SESSION_GET_USERDATA and CBL_MANAGED_SESSION_SET_USERDATA from within a RunUnit.

The COBOL program that utilizes the library routines:

program-id. "GetUserDataExample".
procedure division.
*> retrieves a user data object called message from the
*> current rununit
declare msg as string
call "CBL_MANAGED_SESSION_GET_USERDATA" using
                                         by value "message"
                                         returning msg
end-call.

*> creates a new user data object that contains the
*> original object   "OK"
set msg to msg & " - OK"
call "CBL_MANAGED_SESSION_SET_USERDATA" using
                                          by value "reply"
                                          by value msg
end-call.
goback.

And the Java program that calls the COBOL program from within a RunUnit:

import com.microfocus.cobol.runtimeservices.*;

class demoUserData {
       public static void main(String[] args) {
           RunUnit ru = new RunUnit();
           try
           {
           ru.SetUserData("message","PASS: CBL_MANAGED_SESSION_GET_USER_DATA");
           ru.Call("GetUserDataExample");
           System.out.println(ru.GetUserData("reply"));
           }
           finally
           {
           ru.StopRun();
           }
       }
}
Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_PUT_SHMEM_PTR

Creates or updates a named value.

Syntax:

call "CBL_PUT_SHMEM_PTR" using by value     node-value
                               by reference node-name
                         returning          status-code

Parameters

node-value
Call prototype (see Key): cblt-pointer
Picture: usage pointer.
node-name
Group predefined as cblt-node-name containing:
01  cblt-node-name          typedef.
  03 cblte-nname-name-len   cblt-x1-comp5. *> pic x comp-5 value n.
  03 cblte-nname-name-text  cblt-x1.       *> occurs depending cblte-nname-name-len.
                                           *> pic x(n) value "name".
status-code
See Library Routines - Key.

On Entry:

node-value | The value to assign to the created/updated named value.
cblte-nname-name-len | The length of name.
cblte-nname-name-text | The name of the named value.

On Exit:

None

Comments:

Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


CBL_YIELD_RUN_UNIT

Yields the remainder of a run-unit's time-slice.

Syntax:

call "CBL_YIELD_RUN_UNIT"

Parameters:

None

Comments:

The remainder of the run-unit's time-slice is yielded to unspecified run-units.

Parent topic: Run unit handling routines
Parent topic: Alphabetical List of Library Routines


Screen Routines

Restriction: These routines are supported for native COBOL only.

A number of the screen routines specify the screen-position parameter. In this COBOL system, the top left corner of the screen is row 0, column 0. For example, if you want to change attributes beginning in row 5, column 8, you specify row-number as 4 and column-number as 7.

The CBL_GET_SCR routines enable you to make use of generic line drawing to produce the best possible representation of graphics characters available in any supported environment without having to modify your source programs.

  • CBL_CLEAR_SCR
    Clears the whole screen to a specified character and attribute.
  • CBL_GET_CSR_POS
    Returns the cursor position.
  • CBL_GET_SCR_GRAPHICS
    Returns operating system independent codes for graphics characters.
  • CBL_GET_SCR_LINE_DRAW
    Returns a table of values defining the character values required by the run-time system screen output routines to correctly display given line drawing characters.
  • CBL_GET_SCR_SIZE
    Returns information about the size of the screen.
  • CBL_READ_SCR_ATTRS
    Reads a string of attributes from the screen.
  • CBL_READ_SCR_CHARS
    Reads a string of characters from the screen.
  • CBL_READ_SCR_CHATTRS
    Reads a string of characters and their attributes from the screen.
  • CBL_SET_CSR_POS
    Moves the cursor.
  • CBL_SWAP_SCR_CHATTRS
    Swaps a string of characters and their attributes with a string from the screen.
  • CBL_WRITE_SCR_ATTRS
    Writes a string of attributes to the screen.
  • CBL_WRITE_SCR_CHARS
    Writes a string of characters to the screen.
  • CBL_WRITE_SCR_CHARS_ATTR
    Writes a string of characters to the screen, giving them all the same attribute.
  • CBL_WRITE_SCR_CHATTRS
    Writes a string of characters and their attributes to the screen.
  • CBL_WRITE_SCR_N_ATTR
    Writes a specified attribute to a string of positions on the screen.
  • CBL_WRITE_SCR_N_CHAR
    Writes a specified character to a string of positions on the screen.
  • CBL_WRITE_SCR_N_CHATTR
    Writes a specified character and attribute to a string of positions on the screen.
  • CBL_WRITE_SCR_TTY
    Writes a string of characters to the screen starting at the current position and scrolling.
  • X"A7" function 17
    Sets the cursor type.
  • X"A7" function 18
    Makes console I/O redirectable.
  • X"A7" function 25
    Returns the current screen type as recognized by the run-time system.
  • X"AF" function 18
    Displays a character to the screen at the current cursor position.
  • X"AF" function 22
    Sounds the terminal alarm.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_CLEAR_SCR

Clears the whole screen to a specified character and attribute.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_CLEAR_SCR" using     character
                               attribute-buffer
                     returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
character | cblt-x1-compx | pic x.
attribute-buffer | cblt-x1-compx | pic x.
status-code | See Library Routines - Key |

On Entry:

character The character to write.
attribute-buffer The attribute(s) to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT

On Exit:

None.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_CSR_POS

Returns the cursor position.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_CSR_POS" using     screen-position
                       returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing
01 cblt-screen-position     typedef.
  03 cblte-scrp-row         cblt-x1-compx.  *> pic x comp-x.
  03 cblte-scrp-col         cblt-x1-compx.  *> pic x comp-x.
status-code
See Library Routines - Key.

On Entry:

None

On Exit:

screen-position The screen position of the cursor. The top left corner is row 0, column 0. If the cursor is invisible, cblte-scrp-row and cblte-scrp-col are both set to 255.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_SCR_GRAPHICS

Returns operating system independent codes for graphics characters.

Restriction: This routine is supported for native COBOL only.

Syntax

        call "CBL_GET_SCR_GRAPHICS" using     graphics-params
        returning status-code

Parameters

graphics-params
Group predefined as cblt-get-scr-graphics-buffer, a group containing:
01 cblt-get-scr-graphics-buffer          typedef.
  03 cblte-gsgb-flag                     cblt-x1-compx.     *> pic x comp-x.
  03 cblte-gsgb-buf-size                 cblt-x2-compx.     *> pic x(2) comp-x.
  03 cblte-gsgb-buf.
    04 cblte-gsgb-up-arrow.
      05 cblte-gsgb-up-arrow-dbflag      cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-up-arrow-arrow       cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-down-arrow.
      05 cblte-gsgb-down-arrow-dbflag    cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-down-arrow-arrow     cblt-x1-compx.     *> pic x
    04 cblte-gsgb-right-arrow.
      05 cblte-gsgb-right-arrow-dbflag   cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-right-arrow-arrow    cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-left-arrow.
      05 cblte-gsgb-left-arrow-dbflag    cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-left-arrow-arrow     cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-maximize.
      05 cblte-gsgb-maximize-dbflag      cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-maximize-char        cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-minimize.
      05 cblte-gsgb-minimize-dbflag      cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-minimize-char        cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-check.
      05 cblte-gsgb-check-dbflag         cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-check-char           cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-restore.
      05 cblte-gsgb-restore-dbflag       cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-restore-char         cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-radio.
      05 cblte-gsgb-radio-dbflag         cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-radio-char           cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-scroll.
      05 cblte-gsgb-scroll-dbflag        cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-scroll-char          cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-rubber-band.
      05 cblte-gsgb-rubber-band-dbflag   cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-rubber-band-char     cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-sysmenu.
      05 cblte-gsgb-sysmenu-char-dbflag  cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-sysmenu-char-char    cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-editor-char.
      05 cblte-gsgb-editor-char-dbflag   cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-editor-char-char     cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-hyhelp-tab.
      05 cblte-gsgb-hyhelp-tab-dbflag    cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-hyhelp-tab-char      cblt-x1-compx.     *> pic x.
    04 cblte-gsgb-hyhelp-btab.
      05 cblte-gsgb-hyhelp-btab-dbflag   cblt-x1-compx.     *> pic x comp-x.
      05 cblte-gsgb-hyhelp-btab-char     cblt-x1-compx.     *> pic x.
status-code
See Library Routines - Key.

On Entry

cblte-gsgb-flag
Type of character code to return:
Code | Description
0 | Either single-byte or double-byte character set as appropriate for the host environment
1 | Only single-byte character set (SBCS)
2 | Only double-byte character set (DBCS)
cblte-gsgb-buf-size
Length of cblte-gsgb-buf in bytes. The normal value of cblte-gsgb-buf-size is 30, although by specifying a smaller value you can request only the graphics values you require.

You must not set cblte-gsgb-buf-size to be greater than the length of cblte-gsgb-buf. If cblte-gsgb-buf-size exceeds the length of cblte-gsgb-buf, the run-time system continues to write to memory past the buffer, which could corrupt other data.

On Exit

cblte-gsgb-buf-size
Number of bytes filled.
cblte-gsgb-buf
Character codes for each entry that is completely contained in the cblte-gsgb-buf-size byte count. The contents of any character code which is only partially in the byte count is undefined. Any character codes wholly outside the byte count are ignored.

The byte count should include the whole of any DBCS character-part, even if DBCS is not requested or expected.

For the cblte-gsgb-*-dbflg data items, zero indicates single-byte character codes have been returned; a nonzero value is the first byte of the double-byte character returned.

status-code
Return status:
Code | Description
0 | Success
1 | Not all requested codes were available; cblte-gsgb-buf-size contains the number of bytes that were returned
2 | cblte-gsgb-buf could not be filled with the character codes specified (either SBCS or DBCS). In this case, the characters that were not available were filled as though cblte-gsgb-flag was set to 0.
3 | Both the errors signaled by status-code = 1 and 2 occurred.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_SCR_LINE_DRAW

Returns a table of values defining the character values required by the run-time system screen output routines to correctly display given line drawing characters.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_SCR_LINE_DRAW" using     function-code
                                       line-draw-table
                             returning status-code

Parameters

function-code
Call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
Contains one of the following:

0: Request for single-byte line drawing table

1: Request for double-byte line drawing table

2: Request for a single single-byte line drawing code

3: Request for a single double-byte line drawing code

line-draw-table
Group predefined as cblt-get-scr-line-draw-buffer containing:
01   cblt-get-scr-line-draw-buffer        typedef.
  03 cblte-gsld-draw-code                 cblt-x1-compx.  *> pic x comp-x.
  03 cblte-gsld-dbcs-draw-char            cblt-x2-compx.  *> various pic x(2) Occurs n times
  03 cblte-gsld-draw-char
     redefines cblte-gsld-dbcs-draw-char  cblt-x1-compx.  *> Occurs n times
status-code
See Library Routines - Key.

On Entry:

With function-code = 2 or 3
cblte-gsld-draw-code
The offset (shape description) of the character required.

On Exit:

cblte-gsld-draw-code
Byte filled in by the run-time system to determine any mapping that has taken place in the table as follows:
For bits 0 through 2, line types are mapped to the first available of single, double, extended or ASCII character.
bit 7 - 3 | Reserved (set to 0)
bit 2 | Extended lines not supported - mapped
bit 1 | Double lines not supported - mapped
bit 0 | Single lines not supported - mapped
With function-code = 0
cblte-gsld-draw-char
The single-byte line drawing table. Bytes in the table are arranged as follows:
bits 6 and 7 | The North line.
bits 4 and 5 | The South line
bits 2 and 3 | The West line
bits 0 and 1 | The East line
  • The bit pairs are combined and used as an index into the table.
  • Non-valid combinations will map to a space.
  • For a valid combination any two of the bit pairs must each have at least one bit set.
  • You must specify at least 2 bit pairs.
With function-code = 1
cblte-gsld-dbcs-draw-char
The double-byte line drawing table. Bytes in the table are arranged as follows:
bits 6 and 7 | The North line.
bits 4 and 5 | The South line
bits 2 and 3 | The West line
bits 0 and 1 | The East line
With function-code = 2
cblte-gsld-draw-char
The requested single single-byte line drawing code.
With function-code = 3
cblte-gsld-dbcs-draw-char
The requested single double-byte line drawing code.

Comments:

When requesting a single line drawing character (function-code = 2 or 3), the cblte-gsld-draw-code parameter is used to tell the run-time system which character you require. The cblte-gsld-draw-code parameter for a given cblte-gsld-drawing shape can be calculated by splitting a byte into four bit-pairs. Each bit-pair defines the type of line that you want to appear in one of the four directions:

Bits | Direction
7 and 6 | North
5 and 4 | South
3 and 2 | West
1 and 0 | East

Each bit-pair can have one of the following values:

00 | In the given direction, there is no line
01 | There is a single-thickness line
10 | There is a double-thickness line
11 | There is an extended-type line.

The extended line type is available only for systems which have additional types of line drawing, such as dotted lines. If a system has more than one additional type, only one can be used at a time.

For example, if you wished to find out the screen handler's character code for a line which would define the bottom-left of a box with single thickness sides and a double thickness bottom, you would make the following calculations:

Bit-pairs:

North: | 01 (single)
South: | 00 (blank)
West: | 00 (blank)
East: | 10 (double)

This gives the binary value of 01000010 or a decimal value of 66. Therefore, you would move 66 to cblte-gsld-draw-code before calling CBL_GET_SCR_LINE_DRAW in order to obtain the correct character for this shape.

If you use function-code = 0 or 1 to obtain the full line drawing table, a given character can be located in the table using the bit-pair algorithm described above, which yields a numeric value for a given shape. However, by default, COBOL subscripts begin at one, not zero. Therefore, if you use the following construct to obtain the full line drawing table:

  03 cblte-gsld-draw-char    pic x occurs 256 times.

you need to add 1 to the result of the bit-pair algorithm to locate the correct character (and, therefore, need a subscript which is larger than one byte).

However, you can use the following construct to obtain the table:

With function-code = 0:

  03
filler  pic x.
  03 cblte-gsld-draw-char    pic x occurs 255 times.

With function-code = 1:

  03 filler  pic x(2).
  03 cblte-gsld-dbcs-draw-char  pic x(2) occurs 255 times.

You must ensure that the NOBOUND Compiler directive is set to enable you to use subscripts 0 to 255, which map directly onto the result from the bit-pair algorithm.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_SCR_SIZE

Returns information about the size of the screen.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_SCR_SIZE" using     depth
                                  width
                        returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
depth | cblt-x1-compx | pic x comp-x.
width | cblt-x1-compx | pic x comp-x.
status-code | See Library Routines - Key |

On Entry:

None.

On Exit:

depth | Number of lines.
width | Number of columns.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_SCR_ATTRS

Reads a string of attributes from the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_READ_SCR_ATTRS" using     screen-position
                                    attribute-buffer
                                    string-length
                          returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x(2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines.
string-length | The length of the string to read.

On Exit:

attribute-buffer The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.

The attributes are as follows:

B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length If the end of the screen is reached the length read is returned in here.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_SCR_CHARS

Reads a string of characters from the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_READ_SCR_CHARS" using     screen-position
                                    character-buffer
                                    string-length
                          returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x(2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines.
string-length | The length of the string to read.

On Exit:

character-buffer | The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.
string-length | If the end of the screen is reached, the length read is returned in here.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_SCR_CHATTRS

Reads a string of characters and their attributes from the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_READ_SCR_CHATTRS"  using    screen-position
                                      character-buffer
                                      attribute-buffer
                                      string-length
                            returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x(2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines.
string-length | The length of the string to read.

On Exit:

character-buffer | The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.
attribute-buffer The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.

The attributes are as follows:

B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | If the end of the screen is reached, the length read (in cells, that is, character-attribute pairs) is returned in here.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_SET_CSR_POS

Moves the cursor.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SET_CSR_POS" using     screen-position
                       returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position The screen position at which to put the cursor. The top left corner is row 0, column 0. See Screen Routines

On Exit:

None

Comments:

To make the cursor invisible, set cblte-scrp-row and cblte-scrp-col to 255. Any other legal on-screen values make the cursor visible.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_SWAP_SCR_CHATTRS

Swaps a string of characters and their attributes with a string from the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_SWAP_SCR_CHATTRS"  using     screen-position
                                      character-buffer
                                      attribute-buffer
                                      string-length
                            returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character-buffer | The characters to write.
attribute-buffer The attributes to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

character-buffer | The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.
attribute-buffer | The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged.
string-length | If the end of the screen is reached the length swapped (in cells, that is, character-attribute pairs) is returned in here.
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_ATTRS

Writes a string of attributes to the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_ATTRS" using     screen-position
                                     attribute-buffer
                                     string-length
                           returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position       typedef.
   03 cblte-scrp-row          cblt-x1-compx. 	*> pic x comp-x.
   03 cblte-scrp-col          cblt-x1-compx. 	*> pic x comp-x.
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
attribute-buffer The attribute(s) to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_CHARS

Writes a string of characters to the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_CHARS" using     screen-position
                                     character-buffer
                                     string-length
                           returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character-buffer | The characters to write.
string-length | The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_CHARS_ATTR

Writes a string of characters to the screen, giving them all the same attribute.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_CHARS_ATTR" using     screen-position
                                          character-buffer
                                          string-length
                                          attribute-buffer
                                returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x (2) comp-x.
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character-buffer | The characters to write.
attribute-buffer The attributes to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_CHATTRS

Writes a string of characters and their attributes to the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_CHATTRS" using     screen-position
                                       character-buffer
                                       attribute-buffer
                                       string-length
                             returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position                 typedef.
   03    cblte-scrp-row                  cblt-x1-compx. 	*> pic x comp-x.
   03    cblte-scrp-col                  cblt-x1-compx. 	*> pic x comp-x.
character-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
attribute-buffer
Call prototype (see Key): pic x (n).
Picture: pic x (n).
string-length
Call prototype (see Key): cblt-x2-compx.
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character-buffer | The characters to write.
attribute-buffer The attribute(s) to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_N_ATTR

Writes a specified attribute to a string of positions on the screen.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_N_ATTR"  using     screen-position
                                      attribute-buffer
                                      fill-length
                            returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
attribute-buffer
Call prototype (see Key): pic x1-compx
Picture: pic x.
fill-length
Call prototype (see Key): pic x2-compx
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
attribute-buffer The attribute(s) to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
string-length | The number of screen positions to write the attribute to. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_N_CHAR

Writes a specified character to a string of positions on the screen.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_N_CHAR"  using     screen-position
                                      character
                                      string-length
                            returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character
Call prototype (see Key): pic x1-compx
Picture: pic x.
string-length
Call prototype (see Key): pic x2-compx
Picture: pic x (2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character | The character to write.
string-length | The number of screen positions to write the character to. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_N_CHATTR

Writes a specified character and attribute to a string of positions on the screen.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_N_CHATTR" using     screen-position
                                        character
                                        attribute-buffer
                                        fill-length
                              returning status-code

Parameters

screen-position
Group predefined as cblt-screen-position containing:
01 cblt-screen-position   typedef.
  03 cblte-scrp-row       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-scrp-col       cblt-x1-compx. 	*> pic x comp-x.
character
Call prototype (see Key): cblt-x1-compx
Picture: pic x.
attribute-buffer
Call prototype (see Key): cblt-x1-compx
Picture: pic x.
fill-length
Call prototype (see Key): cblt-x2-compx
Picture: pic x(2) comp-x.
status-code
See Library Routines - Key.

On Entry:

screen-position | The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines
character | The character to write.
attribute-buffer The attribute(s) to write. Use the following table to set one or more attributes:
B"10000000" | Reserved
B"01000000" | Reserved
B"00100000" | Reserved
B"00010000" | Reserved
B"00001000" | BLANK
B"00000100" | REVERSE-VIDEO
B"00000010" | UNDERLINE
B"00000001" | HIGHLIGHT
fill-length | The number of screen positions to write the character-attribute pair to. If this would go off the end of the screen, the write finishes at the end of the screen.

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_SCR_TTY

Writes a string of characters to the screen starting at the current position and scrolling.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_WRITE_SCR_TTY" using     character-buffer
                                   string-length
                         returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
character-buffer | pic x(n). | pic x(n).
string-length | cblt-x2-compx | pic x(2) comp-x.
status-code | See Library Routines - Key |

On Entry:

character-buffer | The characters to write.
string-length | The length of the string to write. If this would go off the edge of the screen, the screen is scrolled up a line and the write continues on the bottom line.

On Exit:

None

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


X"A7" function 17

Sets the cursor type.

Note: This routine is supported for native COBOL only.

Syntax:

call X"A7" using function-code
                 cursor-type

Parameters:

function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
cursor-type
Group containing:
01 cursor-type
  03 cursor-end   cblt-x1-compx   *> pic x comp-x.
  03 cursor-start cblt-x1-compx   *> pic x comp-x.

On Entry:

function-code | Value 17.
cursor-end | Scan line cursor ends on.
cursor-start | Scan line cursor starts on.

On Exit:

None

Comments:

Details of cursor-start and end lines can be found in your IBM BIOS Technical Reference manual.

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


X"A7" function 25

Returns the current screen type as recognized by the run-time system.

Note: This routine is supported for native COBOL only.

Syntax:

call x"A7" using function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx | pic x comp-x.

On Entry:

function-code
Value 25

On Exit:

parameter
Bit settings indicating the type of screen as follows:
bit 0 | unset = monochrome screen
bit 1 | reserved
bit 2 | reserved
bit 3 | set = EGA-type screen
bit 4 | set = VGA-type screen
bit 5 | reserved
bit 6 | reserved
bit 7 | reserved
Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


X"AF" function 18

Displays a character to the screen at the current cursor position.

Note: This routine is supported for native COBOL only.

Syntax:

call x"AF" using function-code
                 char

Parameters:

 | Using call prototype (see Key) | Picture
function-code | cblt-x1-compx | pic x comp-x.
char | pic x | pic x

On Entry:

function-code | Value 18
char | The character to be displayed.

On Exit:

None

Parent topic: Screen Routines
Parent topic: Alphabetical List of Library Routines


State Maintenance Routines

Restriction: These routines are supported for native COBOL only.

The state maintenance routines enable you to create an internet application which can store user and application state information on the web server.

For more details on using the state maintenance routines, see the CGI-based Applications book.

  • MF_CLIENT_STATE_ALLOCATE
    Allocates a client identifier.
  • MF_CLIENT_STATE_DELETE
    Deletes an existing client identifier and its associated client information.
  • MF_CLIENT_STATE_EXPIRY
    Returns a date string for use in the cookie expiry field.
  • MF_CLIENT_STATE_FILE
    Specifies the file to be used on the server to store state information.
  • MF_CLIENT_STATE_PURGE
    Deletes all client information older than the number of days specified.
  • MF_CLIENT_STATE_RESTORE
    Restores a previously saved or allocated record which matches the client identifier.
  • MF_CLIENT_STATE_SAVE
    Updates the information in the state file.
  • State Maintenance Routines Status
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


MF_CLIENT_STATE_ALLOCATE

Allocates a client identifier.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_ALLOCATE" using  client-id
                                       client-length
                                       server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
client-id | pic x(30). | pic x(30).
client-length | cblt-x4-compx | pic x(4) comp-x.
server-status | cblt-x1-compx | pic x comp-x.

On Entry:

client-id | The client identifier. See Comments below.
client-length | The length of the empty record for the state information.

On Exit:

client-id | The client identifier. See Comments below.
server-status | The status of the operation. See State Maintenance Routines Status.

Comments:

This routine:

  • Allocates a new empty record for the state information, with the length given in client-length.
  • Returns a new client-id, and allocates an empty record, if the value passed in client-id is set to spaces. Otherwise, if client-id is set to a valid client identifier, this routine allocates an empty record with that client identifier.

Example:

 working-storage section.
 ...
 01 client-id                pic x(30).
 01 client-length            pic xxxx comp-x.
 01 state-status             pic x comp-x.
 ...
 procedure division.
 ...
     call "MF_CLIENT_STATE_ALLOCATE"
          using client-id client-length state-status
 ...
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_DELETE

Deletes an existing client identifier and its associated client information.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_DELETE " using client-id
                                     server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
client-id | pic x(30). | pic x(30).
server-status | cblt-x1-compx | pic x comp-x.

On Entry:

client-id The client identifier.

On Exit:

server-status The status of the operation. See State Maintenance Routines Status.
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_EXPIRY

Returns a date string for use in the cookie expiry field.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_EXPIRY" using date-criteria
                                  expiry-string

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
date-criteria | cblt-x4-compx | pic x(4) comp-x.
expiry-string | pic x(50). | pic x(50).

On Entry:

date-criteria The number of days after which client records are to expire.

On Exit:

expiry-string The expiry date to be used in the cookie expiry field.

Comments:

expiry-string returns a value with the format day, dd-month-yyyy hh:mm:ss GMT

Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_FILE

Specifies the file to be used on the server to store state information.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_FILE" using filename
                                  server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
filename | pic x(255). | pic x(255).
server-status | cblt-x1-compx | pic x comp-x.

On Entry:

filename The filename.

On Exit:

server-status The status of the operation. See State Maintenance Routines Status.

Example:

 working-storage section.
 ...
 01 state-status             pic x comp-x.
 01 state-filename           pic x(255)
               value "MF-STATE-SAVE.DAT".
 ...
 procedure division.
 ...
     call "MF_CLIENT_STATE_FILE" using state-filename
                                       server-status
 ...
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_PURGE

Deletes all client information older than the number of days specified.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_PURGE" using date-criteria
                                   server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
date-criteria | cblt-x4-compx | pic x(4) comp-x.
server-status | cblt-x1-compx | pic x comp-x.

On Entry:

date-criteria The number of days after which client information should be purged.

On Exit:

server-status The status of the operation. See State Maintenance Routines Status.
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_RESTORE

Restores a previously saved or allocated record which matches the client identifier.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_RESTORE " using client-id
                                      client-state
                                      client-length
                                      server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
client-id | pic x(n). | pic x(30).
client-state | cblt-x4-compx | pic x(4) comp-x.
client-length | See Comments.
server-status | cblt-x1-compx | pic x comp-x.

On Entry:

client-id | The client identifier.
client-state | The state information to be saved. See Comments.
client-length | The length of the empty record for the state information.

On Exit:

client-state | The state information to be saved. See Comments.
server-status | The status of the operation. See State Maintenance Routines Status.

Comments:

On entry, client-length is the length of the buffer. On exit, client-length returns the length of the data recovered. The data is truncated to fit the client-length specified on entry.

You can define any format for client-state records. Define the length of the client-state record in the client-length field.

Example:

 working-storage section.
 ...
 01 client-id                pic x(30).
 01 client-length            pic xxxx comp-x.
 01 state-status             pic x comp-x.
01 client-state.
   03 user-preferences       pic x(10).
   03 user-selection-list    pic x(80).
...
 procedure division.
 ...
     call "MF_CLIENT_STATE_RESTORE"
            using client-id client-state
                  client-length state-status
 ...
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


MF_CLIENT_STATE_SAVE

Updates the information in the state file.

Note: This routine is supported for native COBOL only.

Syntax:

call "MF_CLIENT_STATE_SAVE" using client-id
                                  client-state
                                  client-length
                                  server-status

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems)
client-id | pic x(n). | pic x(30).
client-state | cblt-x4-compx | pic x(4) comp-x.
client-length | See Comments. |
server-status | cblt-x1-compx | pic x comp-x.
status-code | See Library Routines - Key |

On Entry:

client-id | The client identifier.
client-state | The state information to be saved. See Comments.
client-length | The length of the empty record for the state information.

On Exit:

server-status The status of the operation. See State Maintenance Routines Status.

Comments:

This routine saves a previously allocated client-id and client state, or rewrites a previously saved client-id and client state. client-length can be updated.

You can define any format for client-state records. Define the length of the client-state record in the client-length field.

Example:

 working-storage section.
 ...
 01 client-id                pic x(30).
 01 client-length            pic x(4) comp-x.
 01 state-status             pic x comp-x.
 01 client-state.
   03 user-preferences       pic x(10).
   03 user-selection-list    pic x(80).
...
 procedure division.
 ...
     call "MF_CLIENT_STATE_SAVE"
            using client-id client-state
                  client-length state-status
 ...
Parent topic: State Maintenance Routines
Parent topic: Alphabetical List of Library Routines


State Maintenance Routines Status

0 | Call is successful
1 | Call failed
2 | Duplicate client-id has been found (allocate)
3 Possible causes:
  • Client-id not found (save and restore).
  • Trying to save/restore/delete a record with no matching key.
  • Another internal error happens (due to incorrect CALL order).
  • Record allocation problem.
Parent topic: State Maintenance Routines


Text Routines

  • CBL_TOLOWER
    Converts a string of letters to lower case.
  • CBL_TOUPPER
    Converts a string of letters to upper case.
  • PC_WIN_SET_CHARSET
    Specifies the character set to be used by the case conversion routines CBL_TOUPPER and CBL_TOLOWER.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_TOLOWER

Converts a string of letters to lower case.

Syntax:

call "CBL_TOLOWER" using      string
                   by value length
                   returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
string | pic x(n). | pic x(n).
length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

string | The string to convert.
length | The number of bytes of string to change; positions beyond this are unchanged.

On Exit:

string The converted string.

Comments:

The routine starts at the left-hand end of string and converts letters to lower case (also called folding to lower case).

Parent topic: Text Routines
Parent topic: Alphabetical List of Library Routines


CBL_TOUPPER

Converts a string of letters to upper case.

Syntax:

call "CBL_TOUPPER" using     string
                   by value  length
                   returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
string | pic x(n). | pic x(n).
length | cblt-os-size | pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
status-code | See Library Routines - Key |

On Entry:

string | The string to convert.
length | The number of bytes of string to change; positions beyond this are unchanged.

On Exit:

string The converted string.

Comments:

The routine starts at the left-hand end of string and converts letters to upper case (also called folding to upper case).

Parent topic: Text Routines
Parent topic: Alphabetical List of Library Routines


Unit Testing Routines

Call one of these routines from your unit tests to indicate that the test has failed, and to produce a failure assertion message.

  • MFU_ASSERT_FAIL
    Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report.
  • MFUFMSG
    Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report.
  • MFU_ASSERT_FAIL_Z
    Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report.
  • MFUFMSGZ
    Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report.
Parent topic: Library Routines


MFU_ASSERT_FAIL

Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report.

Syntax:

call "MFU_ASSERT_FAIL" using by reference msg
                             by value msg-len
end-call.

Parameters:

msg
pic x(n)
msg-len
binary-long

On Entry:

msg
The message that is used in the test report output.
msg-len
The length of the message.

On Exit:

None.

Example:

call "MFU_ASSERT_FAIL" using
                       by reference "Condition 4 has failed."
                       by value 23
end-call.

Comments:

The unit testing library routines use the mfunit_prototype.cpy copybook for call prototyping. If required, it is available from the cpylib directory of your product installation directory.

Parent topic: Unit Testing Routines
Related information
MFUFMSG
MFU_ASSERT_FAIL_Z
MFUFMSGZ


MFUFMSG

Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a message to the test report.

Syntax:

call "MFUFMSG" using by reference msg
                             by value msg-len
end-call.

Parameters:

msg
pic x(n)
msg-len
binary-long

On Entry:

msg
The message that is used in the test report output.
msg-len
The length of the message.

On Exit:

None.

Example:

call "MFUFMSG" using
                       by reference "Condition 4 has failed."
                       by value 23
end-call.

Comments:

Use this library routine (in place of MFU_ASSERT_FAIL) when your test case uses a mainframe dialect. Mainframe dialects such as ENTCOBOL restrict the names of program-ids and entry points to 8 characters or less, hence the shorter routine name.

The unit testing library routines use the mfunit_prototype.cpy copybook for call prototyping. If required, it is available from the cpylib directory of your product installation directory.

Parent topic: Unit Testing Routines
Related information
MFU_ASSERT_FAIL
MFU_ASSERT_FAIL_Z
MFUFMSGZ


MFU_ASSERT_FAIL_Z

Signifies that a test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report.

Syntax:

call "MFU_ASSERT_FAIL_Z" using by reference msg
end-call.

Parameters:

msg
pic x(n)

On Entry:

msg
The message that is used in the test report output. This message string is null-terminated.

On Exit:

None.

Example:

call "MFU_ASSERT_FAIL_Z" using
                       by reference z"Condition 6 has failed."
end-call.

Comments:

The unit testing library routines use the mfunit_prototype.cpy copybook for call prototyping. If required, it is available from the cpylib directory of your product installation directory.

Parent topic: Unit Testing Routines
Related information
MFU_ASSERT_FAIL
MFUFMSG
MFUFMSGZ


MFUFMSGZ

Signifies that a mainframe test case running under the Micro Focus Unit Testing framework has failed, and outputs a null-terminated message to the test report.

Syntax:

call "MFUFMSGZ" using by reference msg
end-call.

Parameters:

msg
pic x(n)

On Entry:

msg
The message that is used in the test report output.

On Exit:

None.

Example:

call "MFUFMSGZ" using
                       by reference z"Condition 6 has failed."
end-call.

Comments:

Use this library routine (in place of MFU_ASSERT_FAIL_Z) when your test case uses a mainframe dialect. Mainframe dialects such as ENTCOBOL restrict the names of program-ids and entry points to 8 characters or less, hence the shorter routine name.

The unit testing library routines use the mfunit_prototype.cpy copybook for call prototyping. If required, it is available from the cpylib directory of your product installation directory.

Parent topic: Unit Testing Routines
Related information
MFU_ASSERT_FAIL
MFUFMSG
MFU_ASSERT_FAIL_Z


Virtual Heap Routines

A heap is a byte-stream file which is buffered in available memory.

The status word specified when the heap is created is associated with each heap. It is written to when an operation on the heap fails. Each heap is thereby attached to a particular program, namely the program which contains the heap's status word, and is automatically deallocated (unless it has already been explicitly deallocated by a call to CBL_CLOSE_VFILE) when that program is canceled.

A heap is identified by a heap identifier word. This can be passed around between programs so that the heap can be read or written by any program. However, in order to check for failure, the program needs to have access (using a pointer variable, for example, or via normal linkage section mapping) to the associated status word.

Alternatively the RETURN-CODE register can be examined to catch a general heap function failure. The specific error can then be determined by examining the heap status word.

If the read/write succeeds, the RETURN-CODE is zero. If it fails, the RETURN-CODE is nonzero and the heap status first byte contains "9", with detail in the second byte.

The buffer used with CBL_READ_VFILE and CBL_WRITE_VFILE can reside anywhere in the Data or Linkage Section, or it can be dynamically allocated using the CBL_ALLOC_MEM routine.

Each heap is paged, if necessary. A heap is paged into a separate file on disk with name sourcename.Vnn, where sourcename is the base-name of the program to which the heap is attached and nn is an integer from 1 to 99. Once nn reaches 99, the V is overwritten. The maximum number allowed for the extension is 384.

The number of local heaps is configurable, up to 65535.

You can use reference modification in the buffer call parameter to declare the heap buffer in the middle of a COBOL record. This is compiled efficiently provided the length is given as fixed; since the length is ignored by the call interface, you can give it as one.

  • CBL_CLOSE_VFILE
    Closes a heap.
  • CBL_OPEN_VFILE
    Opens a heap.
  • CBL_READ_VFILE
    Reads bytes from a heap.
  • CBL_WRITE_VFILE
    Writes bytes to a heap.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_CLOSE_VFILE

Closes a heap.

Syntax:

call "CBL_CLOSE_VFILE" using by value heap-id
                       returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
heap-id | cblt-vfile-handle | pic x(2) comp-5.
status-code | See Library Routines - Key

On Entry:

heap-id This contains the heap handle assigned when the heap was opened.

On Exit:

None.

Parent topic: Virtual Heap Routines
Parent topic: Alphabetical List of Library Routines


CBL_OPEN_VFILE

Opens a heap.

Syntax:

call "CBL_OPEN_VFILE" using     heap-id
                                status-word
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
heap-id | cblt-vfile-handle. | pic x(2) comp-5.
status-word | cblt-vfile-status. | pic x(2) comp-x.
status-code | See Library Routines - Key.

On Entry:

None

On Exit:

heap-id
The heap handle assigned. A heap handle of zero means the open failed.
status-word
The status word for the heap, set to zero on the open. When status-word (1:1) = '9', binary values in the second status byte are:
000 | Heap closed by user request
001 | Heap access failure - out of buffers
002 | Heap deallocated while program inactive
014 | Backing-file failure: too many files
037 | Backing-file failure: file access denied
201 | Backing-file failure: I/O failure
status-word remains associated with the heap until the heap is closed; the first byte is set to ASCII zero by a successful OPEN; status-word is written as file status data by a subsequent heap READ, WRITE or CLOSE that encounters allocation or I/O errors (but is not reset to zero by successful operations).
If a program in which a heap status word actually exists (that is, it is not in a Linkage Section) is canceled, all heaps with status words in that program are automatically canceled, and the heap identifiers (which might have been passed to other programs) should not be used any more.
Parent topic: Virtual Heap Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_VFILE

Reads bytes from a heap.

Syntax:

call "CBL_READ_VFILE" using by value heap-id
                                     heap-ref
                                     heap-length
                      by reference   heap-buffer
                      returning      status-code

Parameters:

 | Using call prototype (see Key) | Picture
heap-id | cblt-vfile-handle. | pic x(2) comp-5.
heap-ref | cblt-x4-comp5. | pic x(4) comp-5.
heap-length | cblt-x4-comp5. | pic x(4) comp-5.
heap-buffer | pic x(n). | pic x(n).
status-code | See Library Routines - Key. |

On Entry:

heap-id | This contains the heap handle assigned when the heap was opened.
heap-ref | Offset in the heap at which to start reading. In .NET, this is limited to a maximum value of 0x7fffffff.
heap-length | Number of bytes to read.

On Exit:

heap-buffer Buffer into which bytes are read. It is your responsibility to ensure that the buffer is large enough to hold the number of bytes being read.

Comments:

Trying to read data from an area of the heap which has not yet been written results in indeterminate data being returned to the buffer.

Parent topic: Virtual Heap Routines
Parent topic: Alphabetical List of Library Routines


CBL_WRITE_VFILE

Writes bytes to a heap.

Syntax:

call "CBL_WRITE_VFILE" using by value heap-id
                                      heap-ref
                                      heap-length
                       by reference   heap-buffer
                        returning     status-code

Parameters:

 | Using call prototype (see Key) | Picture
heap-id | cblt-vfile-handle | pic x(2) comp-5.
heap-ref | cblt-x4-comp5 | pic x(4) comp-5.
heap-length | cblt-x4-comp5 | pic x(4) comp-5.
heap-buffer | pic x(n). | pic x(n).
status-code | See Library Routines - Key |

On Entry:

heap-id | The heap handle assigned when the heap was opened.
heap-ref | Offset in the heap at which to start writing. In .NET, this is limited to a maximum value of 0x7fffffff.
heap-length | Number of bytes to write.
heap-buffer | Buffer from which bytes are written. It is your responsibility to ensure that the buffer is large enough to hold the number of bytes being written.

On Exit:

None.

Parent topic: Virtual Heap Routines
Parent topic: Alphabetical List of Library Routines


Windows Routines

These routines are used when creating Windows API applications.

  • PC_ISAPI_GET_EXT
    Returns the ISAPI extension block.
  • PC_WIN_HANDLE
    Returns the handle of the window used for screen I/O.
  • PC_WIN_INIT
    Returns the Windows startup values.
  • SYSTEM
    Executes an arbitrary operating system command.
Parent topic: Library Routines


PC_ISAPI_GET_EXT

Returns the ISAPI extension block.

Note: This routine is supported for native COBOL only.

Syntax:

call "PC_ISAPI_GET_EXT"  using    ext-block
                            returning pc-status-code

Parameters:

file-details
Group containing
01 extension-control-block    typedef
   03 cbsize                  DWORD
   03 dwversion               DWORD
   03 connid                  HCONN
   03 dwhttpstatuscode        DWORD
   03 lpszlogdata             PIC x(hse-log-buffer-len)
   03 lpszmethod              LPSTR
   03 lpszquerystring         LPSTR
   03 lpszpathinfo            LPSTR
   03 lpszpathtranslated      LPSTR
   03 cbtotalbytes            DWORD
   03 cbavailable             DWORD
   03 lpbdata                 LPBYTE
   03 lpszcontenttype         LPSTR
   03 getservervariable       procedure-pointer
   03 writeclient             procedure-pointer
   03 readclient              procedure-pointer
   03 serversupportfunction   procedure-pointer
pc-status-code
See Library Routines - Key

On Entry:

cbsize
Length of extension block.

On Exit:

ext-block
ISAPI extension block as passed from the Web server.
pc-status-code
One of the following codes:
0 | OK
1 | Non-ISAPI environment
2 | cbsize smaller than current ISAPI extension block
Parent topic: Windows Routines


PC_WIN_HANDLE

Returns the handle of the window used for screen I/O.

Note: This routine is supported for native COBOL only.

Syntax:

call "PC_WIN_HANDLE" using      hwnd
                     returning  status-code

Parameters:

 | Using call prototype (see Key) | Picture (32-bit systems) | Picture (64-bit systems)
hwnd | cblt-HWND. | pic x(4) comp-x. | pic x(8) comp-x.
status-code | See Library Routines - Key |  |

On Entry:

None

On Exit:

hwnd Contains the window handle.

Comments:

This routine is available only in the Windows environment.

Parent topic: Windows Routines


PC_WIN_INIT

Returns the Windows startup values.

Syntax:

call "PC_WIN_INIT" using     hInst
                             hPrevInst
                             lpszCmdLine
                             nCmdShow
                   returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
hInst | cblt-HINSTANCE | usage pointer.
hPrevInst | cblt-HINSTANCE | usage pointer.
lpszCmdLine | cblt-pointer | usage pointer.
nCmdShow | cblt-x4-comp5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

None

On Exit:

hInst | The handle of this instance.
hPrevInst | The handle of the previous instance.
lpszCmdLine | A pointer to the command line. Not for COBOL use.
nCmdShow | Flags to indicate the attributes attached to any windows created.

Comments:

When starting a Windows application Windows returns four start-up values. These are required when calling a number of the Windows API routines. When using the shared run-time system, it is necessary to call this routine to get the start-up values so you can then use the Windows API.

You should not access the command line using the parameter passed here. Use ACCEPT ... FROM COMMAND-LINE instead.

This library routine is supported by the JVM runtime.

Parent topic: Windows Routines
Related concepts
JVM COBOL Interoperating with Native COBOL


SYSTEM

Executes an arbitrary operating system command.

Syntax:

CALL "SYSTEM" USING command-line

Parameters:

command-line
PIC X(n)

On Entry:

command-line
An alphanumeric data item that contains the command line to be passed to the operating system.
Parent topic: Windows Routines
Parent topic: Alphabetical List of Library Routines


Miscellaneous Routines

  • ES_WRITE_CUSTOM_HSF
    Writes data to a custom field in the HSF record viewable from the generated .csv file.
  • ESCSTHSF
    Writes data to a custom field in the HSF record viewable from the generated .csv file.
  • ESUSRTRC
    Allows you to write entries to the system trace table.
  • JVM_LOAD_NATIVE (deprecated)
    Loads a native shared library into the JVM runtime. Once the shared library is loaded, use the CALL statement to call one of its entry points, from your JVM COBOL programs.
  • JVM_UNSAFE_NATIVE_MEMCOPY
    Copies native memory to managed memory allocated by third-party APIs, such as the Windows FormatMessage API. You cannot address managed memory except with this JVM_UNSAFE_NATIVE_MEMCOPY library routine.
  • X"91" function 11
    Sets the programmable COBOL switches.
  • X"91" function 12
    Reads the programmable COBOL switches.
  • X"91" function 13
    Sets the run-time switches
  • X"91" function 15
    Checks for the existence of the specified program.
  • X"91" function 16 (deprecated)
    Shows how many of the parameters in the call statement of the calling program have been transferred to the called subprogram.
  • X"91" function 35
    Performs an EXEC call (like the DOS 4B call) to the specified program file, executing it.
  • X"91" function 69 (deprecated)
    Searches a directory for a given file specification.
  • X"E5"
    Sounds the bell.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


ES_WRITE_CUSTOM_HSF

Writes data to a custom field in the HSF record viewable from the generated .csv file.
Important: If your programs are running under a mainframe dialect, use the mainframe-compatible version of this library routine, entitled ESCSTHSF.

Syntax:

Restriction: This topic applies only when the Enterprise Server feature is enabled.
call "ES_WRITE_CUSTOM_HSF" using by value length
                                 by reference  data
                                 by value  id

Parameters:

length
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
data
Picture: pic x(n).
id
Call prototype (see Key): cblt-x4-comp5
Picture: pic x comp-5.

On Entry:

length
Specifies the length of the custom data (1-255 chars).
data
The data to be written to the custom field.
id
A one-byte value that identifies the custom field.
Note: This can be a value between 0-255.

On Exit:

return-code
0 | Success
12 | No id specified
16 | length is 0 or >255

Comments:

You can add up to five separate custom fields; configure the number of custom fields using the ES_HSF_CFG environment variable.

A call to this routine results in a trace (or traces if the data exceeds the maximum data length for a single entry - 8 bytes for 32-bit or 16 bytes for 64-bit) being written to the local trace table. Each call in the table can be identified by using the unique id used in the call - the trace id appears as x'ffid02'.

When the trace table is dumped to the .csv report, the custom fields (CUSTOM01, CUSTOM02, etc...) are populated in the order in that the custom entries are found (up to five entries, depending on the value of ES_HSF_CFG). If multiple calls are made for the same id, the call data is concatenated in the appropriate custom field (up to a maximum of 255 bytes).

If the user trace flag is switched on, the trace (or traces) are also written to the system trace table.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines
Related reference
ESCSTHSF
Environment variables in alphabetical order


ESCSTHSF

Writes data to a custom field in the HSF record viewable from the generated .csv file.
Note: This is the mainframe-compatible equivalent of ES_WRITE_CUSTOM_HSF.

Syntax:

Restriction: This topic applies only when the Enterprise Server feature is enabled.
call "ESCSTHSF" using by value length
                      by reference  data
                      by value  id

Parameters:

length
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
data
Picture: pic x(n).
id
Call prototype (see Key): cblt-x4-comp5
Picture: pic x comp-5.

On Entry:

length
Specifies the length of the custom data (1-255 chars).
data
The data to be written to the custom field.
id
A one-byte value that identifies the custom field.
Note: This can be a value between 0-255.

On Exit:

return-code
0 | Success
12 | No id specified
16 | length is 0 or >255

Comments:

You can add up to five separate custom fields; configure the number of custom fields using the ES_HSF_CFG environment variable.

A call to this routine results in a trace (or traces if the data exceeds the maximum data length for a single entry - 8 bytes for 32-bit or 16 bytes for 64-bit) being written to the local trace table. Each call in the table can be identified by using the unique id used in the call - the trace id appears as x'ffid02'.

When the trace table is dumped to the .csv report, the custom fields (CUSTOM01, CUSTOM02, etc...) are populated in the order in that the custom entries are found (up to five entries, depending on the value of ES_HSF_CFG). If multiple calls are made for the same id, the call data is concatenated in the appropriate custom field (up to a maximum of 255 bytes).

If the user trace flag is switched on, the trace (or traces) are also written to the system trace table.

Parent topic: Miscellaneous Routines
Related reference
ES_WRITE_CUSTOM_HSF
Environment variables in alphabetical order


ESUSRTRC

Allows you to write entries to the system trace table.

Syntax:

CALL "ESUSRTRC" using by reference entry-length
                      by reference entry-data

Parameters:

entry-length
Picture: pic 9(4) comp.
entry-data
Picture: pic x(n).
Maximum length: 256.

On Entry:

entry-length
Specifies the length of the trace data.
entry-data
The data to be written to the system trace table.

On Exit:

return-code
0 | Success
12 | User trace flag not set
16 | entry-length exceeds maximum

Comments:

The trace entries are only created if the CICS, User trace flag is set. You can set this flag persistently in the region's System Initialization Table (SIT), or ephemerally through the Enterprise Server Monitor and Control (ESMAC) Control page.

Parent topic: Miscellaneous Routines


JVM_LOAD_NATIVE (deprecated)

Loads a native shared library into the JVM runtime. Once the shared library is loaded, use the CALL statement to call one of its entry points, from your JVM COBOL programs.
Note: JVM_LOAD_NATIVE library routine is deprecated, and provided for backward compatibility only. We recommend that you load native shared libraries using procedure-point syntax, thereby eliminating the need to load them using this routine.

Syntax:

call "JVM_LOAD_NATIVE" using by reference myLibrary

Parameters:

myLibrary
pic x(n).

On entry:

myLibrary
The name of the native shared library (.dll or .so on most platforms), without the file extension.

On exit:

None.

Example:

The following pair of programs show group items being used to interoperate between JVM COBOL and native COBOL.

Native COBOL:

    program-id. NativeProgram as "NativeProgram".
    linkage section.
    01 pets.
       03 p1 pic xxx.
       03 p2 pic xxx.
       03 result pic x(6).
    procedure division.
       goback.
       entry "SwapStrings" using pets.
          display "p1='" p1 "' p2='" p2 "'"
          move p1 to result(4:3)
          move p2 to result(1:3)
          goback.
    end program NativeProgram.

JVM COBOL:

    program-id. JVMProgram as "JVMProgram".
    01 pets.
        03 dog pic xxx value "dog".
        03 cat pic xxx value "cat".
        03 result pic x(6).
    01 nat-ptr procedure-pointer.
    procedure division.
       set nat-ptr to entry “NativeProgram"
        display ""
        display "Calling native program"
        display "======================="
        display "Pass in 2 strings: '" dog "' & '" cat "'"
        perform reset-all
       call "SwapStrings" using pets
        display "Native program swaps strings"
        display "result = '" result "'"
        display ""
        goback.
    reset-all section.
        move spaces to result
        .
    end program.

Comments:

The myLibrary parameter must be passed as a literal; it cannot be declared in a COBOL storage section.

You cannot call a native entry point that has the same name as a JVM COBOL entry point.

You cannot load two native libraries that have the same named entry point.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines
Related concepts
Calling Native COBOL from JVM COBOL


JVM_UNSAFE_NATIVE_MEMCOPY

Copies native memory to managed memory allocated by third-party APIs, such as the Windows FormatMessage API. You cannot address managed memory except with this JVM_UNSAFE_NATIVE_MEMCOPY library routine.
Warning: When using this library routine, take great care to pass valid parameters. An invalid parameter can cause instability in your environment.

Syntax:

call “JVM_UNSAFE_NATIVE_MEMCOPY” using
   by value nativePointer
   by value memoryLength
   by value managedPointer
   returning status-code
end-call

Parameters:

nativePointer
A native-pointer.
memoryLength
The length expressed as PIC S9(9) COMP-5.
managedPointer
A pointer where native-pointer is the user typedef:
$IF JVM32 DEFINED
01 native-pointer is typedef pic x(4) comp-5.
$ELSE
01 native-pointer is typedef pic x(8) comp-5.
$END

status-code
The returned status code.

On Entry:

nativePointer
The address if the native memory.
memoryLength
The length of the native memory block.
managedPointer
The address of the managed memory block.

On Exit:

status-code
0 | success
1 | a bad length has been given

Example:

This example demonstrates how the FormatMessage API can be used from a JVM compiled COBOL program.
      $set ans85 mf defaultbyte"00" case
      $ if jvmgen set
      $ set remove"internal" remove"event"
      $end
       copy "windows.cpy".

       program-id. geterror.
       special-names.
          call-convention 74 is winapi.
       data division.
       working-storage section.

      $if jvmgen set
      $ if NOP64 set
        01 native-pointer     is typedef pic x(4) comp-5.
      $ else
        01 native-pointer     is typedef pic x(8) comp-5.
      $ end
      $else
        01 native-pointer     is typedef pointer.
      $end

       01 format-message-group.
        03 last-error                   DWORD.
        03 message-pointer              native-pointer.
        03 format-type                  DWORD.
        03 bytes-returned               DWORD.
        03 last-error-display           pic 9(2).

       local-storage section.
       01 ls-message-buffer                pic x(1024).

       linkage section.
       01 lnk-message-buffer               pic x(1024).
       procedure division.
      $if jvmgen set
           call "cob32api"
      $end

           display "First 20 system error messages"

           perform display-error varying last-error from 0 by 1
              until last-error = 20

           stop run.

       display-error.
           move 0 to format-type
           add FORMAT-MESSAGE-ALLOCATE-BUFFER to format-type
           add FORMAT-MESSAGE-FROM-SYSTEM to format-type

           call winapi FormatMessage
              using by value     format-type
                    by value     0 size 4       *> lpSource ignored
                    by value     last-error     *> error number
                    by value     0 size 4       *> LangID ignored
                    by reference message-pointer*> pointer to mess.
                    by value     0 size 4       *> min size of buffer
                    by value     0 size 4       *> arguments ignored
              returning bytes-returned
           end-call

           if bytes-returned > 0 and
                   bytes-returned < length of ls-message-buffer

      $if jvmgen set
      *> use the managed memory instead of the native memory
              set address of lnk-message-buffer to
                      address of ls-message-buffer

      *> Copy the native memory to to the managed memory
              call "JVM_UNSAFE_NATIVE_MEMCOPY" using
                 by value message-pointer
                 by value bytes-returned
                 by value address of ls-message-buffer
              end-call
      $else
              set address of lnk-message-buffer to message-pointer
      $end
              move last-error to last-error-display
              display " " last-error-display " =  "
                      lnk-message-buffer (1:bytes-returned - 2) *> remove x"ODOA"

              call winapi "LocalFree"
                using by value message-pointer
             end-call

           end-if.
Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 11

Sets the programmable COBOL switches.
Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

result
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
01 parameter
  03 switch-flag cblt-x1-compx occurs 8  *> pic x comp-x occurs 8
  03 debug-flag  cblt-x1-compx           *> pic x comp-x

On Entry:

function-code | Value 11
switch-flag | The values (0 or 1) to set in switches 0 through 7.
debug-flag | If set to 1, the ANSI Debug module is enabled.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

To update one switch without affecting the others, you should read the switches with X"91" function 12, update parameter, and then call this function.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 12

Reads the programmable COBOL switches.
Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

result
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
01 parameter
  03 switch-flag cblt-x1-compx occurs 8  *> pic x comp-x occurs 8
  03 debug-flag  cblt-x1-compx           *> pic x comp-x

On Entry:

function-code Value 12

On Exit:

result | Set to zero if the call was successful, nonzero otherwise.
switch-flag | The values of switches 0 through 7.
debug-flag | Set to 1 if the ANSI Debug module is enabled, otherwise zero.
Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 13

Sets the run-time switches

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx occurs 26 | pic x comp-x occurs 26

On Entry:

function-code | Value 13
parameter | Each byte represents one of the switch letters and each bit in a byte is the state to set the numeric switch for that letter. For example, parameter(1) bit 0 represents switch A (or A0), bit 5 of parameter(19) represents switch S5.

On Exit:

result Set to zero if the call was successful, nonzero otherwise.

Comments:

To update one switch without affecting the others, you should read the switches with Function 14, update parameter, and then call this function.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 15

Checks for the existence of the specified program.

Note: This function is not supported in JVM COBOL.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

result
Using call prototype (see Library Routines - Key) : cblt-x1-compx
Picture: pic x comp-x.
function-code
Using call prototype (see Library Routines - Key) : cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
name-len   cblt-x1-compx   *> pic x comp-x
progname   pic x(n)        *> pic x(n)

On Entry:

function-code | Value 15
name-len | The length of the name in filename.
progname | The name of the program to be looked for. This parameter must be at least 65 characters long.

On Exit:

progname | If the program is found, contains the full name.
result | Set to zero if the program was found, non-zero otherwise.

Comments:

If the program file is found, you must then call the program using the filename returned.

This call must not be used to check for the existence of data files; use CBL_CHECK_FILE_EXIST instead.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 16 (deprecated)

Shows how many of the parameters in the call statement of the calling program have been transferred to the called subprogram.

Restriction: This routine is supported for native COBOL only.
Note: This routine is deprecated, and provided for backward compatibility only. We recommend that you use CBL_GET_PROGRAM_INFO using by value 8.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

 | Using call prototype (see Key) | Picture
result | cblt-x1-compx | pic x comp-x.
function-code | cblt-x1-compx | pic x comp-x.
parameter | cblt-x1-compx | pic x comp-x.

On Entry:

function-code Value 16

On Exit:

parameter | The number of parameters.
result | Set to zero if the call was successful, nonzero otherwise.

Comments:

This function is used in the called program; for the function to work in generated code, the program must be compiled with the PARAMCOUNTCHECK directive.

This function can only be used if the program is called from a COBOL program.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"91" function 35

Performs an EXEC call (like the DOS 4B call) to the specified program file, executing it.

Note:
  • This function is not supported in JVM COBOL.
  • This function is not supported on UNIX.

Syntax:

call x"91" using result
                 function-code
                 parameter

Parameters:

result
Using call prototype (see Library Routines - Key) : cblt-x1-compx
Picture: pic x comp-x.
function-code
Using call prototype (see Library Routines - Key) : cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
name-len   cblt-x1-compx   *> pic x comp-x
progname   pic x(n)        *> pic x(n)

On Entry:

function
Value 35
name-len
The number of characters in the name of the program. If this is set to zero, whatever has been previously written to the command line is executed.
progname
The filename of the program to be executed.

On Exit:

result
Zero if the EXEC call was successful, non-zero otherwise. If the reason for failure is a non-zero return code from the executed program then that value is returned. For other error conditions a value of 255 is returned. However, in .NET, if the target program does not exist, no error is returned.

Comments:

To execute a command line instead of just a named program, set name-len to zero, and set the command line using the DISPLAY...UPON COMMAND-LINE syntax.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines
Related information
Library Routines - Key
Alphabetical List of Library Routines


X"91" function 69 (deprecated)

Searches a directory for a given file specification.

Note:
  • This function is deprecated, and provided for backward compatibility only. We recommend that you use the CBL_DIR_SCAN routines.
  • This function is not supported in JVM COBOL.

Syntax:

call X"91" using result
                 function-code
                 parameter

Parameters:

result
Group containing:
01 result
  03 f-error    cblt-x1-compx   *> pic x comp-x.
  03 f-handle   cblt-x2-compx   *> pic x(2) comp-x.
  03 f-attrout  cblt-x1-compx   *> pic x comp-x.
  03 f-time     cblt-x2-compx   *> pic x(2) comp-x.
  03 f-date     cblt-x2-compx   *> pic x(2) comp-x.
  03 f-size     cblt-x4-compx   *> pic x(4) comp-x.
  03 f-fileout  pic x(n)        *> pic x(n)
function-code
Call prototype: cblt-x1-compx
Picture: pic x comp-x.
parameter
Group containing:
01 parameter
  03 f-action   cblt-x1-compx   *> pic x comp-x.
  03 f-attrin   cblt-x1-compx   *> pic x comp-x.
  03 f-filein   pic x(m)        *> pic x(m)

On Entry:

function-code
Contains 69
f-action
Defines the action to perform:
0 | Find the first matching file
1 | Find the next matching file
2 | Terminate the search early
3 | Find one matching file
f-attrin
Attribute byte. All normal files, plus those with the attributes specified by setting this parameter, are to be included. To specify attributes, set the bits as follows:
bit 7 | Unused
bit 6 | Unused
bit 5 | Archived file
bit 4 | Subdirectory
bit 3 | Unused
bit 2 | System file
bit 1 | Hidden file
bit 0 | Read-only file
f-filein
The space-terminated filename specification of the file(s) required. This can contain a drive/directory or any wildcard characters.

On Exit:

f-error
Contains a status of the result:
0 | Success/file found
1 | No more files
2 | Error
f-handle
The find handle. This field is set by the find-first function (see f-action above) and should not be altered until the corresponding terminate search has been done.
f-attrout
Attribute byte of file found:
bit 7 | Unused
bit 6 | Unused
bit 5 | Archived file
bit 4 | Subdirectory
bit 3 | Volume label
bit 2 | System file
bit 1 | Hidden file
bit 0 | Read-only file
f-time
Time file was created, in DOS format:
bits 15-11 | Hour, 0-23
bits 10-5 | Minute, 0-59
bits 4-0 | Bi-second, 0-29
f-date
Date file was created, in DOS format:
bits 15-9 | Year, 0-119 (1980-2099)
bits 8-5 | Month, 1-12
bits 4-0 | Day, 1-31
f-size
The size of the file in bytes.
f-fileout
The name of the file found, space-terminated.

Comments:

To find a single file, use the find-one function.

To find several files, use the find-first function and then use the find-next function repeatedly. When there are no more matching files, find-next returns with 1 in f-error. If you do not keep calling find-next until this happens, you must finish by calling the terminate-search function.

The f-handle field should be set to zero before you execute the find-first or find-one function. After that, if you are using the first/next/terminate sequence this field should not be changed until after the terminate search. If you are using the find-one function this field is automatically reset to 0 after that call.

If at any time f-error returns 1 or 2, a terminate search has been carried out automatically, and you should not execute the terminate-search function.

This routine cannot be used to check the existence of a network share resource, such as \\server1\share1, but it can be used to locate files or directories on that share, such as \\server1\share1\*.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


X"E5"

Sounds the bell.
Restriction: This routine is not currently supported in COBOL for JVM.

Syntax:

call x"E5"

Parameters:

None

Comments:

The duration and pitch of the bell depend on the environment.

Parent topic: Miscellaneous Routines
Parent topic: Alphabetical List of Library Routines


Alphabetical List of Library Routines

  • _CODESET
    Converts a string between the EBCDIC and ASCII character sets.
  • CBL_ABORT_RUN_UNIT
    Aborts the current run unit irrespective of the state of existing threads.
  • CBL_ALLOC_DYN_MEM
    Dynamically allocates memory, and can associate it with the calling program.
  • CBL_ALLOC_MEM
    Dynamically allocates memory, and can associate allocated heap data with a thread and/or the calling program.
  • CBL_ALLOC_SHMEM
    Dynamically allocates shared memory.
  • CBL_ALLOC_THREAD_MEM
    Allocates thread-specific heap memory.
  • CBL_AND
    Does a logical AND between the bits of two data items.
  • CBL_CANCEL
    Cancels a COBOL program.
  • CBL_CANCEL_PROC
    Provides control over program cancels.
  • CBL_CFGREAD_DYNFH
    The CBL_CFGREAD_DYNFH option determines whether the File Handler should reread its configuration file for configurable custom file handlers.
  • CBL_CFGREAD_EXTFH
    Forces the File Handler to reread its configuration file.
  • CBL_CHANGE_DIR
    Changes the current directory.
  • CBL_CHECK_FILE_EXIST
    Checks whether a file exists and if it does, returns details of when the file was last modified.
  • CBL_CLEAR_SCR
    Clears the whole screen to a specified character and attribute.
  • CBL_CLOSE_FILE
    Closes a file opened for byte-stream operations.
  • CBL_CLOSE_VFILE
    Closes a heap.
  • CBL_CODESET_SET_MAPPING
    Enables you to change the codeset in effect.
  • CBL_COPY_FILE
    Copies a file.
  • CBL_CREATE_CORE
    Enables a COBOL program to invoke a core dump on demand (that is, without encountering a run-time error).
  • CBL_CREATE_DIR
    Creates a subdirectory.
  • CBL_CREATE_FILE
    Creates a new file and leaves it open for byte-stream operations.
  • CBL_CTF_COMP_PROPERTY_GET
    Returns a named property value for a component.
  • CBL_CTF_COMP_PROPERTY_SET
    Specifies a value for a component's property.
  • CBL_CTF_DEST
    Specifies an output destination by associating (or disassociating) an emitter with (or from) a component or the default emitter list.
  • CBL_CTF_EMITTER_PROPERTY_GET
    Returns a named property value for an emitter.
  • CBL_CTF_EMITTER_PROPERTY_SET
    Sets a named property value for an emitter.
  • CBL_CTF_LEVEL
    Specifies the trace level to be used for a specific component, or the default trace level if a component identifier is not specified.
  • CBL_CTF_TRACE
    Outputs an event to one or more output destinations.
  • CBL_CTF_TRACER_GET
    Returns a tracer handle that can be passed to other tracing routines to identify a component.
  • CBL_CTF_TRACER_LEVEL_GET
    Returns a tracer's current threshold trace level.
  • CBL_CTF_TRACER_NOTIFY
    Installs or uninstalls a tracer configuration callback function.
  • CBL_CULL_RUN_UNITS
    Clears any dead run units.
  • CBL_DEBUGBREAK
    Enables a COBOL program to invoke Animator.
  • CBL_DEBUG_START
    Enables a COBOL program to initiate advanced remote debugging, live recording, or cross-session debugging.
  • CBL_DEBUG_STOP
    Enables a COBOL program to stop or suspend animation, or terminate a live recording.
  • CBL_DELETE_DIR
    Deletes a directory. The directory is deleted only if it is empty.
  • CBL_DELETE_FILE
    Deletes a file.
  • CBL_DIR_SCAN_END
    Terminates a search operation.
  • CBL_DIR_SCAN_READ
    Searches for the next entry in the file system using a search handle returned by a previous CBL_DIR_SCAN_START.
  • CBL_DIR_SCAN_START
    Initializes a search for a file or directory.
  • CBL_EQ
    Does a logical EQUIVALENCE between the bits of two data items.
  • CBL_ERROR_PROC
    Installs or removes an error procedure to be invoked automatically when a run-time system error occurs.
  • CBL_EVENT_CLEAR
    Clears the specified event.
  • CBL_EVENT_CLOSE
    Closes the supplied event handle.
  • CBL_EVENT_OPEN_INTRA
    Creates an intra-process event.
  • CBL_EVENT_POST
    Posts the specified event.
  • CBL_EVENT_WAIT
    Waits for the event to be posted.
  • CBL_EXEC_RUN_UNIT
    Creates a synchronous or asynchronous run unit.
  • CBL_EXIT_PROC
    Installs or removes a closedown procedure to be invoked automatically when the application terminates.
  • CBL_FILENAME_CONVERT
    Converts a filename between space-terminated and null-terminated format.
  • CBL_FILENAME_MAX_LENGTH
    Returns the maximum size of a filename that the run-time system and the current operating system can handle. This size does not include any terminators (null or space).
  • CBL_FLUSH_FILE
    Ensures all file buffers for a file are written to disk. This includes both run-time system buffers and operating system buffers.
  • CBL_FREE_DYN_MEM
    Frees dynamically allocated memory allocated by the CBL_ALLOC_DYN_MEM routine.
  • CBL_FREE_MEM
    Frees dynamically allocated memory.
  • CBL_FREE_SHMEM
    Frees dynamically allocated shared memory.
  • CBL_FREE_THREAD_MEM
    Frees dynamically allocated thread-specific heap memory.
  • CBL_GET_CSR_POS
    Returns the cursor position.
  • CBL_GET_CURRENT_DIR
    Returns the current directory.
  • CBL_GET_EXIT_INFO
    Enables an application to determine under what circumstances an exit procedure has been invoked.
  • CBL_GET_KBD_STATUS
    Checks whether there is a character waiting to be read from the keyboard.
  • CBL_GET_OS_INFO
    Returns information about the operating system environment.
  • CBL_GET_PROGRAM_INFO
    Returns information for a named program, or a program in the current call stack.
  • CBL_GET_RECORD_LOCK
    Obtains a record lock on a file.
  • CBL_GET_SCR_GRAPHICS
    Returns operating system independent codes for graphics characters.
  • CBL_GET_SCR_LINE_DRAW
    Returns a table of values defining the character values required by the run-time system screen output routines to correctly display given line drawing characters.
  • CBL_GET_SCR_SIZE
    Returns information about the size of the screen.
  • CBL_GET_SHMEM_PTR
    Reads a named value.
  • CBL_IMP
    Does a logical IMPLIES between the bits of two data items.
  • CBL_JOIN_FILENAME
    Forms a filename by joining together its component parts; that is, the pathname, basename and extension.
  • CBL_LOCATE_FILE
    This routine has two uses. It can be used to expand an environment variable in a file specification, where the environment variable contains a list of several paths. It can also determine whether an OPEN INPUT statement using a particular file specification finds the file in a library file or as a separate disk file.
  • CBL_MANAGED_SESSION_GET_USERDATA
    Retrieves user data saved in the current RunUnit.
  • CBL_MANAGED_SESSION_SET_USERDATA
    Sets user data in the current RunUnit.
  • CBL_MEM_STRATEGY
    Changes the memory strategy for an application dynamically.
  • CBL_MEM_VALIDATE
    Validates memory allocations, monitored freed memory, and, if the operating system supports it, compacts memory heaps.
  • CBL_MONITOR_BROWSE
    Acquires the specified monitor's browse capability for the current thread, blocking until that capability can be acquired.
  • CBL_MONITOR_BROWSE_TO_READ
    Converts monitor browse capability already acquired by the current thread to read capability.
  • CBL_MONITOR_BROWSE_TO_WRITE
    Converts monitor browse capability already acquired by the current thread to write capability, blocking until this can be achieved.
  • CBL_MONITOR_CLOSE
    Closes the supplied monitor handle.
  • CBL_MONITOR_OPEN_INTRA
    Creates a monitor synchronization object for thread synchronization within one process.
  • CBL_MONITOR_READ
    Acquires the specified monitor's read capability for the current thread/process, blocking until that capability can be acquired.
  • CBL_MONITOR_RELEASE
    Releases any lock currently applied to the specified monitor by CBL_MONITOR_WRITE, CBL_MONITOR_READ or CBL_MONITOR_BROWSE.
  • CBL_MONITOR_UNBROWSE
    Releases the monitor's browse capability that was acquired by CBL_MONITOR_BROWSE or CBL_MONITOR_WRITE_TO_BROWSE.
  • CBL_MONITOR_UNREAD
    Releases the monitor's read capability that was acquired by CBL_MONITOR_READ or CBL_MONITOR_BROWSE_TO_READ.
  • CBL_MONITOR_UNWRITE
    Releases the monitor's write capability that was acquired by CBL_MONITOR_WRITE or CBL_MONITOR_BROWSE_TO_WRITE.
  • CBL_MONITOR_WRITE
    Acquires the specified monitor's write capability for the current thread, blocking until that capability can be acquired.
  • CBL_MONITOR_WRITE_TO_BROWSE
    Converts monitor write capability already acquired by the current thread to browse capability.
  • CBL_MUTEX_ACQUIRE
    Acquires a mutex for the specified thread.
  • CBL_MUTEX_CLOSE
    Closes the specified mutex.
  • CBL_MUTEX_OPEN_INTRA
    Create an intra-process mutex.
  • CBL_MUTEX_RELEASE
    Releases the specified mutex.
  • CBL_NLS_CLOSE_MSG_FILE
    Closes a National Locale Support (NLS) message file.
  • CBL_NLS_COMPARE
    Compares two strings.
  • CBL_NLS_INFO
    Gets/sets national language information.
  • CBL_NLS_OPEN_MSG_FILE
    Open a National Locale Support (NLS) message file.
  • CBL_NLS_READ_MSG
    Reads a message from a National Locale Support (NLS) message file.
  • CBL_NOT
    Does a logical NOT on the bits of a data item.
  • CBL_OPEN_FILE
    Opens an existing file for byte-stream operations.
  • CBL_OPEN_VFILE
    Opens a heap.
  • CBL_OR
    Does a logical OR between the bits of two data items.
  • CBL_PUT_SHMEM_PTR
    Creates or updates a named value.
  • CBL_READ_FILE
    Reads bytes from a file.
  • CBL_READ_KBD_CHAR
    Waits until a character is typed and then reads it with no echo.
  • CBL_READ_SCR_ATTRS
    Reads a string of attributes from the screen.
  • CBL_READ_SCR_CHARS
    Reads a string of characters from the screen.
  • CBL_READ_SCR_CHATTRS
    Reads a string of characters and their attributes from the screen.
  • CBL_READ_VFILE
    Reads bytes from a heap.
  • CBL_RENAME_FILE
    Changes the name of a file.
  • CBL_RUNTIME_ERROR
    Forces the application to terminate with a run-time error condition.
  • CBL_SCR_ALLOCATE_COLOR
    Finds an entry in the colormap for each of one or more given RGB values.
  • CBL_SCR_ALLOCATE_VC_COLOR
    Sets one or more specified virtual colormap entries to the RGB values supplied.
  • CBL_SCR_CREATE_VC
    Creates a virtual colormap and copies the contents of the system colormap to it.
  • CBL_SCR_DESTROY_VC
    Destroys a virtual colormap, causing the run-time system to revert to using the system colormap.
  • CBL_SCR_GET_ATTR_INFO
    Returns information about the attribute system for the environment.
  • CBL_SCR_GET_ATTRIBUTES
    Gets the character attribute code, and foreground and background colormap indexes for one or more entries in the attribute table.
  • CBL_SCR_NAME_TO_RGB
    Converts a single named color into an RGB value.
  • CBL_SCR_QUERY_COLORMAP
    Returns the RGB value for one or more colormap entries.
  • CBL_SCR_RESTORE
    Restores an area of the character-mode screen previously saved with a call to the CBL_SCR_SAVE call-by-name routine.
  • CBL_SCR_RESTORE_ATTRIBUTES
    Restores the attribute table to the saved values that are associated with the specified buffer handle.
  • CBL_SCR_SAVE
    Saves away an area of the screen (text and attributes) for subsequent restoration.
  • CBL_SCR_SAVE_ATTRIBUTES
    Saves the current settings of the attribute table.
  • CBL_SCR_SET_ATTRIBUTES
    Defines the character attribute, and foreground and background colormap indexes associated with each of one or more COBOL attribute values (attribute table indexes).
  • CBL_SCR_SET_PC_ATTRIBUTES
    Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.
  • CBL_SEMAPHORE_ACQUIRE
    Acquires one of the resources represented by the semaphore by decrementing the associated count.
  • CBL_SEMAPHORE_CLOSE
    Closes the specified semaphore.
  • CBL_SEMAPHORE_OPEN_INTRA
    Creates an intra-process semaphore.
  • CBL_SEMAPHORE_RELEASE
    Releases one of the resources represented by the semaphore by incrementing the associated count.
  • CBL_SET_CSR_POS
    Moves the cursor.
  • CBL_SPLIT_FILENAME
    Splits a filename into its component parts; that is, the pathname, basename and extension.
  • CBL_STRING_CONVERT
    Converts a string from one character encoding to another.
  • CBL_SUBSYSTEM
    Declares or deallocates subsystems.
  • CBL_SRV_SERVICE_FLAGS_GET
    Enables a program running within a COBOL container as part of a service to determine the service's execution characteristics.
  • CBL_SRV_SERVICE_FLAGS_SET
    Enables a program running within a COBOL container as part of a service to set one or more the service's execution characteristics.
  • CBL_SWAP_SCR_CHATTRS
    Swaps a string of characters and their attributes with a string from the screen.
  • CBL_TEST_RECORD_LOCK
    Tests for an existing record lock on a file.
  • CBL_THREAD_CREATE
    Creates a thread from a named entry point.
  • CBL_THREAD_CREATE_P
    Creates a thread from a procedure pointer.
  • CBL_THREAD_DETACH
    Frees thread resources when the thread terminates.
  • CBL_THREAD_EXIT
    Terminates the current thread.
  • CBL_THREAD_IDDATA_ALLOC
    Allocates an id-data area for the current thread.
  • CBL_THREAD_IDDATA_GET
    Returns a pointer to the id-data area for the specified thread.
  • CBL_THREAD_KILL
    Kills the specified thread, terminating it abnormally and detaching all resources associated with it.
  • CBL_THREAD_LIST_END
    Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_NEXT to obtain a list of all currently existing threads that the run-time system knows about. It is required to terminate a CBL_THREAD_LIST_START.
  • CBL_THREAD_LIST_NEXT
    Used in conjunction with CBL_THREAD_LIST_START and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about. The CBL_THREAD_LIST_NEXT call takes returns the next item in the list of threads.
  • CBL_THREAD_LIST_START
    Used in conjunction with CBL_THREAD_LIST_NEXT and CBL_THREAD_LIST_END to obtain a list of all currently existing threads that the run-time system knows about.
  • CBL_THREAD_LOCK
    Locks most functions of the thread-handling routines.
  • CBL_THREAD_PROG_LOCK
    With CBL_THREAD_PROG_UNLOCK, provides a single pre-initialized synchronization object per calling COBOL program
  • CBL_THREAD_PROG_UNLOCK
    With CBL_THREAD_PROG_LOCK, provides a single pre-initialized synchronization object per calling COBOL program
  • CBL_THREAD_RESUME
    Resumes a thread that was or will be suspended by CBL_THREAD_SUSPEND.
  • CBL_THREAD_SELF
    Stores the thread identifier of the current thread.
  • CBL_THREAD_SLEEP
    Causes the calling thread to give up control to the processor for the given number of milliseconds.
  • CBL_THREAD_SUSPEND
    Suspends the current thread.
  • CBL_THREAD_UNLOCK
    Unlocks most functions of the thread handling routines.
  • CBL_THREAD_WAIT
    Waits for completion of the specified non-detached thread, or returns immediately if the thread has already completed.
  • CBL_THREAD_YIELD
    Yields the rest of the current thread's timeslice.
  • CBL_TOLOWER
    Converts a string of letters to lower case.
  • CBL_TOUPPER
    Converts a string of letters to upper case.
  • CBL_TSTORE_CLOSE
    Closes a handle returned by CBL_TSTORE_CREATE.
  • CBL_TSTORE_CREATE
    Creates a handle for and specifies the size of a thread-storage area. These values can be used in subsequent calls to CBL_TSTORE_GET. The new thread-storage area is initialized to zeroes.
  • CBL_TSTORE_GET
    Gets a pointer to the thread-specific memory specified by CBL_TSTORE_CREATE.
  • CBL_WRITE_FILE
    Writes bytes to a file.
  • CBL_WRITE_SCR_ATTRS
    Writes a string of attributes to the screen.
  • CBL_WRITE_SCR_CHARS
    Writes a string of characters to the screen.
  • CBL_WRITE_SCR_CHARS_ATTR
    Writes a string of characters to the screen, giving them all the same attribute.
  • CBL_WRITE_SCR_CHATTRS
    Writes a string of characters and their attributes to the screen.
  • CBL_WRITE_SCR_N_ATTR
    Writes a specified attribute to a string of positions on the screen.
  • CBL_WRITE_SCR_N_CHAR
    Writes a specified character to a string of positions on the screen.
  • CBL_WRITE_SCR_N_CHATTR
    Writes a specified character and attribute to a string of positions on the screen.
  • CBL_WRITE_SCR_TTY
    Writes a string of characters to the screen starting at the current position and scrolling.
  • CBL_WRITE_VFILE
    Writes bytes to a heap.
  • CBL_XOR
    Does a logical XOR between the bits of two data items.
  • CBL_YIELD_RUN_UNIT
    Yields the remainder of a run-unit's time-slice.
  • ES_WRITE_CUSTOM_HSF
    Writes data to a custom field in the HSF record viewable from the generated .csv file.
  • JVM_LOAD_NATIVE (deprecated)
    Loads a native shared library into the JVM runtime. Once the shared library is loaded, use the CALL statement to call one of its entry points, from your JVM COBOL programs.
  • JVM_UNSAFE_NATIVE_MEMCOPY
    Copies native memory to managed memory allocated by third-party APIs, such as the Windows FormatMessage API. You cannot address managed memory except with this JVM_UNSAFE_NATIVE_MEMCOPY library routine.
  • MF_CLIENT_STATE_ALLOCATE
    Allocates a client identifier.
  • MF_CLIENT_STATE_DELETE
    Deletes an existing client identifier and its associated client information.
  • MF_CLIENT_STATE_EXPIRY
    Returns a date string for use in the cookie expiry field.
  • MF_CLIENT_STATE_FILE
    Specifies the file to be used on the server to store state information.
  • MF_CLIENT_STATE_PURGE
    Deletes all client information older than the number of days specified.
  • MF_CLIENT_STATE_RESTORE
    Restores a previously saved or allocated record which matches the client identifier.
  • MF_CLIENT_STATE_SAVE
    Updates the information in the state file.
  • mFFH
    Initializes the File Handler.
  • MFFH_MODIFY_DISABLE
    Disables all File Handler trace modification set by previous MFFH_MODIFY_TRACE calls.
  • MFFH_MODIFY_TRACE
    Modifies some FCD fields, to save directly accessing the FCD. You can use this call whether you are issuing standard COBOL I/O statements or calling the File Handler explicitly using the API.
  • SYSTEM
    Executes an arbitrary operating system command.
  • X"91" function 11
    Sets the programmable COBOL switches.
  • X"91" function 12
    Reads the programmable COBOL switches.
  • X"91" function 13
    Sets the run-time switches
  • X"91" function 15
    Checks for the existence of the specified program.
  • X"91" function 16 (deprecated)
    Shows how many of the parameters in the call statement of the calling program have been transferred to the called subprogram.
  • X"91" function 35
    Performs an EXEC call (like the DOS 4B call) to the specified program file, executing it.
  • X"91" function 46
    Enables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.
  • X"91" function 47
    Disables insertion of a null character x"00" before data characters whose value is less than x"20" in line sequential files.
  • X"91" function 48
    Enables insertion of tab characters in line sequential files.
  • X"91" function 49
    Disables insertion of tab characters in line sequential files.
  • X"91" function 69 (deprecated)
    Searches a directory for a given file specification.
  • X"A7" functions 6 and 7
    Reads and sets user attribute.
  • X"A7" function 16
    Turns the user attribute on or off.
  • X"A7" function 17
    Sets the cursor type.
  • X"A7" function 18
    Makes console I/O redirectable.
  • X"A7" functions 20 and 21
    Reads and sets system attributes.
  • X"A7" function 25
    Returns the current screen type as recognized by the run-time system.
  • X"AF" function 1
    Sets various configurable features of Adis, including enabling or disabling individual user function, Adis or data keys, or a series of consecutive keys at run-time.
  • X"AF" function 18
    Displays a character to the screen at the current cursor position.
  • X"AF" function 22
    Sounds the terminal alarm.
  • X"AF" function 26
    Gets a character from the keyboard.
  • X"AF" Function 81
    Enables SCREEN SECTION ACCEPT and DISPLAY statements to inherit Keisen attributes written by preceding CBL_ calls.
  • X"B0" function 0
    Creates a function-key table.
  • X"B0" function 2
    Tests the status of the Shift, Alt, Ctrl and Lock keys.
  • X"B0" function 4
    Disables keyboard interrupts (Ctrl+Break).
  • X"E5"
    Sounds the bell.
  • X"F5"
    Unpacks the bits in a byte into eight bytes.
  • X"F4"
    Packs the least significant bits in eight bytes into a single byte.
Parent topic: Library Routines


Restrictions, Compiler Limits, and System Limits

There are a number of areas that need care when you use them, as well as various limits imposed by the Compiler, the Run-time system, and your hardware and operating system.

The Compiler and the intermediate code that it produces are environment independent. The limits associated with the Compiler are environment independent also and cannot be exceeded in any environment. Run-time, operating system and hardware limits might also exist which might well be lower than those of the Compiler.

  • ALTER and ACCEPT Statement Restrictions
  • Command Line Length
  • Size and Number of Data Items
  • Numbers of ELSE Clauses
  • ENTRY Statement Restrictions
  • Filename Restrictions
  • Floating-point Numbers
  • Hardware or Operating System Limits
  • Maximum Core Heap Size
  • Size of Names, Literals and PICTURE Character Strings
  • Nested Statement Restrictions
  • Number of DETAIL Groups
  • Restrictions on the Size of Numbers
  • Number of PERFORM Ranges
  • Program Source File Limits
  • Size of Programs, Divisions and Sections
  • Number of Files for Sorting or Merging
  • Table Dimension Limits
  • Number of USE Statements
  • Number of Parameters in a USING Phrase
  • Managed COBOL Restrictions
    Most COBOL functionality is supported in managed code. However, there are some restrictions.
Parent topic: General Reference


ALTER and ACCEPT Statement Restrictions

Exercise care when using the following statements:

  • ALTER

    In a segmented program, you must not alter code outside the current segment. However, if you do this, the Compiler does not report an error. The Compiler alters the code when the segment is entered.

  • ACCEPT identifier FROM LINE NUMBER

    This syntax is only suitable for use with operating systems that typically support many terminal lines. On Windows, it always returns zero.

Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The ACCEPT Statement
The ALTER Statement


Command Line Length

With COBOL the maximum length of a command line is determined by the operating system.

Some Micro Focus tools limit the command line length to 128 characters. However, user applications should be able to use the operating system limit.

Parent topic: Restrictions, Compiler Limits, and System Limits
Related information
Hardware or Operating System Limits


Size and Number of Data Items

The following table shows the maximum size and number of data items.

Data Item | Maximum Size or Number
Alphanumeric/Group | 2GB-1 (Native COBOL), 4GB (Managed COBOL)
Alphanumeric Edited/ Numeric Edited | Can consist of 32 parts, each of which can contain up to 16 occurrences of a single edited character type subject to a total size of 512 bytes
Numeric | All significant digits must be within 18, 31 or 38 digits of the decimal point, depending on your COBOL environment: ANSI'85: 18 significant digits ISO2000: 31 significant digits Micro Focus: 38 significant digits
COMP/COMP-5 format | 8 bytes
EXTERNAL data item | No specifiable limit
File record size | 62KB
ACCEPT FROM CONSOLE | Limits (if any) are imposed by the operating system.
Full screen DISPLAY/ACCEPT | One screen less one character (the last character position on the screen is not usable)
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The File Control Entry
File Description Entry Skeleton
Data Description Entry Skeleton
Screen Section Entry Skeleton
The ACCEPT Statement
The ALTER Statement
The EXTERNAL Clause
The USAGE Clause
The USAGE Clause in the Screen Section


Numbers of ELSE Clauses

If your program contains IF statements with many ELSE clauses, it might fail to compile. You can get round this problem by increasing the size of the mian stack using the COBMAINSTACK environment variable.

This applies to UNIX systems only.

Parent topic: Restrictions, Compiler Limits, and System Limits


ENTRY Statement Restrictions

Entry points defined using the ENTRY statement can be accessed only after the main entry point (identified by Program-Id) has been called, unless the MFENTMAP facility has been used.

A nested program cannot contain ENTRY statements.

An entry point is an alternative route into a program; an entry point is not treated as a separate program.

All program entry point names are truncated to 127 bytes (so the first 127 bytes of the entry name must be unique).

Parent topic: Restrictions, Compiler Limits, and System Limits


Filename Restrictions

A file is identified in a COBOL program by a filename which is a user-defined word. Outside the COBOL system it is identified by a filename which must be in an external, operating-system format. There are four components:

  • A drive
  • A path
  • A base-name
  • An extension

The maximum length of the filename is 1023 characters.

COBOL imposes no other limits, but in order for the operating system to handle the filename correctly, any operating system limits must be observed when the program is run.

Parent topic: Restrictions, Compiler Limits, and System Limits


Floating-point Numbers

This COBOL system provides IEEE floating-point support. This is fully compatible with the various languages supplied by Microsoft, including Microsoft Visual C++ V6.0.

Floating-point values must be in the range:

For COMP-1 data, | 8.43E-37 | through | 3.37E38
 | -8.43E-37 | through | -3.37E38
For COMP-2 data, | 4.19E-307 | through | 1.67E308
 | -4.19E-307 | through | -1.67E308

Note that although the above ranges are supported internally, this COBOL system supports only 2 digit exponents, and the range is effectively:

For COMP-2 data, | 4.19E-99 | through | 1.67E99
 | -4.19E-99 | through | -1.67E99

The accuracy of floating-point values is:

For COMP-1 data (4 bytes) | 6-7 significant digits
For COMP-2 data (8 bytes) | 15-16 significant digits
For literals, floating-point values must be in the range:
  • 0.54E-78 through 0.72E+76
  • -0.54E-78 through -0.72E+76

Passing floating-point (COMP-1 and COMP-2) items by value between COBOL and non-COBOL programs is not supported under UNIX. The following statements give undefined behavior if data1 is a floating-point item.

In a COBOL program calling a non-COBOL program:

CALL "program" USING BY VALUE data1.
CALL "program" RETURNING data1
In a COBOL program called from a non-COBOL program:

PROCEDURE DIVISION USING BY VALUE data1.
ENTRY "entry" USING BY VALUE data1.
EXIT PROGRAM RETURNING data1.
GOBACK RETURNING data1.
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
Data Description Entry Skeleton
The USAGE Clause


Hardware or Operating System Limits

Operating system or hardware configurations and parameter settings directly constrain a COBOL application. Check your operating system and hardware for any limits. You might need to consider the following:

Item | Limit
Environment variables | Limited to a maximum of 64 Kilobytes (or the machine's free space, whichever is smaller) of written environment variables at any one time during the run of an application.
Record locks | Operating system dependent
File locks | Operating system dependent
CALL nesting | Limited by stack space allocated by the operating system
Length of contents of DD_ environment variables | Up to the maximum operating system size for each path
Total data and procedure size | Limited by available free memory
Simultaneously loaded subprograms | Limited by available free memory
File and record sizes | Limited by operating system environment
Files open simultaneously | Limited by operating system environment.
Filename size and format | Operating system dependent
Index key size and number | Might be limited if a non-standard file handler is used
Sort key size and number | Might be limited if a non-standard SORT support routine is used
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The File Control Entry
The CALL Statement
The I-O-Control Paragraph
The SORT Statement
Related information
File Handling - Run-time Limits
File Handling - COBOL Compiler Limits


Maximum Core Heap Size

The maximum core heap size is limited only by disk space.

Parent topic: Restrictions, Compiler Limits, and System Limits


Size of Names, Literals and PICTURE Character Strings

Language elements are limited to the following sizes:

Language Element | Maximum Size
Alphanumeric literal values | 8192 bytes
PICTURE character string | 30 characters
PICTURE replication (for example, n in PIC X(n)) | 4GB
Program-Id name | 127 bytes
Entry point names | 127 bytes
Programmer defined words | 127 bytes
External filenames (for program source and object files, copybooks, data files) | 265 characters
Dynamically loadable program names | 265 characters
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The Special-Names Paragraph
Data Description Entry Skeleton
The PICTURE Clause
Screen Section Entry Skeleton
The PICTURE Clause in the Screen Section
Related information
Filename Restrictions
Calling Entry Points in Subprograms


Nested Statement Restrictions

Type of Nested Statement | No of Levels
PERFORM statements:
- intermediate code | 100
- generated code | depends on the amount of memory allocated by the operating system
- debugging | 254. If your program exceeds this level, Debugger will only Step, even if Zoom mode is specified.
IF statements (compiled code only)

Limited by:

  • the amount of stack space available when compiling the program
  • the run-time system to 255
CALL statements | No specifiable limit. However, this is limited by the stack space allocated by the operating system.
Parent topic: Restrictions, Compiler Limits, and System Limits
Related information
Programming Tips


Number of DETAIL Groups

The maximum number of DETAIL groups in a report is 254.

Parent topic: Restrictions, Compiler Limits, and System Limits


Restrictions on the Size of Numbers

According to the ANSI standard, numbers are limited to 18 significant decimal digits. All significant digits must be within 18 digits of the decimal point.

Micro Focus COBOL gives an ON SIZE ERROR if either of the following conditions occurs:

  • A multiplication or division gives a result which is greater than 36 digits
  • An addition or subtraction gives a result which is greater than 37 digits
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The Special-Names Paragraph
The File Control Entry
The I-O-Control Paragraph
Data Description Entry Skeleton
The OCCURS Clause
The ADD Statement
The CALL Statement
The DIVIDE Statement
The ENTRY Statement
The EXIT Statement
The GOBACK Statement
The INVOKE Statement
The MERGE Statement
The MULTIPLY Statement
The SORT Statement


Number of PERFORM Ranges

The maximum number of distinct PERFORM ranges in a program is 65535 .

This limit doesn't apply to .NET programs.

Parent topic: Restrictions, Compiler Limits, and System Limits


Program Source File Limits

The following limits apply to program source files:

Source File Item | Number of Items or Size of Item
Source lines | 999,999
Data and procedure-names | 64,000
Host variables | 8,000 or database system limit if lower
Literal values | No limit
Words in COPY pseudo-text | 65,000
BY clauses in a COPY REPLACING statement | 65,000
Actual fixed format line | 80 bytes
Effective fixed format line | 72 bytes
Free format line | 160 bytes
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The COPY Statement


Size of Programs, Divisions and Sections

The following table shows the maximum size of program divisions and sections.

Object | Maximum Size
Total | No limit
Data Division | 2GB-1 (Native COBOL), 4GB (Managed COBOL)
Local-Storage Section | Platform specific
Procedure Division | 16MB per segment
Number of sections, paragraphs and labels in Procedure Division | 65535 (64KB)
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
Language Fundamentals
Procedure Division General Description
General Description (Data Division)
Local-Storage Section


Number of Files for Sorting or Merging

The maximum number of files in a SORT filename GIVING or MERGE filename GIVING phrase is 128.

Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The SORT Statement
The MERGE Statement
The File Control Entry
The I-O-Control Paragraph
The PROCEDURE DIVISION Header
The ADD Statement
The CALL Statement
The DIVIDE Statement
The ENTRY Statement
The EXIT Statement
The GOBACK Statement
The INVOKE Statement
The MULTIPLY Statement
Related information
Mixed Language Programming
Passing Parameters to a Called Program
Optimizing Parameter Handling


Table Dimension Limits

Table Element | Limit
Total size | No limit
Nesting of OCCURS clause | No limit
In Screen Section | No specifiable limit
Number of subscripts | 16
OCCURS in Screen Section | Limited by the number of fields and/or the levels of occurrence. It is not possible to give an actual limit, but exceeding the limit will result in an error when you compile your program.
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
Data Description Entry Skeleton
The OCCURS Clause
Screen Section Entry Skeleton
The OCCURS Clause in the Screen Section
General Description (Data Division)
The BLANK Clause
The DISPLAY Statement


Number of USE Statements

The maximum number of USE statements in a program is 250.

Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The USE Statement
General Description (Data Division)
The USE BEFORE REPORTING Statement


Number of Parameters in a USING Phrase

The following maximum numbers of parameters are permitted in each type of USING phrase:

Statement with USING Phrase | Maximum Parameters
CALL statement | 65535
PROCEDURE DIVISION header | 65535
ENTRY statement | 65535
CALL prototype | 40
Parent topic: Restrictions, Compiler Limits, and System Limits
Related reference
The PROCEDURE DIVISION Header
The CALL Statement
The ENTRY Statement
The MERGE Statement
The SET Statement
The SORT Statement
The USE Statement
The XML PARSE Statement
Related information
Mixed Language Programming
Passing Parameters to a Called Program
Optimizing Parameter Handling


Managed COBOL Restrictions

Most COBOL functionality is supported in managed code. However, there are some restrictions.

  • COBOL Syntax Restrictions in Managed COBOL
    There is a range of syntax designed specifically for managed COBOL. In addition, the native COBOL syntax is supported in managed COBOL, with a few exceptions. Also there are some words are now reserved.
  • Compiler Directives Restrictions in Managed COBOL
    Most Compiler directives are supported for managed COBOL, in addition to those directives designed specifically for compiling managed code. There are a few native COBOL Compiler directives that are not supported in managed COBOL.
  • File Handling Restrictions in Managed COBOL
    Managed COBOL supports virtually all file handling functionality. However, there are one or two features that are not supported.
  • COBOL Services as Java Interfaces and Web Services
    Any COBOL service, such as a Java interface or a Web Service, that you created using the Interface Mapping Toolkit can continue to run under COBOL Server.
  • Mixed-language Implications in Managed COBOL
    Managed COBOL programs can interoperate seamlessly with programs in other managed languages.
  • Object-Oriented (OO) COBOL Restrictions in Managed Code
    Applications that use the native Object-Oriented (OO) COBOL syntax will probably require significant work to migrate them to managed COBOL. We recommend that you contact Micro Focus SupportLine for extra help with this.
  • SQL Restrictions in Managed COBOL
    Managed COBOL provides extensive support for SQL. However, there are one or two features of SQL are not supported in managed COBOL.
  • Unsupported Functionality in Managed COBOL
    Some areas of functionality are not supported in managed COBOL.
Parent topic: Restrictions, Compiler Limits, and System Limits


COBOL Syntax Restrictions in Managed COBOL

There is syntax designed specifically for managed COBOL. We recommend you use this syntax, although you can continue to use the original native COBOL syntax, in virtually all situations.

However, there are some words that are now reserved. If your native code uses these reserved words, you get a Compiler error when you compile to managed code. You can change your data item names so that they don't conflict with a reserved word or you can unreserve the necessary words using the REMOVE Compiler directive.

In addition, the following syntax is not supported in managed COBOL:

  • ALTER statement. This is supported but in segmented programs, an altered paragraph remains altered even when a segment is reloaded.
  • CHAIN statement. This is mapped to a CALL statement.
  • GLOBAL declaratives in nested programs.
  • Mainframe pointers.

The syntax designed specifically for managed COBOL and some additional words are now reserved. If your native code uses words that are now reserved, you get a Compiler error when you compile to managed code. You can change your data item names so that they don't conflict with a reserved word or you can unreserve the necessary words using the REMOVE Compiler directive.

Parent topic: Managed COBOL Restrictions
Related reference
Managed COBOL Reference


Compiler Directives Restrictions in Managed COBOL

Most Compiler directives are supported for managed COBOL, in addition to those directives designed specifically for compiling managed code. There are a few native COBOL Compiler directives that are not supported in managed COBOL.

The following Compiler directives are not supported in managed COBOL:

  • ACCEPTREFRESH
  • ACTUAL-PARAMS
  • BOUNDOPT
  • CALL-RECOVERY
  • CHECK
  • DATA-CONTEXT
  • DB2
  • DEFAULTCALLS
  • FASTCALL
  • FASTINIT
  • FASTLINK
  • FCDALIGN
  • FIXOPT
  • FP-ROUNDING
  • GNT
  • HOSTARITHMETIC
  • HOSTCONTZERO
  • INITPTR
  • LINKCHECK
  • LITLINK
  • LNKALIGN
  • MAPNAME
  • NATIONAL
  • NATIVE-FLOATING-POINT
  • OBJ
  • ODOOSVS
  • OPT
  • PARAMCOUNTCHECK
  • PC1
  • PERFORMOPT
  • PPLITLINK
  • PROTECT-LINKAGE
  • RDFPATH
  • RECMODE
  • RECURSECHECK
  • REMAINDER
  • REPOSITORY
  • SCHEDULER
  • SEG
  • SIGNDISCARD
  • SOURCEASM
  • SSRANGE
  • STICKY-LINKAGE
  • TESTCOVER
  • 1TRICKLE
  • TRUNCCALLNAME
Parent topic: Managed COBOL Restrictions
Related information
Compiler Directives
Managed COBOL Command Line Compiler Directives
1 deprecated


File Handling Restrictions in Managed COBOL

Managed COBOL supports virtually all file handling functionality. However, there are one or two features that are not supported.

The following file handling features are not supported in managed COBOL when using the Micro Focus File Handler:

  • .lbr files
  • LPT[2-n] devices
  • Object references specified in the file section

The following file handling features are not supported in managed COBOL when using the Managed File Handler:

  • Fileshare
  • ACUCOBOL-GT and RM/COBOL File Handlers
Parent topic: Managed COBOL Restrictions
Related information
File Handling


COBOL Services as Java Interfaces and Web Services

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

Enterprise Server can run Java interfaces and Web Services that you create using the Interface Mapping Toolkit.

Parent topic: Managed COBOL Restrictions
Related information
Using COBOL and Java Together


Mixed-language Implications in Managed COBOL

Managed COBOL programs can interoperate seamlessly with programs in other managed languages.

Managed COBOL programs can interoperate seamlessly with programs in other managed languages.

There is a small performance overhead for calls between native COBOL and managed code. There is no performance penalty for method invocations between managed COBOL and other managed languages.

Parent topic: Managed COBOL Restrictions
Related information
Interoperability
Data Marshaling and Type Conversion for Managed Code Interoperation
JVM COBOL Interoperating with Native COBOL


Object-Oriented (OO) COBOL Restrictions in Managed Code

Applications that use the native Object-Oriented (OO) COBOL syntax will probably require significant work to migrate them to managed COBOL. We recommend that you contact Micro Focus SupportLine for extra help with this.

Some of the significant differences between native OO COBOL and managed COBOL are:

  • Managed code is typed, unlike native OO COBOL. The Compiler enforces type checking on object references in managed COBOL. This is different to native OO COBOL where all object references are simply of type "object" and can hold a reference to instances of any class of object.
  • Object references must be defined at level-01 in managed COBOL, because the compiled code and the run-time system now conform to the rules for type-safe code. This conforms with the ISO2002 COBOL standard.
  • The Micro Focus OO class libraries are not supported for managed COBOL.
  • The CLASS-OBJECT syntax is not available in managed COBOL.
  • Multiple inheritance is not supported in native OO COBOL, although it is part of the ISO 2002 standard. Managed COBOL supports single inheritance of classes, but you can inherit (implement) multiple interfaces.
  • Interface files (.if) and the vocabularies syntax do not have an equivalent in managed COBOL.
Parent topic: Managed COBOL Restrictions
Related information
Micro Focus OO COBOL Extensions


SQL Restrictions in Managed COBOL

Managed COBOL provides extensive support for SQL. However, there are one or two features of SQL are not supported in managed COBOL.
  • Dynamic SQL using the SQL Descriptor Area (SQLDA) is not supported for OpenESQL applications compiled with the SQL(DBMAN=ODBC) directive.
  • ESQL is not supported in COBOL for JVM
Parent topic: Managed COBOL Restrictions
Related information
Database Access Concepts
Reference


Unsupported Functionality in Managed COBOL

Some areas of functionality are not supported in managed COBOL.

The following functionality is not supported in managed COBOL:

  • ANSI debug
  • CGI
  • Micro Focus class libraries
Parent topic: Managed COBOL Restrictions


JVM COBOL

  • Managed COBOL Reference
  • Comparison of COBOL with Other Managed Languages
    This is also known as the Rosetta Stone document.
  • com.microfocus.cobol.runtimeservices
Parent topic: General Reference


Managed COBOL Reference

Managed COBOL supports all aspects of the managed framework (both .NET and JVM), providing new syntax specifically designed to support these features.

In addition, managed COBOL continues to support all of the existing COBOL syntax (for procedural COBOL) with very few exceptions.

This reference describes the syntax designed and recommended for managed COBOL. The syntax for procedural COBOL is documented in the COBOL Language Reference.

  • Program Structure
  • Structural Syntax Elements - Alphabetic List
  • Common Syntax Elements
  • Statements - Alphabetic List
  • Concepts - Managed COBOL
Parent topic: JVM COBOL
Related information
COBOL Language Reference


Program Structure

A managed COBOL program consists of one or more type specifications, where a type can be a class, a value type, an interface, a delegate, an enum, or an attribute.

Procedural COBOL programs, delimited by PROGRAM-ID/END PROGRAM are also permitted but are documented elsewhere.

Tip: Where applicable, the diagrams in this section contain links to more detailed syntax.
type-specification ...
Parent topic: Managed COBOL Reference


Types

Context:

    Program Structure

type-specification

class-specification delegate-specification enum-specification interface-specification valuetype-specification Attribute specification

Example

class-id A.
...
end class.

interface-id I.
...
end interface.


Classes

A class defines the data members and function members for object instances that are created from that class.

In managed COBOL, each class inherits from exactly one other class. If the inherited class is not specified (in the INHERITS clause), then the class inherits from System.Object (.NET) or from java.lang.Object (JVM).

Context:

    Program Structure
        Types

class-specification

class-header constraints-paragraph attribute-clause Static or Instance Fields static-or-instance-member type-specification

class-header

access-modifier type-specifier type-specifier attribute-clause generic-using-phrase

Example

class-id A.
01 sField string.
method-id doStuff.
   ...
end method.

class-id nestedClass.
...
end class.

end class.

See also the Core sample, which is available from $COBDIR/demo.

Class Header Keywords

ABSTRACT
Declares a class that is only intended to be used as a base class. An abstract class can be thought of as an incomplete class.
FINAL
Declares a class whose definition is complete. The FINAL modifier on a class implies that the class cannot be inherited.
STATIC
Declares a class that cannot be instantiated.
PARTIAL
Indicates that the declaration is one of two or more parts that make up the full declaration. Partial classes enable you to split a class declaration into logical parts.
INHERITS
Defines that a class is inherited, where type-specifier specifies the class that is inherited. Inheritance enables a class to implicitly contain members of its inherited class type.
IMPLEMENTS
Indicates that an interface is implemented, where type-specifier specifies the interface that is implemented.
SERIALIZABLE
This allows the class to be serialized in .NET COBOL via the System.Runtime.Serialization.Formatters.Binary class, and in JVM COBOL via the java.io.ObjectOutputStream class.

Abstract Classes

An abstract class cannot itself be instantiated, but non-abstract classes can inherit from the abstract class, and can be instantiated. Because an ABSTRACT class has to be inherited, it cannot be FINAL.

An abstract class typically contains abstract methods, which are not implemented in the class declaration, like method declarations in an interface. It is however possible for an abstract class to define non-abstract methods. A class inheriting the abstract class, and which is not itself abstract, must provide implementations for all the abstract methods defined in the abstract class. Only an abstract class can contain abstract methods.

Use OVERRIDE when implementing the members of an abstract class in the non-abstract members of the derived class, as shown in the following example:

       class-id. Animal abstract.
       method-id MakeNoise abstract.
      *> No implementation allowed
       end method.

       end class.

       class-id Dog inherits type Animal.
      *> Overrides the MakeNoise method in the Animal class
       method-id MakeNoise override.
           display "Woof!"
       end method.
       end class.

In this example, the abstract class Animal contains the abstract method MakeNoise. Because the non-abstract class Dog inherits from the abstract class Animal, it must provide an implementation of MakeNoise using the OVERRIDE modifier.

An abstract class can contain non-abstract methods in addition to abstract methods.

A class that inherits an abstract class must also be declared as an abstract class if it does not provide implementation of the inherited class' members.

Final Classes

A final class cannot be inherited. Because of this, methods in a final class cannot be overridden.

Declaring a class as FINAL is useful to prevent subversion of the class. It prevents a subclass from potentially changing the intended class functionality by overriding its intended behavior.

Nested Classes

Nested classes can access static fields, properties and methods within the containing classes.

The optional SHARING PARENT phrase in the nested class definition enables instance methods and properties in the nested class to access the instance fields, properties and methods in the containing class.

    class-id ContainingClass.
    ...
    class-id Nested1.
        ...
    end class.
    class-id Nested2 sharing parent.
       ...
    end class.
    end class.

Nested Classes with SHARING PARENT

Nested classes with the SHARING PARENT phrase may only be instantiated from within an instance method in the enclosing class. They can access the instance members from that containing class, even when those instance members are private.

Such a nested class contains an implicit reference to an instance of its containing class. The nested class uses this reference to access the enclosing class's instance members. This means that the containing class instance will not be garbage collected until all references to the inner class held externally have themselves been garbage collected.

For example:

    class-id ContainingClass.
    01 companyName string value "Micro Focus".

    method-id instance1.
    01 o type Nested2.
        set o to new Nested2
        ...
    end method

    class-id Nested2 SHARING PARENT.
    method-id method2
        display companyName
    end method.
    end class.

    end class.

Nested Classes without SHARING PARENT

Nested classes defined without the SHARING PARENT phrase may be declared as public, private or internal. Depending on the visibility specified, they can be instantiated from any context, not just from the containing class, and not just from instance methods. They can only access instance members of the containing class using an explicit object reference.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Program Structure - in COBOL and Java
Objects - in COBOL and Java
Nested Classes in Managed COBOL


ValueTypes

Value types can contain data members and function members, similar to classes. The difference is that value types store the data as values and don't require heap allocation.

Context:

    Program Structure
        Types

valuetype-specification

valuetype-header constraints-paragraph static-or-instance-field static-or-instance-member

valuetype-header

access-modifier type-specifier attribute-clause

Example

valuetype-id StudentRecord.
01 aName string public.
01 gpa float-short public.
method-id new.
procedure division using by value nam as string,
                                  gpa as float-short.
    set aName to nam
    set self::"gpa" to gpa
end method.
end valuetype.

class-id a.
method-id main static.
local-storage section.
01 stu type StudentRecord value new StudentRecord("Bob", 3.5).
01 stu2 type StudentRecord.
procedure division.
    set stu2 to stu
    set stu2::aName to "Sue"
    display stu::aName   *> Prints Bob
    display stu2::aName  *> Prints Sue
end method.
end class.
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Structures, Value Types - in COBOL and Java


Interfaces

An interface is a list of instance methods specifying names and signatures but without implementation.

Context:

    Program Structure
        Types

interface-specification

interface-header constraints-paragraph interface-member

interface-header

access-modifier type-specifier attribute-clause generic-using-phrase

interface-member

method-specification property-specification indexer-specification

Example

*> Interface definition
interface-id IClock
01 Hour      binary-long property with no set.
01 Minute    binary-long property with no set.

method-id Reset.
end method.

end interface.

*> Extending an interface
interface-id IAlarmClock implements type IClock.
01 AlarmHour   binary-long property.
01 AlarmMinute binary-long property.

method-id Snooze (#time as binary-long).
end method.

end interface.

*> Interface implementation
class-id WristWatch implements type IAlarmClock,
                               type System.IDisposable.

working-storage section.
01 Hour        binary-long property with no set.
01 Minute      binary-long property with no set.
01 AlarmHour   binary-long property.
01 AlarmMinute binary-long property.
method-id Dispose.
    invoke self::Reset()
end method.

method-id Reset.
    set Hour to 0
    set Minute to 0
    set AlarmHour to 0
    set AlarmMinute to 0
end method.

method-id Snooze (#time as binary-long).
    add #time to AlarmMinute
end method.

end class.

About Interfaces

An interface is a list of instance methods specifying names and signatures but without implementation.

When a program declares that it implements a particular interface this means that the program is required to have implementations for all the methods defined in the interface. To implement an interface you use the IMPLEMENTS phrase of the OBJECT clause in a class definition to declare that a program provides an implementation for the specified interface. You can also declare an object reference to this interface type.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Constraints Paragraph
Related information
Interfaces - in COBOL and Java


Delegates and Events

Delegates are the object-oriented equivalent of the procedure pointer, offering a type-safe solution. Used in conjunction with the EVENT keyword, they are generally used as a mechanism for one software component to notify another about an event which has occurred, for example a key being pressed in a GUI environment.

Context:

    Program Structure
        Types

delegate-specification

delegate-header procedure-division-header

delegate-header

Method SignatureThe method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature. access-modifier attribute-clause

Example

delegate-id MessageHandler (str as string).
end delegate.

class-id DelegatesEvents.

01 MessageArrived     event type MessageHandler static.

method-id Main static.
  *> explicit delegate construction
  invoke new MessageHandler(MyHandler)

  *> implicit delegate construction
  declare handler as type MessageHandler = method MyHandler

  *> subscribe to an event
  attach method MyHandler to MessageArrived

  *> raise the event
  invoke MessageArrived("Test message")

  *> unsubscribe from the event
  detach method MyHandler from MessageArrived

  *> Throws a null reference exception as there are no subscribers
  invoke MessageArrived("Test message 2")

  *> Safely raising an #event
  declare handler2 as type MessageHandler = MessageArrived
  if handler2 not equals null
     invoke handler1("Safe message")
  end-if

end method.

method-id MyHandler static (str as string).
  display str
end method.

end class.

Further Information

A delegate is a class that can hold a reference to a method and, in the case of an instance method, an object on which that method can be invoked.

Once an instance of a delegate class has been created, it can be invoked, at which point the referenced method is invoked on the stored instance.

A delegate type can only hold references to methods of a particular signature, so creating and invoking delegates is type safe.

To define a delegate in COBOL, you use the DELEGATE-ID keyword, and the PROCEDURE DIVISION header to specify the signature. For example, to declare a delegate that has a string parameter and returns a binary-long:

delegate-id MyDelegate.
procedure division using by value s1 as string returning n1 as binary-long.
end delegate.
Method Groups

A method group is a method invocation expression preceded by the keyword METHOD, and without any parameters. When a method group is specified, it denotes one of the set of methods with the specified name in the specified class.

An implicit conversion exists between a method group and a specific delegate type, if one of the methods identified by the method group has a signature which is compatible with that delegate type.

For example, to create an instance of the delegate MyDelegate you declared above, that points to a suitable method:

01 d type MyDelegate.
01 c type Class1.
...
set d to method c::m

class-id Class1.
method-id m.
procedure division using by value s1 as string returning n1 as binary-long.
end method.

method-id m.
procedure division using by value s1 as string s2 as string returning n1 as binary-long.
end method.

end class.

In the example above, the SET statement automatically selects the first overload of the method m as it has a signature which is compatible with that of the delegate type MyDelegate.

A method group can also be used as a parameter to a method, when that method has an argument of a compatible delegate type. Again, an implicit conversion from the method group to the delegate type will take place, and that delegate will be passed as the parameter to the target method.

Anonymous methods

You can set a delegate to point to a piece of code, without formally setting that code up as a specific method. Such a piece of code is called an Anonymous Method, and you use the keywords DELEGATE and END-DELEGATE to specify it.

You specify any parameters and return values with the words USING and RETURNING attached to the word DELEGATE.

The following shows how you can attach an anonymous method to the delegate MyDelegate you created in the previous examples:

01 d type MyDelegate.
set d to delegate using s1 as string
                                returning n1 as binary-long
                  set n1 to s1::Length
              end-delegate.
Invoking delegates

To invoke a delegate after it has been created, you use the keyword RUN followed by the delegate name, and any parameters enclosed in parentheses. For example, to run the delegate d created above and displaying the results, type:

display run d("Hello")

This statement causes the anonymous method to be invoked and return a value of 5. This value is then displayed.

Example of creating and invoking delegates
       delegate-id MyDelegate.
       procedure division using by value s1 as string returning n1 as binary-long.
       end delegate.

       class-id a.
       method-id main static.
       01 d type MyDelegate.
       01 c type Class1 value new Class1.

       set d to method c::m
       display run d("ABC")

       set d to delegate using s1 as string
                         returning n1 as binary-long
                    set n1 to s1::Length
                end-delegate
       display run d("XYZ")
       end method.
       end class.

       class-id Class1.
       method-id m.
       procedure division using by value s1 as string returning n1 as binary-long.
           set n1 to size of s1 + 3
       end method.
       method-id m.
       procedure division using by value s1 as string s2 as string returning n1 as binary-long.
       end method.
       end class.
Combining delegates

A single delegate can hold references to more than one object/method pair. In such cases, at the time when the delegate is invoked, each one of the methods will be invoked in the order in which they were added to the delegate.

  • You use the operator '+' to add a method group, anonymous method or another delegate to a delegate.
  • You use the operator '-' to remove methods from a delegate.
Note: At least one side of such an expression must be an instance of a delegate type.

For example:

       class-id DelegateCombining.
       method-id main static.
       01 cd1 type D.
       01 cd2 type D.
       01 cd3 type D.
       01 c type C value new C.
           set cd1 to method type C::M1
           invoke cd1(-1)
           set cd2 to method type C::M2
           invoke cd2(-2)
           set cd3 to cd2 + method type C::M1
           invoke cd3(10)
           set cd3 to method type C::M1 + cd3
           invoke cd3(20)

           set cd3 to cd3 + method c::M3
           invoke cd3(30)

           set cd3 to cd3 - method type C::M1
           invoke cd3(40)
           set cd3 to cd3 - method c::M3
           invoke cd3(50)
           set cd3 to cd3 - method type C::M2
           invoke cd3(60)
           set cd3 to cd3 - cd2
           invoke cd3(60)
           set cd3 to cd3 - cd1
           try
               invoke cd3(70)
           catch
               display "null reference exception caught"
           end-try
           set cd3 to cd3 - cd1

           set cd1 to method type C::M1
           set cd2 to method type C::M2
           set cd3 to cd1 + cd2 + cd2 + cd1
           invoke cd3(80)
           set cd3 to cd3 - cd1
           invoke cd3(90)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd1 + cd2)
           invoke cd3(100)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd2 + cd2)
           invoke cd3(110)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd2 + cd1)
           invoke cd3(120)
           set cd3 to cd1 + cd2 + cd2 + cd1
           set cd3 to cd3 - (cd1 + cd1)
           invoke cd3(130)

       end method.
       end class.

       delegate-id D.
       procedure division using by value i as binary-long.
       end delegate.

       class-id C.
       method-id M1 static.
       procedure division using by value i as binary-long.
           display "C::M1 --> " i
       end method.
       method-id M2 static.
       procedure division using by value i as binary-long.
           display "C::M2 --> " i
       end method.
       method-id M3.
       procedure division using by value i as binary-long.
           display "C::M3 --> " i
       end method.
       end class.

Events

An event is a way in which a class can provide notifications when something of interest happens, such as a key being pressed in a GUI environment.

To define an event, you add the keyword EVENT to a delegate field. For example:

       01 ChangeEvent type ChangeDelegate event public.

Delegates of the same type, or compatible method groups or anonymous methods can be attached to the event, and will be invoked at the time when the owning class of the event invokes the backing delegate.

The relationship between an event and its backing delegate is very similar to the relationship between a property and its backing storage.

Attaching a method or a delegate to an event

You use the ATTACH statement to attach a delegate, method group or an anonymous method to an event:

ATTACH {delegate-instance}    TO event-expression
                {method-group}
                {anonymous-method}

For example:

       01 names type myList.
       01 MyDelegate type ChangeDelegate.
       procedure division.
           set names to new myList
           attach method ListChanged to names::ChangeEvent
           set MyDelegate to method ListChanged
           attach MyDelegate to names::ChangeEvent
To detach a method or a delegate from an event

To detach a delegate or method group from an event use the DETACH statement:

DETACH {delegate-instance}    FROM  event-expression
                {method-group}

For example:

           detach MyDelegate from names::ChangeEvent
           detach method ListChanged from names::ChangeEvent
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Fields
Related information
Delegates and Events - in COBOL and Java


Enums

An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.

Context:

    Program Structure
        Types

enum-specification

enum-header type-specifier enum-constant

enum-header

access-modifier attribute-clause

enum-constant

type-specifier

Example

enum-id Action.
   78 #Start.   *> Start is a reserved word so use '#' symbol
   78 #Stop.
   78 #Rewind.
   78 #Forward.
end enum.

enum-id Status.
   78 Flunk value 50.
   78 Pass  value 70.
   78 Excel value 90.
end enum.

class-id MainClass.
method-id main static.
   declare a = type Action::Stop
   if a not = type Action::Start
       display a & " is " & a as binary-long   *> Prints "Stop is 1"
    end-if
   display type Status::Pass as binary-long    *> prints 70
   display type Status::Pass *> prints
end method.
end class.

See also the Enums sample, available from $COBDIR/demo.

Further Information

The Compiler adds a static method called 'values' that returns an array containing the values of the enum. You can use this method together with the PERFORM THROUGH construct to iterate over the values of an enum type.

The enum-header is followed by a working-storage section consisting of:

  • A single numeric field of one of the predefined types. By default, this is binary-long.
  • Any number of level 78 items defining the values for the enum. The default value of the first item is 0 and the values of subsequent items are incremented by default.
Note: In COBOL for JVM, as in Java, the enum declaration defines an enum class, which is a class that derives from java.lang.Enum. In Java, this enum class can include methods and other fields explicitly declared by the user, whereas this is not allowed in COBOL.
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Related information
Enums - in COBOL and Java


Attributes

The ATTRIBUTE-ID syntax allows for the definition of new attribute types, which can be used in various contexts (see attribute-clause).

Context:

    Program Structure
        Types

attribute-specification

Static or Instance Fields Type Specification - syntax

attribute-header

Attribute Clause - Syntax

Example

Note that, when compiling for JVM COBOL, instance members (that is, constructors, methods or properties) are ignored, but do not cause a compilation error. Similarly, the keyword PROPERTY on fields is also ignored in this case.

An example of a simple attribute, which can be used interchangeably both on .NET and on JVM COBOL is:

attribute-id AuthorAttribute.
01 #value string.
method-id new(auth as string).
    set #value to auth
end method.
end attribute.

On .NET, the resulting code is equivalent to the following .NET COBOL class:

class-id AuthorAttribute inherits type System.Attribute
01 #value string.
method-id new(auth as string).
    set #value to auth
end method.
end class.

On JVM, the resulting code is equivalent to the following Java annotation:

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
public @interface AuthorAttribute
{
  public String value();
}


Structural Syntax Elements - Alphabetic List

  • Classes
    A class defines the data members and function members for object instances that are created from that class.
  • Constructors
    A constructor is a class method that is executed when the class is created.
  • Delegates and Events
    Delegates are the object-oriented equivalent of the procedure pointer, offering a type-safe solution. Used in conjunction with the EVENT keyword, they are generally used as a mechanism for one software component to notify another about an event which has occurred, for example a key being pressed in a GUI environment.
  • Enums
    An enumeration represents a list of constant values, such as values for the days of the week. You can declare an enum type that defines the values and symbolic names for them. You can then refer to the values by name.
  • Fields
    A class, valuetype and interface can define a set of static or instance fields.
  • Indexers
    Indexers resemble properties except that their accessors take parameters. Indexers allow instances of a class or valuetype to be indexed just like arrays.
  • Interfaces
    An interface is a list of instance methods specifying names and signatures but without implementation.
  • Iterators
    An iterator is a section of code that returns an ordered sequence of values. You can create an iterator by defining a member as an iterator, using iterator-id.
  • Methods
    A method defines a block of code to be executed when the method is invoked.
  • Operators
    A set of default operators are predefined and implemented. You can overload an operator and define your own behavior for it.
  • Procedure Division
    The procedure division defines the code to be executed when a type or member is invoked. The procedure division header defines any parameters to pass in to the code and any returning item to pass back.
  • Procedure Division Header
    You can specify the parameters, both passed to a member and items returned, in either the method signature or the procedure division header. If the parameters are specified in the method signature, the procedure division header must be omitted from the method.
  • Properties
    Properties are members with associated types. They are similar to fields but they have accessors that provide the means to read and write values.
  • Type Members
    A class, valuetype or interface can define a set of members, such as methods and properties.
  • ValueTypes
    Value types can contain data members and function members, similar to classes. The difference is that value types store the data as values and don't require heap allocation.
Parent topic: Managed COBOL Reference


Constructors

A constructor is a class method that is executed when the class is created.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

constructor-specification

constructor-header Procedure Division Header chained-constructor

constructor-header

constructor-signatureThe method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature. Access Modifiers - SyntaxThe access modifiers of an item control the visibility (accessibility) of the item to other code. For example, you can call public methods from anywhere, whereas private methods can be called only from other methods within the same type. attribute-clause

Example

class-id SuperHero.
01 _powerLevel binary-long.

method-id new.
    set _powerLevel to 0
end method.

method-id new (powerLevel as binary-long).
    set _powerLevel to powerLevel
end method.

$if JVMGEN set
method-id Finalize override protected.
    *> JVM finalizer method.
end method.
$else
method-id Finalize override protected.
    *> .NET finalizer method.
end method.
$end
end class.

Further Information

If STATIC is not specified, the method is an instance constructor, and the code is executed when a class instance is created (see the NEW expression).

If STATIC is specified, the method is a static constructor, and is executed when the class is first loaded.

Neither instance constructors nor static constructors may specify a RETURNING item. Static constructors may not specify any parameters.

If you specify parameters in the constructor header, you must not include a procedure division header in the body of the constructor.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Attributes
Methods
Procedure Division
Related information
Methods - in COBOL and Java
Constructors and Destructors - in COBOL and Java


Fields

A class, valuetype and interface can define a set of static or instance fields.

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

static-or-instance-field

variable-field constant-field

variable-field

type-specifier access-modifier attribute-clause

constant-field

type-specifier access-modifier attribute-clause

Example

    01 dAmount  decimal.
    01 asNames string occurs 5.
    01 abFigures binary-long occurs any.

    78 Max_Students value 25.  *> default is public, binary-long

See also the Core sample available from $COBDIR/demo.

INITIALIZE ONLY Keywords

The INITIALIZE ONLY phrase defines a static or instance field that can only be modified within a static constructor or instance constructor (respectively). For example:

    class-id a.
    01 s string static value "Shouldn't see this" initialize only.
    method-id main static.
        display s
    end method.
    method-id new static.
        set s to "Hello world"
    end method.
    end class.

INITIALIZE ONLY fields and constant fields differ as follows:

INITIALIZE ONLY field:
  • Can be either instance-level or static
  • Evaluated at run time
  • Can be initialized in declaration or by code in the constructor
Constant field (78-level):
  • Always implicitly static
  • Evaluated at compile time
  • Initialized at declaration only

CONSTANT Keyword

Use the CONSTANT keyword to declare 01-level fields as constants.

The VALUE clause must be a literal value or a constant defined within this or another class.

For numeric fields, the VALUE clause may be an arithmetic expression. The arithmetic expression may contain parentheses, and is evaluated according to the normal rules of arithmetic expressions and according to type, so truncation may occur.

For string fields, the VALUE clause may be a string constant or a string concatenation expression containing only constants.

EVENT Keyword

The EVENT keyword is allowed only on items that are declared as delegates. It causes the creation of an event, which may be static or instance depending on the presence of the STATIC keyword.

Methods, delegates and anonymous methods, which are compatible with the underlying delegate type of the event, can be attached to the event using the ATTACH verb, and can subsequently be detached using the DETACH verb. For example:

class-id MyList using I.
working-storage section.
01 ChangeEvent type ChangeDelegate event public.
…
end class
class-id a.

method-id main static.
 declare names as type MyList[string] = new MyList[string]
 attach method ListChanged1 to names::ChangeEvent
 …

Use the following clauses to modify the characteristics of the event.

The FOR Clause

Use the FOR clause as an explicit interface implementation, which is particularly useful when the containing class implements two different interfaces, and these two interfaces have properties with the same name and type. In this case, by using the FOR phrase, you can supply two different implementations of the event for the two different interfaces.

01 ChangeEvent type ChangeDelegate EVENT FOR MyInterface1.
01 ChangeEvent type ChangeDelegate EVENT FOR MyInterface2.

The FINAL Clause

Use the FINAL clause to make the event non-virtual, so that it cannot be overridden in a derived class.

01 ChangeEvent type ChangeDelegate EVENT FINAL.

The OVERRIDE Clause

Use the OVERRIDE clause to override an event of this name and type in an inherited class. Only virtual events in the inherited class can be overridden in this way. The OVERRIDE and the REDEFINE clauses are mutually exclusive.

 01 ChangeEvent type ChangeDelegate EVENT OVERRIDE.

The REDEFINE Clause

Use the REDEFINE clause to redefine an event of this name and type in an inherited class. Both virtual and non-virtual events in the inherited class can be redefined in this way. The OVERRIDE and the REDEFINE clauses are mutually exclusive.

01 ChangeEvent type ChangeDelegate EVENT REDEFINE.

PROPERTY Keyword

You can expose a field as a property using the PROPERTY keyword. By default, the property name will be the same as the field name (and in the same case). You can use the AS clause to specify a different external name.

01 public-field pic x property as "Property1".

The PROPERTY keyword generates two accessor methods to retrieve and update the field. The names of these methods are derived from the property name by prefixing it with 'get_' and 'set_' (.NET) or with 'get' and 'set' (JVM). These methods are commonly known as getter and setter methods. Languages that support properties will hide these methods from you and appear to allow you to get and set these member fields directly. In fact, the Compiler is substituting the property name with the relevant getter or setter.

The property thus defined is virtual by default, which means that it can be overridden in derived classes.

Use the following clauses to modify the characteristics of the property.

The FOR Clause

Use the FOR clause as an explicit interface implementation, which is particularly useful when the containg class implements two different interfaces, and these two interfaces have properties with the same name and type. In this case, by using the FOR phrase, you can supply two different implementations of the property for the two different interfaces.

01 public-field2 pic x property as "Property1" FOR MyInterface1.
01 public-field2 pic x property as "Property1" FOR MyInterface2.

The FINAL Clause

Use the FINAL clause to make the property non-virtual, so that it cannot be overridden in a derived class.

 01 public-field pic x property as "Property1" FINAL.

The OVERRIDE Clause

Use the OVERRIDE clause to override a property of this name and type in an inherited class. Only virtual properties in the inherited class can be overridden in this way. The OVERRIDE and the REDEFINE clauses are mutually exclusive.

 01 public-field pic x property as "Property1" OVERRIDE.

The REDEFINE Clause

Use the REDEFINE clause to redefine a property of this name and type in an inherited class. Both virtual and non-virtual properties in the inherited class can be redefined in this way. The OVERRIDE and the REDEFINE clauses are mutually exclusive.

01 public-field pic x property as "Property1" REDEFINE.

Example:

The output from the following program should be:

P1 in b

P2 in a

P3 in a

M1 in b

M2 in a

M3 in a

class-id myTesterClass.
method-id main static.
   01 a type a value new b.

   display a::P1
   display a::P2
   display a::P3
   invoke a::M1
   invoke a::M2
   invoke a::M3
end method.
end class.

class-id a.

01 P1 string property value "P1 in a".
01 P2 string property value "P2 in a".
01 P3 string property final value "P3 in a".

method-id M1.
   display "M1 in a".
end method.

method-id M2.
   display "M2 in a".
end method.

method-id M3 final.
   display "M3 in a".
end method.

end class.

class-id b inherits type a.

01 P1 string property override value "P1 in b".
01 P2 string property redefine value "P2 in b".
01 P3 string property redefine value "P3 in b".

method-id M1 override.
   display "M1 in b".
end method.

method-id M2 redefine.
   display "M2 in b".
end method.

method-id M3 redefine.
   display "M3 in b".
end method.
end class.

See also the Properties sample, which is available from $COBDIR/demo.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Delegates and Events
Properties
Local Data Item Declaration
Access Modifiers
Attributes
Type Specifier
Related information
Data Types - in COBOL and Java
Constants - in COBOL and Java
String Handling in Managed COBOL


Indexers

Indexers resemble properties except that their accessors take parameters. Indexers allow instances of a class or valuetype to be indexed just like arrays.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

indexer-specification

indexer-header procedure-division-header access-modifier statement-block access-modifier statement-block

indexer-header

type-specifier indexer-id-signatureThe method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature. access-modifier attribute-clause

Example

In the following example, a class is defined and provided with simple getter and setters as a means of assigning and retrieving values. Square brackets used to access arrays, use 0-based indexing. Round brackets use 1-based indexing.

       class-id SimpleIndexer.
       01 myArray string occurs 100.

       indexer-id string.
       procedure division using by value i as binary-long.
       getter.
           set property-value to myArray[i]
       setter.
           set myArray[i] to property-value
       end indexer.

       end class.

See also the IndexerDemo.cbl in the Indexers sample, available from $COBDIR/demo.

Explicit Indexer Implementation

If the FOR clause is specified, this indexer is an Explicit Interface Member Implementation. The indexer may not be invoked explicitly. It will be invoked implicitly when the corresponding indexer is invoked on an instance of this class which has been cast to the interface type.

Use of explicit interface implementation (via the FOR clause) is particularly useful when the class implements two different interfaces, and these two interfaces have a method with the same signature. In this case, by using the FOR phrase, you can supply two different implementations of the method for the two different interfaces.

For example:

interface-id. "Interface1".
indexer-id string.
procedure division using i as binary-long.
end indexer.
end interface.

interface-id. "Interface2".
indexer-id string.
procedure division using i as binary-long.
end indexer.
end interface.

class-id TwoIndexers implements type Interface1 type Interface2.

indexer-id string for type Interface1.
...
end indexer.

indexer-id string for type Interface2.
...
end indexer.
end class.
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Access Modifiers
Attributes
Properties
Iterators
Type Specifier
Related information
Arrays - in COBOL and Java
Iterators - in COBOL and Java


Iterators

An iterator is a section of code that returns an ordered sequence of values. You can create an iterator by defining a member as an iterator, using iterator-id.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

iterator-specification

iterator-header procedure-division

iterator-header

iterator-id-signatureThe method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature. Extension Methods and Operator Overloading Extension methods enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code. access-modifier attribute-clause Generics - Managed Syntax Generic types and methods can be defined in COBOL with the USING phrase.

Example

Here we use an iterator-id paragraph GetEven to return the even numbers in the m-FibonacciArray

       class-id Fibonacci.Class1 static.

       data division.
       working-storage section.
       01 m-FibonacciArray binary-long occurs any static.
       method-id FibEvens static.
       procedure division.
        set content of m-FibonacciArray to (1 2 3 5 8 13 21 34 55 89 144)

        display "Even numbers in the Fibonacci sequence:"
        perform varying evenNumber as binary-long through self::GetEven
            display evenNumber
        end-perform
           goback.
       end method.

       iterator-id GetEven yielding res as binary-long static.

        perform varying i as binary-long through m-FibonacciArray
            if i b-and 1 = 0
                set res to i
                goback
            end-if
        end-perform
        stop iterator *> stops the iterator explicitly
       end iterator.  *> end of method stops the iterator implicitly
       end class.

The following is a similar example, but uses the self syntax to allow iteration directly through the current class (that is, the class in which the iterator appears).

       class-id Fibonacci.Class2.
       method-id main static (args as string occurs any).
           try
               declare max as binary-long = binary-long::Parse(args[0])
               declare fibs = new Fibonacci(max)
               perform varying i as binary-long through fibs
                   display i
               end-perform
           catch
               display "Bad command line"
           end-try
       end method.
       end class.

       class-id Fibonacci.
       01 MaxNumber binary-long.

       method-id new (#max as binary-long).
           set MaxNumber to #max
       end method.

       iterator-id self yielding res as binary-long.
           set res to 1
           exit iterator
           declare frst as binary-long = 0
           declare second as binary-long = 1
           perform until exit
               compute res = frst + second
               if res > MaxNumber
                   stop iterator
               end-if
               move second to frst
               move res to second
               exit iterator
           end-perform
       end iterator.
       end class.

See also the Iterators sample, which is available from $COBDIR/demo.

Further information

If you specify parameters in the iterator header, you must not include a procedure division header in the body of the iterator.

The STOP ITERATOR statement stops the iteration.

This statement is not needed if the next statement is END ITERATOR.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Indexers
Access Modifiers
Attributes
Related information
Iterators - in COBOL and Java


Method-ID (COBOL Language Reference)

Methods

A method defines a block of code to be executed when the method is invoked.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

method-specification

In this topic:

  • Static and Instance Methods
  • Instance Method Modifiers
  • Abstract Methods
  • Override Methods
  • Redefine Methods
  • Final Methods
  • Extension Methods
  • Synchronized Methods
  • Explicit Interface Implementation
  • Asynchronous Methods
method-header constraints-paragraph procedure-division

method-header

Method SignatureThe method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature.

Examples

method-id methodA static.
01 s string value "Hello".
procedure division.
   display s
end method.
method-id methodB (paramA AS binary-short paramB AS binary-short) RETURNING paramC AS binary-short.
set paramC = paramA * paramB
end method.

See also the Core sample, which is available from $COBDIR/demo.

Static and Instance Methods

Methods can be either static methods or instance methods, and are by default instance. An instance method operates on a given instance of a class, whereas a static method does not operate on a given instance.

A static method can access static methods and static fields in its own class. It can also access instance methods and fields, in its own class or any other class, by constructing an object of the required class and accessing the method or field via that object.

For example, the following class contains static and instance methods, and static and instance fields.

       class-id MyCounter.

       01 totalCount binary-long static.
       01 myCount binary-long.

       method-id New.
       procedure division.
           set myCount to totalCount
           set totalCount to totalCount + 1
       end method.

       method-id GetCount.
       procedure division returning returnItem as binary-long.
           set returnItem to myCount
       end method.

       method-id GetTotalCount static.
       procedure division returning returnItem as binary-long.
           set returnItem to totalCount
       end method.

       method-id SetCount static.
       procedure division using by value aCount as binary-long.
           set totalCount to aCount
       end method.
       end class.

Here is the program that invokes the above code:

       program-id StaticInstanceProgram.
       01 myInstance1 type MyCounter.
       01 myInstance2 type MyCounter.

       procedure division.
           invoke type MyCounter::SetCount(10)
           set myInstance1 to new type MyCounter
           set myInstance2 to new type MyCounter
           display myInstance1::GetCount()         *> displays 10
           display myInstance2::GetCount()         *> displays 11
           display type MyCounter::GetTotalCount() *> displays 12

       end program.

To use static and instance methods:

  • To declare a static method, use the STATIC keyword. If the method is in a static class, you must specify STATIC.
  • To declare an instance method, don't use the keyword STATIC.
  • To access a static method, you use the type-specifier for the class, followed by :: and then the method name. For example: type MyCounter::GetTotalCount() as in the above code. If the static method is in the current class, you can omit the type-specifier and the colons.
  • To access an instance method, you use the name of the instance object, then :: followed by the method. For example: myInstance1::GetCount() as in the above code.

Instance Method Modifiers

The following modifiers indicate the extent to which the method inherits and is inherited:

ABSTRACT
declares an abstract method. Abstract methods can only be declared in abstract classes, and must be overridden in any non-abstract class that derives from it.
OVERRIDE

specifies that this method overrides the inherited method of the same name and signature.

REDEFINE

hides the superclass method only when the redefine method is invoked on an item defined as being of the subclass type.

FINAL
prevents a derived class from further overriding the method.

Abstract Methods

An abstract method has no implementation. To use an abstract method, you inherit it and in the inheriting subclass, you provide the implementation of the method. An abstract class can contain methods that are not abstract, as well as abstract ones. The methods that aren't abstract can provide a default implementation, which can be overridden by a subclass method. For example:

class-id MyAbstractClass abstract.
       01 myField  value 0 binary-long property.

       method-id AbstractMethod abstract. *> no implementation
       end method.

       method-id NonAbstractMethod.       *> not abstract
       procedure division.
            set myField to 1   *> Default behavior, which can be overridden
       end method.

       end class.

Non-abstract methods in an abstract class can provide a default implementation, which can be overridden by a subclass method.

       class-id MySubClass inherits type MyAbstractClass.

       method-id AbstractMethod override.
       procedure division.
           *> Subclass method implements abstract method
           display "myField is: " myField  *> displays 0
       end method.

       method-id NonAbstractMethod override.
       procedure division.
           *> Subclass method overrides method that is not abstract
           set myField to 6
           display "myField is: " myField  *> displays 6
       end method.

       end class.

To define and use methods in abstract classes:

  • You use the ABSTRACT keyword to define any members that are abstract, and omit it for members that are not abstract. Abstract members must be within an abstract class.
  • A non-abstract class inheriting an abstract superclass must contain an implementation of all the abstract members of the superclass. However the subclass itself can be abstract an in this case need not contain implementation.
  • Subclass methods which override methods in the superclass must use the keyword OVERRIDE.
  • An abstract method cannot be private. It can be public, protected or internal, or protected internal.

Override Methods

An override method is a method that overrides an inherited virtual method of the same name and signature.

For example, a subclass Circle inherits from a superclass Shape. Both classes contain a Draw method. The Draw method in the Circle subclass overrides the Draw method in the Shape superclass.

       class-id Shape.
       method-id Draw.
           display "let's draw a super shape"
       end method.
       end class.

       class-id Circle inherits type Shape.
       method-id Draw override.
           display "let's draw a circle"
       end method.
       end class.

To define an override method:

  • Specify the OVERRIDE modifier in the method-id header
  • Ensure that the method has the same name and signature as the method to be overridden in the inherited class

You cannot override a final method in the inherited class. You can override only virtual methods (methods not defined as final).

Redefine Methods

The REDEFINE keyword is used to hide a method inherited from a class. To hide an inherited method, declare it in the derived class using the same name and specify REDEFINE.

A redefine method is similar to an override method, in that it is a method with the same name and signature as a method in the superclass. However, unlike an override method, the redefine method might or might not be executed depending on how it is invoked. When the method is invoked on an item defined as being in the:

  • Superclass, even when that item actually holds an instance of the subclass, the superclass method is executed.
  • Subclass - the subclass redefine method is executed.

For example, we have two subclasses Circle and Square, which inherit from the Shapes superclass. All the classes have a Draw method. The Circle class's Draw method overrides the Draw method in the Shapes superclass. The Square class's Draw method redefines the Draw method in the Shapes superclass.

       class-id Shape.
       method-id Draw.
           display "let's draw a super shape"
       end method.
       end class.

       class-id Circle inherits type Shape.
       method-id Draw override.
           display "let's draw a circle"
       end method.
       end class.

       class-id Square inherits type Shape.
       method-id Draw redefine.
           display "let's draw a square"
       end method.
       end class.

You can invoke the Circle and Square classes as follows:

       program-id. RedefineSampleProgram.

       01 myShape type Shape.
       01 myCircle type Circle.
       01 mySquare type Square.

       procedure division.
           set myShape to new type Shape
           set myCircle to new type Circle
           set mySquare to new type Square

           invoke myCircle::Draw   *> Circle Draw method is invoked
           invoke mySquare::Draw   *> Square Draw method is invoked
                                   *> Shape Draw method is hidden, redefined

           set myShape to myCircle *> Superclass instance is set to subclass
           invoke myShape::Draw    *> Circle Draw method is invoked
                                   *> as it overrides Shape Draw method

           set myShape to mySquare *> Superclass instance is set to subclass
           invoke myShape::Draw    *> Shape Draw method is invoked as
                                   *> Square Draw method doesn't override it

       end program.

The above invocations produce the following output:

let’s draw a circle
let’s draw a square
let’s draw a circle
let’s draw a super shape

Another place to use REDEFINE is where the method in the superclass is defined as FINAL and so it cannot be overridden. In this case, you can use REDEFINE to hide the superclass method.

Final Methods

A method that is declared as final is prevented from being overridden in any subclasses. This enables a class to inherit a superclass, while preventing a specific superclass method from being overridden in the subclass.

For example, we have a class MySubClass, which inherits from MySuperClass. MySuperClass has one final method and one virtual (not final) method. The subclass overrides the virtual method, but it cannot inherit or override the final method.

       class-id MySuperClass.

       method-id VirtualMethod. *> Methods are virtual by default
       procedure division.
           display "Virtual method in the superclass"
       end method.

       method-id FinalMethod final. *> Final methods are not virtual
       procedure division.
           display "Final method in the superclass"
       end method.

       end class.

The subclass is defined as follows:

       class-id MySubClass inherits type MySuperClass.

       method-id VirtualMethod override.
       procedure division.
           display "Overridden virtual method in the subclass"
       end method.

      * method-id FinalMethod override.
      *>COBCH0954 Method 'FinalMethod' cannot OVERRIDE a nonvirtual method

       end class.

The classes are invoked as follows:

       program-id FinalOverrideSampleProgram.
       01 mySuper type MySuperClass.
       01 mySub type MySubClass.

       procedure division.
           set mySuper to new type MySuperClass
           invoke mySuper::FinalMethod()
           invoke mySuper::VirtualMethod()

           set mySub to new type MySubClass
           invoke mySub::VirtualMethod()

       end program.

The above sample program produces output as follows:

Final method in the superclass
Virtual method in the superclass
Overridden virtual method in the subclass

Although a final method cannot be overridden in a subclass, it can be redefined in the subclass.

Extension Methods

The EXTENSION keyword declares a method as an extension method.

Extension methods enable you to add methods to existing types without the need to edit or recompile the code. Extension methods appear as additional methods available on an object instance while they are implemented elsewhere.

For example, the following extension method extends the string class, by adding a method to count the number of words in a string:
       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using by value str as string
                          returning wordCount as binary-long.
            set wordCount to str::Split(' ')::Length
       end method.
       end class.

To declare an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.

There is no special syntax for calling extension methods from managed COBOL. You consume an extension method in the same way as any other method, except you specify the first parameter as if it were the instance on which the method is called:

parameter-1::method-name(more parameters)

In JVM COBOL, there are two extensions that are preloaded before compilation:

  • An extension operator for string equality
  • An extension method for substring

These two extensions ensure that managed COBOL produces the same results, regardless of whether it is compiled to JVM COBOL or .NET COBOL. For more detail, see Extension Methods and Operators.

Synchronized Methods

The SYNC modifier locks the values of the arguments sent to the method, so that they do not change while the method is processing.

When an argument is sent to a method and is received as a reference parameter, the value of the parameter and its corresponding sending argument might be updated. Without the SYNC modifier, the value of the sending argument is unknown, while the method is processing.

The SYNC modifier on a method is equivalent to wrapping the whole method in a SYNC statement.

For example:

       01 a binary-long value 20.
       ...
       invoke Adjust(a)
       display a                 *> displays 93

       method-id Adjust sync (reference x as binary-long).
           set x to x + 73
       end method.
       end class.

In the above example, the SYNC modifier is applied to the method Adjust(). This ensures that the variables within the method (in this case, the variable x locally, but variable a in the invoking code) cannot be accessed until the method has finished processing.

Explicit Interface Implementation

If the FOR clause is specified, this method is an Explicit Interface Member Implementation. The method may not be invoked explicitly. It will be invoked implicitly when the corresponding method is invoked on an instance of this class which has been cast to the interface type.

Use of explicit interface implementation (via the FOR clause) is particularly useful when the class implements two different interfaces, and these two interfaces have a method with the same name and signature. In this case, by using the FOR phrase, you can supply two different implementations of the method for the two different interfaces.
For example:
interface-id. "IAlarm1".
method-id checkAlarm.
procedure division using atime as binary-long.
end method.
end interface.

interface-id. "IAlarm2".
method-id checkAlarm.
procedure division using atime as binary-long.
end method.
end interface.

class-id BasicAlarm implements type IAlarm1 type IAlarm2.

method-id checkAlarm for type IAlarm1.
procedure division using atime as binary-long.
...
end method.

method-id checkAlarm for type IAlarm2.
procedure division using atime as binary-long.
...
end method.
end class.

Asynchronous Methods

Note: Only supported in .NET COBOL.

.NET COBOL utilizes the .NET async and await syntax to enable you to write responsive applications.

Asynchronous programming enables you to create tasks in your application that run independently from the main application thread. This means that when a task is busy, it executes in a different thread and your application remains responsive. After completion, the result of the task can be accessed by the caller.

Asynchronous programming is especially useful in applications that perform operations taking a long time to complete. These could be applications that handle web requests where you need the interface to stay responsive, or desktop applications that process big data or multiple resources.

You can create asynchronous applications by using the ASYNC and AWAIT syntax which indicate the method and the asynchronous operation it is waiting for. With it being simple enough for the programmer, the Compiler handles all the complicated work of running the asynchronous operation in a different thread, while the application continues to run in the main thread. The Compiler also ensures the correct operations are executed when the control is returned to the method at the await place.

In the following example, the ASYNC keyword indicates that your method is an asynchronous one. When execution reaches the AWAIT call, control is given to the .NET Task method that performs a delay of 1000ms. After the delay, control is given back to the method:

method-id ProcessItemsAsync async (#type as string,
                                   #count as binary-long)
                            yielding items as string occurs any.
     invoke await type Task::Delay(1000)
     set items to table of ("a", "b", "c")
 end method.

Use the AWAIT keyword to begin an asynchronous operation and then continue executing the method after it completes. In the code below, the asynchronous operation is a delay performed by the Delay method of the Task threading class:

invoke await type Task::Delay(1000)

Task belongs to the System.Threading.Tasks namespace which includes types for writing asynchronous code. Task includes a number of methods that are useful for running code asynchronously.

The example below shows the result of ProcessItemsAsync being moved to items after completion:

declare items = await ProcessItemsAsync("user", 8)

Use async-void with an event handler that uses await statements. In the following example, the button is disabled with an artificial delay. The operation is asynchronous so the rest of your code will continue to execute after the delay of 1000ms without blocking the UI thread:

method-id button1_Click async-void (sender as object,
                                    e as type EventArgs).
     set button1::Enabled to false
     invoke await type Task::Delay(1000)
     set button1::Enabled to true
 end method.

The following example shows an async method which does not return a result:

method-id Task ProcessAsync() async.
     invoke await type Task::Yield()
     invoke type Console::WriteLine("async...")
 end method.

The following async method returns a result:

method-id ProcessItemsAsync async (#type as string,
                                   #count as binary-long)
                            yielding items as string occurs any.
     invoke await type Task::Delay(1000)
     set items to table of ("a", "b", "c")
 end method.

Use the async-value keyword if your method should return a value task.

Note: In order to use async-value, your project must include a reference to System.Threading.Extensions.dll - preferably using a NuGet (the .NET package manager utility) package reference. The required NuGet package is: https://www.nuget.org/packages/System.Threading.Tasks.Extensions/.
method-id AProcess async-value (x as condition-value)
                   yielding result as string.
     if x
         invoke await type Task::Delay(1000)
         set result to "x"
     else
         set result to "y"
     end-if
 end method.
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Constructors
Access Modifiers
Attributes
Procedure Division
INVOKE Statement
SET Statement
Related information
Extension Methods and Operators
Method Overloading in Managed COBOL
Methods - in COBOL and Java
Constructors and Destructors - in COBOL and Java
Invoking a Method
Extension Methods and Operators


Operators

A set of default operators are predefined and implemented. You can overload an operator and define your own behavior for it.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

operator-specification

operator-header procedure-division

operator-header

operator-name attribute-clause

operator-name

binary-operator
comparison-operator arithmetic-operator bitwise-operator
  • =
  • <>
  • <=
  • <
  • >=
  • >
  • +
  • -
  • *
  • /
  • **
  • B-AND
  • B-OR
  • B-XOR
  • B-LEFT
  • B-RIGHT
unary-operator
  • +
  • -
  • B-NOT
  • EXPLICIT
  • IMPLICIT

Example

class-id MyType.
operator-id +
procedure division using by value o as type MyType, I as binary-long
                           returning ret as type MyType.
  ...
end operator.
end class.

See also the Operator Overloading sample, available from $COBDIR/demo.

Conversion Operators, IMPLICIT and EXPLICIT

Conversion operators can be overloaded, so that the appropriate conversion operator is used according to the parameter types in the calling code. The operator with the matching signature (procedure division using clause) is executed. For example, where a data item of type Timer requires converting to binary-long, the operator used is the operator with an input parameter of type Timer and output parameter of binary-long.

To define and use conversion operators:

  • Use the IMPLICIT or EXPLICIT keyword on the operator-id header
  • The operator converts the types specified in the operator's signature (its procedure division using clause)
  • The types converted can be either classes or value-types, but not interfaces
  • Types that inherits from one another cannot be converted using a conversion operator
  • The same conversion cannot be defined twice: once as implicit and as explicit

Operator Overloading

You can overload operators to provide alternative behavior, or behavior for different operand types. For example, where a Timer type is expressed as hours and minutes, you could define one + (plus) operator to add two Timers and another + (plus) operator to add a number of minutes to a Timer type.

To declare overloaded operators:

  • Overloaded operators are public and static.
  • The parameters in the operator's signature must be declared by value. They must have a returning item.
  • The following operators can be overloaded, and require the following operator-id signatures:
Operators that can be overloaded | Overload operator-id signature | Notes
Comparison operators, such as: t1 = t2, t1 equals t2 | value t1 t2 returning condition-value | Comparison operators must be specified in pairs where the pairs are - equality (=) and inequality (<>) operators, greater than (>) and less than (<) operators, and greater than or equal to (>=) and less than or equal to (<=) operators. The returning item must be of type condition-value.
Other binary operators, such as: t1 + t2 | value t1 t2 returning t3 | Binary operators have two arguments. If the two arguments are of different type, you need to specify a pair of operators to enable the two operands to be passed in either order.
Unary operators, such as: -t1 | value t1 returning t3 | Unary operators have only one argument.

While the arithmetic operators for addition, subtraction, multiplication and division can all be overloaded, their verb equivalents cannot. For example, ADD in the following statement cannot be overloaded:

       add a to b giving c
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Attributes
Type Specifier
Related information
Operators - in COBOL and Java
Operator Overloading in Managed COBOL


Procedure Division

The procedure division defines the code to be executed when a type or member is invoked. The procedure division header defines any parameters to pass in to the code and any returning item to pass back.

Context:

    Methods
    Constructors
    Iterators
    Operators

procedure-division

procedure-division-header statement-block

procedure-division-header

attribute-clause attribute-clause attribute-clause attribute-clause attribute-clause

See the Core sample, which is available from $COBDIR/demo.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Constructors


Procedure Division Header

You can specify the parameters, both passed to a member and items returned, in either the method signature or the procedure division header. If the parameters are specified in the method signature, the procedure division header must be omitted from the method.

See method signature for more information about parameter specification.

Context:

    Procedure Division
    Delegates and Events
    Indexers

procedure-division-header

attribute-clause attribute-clause attribute-clause attribute-clause attribute-clause

See the Core sample, which is available from $COBDIR/demo.

Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
INVOKE Statement
Local Data Item Declaration
METHODDEFAULT
ILPARAMS
Method Signature
Related information
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Types and Type Conversion
Type Mappings from Native COBOL to Managed Code


Properties

Properties are members with associated types. They are similar to fields but they have accessors that provide the means to read and write values.

Context:

    Classes
    ValueTypes
    Interfaces
        Type Members

property-specification

property-header procedure-division-header access-modifier statement-block access-modifier statement-block

property-header

type-specifier access-modifier attribute-clause

Example

class-id MyClass.
working-storage section.
01 volume binary-long private.
property-id Volume binary-long.
  getter.
    set property-value to volume
  setter.
    if property-value < 0
      set volume to 0
    else
      set volume to property-value
    end-if
end property.
end class.
property-id PropertyReadOnly string.
  getter.
    set property-value to field-5
end property.

See also the Properties sample, available from $COBDIR/demo.

Further Information

A property specified using PROPERTY-ID must contain a get or set accessor (or both), using the GETTER and SETTER keywords respectively. The Compiler then generates get_ and set_ methods accordingly.

There are two ways of exposing a field as a property within a COBOL program:

  • The simplest way is to specify the keyword PROPERTY on any data declaration within the program. This automatically sets up two accessor methods for getting and setting the value of the data item. There are optional phrases that follow the PROPERTY keyword that you can use to suppress either the get or the set accessor. You can also use the AS clause to change the external name.
  • The alternative way is to specify a PROPERTY-ID with the GETTER or SETTER phrases to be executed whenever the property is accessed. This mechanism, though slightly more complicated than the PROPERTY keyword, gives you complete control over the statements that are executed when the property is accessed. See PROPERTY Keyword

The FOR Clause

Use the FOR clause as an explicit interface implementation, which is particularly useful when the containing class implements two different interfaces, and these two interfaces have PROPERTY-IDs with the same name and type. In this case, by using the FOR phrase, you can supply two different implementations of the PROPERTY-IDs for the two different interfaces.

property-id PropertyReadOnly string FOR MyInterface1.
  getter.
    set property-value to field-1
end property.
property-id PropertyReadOnly string FOR MyInterface2.
  getter.
    set property-value to field-2
end property.
Parent topic: Structural Syntax Elements - Alphabetic List
Related reference
Indexers
Access Modifiers
Attributes
Constraints Paragraph
Fields
Type Specifier
Related information
Properties - in COBOL and Java


Type Members

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

static-or-instance-member

method-specification constructor-specification property-specification indexer-specification operator-specification iterator-specification
Parent topic: Structural Syntax Elements - Alphabetic List


Common Syntax Elements

  • Access Modifiers
    The access modifiers of an item control the visibility (accessibility) of the item to other code. For example, you can call public methods from anywhere, whereas private methods can be called only from other methods within the same type.
  • Assembly-Attributes Paragraph
    The Assembly-Attributes paragraph allows you to specify assembly-wide attributes.
  • Attributes
    Attributes are used to provide additional information about elements within your program.
  • Constraints Paragraph
    The Constraints paragraph allows specification of properties of the type parameters of a generic type or method, and therefore allows the use of methods or properties on data items whose type is specified as that parameter.
  • Method Signature
    The method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature.
  • Expressions
    An expression is classified as a primary expression, an arithmetic expression, or a conditional expression. Arithmetic and conditional expressions are made up from a sequence of primary expressions separated by operators.
  • Generic Using Phrase
    Generic types and methods can be defined in COBOL with the USING phrase.
  • Local Data Item Declaration
    Local data items are data items (also known as variables) that are declared in the procedure division body.
  • Type Specifier
    A type specifier is a declaration of a type, such as a class, interface, enum and so on.
Parent topic: Managed COBOL Reference


Access Modifiers

The access modifiers of an item control the visibility (accessibility) of the item to other code. For example, you can call public methods from anywhere, whereas private methods can be called only from other methods within the same type.

Context:

    Classes
    ValueTypes
    Interfaces
    Delegates and Events
    Enums

    Fields

    Methods
    Properties
    Indexers
    Iterators

access-modifier

Further Information

By default, all types and members are PUBLIC, with the exception of fields which are PRIVATE.

The modifier affects the visibility of an item as follows:

Modifier: | Item is visible:
PUBLIC | always
PRIVATE | when the calling type is the same as the target type
PROTECTED | when the calling type inherits from the target type.
INTERNAL | when the calling type is in the same assembly as the target (.NET), or when the calling type has the same namespace as the target (JVM).
PROTECTED INTERNAL or INTERNAL PROTECTED | when the calling type derives from the target type, or the calling type is in the same assembly as the target
PUBLIC
Indicates that this item may be accessed from any code.
PRIVATE
Indicates that this item may be accessed only from within the containing type.
PROTECTED
Indicates that this item may be accessed only from within the containing type or from a subtype that inherits from the containing type. You cannot specify PROTECTED on an abstract member. PROTECTED restricts access within an inheritance tree. For example, a protected field in a superclass can be accessed from any subclass, but it can't be accessed from a class outside the inheritance tree.
INTERNAL
Indicates that this item may be accessed only from within the current compilation unit.
PROTECTED INTERNAL or INTERNAL PROTECTED
Indicates that this item may be accessed only from within the containing type, from a subtype that inherits from the containing type, or from within the current compilation unit.
Parent topic: Common Syntax Elements
Related reference
Constraints Paragraph
Classes
Delegates and Events
Enums
Indexers
Interfaces
Iterators
Properties
ValueTypes
Fields
Related information
Comparison of COBOL with Other Managed Languages


Assembly-Attributes Paragraph

The Assembly-Attributes paragraph allows you to specify assembly-wide attributes.
Note: This syntax is supported for .NET COBOL only.

assembly-attributes-paragraph

Example

Class-id myClass.

ASSEMBLY-ATTRIBUTES.  *> Define an attribute on an assembly
 attribute CLSCompliant(true).

Method-id myMethod.
...
end method.
end class.
Parent topic: Common Syntax Elements


Attributes

Attributes are used to provide additional information about elements within your program.

Context:

    Classes
    ValueTypes
    Interfaces
    Delegates and Events
    Enums

    Fields

    Methods
    Constructors
    Properties
    Indexers
    Operators
    Iterators

attribute-clause

constructor-parameters property-name = property-value

Example

*> Attribute on a class
class-id Attributes
    attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a field
01 book string attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a property
01 bookProperty string property
    attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a method and argument
method-id GetAnotherBook
    attribute Author(name AuthorName = "Benjamin Franklin")
    (arg1 as string
        attribute Author(name AuthorName = "Benjamin Franklin"))
    returning return-value as string.
        set return-value to book
end method.

end class.

*> Attribute definition
 attribute-id AuthorAttribute public.
 01 AuthorName string property.

end attribute.

To Specify Attributes

You can specify attributes using:

constructor parameters
These specify the parameters of a constructor for that attribute. The constructor parameters used in the attribute specification must match a constructor defined by the attribute. In the following example, the constructor expects a single parameter of type string:
 01 a binary-long attribute xml("UpperB").
NAME property-name = property-value
These are named parameters and correspond to properties defined on the attribute class. The named parameters must match properties defined by the attribute. In the following example, Description is a property of type string defined for the attribute class WebService:
attribute WebService(NAME Description="My service")

About Attributes

Attributes (also known as custom attributes) are used to provide additional information about elements within your program. Attributes may be used to describe methods, data items, properties, events, delegates, method parameters, assemblies, classes and method return values.

Much of the syntax used in a COBOL program describes program elements, such as the visibility of methods and fields (such as PUBLIC, PRIVATE and PROTECTED). All these descriptions are embedded as ‘Metadata’ into the dll or exe file output by the Compiler, and can be interrogated by other programs using Reflection. Attributes are a way of adding additional metadata to program elements in a way that is open ended and unlimited.

The attribute specified becomes part of the metadata describing the subject of the entry and is visible to a reflector.

Parent topic: Common Syntax Elements
Related reference
Constraints Paragraph
Classes
Constructors
Delegates and Events
Enums
Indexers
Interfaces
Iterators
Operators
Properties
ValueTypes
Fields
Related information
Attributes - in COBOL and Java


Constraints Paragraph

The Constraints paragraph allows specification of properties of the type parameters of a generic type or method, and therefore allows the use of methods or properties on data items whose type is specified as that parameter.

Context:

    Classes
     ValueTypes
     Interfaces
     Methods

constraints-paragraph

type-specifier type-specifier

Example

The following shows a static generic method with a USING phrase that declares the generic argument T. This generic argument is constrained to implement the type System.IComparable. The method expects two parameters both of which must be of the same type as the generic argument.

       method-id Min using T static.
       constraints.
           constrain T implements type System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item1
           else
               set res to item2
           end-if
       end method.

In this case the CompareTo method may be invoked since T is known to implement the IComparable interface.

Parent topic: Common Syntax Elements
Related reference
Access Modifiers
Attributes
Classes
Interfaces
Properties
ValueTypes
Generic Using Phrase
Related information
Generics, Defining - in COBOL and Java


Method Signature

The method signature enables you to specify passing parameters and returning items within the header of certain elements. You must omit the procedure division header within the method if you use this signature.

Context:

   Constructors
   Delegates and Events
   Indexers
   Iterators
   Methods

signature

  • Each parameter must specify a parameter passing mode before it, otherwise passing mode defaults to by VALUE.
  • If you are passing a parameter by PARAMS, it must be last, and must be a one-dimensional array.
  • Indexers or constructors cannot specify returning items.
  • Iterators specify YIELDING items, not RETURNING items; for example, iterator-id GetEven yielding res as binary-long static.

Parameters

Parameters are values or variable references that are passed to a method. They can be specified in the method header or in the procedure division header. If they are specified in the method header, you must omit the procedure division header from the method.

The actual values of the parameters are specified when the method is invoked.

Typically, when you invoke a method, you specify the parameters in the invocation, and the invoked method receives the parameters in the same order as in the invocation. For example:

       invoke type MyClass::MyMethod(a,b)
       ...
       method-id MyMethod (x as string y as binary-long).
       ...
       end method.

The arguments a and b above are passed to the invoked method, and these correspond to the parameters x and y respectively, in the invoked method. The types of the parameters are specified in the AS phrase.

If you use named parameters, the invocation does not need to specify them in the same order as they are specified in the method header.
       invoke type MyClass::MyMethod(param y = 3.141592, param x = "Pi")
       ...
       method-id MyMethod (value x as string, y as decimal).
       ...
       end method.

As long as the parameters x and y are named during invocation, the invoked method receives and uses them appropriately. If you use a mixture of positional and named arguments during invocation, the named arguments must be specified after any positional arguments.

If your method contains optional parameters (also known as default parameters), you do not need to pass all the arguments during invocation. The default values specified in the method signature are used.
       invoke type MyClass::MyMethod(a)
       ...
       method-id MyMethod (value x as string, y as decimal = 3.141592).
       ...
       end method.

The invocation above only passes one positional argument (which corresponds to parameter x), so the value specified for optional parameter y is used in the method. Optional parameters can only be used as value parameters.

Parameter passing mode

Parameters are passed into a method using one of the following modes, specified after the USING phrase:

  • VALUE. Parameters that are passed by value do not pass back any changes in value to the invoking code.
  • REFERENCE. Parameters that are passed by reference pass back any changes to their value during execution of the method, to the invoking code when the method finishes. These are used for both input and output.
  • OUTPUT. This mode is similar to REFERENCE. The main difference is that parameters don't need to be assigned on entry to the method, but they must be assigned on exit from the method.
  • PARAMS. Only one parameter may be passed using PARAMS mode. It must be a single dimensional array and it must be the last input parameter.

If no passing mode is specified, parameters specified in the method header use the VALUE mode by default, and parameters specified in the procedure division header use the REFERENCE mode by default (except in extension methods where they are passed by value). You can change the default by setting the METHODDEFAULT Compiler directive.

When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters. In the following example, v and vv are passed by value, and the others are passed by reference:

       procedure division using a as binary-long
                          value v as binary-long
                                vv as binary-long
                      reference r as binary-long
                                rr as binary-long.

VALUE Parameters

A value parameter behaves like a local variable. Its initial value is established when the method is invoked. When the method processes, it can change the value of the local variable. When the method finishes, the original argument in the invoking code remains unchanged. For example:

       declare a as binary-long = 3
       invoke type MyUtils::CheckByValue(a)
       display a              *> a is still 3

       method-id CheckByValue static (x as binary-long).
       set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by value. The invoked method increments the value. However, on return to the invoking code, the variable a remains unchanged.

Usage:

  • Use a value parameter for input to a method, and when you don't need to output the parameter from the method.
  • Value parameters that are managed types are exposed as the corresponding COBOL types. For example, signed numeric items with no implied decimal point are exposed as int8, int16, int32, int64, depending on the size.

    Value parameters that are not managed types but are other COBOL data types are exposed as defined in the COBOL Type Compatibility table. For example: PIC X fields and groups are exposed as string. See Type Compatibility of .NET and JVM COBOL with Other Managed Languages.

  • Value parameters may include the optional syntax '= constant-expression'. Such parameters are optional parameters, and the expression represents the value in the case where the parameter is not supplied by the invoking code.

    All optional parameters must be specified following any non-optional parameters.

REFERENCE Parameters

A reference parameter contains a reference to the required value rather than the value itself.

A reference parameter corresponds to a local variable, whose value is established when the method is invoked, and whose value can change while the method is processing. Unlike a value parameter, when the method finishes, the value of the original argument in the invoking code is changed accordingly.

Note, that a reference parameter does not necessarily create a copy of the variable local to the method. Instead, it might refer to the original argument in the location in use when the method was invoked. While the method is processing, the variable can change locally, but the original argument in the invoking code does not necessarily change. It might change or it might not. The value of the original argument is unknown until the method finishes. When the method finishes and returns to the invoking code, the value of the original argument in the invoking code is updated.

For example:

       declare a as binary-long=3
       invoke type MyUtils::CheckByReference(a)
       display a              *> a is now 4

       method-id CheckByReference static (reference x as binary-long).
       set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by reference. The invoked method increments the variable a. On return to the invoking code, the variable a is updated with the incremented value.

Usage:

  • Use a reference parameter for both input and output. Use it to input a value to the method and to output the resulting value to the invoking code.
  • Parameters are passed by reference by default, except where the previous parameter in the method signature is not a reference parameter. In this case, the keyword REFERENCE is required.
  • While the method is running, the value of a sending argument that corresponds to a reference parameter might change. The value is unknown. To lock the sending argument so that it does not change while the method is running, use the SYNC clause. When the method finishes, the lock is released and the sending argument is updated as necessary.
  • Reference parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.

    Reference parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers .

OUTPUT Parameters

Like reference parameters, output parameters don't create a new storage location, but use the storage location of the variable specified on the invocation.

Output parameters are very similar to reference parameters. The main difference is that they must be assigned before returning to the invoking code.

For example:

       declare a as binary-long=4
       declare b as binary-long
       invoke type MyUtils::CheckByOutput(a,b)
       display "Value Param a = " &  a          *> a is still 4
       display "Output Param b = " & b          *> b is 16

       method-id CheckByOutput static (x as binary-long, output y as binary-long).
           set x to x + 10     *> x is now 14
           set y to x + 2      *> y is now 16
       end method.

In the above example, two parameters are passed, where variable b is not initialized and is passed by output. The method CheckByOutput updates the variables x and y. On return, the output variable b is updated but the variable a remains unchanged.

Usage:

  • Typically used in methods where there are multiple return values.
  • Can optionally be initialized or assigned a value for input to the method.
  • Must be assigned for return, when the method finishes.
  • Output parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.

    Output parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers.

PARAMS Parameters

Only one parameter may be passed with the PARAMS keyword, and it must be the last parameter. The parameter type must be a single dimensional array.

Programs that invoke this method may pass this parameter in the normal way as an array of the given type. Alternatively the program may pass zero or more parameters corresponding to the PARAMS parameter, where each parameter passed has the same type (or a compatible type) as the element type of the array. In this case the compiler will automatically generate code to create an array from the specified parameters (containing 0 or more elements), and pass this array to the invoked method.

RETURNING Items

Returning items pass the results of a method back to the invoking code. For example:

       method-id AddMins (a as type MyTimer, b as binary-long) returning c as type MyTimer.

Each method can have only one returning item. However you can package a set of return information in an object. For example, the following AddMins() method receives and returns an instance of type myTime :

       program-id ParamAsObject.
       01 myTime type MyTimer value new MyTimer(5 45).

       procedure division.
           set myTime to myTime::AddMins(myTime 70) *> inline invocation
           display myTime::anHour & ":" myTime::aMin
       end program.

       class-id MyTimer.
       01 anHour binary-long property.  *> property keyword enables get/set
       01 aMin binary-long property.
       ...
       method-id AddMins (a as type MyTimer, b as binary-long) returning c as type MyTimer.
       01 h binary-long value 0.
       01 m binary-long value 0.
           set b to a::aMin + b
           divide b by 60 giving h remainder m
           set c to new MyTimer(a::anHour + h , m)
       end method.

       end class.
Parent topic: Common Syntax Elements
Related reference
Procedure Division Header


Expressions

An expression is classified as a primary expression, an arithmetic expression, or a conditional expression. Arithmetic and conditional expressions are made up from a sequence of primary expressions separated by operators.
primary-expression unary-expression binary-expression

primary-expressions

 literal
 data-item
 Parenthesized-expression
 non-parameterized-member-access
 method-invocation-expression
 chained-constructor
 object-creation-expression
 delegate-invocation-expression
 subscript-expression
 reference-modification-expression
 concatenation-expression
 cast-expression
 type-of-expression
 anonymous-method-expression
 method-group-expression
 arithmetic-expression
 size-of-expression
 table-of-expression
 unary-expression
 binary-expression
 conditional-expression
 await-expression

literal

data-item

Parenthesized-expression

non-parameterized-member-access

type-specifier

method-invocation-expression

type-specifier Procedure Division HeaderYou can specify the parameters, both passed to a member and items returned, in either the method signature or the procedure division header. If the parameters are specified in the method signature, the procedure division header must be omitted from the method.

Where:

positional-argument
an expression corresponding to the parameter in the same position in the method definition.
param-name
the name of a parameter as defined in the method definition, not corresponding to one of the positional-arguments.

Any parameter defined by the method that does not correspond either to one of the positional arguments, or to one of the named arguments, must be an optional parameter (i.e. a parameter with a default value).

chained-constructor

type-specifier Procedure Division HeaderYou can specify the parameters, both passed to a member and items returned, in either the method signature or the procedure division header. If the parameters are specified in the method signature, the procedure division header must be omitted from the method.

Where:

positional-argument
an expression corresponding to the parameter in the same position in the constructor definition.
param-name
the name of a parameter as defined in the constructor definition, not corresponding to one of the positional-arguments.

None of positional-argument, named-argument, or property-initializer should reference instance data or local data. Typically they reference arguments of the current constructor.

Object-creation-expression

Type Specifier - syntax

Where:

positional-argument
An expression corresponding to the parameter in the same position in the constructor definition.
param-name
the name of a parameter as defined in the constructor definition, not corresponding to one of the positional-arguments.
Property-name
The name of an instance property associated with the class being constructed. Following the construction of the new object, the property with that name will be initialized to the value of the property-initializer.

Any parameter defined by the constructor that does not correspond either to one of the positional arguments, or to one of the named arguments, must be an optional parameter (i.e. a parameter with a default value).

Delegate-invocation-expression

Where:

primary-expression
Must resolve to an object of delegate type.
positional-argument
An expression corresponding to the parameter in the same position in the delegate definition.
param-name
The name of a parameter as defined in the delegate definition, not corresponding to one of the positional-arguments.

Any parameter defined by the delegate that does not correspond either to one of the positional arguments, or to one of the named arguments, must be an optional parameter (i.e. a parameter with a default value).

subscript-expression

[ subscript ] ( subscript )

Where:

[ subscript... ]
Square brackets [ ] indicate that the subscript is zero based. For example:
     myArray[5]   *> sixth item in the array

Square brackets can also be used to pass the parameters to an indexer expression.

( subscript... )
Round parentheses ( ) indicate that the subscript is one based. For example:
     myArray(5)   *> fifth item in the array
This form of subscript expression is only available for items defined in the COBOL program using the OCCURS clause. It cannot be used to access elements of an array returned by a member access or a method invocation expression. Nor can it be used to access an indexer.

Reference-modification-expression

The primary expression must be of type string. The offset must be of integral type. The length expression may be omitted but, if specified, must be of integral type.

The result of a reference modification expression is a string value formed by taking a substring of the original string starting from the specified offset (0 based), for the specified length, or until the end of the original string if length expression is omitted.

If the offset expression, or the sum of the offset expression and the length expression, is greater than the original string length an exception is thrown.

Concatenation-expression

where the right-hand primary-expression is not itself a concatenation expression. The result of a concatenation expression is a string value formed by concatenating all the operands. If any operand is not itself of type string, the ToString (.NET) or toString(JVM) method is applied to the operand before it participates in the concatenation.

Cast-expression

The cast expression is used to specify an explicit conversion, for example, reference type conversion or explicit user conversion. If you do not specify the optional IF and the cast fails, an exception is thrown (InvalidCastException for .NET or ClassCastException for JVM); if you specify IF and the cast fails, no exception is thrown and the target object is set to null. See the Explicit reference conversions section for more information.

Type-of-expression

Anonymous-method-expression

DELEGATE
procedure-division
END-DELEGATE

The procedure division may start with a procedure division header, which can specify zero or more parameters and an optional returning item.

Method-group-expression

The expression represents any of the methods with the given name belonging to the specified type. For instance methods, the method group expression also encapsulates an object instance.

Method group expressions are implicitly converted to a delegate type by selecting the member of the method group which is compatible with the delegate type.

Example:

01 del type MyDelegate.
01 o type MyType.
set del to method o::Meth1

The compiler will set del to point to the override of Meth1 in MyType, which has the same signature as MyDelegate.

Arithmetic-expression

An arithmetic expression may be either a unary expression or a binary expression. In both cases, the expressions which are subject to operations may be:

  • Numeric expressions.
  • Expressions of a type for which a suitable operator overload has been defined.
  • In the case of binary +, the left expression may be an enum type and the right expression an integral type, or vice versa. The result is of the same enum type.
  • In the case of binary -, both expressions may be of the same enum type, or the left expression may be an enum type and the right expression an integral type. The result in the first case is a value whose type is that of the underlying type of the enum. In the second case, the result is of the same enum type.
  • In the case of binary b-and, b-or and b-xor, both expressions may be of the same enum type. The result is of the same enum type.
  • In the case of binary + and binary -, both expressions may be of the same delegate type or one expression may be a delegate type and the other a compatible anonymous method or method group. The result is of the same delegate type.

Size-of-expression

where expression can be one of the following:
  • An item of type string
  • A managed single-dimensional array of any type
  • An item of a collection type
Note: The word OF in the SIZE OF phrase is normally optional, but is required in the case of a DISPLAY statement, where the expression is not the first DISPLAY operand.

Table-of-expression

Helps create an array inline in managed COBOL.

For example:

set myArray to table of ( "abc", "bcd" )

This is equivalent to:

set content of myArray to ( "abc", "bcd" )

An example of creating a multi-dimensional array:

declare myArray as string occurs any any = table of string (
               ("abc", "def")
               ("ghi", "jkl")
           )
Note: Multi-dimensional arrays do not exist in JVM environments.

unary-expression

unary-operator

Where unary-operator is one of '+', '-', or 'b-not'.

binary-expression

binary-operator

Where binary-operator is one of '+', '-', '*', '/', '**', 'b-and', 'b-or', 'b-xor', 'b-left', or 'b-right'.

When the binary-expression contains more than one binary operator, the order in which the operations are performed is determined by operator precedence as follows:
  1. Shift right and shift left (b-right and b-left)
  2. binary or (b-or)
  3. binary xor (b-xor)
  4. binary and (b-and)
  5. Exponentiation (**)
  6. Multiplication and division( * and /)
  7. Addition and subtraction (* and -)

The order of evaluation can be modified by making use of parenthesized expressions.

Conditional-expression

A conditional expression may be a primary conditional expression or a combined conditional expression.

A primary conditional expression may be:

  • An arithmetic expression evaluating to a boolean type
  • A relational condition, consisting of two arithmetic expressions separated by a relational operator
  • A negated primary conditional expression
  • A conditional expression enclosed in parentheses
  • An INSTANCE OF expression
  • A CONTAINS expression

A relational operator is one of the following, where each line includes variants for the same operator.

= |  | EQUALS
<> | NOT= | NOT EQUALS
> |  | GREATER [THAN]
< |  | LESS [THAN]
>= | NOT< | GREATER [THAN] OR EQUAL NOT LESS [THAN]
<= | NOT> | LESS [THAN] OR EQUAL NOT GREATER [THAN]

An INSTANCE OF expression is of the form:

A CONTAINS expression is of the form:

where expression-1 evaluates to either:

  • An object of type DICTIONARY and expression-2 evaluates to an object whose type is the key type of the dictionary, or
  • an object of type LIST and expression-2 evaluates to an object whose type is the element type of the list.

Await-expression

Note: Only applies to .NET COBOL.

The type of primary-expression must implement the method GetAwaiter(). If the type returned by this GetAwaiter method has a GetResult method, then the type of the await-expression is the same as the type returned by this GetResult method. Otherwise, the type of the await-expression is void.

A void await-expression can be specified by using an INVOKE statement:

A non-void await-expression can be used wherever an expression of its resolved type can be used.

In most cases, the type of the primary-expression will be one of System.Threading.Tasks.Task or System.Threading.Tasks.Task[T], which satisfy the above conditions. In the first case, the type of the await-expression is void, and in the second case the type of the await-expression is T.

Parent topic: Common Syntax Elements
Related information
Types and Type Conversion


Generic Using Phrase

Generic types and methods can be defined in COBOL with the USING phrase.

Context:

    Classes
    ValueTypes
    Interfaces
    Methods
    Iterators

generic-using-phrase

generic-argument

generic-argument

generic-argument conventionally has a single character upper case name such as T and U.

Example

In this example, the main method finds and displays the greater and the smaller number from two ones. T is a generic argument to the Min method, which in this case is a static generic method. The Min method expects two parameters both of which should be of the same type as the generic parameter. The CompareTo method may be invoked since T is known to implement the IComparable interface.

       class-id GenericMath.

       method-id main static.
       01 n1 binary-double.
       01 n2 binary-double.
           set n1 to 999
           set n2 to 100
           display n1 space n2
           display Min[binary-double](n1 n2)
           display Max[binary-double](n1 n2)
           goback.
       end method.
       method-id Min using T static.
       constraints.
           constrain T implements type System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item1
           else
               set res to item2
           end-if
       end method.
       method-id Max using T static.
       constraints.
           constrain T implements type System.IComparable.
       procedure division using by value item1 as T item2 as T
                      returning res as T.
           if item1::CompareTo(item2) < 0
               set res to item2
           else
               set res to item1
           end-if
       end method.

       end class.
Parent topic: Common Syntax Elements
Related reference
Constraints Paragraph
Related information
Generics, Defining - in COBOL and Java


Local Data Item Declaration

Local data items are data items (also known as variables) that are declared in the procedure division body.

Context

    Procedure Division
        DECLARE Statement
        PERFORM Statement
        TRY Statement

local-declaration

type-specifier

Example

       declare i1 as binary-long
       display i1

       *>   Optionally, the variables can be initialised inline
        declare c2 as condition-value = true
        display c2

        declare string-list2 as string occurs 3 = table of string("Bill", "Ben", "LittleWeed")

      **************************************************************************
      * Iteration Variables
      **************************************************************************

      *>   A variable can be declared at the point of use in an iterator.
      *>   In this case the scope of i will be until the end-perform.
           perform varying i as binary-long from 1 by 1 until i > 10
               display i
           end-perform

      **************************************************************************
      * Exception Variables
      **************************************************************************

      *>   The example below shows that you can declare e at the point of use.
      *>   It is in scope until the end-try.
           try
               display "exception test"
           catch e as type Exception
               display e::Message
           end-try

See also the Local Variables sample, which is available from $COBDIR/demo.

Further Information

The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.

Parent topic: Common Syntax Elements
Related reference
DECLARE Statement
Type Specifier
Procedure Division Header
Fields
Related information
Data Types - in COBOL and Java


Type Specifier

A type specifier is a declaration of a type, such as a class, interface, enum and so on.

Context:

    Classes
    ValueTypes
    Interfaces
    Enums
    Properties
    Indexers
    Fields

type-specifier

simple-type-specifier

simple-type-specifier

predefined-type-specifier

predefined-type-specifier

Example

Predefined Types
  01 dAmount  decimal.
  01 asNames string occurs 5.
  01 abFigures binary-long occurs any.
TYPE keyword
  01 objMyType type MyType.
  01 objDataTime type DateTime.        *> .NET COBOL
  01 objDataTime type java.util.Date.  *> JVM COBOL

Where:

  • objMyType is defined as an object of type MyType
  • objDataTime is defined as an object type DateTime in .NET COBOL or java.util.Date in JVM COBOL.

Long Type Names

To define a namespace to represent long class names so that you need to type a short name only, use the ILUSING directive.

Type Compatibility with Managed Types

All the predefined COBOL data types and any further managed types that you define are mapped onto the corresponding native managed type (.NET or JVM), but they must conform to the following rules. They:

  • Must be declared at 01 (or 77) level
  • Must have no REDEFINES or RENAMES
  • Must never be the subject of reference modification
  • Must never be the subject of the ADDRESS OF clause
  • May use format 3 of the OCCURS clause to declare an array

Any COBOL data item that does not follow these rules, or is of any other category, is not considered to be a managed type (.NET or JVM) and is allocated by the Compiler within an internally managed byte array. COBOL pointer data items always point into one of these byte arrays.

Generic Types

In managed COBOL, to refer to a generic type using the TYPE literal syntax, you enumerate the generic parameters within square brackets. The following example declares myNames as an item of type Dictionary (for .NET COBOL) or HashMap (for JVM COBOL), with both generic parameters set to string - System.String for .NET COBOL, and java.lang.String for JVM COBOL:

myNames type System.Collections.Generic.Dictionary[string, string]. *> .NET COBOL
myNames type java.util.HashMap[string, string]. *> JVM COBOL
Parent topic: Common Syntax Elements
Related reference
Indexers
Operators
Properties
Local Data Item Declaration
Fields
Related information
Operator Overloading in Managed COBOL
String Handling in Managed COBOL
Types and Type Conversion
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Statements - Alphabetic List

  • Statements
  • ACCEPT Statement
    Takes data keyed at the console or supplied by the operating system and makes it available to the program in a specified data item.
  • ADD Statement
    Adds two or more numeric operands and stores the result.
  • ATTACH Statement
    Attaches a delegate, a method group or an anonymous method to an event.
  • CREATE Collection Statement
    Creates or constructs an instance of a list or dictionary.
  • COMPUTE Statement
    Assigns to one or more data items the value of an arithmetic expression.
  • CONTINUE Statement
    The CONTINUE statement is a no operation statement, indicating that no executable statement is present.
  • DECLARE Statement
    Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.
  • DELETE Collection Statement
    Deletes an element from the list or dictionary.
  • Detach Statement
    Detaches a delegate or a method group from an event.
  • DISPLAY Statement
    Displays the specified data items.
  • DIVIDE Statement
    Divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.
  • EVALUATE Statement
    Describes a multi-branch, multi-join structure, which can evaluate multiple conditions. The subsequent action of the run-time element depends on the results of these evaluations.
  • EXIT Statement
    Causes an exit from a perform loop, method or iterator.
  • GOBACK Statement
    Causes a return from a method.
  • IF Statement
    Evaluates a condition and takes subsequent action depending on whether the value of the condition is true or false.
  • INSPECT Statement
    Provides the ability to perform tally, replace, tally and replace, and convert and tally trailing operations on a data item.
  • INVOKE Statement
    Invokes a method.
  • MOVE Statement
    Transfers data to one or more data areas.
  • MULTIPLY Statement
    Multiplies numeric data items and sets the values of data items equal to the results.
  • PERFORM Statement
    Controls execution of a statement block in the scope of the PERFORM statement. This statement can also process each element of an array or collection.
  • RAISE Statement
    Raises an exception.
  • READ Collection Statement
    Reads an element in the list or in the dictionary from a given key.
  • RESET Collection Statement
    Deletes all the elements from the list or dictionary.
  • REWRITE Collection Statement
    Overwrites an element in the list or dictionary.
  • SET Statement
    Can set the size of an array; initialize the contents of an array and set the size accordingly; and set the value of a data item or a boolean data item.
  • SORT Statement
    Sorts the elements of a table.
  • SUBTRACT Statement
    Subtracts one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.
  • STRING Statement
    Concatenates the partial or complete contents of two or more data items into a single data item.
  • SYNC Statement
    Marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.
  • TRY Statement
    The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling.
  • UNSTRING Statement
    Separates contiguous data in a sending field and places it into multiple receiving fields.
  • WRITE Collection Statement
    Writes an element to the list or dictionary.
Parent topic: Managed COBOL Reference


Statements

Context:

Procedure Division

statement-block

ACCEPT Statement - Managed SyntaxTakes data keyed at the console or supplied by the operating system and makes it available to the program in a specified data item. ADD Statement - Managed SyntaxAdds two or more numeric operands and stores the result. Attach StatementAttaches a delegate, a method group or an anonymous method to an event. CREATE Collection Statement - Managed SyntaxCreates or constructs an instance of a list or dictionary. COMPUTE Statement - Managed SyntaxAssigns to one or more data items the value of an arithmetic expression. CONTINUE Statement - Managed SyntaxThe CONTINUE statement is a no operation statement, indicating that no executable statement is present. DECLARE Statement - Managed Syntax Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks. DELETE Collection Statement - Managed SyntaxDeletes an element from the list or dictionary. Detach Statement - Managed SyntaxDetaches a delegate or a method group from an event. DISPLAY Statement - Managed SyntaxDisplays the specified data items. DIVIDE Statement - Managed SyntaxDivides one numeric data item into others and sets the values of data items equal to the quotient and remainder. EVALUATE Statement - Managed SyntaxDescribes a multi-branch, multi-join structure, which can evaluate multiple conditions. The subsequent action of the run-time element depends on the results of these evaluations. EXIT Statement - Managed SyntaxCauses an exit from a perform loop, method or iterator. GOBACK Statement - Managed SyntaxCauses a return from a method. IF Statement - Managed SyntaxEvaluates a condition and takes subsequent action depending on whether the value of the condition is true or false. INSPECT Statement - Managed SyntaxProvides the ability to perform tally, replace, tally and replace, and convert and tally trailing operations on a data item. INVOKE Statement - Managed SyntaxInvokes a method. MOVE Statement - Managed SyntaxTransfers data to one or more data areas. MULTIPLY Statement - Managed SyntaxMultiplies numeric data items and sets the values of data items equal to the results. PERFORM Statement - Managed SyntaxControls execution of a statement block in the scope of the PERFORM statement. This statement can also process each element of an array or collection. RAISE Statement - Managed SyntaxRaises an exception. READ Collection Statement - Managed SyntaxReads an element in the list or in the dictionary from a given key. RESET Collection Statement - Managed SyntaxDeletes all the elements from the list or dictionary. REWRITE Collection Statement - Managed SyntaxOverwrites an element in the list or dictionary. SET Statement - Managed SyntaxCan set the size of an array; initialize the contents of an array and set the size accordingly; and set the value of a data item or a boolean data item. SORT Statement - Managed SyntaxSorts the elements of a table. STRING Statement - Managed SyntaxConcatenates the partial or complete contents of two or more data items into a single data item. SUBTRACT Statement - Managed SyntaxSubtracts one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results. SYNC Statement - Managed SyntaxMarks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock. TRY Statement - Managed SyntaxThe TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling. UNSTRING Statement - Managed SyntaxSeparates contiguous data in a sending field and places it into multiple receiving fields. WRITE Collection Statement - Managed SyntaxWrites an element to the list or dictionary.
Parent topic: Statements - Alphabetic List


ACCEPT Statement (JVM Reference)

ACCEPT Statement

Takes data keyed at the console or supplied by the operating system and makes it available to the program in a specified data item.

Context:

    Procedure Division
        Statements

accept-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The ACCEPT Statement


ADD Statement

Adds two or more numeric operands and stores the result.

Context:

    Procedure Division
        Statements

add-statement

Parent topic: Statements - Alphabetic List


ATTACH Statement

Attaches a delegate, a method group or an anonymous method to an event.

Context:

    Procedure Division
        Statements

attach-statement

Parent topic: Statements - Alphabetic List


CREATE Collection Statement

Creates or constructs an instance of a list or dictionary.

Context:

    Procedure Division
        Statements

create-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Example

The following declares and creates a list collection: and then writes an element to the list:

       declare stringList as list[string]
       create stringList
       write stringList from "item 0"

See also the Collections sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
WRITE Collection Statement
REWRITE Collection Statement
RESET Collection Statement
READ Collection Statement
DELETE Collection Statement


COMPUTE Statement

Assigns to one or more data items the value of an arithmetic expression.

Context:

    Procedure Division
        Statements

compute-statement

Parent topic: Statements - Alphabetic List


CONTINUE Statement

The CONTINUE statement is a no operation statement, indicating that no executable statement is present.

Context:

    Procedure Division
        Statements

continue-statement

Parent topic: Statements - Alphabetic List


DECLARE Statement

Declares one or more local variables within the procedure division body. The scope of any inline local variable is from the point of declaration until the end of the innermost containing block, where paragraphs, sections and the whole method are considered to be blocks.

Context:

    Procedure Division
        Statements

declare-statement

Example

       declare i1 as binary-long
       display i1

       *>   Optionally, the variables can be initialised inline
        declare c2 as condition-value = true
        display c2

        declare string-list2 as string occurs 3 = table of string("Bill", "Ben", "LittleWeed")

See also the Local Variables sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
Local Data Item Declaration


DELETE Collection Statement

Deletes an element from the list or dictionary.

Context:

    Procedure Division
        Statements

delete-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Parent topic: Statements - Alphabetic List
Related reference
CREATE Collection Statement
WRITE Collection Statement
REWRITE Collection Statement
RESET Collection Statement
READ Collection Statement


Detach Statement

Detaches a delegate or a method group from an event.

Context:

    Procedure Division
        Statements

detach-statement

Parent topic: Statements - Alphabetic List


DISPLAY (JVM Language Reference)

DISPLAY Statement

Displays the specified data items.

Context:

    Procedure Division
        Statements

display-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The DISPLAY Statement


DIVIDE Statement

Divides one numeric data item into others and sets the values of data items equal to the quotient and remainder.

Context:

    Procedure Division
        Statements

divide-statement

Parent topic: Statements - Alphabetic List


EVALUATE Statement

Describes a multi-branch, multi-join structure, which can evaluate multiple conditions. The subsequent action of the run-time element depends on the results of these evaluations.

Context:

    Procedure Division
        Statements

evaluate-statement

Parent topic: Statements - Alphabetic List


EXIT Statement

Causes an exit from a perform loop, method or iterator.

Context:

    Procedure Division
        Statements
Program Structure
   Types
      { Classes ValueTypes Interfaces Delegates Enums  }
           *
               Procedure Division
                  statement-block

exit-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The EXIT Statement


GOBACK Statement

Causes a return from a method.

Context:

    Procedure Division
        Statements

goback-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The GOBACK Statement


IF Statement

Evaluates a condition and takes subsequent action depending on whether the value of the condition is true or false.

Context:

    Procedure Division
        Statements

if-statement

Parent topic: Statements - Alphabetic List
Related information
Conditions - in COBOL and Java


INSPECT Statement

Provides the ability to perform tally, replace, tally and replace, and convert and tally trailing operations on a data item.

Context:

    Procedure Division
        Statements

inspect-statement

Inspect/Tallying

Inspect Format 1

Inspect/Replacing

Inspect Format 2

Inspect/Tallying/Replacing

Inspect Format 3

Inspect/Converting

Inspect Format 4

Inspect/Tallying for Trailing/Replacing Trailing

Inspect Format 5

Further information

identifier-1 must be of type string. All other identifiers or literals must be of data types string or character.

Parent topic: Statements - Alphabetic List
Related information
INSPECT Statement


INVOKE Statement

Invokes a method.

Context:

    Procedure Division
        Statements

invoke-statement

method-invocation-expression

Example

In the following example, the arguments a and b above are passed to the invoked method, and these correspond to the parameters x and y respectively, in the invoked method. The types of the parameters are specified in the AS phrase in the method signature.

       01 a string.
       01 b binary-long.
       invoke type MyClass::MyMethod(a,b)
       ...

       method-id MyMethod (x as string, y as binary-long).
       ...
       end method.

See also the Core sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
Procedure Division Header
SET Statement
Related information
Types and Type Conversion
Methods - in COBOL and Java
Objects - in COBOL and Java
Invoking a Method


MOVE Statement

Transfers data to one or more data areas.

Context:

    Procedure Division
        Statements

move-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The MOVE Statement


MULTIPLY Statement

Multiplies numeric data items and sets the values of data items equal to the results.

Context:

    Procedure Division
        Statements

multiply-statement

Parent topic: Statements - Alphabetic List


PERFORM Statement

Controls execution of a statement block in the scope of the PERFORM statement. This statement can also process each element of an array or collection.

Context:

    Procedure Division
        Statements

perform-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Further information

For JVM COBOL, the USING phrase is only applicable to JVM version 1.7 and onwards.

The type-specifier section of the PERFORM..USING phrase must specify a type that implements the java.lang.AutoCloseable interface, and must specify an initial value via the = expression syntax.

Example of local declaration within an iterator

A variable can be declared at the point of use in an iterator, and its scope is until the end of the perform block.

      *>   In this case, the scope of i is until the end of the perform block.
           perform varying i as binary-long from 1 by 1 until i > 10
               display i
           end-perform

      *>   So the i in the following perform block is a new instance of i,
      *>   independent of the i in the preceding perform block.
           perform varying i as binary-short from 0 by 1 until i > 10
               display i
           end-perform

Here, k is declared inline to iterate through a dictionary. Again, it is in scope until the corresponding end-perform.

    01 dict1 dictionary[string string].
           create dict1
           write dict1 from "Anthony" key "A"
           write dict1 from "Brian" key "B"
           write dict1 from "Charles" key "C"
           perform varying key k as string value val as string through dict1
               display k ":" val
           end-perform
           perform varying value val as string through dict1
               display val
           end-perform
           perform varying key k as string through dict1
               display k
           end-perform

See also the Local Variables sample, available in the Samples Browser. See To start the Samples Browser for instructions.

Parent topic: Statements - Alphabetic List
Related tasks
To start the Samples Browser
Related reference
The PERFORM Statement
Related information
Loops - in COBOL and Java


RAISE Statement

Raises an exception.

Context:

    Procedure Division
        Statements

raise-statement

Example

Parent topic: Statements - Alphabetic List
Related reference
TRY Statement
Related information
Exception Handling - in COBOL and Java


READ Collection Statement

Reads an element in the list or in the dictionary from a given key.

Context:

    Procedure Division
        Statements

read-collection-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Where: identifier is the name of the list or dictionary collection type.

Example

The following reads an element from a list collection:

       declare val as string
       read stringList into val key 0

The following example, shows exception handling and catching an exception on reading an invalid key in a dictionary collection:

       display "reading an invalid key message : "
       read stringDictionary into val key "RUBBISH"
       invalid key
           display "Caught invalid key"
       not invalid key
           display "Shouldn't see this"
       end-read

See also the Collections sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
CREATE Collection Statement
WRITE Collection Statement
REWRITE Collection Statement
RESET Collection Statement
DELETE Collection Statement


RESET Collection Statement

Deletes all the elements from the list or dictionary.

Context:

    Procedure Division
        Statements

reset-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
CREATE Collection Statement
WRITE Collection Statement
REWRITE Collection Statement
READ Collection Statement
DELETE Collection Statement


REWRITE Collection Statement

Overwrites an element in the list or dictionary.

Context:

    Procedure Division
        Statements

rewrite-collection-statement

Where: identifier is the name of the list or dictionary collection type.

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

The following overwrites the first element in the list stringList.

       rewrite stringList from "ITEM REWRITE" key 0
       display "The contents of the list after rewrite element 0 : "
       invoke displayListContents(stringList)

See also the Collections sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
CREATE Collection Statement
WRITE Collection Statement
RESET Collection Statement
READ Collection Statement
DELETE Collection Statement


SET Statement

Can set the size of an array; initialize the contents of an array and set the size accordingly; and set the value of a data item or a boolean data item.

Context:

    Procedure Division
        Statements

set-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

See the Core sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
INVOKE Statement
The SET Statement
Related information
Invoking a Method
Arrays - in COBOL and Java
Objects - in COBOL and Java


SORT Statement

Sorts the elements of a table.

Context:

    Procedure Division
        Statements

sort-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.
Parent topic: Statements - Alphabetic List
Related reference
The SORT Statement


SUBTRACT Statement

Subtracts one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.

Context:

    Procedure Division
        Statements

subtract-statement

Parent topic: Statements - Alphabetic List


STRING Statement

Concatenates the partial or complete contents of two or more data items into a single data item.

Context:

    Procedure Division
        Statements

string-statement

Further information

identifier-3 must be of type string. All other identifiers or literals must be of data types string or character.

Parent topic: Statements - Alphabetic List
Related information
STRING Statement


SYNC Statement

Marks a statement block as a critical section by obtaining the mutual-exclusion lock for a given object, executing a block of statements, and then releasing the lock.

Context:

    Procedure Division
        Statements

sync-statement

Example

class-id Account.
  working-storage section.
  01 balance binary-long.
  01 r type Random value new Random.
  method-id new.
  procedure division using value init as binary-long.
      move init to balance
  end method.

  method-id Withdraw.
  procedure division using value amount as binary-long returning ret as binary-long.
  *> This condition will never be true unless the lock statement
  *> is commented out:
      if balance > 0
          display "< 0"
          raise new Exception("Negative Balance")
      end-if
      sync on self
          if balance >= amount
               display "In critical section"
               *>display "Balance before Withdrawal :  " balance
               *>display "Amount to Withdraw        : -" amount
               compute balance = balance - amount
               *>display "Balance after Withdrawal  :  " balance
               move amount to ret
          else
               display "In critical section"
               move 0 to ret
          end-if
      end-sync
  end method.

  method-id DoTransactions.
  local-storage section.
  01 i binary-long.
  procedure division.
      perform varying i from 0 by 1 until i = 100
          invoke Withdraw(r::Next(1, 100))
      end-perform
  end method.
end class.
Parent topic: Statements - Alphabetic List
Related information
Synchronization - in COBOL and Java


TRY Statement

The TRY...CATCH...FINALLY...END-TRY structure is the basis for structured exception handling.

The TRY block allows you to test a section of code for exceptions that may occur during its execution. The CATCH block must specify the type of exception you wish to handle if one should occur during the execution of the TRY block. The FINALLY block allows you to execute a section of code following the TRY block, whether or not an exception occurred.

Context:

    Procedure Division
        Statements

try-statement

Example of a local declaration of an exception

      *>   The example below shows that you can declare e at the point of use.
      *>   It is in scope until the end-try.
           try
               display "exception test"
           catch e as type Exception
               display e::Message
           end-try

See also the Local Variables sample, available from $COBDIR/demo.

Further Information

In the TRY statement, the:

TRY statement-block
specifies the section of code to be tested for exceptions that may occur during its execution
CATCH statement-block
specifies the type of exception to handle if an exception occurs during execution of the TRY block
FINALLY statement-block
specifies the section of code to execute following the TRY block, whether or not an exception occurred

Your program can raise an exception using the RAISE statement and pass this exception back to the caller. This is commonly referred to as "throwing an exception".

Parent topic: Statements - Alphabetic List
Related reference
RAISE Statement
Related information
Exception Handling - in COBOL and Java


UNSTRING Statement

Separates contiguous data in a sending field and places it into multiple receiving fields.

Context:

    Procedure Division
        Statements

unstring-statement

Further information

identifier-1 must be of type string. All other identifiers and literals must be of data types string or character.

Parent topic: Statements - Alphabetic List
Related information
The UNSTRING Statement


WRITE Collection Statement

Writes an element to the list or dictionary.

Context:

    Procedure Division
        Statements

write-collection-statement

Note: Other formats of this statement are available. See Statements in the COBOL Language Reference.

Example

The following declares and creates a list collection and then writes an element to the list:

       declare stringList as list[string]
       create stringList
       write stringList from "item 0"

The following writes 5 more elements to the list using a perform loop:

       perform varying i as binary-long from 1 by 1 until i > 5
           write stringList from "item " & i
       end-perform

       display "The contents of the list : "
       invoke displayListContents(stringList)

See also the Collections sample, which is available from $COBDIR/demo.

Parent topic: Statements - Alphabetic List
Related reference
CREATE Collection Statement
REWRITE Collection Statement
RESET Collection Statement
READ Collection Statement
DELETE Collection Statement


Concepts - Managed COBOL

  • Extension Methods and Operators
    Extension methods enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.
  • Invoking a Method
    You can invoke a method in two ways: by using the invoke statement or by using the inline invocation syntax.
  • Method Overloading in Managed COBOL
    Managed COBOL supports method overloading
  • Operator Overloading in Managed COBOL
    You can overload operators to provide alternative behavior, or behavior for different operand types.
  • String Handling in Managed COBOL
    Managed COBOL provides a predefined managed string type and provides powerful techniques for handling strings.
  • Types and Type Conversion
    Types can be converted into other types using the AS syntax or a conversion operator.
  • Type Compatibility of .NET and JVM COBOL with Other Managed Languages
    Many managed COBOL (.NET COBOL and JVM COBOL) types have a strict correspondence with managed types in other languages, such as binary-long and float-short. For those that don't have a correspondence, there are alternatives.
  • Type Mappings from Native COBOL to Managed Code
    COBOL data items are exposed as managed types, when the code is compiled with the ILSMARTLINKAGE directive.
Parent topic: Managed COBOL Reference


Extension Methods and Operators

Extension methods enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.

Extension Methods

Similar to other managed code languages such as C#, managed COBOL supports extension methods, which enable you to add methods to existing types thereby providing additional functionality without the need to edit or recompile the code.

For example, the following extension method extends the string class, by adding a method to count the number of words in a string:

       class-id MyCount static.
       method-id CountWords extension. *> extension method is implicitly static
       procedure division using by value str as string
                          returning wordCount as binary-long.
            set wordCount to str::Split(' ')::Length
       end method.
       end class.

You extend a method when you cannot override it. The method you want to extend might be in a final class or in code that you don't have access to. In these cases, you can define and compile the extension method separately and then use it freely.

Defining an extension method

Use the following construction to define an extension method:

       class-id MyExtension static.
       method-id MyExtensionMethod extension.
       procedure division using myName as ExtendedType
                      returning myReturnName as returnType.
           set myReturnName to my code...
       end method.
       end class.

To define an extension method:

  • Use the EXTENSION keyword in the method header.
  • The method must be in a static class that is not nested or generic. The method is implicitly static.
  • In the method body, the first parameter is the type to extend. It is always a value parameter.
Consuming an extension method

There is no special syntax for calling extension methods. You consume extension methods in much the same way as any other method, except you specify the first parameter as the type that is extended. You use this syntax:

parameter-1::method-name(more parameters)

In the example below, you consume with code such as aString::CountWords:

       class-id MyWords.
       method-id CheckWords.
       01 myWordCount binary-long.
       procedure division using by value aString as string
                          returning b as condition-value.
           set myWordCount to aString::CountWords
           if myWordCount < 10
               set b to true
           else
               set b to false
           end-if
       end method.
       end class.

You use extension methods as if they were instance methods defined in another class or interface. Extension methods appear as additional methods available on an object instance and yet they are implemented elsewhere.

When you invoke an extended method, the extension method is not contained in the class specified in the invoking statement. It is contained in another class elsewhere. The invoking and executing classes are different. The method's defined and execution containing types are different.

Extension methods work like this:

  • The Compiler produces a static method with parameters. The type of the first parameter is the type being executed (or invoked). The second and subsequent parameters are the declared parameters. For example, the Compare method effectively has two parameters: the type of the first parameter is a string, and the second parameter is s2.
  • The first parameter is annotated with the System.run-time.CompilerServices.ExtensionAttribute attribute (or in the case of a JVM program, an equivalent that is defined in the JVM runtime system). This attribute is also applied to the containing class and assembly.

Extension Operators

Extension operators are very similar to extension methods. They enable you to provide alternative behavior for an operator, without the need to edit or recompile the code. You define and use extension operators in the same way as extension methods.

For example, you could define and use an extension plus operator, as follows:

       set timer3 to timer1 + myMins
       operator-id + extension.
       01 sumMins binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.
           set sumMins to a::pMins + b
           divide sumMins by 60 giving h remainder m
           set c to new Timer(a::pHour + h , m)
       end operator.

You extend an operator when you cannot overload it. The operator you want to extend might be in a final class or in code that you don't have access to. In these cases, you can define and compile the extension operator separately and then use it freely.

To declare and use an extension operator:

  • Declare the operator using the EXTENSION keyword. The operator must be in a static class.
  • There is no special syntax for using extension operators.
  • In JVM managed COBOL, the extension operator must be available to the Compiler. You might need to use the ILREF directive in combination with the JVMGEN directive. See Extension Methods for full details.

Extension operators are implemented as methods, such as an op_Equality or op_Addition method. This method is added to a specific dictionary in TypeInfo. This enables the code looking for operator overloads and extensions to look in this dictionary in addition to the classes of the two operands.

Extension Methods (and Operators) in JVM COBOL

When you invoke a method, you specify the class in which the method belongs. In our example, the method CheckWords() in the myWord class and is invoked as follows:

       01 myWord type MyWords.
       01 myDoc string.
       01 sizeOK condition-value.
           set sizeOK to myWord::CheckWords(myDoc)
           ...
       class-id MyWords final.
       method-id CheckWords.
       ...

In the above, since the class can be found, so can the method. The class loader architecture uses the class on which a method is defined to know when to load a class. In this case, the myWord class is loaded before the method CheckWords() is invoked. This happens in much the same way during compilation. When the myWord::CheckWords method is referred to in a class that is being compiled, the Compiler uses a class loader to load the CheckWords method to resolve the method signature and understand how to generate the appropriate code.

Problem: extensions can't be found

However, when you invoke an extended method (or operator), the extension method is not contained in the class specified in the invoking statement. In our example, the extension method CountWords() is invoked on the type of the aString variable (which is a string), but it is executed in your extension class, as follows:

       01 aString string.
       01 myWordCount binary-long.
           set myWordCount to aString::CountWords
           ...
       class-id MyCount static.
       method-id CountWords extension.
       ...

Although the method is invoked on the String class, the method to be executed is contained in a different class (the MyCount class). The class loader can't find the method, because its defined and execution containing types are different. For the Compiler to use extension methods (and extension operators), it has to load their defining classes before compiling the classes that refer to those extensions.

Solution: preload the extensions

To ensure that the Compiler can find the extensions, you use ILREF directive at the command line, combined with the JVMGEN directive. The following example loads the class defined within the ops.class file. The name and package of the class defined in ops.class does not need to be the same as the name and directory of the class file.

Windows:

cobol x.cbl jvmgen ilref(ops.class);

UNIX:

cob x.cbl –C jvmgen  -C ilref(ops.class)

The following command unpacks the file ops.jar and loads the moreOps.class. Note that the .jar file needs to be on the CLASSPATH environment variable or specified in the JVMCLASSPATH directive for it to work.

Windows:

cobol -j x.cbl jvmclasspath(ops.jar) ilref(moreOps.class);

UNIX:

cob -j x.cbl -C jvmclasspath(ops.jar) –C ilref(moreOps.class)

The ILREF directive requires a file in class format. Files with the .class extension are treated as class format.

Preloaded Extensions for JVM

The following extensions are supplied for JVM:

  • String equality extension operator
  • Substring extension method

The classes containing the extensions are preloaded by the Compiler by using the ILREF directive.

String Equality Extension Operator

An extension operator for string equality is preloaded by the Compiler before compilation. This ensures that a check for equality gives the same results in the .NET environment as in the JVM environment. For example, the following code compares two strings:

       01 string1 string value “12345”.
       01 string2 string value “12345”.
       if string1 = string2
              display “the values are the same”
       else
           display “error - the values look the same, but the equality returned false”
       end-if

Without the preloaded extension, the code sees the strings as different, because the JVM java.lang.String::equality(string) method compares the references and the .NET System.String::equality(string) method compares the values. With the preloaded extension, the code sees the strings as the same.

The string equality extension extends both the = and equals operators for the type string. The operator returns true if the two string instances contain exactly the same character sequence, false otherwise. The operator extension is defined as:

       operator-id = extension.
       procedure division using value a as string
                                      b as string
                          returning r as condition-value.

To check for object equality between string instances use:

       if a as object = b as object
Substring Extension Method for JVM COBOL

An extension method for Substring is preloaded by the Compiler before compilation. This ensures that the Substring method gives the same results in the .NET environment as in the JVM environment. For example:

       01 x string value “1234567890”.
       display x::Substring(2,3) “ The .NET way of doing things”
       display x::substring(2,3) “ The JDK way of doing things”

Since, the .NET behavior of System.String::Substring(int, int) differs from the JVM behavior of java.lang.String::Substring(int int), you get different results for .NET and JVM, if the extension is not installed. However, if the extension is installed, the JVM behavior matches that of .NET and you get the same results.

The Substring extension method extends the string type (which is also java.lang.String). This method returns a new instance of string with a signature that matches that of the Substring method in .NET. The Substring method extension is defined as follows:

       method-id Substring extension.
       procedure division using value a as string
                                startIdx as binary-long
                                sslength as binary-long
                      returning r as string.

String Equality Extension Operator for JVM

An extension operator for string equality is preloaded by the Compiler before compilation. This ensures that a check for equality gives the same results in the .NET environment as in the JVM environment. For example, the following code compares two strings:

       01 string1 string value “12345”.
       01 string2 string value “12345”.
       if string1 = string2
              display “the values are the same”
       else
           display “error - the values look the same, but the equality returned false”
       end-if

Without the preloaded extension, the code sees the strings as different, because the JVM java.lang.String::equality(string) method compares the references and the .NET System.String::equality(string) method compares the values. With the preloaded extension, the code sees the strings as the same.

The string equality extension extends both the = and equals operators for the type string. The operator returns true if the two string instances contain exactly the same character sequence, false otherwise. The operator extension is defined as:

       operator-id = extension.
       procedure division using value a as string
                                      b as string
                          returning r as condition-value.

To check for object equality between string instances use:

       if a as object = b as object

Substring Extension Method for JVM COBOL

An extension method for Substring is preloaded by the Compiler before compilation. This ensures that the Substring method gives the same results in the .NET environment as in the JVM environment. For example:

       01 x string value “1234567890”.
       display x::Substring(2,3) “ The .NET way of doing things”
       display x::substring(2,3) “ The JDK way of doing things”

Since, the .NET behavior of System.String::Substring(int, int) differs from the JVM behavior of java.lang.String::Substring(int int), you get different results for .NET and JVM, if the extension is not installed. However, if the extension is installed, the JVM behavior matches that of .NET and you get the same results.

The Substring extension method extends the string type (which is also java.lang.String). This method returns a new instance of string with a signature that matches that of the Substring method in .NET. The Substring method extension is defined as follows:

       method-id Substring extension.
       procedure division using value a as string
                                startIdx as binary-long
                                sslength as binary-long
                      returning r as string.
Parent topic: Concepts - Managed COBOL
Related reference
Methods
Related information
Methods - in COBOL and Java


Invoking a Method

You can invoke a method in two ways: by using the invoke statement or by using the inline invocation syntax.

INVOKE statement

For example, the following INVOKE statement invokes the replace method on the input string obj-string and returns the results in obj-string. Notice that the case of the method name is different for .NET and JVM. It is replace in .NET and Replace in JVM.

       invoke obj-string::replace("Some" "New")   *> .NET
       invoke obj-string::Replace("Some" "New")   *> JVM
       display obj-string

Inline invocation

Similarly, the following SET statement uses the inline invocation syntax, which employs an implicit set property method. This example statement invokes the Replace() method on the input string obj-string and sets the results in the aString variable.

       set aString to obj-string::replace("Some" "New")   *> .NET
       set aString to obj-string::Replace("Some" "New")   *> JVM
       display aString

In addition, you can use the inline invocation syntax to access properties. In the following example, the Length property of the string myString is accessed and is displayed:

       display "Total characters is " myString::Length

You can invoke any method in the same compilation as the invoking code, either a static or instance method, as follows:

Invoking a static method

To invoke a static method, you specify the class name, followed by :: and then the method name. For example, SimpleClass::StaticMethod as in the invoke statement below:

       invoke type SimpleClass::StaticMethod
       ...
       class-id SimpleClass.
       method-id StaticMethod  static.
          display "In static method"
       end method.
       end class.

Invoking an instance method

To invoke an instance method in the same compilation unit, you instantiate an object first. You can then specify the instance object, followed by :: and then the method name. For example, mySimpleObj::InstanceMethod as in the invoke statement below:

       01 mySimpleObj type SimpleClass.
       set mySimpleObj to new SimpleClass("Hello")
       invoke mySimpleObj::InstanceMethod
       ...
       class-id SimpleClass.
       01 thisString string.

       method-id New.
       procedure division using by value aString as string.
           set thisString to aString
       end method.

       method-id InstanceMethod.
       procedure division.
           display "In instance method"
           display "Instance data is " thisString
       end method.

Examples

See also the Core sample, which is available from $COBDIR/demo.

Parent topic: Concepts - Managed COBOL
Related reference
SET Statement
INVOKE Statement
Related information
Methods - in COBOL and Java
Objects - in COBOL and Java


Method Overloading in Managed COBOL

About Overloading

Overloading is a programming technique where you overload a method name with more than one implementation.

For example, there may be a method called CalculateBill, taking as a parameter a list of purchases. We may want to have a variant of this method which, in addition to the list of purchases, has another parameter representing a discount code. The two methods can have the same name, and, when the method is invoked, the required one is selected based on the presence or absence of the discount code parameter.

Method Overloading in Managed COBOL

In managed COBOL, it is permissible (and very common practice) for a given class or interface to have multiple methods with the same name, which are distinguished from each other by having different signatures. The signature of a method is determined by the:

  • Number of parameters
  • Type of each parameter
  • Passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter
  • Return type

When code written in COBOL, or any other language, attempts to invoke a method in some class or interface, and more than one method with the given name exists, then a choice of the available methods is made. The choice is based on the number of parameters and the ‘best’ type match for the parameters (the precise definition of ‘best’ is complex and is treated later). If no method with a suitable signature can be found, a ‘method not found’ error results. If there is no method that provides a better match than all the other possible methods with this name, an ‘ambiguous match’ error is given.

Although the type of the RETURNING item is a part of the method's signature, the choice of method to be invoked is never based on the RETURNING type. This is different from .NET and JVM, which allow a class to have multiple methods that differ only by returning type. This is not generally good practice, and COBOL produces an error if it finds such multiple methods within a single class. The only time when such multiple methods can arise from a COBOL program is in the case of the explicit and implicit operators.

Method Signatures

The type of a COBOL parameter may be specified by:

  • Referencing the type explicitly in the PROCEDURE DIVISION phrase using the AS syntax
  • Declaring a linkage section item with a given type and referencing that linkage section item in the PROCEDURE DIVISION USING phrase

For REFERENCE and OUTPUT parameters, managed types are exposed directly as managed pointers to the corresponding managed type. COBOL data types that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than BINARY-LONG and so on) are exposed as COBOL pointers.

For VALUE parameters, and RETURNING items, types are exposed as follows:

COBOL types: are exposed as:
Managed types | objects of the corresponding type
Numeric items with more than 19 decimal digit positions | MicroFocus.COBOL.Program.BigDecimal
Numeric items with implied decimal point, such as PIC 9(9)v99, all sizes | - com.microfocus.cobol.program.ScaledInteger in JVM COBOL
Unsigned numeric items with no implied decimal point: In .NET COBOL:
  • < 3 numeric digits - unsigned int8
  • < 5 numeric digits - unsigned int16
  • < 10 numeric digits - unsigned int32
  • < 19 numeric digits - unsigned int64

In JVM COBOL, they are exposed the same as signed numeric items.

Signed numeric items with no implied decimal point:
  • < 3 numeric digits - int8
  • < 5 numeric digits - int16
  • < 10 numeric digits - int32
  • < 19 numeric digits - int64
All other types PIC X, group and so on | string

Method Overload Resolution

Method overload resolution takes place in two phases:

  1. Selection of all applicable methods, that is, selection of all those methods with the given name for which the arguments specified in the invoking program are compatible with the parameters of the target methods. If no such applicable method is found, then an error (method not found) is produced.
  2. Selection of the ‘best’ match from within the set of applicable methods. The general intent of the selection process is to produce the best match (in the sense of most specific match) for the given set of arguments.

    Formally, the method overload that is ‘better’ than any other of the applicable method overloads is chosen. If no single overload is determined to be better than any other overload, then the match is considered to be ambiguous, and a compiler error results.

    If this two-phase process does not result in a unique best match, an error (ambiguous match error) is produced

Note:

In this discussion, the term arguments means the set of parameters specified in the invoking method, for example obj01 in the statement:

INVOKE Method1(obj01)

The term parameters means the formal parameters specified in each method definition (in the PROCEDURE DIVISION USING header).

Selection of Applicable Methods

We start with the complete set of all methods with the required name that exist in the target class or in any of its parent classes (excluding those with identical signatures). From this set, any methods that are not visible from the invoking program, based on the visibility attribute encoded into the method, are discarded as follows:

Attribute | Visibility
PRIVATE | Visible only if the calling class is the same as the target class
PUBLIC | Always visible
PROTECTED | Visible only if the calling class derives from the target class
INTERNAL | Visible only if the target class is in the same assembly as the calling class
PROTECTED INTERNAL | Visible only if the calling class derives from the target class, or the calling class is in the same assembly as the target

Next, if the required method is an instance method (a method that is applied to an object instance), all static methods are discarded. Similarly, if the required method is a static method, all instance methods are discarded.

Now each method is examined in turn to see whether it is applicable in normal form. This is determined as follows:

  1. If the number of arguments is different from the number of parameters in the method, then this method is discarded.
  2. If the type of the parameter in the target method is generic COBOL data passed by reference , then any argument type is assumed to match except for JVM native types.
  3. For each argument with an explicit parameter passing mode (BY CONTENT, BY VALUE or BY OUTPUT), that mode must correspond to the definition of the parameter in the method being examined.

  4. For a REFERENCE or OUTPUT parameter, the type of the argument must be exactly the same as the parameter type.

    For a VALUE parameter, an implicit conversion must exist from the type of the argument to the type of the corresponding parameter. If any of these implicit conversions require truncation, this method is said to be a ‘truncation match’.

If a method is not applicable according to these rules, an attempt is made to match the method in expanded form, if both the following are true:

  • The last parameter of the method is an array with the ‘params’ attribute
  • The total number of method parameters (excluding this array parameter) is less than or equal to the number of arguments

The expanded form of the method is derived from the normal form by replacing the array parameter by zero or more value parameters of the same type as the array element, so that the total number of parameters is the same as the number of invoking arguments. If the class already contains a method in normal form with this same expanded signature, then this method is determined to be not applicable. Otherwise the expanded form is tested for applicability in the same way as the test for normal form above.

After the above selection procedure:

  1. If exactly one member is found to be applicable, then that method is known to be the required method.
  2. If more than one method is found to be applicable, then an attempt is made to find the best method.
  3. If any non-truncation matches are found, then all truncation matches are discarded.
  4. If the only matches found are truncation matches, then if only one such match has been found, this becomes the chosen method and a warning is produced. If more than one truncation match is found, then the Compiler returns an error:
    ambiguous match
  5. If no methods are found to be applicable, then the Compiler returns an error:
    method not found

Better Method Overload

Suppose we have an argument list A with a set of argument types (A1, A2,…An) and two applicable method overloads Mp and Mq with parameter types (P1…Pn) and (Q1,…Qn), where if necessary the parameters have been converted to expanded form (see above).

Then, Mp is said to be a better method overload than Mq if both the following are true:

  • For each argument, the implicit conversion from Ax to Px is not worse than the conversion from Ax to Qx (see below for definition of better conversion)
  • There is at least one argument for which the conversion from Ax to Px is better than the conversion from Ax to Qx

Suppose we have two conversions, from type S to types T1 and T2, then T1 is the better conversion when T1 and T2 are as follows:

T1 is: And T2 is one of:
same as S anything
binary-char
  • binary-char unsigned
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-long unsigned
  • binary-double unsigned
binary-double
  • binary-double unsigned

Otherwise neither conversion is better.

Example of Simple Method Overloading

The following example shows how, even in the case where the supplied argument is not exactly the same as that for any of the target methods, the “most specific” rule takes effect.

       class-id Class1 static.
       method-id main static.
       01 objAnyObject object.
       01 objString string.
       01 objDateTime type DateTime.         *> .NET COBOL
      * 01 objDateTime type java.util.Date.  *> JVM COBOL
       01 ref1 type Class1.
       procedure division.
           set ref1 to new Class1
           invoke ref1::method1                *> uses variant 1
           invoke ref1::method1(objAnyObject)  *> uses variant 2
           invoke ref1::method1(objString)     *> uses variant 3
           invoke ref1::method1(objDateTime)   *> also uses variant 2,
               *> because an object of type DateTime can be assigned
               *> to an Object but not to a String.
       end method.

       method-id method1.     *> Variant 1 (no parameters)
       procedure division.
           display "variant 1"
       end method.

       method-id method1.     *> Variant 2 (object parameter)
       procedure division using by value objAnyObject as object.
           display "variant 2"
       end method.

       method-id method1.     *> Variant 3 (string parameter)
       procedure division using by value objString as string.
           display "variant 3"
       end method.

       end class.

Implicit Conversion

An implicit conversion exists from type S to type T if it is possible to assign an object of type S to an object of type T, with the equivalent of the following statement:

SET obj-T TO obj-S

The following types of implicit conversion are available:

Identity conversions

This simply means that S is the same type as T

Implicit numeric conversions

COBOL generally allows any numeric item to be assigned to any other, with any loss of data being the responsibility of the user. However, when determining if a conversion exists for the purposes of method overloading, we distinguish between proper conversions and truncation conversions. Proper conversions are those for which no loss of data magnitude should result, though even in this case precision can be lost when converting between fixed point and floating point.

For managed COBOL types, proper implicit conversions include:

binary-char
  • binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-char unsigned

The same as binary-char, plus:

  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-short unsigned

The same as binary-short, plus:

  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-long unsigned

The same as binary-long, plus:

  • binary-double unsigned
binary-double
  • float-short
  • float-long
  • decimal
binary-double unsigned

The same as binary-double

character
  • binary-short unsigned
  • binary-long
  • binary-long unsigned
  • binary-double
  • binary-double unsigned
  • float-short
  • float-long
  • decimal
float-short
  • float-long
Implicit enumeration conversions

The value 0 may be converted to any enum type

Implicit reference conversions

If S and T are reference types, S may be assigned to T when:

  • Type S is derived (directly or indirectly) from type T. This includes the case where T is java.lang.Object since all types derive from that
  • Type S implements interface type T
  • If S is an array type with element type E1 and T is an array type with element type E2, then S can be assigned to T provided:
    • S and T have the same number of dimensions
    • Both E1 and E2 are reference types
    • An implicit conversion exists from E1 to E2
  • Any array type may be assigned to type java.util.Array in JVM COBOL
  • Null may be assigned to any reference type
Boxing conversions

Any value type can be converted to a java.lang.Object type by a process known as boxing. As part of this process the value is copied onto the object heap and a reference is created

Implicit constant expression conversions

Any numeric constant can be converted to any type capable of containing the full value of that constant. For instance the value 1 can be converted both to BINARY-CHAR UNSIGNED and to BINARY-CHAR.

User defined implicit conversions

A user defined implicit conversion consists of an optional implicit numeric conversion from S to S1 followed by the execution of a user defined implicit conversion operator resulting in T1, followed by another optional implicit numeric conversion to T. User defined implicit conversion operators are defined in COBOL with OPERATOR-ID IMPLICIT and result in methods with the name op_Implicit.

Parent topic: Concepts - Managed COBOL
Related reference
Access Modifiers
Methods
Related information
Methods - in COBOL and Java
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Operator Overloading in Managed COBOL

You can overload operators to provide alternative behavior, or behavior for different operand types. For example, where a Timer type is expressed as hours and minutes, you could define one plus operator to add two Timers and another plus operator to add a number of minutes to a Timer type, as follows:

       operator-id + .
       01 sumMins binary-long.
       01 sumHour binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as type Timer
                            returning c as type Timer.
           set sumHour to a::pHour + b::pHour
           set sumMins to a::pMins + b::pMins
           if sumMins >= 60
               divide sumMins by 60 giving h remainder m
               set c to new Timer(sumHour + h, m)
           else
               set c to new Timer(sumHour sumMins)
           end-if
       end operator.

       operator-id + .
       01 sumMins binary-long.
       01 m binary-long value 0.
       01 h binary-long value 0.
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.
           set sumMins to a::pMins + b
           divide sumMins by 60 giving h remainder m
           set c to new Timer(a::pHour + h , m)
       end operator.

To use the overloaded operators, you use statements such as the following:

       program-id OpConversionExtension.
       01 timer1 type Timer value new Timer(1 45).
       01 timer2 type Timer value new Timer(2 45).
       01 timer3 type Timer value new Timer.
       01 myMins binary-long value 30.

       procedure division.
      *> Overloaded operators:
           set timer3 to timer1 + myMins   *> Plus operator adds binary-long to a Timer
           display timer3::pHour & ":" & timer3::pMins   *> displays 2:15

           set timer3 to timer1 + timer2   *> Plus operator adds 2 Timer types
           display timer3::pHour & ":" & timer3::pMins   *> displays 4:30
       end program.

The appropriate operator is executed according to the types of operands being operated on. The operator with a matching signature (procedure division using clause) is executed. Where two Timer types are being added, the operator with a signature that adds two Time types is executed.

Note that the operator signature requires that the arguments are passed in the defined order. In the above example, the Timer type must be first and the binary-long second, as follows:

       set timer3 to timer1 + myMins
       ...
       operator-id + .
       procedure division using value a as type Timer
                                      b as binary-long
                            returning c as type Timer.

To enable the arguments to be passed in the opposite order, you need to declare an another operator where the operands are in the opposite order in the operator's signature. For example:

       set timer3 to myMins + timer1
       ...
       operator-id + .
       procedure division using value a as binary-long
                                      b as type Timer
                            returning c as type Timer.

While the arithmetic operators for addition, subtraction, multiplication and division can all be overloaded, their verb equivalents cannot. For example, ADD in the following statement cannot be overloaded:

       add a to b giving c

Further Examples

See also the Operator Overloading sample, available from $COBDIR/demo.

Parent topic: Concepts - Managed COBOL
Related reference
Operators
Type Specifier
Related information
Operators - in COBOL and Java


String Handling in Managed COBOL

Managed COBOL provides a predefined managed string type and provides powerful techniques for handling strings.

In managed COBOL, you can:

  • Construct a string implicitly by assigning a value
  • Concatenate strings using &
  • Get a substring using the (offset:length) syntax
  • Get the length of a string, using SIZE OF
  • Compare strings using = and <>

The String Predefined Type

Managed COBOL provides a predefined string type corresponding to the managed code string type. You use this type name when declaring a data item, and anywhere that a class name is expected. For example:

01 obj-string string.

Constructing String Objects

String objects are not normally constructed using the "New" method. You can simply assign a value to the string reference and the compiler automatically performs the construction for you. The string value may be set up in this way either to a literal value, or to an alphanumeric, national or group data item. For example:

       set obj-string to "   Some text..."
        display obj-string

Substringing

Substringing is built into managed COBOL with the syntax (offset:stringLength). For example, the following line displays two characters of the string 'a' starting at the sixth character:

display a(6:2)

This looks simple enough, 'a' is a string not a 'pic x'. To do this with C# or Java you have to use a substring method, whereas managed COBOL it is in syntax.

Concatenation

Concatenation is easy using & (ampersand).

You can do string concatenation and string reference modification in the same line; not only that but it seamlessly concatenates COBOL quoted constants with string objects. For example:

       set a to a(1:5) & "-" & a(7:)
       display a

You can concatenate strings with the following using & (ampersand):

string variables | a & b
substrings | a & b(1:3)
quoted string constants | a & "-"
non-string types | 23 & " is a number"
return values from invokes | a & type COBOLString::Split(b,13,7)

The following example combines substringing with concatenation. Here a COBOL quoted constant is automatically cast to a string and the string returned from the invoke is then concatenated with two COBOL quoted constants.

       set a to "Micro Focus Managed COBOL is "                  & *>Micro Focus Managed COBOL is
           type COBOLString::Split("The cake is amazing", 13, 7) & *>amazing
           "ly good for working with strings!"                     *>ly good for working with strings!
       display a

Where the COBOLString::Split() method contains:

       set stringOut to stringIn(offset:stringLength)

Getting the String Length

To get the length of a string, use SIZE OF. For example:

       set n to size of myString

Concatenating Numbers and Strings

The following example concatenates a string variable (a COBOL quoted constant, which is automatically cast to a string) with a number returned from an invoke, which is then concatenated with another COBOL quoted constant.

           display a                           &
              " (this string is "              & *> (this string is
               type COBOLString::CharCount(a)  & *>69
              " bytes long)"                     *> bytes long)

Comparing Strings

To compare strings, use = and <>. For example:

           if a = b
               display "a = b"
            end-if
            if a <> b
               display "a <> b"
            end-if

String comparisons are implemented as overloads to the = and <> operators, which compare character by character (rather than compare object references).

Parent topic: Concepts - Managed COBOL
Related reference
Fields
Type Specifier
Related information
Strings - in COBOL and Java


Types and Type Conversion

Value types, reference types and boxing

Managed COBOL distinguishes between:

  • Value types (such as binary-long and System.DateTime in .NET). Value type data items contain the actual data. For example, a COBOL binary-long data item contains a 32 bit integer.
  • Reference types, which are allocated on the object heap. Reference type data items hold a reference into the object heap. Reference types are under the management of the garbage collector, which will reclaim the space on the object heap at the point when there are no longer any active references.

All value types can be turned into reference types by a process known as boxing. For example, you can set an object reference to a value type, such as a binary-long. During boxing, the system copies the value into the object heap and returns a reference to it.

Boxing happens automatically when needed, for example when a value type is passed as a parameter to a method that expects an object as a parameter.

You can box explicitly by assigning a value type to a generic object (such as System.Object in .NET COBOL or java.lang.Object in JVM COBOL). You can unbox value types to restore the original value type.

When you specify TYPE classname in the data item definition:

  • If classname represents a reference type, you get a reference type object.
  • If classname represents a value type, you get a value type object.

Type information

Every class has an associated root object, which can be used to get information about the class such as its fields and methods. To obtain type information, you use the following:

  • In NET COBOL, GetType() - to obtain the System.Type object for an object reference
  • In JVM COBOL, getClass() - to obtain the java.lang.Class object reference
  • TYPE OF - to obtain the System.Type or java.lang.Class object for a class, interface, delegate or enumeration
    imperative-clause TYPE OF type-name
  • TYPE OF type-name[ANY...] - to obtain the System.Type (.NET) or java.lang.Class (JVM) object for a generic class, interface, or delegate.

For example, in JVM COBOL:

*>Value Types
*>condition-value
*>binary-char (unsigned)
*>character
*>binary-short, binary-long, binary-double (unsigned)
*>float-short, float-long
*>decimal
*>DateTime (a framework type)

*>Reference types
*>object
*>string

*>Initializing
declare correct as condition-value = true
*> Can also infer variable type if the value has a well-defined type
declare incorrect = false  *> automatically a condition-value
declare b as byte = h"2a"  *> hex
declare o as byte = o"52"  *> octal
declare b2 as byte = b"101010" *> binary
declare person as object = null
declare nam as string = "Dwight"
declare grade as character = "B"
declare now as type DateTime = type DateTime::Now
*> No support for date/time literals
declare amount as decimal = 35.99
declare gpa as float-short = 2.9
declare pi as float-long = 3.14159265
declare lTotal as binary-double = 123456
declare sTotal as binary-short = 123
declare usTotal as binary-short unsigned = 123
declare uiTotal as binary-long = 123
declare ulTotal as binary-long unsigned = 123

*>Type Information
declare x as binary-long
display x::GetType            *> Prints System.Int32
display type of binary-long   *> Prints System.Int32
display x::GetType::Name      *> Prints Int32
*>Type Conversion
declare f as float-short = 3.5   *> automatic conversion
declare i = f as binary-long     *> set to 3 (truncates decimal)

end program.

program-id Legacy.
*> COBOL types not supported directly by other languages.
*> Visual COBOL supports these types on all platforms.
*> Only a few examples here
01 displayNumber pic 9(9).99.
01 computeNumber pic 9(9)V99.
01 alphaNumberic pic a(23).
01 binaryStorage pic x(12).
*> Also groups and redefines - a few examples
01 arecord.
   03 aSubRecord pic x(10).
   03 aUnion     pic 9(10) redefines aSubrecord.
end program.

Type conversions

A type conversion allows an expression of some type to be converted to a different type. There are two kinds of type conversion, explicit and implicit. In order to perform an explicit conversion, it is necessary to use the AS or AS IF phrase, specifying the required target type. An example of this type of conversion is:

Declare myAnimal as type Animal
Declare myWarthog as type Warthog
…
Set myWarthog to myAnimal as type Warthog    *> Convert type Animal to type Warthog

The explicit conversion is necessary because not all objects of type Animal are of type Warthog.

An example of an implicit conversion is:

Set myAnimal to myWarthog

Because type Warthog derives from type Animal, the conversion is always legitimate and can be done implicitly. Similarly, using implicit conversion, myWarthog can be passed as an argument to any method that has a by value parameter of type Animal.

Implicit conversions

COBOL allows the following kinds of implicit conversion:

  • Implicit numeric conversions
  • Implicit enum conversions
  • Implicit reference conversions
  • Boxing conversions
  • User-defined implicit conversions
  • Anonymous method conversions
  • Method group conversions

The main contexts in which implicit conversions occur are:

  • Assignments (e.g. SET and DECLARE statements)
  • Parameter passing

Implicit enum conversions

The numeric literal 0 can be converted to any enum type.

Note: This kind of version is allowed in .NET COBOL, but not in JVM COBOL.

Implicit reference conversions

An implicit conversion from type S to type T is allowed in the following cases:

  • S is derived from T
  • T is an interface type and S implements T
  • S and T are both arrays of the same dimensionality and:
    • The array elements of S and T are both reference types and;
    • An implicit reference conversion exists from the element type of S to the element type of T

Note that in .NET COBOL:

  • All array types derive from the type System.Array
  • All single dimensional arrays, e.g. type S[] implement the interface System.Collections.Generic.IList[S]
  • All delegate types derive from the type System.MulticastDelegate, which itself defives from System.Delegate

Some examples of implicit reference conversions:

01 appDomain type System.AppDomain.
01 obj object.
01 myList type List[string].
01 myEnumerable type IEnumerable[string].
01 objArray object occurs 10.
01 strArray string occurs 10.

set obj to appDomain       *>   type System.AppDomain derives from System.Object
set appDomain to obj       *> produces compile time error
set myEnumerable to myList *> List[string] implements IEnumerable[string]
set objArray to strArray   *> source element type derives from target element type

Boxing conversions

In .NET COBOL, any value type can be converted to a reference type, either of type System.Object or of type System.ValueType. An enum type can also be converted to type System.Enum.

In JVM COBOL, the primitive types may be converted to boxed types as follows:
  • Binary-char can be converted to java.lang.Byte
  • Binary-short can be converted to java.lang.Short
  • Binary-long can be converted to java.lang.Integer
  • Binary-double can be converted to java.lang.Long
  • Condition-value can be converted to java.lang.Boolean
  • Character can be converted to java.lang.Character
  • Float-short can be converted to java.lang.Float
  • Float-long can be converted to java.lang.Double

User-defined implicit conversions

A user defined implicit conversion exists from type S to type T if there exists an implicit user defined type conversion operator (see below) from type S1 to type T1 such that:

  • S is the same as S1 or there exists a non-user-defined conversion from S to S1
  • T is the same as T1 or there exists a non-user-defined conversion from T1 to T

Anonymous method conversion

An anonymous method with signature S can be converted to any delegate type with the same signature and return type. Also, an anonymous method with no parameters can be converted to any delegate type with the same return type.

Method group conversions

A method group with method name method-name can be converted to a delegate type with signature S and return type R if there exists a method within that method group (i.e. a method with the specified name) with the same signature and return type.

Explicit conversions

Explicit conversions are specified using the AS [ IF ] phrase. They can be used anywhere that an expression of the target type is permitted.

COBOL allows the following kinds of explicit conversion:

  • All implicit conversions including numeric conversions
  • Explicit enum conversions
  • Explicit reference conversions
  • Unboxing conversions
  • User-defined explicit conversions

Explicit enum conversions

Any enum type may be explicitly converted to any numeric type.

Any numeric type may be explicitly converted to any enum type.

Explicit reference conversions

An explicit conversion from type S to type T (also known as a cast) is allowed in the following cases:

  • Type T is derived from type S
  • Type S is a class type and type T is an interface type and S does not implement T and S is not final
  • Type S is in interface type and type T is a class type, and T is not final or T implements S
  • S and T are both interface types, and S is not derived from T
  • S and T are both array types with the same dimensionality and:
    • The array elements of S and T are both reference types and;
    • An explicit reference conversion exists from the element type of S to the element type of T

If the cast fails, an exception is thrown (InvalidCastException for .NET or ClassCastException for JVM). To avoid this, you can: test for a valid cast first using INSTANCE OF; wrap the cast in an exception block (see the TRY Statement for more information); or use the AS IF phrase, which in the case of an invalid cast sets the target object to null and does not throw an exception (see cast expressions for more information).

Some examples of explicit reference conversions:
01 appDomain type System.AppDomain.
01 obj object.
01 myList type List[string].
01 myEnumerable type IEnumerable[string].
01 objArray object occurs 10.
01 strArray string occurs 10.

*> Following allowed as type System.AppDomain derives from object
set appDomain to obj as type System.AppDomain
*> Following allowed as list[string] implements IEnumerable[string]
set myList to myEnumerable as type List[string]
*> Following allowed as there exists an explicit reference conversion
*> from object (the element type of objArray) to string (element type of strArray)
set strArray to objArray as string occurs any
*> explicit conversions can be used anywhere…
display obj as type System.AppDomain
set obj to type of object    *> sets obj to a System.Type object
*> The following will throw an exception
set appDomain to obj as type System.AppDomain
*>
*> this statement does not fail, but sets myString to null
*> set myString to myObject as if string
An exception is thrown in the following as we are claiming obj-object references a System.AppDomain instance where in fact it's referencing a System.Type instance.
*> these statements fail if uncommented
*> set obj-object to obj-type
*> set obj-app-domain to obj-object as type System.AppDomain

Unboxing conversions

In .NET COBOL, items of type System.Object or of type System.ValueType can be explicit converted to a value type. Items of type System.Enum can be converted to enum types.

For example:

01 obj object.
01 dt type System.DateTime.

Set obj to dt                          *> this is an implicit conversion using boxing
Set dt to obj as type System.DateTime  *> explicit unboxing conversion
In JVM COBOL, following types may be converted to primitive types:
  • java.lang.Byte can be converted to binary-char
  • java.lang.Short can be converted to binary-short
  • java.lang.Integer can be converted to binary-long
  • java.lang.Long can be converted to binary-double
  • java.lang.Boolean can be converted to condition-value
  • java.lang.Character can be converted to character
  • java.lang.Float can be converted to float-short
  • java.lang.Double can be converted to float-long

User defined explicit conversions

A user defined explicit conversion exists from type S to type T if there exists an explicit user defined type conversion operator (see below) from type S1 to type T1 such that:

  • S is the same as S1 or there exists a non-user-defined explicit conversion from S to S1
  • T is the same as T1 or there exists a non-user-defined explicit conversion from T1 to T

Creating user-defined conversion operators

A conversion operator converts a data item from one data type into another, such as from a type that you have defined into an integer. Conversion operators can be overloaded, so that the appropriate conversion operator is used according to the parameter types in the calling code.

Creating implicit conversions

For example, the type Timer, which contains hours and minutes, is converted into minutes as binary-long using the following conversion operator:

operator-id Implicit (a as type Timer) returning b as binary-long.

  set b to a::Hour * 60 + a::Minutes
end operator.

This operator can then be used in statements such as:

set myMins to timer3

Similarly, you can convert from a binary-long data item (representing a number of minutes) to the type Timer, which is expressed in hours and minutes, using the following conversion operator:

operator-id Implicit (a as binary-long) returning b as type Timer.

  set b to new Timer
  declare hour as binary-long = a / 60
  set b::Hour to hour
  set b::Minutes to a - 60 * hour
end operator.

This operator can then be used in statements such as:

set timer4 to myMins

Implicit conversions can occur in all sorts of places, such as assignments and member invocations.

You can invoke an implicit conversion implicitly or explicitly. For example, the following statements both invoke the implicit conversion:

set myMins to timer3
set myMins to timer3 as binary-long

You use implicit conversions where the conversion is reliable, where it will not lose information and will not throw an exception.

Creating explicit conversions

operator-id Explicit (a as String) returning b as type Timer.
01 strH String.
01 strM String.
01 colonPos  binary-long value 0.

  set b to new Timer()
  set colonPos to a::IndexOf(":")
  try
    set strH to a::Substring(0 colonPos)
    set strM to a::Substring(colonPos + 1 2)
    set b::Hour to type Int32::Parse(strH)
    set b::Minutes to type Int32::Parse(strM)
  catch
    display "Invalid time format"
  end-try
end operator.

Explicit conversions occur only in statements that explicitly state the type to convert to. For example, where the conversion operator is defined as explicit, only the second statement below works:

set timer4 to myString                *> fails to compile as no implicit conversion exists
set timer4 to myString as type Timer  *> succeeds

You use explicit conversions (as opposed to implicit ones) where the conversion has the potential to lose information or throw an exception. In the above example, the string might contain text or be invalid somehow. In this case, a try-catch block is required to handle the failure.

Parent topic: Concepts - Managed COBOL
Related reference
Procedure Division Header
INVOKE Statement
Type Specifier
TRY Statement
Expressions
Related information
Data Types - in COBOL and Java
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code


Type Compatibility of .NET and JVM COBOL with Other Managed Languages

Many managed COBOL (.NET COBOL and JVM COBOL) types have a strict correspondence with managed types in other languages, such as binary-long and float-short. For those that don't have a correspondence, there are alternatives.

The following table lists the correspondence between the .NET and JVM COBOL types and classes and types in other managed languages.

Managed COBOL (.NET or JVM COBOL) | .NET type | JVM type | C# keyword | Description
Integer types:
binary-char | System.SByte | byte | sbyte | An 8-bit signed integer Not CLS-compliant
binary-char unsigned | System.Byte |  | byte | An 8-bit unsigned integer
binary-short | System.Int16 | short | short | A 16-bit signed integer Not CLS-compliant
binary-short unsigned | System.UInt16 |  | ushort | A 16-bit unsigned integer
binary-long | System.Int32 | int | int | A 32-bit signed integer
binary-long unsigned | System.UInt32 |  | uint | A 32-bit unsigned integer Not CLS-compliant.
binary-double | System.Int64 | long | long | A 64-bit signed integer
binary-double unsigned | System.UInt64 |  | ulong | A 64-bit unsigned integer Not CLS-compliant
Floating point types:
float-short | System.Single | float | float | A single-precision (32-bit) floating-point number
float-long | System.Double | double | double | A double-precision (64-bit) floating-point number
Logical types:
condition-value | System.Boolean | boolean | bool | A boolean value (true or false)
Other types:
character | System.Char | char | char | A unicode (16-bit) character
decimal | System.Decimal | see JVMDECIMAL. | decimal | A 96-bit decimal value
Class objects:
object | System.Object | java.lang.Object | object | The root of the object hierarchy
string | System.String | java.lang.String | string | An immutable, fixed-length string of Unicode characters
Collection types:
list | System.Collections.Generic.IList<T> | java.util.List |  | An ordered collection of items
dictionary | System.Collections.Generic.IDictionary<TKey, TValue> | java.util.Map |  | A mapping of keys to values
set | System.Collections.Generic.ISet<T> | java.util.Set<T> |  | An unordered collection of items

Examples:

       local-storage section.
       01 aByte binary-char unsigned.
       01 aSignedByte binary-char.
       01 anInt16 binary-short.
       01 anInt32 binary-long.
       01 anInt64 binary-double.
       01 anUnsignedInt16 binary-short unsigned.
       01 anUnsignedInt32 binary-long unsigned.
       01 anUnsignedInt64 binary-double unsigned.
       01 aSingle float-short.
       01 aDouble float-long.
       01 aBoolean condition-value.
       01 aChar character.
       01 aDecimal decimal.
       01 anIntPtr type IntPtr.
       01 anUnsignedIntPtr type UIntPtr.
       01 anObject object.
       01 aString string.
Parent topic: Concepts - Managed COBOL
Related reference
Procedure Division Header
Type Specifier
Related information
Types and Type Conversion
Data Types - in COBOL and Java
Type Mappings from Native COBOL to Managed Code


Comparison of COBOL with Other Managed Languages

The following topics show examples of various programming techniques and constructs in COBOL compared with Java.

  • Arrays - in COBOL and Java
  • Async - in COBOL and Java
  • Attributes - in COBOL and Java
  • Classes - in COBOL and Java
  • Comments - in COBOL and Java
  • Conditions - in COBOL and Java
  • Constants - in COBOL and Java
  • Constructors and Destructors - in COBOL and Java
  • Data Types - in COBOL and Java
  • Delegates and Events - in COBOL and Java
  • Enums - in COBOL and Java
  • Exception Handling - in COBOL and Java
  • Generics - in COBOL and Java
  • Generics, Defining - in COBOL and Java
  • Interfaces - in COBOL and Java
  • Iterators - in COBOL and Java
  • Loops - in COBOL and Java
  • Methods - in COBOL and Java
  • Namespaces - in COBOL and Java
  • Objects - in COBOL and Java
  • Operators - in COBOL and Java
  • Program Structure - in COBOL and Java
  • Properties - in COBOL and Java
  • Strings - in COBOL and Java
  • Structures, Value Types - in COBOL and Java
  • Synchronization - in COBOL and Java
Parent topic: JVM COBOL
Related reference
Access Modifiers


Arrays - in COBOL and Java

COBOL Java
declare nums = table of binary-long (1 2 3)

declare names as string occurs 5
*> Can also do:
declare names-again as string occurs any
set size of names to 5

set names(1) to "David"  *> first element indexed as 1
*> ...but can also use zero based subscripting:
set names[0] to "David"  *> first element indexed as 0

*>set names(6) to "Bobby"  *> throws System.IndexOutOfRangeException

*> COBOL does not have direct resizing syntax but achieves similar
*> results using 'reference modification' syntax:
declare names2 as string occurs 7
set names2[0:size of names] to names
*> Resizing to a smaller size is even simpler:
set names2 to names[0:3]

declare twoD as float-short occurs any, any.
declare rows as binary-long = 3
declare cols as binary-long = 10
set size of twoD to rows, cols

declare jagged = table of (table of binary-long(1 2)
                           table of binary-long(3 4 5)
                           table of binary-long(6 7 8 9))

*> Can also do:
declare jagged2 as binary-long occurs any, occurs any
set size of jagged2 to 3
set size of jagged2(1) to 5
set jagged2(1 5) to 5

public class Arrays
{
    public static void main(String args[])
    {
        int nums[] = { 1, 2, 3 };

        String names[] = new String[5];

        names[0] = "David";

        // names[5] = "Bobby"; // throws ArrayIndexOutOfBoundsException

        // Can't resize arrays in Java

        String names2[];

        // Copy elements from an array
        names2 = java.util.Arrays.copyOfRange(names, 0, 3);

        float twoD[][];

        int rows = 3;
        int cols = 10;

        twoD = new float[rows][cols];

        int[][] jagged = { { 1, 2 }, { 3, 4, 5 }, { 6, 7, 8, 9 } };

        int[][] jagged2 = new int[3][];
        jagged[0] = new int[5];
        jagged[0][4] = 5;

    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Indexers
SET Statement
Related information
Creative Commons License


Async - in COBOL and Java

COBOL Java
*> Calling async methods
 invoke await type Task::Delay(1000)
 declare items = await ProcessItemsAsync("user", 8)

*> Run code on background thread
 await type Task::Run(
     delegate
         invoke type Console::WriteLine("On background thread")
     end-delegate)

*> An async void method
 method-id button1_Click async-void (sender as object,
                                     e as type EventArgs).
     set button1::Enabled to false
     invoke await type Task::Delay(1000)
     set button1::Enabled to true
 end method.
*> An async method returning no result
 method-id Task ProcessAsync() async.
     invoke await type Task::Yield()
     invoke type Console::WriteLine("async...")
 end method.
*> An async method returning a result
 method-id ProcessItemsAsync async (#type as string,
                                    #count as binary-long)
     yielding items as string occurs any.
     invoke await type Task::Delay(1000)
set items to table of ("a", "b", "c")
 end method.
*> An async value-task method returning a result
 method-id MaybeProcess async-value (x as condition-value)
                        yielding result as string.
     if x
         invoke await type Task::Delay(1000)
         set result to "x"
     else
         set result to "y"
     end-if
 end method.

// Java has no async coroutine support.
// Similar behaviour is typically achieved by using
// executors.

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages


Attributes - in COBOL and Java

COBOL Java
*> Attribute on a class
class-id Attributes
    attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a field
01 book string attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a property
01 bookProperty string property
    attribute Author(name AuthorName = "Benjamin Franklin").

*> Attribute on a method and argument
method-id GetAnotherBook
    attribute Author(name AuthorName = "Benjamin Franklin")
    (arg1 as string
        attribute Author(name AuthorName = "Benjamin Franklin"))
    returning return-value as string.
        set return-value to book
end method.

end class.

*> Attribute definition
 attribute-id AuthorAttribute public.
 01 AuthorName string property.

end attribute.

// Java terminology : annotation
// Annotation definition
import java.lang.annotation.*;

// Annotation on a class
@authorAttribute(authorName = "Benjamin Franklin")
public class attributes {

    // Annotation on a field
    @authorAttribute(authorName = "Benjamin Franklin")
    String book;

    // Annotation on a method
    @authorAttribute(authorName = "Benjamin Franklin")
    String getTheBook() {
        return book;
    }

    // Annotation on an argument
    @authorAttribute(authorName = "Benjamin Franklin")
    String getAnotherBook(
        @authorAttribute(authorName = "Benjamin Franklin") String arg1) {
        return book;
    }
}

// Annotation declaration
@Retention(RetentionPolicy.RUNTIME)
@interface authorAttribute {
    public String authorName();
}
Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Attributes
Related information
Creative Commons License


Classes - in COBOL and Java

COBOL Java

// Closest possible form of a static class
final class Utils
{
private Utils() { }
public static int square(int x)
{
return x * x;
}
}
// Abstract class
public abstract class Shape
{
protected abstract int getArea();
public String toString()
{
return "Area = " + getArea();
}
}
// Sub class
public class Rectangle extends Shape
{
private int _width, _height;
public int getWidth() { return _width; }
public void setWidth(int value) { _width = value; }
public int getHeight() { return _height; }
public void setHeight(int value) { _height = value; }
protected int getArea() { return _width * _height; }
}
// Sub class of a sub class
public class Square extends Rectangle
{
private int _size;
public int getSize() { return _size; }
public void setSize(int value) { _size = value; }
public int getWidth() { return _size; }
public void setWidth(int value) { _size = value; }
public int getHeight() { return _size; }
public void setHeight(int value) { _size = value; }
protected int getArea() { return Utils.square(getSize()); }
public String toString()
{
return "Square, " + super.toString();
}
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages


Comments - in COBOL and Java

COBOL Java
$set sourceformat(variable)
      * Single line "old-style" COBOL comment with '*' in column 7
               *> inline comment may follow COBOL statements etc.
         *>> <summary>XML comments</summary>

// Comments on a single line

/*
   C style multi-line comments
 */

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Conditions - in COBOL and Java

COBOL Java
declare age as binary-long = 10
declare greeting as string
*>greeting = age < 20 ? has no directly equivalent syntax in COBOL

if age < 20
   move "What's up?" to greeting
else
   move "Hello" to greeting
end-if

declare x as binary-long = 200
declare y as binary-long = 3
if x not = 100 and y < 5
   multiply 5 by x
   multiply 2 by y
end-if

*> evaluate is preferred in COBOL rather than if/else if/else
evaluate x
when > 5
   multiply y by x
when 5
   add y to x
when < 10
   subtract y from x
when other
   divide y into x
end-evaluate

declare color as string = "blue"
declare r b g other-color as binary-long
evaluate color   *> can be any type
when "pink"
when "red"
   add 1 to r
when "blue"
   add 1 to b
when "green"
   add 1 to g
when other
   add 1 to other-color
end-evaluate

public class choices
{

    public static void main(String[] args)
    {
        int age = 10;
        String greeting = age < 20 ? "What's up?" : "Hello";

        if (age < 20)
        {
            greeting = "What's up?";
        } else
        {
            greeting = "Hello";
        }

        int x = 200;
        int y = 3;

        if (x != 100 && y < 5)
        {
            x = 5 * x;
            y = 2 * y;
        }

        if (x > 5)
        {
            x = x * y;
        }
        else if (x == 5)
        {
            x = x + y;
        }
        else if (x < 10)
        {
            x = x - y;
        }
        else
        {
            x = x / y;
        }

        String color = "blue";
        int r = 0, b = 0, g = 0, other_color = 0;

        if (color.equals("pink") || color.equals("red"))
        {
            r++;
        }
        else if (color.equals("blue"))
        {
            b++;
        }
        else if (color.equals("green"))
        {
            other_color++;
        }

    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
IF Statement
Related information
Creative Commons License


Constants - in COBOL and Java

COBOL Java
class-id Students.

*> optionally public etc., and may reference constants in other classes
01 MAX_STUDENTS binary-long constant value 25 + 3.

*> Can set to a const or var; may be initialized in a constructor
01 MIN_DIAMETER float-short value 4.93 initialize only.

method-id Main().
    display MAX_STUDENTS
    display MIN_DIAMETER
end method.

end class.

public class constants
{
    // constant value cannot be changed ;
    public static final int MAX_STUDENTS = 25 + 3;

    // This value can be assigned at declaration
    // OR
    // assigned in constructor
    // (not both)
    public final float MIN_DIAMETER = 4.93f;

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Fields
Related information
Creative Commons License


Constructors and Destructors - in COBOL and Java

COBOL Java
class-id SuperHero.
01 _powerLevel binary-long.

method-id new.
    set _powerLevel to 0
end method.

method-id new (powerLevel as binary-long).
    set _powerLevel to powerLevel
end method.

$if JVMGEN set
method-id Finalize override protected.
    *> JVM finalizer method.
end method.
$else
method-id Finalize override protected.
    *> .NET finalizer method.
end method.
$end
end class.

public class ConstructorsDestructors
{
    private int _powerOevel;

    public ConstructorsDestructors(int powerLevel)
    {
        _powerOevel = powerLevel;
    }

    @Override
    public void finalize()
    {
        // finalizer code
    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constructors
Related information
Creative Commons License


Data Types - in COBOL and Java

COBOL Java
*>Value Types
*>condition-value
*>binary-char (unsigned)
*>character
*>binary-short, binary-long, binary-double (unsigned)
*>float-short, float-long
*>decimal
*>DateTime (a framework type)

*>Reference types
*>object
*>string

*>Initializing
declare correct as condition-value = true
*> Can also infer variable type if the value has a well-defined type
declare incorrect = false  *> automatically a condition-value
declare b as byte = h"2a"  *> hex
declare o as byte = o"52"  *> octal
declare b2 as byte = b"101010" *> binary
declare person as object = null
declare nam as string = "Dwight"
declare grade as character = "B"
declare now as type DateTime = type DateTime::Now
*> No support for date/time literals
declare amount as decimal = 35.99
declare gpa as float-short = 2.9
declare pi as float-long = 3.14159265
declare lTotal as binary-double = 123456
declare sTotal as binary-short = 123
declare usTotal as binary-short unsigned = 123
declare uiTotal as binary-long = 123
declare ulTotal as binary-long unsigned = 123

*>Type Information
declare x as binary-long
display x::GetType            *> Prints System.Int32
display type of binary-long   *> Prints System.Int32
display x::GetType::Name      *> Prints Int32
*>Type Conversion
declare f as float-short = 3.5   *> automatic conversion
declare i = f as binary-long     *> set to 3 (truncates decimal)

end program.

program-id Legacy.
*> COBOL types not supported directly by other languages.
*> Visual COBOL supports these types on all platforms.
*> Only a few examples here
01 displayNumber pic 9(9).99.
01 computeNumber pic 9(9)V99.
01 alphaNumberic pic a(23).
01 binaryStorage pic x(12).
*> Also groups and redefines - a few examples
01 arecord.
   03 aSubRecord pic x(10).
   03 aUnion     pic 9(10) redefines aSubrecord.
end program.

import java.math.BigDecimal;
import java.time.LocalDateTime;

public class DataTypes
{
// Java doesn't have value types, though it does have
// "primitives" avaialble for the common types, which
// are similar in some respects
// boolean
// byte
// char
// short, int, long
// float, double
// BigDecimal   (a framework type)

    @SuppressWarnings("unused")
    public static void main(String[] args)
    {
        boolean correct = true;
        // no mechanism for automatic typing
        byte b = 0x2a; // hex
        byte o = 052; // octal
        byte b2 = 0b101010; // binary (Java 7 onwards)
        Object person = null;
        String nam = "Dwight";
        char grade = 'B';
        LocalDateTime now = LocalDateTime.now();
        // No support for date/time literals
        BigDecimal amount = new BigDecimal(35.99);
        float gpa = 2.9f;
        double pi = 3.14159265;
        long lTotal = 123456;
        short sTotal = 123;

        // Java has no unsigned integer types

        // Java reflection does not work on primitive types.
        Integer x = new Integer(0);
        System.out.println(x.getClass().getCanonicalName());

        // Type conversion
        short f = (short) 3.5 ; // must use cast to convert
        int i = f; // set to 3 (truncation)
    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Local Data Item Declaration
Fields
Related information
Types and Type Conversion
Type Compatibility of .NET and JVM COBOL with Other Managed Languages
Type Mappings from Native COBOL to Managed Code
Creative Commons License


Delegates and Events - in COBOL and Java

COBOL Java
delegate-id MessageHandler (str as string).
end delegate.

class-id DelegatesEvents.

01 MessageArrived     event type MessageHandler static.

method-id Main static.
  *> explicit delegate construction
  invoke new MessageHandler(MyHandler)

  *> implicit delegate construction
  declare handler as type MessageHandler = method MyHandler

  *> subscribe to an event
  attach method MyHandler to MessageArrived

  *> raise the event
  invoke MessageArrived("Test message")

  *> unsubscribe from the event
  detach method MyHandler from MessageArrived

  *> Throws a null reference exception as there are no subscribers
  invoke MessageArrived("Test message 2")

  *> Safely raising an #event
  declare handler2 as type MessageHandler = MessageArrived
  if handler2 not equals null
     invoke handler1("Safe message")
  end-if

end method.

method-id MyHandler static (str as string).
  display str
end method.

end class.

// Java has no concept of delegates or events.
// Similar behavior is typically achieved by using
// anonymous inner classes instead.

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Delegates and Events
Related information
Creative Commons License


Enums - in COBOL and Java

COBOL Java
enum-id Action.
   78 #Start.   *> Start is a reserved word so use '#' symbol
   78 #Stop.
   78 #Rewind.
   78 #Forward.
end enum.

enum-id Status.
   78 Flunk value 50.
   78 Pass  value 70.
   78 Excel value 90.
end enum.

class-id MainClass.
method-id main static.
   declare a = type Action::Stop
   if a not = type Action::Start
       display a & " is " & a as binary-long   *> Prints "Stop is 1"
    end-if
   display type Status::Pass as binary-long    *> prints 70
   display type Status::Pass *> prints
end method.
end class.

public class enumeration
{
    public enum Action
    {
        Start,
        Stop,
        Rewind,
        Forward;
    }

    public enum Status
    {
        Flunk(50),
        Pass(70),
        Excel(90);

        int mark;

        public int getMark()
        {
            return mark;
        }

        Status(int mark)
        {
            this.mark = mark;
        }
    }

    public static void main(String[] args)
    {
        Action a = Action.Stop;
        if (a != Action.Start)
        {
            // Ordinal is printing out the 0-based index of the entry
            // rather than its "value"
            System.out.println(a +  " is " + new Integer(a.ordinal()).toString());

            System.out.println(Status.Pass.getMark());// can only print value
                                                      // if enum defines method
            System.out.println(Status.Pass); // prints Pass
        }

    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Enums
Related information
Creative Commons License


Exception Handling - in COBOL and Java

COBOL Java
*> Throw an exception
declare exc = new Exception("Something is really wrong.");
 raise exc
*> Catch an exception
declare x y as binary-long
try
  declare o as string = null
  display o[0]  *> display first character

catch ex as type Exception
  display ex
finally
  display "Finally"
end-try

public class ExceptionHandling
{

    public static void main(String[] args) throws Exception
    {
        Exception e = new Exception("Something is really wrong.");
        throw e;
    }

    public void nullReference()
    {
        try
        {
            String o = null;
            System.out.println(o.charAt(0));
        }
        catch (Exception f)
        {
            System.out.println(f);
        }
        finally
        {
            System.out.println("Finally");
        }

    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
RAISE Statement
TRY Statement
Related information
Creative Commons License


Generics - in COBOL and Java

Table 1. Consuming
COBOL Java
*> Consuming a generic method via type inference

class-id Generics public.
01 point type IPoint[binary-double].
01 constrainedPoint type ConstrainedPoint[type PointImpl].
01 justAPoint type Point[string, string].

method-id init.
    *> initialize generic variables
    set point = new PointImpl()
    set constrainedPoint = new ConstrainedPoint[type PointImpl]()
    set justAPoint = new Point[string, string]()
    *> use generic variables
    invoke point::makePoint(1, 2, 3)
    invoke constrainedPoint::makeConstrainedPoint(point)
    set justAPoint::varT to "varT's value"
    set justAPoint::varN to "varN's value"
end method.
end class.

// Consuming a generic method
public class generics {
    IPoint<Long> point;
    ConstrainedPoint<PointImpl> cPoint;
    Point<String, String> justAPoint;

    public void init() {
        // initialize generic variables
        point = new PointImpl();
        cPoint = new ConstrainedPoint<PointImpl>();
        justAPoint = new Point<String, String>();
        // use generic variables
        point.makePoint(1l, 2l, 3l);
        cPoint.makeConstrainedPoint(point);
        justAPoint.varT = "varT's value";
        justAPoint.varN = "varN's value";
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Table 2. Defining
COBOL Java
*> Generic interface
interface-id IPoint using T
method-id makePoint using T (x as T, y as T, z as T).
end method.
end interface.

*> Generic class
class-id Point using T, N.
01 varT T public.
01 varN N public.
end class.

*> Generic class with constraints
class-id ConstrainedPoint using T.
constraints.
constrain T implements type IPoint[binary-double].
method-id makeConstrainedPoint using N (x as N).
constraints.
    constrain N implements type IPoint[binary-double].

end method.
end class.

*> Class with generic interface
class-id PointImpl
    implements type IPoint[binary-double].
method-id makePoint using T (x as T, y as T, z as T).

end method.
end class.

// Generic interface
interface IPoint<T> {
    void makePoint(T x, T y, T z);
}

// Generic class
class Point<T, N> {
    public T varT;
    public N varN;
}

// Generic class with constraints
class ConstrainedPoint<T extends IPoint<Long>> {
    <N extends IPoint<Long>> void makeConstrainedPoint(N x) {

    }
}

// Class with generic interface
class PointImpl implements IPoint<Long> {

    @Override
    public void makePoint(Long x, Long y, Long z) {

    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Generics, Defining - in COBOL and Java

Table 1. Defining
COBOL Java
*> Generic interface
interface-id IPoint using T
method-id makePoint using T (x as T, y as T, z as T).
end method.
end interface.

*> Generic class
class-id Point using T, N.
01 varT T public.
01 varN N public.
end class.

*> Generic class with constraints
class-id ConstrainedPoint using T.
constraints.
constrain T implements type IPoint[binary-double].
method-id makeConstrainedPoint using N (x as N).
constraints.
    constrain N implements type IPoint[binary-double].

end method.
end class.

*> Class with generic interface
class-id PointImpl
    implements type IPoint[binary-double].
method-id makePoint using T (x as T, y as T, z as T).

end method.
end class.

// Generic interface
interface IPoint<T> {
    void makePoint(T x, T y, T z);
}

// Generic class
class Point<T, N> {
    public T varT;
    public N varN;
}

// Generic class with constraints
class ConstrainedPoint<T extends IPoint<Long>> {
    <N extends IPoint<Long>> void makeConstrainedPoint(N x) {

    }
}

// Class with generic interface
class PointImpl implements IPoint<Long> {

    @Override
    public void makePoint(Long x, Long y, Long z) {

    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constraints Paragraph
Generic Using Phrase
Related information
Creative Commons License


Interfaces - in COBOL and Java

COBOL Java
*> Interface definition
interface-id IClock
01 Hour      binary-long property with no set.
01 Minute    binary-long property with no set.

method-id Reset.
end method.

end interface.

*> Extending an interface
interface-id IAlarmClock implements type IClock.
01 AlarmHour   binary-long property.
01 AlarmMinute binary-long property.

method-id Snooze (#time as binary-long).
end method.

end interface.

*> Interface implementation
class-id WristWatch implements type IAlarmClock,
                               type System.IDisposable.

working-storage section.
01 Hour        binary-long property with no set.
01 Minute      binary-long property with no set.
01 AlarmHour   binary-long property.
01 AlarmMinute binary-long property.
method-id Dispose.
    invoke self::Reset()
end method.

method-id Reset.
    set Hour to 0
    set Minute to 0
    set AlarmHour to 0
    set AlarmMinute to 0
end method.

method-id Snooze (#time as binary-long).
    add #time to AlarmMinute
end method.

end class.

// Interface definition
interface IClock
{
    int getHour();
    int getMinute();

    void reset();
}

// Extending an interface
interface IAlarmClock extends IClock
{
    int getAlarmHour();
    void setAlarmHour(int value);
    int getAlarmMinute();
    void setAlarmMinute(int value);

    void snooze(int time);
}

// Interface implementation
class WristWatch implements IAlarmClock, java.io.Closeable
{
    private int _hour, _minute, _alarmHour, _alarmMinute;

    public int getHour() { return _hour; }
    public int getMinute() { return _minute; }
    public int getAlarmHour() { return _alarmHour; }
    public void setAlarmHour(int value) { _alarmHour = value; }
    public int getAlarmMinute() { return _alarmMinute; }
    public void setAlarmMinute(int value) { _alarmMinute = value; }

    public void close()
    {
        reset();
    }

    public void reset()
    {
        _hour = 0;
        _minute = 0;
        _alarmHour = 0;
        _alarmMinute = 0;
    }

    public void snooze(int time)
    {
        _alarmMinute += time;
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Interfaces
Related information
Creative Commons License


Iterators - in COBOL and Java

COBOL Java
$set ilusing(System.Collections.Generic)

class-id Iterators.

method-id Use static.

    perform varying i as binary-long thru GetSequence()
        display i
    end-perform

    declare #instance = new Iterators()
    perform varying i as binary-long thru #instance
        display i
    end-perform
end method.

iterator-id GetSequence static yielding retn as binary-long.
    declare c as binary-long = 1
    perform until exit
        add 1 to c

        *> yield the next number
        set retn to c
        goback

        if c < 5
            *> yield the next number
            set retn to c * 10
            goback
        else
            *> end the iterator
            exit iterator
        end-if
    end-perform
end iterator.

*> Define an iterator for the current class
iterator-id self yielding retn as binary-long.
    perform varying i as binary-long from 23 by -5 until i < 0
        set retn to i
        goback
    end-perform
end iterator.
end class.

// Java does not support coroutines so iterators can only be implemented
// as classes that implement java.util.Iterator.

import java.util.Iterator;

class iterators implements Iterable<Integer>
{
    public static void Use()
    {
        for (Iterator seq = new GetSequence(); seq.hasNext(); )
        {
            System.out.println(seq.next());
        }

        iterators instance = new iterators();
        for (int i : instance)
        {
            System.out.println(i);
        }
    }

    static class GetSequence implements Iterator<Integer> {
        private boolean nextIsMultiplied = false;
        private int c = 1;

        public boolean hasNext() {
            return c < 5;
        }

        public Integer next() {
            if (!nextIsMultiplied) {
                nextIsMultiplied = true;
                // yield the next number
                c++;
                return c;
            } else {
                nextIsMultiplied = false;
                // yield the next number
                return c * 10;
            }
        }
    }

    // Define an iterator for the current class
    public Iterator<Integer> iterator() {
        return new GetOtherIterator();
    }

    // Our iterator class that is created when iterating this instance
    static class GetOtherIterator implements Iterator<Integer> {
        private int i = 23;

        public boolean hasNext() {
            return i >= 0;
        }

        public Integer next() {
            int result = i;
            i -= 5;
            return result;
        }
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Indexers
Iterators
Related information
Creative Commons License


Loops - in COBOL and Java

COBOL Java
declare c as binary-long = 0

perform 10 times
    display "Again and "
end-perform

*>Pre-test loops:
perform until c >= 10
   add 1 to c
end-perform

perform varying c from 2 by 2 until c > 10
   display c
end-perform

perform varying c2 as binary-long from 2 by 2 until c2 > 10
   display c2
end-perform

*>Post-test loops:
set c = 0
perform with test after until c >= 10
   add 1 to c
end-perform

*> Varying

*>Array or collection looping
declare names as string occurs any
set content of names to ("Fred" "Sue" "Barney")
perform varying s as string through names
   display s
end-perform

*>Breaking out of loops:
declare i as binary-long = 0
perform until exit
   if i = 5
      exit perform
   end-if
   display i
   add 1 to i
end-perform

*>Continue to next iteration:
set i = 0
perform varying i from 0 by 1 until i >= 5
   if i < 4
      exit perform cycle
   end-if
   display i *>Only prints 4
end-perform

public class loops
{

    public static void main(String[] args)
    {
        int c = 0 ;

        // Java has no direct equivalent to perform n times

        // pre test loops
        // "while" means condition inverted from COBOL's "until"
        while ( c < 10);
        {
            c++;
        }

        for (int c2 = 2 ; c2 > 10 ; c2 += 2)
        {
            System.out.println(c2);
        }

        // Post test loops
        c = 0 ;
        do
        {
            c++;
        }
        while (c < 10 );

        // looping through arrays or lists
        String names[] = {"Fred", "Sue", "Barney"};
        for (String s : names)
        {
            System.out.println(s);
        }

        // break out of loops
        int i = 0;
        while (true)
        {
            if (i == 5)
                break;
            System.out.println(i);
            i++;
        }

        // Continue to next iteration:
        for (i = 0; i < 5 ; i++)
        {
            if (i < 4)
                continue;
            System.out.println(i);
        }
    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
PERFORM Statement
Related information
Creative Commons License


Methods - in COBOL and Java

COBOL Java
class-id Functions.
*> Pass by value (in, default), reference (in/out), and reference (out)
method-id TestFunc (x as binary-long,
                    reference y as binary-long,
                    output z as binary-long).
      add 1 to x, y
      move 5 to z
end method.

method-id InstMethod.
    declare a as binary-long = 1
    declare b as binary-long = 1
    declare c as binary-long
    invoke TestFunc(value a reference b output c)
    *> Or
    invoke self::TestFunc(a b c)
    display a space b space c

    declare total as binary-long
    *> Commas in parameter lists are optional
    set total to function sum(4 3 2 1) *> returns 10
    display total
end method.

method-id main static.
    declare i as binary-long
    set i to MySum(1 2 3 4)
    display i
    declare o = new self

    *> Parentheses are optional when there are no parameters.
    invoke o::InstMethod
    invoke SayHello("Strangelove", "Dr.")
    invoke SayHello("Madonna")
end method.

*> To create a non intrinsic variable argument list function:
method-id MySum static (params nums as binary-long occurs any)
                      returning mysum as binary-long.
    perform varying i as binary-long through nums
        add i to mysum
    end-perform
end method.

*> COBOL supports optional arguments/parameters.
*> The default value is specified with the syntax '= value'.
*> Optional parameters must be listed last.
method-id SayHello static (nam as string,
                           prefix as string = "").
      display "Greetings, " prefix space nam
end method.

end class.

public class functions
{
    // Java only allows arguments to be passed by value

    public static void main(String[] args)
    {
       int i = mySum(1, 2, 3, 4);
       System.out.println(i);
    }

    // Use ellipses to indicate a variable argument list
    public static int mySum(int... arguments)
    {
        int sum = 0;
        for (int i : arguments)
        {
            sum += i;
        }
        return sum;
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Constructors
INVOKE Statement
Related information
Extension Methods and Operators
Invoking a Method
Creative Commons License


Namespaces - in COBOL and Java

Namespaces can be set at the file level.

COBOL Java
*> At the file level
$set ilnamespace "MicroFocus.COBOL.Examples"

*> The directive can also be set at project
*> level to apply the name space to all classes in the project.

*> Alternatively, at the class level:

class-id MicroFocus.COBOL.Examples.MyClass.
end class.

*> namespace import at file level:
$set ilusing(MicroFocus.COBOL.Examples)

*> The directive can also be set at project
*> level to apply the import to the entire project.

package MicroFocus.COBOL.Examples;
public class namespaces
{

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related information
Creative Commons License


Objects - in COBOL and Java

COBOL Java
    declare hero = new SuperHero
    declare hero2 as type SuperHero
    declare obj as object
    declare lin as string

*> No "With" construct
    set hero::Name to "SpamMan"
    set hero::PowerLevel to 3

    invoke hero::Defend("Laura Jones")
    invoke type SuperHero::Rest   *> Calling static method

    set hero2 to hero      *> Both reference the same object
    set hero2::Name to "WormWoman"
    display hero::Name   *> Prints WormWoman

    set hero to null       *> Free the object

    if hero = null
        set hero to new SuperHero
    end-if

    set obj to new SuperHero
    if obj is instance of type SuperHero
        display "Is a SuperHero object."
    end-if

   end program.

*> Mark object for quick disposal
perform using reader as type StreamReader =
              type File::OpenText("test.txt")
  perform until exit
    declare lin = reader::ReadLine()
    if lin = null
        exit perform
    end-if
  end-perform
end-perform

public class using_objects
{
    public static void main(String[] args)
    {
        SuperHero hero = new SuperHero();
        SuperHero hero2;
        Object obj;
        String lin;

        hero.setName("SpamMan");
        hero.setPowerLevel(3);

        hero.defend("Laura Jones");
        SuperHero.rest(); // Static method

        hero2 = hero; // Both reference same object
        hero2.setName("WormWoman");
        System.out.println(hero.getName()); // prints "WormWoman"

        hero = null;

        if (hero == null)
        {
            hero = new SuperHero();
        }

        obj = new SuperHero();
        if (obj instanceof SuperHero)
        {
            System.out.println("Is a SuperHero object");
        }
    }
}

class SuperHero
{
    private String name;
    private int powerLevel ;

    public String getName()
    {
        return name;
    }

    public void setName(String name)
    {
        this.name = name;
    }

    public int getPowerLevel()
    {
        return powerLevel;
    }

    public void setPowerLevel(int powerLevel)
    {
        this.powerLevel = powerLevel;
    }

    public void defend(String defendee)
    {
    }

    public static void rest()
    {
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Classes
INVOKE Statement
SET Statement
Related information
Invoking a Method
Creative Commons License


Operators - in COBOL and Java

COBOL Java
*> Comparison operators:
*> = < > <= >= <>
 display (1 = 1) *> true

 display (1 > 2) *> false

 display (1 < 2) *> true

 display (1 <= 1) *> true

 display (1 >= 2) *> false

 display (0 <> 1) *> true

*> Arithmetic operators,
*> * / + - **

 display ( (5 + 1) * (5 - 1) / 2 ** 2 ) *> result 6
 display (function mod (5 3 ))        *> result 2

*> Local variable declarations
 declare a, b, c as binary-long
 declare d = "I'm a string" *> string type inferred from value

*> Assignment statements
*> move, set, compute
 set a = 1
 move 2 to b
 compute c = 3 * 6
 set a = 3 * 6

*> Type operator
 declare mystr as string = "string"
 declare myobj as object = mystr
 display (myobj instance of string) *> true

*> Bitwise
*> b-and, b-or, b-xor, b-not, b-left, b-right
 display (4 b-and 3)
 display (4 b-or 3)
 display (b-not 3)
 display (4 b-xor 3)
 display (4 b-left 1) *> shift left one place
 display (4 b-right 2) *> shift right two places

*> Logical
*> and, or, not

 display (true and false) *> false
 display (true or false) *> true
 display (not true) *> false

public class operators
{

    public static void main(String[] args)
    {
        // Comparison operators
        // = < > <= >= !=
        System.out.println(1 == 1); // true

        System.out.println(1 > 2); // false

        System.out.println(1 < 2); // true

        System.out.println(1 <= 1); // true

        System.out.println(1 >= 2); // false

        System.out.println(0 != 1); // true

        // Arithmetic operators
        // * / + -
        // No exponentiation operator - use static method Math.pow();
        System.out.println( (5 + 1) * (5 - 1) ); // result 24
        System.out.println( Math.pow(2, 3) ); // result 8
        System.out.println( 5 % 3 ); // result 2

        // Local variable declarations.
        int a, b, c;
        String d = "I'm a string" ; // no declaration type inference

        // Assignment statements
        // all have same format in Java
        a = 1 ;
        b = 2;
        c = 3 * 6;
        a = 3 * 6;

        // type operator
        String mystr = "string";
        Object o = mystr;
        System.out.println(o instanceof String); // true

        //Bitwise operations
        // & | ^ ~  << >>
        System.out.println (4 & 3);
        System.out.println (4 | 3);
        System.out.println (~3);
        System.out.println (4 ^ 3);
        System.out.println (4 << 1);  // shift left one place
        System.out.println (4 >> 2);  // shift right two places

       // Logical
       // && || !

        System.out.println (true && false); // false
        System.out.println (true || false); // true
        System.out.println (!true);  // false
    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Operators
Related information
Operator Overloading in Managed COBOL
Creative Commons License


Program Structure - in COBOL and Java

COBOL Java
class-id MicroFocus.Examples.HelloWorld.
*> member variable
01 field1           binary-long.

method-id Main static(args as string occurs any).
    declare nam as string = "Bob"
    *> See if an argument was passed from the command line
    if size of args > 0
        set nam to args[0] *> [] means 0 based index
    end-if
    display "Hello " & nam & "!"
end method.

end class.

public class program_structure
{
    // Member variable
    private String field1 ;

    public static void main(String[] args)
    {
        String nam = "Bob";
        // See if an argument was passed from the command line
        if (args.length > 0)
            nam = args[0];

    }

}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Classes
Related information
Creative Commons License


Properties - in COBOL and Java

COBOL Java
class-id MyClass.
working-storage section.
01 volume binary-long private.
property-id Volume binary-long.
  getter.
    set property-value to volume
  setter.
    if property-value < 0
      set volume to 0
    else
      set volume to property-value
    end-if
end property.
end class.
*> COBOL also allows you to expose fields as properties
class-id MyClass.
working-storage section.
01 llength  binary-long property as "Length".
01 width    binary-long property as "Width"   no get.
01 breadth  binary-long property as "Breadth" no set.
end class.
class-id a.
method-id main.
local-storage section.
01 foo type MyClass value new MyClass.
procedure division.
    add 1 to foo::Volume
    display foo::Volume
end method.
end class.

// Java's properties are entirely convention based,
// rather than being implemented by the system.
// As a result they exist only as getter and setter methods.

class Properties
{
  private int _size;

  // no equivalent for shorthand properties

  public int getSize()
  {
    return _size;
  }

  public void setSize(int newSize)
  {
    _size = newSize;
  }

  public void static main(String[] args)
  {
    Properties foo = new Properties()
    foo.setSize(foo.getSize() + 1);
    System.out.println(foo.getSize());
  }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
Properties
Related information
Creative Commons License


Strings - in COBOL and Java

COBOL Java
*> Escape sequences
*> COBOL string literals don't have escape sequences,
*> however you can specify strings as hex literals:
*> x"0d"  *> carriage-return
*> x"0a"  *> line-feed
*> x"09"  *> tab
*> "\"    *> backslash
*> """"   *> quote

*> String concatenation
    declare co as string = "Micro Focus" & x"09".
    set co to co & "Ltd"  *> "Micro Focus<tab>Ltd"

*> Chars
    declare letter as character = co[0]   *> letter is M
    set letter to 65 as character      *> "A"

    declare letters = as character occurs any = "abc".ToCharArray()
    *> letters now holds table of character ('a', 'b', 'c')

*> COBOL does not have verbatim string literals
    declare msg as string = "File is c:\temp\x.dat"

*> String comparison
   declare mascot = "Bisons"
*> compare value of strings rather than object references
   if mascot = "Bisons" *> true
*> Substring
   set s to mascot(2:3) *> s is "iso"
   set s to mascot[2:3] *> s is "son"

*> Replacement
set s to mascot::Replace("sons" "nomial") *> s is "Binomial"

*> Split
declare names = "Frank,Becky,Stephen,Helen"
declare parts as list[string]
set parts to names::Split(',') *> .NET

*> Date to string
declare dt as type DateTime
declare s as string value dt::ToString("MMM dd, yyyy") *> Oct 12, 1973

public class Strings
{

    public static void main(String[] args)
    {
        // Escape sequences:
        // "\n"  //  line-feed
        // "\t"  //  tab
        // "\\"    //  backslash
        // "\""   //  quote
        // string concatenation
        String co = "Micro Focus\t" ;
        co = co + "Ltd" ;  // "Micro Focus<tab>Ltd

        char letter = co.charAt(0);
        letter = (char) 65;  // "A"

        // String literal
        String msg = "File is c:\\temp\\x.dat";

        // String comparison
        String town = "Newbury";
        if (town.equals("Newbury"))
        {
            System.out.println("true");
        }

        // Substring
        System.out.println(town.substring(1, 3)); //Displays "ewb"

        // Split
        String names = "Frank,Becky,Stephen,Helen";
        String[] parts = names.split(","); // split argument is a regex

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related information
String Handling in Managed COBOL
Creative Commons License


Structures, Value Types - in COBOL and Java

COBOL uses the valuetype-id to define a value type.

COBOL Java
valuetype-id StudentRecord.
01 aName string public.
01 gpa float-short public.
method-id new.
procedure division using by value nam as string,
                                  gpa as float-short.
    set aName to nam
    set self::"gpa" to gpa
end method.
end valuetype.

class-id a.
method-id main static.
local-storage section.
01 stu type StudentRecord value new StudentRecord("Bob", 3.5).
01 stu2 type StudentRecord.
procedure division.
    set stu2 to stu
    set stu2::aName to "Sue"
    display stu::aName   *> Prints Bob
    display stu2::aName  *> Prints Sue
end method.
end class.

// Java has no equivalent to .NET's general purpose structs.

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
ValueTypes
Related information
Creative Commons License


Synchronization - in COBOL and Java

COBOL Java
*> Synchronize on an object's monitor,
*> in this case the current object
class-id synchronization public.
01 _items list[string].
method-id addItemsSafe (items as string occurs any).
    sync on self
        perform varying auto item thru items
            write _items from item
        end perform
    end-sync
end method.

method-id addItemSafe (item as string) sync.
    write _items from item
end method.

end class.

Class
// Synchronize on an object's monitor
// in this case the current object
public class synchronization {
    private ArrayList<string> _items;

    public void addItemsSafe(String[] items) {
        synchronized (this) {
            for (String item : items) {
                 _items.add(item);
            }
        }
    }
    synchronized public void addItemSafe(String item) {
        _items.add(item);
    }
}

Portions of these examples were produced by Dr. Frank McCown, Harding University Computer Science Dept, and are licensed under a Creative Commons License.

Parent topic: Comparison of COBOL with Other Managed Languages
Related reference
SYNC Statement
Related information
Creative Commons License


com.microfocus.cobol.runtimeservices

Restriction: com.microfocus.cobol.runtimeservices is supported for JVM COBOL only.

The com.microfocus.cobol.runtimeservices class library provides the following classes:

  • CallableProgram
  • Interop
  • RunUnit

To use these classes in your Java programs, add mfcobolrts.jar to the build path of your Java project. This file is located by default in the $COBDIR/bin directory.

For information on these classes, see the com.microfocus.cobol.runtimeservices Guide available in the Micro Focus Infocenter.

Parent topic: JVM COBOL
Related concepts
Java Calling JVM COBOL
Related information
Developing an application for multiple run units in Java


Panels

Note: The following documentation is only provided for your reference if you are using Panels within your existing applications. Panels is an old technology and Micro Focus does not recommend using it to create new applications.

Panels is a module that enables you to build windowing into an application. It comprises a set of routines that you can call from your COBOL programs.

The windowing features provided include overlapping windows, separate or synchronized updating of text and attributes, scrolling of text across a window and the creation of popup/pull-down menus.

Panels takes care of maintaining the areas of the screen that are overlaid by another window automatically. It is for programmers who require high performance screen handling facilities.

Panels enables you to create up to 65534 panels and to have 254 panels visible on the screen (subject to your machine having enough memory).

  • What is a Panel?
  • Using Panels
  • Text and Attributes for a Panel
  • Clipping a Panel
  • Panels Parameter Block
  • Panels Functions
  • Using Adis Functions with Panels
  • Panels Error Codes
  • Frequently Used Terms in Panels
Parent topic: General Reference


What is a Panel?

The basic concept in Panels is the panel. The panel can be considered as a virtual screen that can be written to just like a real screen. However, a panel can be larger or smaller than the real screen.

The contents of a panel are viewed through a window. It is the window associated with a panel that is actually displayed on the real screen. The window can be smaller than the actual size of the panel, in which case only part of the panel's contents are visible. The part of the panel which is visible through the window can be varied by the programmer. Any number of windows can be displayed on the screen at once, overlapping each other if necessary.

The window associated with a particular panel can either be visible on the screen (enabled) or it can be invisible (disabled). Even if the panel is disabled, it can still be written to, but its contents are not visible on the screen until the panel is enabled again. The position and size of a window on the screen can be altered at any time.

Any part of a panel can be written to or read from by a program. Also, any rectangular region of a panel can be scrolled in any direction.

The diagram below represents the relationship among screen, window and panel.

Vis. Rep. of panels, screens+windows

Parent topic: Panels


Using Panels

You use Panels by calling the Panels module using the CALL statement.

The CALL statement must include the panels-parameter-block, which contains all the fields you define when you are working with Panels.

You include the text-buffer and attribute-buffer parameters in the CALL statement, but you need this only if you are writing to, reading from, or scrolling a panel.

When a panel is created or the window is moved or resized, the size of the window might be reduced if one of the specified size cannot be created. This is known as clipping the height and width of the window.

  • Calling Panels
Parent topic: Panels
Related information
Panels Parameter Block


Calling Panels

Use the following CALL statement in your COBOL program:

call "PANELS" using   panels-parameter-block
                      [text-buffer]
                      [attribute-buffer]

where the parameters are:

panels-parameter-block | A level-01 item containing all the fields you define when you are working with Panels. The definitions for this group item are provided in the copyfile panlink.cpy which is supplied with this COBOL system. You never need to change panlink.cpy, instead, your program moves mnemonics to certain data items in panlink.cpy to specify what function Panels is to perform.
text-buffer | Contains text to be included in a panel, a name to associate with a panel, or a list of enabled panels. It must be defined in the Working-Storage Section of your program.
attribute-buffer | Contains attributes to be included in a panel. It must be defined in the Working-Storage section of your program.

You must include panels-parameter-block in all calls to Panels. You include the text-buffer and attribute-buffer parameters in the CALL statement only if you are writing to, reading from, or scrolling a panel.

Parent topic: Using Panels
Related information
Panels Parameter Block


Text and Attributes for a Panel

Panels associates one attribute-encoding byte with each text character. When a panel is displayed on the screen, each text character is displayed with attributes encoded in the corresponding attribute-encoding byte.

There are three types of encoding:

  • Standard PC monochrome attribute encoding. This is the default encoding for Panels for systems with a monochrome display.
  • Standard PC color attribute encoding. This is the default encoding for Panels for systems with a color display.
  • User selected or generic attribute encoding for all types of display.

You can determine the type of encoding used by Panels by calling a suitable run-time system library routine. See Display Attribute Routines.

ACCEPT and DISPLAY statements use Adis to support terminal I/O and when used with Panels, Adis and Panels must use the same attribute encoding. This is automatically provided.

  • To Specify Text for a Panel
  • To Specify Attributes for a Panel
  • To Specify Attributes Without Specifying Text
Parent topic: Panels
Related information
Using Adis Functions with Panels


To Specify Text for a Panel

Use one of the three methods below:

  • Define text-buffer in the Working-Storage Section of your program and call Panels using text-buffer as a parameter. This method can be used to fill an area with different characters.
  • Specify a value for PPB-Fill-Character in the parameter block. This method can be used to fill an area with the same character.
  • Using the ACCEPT and DISPLAY statements for formatted screen I/O within a panel.
Parent topic: Text and Attributes for a Panel
Related information
Using Adis Functions with Panels
Calling Panels
PPB-Fill-Character


To Specify Attributes for a Panel

Use one of the three methods below:

  • Define attribute-buffer in the Working-Storage Section of your program and call Panels using attribute-buffer as a parameter. This method can be used to fill an area with different attributes.
  • Specify a value for PPB-Fill-Attribute in the parameter block. This is used to fill an area with the same attribute.
  • Using the ACCEPT and DISPLAY statements for formatted screen I/O that specifies attributes or colors for a panel.
Parent topic: Text and Attributes for a Panel
Related information
Using Adis Functions with Panels
Calling Panels
PPB-Fill-Attribute


To Specify Attributes Without Specifying Text

When you specify text-buffer, it must always be the second parameter in the call. attribute-buffer must be the third parameter in the call. Therefore, if you want to specify attributes without specifying text, you must set up a dummy parameter as the second parameter in the call. The dummy parameter can be any variable. The syntax to specify a dummy parameter is as follows:

call "PANELS" using panels-parameter-block
                    dummy
                    attribute-buffer
Parent topic: Text and Attributes for a Panel
Related information
Using Adis Functions with Panels
Calling Panels


Clipping a Panel

When a panel is created or the window is moved or resized using PF-Shift-Panel, the size of the window specified is validated by Panels and is reduced in size if a window of the specified size cannot be created. This is known as clipping the height and/or width of the window.

The window can be reduced in size for two reasons. The following examples describe how the width of the window is affected. The height is affected in a similar way, but depending on the values of PPB-Panel-Start-Row and PPB-First-Visible-Row instead of PPB-Panel-Start-Column and PPB-First-Visible-Col:

  1. PPB-Panel-Start-Column is too large. If the value of the start column is such that a window of the specified size would be off the right-hand edge of the screen, the width of the window is reduced to fit on the screen.

    For example, for a screen that is 80 characters wide, a window is defined that is 40 characters wide (PPB-Visible-Width = 40). If the window starts with the 60th character of the screen (PPB-Panel-Start-Column = 60) the screen would have to be 100 characters wide for the entire window to fit on the screen. Because the screen is only 80 characters wide, PPB-Visible-Width is clipped by 20 characters (PPB-Visible-Width is reduced to 20).

  2. PPB-First-Visible-Col is too large. If the value of the start column within the panel is such that a window of the specified size would be off the right-hand edge of the panel, the width of the window is reduced so that it is completely in the panel.
  3. For example, if a panel has been created with a width of 40 (PPB-Panel-Width = 40), and a window width of 30 (PPB-Visible-Width = 30) and a start position in the panel of 15 is specified, (PPB-First-Visible-Col = 15), Panels automatically reduces the width of the window to 25 (PPB-Panel-Width is reduced to 25).

The width or height of a window can be reduced to 0, in which case the window disappears from the display. It does, however, retain its order in the stack of panels on the screen (unlike the results of making a call to PF-Disable-Panel).

A panel is moved to the right by increasing the value in PPB-Panel-Start-Column. As the right-hand edge of the screen is reached, Panels starts to clip the width so that the panel appears to disappear off the right-hand edge of the screen.

A panel is moved to the left by decreasing the value in PPB-Panel-Start-Column. When this reaches 0, the left-hand edge of the screen has been reached. To give the impression of the panel disappearing off the left-hand edge of the screen, the value of PPB-First-Visible-Col is increased. The width of the window is reduced by Panels as a result and the panel appears to slide off the edge of the screen.

Parent topic: Panels
Related information
PF-Shift-Panel (Value 4)
PF-Disable-Panel (Value 8)
PPB-Panel-Start-Row
PPB-First-Visible-Row
PPB-Panel-Start-Column
PPB-First-Visible-Col
PPB-Visible-Width
PPB-Panel-Width


Panels Parameter Block

The Panels parameter block is made up of fields that you initialize to execute a particular function within Panels. You must make sure that you define all fields relevant to a function before calling Panels. For your convenience, the parameter block is in the copyfile panlink.cpy, provided with Visual COBOL, and you can use the COPY statement to include it in your program.

  • Panels Parameter Block Listing
  • Panels Parameter Block Fields
Parent topic: Panels


Panels Parameter Block Listing

The Panels parameter block, as defined in panlink.cpy, is shown below for reference.

01 Panels-Parameter-Block.
    03 PPB-Function               PIC 9(2) COMP-X.
    03 PPB-Status                 PIC 9(2) COMP-X.
    03 PPB-Panel-ID               PIC 9(4) COMP-X.
    03 PPB-Panel-Width            PIC 9(4) COMP-X.
    03 PPB-Panel-Height           PIC 9(4) COMP-X.
    03 PPB-Visible-Width          PIC 9(4) COMP-X.
    03 PPB-Visible-Height         PIC 9(4) COMP-X.
    03 PPB-First-Visible-Co       PIC 9(4) COMP-X.
    03 PPB-First-Visible-Row      PIC 9(4) COMP-X.
    03 PPB-Panel-Start-Column     PIC 9(4) COMP-X.
    03 PPB-Panel-Start-Row        PIC 9(4) COMP-X.
    03 PPB-Buffer-Offset          PIC 9(4) COMP-X.
    03 PPB-Vertical-Stride        PIC 9(4) COMP-X.
    03 PPB-Update-Group.
        05 PPB-Update-Coun        PIC 9(4) COMP-X.
        05 PPB-Rectangle-Offset   PIC 9(4) COMP-X.
        05 PPB-Update-Start-Col   PIC 9(4) COMP-X.
        05 PPB-Update-Start-Row   PIC 9(4) COMP-X.
        05 PPB-Update-Width       PIC 9(4) COMP-X.
        05 PPB-Update-Height      PIC 9(4) COMP-X.
    03 PPB-Fill.
        05 PPB-Fill-Character     PIC X.
        05 PPB-Fill-Attribute     PIC X.
    03 PPB-Update-Mask            PIC X.
    03 PPB-Scroll-Direction       PIC 9(2) COMP-X.
    03 PPB-Scroll-Count           PIC 9(4) COMP-X.

The fields relevant to a particular function are explained in the description of that function.

Parent topic: Panels Parameter Block
Related information
Panels Parameter Block Fields


Panels Parameter Block Fields

The following fields are available in the Panels parameter block:

  • PPB-Buffer-Offset
  • PPB-Fill-Attribute
  • PPB-Fill-Character
  • PPB-First-Visible-Col
  • PPB-First-Visible-Row
  • PPB-Function
  • PPB-Panel-Height
  • PPB-Panel-ID
  • PPB-Panel-Start-Column
  • PPB-Panel-Start-Row
  • PPB-Panel-Width
  • PPB-Rectangle-Offset
  • PPB-Scroll-Count
  • PPB-Scroll-Direction
  • PPB-Status
  • PPB-Update-Count
  • PPB-Update-Height
  • PPB-Update-Mask
  • PPB-Update-Start-Col
  • PPB-Update-Start-Row
  • PPB-Update-Width
  • PPB-Vertical-Stride
  • PPB-Visible-Height
  • PPB-Visible-Width
Parent topic: Panels Parameter Block


PPB-Buffer-Offset

The value you specify for PPB-Buffer-Offset determines the position of the first character to be found in the text buffer and/or the first attribute to be found in the attribute buffer. A value of one indicates the first byte in the buffer.
Parent topic: Panels Parameter Block Fields


PPB-Fill-Attribute

You use the PPB-Fill-Attribute to define the attribute of the backdrop character for the screen or the attribute you specify to fill a designated area of a panel. The default (initial) value for the backdrop attribute is x"07" on an IBM-PC; that is, white text on a black background.

Parent topic: Panels Parameter Block Fields


PPB-Fill-Character

You use PPB-Fill-Character to define either the backdrop character for the screen or a single character to fill a designated area of a panel. The default backdrop character is space if you do not explicitly define it.

Parent topic: Panels Parameter Block Fields


PPB-First-Visible-Col

The value you specify for PPB-First-Visible-Col determines the position of the window relative to the left edge of the panel. If you set PPB-First-Visible-Col to 0, the left edge of the window is aligned with the left edge of the panel.

Parent topic: Panels Parameter Block Fields


PPB-First-Visible-Row

The value you specify for PPB-First-Visible-Row determines the position of the window relative to the top of the panel. If you set PPB-First-Visible-Row to 0, the top of the window is aligned with the top of the panel.

Parent topic: Panels Parameter Block Fields


PPB-Function

The function you want Panels to perform must be specified for every call. You enter the value of the function, or its mnemonic, in this field.

Parent topic: Panels Parameter Block Fields
Related information
Panels Functions


PPB-Panel-Height

Panel height is defined in rows. You specify the height of a panel, in characters, in PPB-Panel-Height. The height of a panel multiplied by its width cannot exceed 65535 characters. If it does, Panels returns error code 6, PE-Panel-Too-Large.

Once you have created a panel, you cannot adjust its height.

Parent topic: Panels Parameter Block Fields
Related information
PE-Panel-Too-Large (Value 6)


PPB-Panel-ID

When you create a panel, Panels returns an identifying handle in PPB-Panel-ID. Each panel you create is given a unique handle. When working with a specific panel, PPB-Panel-ID must contain the handle that was returned when that panel was created. Failure to specify the correct handle is a common cause of problems when using Panels.

You should not assume that Panels allocates any particular identifier to a particular panel. Neither should you assume that the same identifier is used for two different executions of the same program. Always use the identifier returned by Panels when the panel was created.

Parent topic: Panels Parameter Block Fields


PPB-Panel-Start-Column

The value you specify for PPB-Panel-Start-Column determines the left edge of the visible window on the screen. If you set PPB-Panel-Start-Column to 0, the visible window is aligned with the first column on the screen.

Parent topic: Panels Parameter Block Fields


PPB-Panel-Start-Row

The value you specify for PPB-Panel-Start-Row determines the top of the visible window on the screen. If you set PPB-Panel-Start-Row to 0, the visible window is aligned with the first row on the screen.

Parent topic: Panels Parameter Block Fields


PPB-Panel-Width

Panel width is defined in columns. You specify the width of a panel, in characters, in PPB-Panel-Width. The width of a panel cannot exceed 2000 characters.

Once you have created a panel, you cannot adjust its width.

Parent topic: Panels Parameter Block Fields


PPB-Rectangle-Offset

This field specifies how many characters not to update within the rectangle. The value you specify for PPB-Rectangle-Offset is the position within the specified rectangle (defined by PPB-Update-Width and PPB-Update-Height) at which you wish to start updating the panel. If you intend to update the entire rectangle, you should set the PPB-Rectangle-Offset field to 0.

You can choose to update an irregular-shaped area of a rectangle by specifying values for both the PPB-Update-Count and PPB-Rectangle-Offset fields.

If you want to update the unshaded part of the panel you have to use PPB-Update-Count and PPB-Rectangle-Offset to specify how many characters are to be updated, and where the updating is to start:

  1. 406 characters of the panel are to be updated (6 characters on the fifth line and 20 full lines, each line being 20 characters wide) by moving 406 to PPB-Update-Count.
  2. Updating starts on the fifth line of the rectangle, beginning with the fifteenth character, so you need to skip the first 94 characters of the rectangle (four lines of 20 characters each, plus 14 characters of the fifth line). Start updating by moving 94 to PPB-Rectangle-Offset.
Parent topic: Panels Parameter Block Fields
Related information
PPB-Update-Width
PPB-Update-Height
PPB-Update-Count


PPB-Scroll-Count

You use PPB-Scroll-Count to specify the number of rows or columns you want to scroll. If you scroll up or down (PPB-Scroll-Direction is set to 0 or 1), PPB-Scroll-Count specifies the number of rows to be scrolled. If you scroll to the left or right (PPB-Scroll-Direction is set to 2 or 3), PPB-Scroll-Count specifies the number of columns to be scrolled.

Parent topic: Panels Parameter Block Fields
Related information
PPB-Scroll-Direction


PPB-Scroll-Direction

You use PPB-Scroll-Direction to specify the direction in which the text and attributes in a panel are to be scrolled. The values associated with the scroll direction are:

Value | Direction
0 | Up
1 | Down
2 | Left
3 | Right
Parent topic: Panels Parameter Block Fields


PPB-Status

After every call, Panels returns a status value in PPB-Status to indicate the success, or otherwise, of the call. The function was successfully executed if PPB-Status contains 0. If Panels returns a value greater than 0, an error occurred while Panels was trying to execute the function.

We recommend you test the status field after every call to Panels.

Parent topic: Panels Parameter Block Fields
Related information
Panels Error Codes


PPB-Update-Count

This field specifies the number of characters to be updated within a specified rectangle. You can choose to update an irregular-shaped area of a rectangle by specifying values for both the PPB-Update-Count and PPB-Rectangle-Offset fields.

If you update an entire rectangle, you set this field to the resulting value of PPB-Update-Width multiplied by PPB-Update-Height.

Parent topic: Panels Parameter Block Fields
Related information
PPB-Rectangle-Offset
PPB-Update-Width
PPB-Update-Height


PPB-Update-Height

This field defines the size, in characters, of the rectangle to update. You specify a value in this field to determine the number of rows that are affected when you update a panel. If the height of the update area is greater than the height of the panel, the area is reduced to the height of the panel.

Parent topic: Panels Parameter Block Fields


PPB-Update-Mask

You use PPB-Update-Mask field to specify:

  • Whether the screen is to be automatically updated.
  • Whether text, attributes or both are to be updated.
  • The location of the data to fill the specified area.

The update mask is a single byte value (PIC X). The individual bits of this byte are defined for PF-Flush-Panel, PF-Scroll-Panel, PF-Write-Panel and PF-Read-Panel as shown below:

Bit | Meaning When Set
7 | Unused. Reserved for future use and must be set to 0.
6 | Unused. Reserved for future use and must be set to 0.
5 | Any update to the attributes in a panel is to show on the screen immediately (provided the panel is enabled). If this bit is not set, the update does not show on the screen until the next call to PF-Flush-Panel is made.
4 | Any update to the text in a panel is to show on the screen immediately (provided the panel is enabled). If this bit is not set, the update does not show on the screen till the next call to PF-Flush-Panel is made.
3 | The attributes in the specified area of a panel are to be replaced by the attribute specified in PPB-Fill-Attribute in Panels-Parameter-Block. This bit is mutually exclusive with bit 1; setting bits 3 and 1 causes unpredictable results.
2 | The text in the specified area of a panel is to be replaced by the character specified in the PPB-Fill-Character in Panels-Parameter-Block. This bit is mutually exclusive with bit 0; setting bits 2 and 0 causes unpredictable results.
1 | The attributes in the specified area are to be replaced by the attributes provided in the attribute buffer. When used, this buffer must always be specified as the third parameter in the call to Panels. This bit is mutually exclusive with bit 3; setting bits 1 and 3 causes unpredictable results.
0 | The text in the specified area is to be replaced by the text provided in the text buffer. When used, this buffer must always be specified as the second parameter in the call to Panels. This bit is mutually exclusive with bit 2. Setting bits 0 and 2 causes unpredictable results.
Note:
  • Bits are ordered with bit 7 as the most significant, or first, and bit 0 as the least significant, or last.
  • PF-Read-Panel uses only bits 0 and 1.
Parent topic: Panels Parameter Block Fields
Related information
PF-Flush-Panel (Value 9)
PF-Write-Panel (Value 11)
PF-Read-Panel (Value 12)
PF-Scroll-Panel (Value 10)
PPB-Fill-Character
PPB-Fill-Attribute


PPB-Update-Start-Col

This field defines the position of the rectangle within the panel. It defines the first column of the rectangle that is affected when you update the panel. If you specify 0 for PPB-Update-Start-Col, the first column to be updated is the leftmost column of the panel.

Parent topic: Panels Parameter Block Fields


PPB-Update-Start-Row

This field defines the position of the rectangle within the panel. It defines the first row of the rectangle that is affected when you update the panel. If you specify 0 for PPB-Update-Start-Row, the first row to be updated is the top row of the panel.

Parent topic: Panels Parameter Block Fields


PPB-Update-Width

This field defines the size, in characters, of the rectangle to update. The number defined in this field is the number of columns that are affected when you update a panel. If the width of the update area is wider than the width of the panel, the area is reduced to the width of the panel.

Parent topic: Panels Parameter Block Fields


PPB-Vertical-Stride

The value you specify for PPB-Vertical-Stride determines the distance, in characters, between the start of one row and the start of the next row in the text and/or attribute buffers. You must make sure that the buffers contain enough data to fill the specified area as Panels assumes that enough data has been supplied.

Parent topic: Panels Parameter Block Fields


PPB-Visible-Height

You specify the height of a visible window, in rows, in PPB-Visible-Height. This sets the number of rows that are initially visible on the screen when you enable the panel. The height of the window cannot be greater than either the height of the panel or the screen.

Parent topic: Panels Parameter Block Fields


PPB-Visible-Width

You specify the width of a visible window, in columns, in PPB-Visible-Width. This sets the number of columns that are initially visible on screen when you enable a panel.

The width of a window cannot be wider than either the width of the panel or the screen.

Parent topic: Panels Parameter Block Fields


Panels Functions

You can execute a number of functions when using Panels. The functions are:

  • PF-Create-Panel (Value 3)
    Creates a panel.
  • PF-Create-Panel-With-Shadow (Value 19)
    Creates a panel with a shadow effect.
  • PF-Delete-Panel (Value 6)
    Deletes a panel from the system.
  • PF-Disable-Panel (Value 8)
    Disables a panel, making it invisible.
  • PF-Enable-Panel (Value 7)
    Enables a panel, making it visible on the screen.
  • PF-Flush-Panel (Value 9)
    Updates the screen with changes to the specified panel that have not yet been applied.
  • PF-Get-First-Panel (Value 15)
    Returns the identifying handle and information about the panel that was enabled most recently.
  • PF-Get-Next-Panel (Value 16)
    Returns the identifying handle and information about the panel that would be the topmost panel if the currently topmost panel were deleted.
  • PF-Get-Panel-At-Position (Value 13)
    Determines if there is a panel at a particular position.
  • PF-Get-Panel-Info (Value 5)
    Finds out the size and position of an existing panel.
  • PF-Get-Panel-Stack (Value 17)
    Returns a list of the identifying handles of all enabled panels.
  • PF-Get-Screen-Info (Value 0)
    Returns information about the size of the current screen.
  • PF-Read-Panel (Value 12)
    Reads text and attributes from a panel into buffers supplied by your calling program.
  • PF-Redraw-Screen (Value 2)
    Refreshes the contents of the entire screen.
  • PF-Scroll-Panel (Value 10)
    Scrolls a rectangular area of a panel.
  • PF-Set-Panel-Name (Value 14)
    Associates a name with the specified panel.
  • PF-Set-Panel-Stack (Value 18)
    Resets the stack of enabled panels then redraws the screen.
  • PF-Set-Screen-Backdrop (Value 1)
    Changes the current backdrop character and attribute.
  • PF-Shift-Panel (Value 4)
    Moves a window and/or changes its size.
  • PF-Write-Panel (Value 11)
    Writes to a panel.
Parent topic: Panels


PF-Create-Panel (Value 3)

Creates a panel.

Parameters:

The panel's window is created disabled; that is, it is not visible.

PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

PPB-First-Visible-Col | Positions the window horizontally within the panel. A value of 0 indicates that the left-hand edge of the window is positioned on the left-hand edge of the panel.
PPB-First-Visible-Row | Positions the window vertically within the panel. A value of 0 indicates that the top of the window is positioned on the top edge of the panel.
PPB-Panel-Height | The number of rows of text in the panel to be created.
PPB-Panel-Start-Column | Positions the panel horizontally on the screen. A value of 0 indicates that the left-hand edge of the panel is positioned on the left-hand edge of the screen.
PPB-Panel-Start-Row | Positions the panel vertically on the screen. A value of 0 indicates that the top of the panel is positioned on the top edge of the screen.
PPB-Panel-Width | The number of columns of text in the panel to be created.
PPB-Visible-Height | The number of rows of text in the visible window.
PPB-Visible-Width | The number of columns of text in the visible window.

On Exit:

PPB-Panel-ID The identifying handle of the created panel. You should copy this value into a data item in the Working-Storage Section of your program and specify it when using any functions that act on this panel.

Comments:

Panels allocates an area of memory for the new panel based on its size. The number of bytes of memory used by a panel is determined as follows:

2 * PPB-Panel-Height * PPB-Panel-Width

The size of the new panel can be larger than the screen, but you must observe the following:

  • PPB-Panel-Width must not be greater than 2000.
  • PPB-Panel-Height * PPB-Panel-Width must not be greater than 65535.

Failure to observe either of these limits results in Panels error code 6 being returned.

Once you create a panel, you can change any of its variables except its width and height, using PF-Shift-Panel. The newly created panel is filled with the current backdrop character and attribute.

Example:

This example creates a panel that is 20 characters wide by 15 lines high. This panel starts on line 4, column 1 of the screen. The window into this panel starts on the first line and first column of the panel. This window is 20 characters wide by 10 rows deep.

* Panel size is 20 characters wide by 15 lines
       move 20 to ppb-panel-width.
       move 15 to ppb-panel-height.
* The window starts on screen line 4, col 1. Remember that
* PPB-Panel-Start-Column and PPB-Panel-Start-Row specify a
* screen position, where 0,0 is the top left corner of the
* screen.
       move 3 to ppb-panel-start-row.
       move 0 to ppb-panel-start-column.
* The window into the panel is 20 char wide by 10 lines.
       move 20 to ppb-visible-width.
       move 10 to ppb-visible-height.
* The window starts on the first line and column of the panel.
* Remember that 0,0 is the top left corner of the panel.
       move 0 to ppb-first-visible-row.
       move 0 to ppb-first-visible-col.
* Create the panel. It is initially disabled (invisible).
       move pf-create-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*         (code to abort)
            ...
* Save the panel identifier.
       move ppb-panel-id to ws-save-panel-id.
Parent topic: Panels Functions


PF-Create-Panel-With-Shadow (Value 19)

Creates a panel with a shadow effect.

Parameters:

The panel's window is created disabled; that is, it is not visible.

PPB-Fill-Attribute | pic x.
PPB-Fill-Character | pic x.
PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Update-Mask | pic x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

PPB-Fill-Attribute | The attribute to be used for the shadow.
PPB-Fill-Character | The character to be used as the shadow.
PPB-First-Visible-Col | Positions the window horizontally within the panel. A value of 0 indicates that the left-hand edge of the window is positioned on the left-hand edge of the panel.
PPB-First-Visible-Row | Positions the window vertically within the panel. A value of 0 indicates that the top of the window is positioned on the top edge of the panel.
PPB-Panel-Height | The number of rows of text in the panel to be created.
PPB-Panel-Start-Column | Positions the panel horizontally on the screen. A value of 0 indicates that the left-hand edge of the panel is positioned on the left-hand edge of the screen.
PPB-Panel-Start-Row | Positions the panel vertically on the screen. A value of 0 indicates that the top of the panel is positioned on the top edge of the screen.
PPB-Panel-Width | The number of columns of text in the panel to be created.
PPB-Update-Mask | The width of the shadow to be used. Zero indicates a width of one character, otherwise the shadow is two characters wide.
PPB-Visible-Height | The number of rows of text in the visible window.
PPB-Visible-Width | The number of columns of text in the visible window.

On Exit:

PPB-Panel-ID The identifying handle of the created panel. You should copy this value into a data item in the Working-Storage Section of your program and specify it when using any functions that act on this panel.

Comments:

Panels allocates an area of memory for the new panel based on its size. The number of bytes of memory used by a shadowed panel is determined as follows:

4 * PPB-Panel-Height * PPB-Panel-Width

The size of the new panel can be larger than the screen, but you must observe the following:

  • PPB-Panel-Width must not be greater than 2000.
  • PPB-Panel-Height * PPB-Panel-Width must not be greater than 65535.

Failure to observe either of these limits results in Panels error code 6 being returned.

Once you create a panel with a shadow, you can change any of its variables except its width, height, and shadow details. You do this using PF-Shift-Panel. The newly created panel is filled with the current backdrop character and attribute. The shadowing effect on a shadowed panel is not transparent.

Example:

This example creates a panel that is 25 characters wide by 8 lines high. This panel starts on line 1, column 1 of the screen. The window into this panel starts on the first line and first column of the panel. This window is 25 characters wide by 6 rows deep.

The shadowing on the panel is one character wide, and is seen as a gray band.

* Panel size is 20 characters wide by 15 lines
       move 25 to ppb-panel-width.
       move  8 to ppb-panel-height.
* The window starts on screen line 1, col 1. Remember that
* PPB-Panel-Start-Column and PPB-Panel-Start-Row specify a
* screen position, where 0,0 is the top left corner of the
* screen.
       move 0 to ppb-panel-start-row.
       move 0 to ppb-panel-start-column.
* The window into the panel is 20 char wide by 10 lines.
       move 25 to ppb-visible-width.
       move  6 to ppb-visible-height.
* The window starts on the first line and column of the panel
* Remember that 0,0 is the top left corner of the panel.
       move 0 to ppb-first-visible-row.
       move 0 to ppb-first-visible-col.
* Specify the shadowing for the panel
       move 0 to ppb-update-mask
       move space to ppb-fill-character
       move gray  to ppb-fill-attribute
* Create the panel. It is initially disabled (invisible).
       move pf-create-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*         (code to abort)
            ...
* Save the panel identifier.
       move ppb-panel-id to ws-save-panel-id.
Parent topic: Panels Functions


PF-Delete-Panel (Value 6)

Deletes a panel from the system.

Parameters:

PPB-Panel-ID pic 9(4) comp-x.

On Entry:

PPB-Panel-ID The handle of the panel to be deleted.

On Exit:

None

Comments:

When you delete a panel, both the panel identifier and the storage area that had been allocated to the panel becomes available for reuse. Any attempt to access the panel after it has been deleted returns a Panels error code 1, indicating that the attempt was unsuccessful.

If you delete a panel that was enabled, it disappears from the screen.

Example:

This example deletes the panel whose identifier has been saved in the variable ws-save-panel-id.

       move ws-save-panel-id to ppb-panel-id.
       move pf-delete-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Disable-Panel (Value 8)

Disables a panel, making it invisible.

Parameters:

PPB-Panel-ID pic 9(4) comp-x.

On Entry:

PPB-Panel-ID The identifying handle of the panel to disable.

On Exit:

None

Comments:

Any windows that were overlaid by the disabled panel are now uncovered. You can still work with the panel you disable, even though it is no longer visible on the screen. To see the results of changes you make to a disabled panel, you simply re-enable it.

Example:

This example disables the panel whose identifier is saved in variable ws-save-panel-id.

       move ws-save-panel-id to ppb-panel-id.
       move pf-disable-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Enable-Panel (Value 7)

Enables a panel, making it visible on the screen.

Parameters:

PPB-Panel-ID pic 9(4) comp-x.

On Entry:

PPB-Panel-ID The identifying handle of the panel to enable.

On Exit:

None

Comments:

You can create, move, change, or write to a panel before enabling it. However, you must enable the panel before you can see the results of these operations.

When you enable a panel, you are actually displaying the window associated with that panel. The window appears in the position defined when you created the panel, unless you recently changed or moved it.

If the enabled panel shares the same screen area as a visible panel that was previously created, the newly enabled panel overlays the previously created one.

If you have multiple panels in the program, they are stacked in the order in which you enabled them. The most recently enabled panel overlays all others on the screen.

You can move, change, read from and write to a panel even if it is partially or fully overlaid by another.

Example:

This example enables the panel whose identifier is saved in data item ws-save-panel-id.

       move ws-save-panel-id to ppb-panel-id.
       move  pf-enable-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Flush-Panel (Value 9)

Updates the screen with changes to the specified panel that have not yet been applied because bit 4 or 5 in PPB-Update-Mask was off during previous calls to Panels.

Parameters:

PPB-Panel-ID | pic 9(4) comp-x.
PPB-Update-Height | pic 9(4) comp-x.
PPB-Update-Mask | pic x.
PPB-Update-Start-Col | pic 9(4) comp-x.
PPB-Update-Start-Row | pic 9(4) comp-x.
PPB-Update-Width | pic 9(4) comp-x.

On Entry:

PPB-Panel-ID | The identifying handle of the panel to flush.
PPB-Update-Height | The height of the rectangle to update.
PPB-Update-Mask | See the section Panels Parameter Block.
PPB-Update-Start-Col | The first column of the rectangle that is to be updated.
PPB-Update-Start-Row | The first row of the rectangle that is to be updated.
PPB-Update-Width | The width of the rectangle to update.

On Exit:

None

Comments:

PF-Flush-Panel has no effect if you specify a panel that is not enabled.

Example:

This example assumes a panel has been defined that is 30 characters wide and 17 rows deep. The screen display of the original panel is updated, starting with the second line, column 1, through the 16th line of the panel. The handle of the original panel is assumed to be saved in data item ws-save-panel-id.

* Define the size of the rectangle to flush
       move 30 to ppb-update-width.
       move 15 to ppb-update-height.
* Now define where in the panel the rectangle starts (0,0
* defines the top left-hand corner of the panel). The update
* panel starts on line 2, column 1 of the panel.
       move 1 to ppb-update-start-row.
       move 0 to ppb-update-start-col.
* Set bits 4 and 5 of the Update Mask on to apply updates for
* both text and attributes. Hex 30 is binary 00110000.
       move X"30" to ppb-update-mask.
* When the panel was created, it was saved with the panel
* identifier in a variable ws-save-panel-id.
       move ws-save-panel-id to ppb-panel-id.
* Apply the updates
       move pf-flush-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*         (code to abort)
Parent topic: Panels Functions


PF-Get-First-Panel (Value 15)

Returns the identifying handle and information about the panel that was enabled most recently.

Parameters:

Panel-Name-Buffer. Group item containing:
Panel-Name-Length    pic 99 comp-x.
Panel-Name-Text      pic x(30).
PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

None

On Exit:

Panel-Name-Length | The length of the name associated with the panel.
Panel-Name-Text | The name associated with the panel by a call to function PF-Set-Panel-Name.
PPB-First-Visible-Col | The horizontal position of the visible window on the panel.
PPB-First-Visible-Row | The vertical position of the visible window on the panel.
PPB-Panel-Height | The height of the panel.
PPB-Panel-ID | The identifying handle of the panel that was enabled most recently.
PPB-Panel-Start-Column | The horizontal position of the panel on the screen.
PPB-Panel-Start-Row | The vertical position of the panel on the screen.
PPB-Panel-Width | The width of the panel.
PPB-Visible-Height | The height of the visible window in the panel.
PPB-Visible-Width | The width of the visible window in the panel.

Comments:

On exit from this function, the most significant bit of Panel-Name-Length is a flag that indicates whether or not the panel is currently enabled - zero indicates that the panel is not enabled, while a non-zero value shows that it is enabled. To check whether this is the case, you should check whether Panel-Name-Length > 127.

If there are no panels when you call PF-Get-First-Panel, PPB-Status contains the value Error-Invalid-ID.

Example:

This example assumes that you have defined Panel-Name-Buffer in the Working-Storage Section of your program as specified above.

       move pf-set-panel-name to ppb-function.
       call "PANELS" using panels-parameter-block
                              panel-name-buffer.
*
* code to check if the panel is enabled.
*       if ppb-status not = zero
*         (code to abort)
Parent topic: Panels Functions


PF-Get-Next-Panel (Value 16)

Returns the identifying handle and information about the panel that would be the topmost panel if the currently topmost panel were deleted.

Parameters:

Panel-Name-Buffer. Group item containing:
Panel-Name-Length     pic 99 comp-x.
Panel-Name-Text       pic x(30).
PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

None

On Exit:

Panel-Name-Length | The length of the name associated with the panel.
Panel-Name-Text | The name associated with the panel by a call to function PF-Set-Panel-Name.
PPB-First-Visible-Col | The horizontal position of the visible window on the panel.
PPB-First-Visible-Row | The vertical position of the visible window on the panel.
PPB-Panel-Height | The height of the panel.
PPB-Panel-ID | The identifying handle of the panel that was enabled most recently.
PPB-Panel-Start-Column | The horizontal position of the panel on the screen.
PPB-Panel-Start-Row | The vertical position of the panel on the screen.
PPB-Panel-Width | The width of the panel.
PPB-Visible-Height | The height of the visible window in the panel.
PPB-Visible-Width | The width of the visible window in the panel.

Comments:

On exit from this function, the most significant bit of Panel-Name-Length is a flag that indicates whether or not the panel is enabled - zero indicates that the panel is not enabled, while a non-zero value shows that it is enabled. To check whether this is the case, you should check whether Panel-Name-Length > 127.

The only Panels calls that you can use immediately before PF-Get-Next-Panel are PF-Get-First-Panel and other PF-Get-Next-Panel. That is, there must be no other Panels calls between two successive calls to PF-Get-Next-Panel, or between a call to PF-Get-First-Panel and one to PF-Get-Next-Panel.

If there is no next panel when you call PF-Get-Next-Panel, PPB-Status contains the value Error-Invalid-ID.

Example:

This example returns the details of all panels that Panels is aware of. The example assumes that you have declared a table in the Working-Storage Section of your program to hold the information, and a data item panel-num to use as a subscript.

*
* Get details of the first panel
*
       move 1 to panel-num
       move pf-get-first-panel to ppb-function
       perform make-panels-call
       if ppb-status not = error-invalid-id
*      (code to abort)
       perform move-values-to-working-storage
       add 1 to panel-num
*
* Get details of all other panels, until ppb-status is
* returned as error-invalid-id.
*
       move pf-get-next-panel to ppb-function
       call "PANELS" using panels-parameter-block
                              panel-name-buffer
       perform until ppb-status = error-invalid-id
       perform move-values-to-working-storage
       add 1 to panel-num
       perform make-panels-call
       end-perform
         ...
 move-values-to-working-storage section.
*
* Move all the exit parameters to the Working-Storage section
* to retain their values.
*
       move ppb-panel-id       to ws-panel-id (panel-num)
       move ppb-panel-height   to ws-panel-height (panel-num)
       move ppb-panel-width    to ws-panel-width (panel-num)
       move ppb-visible-height
                        to ws-visible-height (panel-num)
       move ppb-visible-width
                        to ws-visible-width (panel-num)
       move ppb-panel-start-column
                        to ws-panel-start-column (panel-num)
       move ppb-panel-start-row
                        to ws-panel-start-row (panel-num)
       move ppb-first-visible-col
                        to ws-first-visible-col (panel-num)
       move ppb-first-visible-row
                        to ws-first-visible-row (panel-mum)
       move panel-name-buffer
                        to ws-panel-name-buffer (panel-num)
       move panel-name-length
                        to ws-panel-name-length (panel-num)
       move panel-name-text
                        to ws-panel-name-text (panel-num)
       .
 make-panels-call section.
       call "PANELS" using panels-parameter-block
                           panel-name-buffer
Parent topic: Panels Functions


PF-Get-Panel-At-Position (Value 13)

Determines if there is a panel at a particular position. If there is, details of the panel's appearance are also returned.

Parameters:

PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

PPB-Panel-Start-Column | The x-coordinate to check for the existence of a panel.
PPB-Panel-Start-Row | The y-coordinate to check for the existence of a panel.

On Exit:

PPB-First-Visible-Col | The x-coordinate of the visible window, relative to the panel. The column of the panel is column 0.
PPB-First-Visible-Row | The y-coordinate of the visible window, relative to the panel. The first row of the panel is row 0.
PPB-Panel-Height | The height of the panel found at the specified location.
PPB-Panel-ID | The identifying handle of the panel found at the specified location. If there is no enabled panel, a value of 0 is returned. If more than one panel exists at the specified location, the handle of the panel most recently enabled is returned.
PPB-Panel-Start-Column | The x-coordinate of the left edge of the panel on the screen. The first column on the screen is column 0.
PPB-Panel-Start-Row | The y-coordinate of the top edge of the panel on the screen. The first row on the screen is row 0.
PPB-Panel-Width | The width of the panel found at the specified location.
PPB-Visible-Height | The height of the visible window on the panel.
PPB-Visible-Width | The width of the visible window on the panel.

Comments:

Use PF-Get-Panel-Info if you know the handle of a panel but want to return information about its appearance.

Example:

This example identifies which panel is at line 4, column 6 (where 0,0 is the top left-hand corner of the screen).

     move 3 to ppb-panel-start-row.
     move 5 to ppb-panel-start-column.
     move pf-get-panel-at-position to ppb-function.
     call "PANELS" using panels-parameter-block.
     if ppb-status not = zero
*        (code to abort)
Parent topic: Panels Functions


PF-Get-Panel-Info (Value 5)

Finds out the size and position of an existing panel.

Parameters:

PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

PPB-Panel-ID The handle of the panel whose information you want returned. This value is returned from a call to PF-Create-Panel.

On Exit:

PPB-First-Visible-Col | The horizontal position of the visible window on the specified panel.
PPB-First-Visible-Row | The vertical position of the visible window on the specified panel.
PPB-Panel-Height | The height of the specified panel.
PPB-Panel-Start-Column | The horizontal position of the specified panel on the screen.
PPB-Panel-Start-Row | The vertical position of the specified panel on the screen.
PPB-Panel-Width | The width of the specified panel.
PPB-Visible-Height | The height of the visible window in the specified panel.
PPB-Visible-Width | The width of the visible window in the specified panel.

Example:

This example returns information about the panel whose panel identifier is saved in the variable ws-save-panel-id.

       move ws-save-panel-id to ppb-panel-id.
       move pf-get-panel-info to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
   *          (code to abort)
Parent topic: Panels Functions


PF-Get-Panel-Stack (Value 17)

Returns a list of the identifying handles of all enabled panels.

Parameters:

Panels-Order-List | A group item containing:
POL-Count | pic 9(4) comp-x.
POL-ID | pic 9(4) comp-x occurs 254.

On Entry:

None

On Exit:

POL-Count | The number of enabled panels in the list.
POL-ID | The list of identifying handles.

Comments:

The first item returned in the list (POL-ID(1)) holds the most recently enabled panel, and so on.

Example:

This example returns a list of the identifying handles of all enabled panels. The example assumes that you have declared Panels-Order-List in the Working-Storage Section of your program as described above.

       move pf-get-panel-stack to ppb-function.
       call "PANELS" using panels-parameter-block.
       panels-order-list.
Parent topic: Panels Functions


PF-Get-Screen-Info (Value 0)

Returns information about the size of the current screen.

Parameters:

PPB-Fill-Attribute | pic 9(4) comp-x.
PPB-Fill-Character | pic 9(4) comp-x.
PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-Height | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Panel-Width | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

None

On Exit:

PPB-Fill-Attribute | The current backdrop attribute.
PPB-Fill-Character | The current backdrop character.
PPB-First-Visible-Col | 0
PPB-First-Visible-Row | 0
PPB-Panel-Height | The number of rows visible on the screen.
PPB-Panel-Start-Column | 0
PPB-Panel-Start-Row | 0
PPB-Panel-Width | The number of columns on the screen.
PPB-Visible-Height | The number of rows visible on the screen.
PPB-Visible-Width | The number of columns on screen.

Comments:

You can change the backdrop character and attribute using PF-Set-Screen-Backdrop.

Example:

       move pf-get-screen-info to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*         (code to abort)
Parent topic: Panels Functions


PF-Read-Panel (Value 12)

Reads text and attributes from a panel into buffers supplied by your calling program.

Parameters:

attribute-buffer | pic x(n).
PPB-Buffer-Offset | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Rectangle-Offset | pic 9(4) comp-x.
PPB-Update-Count | pic 9(4) comp-x.
PPB-Update-Height | pic 9(4) comp-x.
PPB-Update-Mask | pic x.
PPB-Update-Start-Col | pic 9(4) comp-x.
PPB-Update-Start-Row | pic 9(4) comp-x.
PPB-Update-Width | pic 9(4) comp-x.
PPB-Vertical-Stride | pic 9(4) comp-x.
text-buffer | pic x(n).

On Entry:

attribute-buffer | If bit 1 of PPB-Update-Mask is set, specifies the buffer to hold the attributes read from the panel.
PPB-Buffer-Offset | Where the first character read from the update rectangle is placed in the text buffer.
PPB-Panel-ID | The identifying handle of the panel to read from.
PPB-Rectangle-Offset | The number of characters not to read from the update rectangle.
PPB-Update-Count | The number of characters to read from the update rectangle.
PPB-Update-Height | The height of the update rectangle to read from.
PPB-Update-Mask | If bit 0 is set, the text read from the panel is to be included in a text buffer. If bit 1 is set, the attributes read from the panel are to be included in an attribute buffer.
PPB-Update-Start-Col | The first column of the specified panel to read from.
PPB-Update-Start-Row | The first row of the specified panel to read from.
PPB-Update-Width | The width of the update rectangle to read from.
PPB-Vertical-Stride | The width of a line in the text buffer.
text-buffer | If bit 0 of PPB-Update-Mask is set, specifies the buffer to hold the text read from the panel.

On Exit:

None

Comments:

PF-Read-Panel does not behave like an ACCEPT statement; that is, it does not allow the user to input information to a panel. If you want to obtain information from the user, you must use an ACCEPT statement.

You must make sure that the buffers are large enough to accommodate the data that Panels places into them. If they are not large enough, Panels could overwrite information following the buffers in the Working-Storage Section of your program.

Example:

This example assumes a panel has been defined that is 10 characters wide and 30 rows deep. The handle for this panel is saved in ws-save-panel-id.

This example reads a portion of this panel, starting from the first column of the 7th line, to the end of the panel. Text only (not attributes) is read into a buffer called text-buffer which is assumed to be defined in the Working-Storage Section of the program.

* Define an update rectangle to read from. In this case,
* define the rectangle from line 7 through line 30 of the
* panel. This is a total of 24 lines and each line is 10
* characters wide.
       move 10 to ppb-update-width.
       move 24 to ppb-update-height.

* Start reading beginning with the 7th line and first column
* of the panel. (0,0 is the top left-hand corner of the
* panel.)
       move 6 to ppb-update-start-row.
       move 0 to ppb-update-start col.

* Within the rectangle, read beginning with the first
* character (where 0 is the top left-hand corner of the
* rectangle).
       move 0 to ppb-rectangle-offset.
* Read 240 characters into the buffers (24 lines times 10
* characters per line).
       move 240 to ppb-update-count.
* Read updates beginning with the first character of the
* buffer.
       move 1 to ppb-buffer-offset.
* One row of the update rectangle is 10 characters wide.
       move 10 to ppb-vertical-stride.
* Read text only, not attributes (set bit 0 of
* PPB-Update-Mask).
       move x"01" to ppb-update-mask.
* The panel identifier was saved in ws-save-panel-id.
       move ws-save-panel-id to ppb-panel-id.
* Read text from the panel into text-buffer, defined
* as PIC X(240).
       move pf-read-panel to ppb-function.
       call "PANELS" using panels-parameter-block
       text-buffer.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Redraw-Screen (Value 2)

Refreshes the contents of the entire screen.

Parameters:

None

Comments:

Any panels currently visible on the screen are refreshed in the order in which they previously appeared. Portions of the screen not hidden by enabled panels display the current backdrop character and attribute.

On the first call to this function, the screen is cleared and the entire screen is set to the current backdrop character and attribute.

This function is particularly useful if a screen becomes corrupted by another program that uses a method of screen updating other than Panels. This call resets the screen to a state recognized by Panels.

Example:

       move pf-redraw-screen to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Scroll-Panel (Value 10)

Scrolls a rectangular area of a panel.

A rectangle is a specific area within a panel. You can scroll this identified area either up or down by row, or left or right by column.

You must specify certain data items depending on the bit settings in PPB-Update-Mask:

Bit | Data Items Needed
0 | text-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride.
1 | attribute-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride.
2 | PPB-Fill-Character.
3 | PPB-Fill-Attribute.

Parameters:

attribute-buffer | pic x(n).
PPB-Buffer-Offset | pic 9(4) comp-x.
PPB-Fill-Attribute | pic x.
PPB-Fill-Character | pic x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Scroll-Count | pic 9(4) comp-x.
PPB-Scroll-Direction | pic 9(2) comp-x.
PPB-Update-Height | pic 9(4) comp-x.
PPB-Update-Mask | pic x.
PPB-Update-Start-Col | pic 9(4) comp-x.
PPB-Update-Start-Row | pic 9(4) comp-x.
PPB-Update-Width | pic 9(4) comp-x.
PPB-Vertical-Stride | pic 9(4) comp-x.
text-buffer | pic x(n).

On Entry:

Bit | Data Items Needed
attribute-buffer | If bit 1 of PPB-Update-Mask is set, specifies the attribute buffer to fill the rectangle from.
PPB-Buffer-Offset | If bit 0 of PPB-Update-Mask is set, specifies the position of the first character to display from the text-buffer. If bit 1 of PPB-Update-Mask is set, specifies the position of the first attribute to display from attribute-buffer.
PPB-Fill-Attribute | If bit 3 of PPB-Update-Mask is set, specifies the attribute that is to be used to fill the rectangle.
PPB-Fill-Character | If bit 2 of PPB-Update-Mask is set, specifies the character that is to be used to fill the rectangle.
PPB-Panel-ID | The identifying handle of the panel to be scrolled. This value is returned from a call to PF-Create-Panel.
PPB-Scroll-Count | The number of lines to scroll.
PPB-Scroll-Direction The direction of the scrolling:
0
Up
1
Down
2
Left
3
Right
PPB-Update-Height | The height of the rectangle to scroll.
PPB-Update-Mask | See the section Panels Parameter Block.
PPB-Update-Start-Col | The first column of the rectangle to be affected by the scrolling.
PPB-Update-Start-Row | The first row of the rectangle to be affected by the scrolling.
PPB-Update-Width | The width of the rectangle to scroll.
PPB-Vertical-Stride | If bit 0 or 1 of PPB-Update-Mask is set, specifies the length of a line in text-buffer or attribute-buffer.
text-buffer | If bit 0 of PPB-Update-Mask is set, specifies the text buffer to fill the rectangle from.

On Exit:

None

Comments:

Panels does not allow you to scroll text and attributes separately.

Example:

A panel has been defined that is 50 characters wide and 15 rows deep. The handle for this panel is saved in the data item ws-save-panel-id.

This example scrolls the text and attributes in the panel up 15 rows and replaces the vacated text with text and attributes from text and attribute buffers. The first 15 lines of the text and attribute buffers are already used (displayed on the screen). Therefore, scrolling starts with the 16th line of the text and attribute buffer (one line in the text and attribute buffers is 50 characters wide).

* Define an update rectangle; that is a block of the panel
* to scroll. In this case, define the entire panel as the
* rectangle.
       move 50 to ppb-update-width.
       move 15 to ppb-update-height.
* Since the update rectangle is the same size as the panel,
* begin scrolling with line 1, column 1 of the panel (where
* 0,0 is the top left-hand corner of the panel).
       move 0 to ppb-update-start-row.
       move 0 to ppb-update-start-col.
* The rectangle scrolls up.
       move 0 to ppb-scroll-direction
* Scroll up 15 lines.
       move 15 to ppb-scroll-count.
* The panel is filled with text and attributes from user
* specified buffers. The first 15 lines (each line in the
* buffer is 50 characters wide) are already displayed. Start
* updating with the 16th line of the buffers.
* PPB-Buffer-Offset specifies what character of the buffers
* to begin with (where 1 is the first character). Therefore,
* start with the 751st character (15 rows times 50
* characters per row equals 750 characters already on the
* screen).
       move 751 to ppb-buffer-offset.
* One row of the update rectangle is 50 characters wide.
       move 50 to ppb-vertical-stride.
* Update the vacated portions of the panel using text and
* attribute buffers (set bits 0 and 1 of PPB-Update-Mask)
* and changes are seen on the screen as the rectangle
* scrolls in the enabled panel(set bits 4 and 5 of
* PPB-Update-Mask). x"33" is binary 00110011.
       move x"33" to ppb-update-mask.
* The panel ID was saved in ws-save-panel-id.
       move ws-save-panel-id to ppb-panel-id.
* Scroll the panel. The text buffer is text-buffer and the
* attribute buffer is attribute-buffer.
       move pf-scroll-panel to ppb-function.
       call "PANELS" using panels-parameter-block
       text-buffer
       attribute-buffer
       if ppb-status not = zero
*         (code to abort)
Parent topic: Panels Functions


PF-Set-Panel-Name (Value 14)

Associates a name with the specified panel.

Parameters:

PPB-Panel-ID | pic 9(4) comp-x.
Panel-Name-Buffer. | Group item containing:
  • Panel-Name-Length
  • Panel-Name-Text
  • pic 99 comp-x.
  • pic x(30).

On Entry:

PPB-Panel-ID | The identifying handle of the panel with which you want to associate a name.
Panel-Name-Length | The length of the name.
Panel-Name-Text | The name to associate with the panel specified in PPB-Panel-ID.

On Exit:

None.

Comments:

Once you have used this function, you can see the name associated with each panel by using the PF-Get-First-Panel and PF-Get-Next-Panel functions.

Example:

This example assumes that you have just created a panel, and that you have defined Panel-Name-Buffer in the Working-Storage Section of your program as specified above.

       move 11 to panel-name-length.
       move "Dummy Panel" to panel-name-text.
       move pf-set-panel-name to ppb-function.
       call "PANELS" using panels-parameteer-block
                               panel-name-buffer.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Set-Panel-Stack (Value 18)

Resets the stack of enabled panels according to the specified list of enabled panels, then redraws the screen.

Parameters:

Panels-Order-List | A group item containing:
POL-Count | pic 9(4) comp-x.
POL-ID | pic 9(4) comp-x occurs 254.

On Entry:

POL-Count | The number of enabled panels in the list.
POL-ID | The list of identifying handles of the enabled panels that are to be redrawn.

On Exit:

None

Comments:

Any panel not specifed in POL-ID is disabled, while any panel that is specified in POL-ID is enabled and displayed.

Example:

The following example shows how you could use the PF-Get-Panel-Stack and PF-Set-Panel-Stack functions together to save the state of an application's panels, before changing the panels, then restoring the panels to their original state.

The example shows extracts of a main program that calls a subprogram, where the state of the main program's panels is saved prior to calling the subprogram and restored on return. The subprogram requires only one panel to be displayed, a company logo, which is displayed by the main program.

 working-storage section.
 01 panels-order-list.
     03  pol-count          pic 9(4) comp-x.
     03  pol-id             pic 9(4) comp-x occurs 254.
 01 save-panels-order-list  pic x(510).
 01 company-logo-panel-id   pic 9(4) comp-x.
  ...
 procedure division.
      ...
 call-subprogram section.
      ...
* Before calling the subprogram, get a copy of the current
* stack of panels.
     move pf-get-panel-stack to ppb-function
     perform make-panels-call
* Now save this copy of the stack.
     move panels-order-list to save-panel-order-list
* Next, remove all of the main program's panels from the
* display, except for the panel showing the company logo.
     move 1 to pol-count
     move company-logo-panel-id to pol-id(1)
     move pf-set-panel-stack to ppb-function
     perform make-panels-call
* The Stack is now empty, except for the company logo, so
* call the subprogram.
     call "SUBPROG"
* On return from the subprogram, restore the program's
* panels to their state prior to the subprogram call.
     move pf-set-panel-stack to ppb-function
     perform make-panels-call
      ...
 make-panels-call section.
     call "PANELS" using panels-parameter-block
     panels-order-list
Parent topic: Panels Functions


PF-Set-Screen-Backdrop (Value 1)

Changes the current backdrop character and attribute.

Parameters:

PPB-Fill-Attribute | pic x.
PPB-Fill-Character | pic x.

On Entry:

PPB-Fill-Attribute | The new backdrop attribute to use.
PPB-Fill-Character | The new backdrop character to use.

On Exit:

None

Comments:

This function does not automatically update the screen; it merely defines the backdrop character and attribute to Panels. You must redraw the screen using PF-Redraw-Screen before the changed backdrop character and attribute are displayed.

Example:

This example makes the backdrop character an asterisk. The backdrop attribute is set to a red foreground on a blue background.

     move "*" to ppb-fill-character.
     move x"14" to ppb-fill-attribute.
     move pf-set-screen-backdrop to ppb-function.
     call "PANELS" using panels-parameter-block.
     if ppb-status not = zero
*        (code to abort)
Parent topic: Panels Functions


PF-Shift-Panel (Value 4)

Moves a window and/or changes its size.

Parameters:

PPB-First-Visible-Col | pic 9(4) comp-x.
PPB-First-Visible-Row | pic 9(4) comp-x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Panel-Start-Column | pic 9(4) comp-x.
PPB-Panel-Start-Row | pic 9(4) comp-x.
PPB-Visible-Height | pic 9(4) comp-x.
PPB-Visible-Width | pic 9(4) comp-x.

On Entry:

PPB-First-Visible-Col | The new horizontal position of the window within the panel. A value of 0 indicates that the left-hand edge of the window is positioned on the left-hand edge of the panel.
PPB-First-Visible-Row | The new vertical position of the window within the panel. A value of 0 indicates that the top edge of the window is positioned on the top edge of the panel.
PPB-Panel-ID | The identifying handle of the panel whose appearance you want to change. This value is returned from a call to PF-Create-Panel.
PPB-Panel-Start-Column | The new horizontal position of the panel on the screen. A value of 0 indicates that the top edge of the panel is positioned on the left-hand edge of the screen.
PPB-Panel-Start-Row | The new vertical position of the panel on the screen. A value of 0 indicates that the top edge of the panel is positioned on the top edge of the screen.
PPB-Visible-Height | The new number of rows of text in the visible window.
PPB-Visible-Width | The new number of columns of text in the visible window.

On Exit:

None

Comments:

All of the fields except PPB-Panel-Height and PPB-Panel-Width can be changed using this function - once you have defined the size of a panel it cannot be changed. If you specify any values for PPB-Panel-Height and PPB-Panel-Width they are ignored.

If you do not want to change the values already assigned to the window, you can use PF-Get-Panel-Info to learn the current size and position of the window and set these again.

Any changes you make to the size or position of a window are visible only if you have enabled the panel associated with the window. However, you can change the window while the panel is disabled. The changes are displayed the next time you use PF-Enable-Panel to enable the panel.

Example:

This example assumes a panel has been defined that is 80 characters wide and 20 rows deep. The panel starts on line 1, column 1 of the screen. The window into the panel is currently 80 columns wide and 5 rows deep and starts in the first position (top left-hand corner) of the panel. The handle of this panel was saved in the data item ws-save-panel-id

This example makes more of the panel visible by increasing the visible portion of the window from 5 rows to 10 rows. All other parameters remain the same.

* Window starts in screen line 1, column 1. Remember that
* when the location of the window on the screen is defined,
* it is relative to 0 (that is line 0, row 0 is the top
* left hand corner of the screen).
       move 0 to ppb-panel-start-column.
       move 0 to ppb-panel-start-row.
* The window into the panel is 20 columns wide by 10 rows
* deep.
       move 20 to ppb-visible-width.
       move 10 to ppb-visible-height.
* The window starts at line 1, col 1 of the screen (where
* 0,0 is the top left-hand corner of the screen).
       move 0 to ppb-first-visible-col.
       move 0 to ppb-first-visible-row.
* When the panel was first created, the returned panel ID
* was saved in a Working-Storage variable ws-save-panel-id.
* Now Panels needs to know which panel the call applies to.
       move ws-save-panel-id to ppb-panel-id.
* Move the window.
       move pf-shift-panel to ppb-function.
       call "PANELS" using panels-parameter-block.
       if ppb-status not = zero
*          (code to abort)
Parent topic: Panels Functions


PF-Write-Panel (Value 11)

Writes to a panel.

Text and attributes you write to the panel are visible on the screen if you use bits 4 and 5 in PPB-Update-Mask and the panel is enabled.

You must specify certain data items depending on the bit settings in PPB-Update-Mask:

Bit | Data Items Needed
0 | text-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride.
1 | attribute-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride.
2 | PPB-Fill-Character.
3 | PPB-Fill-Attribute.

Parameters:

attribute-buffer | pic x(n).
PPB-Buffer-Offset | pic 9(4) comp-x.
PPB-Fill-Attribute | pic x.
PPB-Fill-Character | pic x.
PPB-Panel-ID | pic 9(4) comp-x.
PPB-Update-Height | pic 9(4) comp-x.
PPB-Update-Mask | pic x.
PPB-Update-Start-Col | pic 9(4) comp-x.
PPB-Update-Start-Row | pic 9(4) comp-x.
PPB-Update-Width | pic 9(4) comp-x.
PPB-Vertical-Stride | pic 9(4) comp-x
text-buffer | pic x(n).

On Entry:

attribute-buffer | If bit 1 of PPB-Update-Mask is set, specifies the attribute buffer to fill the rectangle from.
PPB-Buffer-Offset | If bit 0 of PPB-Update-Mask is set, specifies the position of the first character to display from the text-buffer. If bit 1 of PPB-Update-Mask is set, specifies the position of the first attribute to display from attribute-buffer.
PPB-Fill-Attribute | If bit 3 of PPB-Update-Mask is set, specifies the attribute that is to be used to fill the rectangle.
PPB-Fill-Character | If bit 2 of PPB-Update-Mask is set, specifies the character that is to be used to fill the rectangle.
PPB-Panel-ID | The identifying handle of the panel to write to.
PPB-Update-Height | The height of the update rectangle.
PPB-Update-Mask | See the section Panels Parameter Block.
PPB-Update-Start-Col | The first column of the rectangle to be affected by the write.
PPB-Update-Start-Row | The first row of the rectangle to be affected by the write.
PPB-Update-Width | The width of the update rectangle.
PPB-Vertical-Stride | If bit 0 or 1 of PPB-Update-Mask is set, specifies the length of a line in text-buffer or attribute-buffer.
text-buffer | If bit 0 of PPB-Update-Mask is set, specifies the text buffer to fill the rectangle from.

Example:

This example assumes a panel has been defined that is 50 characters wide and 15 rows deep. The handle for this panel is saved in the data item ws-save-panel-id.

This example writes the first 15 rows from the text and attribute buffers to the panel.

* Define an update rectangle (that is a block of the panel
* to update). In this case, define the entire panel as the
* rectangle.
     move 50 to ppb-update-width
     move 15 to ppb-update-height
* Since the "update rectangle" is the same size
* as the panel, the update window has no offset within the
* panel.
     move 0 to ppb-update-start-row
     move 0 to ppb-update-start-col
* Write using text and attribute buffers starting with the
* first character of the buffers.
     move 1 to ppb-buffer-offset
* One row of the update window is 50 characters wide.
     move 50 to ppb-vertical-stride
* Start writing beginning with the first character of the
* update window (where 0 is the top left-hand corner of the
* window).
     move 0 to ppb-rectangle-offset
* Write 750 characters (15 rows times 50 characters per row)
* to the panel.
     move 750 to ppb-update-count
* Use text and attribute buffers (set bits 0 and 1 of
* PPB-Update-Mask) and have the text immediately visible on
* the screen if the panel is enabled (set bits 4 and 5 of
* PPB-Update-Mask). x"33" is binary 00110011.
     move x"33" to ppb-update-mask
* The panel identifier was saved in ws-save-panel-id.
     move ws-save-panel-id to ppb-panel-id
* Write to the panel. The text buffer is text-buffer and the
* attribute buffer is attribute-buffer.
     move pf-write-panel to ppb-function
     call "PANELS" using panels-parameter-block
     ws-text-buffer
     ws-attribute-buffer.
     if ppb-status not = zero
*        (code to abort)
Parent topic: Panels Functions


Using Adis Functions with Panels

The Enhanced ACCEPT/DISPLAY syntax (Adis) enables you to use ACCEPT and DISPLAY statements in a program that includes Panels. It is worth considering that:

  • Only enhanced ACCEPT and DISPLAY statements can be directed to a panel. You could encounter problems if you use standard ANSI ACCEPT and DISPLAY statements to write directly to the screen. The same is true if you use the x"B7" COBOL system library routine or the call-by-name screen handling routines with Panels.
  • The positions specified in AT, LINE and COLUMN clauses are relative to the top left corner of the current panel and not to the screen.
  • You can create any number of panels, and can have up to 254 enabled at one time. Six of these are used by Adis when Adis is used with Panels.
  • Calling Adis Functions
  • Adis Functions
Parent topic: Panels


Calling Adis Functions

The syntax for using these Adis functions is:

Syntax:

call x"AF" using  function-code
                  parameter

Parameters:

function-code | A pic x comp-x value field which contains the number of the function to be executed.
parameter | Varies according to the function. See the description of the individual function for information about the setting of parameter.
Note:
  • All Adis calls must have a second parameter even though its contents are sometimes ignored.
  • If an error occurs while executing this call, parameter returns a value of 255.
Parent topic: Using Adis Functions with Panels
Related information
Adis Functions


Adis Functions

The following Adis functions are available for use with Panels:

  • x"AF" Function 1 - Disable or Enable Adis Indicators
  • x"AF" Function 49 - Initialize Adis to Use Panels
  • x"AF" Function 56 - Specify Panel for ACCEPT/DISPLAY
  • x"AF" Function 57 - Enable or Disable Delayed DISPLAY
  • x"AF" Function 62 - Suspend Use of Panels by Adis
  • x"AF" Function 63 - Return Status of Panels Used by Adis
Parent topic: Using Adis Functions with Panels


x"AF" Function 1 - Disable or Enable Adis Indicators

Enables or disables Adis indicators or error messages.

When you use x"AF" function 49 to tell Adis that you are using Adis and Panels together, the function creates six predefined panels for you. Four of the panels are used to display Adis indicators (Insert, Replace, Auto-skip, and Off-end-of-field indicators). Another field is used for displaying Adis error messages. You might want to suppress these messages when you are using Panels.

Syntax:

call x"AF" using   indicators-fn
                   parameter

Parameters:

indicators-fn pic x comp-x value 1. If an error occurs in the execution of this function, function-code is set to 255 on exit.
parameter A pic x(4) field containing one of the following values:
  • x"01322C01" To disable the error message panel.
  • x"03323803" To disable the indicator panels.
  • x"01322C02" To enable the error message panel.
  • x"03323800" To enable the indicator panels.
Parent topic: Adis Functions
Related information
x"AF" Function 49 - Initialize Adis to Use Panels


x"AF" Function 49 - Initialize Adis to Use Panels

Initializes Adis for use with Panels.

The x"AF" function 49 creates a panel with the same dimensions as your screen. This panel is automatically enabled and is space filled with white on black attributes. The screen is cleared.

You execute this call only once at the beginning of your program.

Syntax:

call x"AF" using   init-panels-fn
                   parameter

Parameters:

init-panels-fn | pic x comp-x value 49.
parameter | Any alphanumeric data item. Adis ignores its size and contents.

Example:

 01 init-panels-fn    pic x comp-x value 49.
 01 parameter         pic x.
            ...
     call x"af" using init-panels-fn
                      parameter

The panel created by this call is automatically enabled, clearing the previous contents from the screen. It contains spaces as the default backdrop character. The default attribute setting is white on a black background. All ACCEPT and DISPLAY statements are directed to this panel unless another panel is specified. See the function Specify Panel for ACCEPT/DISPLAY for information on how to do this. The panel identifier (Panel-ID) value of the panel created by this call is always 0.

This call creates six panels for use by Adis. All but the first of the following list are on the bottom line of your screen.

  • A full screen panel.
  • An Adis error message panel, in columns 1 through 77.
  • A one-character panel for the Insert indicator.
  • A one-character panel for the Off-end-of-field indicator.
  • A one-character panel for the Auto-skip indicator.
  • A one-character panel for the Replace indicator.

These six panels cannot be used by your program.

Parent topic: Adis Functions


x"AF" Function 56 - Specify Panel for ACCEPT/DISPLAY

Specifies the panel to which you direct all subsequent ACCEPT and DISPLAY statements in your program. All ACCEPT and DISPLAY statements are directed to this specified panel until you make another call to this function.

Syntax:

call x"AF" using   specify-panel-fn
                   work-panel-ID

Parameters:

specify-panel-fn | pic x comp-x value 56.
work-panel-ID | A PIC XX COMP-X field containing the identifying handle of the panel to be used for the ACCEPT and DISPLAY statements. If you use the panel created by Adis as a result of a call to x"AF" function 49, the panel identifier is 0.

Comments:

Your program must create a panel before you can execute this call, unless you want to work with the default panel created by Adis.

If the specified panel does not exist, the value 255 is returned in specify-panel-function, and the previously specified panel is used for the ACCEPT and DISPLAY statements.

If you direct an ACCEPT statement to a panel, the panel is enabled automatically so that the visible portion is not obscured by another panel. If the panels window is smaller than the panel, and the cursor position resulting from the ACCEPT is not currently visible, Adis positions the window so that the text at the cursor becomes visible. A DISPLAY statement directed to a panel is the same as the PF-Write-Panel when you update both text and attributes.

Example:

 01 specify-panel-fn    pic x comp-x value 56.
 01 work-panel-id       pic xx comp-x.
            ...
*   (Code to create panel and move its identifier into
*      work-panel-id)
            ...
     call x"af" using specify-panel-fn
                      work-panel-id.
Parent topic: Adis Functions
Related information
x"AF" Function 49 - Initialize Adis to Use Panels
PF-Write-Panel (Value 11)


x"AF" Function 57 - Enable or Disable Delayed DISPLAY

Updates the screen with several DISPLAY statements using only one call.

The x"AF" function 57 allows you to execute several DISPLAY statements without updating the screen each time one is executed. You then execute only one call to update the screen with all of them, often resulting in a faster updating process.

Screen updates are delayed until you either execute an ACCEPT statement or use this call to update the screen and re-enable screen updating (see below).

Syntax:

call x"AF" using   control-update-fn
                   control-update-param

Parameters:

control-update-fn pic x comp-x value 57.
control-update-param pic x comp-x value field containing one of the following values:
  • 1 - use the delayed update method
  • 0 - disable the delayed update method, causing the screen to be immediately updated

Comments:

The result of executing an ACCEPT statement is the same as executing this call with parameter set to 0. Therefore, after you execute an ACCEPT statement, you must execute another call to this function with parameter set to 1 if you still want to use the delayed update method.

Example:

 01 control-update-fn       pic x comp-x value 57.
 01 control-update-param    pic x comp-x.
   ...
     move 1 to control-update-param.
     call x"af" using control-update-fn
                      control-update-param.
            ...
* Any DISPLAY statements here are not reflected on the screen
      ...
     move 0 to control-update-param.
     call x"af" using control-update-fn
                           control-update-param.
* Now all the previous displayed information is visible.
Parent topic: Adis Functions


x"AF" Function 62 - Suspend Use of Panels by Adis

Suspends the use of Panels by Adis.

The x"AF" function 62 allows you to suspend the use of Panels by Adis, in order to allow direct screen writes where Panels is not required.

You must have previously initialized Adis to use Panels using x"AF" function 49.

Syntax:

call x"AF" using  suspend-function
                  suspend-parameter

Parameters:

suspend-function pic x comp-x value 62.
suspend-parameter A pic x comp-x value field containing one of the following values:
  • 0 - suspend the use of Panels
  • 1 - re-enable the use of Panels

Comments:

If Adis has not been initialized to work with Panels, the value 255 is returned in suspend-function.

Example:

 01 suspend-function     pic x comp-x value 62.
 01 suspend-parameter    pic x comp-x.
 ...
*   (Code to set up Adis to use Panels)
            ...
* Suspend Panels working
     move 0 TO suspend-parameter.
     call x"af" using suspend-function
                      suspend-parameter.
            ...
* Reactivate Panels working
     move 1 TO suspend-parameter.
     call x"af" using suspend-function
                      suspend-parameter.
Parent topic: Adis Functions
Related information
x"AF" Function 49 - Initialize Adis to Use Panels


x"AF" Function 63 - Return Status of Panels Used by Adis

Returns the status of Panels' use by Adis.

The x"AF" function 63 allows you to obtain details of how Adis is using Panels for ACCEPT and DISPLAY statements.

Syntax:

call x"AF" using  get-status-fn
                  get-status-param

Parameters:

get-status-fn pic x comp-x value 63.
get-status-param A group item with the following definition:
usage-flag
Defined as pic x comp-x value, specifying whether Adis has been initialized to use Panels. 0 indicates that Adis is not using Panels.
status-flag
Defined as pic x comp-x value, specifying whether Panels working is currently enabled on Adis.
current-id
Defined as pic xx comp-x, specifying the handle of the panel being used by Adis.

Example:

 01 get-status-fn         pic x comp-x value 63.
 01 get-status-param.
     03 panels-usage-flag     pic x comp-x.
     03 panels-status-flag    pic x comp-x.
     03 current-panel-id      pic xx comp-x.
  ...
     call x"af" using get-status-fn
                      get-status-param.
     if panels-usage-flag = 0
         display "Adis is not using Panels."
     else
         if panels-status = 0
             display "Use of Panels by Adis is suspended."
         else
             display "Use of Panels by Adis is active."
             display "The ID of the PANEL being used by "
                     "Aids is:"
                     current-panel-id
         end-if
     end-if.
Parent topic: Adis Functions


Panels Error Codes

The following list shows the values that can be returned in the status field PPB-Status by a call to Panels. The mnemonics are shown in the order in which they appear in panlink.cpy.

  • PE-No-Error (Value 0)
  • PE-Not-Created (Value 1)
  • PE-Invalid-ID (Value 2)
  • PE-Invalid-Parameters (Value 3)
  • PE-Invalid-Function (Value 4)
  • PE-No-Room-For-Panel (Value 5)
  • PE-Panel-Too-Large (Value 6)
  • PE-Invalid-Direction (Value 7)
  • PE-Invalid-Scroll-Count (Value 8)
  • PE-Cannot-Initialise (Value 9)
Parent topic: Panels


PE-No-Error (Value 0)

The function requested completed successfully.

Parent topic: Panels Error Codes


PE-Not-Created (Value 1)

The panel required does not exist. This value is returned if you attempt to perform a function on a panel that has not yet been created. You must create a panel before it can be used.

Parent topic: Panels Error Codes


PE-Invalid-ID (Value 2)

The panel identifier is outside the range of valid panel identifiers. The maximum number of panels that can be visible at one time is 254.

Parent topic: Panels Error Codes


PE-Invalid-Parameters (Value 3)

The update parameters supplied do not define an area that is inside the panel. The specified values of PPB-Update-Start-Row or PPB-Update-Start-Col are outside the panel; that is, they are greater than the height and/or width of the panel.

Parent topic: Panels Error Codes
Related information
PPB-Update-Start-Col
PPB-Update-Start-Row


PE-Invalid-Function (Value 4)

The function number specified in PPB-Function is not a valid function number.

Parent topic: Panels Error Codes
Related information
PPB-Function


PE-No-Room-For-Panel (Value 5)

The program is trying to create too many panels. The maximum number of panels have already been created. This error occurs on a call to PF-Create-Panel if the maximum number of panels (65534) has already been created.

Parent topic: Panels Error Codes
Related information
PF-Create-Panel (Value 3)


PE-Panel-Too-Large (Value 6)

The panel specified is too large. This value is returned if the program has specified a panel size that is too large. This will be due to one of the following reasons:

  1. The program is trying to create a panel that is too large, that is: PPB-Panel-Width *PPB-Panel-Height > 65535.
  2. The width of the panel is greater than 2000 characters.
  3. There is insufficient memory available to hold the panel text and attribute buffers.
Parent topic: Panels Error Codes
Related information
PPB-Panel-Width
PPB-Panel-Height


PE-Invalid-Direction (Value 7)

The value supplied in PPB-Scroll-Direction is not in the range 0 through 3.

Parent topic: Panels Error Codes
Related information
PPB-Scroll-Direction


PE-Invalid-Scroll-Count (Value 8)

You are trying to scroll too many rows or columns. The specified value of PPB-Scroll-Count is greater than the number of rows or columns in the panel (depending on the direction of scroll).

Parent topic: Panels Error Codes
Related information
PPB-Scroll-Count


PE-Cannot-Initialise (Value 9)

Panels cannot initialize. This is a fatal error which occurs only on the first call to Panels made by a program in your system. It means that for some reason, Panels cannot initialize.

Parent topic: Panels Error Codes


Frequently Used Terms in Panels

  • Adis
  • Attribute Buffer
  • Clipping
  • Disabled
  • Enabled
  • Panel
  • Parameter Block
  • Rectangle
  • Text Buffer
  • Window
Parent topic: Panels


Adis

The run-time module that executes extended ACCEPT/DISPLAY statements. The Adis module can be told to DISPLAY data in a panel rather than directly on the screen and to ACCEPT data from a panel.

Parent topic: Frequently Used Terms in Panels


Attribute Buffer

The attributes defined in the Working-Storage Section of your program which are then included in a panel.

Parent topic: Frequently Used Terms in Panels


Clipping

Reducing the window size if the specified size is larger than can be created. For example, if the value of the start column is such that a window of the specified size would be off the right-hand edge of the screen, the width of the window is automatically reduced to fit the screen.

Parent topic: Frequently Used Terms in Panels
Related information
Clipping a Panel


Disabled

A particular window is not visible on the screen.

Parent topic: Frequently Used Terms in Panels


Enabled

A particular window is visible on the screen.

Parent topic: Frequently Used Terms in Panels


Panel

A virtual screen that can be written to, but which can be larger or smaller than the real screen. Before a panel can be used, it must be created by supplying the height and width of the panel together with the dimensions and position of the visible portion on the screen and which part of the panel is actually visible.

Parent topic: Frequently Used Terms in Panels


Parameter Block

The means of communication between a program and Panels. The parameter block is made up of fields that you initialize to execute a particular function within Panels. All fields relevant to a function must be initialized before calling Panels.

Parent topic: Frequently Used Terms in Panels


Rectangle

A rectangular portion of a panel, which can be scrolled independently.

Parent topic: Frequently Used Terms in Panels


Text Buffer

Text defined in the Working-Storage Section of your program which is then included in a panel.

Parent topic: Frequently Used Terms in Panels


Window

The visible portion of a panel.

Parent topic: Frequently Used Terms in Panels


Run-time System Configuration

Restriction: The run-time switches and run-time tunables are supported for native COBOL only.

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, run-time tunables, and run-time switches.

You can specify some run-time features in a separate configuration file:

  • A separate configuration file - In a text editor, create or edit a separate text file. See the individual sections for the formats of the text files. Use the COBCONFIG environment variable to specify the location and name of the run-time configuration file for environment variables, tunables, and switches.
  • 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.
  • Run-time Tunables
Parent topic: General Reference
Related information
Overview of Linking Native COBOL Applications and Run-time Systems


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


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:

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

cobrun -2+5-7+7 ./myprog.int
Note: On UNIX platforms, you can only set switches on the command line when using the cobrun command, and so limits the use to .int, .gnt, or .so files.
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:

COBSW={ {+|-|/}switch }...
export COBSW

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 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.
  • 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.
  • T run-time switch
    Enables insertion of tab characters in all line sequential files.
  • Z run-time switch
    Enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file or input from the console.
  • 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 reference
Configuration Section
The Special-Names Paragraph
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 reference
The File Control Entry
Data Description Entry Skeleton
The USAGE Clause
Screen Section Entry Skeleton
The USAGE Clause in the Screen Section
The DISPLAY Statement
Related information
List of Run-time Switches for OO Programs
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 reference
CALLFH
The OPEN Statement
The SORT Statement
The USE Statement
XML Syntax - OPEN Statement
The File Control Entry
The READ Statement
XML Syntax - READ Statement
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:

cobrun[_t] +D myprog
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.
Restriction: These switches are supported for native COBOL only.

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


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" or "0D0A"is taken as the record terminator. This provides compatibility with Micro Focus COBOL behavior for Windows.

When on (+L2), x"0A" 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 on either Windows or UNIX systems, 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 reference
The WRITE Statement
XML Syntax - WRITE Statement
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".

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:

cobrun[_t] -N myprog

loads the program Myprog. 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 reference
INSERTNULL
EXPANDTAB
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


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 reference
Trailing Blanks in Line Sequential Files
EXPANDTAB
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


Z run-time switch

Enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file or input from the console.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

DBCS spaces such as x"8140" for Shift-JIS and x"A1A1" for EUC in Japanese environments are converted to ASCII spaces x"2020".

Parent topic: List of General Run-time Switches


List of Run-time Switches for OO Programs

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

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
  • List of Run-time Tunables
Parent topic: Run-time System Configuration


Run-time Configuration Tunables - Overview

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 and environment variables. Environment variables set in this way override values already set in the environment.

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, or if you are developing a COBOL JVM project and need to specify Java property files, the COBCONFIGJVM 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 , you set COBCONFIG as follows.

COBCONFIG=$HOME/myconf
export COBCONFIG

If you want to use a Java property file called myconf.properties for a JVM project, you set COBCONFIGJVM as follows.

COBCONFIGJVM=$HOME/myconf.properties
export COBCONFIGJVM

The use of a configuration file is optional - no error is issued if it does not exist.

Parent topic: Run-time Tunables


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


List of Run-time Tunables

Restriction: These tunables are supported for native COBOL only.
  • acu_library
    Loads 'aculibs', the ACUCOBOL-GT compatibility module.
  • 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_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 the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • current_hour
    Specifies the hour of the day that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_minute
    Specifies the minute of the hour that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_month
    Specifies the month of the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • current_second
    Specifes the second of the minute that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
  • current_year
    Specifies the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
  • 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.
  • dynamic_dictionary_limit
    Specifies the maximum size of memory to be allocated dynamically at run time for use by virtual heaps.
  • 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_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.
  • intra_process_record_locking
    Specifies whether the run-time system can share a file and set record locks against a file within a process.
  • 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_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.
  • putenv_interface
    On certain platforms, this provides backward compatibility with previous products in the setting of environment variables.
  • 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 run-time system is to use its own signal handlers.
  • stackdump_filename
    Specifies the name of the file that is generated when the stackdump_on_error tunable is set to TRUE.
  • stackdump_on_error
    When a program generates a run-time error, this tunable specifies whether a stackdump file is created. A stackdump file contains a list of the threads in the process at the time of the error, and a stack trace for each thread.
  • strict_file_locking
    Enables or disables the strict file locking mechanism for UNIX platforms.
  • 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_library

Loads 'aculibs', the ACUCOBOL-GT compatibility module.
Restriction: These tunables are supported for native COBOL only.

This tunable is set by the ACU compiler directive, and once set, cannot be un-set without recompiling your program without the ACU directive.

Syntax:

>>-------acu_library=--.-TRUE-.---------><
                       +-FALSE+

Aculibs provides certain functionality for ACUCOBOL-GT compatibility. It provides C$RERR, the library routine for obtaining extended error information from file operations, and a number of external variables (F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO, F-ERRMSG, RETURN-CODE, and A4GL-WHERE-CONSTRAINT) containing other error information.

Parameters:

TRUE | Aculibs functionality is enabled
FALSE | Aculibs functionality is not enabled

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

External variables can provide additional information in troubleshooting situations. For example, if a database returns an error that does not map to one of the standard COBOL errors (record locked, duplicate key, etc.), the external variables F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO and F-ERRMSG will contain extra information. Typically, F-ERRNO will be E_INTERNAL (which has a value of 15). F-INT-ERRNO and F-INT2-ERRNO will be the error values returned by the database, and F-ERRMSG will point to a text message returned by the database.

When acu_library is set, ensure you add the following external declarations to working-storage:

01 A4GL-WHERE-CONSTRAINT PIC X(300).
01 F-INT-ERRNO SIGNED-LONG.
01 F-INT2-ERRNO SIGNED-LONG.
01 F-LOG-ERRNO SIGNED-SHORT.
01 F-ERRMSG POINTER.
77 F-ERRNO SIGNED-SHORT.
01 RETURN-CODE SIGNED-LONG.
Note: Refer to the COBOL COPY file filesys.def for the error value definitions.
Parent topic: List of Run-time Tunables
Related reference
ACU
C$RERR
Related information
Run-time Configuration Tunables - Overview


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
Related information
Run-time Configuration Tunables - Overview


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 cobrun , argument 0 is the trigger name and argument 1 is the name of the main COBOL program. Set this tunable to TRUE for compatibility with Micro Focus Object COBOL Developer Suite V4.1 for UNIX and earlier.
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: |

Comments:

See the Language Reference for more details of the ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE syntax. For details on building applications, see Building COBOL applications if using the IDE, or Compiling and Linking from the Command Line if using the command line/shell prompt.

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:

cobrun 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 ( cobrun ) is returned as argument 0 and myapp as argument 1.

Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview
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
Related information
Run-time Configuration Tunables - Overview


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: | TRUE
IDE equivalent: | None

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
COMMAND-LINE-LINKAGE
Related information
Run-time Configuration Tunables - Overview


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: | core.pid in the current working directory, where pid is the process ID of the program that has encountered the error..
Setting: | None

Example:

set core_filename="/home/temp/core/core.%p@%t_%d"

Produces a file named core.12345@165920_20080115, on the path /home/temp/core.

Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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

Parameters:

0 | The run-time system never produces a core file on any signal 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 system signal is received that would normally produce a core file on the host system; for example, SIGBUS and SIGSEGV (which would usually produce a run-time system error 114). After writing out the core file the process terminates immediately. Warning: When this value is set, operating system security may prevent a core dump file from being created; refer to Preparing for a Core Dump for instructions on how to ensure that a core dump file is created.
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. Warning: When this value is set, operating system security may prevent a core dump file from being created; refer to Preparing for a Core Dump for instructions on how to ensure that a core dump file is created.
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.

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.

Restriction:
The core_on_error=3 functionality has the following restrictions on some operating systems:
  • On HP-UX, it is only supported on version 11.31 or later, where the gcore utility is supported.
  • On Linux, it is only supported if gdb (GNU debugger) is installed and the creation of valid 32-bit core dumps is supported.
  • On AIX, it is only supported when the "fullcore" kernel tunable is set. To enable "fullcore" support, run the following command as root: chdev -l sys0 -a fullcore='true'.
Parent topic: List of Run-time Tunables
Related reference
debug_on_error
signal_regime
Related information
Run-time Configuration Tunables - Overview


current_day

Specifies the day of the month required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 intrinsic function.

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
Related reference
current_hour
current_minute
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


current_hour

Specifies the hour of the day that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 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
Related reference
current_day
current_minute
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


current_minute

Specifies the minute of the hour that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 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
Related reference
current_day
current_hour
current_month
current_second
current_year
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


current_month

Specifies the month of the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 intrinsic function.
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
Related reference
current_day
current_hour
current_minute
current_second
current_year
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


current_second

Specifes the second of the minute that is to be returned when the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 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
Related reference
current_day
current_hour
current_minute
current_month
current_year
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


current_year

Specifies the year required to be returned when the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.
Restrictions:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.
  • This tunable is supported for native COBOL only.

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 intrinsic function.

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
Related reference
current_day
current_hour
current_minute
current_month
current_second
datewarp_dynamic
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


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.
Restriction: These tunables are supported for native COBOL only.

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 the ACCEPT identifier FROM DATE syntax or the CURRENT-DATE intrinsic function is used.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
current_day
current_hour
current_minute
current_month
current_second
current_year
timewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


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 Animator starts if a running program terminates with a run-time system error.

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related reference
core_on_error
signal_regime
Related information
Run-time Configuration Tunables - Overview


debugger_command

Specifies the command to start the debugger when just-in-time debugging is enabled
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set debugger_command=---debugger"-----------><

Parameters:

debugger This must be one of the commands listed in the chapter Debugging Methods in your Debugging Guide.

Properties:

Default: | cobanim
IDE equivalent: | None
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
Related information
Run-time Configuration Tunables - Overview


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
Related information
Run-time Configuration Tunables - Overview


dynamic_dictionary_limit

Specifies the maximum size of memory to be allocated dynamically at run time for use by virtual heaps.
Note: Restriction:

These tunables are supported for native COBOL only.

Syntax:

>>-----set dynamic_dictionary_limit=---integer------><

Parameters:

integer The maximum amount of memory (in bytes) to be allocated dynamically at run time for use by virtual heaps.

Properties:

Default: | 245760 bytes (240 K)
IDE equivalent: | None

Comments:

The Compiler uses virtual heaps when processing your programs, and this size is operating system dependent. If the memory limit is exceeded, the memory allocated to virtual heaps is paged by the COBOL system onto disk. If the amount of memory allocated to virtual heaps is not large enough to process your programs, then the compilation and generation times can be increased due to the overheads of paging the virtual heap accesses to disk.

This run-time tunable is equivalent to the -d run-time switch. The value of -d is used if the values are different.

Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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: | None
Parent topic: List of Run-time Tunables
Related reference
entry_point_mapper_alias_exists_error
entry_point_mapper_search_order
Related information
Entry Point Mapping for COBOL Programs
Run-time Configuration Tunables - Overview


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 198 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: | None

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
Related reference
entry_point_mapper
entry_point_mapper_search_order
Related information
Entry Point Mapping for COBOL Programs
Run-time Configuration Tunables - Overview


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
Related reference
entry_point_mapper
entry_point_mapper_alias_exists_error
Related information
Entry Point Mapping for COBOL Programs
Run-time Configuration Tunables - Overview


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: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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
Setting: | None

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
Related information
Run-time Configuration Tunables - Overview


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: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


intra_process_record_locking

Specifies whether the run-time system can share a file and set record locks against a file within a process.
Note: Restriction:

These tunables are supported for native COBOL only.

Syntax:

>>-----set intra_process_record_locking=---.-TRUE-.-------------><
                                           +-FALSE+

Parameters:

TRUE | Enables the run-time system to share a file and to set record locks against a file within a process; this occurs if a file is opened more than once in different programs, or if a file is opened in different threads. Closing a shared file only releases the record locks obtained by opening the file.
FALSE | The ability to share a file and to set record locks against a file within a process is not defined by this system but by the operating system itself.

Properties:

Default: | TRUE
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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-+
                        +-3-+

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.
3 | Provides compatibility with C-ISAM version 5 and above.

Properties:

Default: | 2
IDE equivalent: | None

Comments:

This tunable is only applicable if the File Handler configuration option FILEMAXSIZE is set to 4.

Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


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

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
Related information
Run-time Configuration Tunables - Overview


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
Run-time Configuration Tunables - Overview
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: | 0x40000000
IDE equivalent: | None

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

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
Run-time Configuration Tunables - Overview
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
Related information
Run-time Configuration Tunables - Overview


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
Related information
Run-time Configuration Tunables - Overview


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.
Default: | 0
IDE equivalent: | None

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
Related information
Run-time Configuration Tunables - Overview


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
Related information
Run-time Configuration Tunables - Overview


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

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
Related information
Run-time Configuration Tunables - Overview


printer_redirection

Redirects WRITE statements through the Windows print spooler.

The following details are for native COBOL only.

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

Comments:

You can also set printer redirection by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview
The File Control Entry


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=---.-0-.-----------><
                               +-1-+

Parameters:

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.

Properties:

Default: | 0
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related information
Introduction to Profiler
Run-time Configuration Tunables - Overview
Time Spent in Called Programs


putenv_interface

On certain platforms, this provides backward compatibility with previous products in the setting of environment variables.
Restriction:

This tunable is supported for native COBOL only.

Syntax:

>>-----set-putenv_interface=--.-TRUE--.--><
                             +-FALSE-+

Parameters:

TRUE | Provides backward compatibility by using the operating system's putenv() function when setting environment variables.
FALSE | Uses the operating system's setenv() function when setting environment variables.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

Only set this tunable on AIX, HP-UX and Solaris platforms, and then only if you are experiencing COBRT105 errors, or when processes are growing in size when you use the DISPLAY UPON ENVIRONMENT-NAME construct. In all other cases, this tunable should not be set.

Parent topic: List of Run-time Tunables


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

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 runtime assumes that any unknown remote file system supports 64-bit file access.
FALSE | The runtime assumes that any unknown remote file system does not support 64-bit file access.

Properties:

Default: | FALSE
IDE equivalent: | None

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
Related reference
CBL_OPEN_FILE
CBL_CREATE_FILE
FILEMAXSIZE


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 132 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
Related information
Run-time Configuration Tunables - Overview


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 60 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
IDE equivalent: None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


shared_memory_segment_size

Specifies the initial size of the shared memory block allocated by the run-time system.
Restriction: These tunables are 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 (8 K).

Properties:

Default: | 65536 (64 K)
IDE equivalent: | None
Parent topic: List of Run-time Tunables
Related information
Run-time Configuration Tunables - Overview


signal_regime

Specifies whether or not the run-time system is to use 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 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 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 115 ("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 sig is 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: | None

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
cobpostsighandler
cobremovesighandler
Related information
Signal Handling Overview
Third Party Software that Uses Signals
Run-time Configuration Tunables - Overview


stackdump_filename

Restriction: This only applies to the following platforms: Linux Intel 64-bit, Solaris Intel 64-bit, and Linux/390.
Specifies the name of the file that is generated when the stackdump_on_error tunable is set to TRUE.

Syntax:

>>-----set stackdump_filename=---"path&filename"-----------><

Parameters:

path&filename The path and name of the file that will be produced when a stackdump file is generated. 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: | <program-basename>.stackdump.<process-id>.log, created in the current working directory.
IDE equivalent: | None

Example:

set stackdump_filename="/home/temp/stackdump/stack.%p@%t_%d"

Produces a filename such as stack.12345@165920_20080115, on the path /home/temp/stackdump.

Parent topic: List of Run-time Tunables
Related reference
stackdump_on_error


stackdump_on_error

Restriction: This only applies to the following platforms: Linux Intel 64-bit, Solaris Intel 64-bit, and Linux/390.
When a program generates a run-time error, this tunable specifies whether a stackdump file is created. A stackdump file contains a list of the threads in the process at the time of the error, and a stack trace for each thread.

Syntax:

>>---set stackdump_on_error=--.-1-.---------><
                              +-0-+

Parameters:

1 | A file is created when a program generates a run-time error. The file contains a stack trace for each thread in the program. The default filename is <program-basename>.stackdump.<process-id>.log, which is created in the program's working directory. You can override the default filename and location using the stackdump_filename tunable.
0 | No file is created when a program generates a run-time error.

Properties:

Default: | 0
IDE equivalent: | None

Comments:

This tunable only affects native applications that are built to an executable; it will not affect managed COBOL programs, or programs built to INT/GNT format.

This option is processed at the same time as an error message is produced. If core_on_error is also specified, core file processing is performed first, which means that if a core file is to be created, a stackdump file is only produced when core_on_error is set to 3.

Parent topic: List of Run-time Tunables
Related reference
stackdump_filename


strict_file_locking

Enables or disables the strict file locking mechanism for UNIX platforms.
Restriction:

This tunable is supported for native COBOL only.

Syntax:

>>-----set-strict_file_locking=--.-TRUE--.--><
                                 +-FALSE-+

Parameters:

TRUE | Sets strict file locking mode, which honors the locking and sharing options that are in place.
FALSE | Provided for backward compatibility.

Properties:

Default: | TRUE
IDE equivalent: | None

Comments:

You can use this mechanism with both 32-bit and 64-bit file handling operations.

If your application encounters unexpected OPEN conditions or fails to open files, it might be as a result of the new file locking behavior. In such circumstances, we recommend that you review the file locking and sharing requirements of your application and refactor your source code to work with the default setting. The original file locking and sharing behavior can be restored by setting strict_file_locking=false.

Parent topic: List of Run-time Tunables
Related concepts
Sharing Mode
The File Control Entry
LOCKTYPE


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

Comments:

As far as your program is concerned, logical and physical cancels behave identically.

The default cancel mode in previous Micro Focus products used to be a logical cancel.

Parent topic: List of Run-time Tunables
Related reference
CBL_SUBSYSTEM
Related information
Run-time Configuration Tunables - Overview


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.
Restriction: These tunables are supported for native COBOL only.

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 the ACCEPT identifier FROM TIME syntax or the CURRENT-DATE intrinsic function is used.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
current_day
current_hour
current_minute
current_month
current_second
current_year
datewarp_dynamic
Related information
Run-time Configuration Tunables - Overview


Terminfo Database and Terminal Devices

Interactive COBOL applications rely heavily on sophisticated use of the terminal device for full-screen input and output, using the ACCEPT and DISPLAY statements. UNIX allows virtually any type of terminal device to be connected and provides the terminfo database as a means for handling the diversity of terminals. This chapter describes how the terminfo database is used by your COBOL system and what details need to be included in the database to enable COBOL to use particular terminal features. This section also describes the Micro Focus terminfo utilities mftic and mfinfocmp.

See Device Handling in your Program Development Guide discusses devices in general including terminal devices. This chapter describes the detailed use and configuration of terminal devices for UNIX.

  • Overview
  • Searching Portable and System Terminfo Databases
  • Terminal Devices
  • Special Terminal Facilities
  • Terminal Emulators
  • The Portable Terminfo Utilities mftic and mfinfocmp
Parent topic: General Reference


Overview

The terminal is perhaps the most important and complex device that a typical COBOL program uses. It can be used in two ways:

  • For simple unformatted line input and output
  • For formatted, full screen, field input and output

For unformatted screen I/O, the COBOL system takes no special action. It simply uses the logical UNIX devices stdin, stdout and stderr (see the chapter Device Handling in your Program Development Guide) assuming that these are redirected by the operating system from or to the terminal.

For formatted screen I/O, the COBOL system has to take action at two levels: the logical level and the physical level. The Adis module translates the high-level COBOL requirements into logical, low-level, terminal-independent operations. The screen handling module translates these logical operations into the terminal-dependent physical character strings and escape sequences required by the attached terminal. The screen handling module also translates any response from the terminal into logical form and returns it to the Adis module.

To carry out the mapping between logical and physical form, the screen handling module needs to know the type of terminal that is attached, the capabilities of that terminal type and the physical format of any I/O activity. UNIX provides a standard method for providing this information; the environment variable TERM contains the name of the terminal type, and the details for that terminal type are held in a UNIX system database, known as terminfo.

  • System Terminfo
  • Portable Terminfo for COBOL
  • COBOL Screen Handling Requirements
Parent topic: Terminfo Database and Terminal Devices


System Terminfo

Your COBOL system can understand and use the standard UNIX System V terminfo format and structure, although it ignores any non-standard UNIX vendor-specific extensions. Some UNIX systems do not use the standard terminfo format and structure, and in this case, your COBOL system uses the alternative portable UNIX terminfo database described in this section.

The system terminfo database is located in the default system terminfo directory (for example, /usr/share/lib/terminfo on AIX) and is available for general use by any system application; a typical example being the system editor vi. If a particular process requires use of an alternative general terminfo database, this can be selected by specifying its location in the environment variable TERMINFO.

The terminal details are held in a terminfo database, for general use by non-COBOL applications. They can be made suitable for use by COBOL applications, but frequently there is a conflict. COBOL terminal I/O is generally more sophisticated than that of most UNIX applications and has more stringent minimal requirements of the terminfo database. The precise meaning of some the terminal information can be ambiguous and sometimes the terminfo database reflects an interpretation that differs from that made by the COBOL system. In addition, the terminfo database is sometimes modified to configure a non-COBOL application and so becomes unsuitable for use with a COBOL application.

Parent topic: Overview
Related information
Portable Terminfo for COBOL


Portable Terminfo for COBOL

This COBOL system supports the use of a portable UNIX terminfo database and provides one that includes details for a selection of terminals. The format follows the UNIX specification but omits the UNIX vendor-specific portions. The database can be used by COBOL applications as an adjunct or alternative to the system databases. The system COBOL terminfo database is held in the directory terminfo in the COBOL system directory $COBDIR. If a particular COBOL process requires use of an alternative COBOL terminfo database, then this can be selected by specifying its location in the environment variable COBTERMINFO.

The portable UNIX terminfo database can be maintained using the utilities mftic and mfinfocmp that are described later in this section.

Parent topic: Overview
Related information
System Terminfo


COBOL Screen Handling Requirements

When COBOL provides formatted field input and output on the terminal, it carries out some sophisticated screen handling compared to many UNIX applications. Certain terminal capabilities must be available and described in the terminfo entry referenced by TERM otherwise the run-time system gives a run-time error.

Your COBOL system tries to optimize the use of the terminal and uses some optional terminal capabilities if they are described in terminfo. Required and optional terminal terminfo details are described in this section.

Parent topic: Overview


Searching Portable and System Terminfo Databases

The COBOL system recognizes two types of terminfo database: the portable terminfo for COBOL and the system terminfo. When it requires details for a terminal it searches each database that is specified by the environment until it finds details for that terminal.

The COBOL system searches first for a COBOL-specific terminfo file and if that is not found it searches for a system terminfo file (see steps below). Non-COBOL utilities such as vi only search for a system terminfo file.

For a particular terminal, COBOL applications and non-COBOL applications such as vi can have different requirements for a terminfo file. Not only can different entries be required but also they can require different binary formats. COBOL might require a portable format and non-COBOL requires a system-specific format.

It is important to distinguish between general terminfo files and COBOL-specific terminfo files (examples provided with this system), to place them in separate locations and at run time to set up the environment variables COBTERMINFO (see the appendix Environment Variables) for the COBOL-specific files and TERMINFO for the system or general terminfo files as appropriate. The COBOL system then searches for a terminfo file using the following steps:

  1. If the COBTERMINFO environment variable is not set, it is considered set to $COBDIR/terminfo.
  2. If COBTERMINFO is set, it is read as a set of colon-separated paths to the terminfo database. If the required file is found on any of the paths (parsed from left to right), then it is used.
  3. If the TERMINFO environment variable is set, it is used as a path to the terminfo database. If the file is found, it is used.
  4. Use the default system terminfo database as the path to the terminfo database. If the file is found here, it is used.
  5. If the file is not found, an error is returned.
Parent topic: Terminfo Database and Terminal Devices


Terminal Devices

UNIX environments support virtually any terminal type, terminal definitions being held in a system database. This database must contain enough details for the terminal being used in order that Adis can function.

Adis uses the standard input and output device interfaces for terminal I/O and so such terminal I/O can be redirected but with the restriction that you must not redirect standard input from a file unless it is a terminal device.

So, for example, the following is legal:

cobrun prog < `tty` >`tty`

(use the appropriate (`) character) whereas redirecting the input from an ordinary file or /dev/null is not legal and could result in a run time error.

  • Screen Handling Requirements
  • Essential Entries
  • Optional Entries
Parent topic: Terminfo Database and Terminal Devices


Screen Handling Requirements

The COBOL run-time system depends on a terminfo database being available and providing various terminal details to support the Adis module. The run time system regards some details as essential, and returns a run time error if they are not available. It regards all others as optional (making use of many of them and ignoring the rest). The following tables list entries in a terminfo terminal description that are recognized by the COBOL system. See your UNIX system documentation for details on the system terminfo database and how to specify terminal capabilities.

Parent topic: Terminal Devices


Essential Entries

The following entries must be present for the Micro Focus COBOL system to operate correctly. Entries marked with an asterisk (*) should be set appropriately for the type of terminal.

Entry | Mnemonic
Clear to end of line | el
Clear screen | clear
Clear to end of screen | ed
Cursor address (row, column) | cup
Cursor down | cud1
Cursor home | home
Cursor left | cub1
Cursor right | cuf1
Cursor up | cuu1
Eat newline glitch * | xenl
Entries for cursor keys | kcud1, kcub1, kcuf1, kcuu1
Entries for function keys f1 to f63 * | kf1 to kf63
Entries for home, next page, previous page, end, backtab, insert, delete and clear-to-end-of-field keys * | khome, knp, kpp, kend, kcbt, kich1, kdch1, kel
Exit attribute mode | sgr0
Number of columns ** | cols
Number of lines ** | lines
Xon/xoff * | xon

** The number of lines and columns will be read dynamically if using an X terminal, or can be overridden using the environment variables LINES and COLUMNS. See the appendix Environment Variables for details.

Parent topic: Terminal Devices


Optional Entries

The following entries should be used if they are required for the particular type of terminal. However, the Micro Focus COBOL system does not insist that they are present.

Entry | Mnemonic
Bell | bel
Carriage return | cr
Enter ca mode | smcup
Exit ca mode | rmcup
Keypad local | rmkx
Keypad transmit | smkx
Move safely in standout mode (if appropriate) | msgr

Some terminals must have smcup and rmcup in order to work correctly.

  • Highlighting
  • Performance Considerations
  • Wide Terminal Mode
  • Line Drawing
  • Color
Parent topic: Terminal Devices


Highlighting

For terminals that have additive attributes the following are used. Entries marked with an asterisk (*) should be set appropriately for the type of terminal:

Entry | Mnemonic
Enter blink mode * | blink
Enter bold mode * | bold
Enter dim mode * | dim
Enter reverse mode * | rev
Enter underline mode * | smul

For terminals that do not have additive attributes, the following is needed:

Entry | Mnemonic
Set attributes | sgr

Highlighting is also affected by the COBATTR environment variable. See the appendix Environment Variables for details.

Parent topic: Optional Entries


Performance Considerations

The following optional entries can be included and can improve the performance of screen displays in some situations:

Entry | Mnemonic
Parameterized cursor down | cud
Parameterized cursor left | cub
Parameterized cursor right | cuf
Parameterized cursor up | cuu

If the following entries are present, scroll regions can be used to scroll areas of the screen, which greatly speeds up such operations:

Entry | Mnemonic
Change scroll region | csr
Insert line | il1
Delete line | dl1
Scroll forward | ind
Scroll reverse | ri
parameterized scroll forward | indn
parameterized scroll reverse | rin
Parent topic: Optional Entries


Wide Terminal Mode

If you want to use wide terminal mode, you must ensure that the sequence to set the number of columns appears in one of the following entries:

Entry | Mnemonic
Initialize string 1 | is1
Initialize string 2 | is2
Initialize string 3 | is3
Reset string 1 | rs1
Reset string 2 | rs2
Reset string 3 | rs3
Parent topic: Optional Entries


Line Drawing

For terminals that have additive attributes the following are used:

Entry | Mnemonic
Enable alternate character set | enacs
Alternate character set characters | acsc
Enter alternate character set | smacs
End alternate character set | rmacs

For terminals that do not have additive attributes, the following is needed:

Entry | Mnemonic
Set attributes | sgr

If you do not specify the appropriate alternate character set characters for your terminal, or your terminal does not provide a complete set, normal ASCII characters are substituted for the missing line drawing characters.

Parent topic: Optional Entries


Color

Only the Tektronix color manipulation method can be used; for example, ANSI color terminals use the Tektronix method. The following entries are required:

Entry | Mnemonic
No color video | ncv
Number of colors | colors
Set foreground | setf
Set background | setb
Original colors | oc
Original pairs | op

Only one of oc or op needs to be specified, but it must reset to the default colors.

Check that these entries are included in your terminfo database by running the mfinfocmp utility. See Terminfo Lister (mfinfocmp) for details.

Should you require, you can add entries to your terminfo database by running the operating system utility tic See your operating system manuals for details of how to do this. Alternatively, you can create a new set of COBOL-specific terminal details in a COBOL-specific terminfo database using the mftic utility. See Terminfo Compiler (mftic) for details.

Notes:

  • If you use an attribute that is defined in your terminfo, but your terminal does not recognize it, the attribute is not displayed and no error message is given.
  • Any attributes in ACCEPT or DISPLAY statements are automatically disabled by the run-time system if your terminal uses character positions to store attributes. This is the case for terminals that support the magic cookie glitch; that is, terminals that have "xmc" defined in their terminfo file.
Parent topic: Optional Entries
Related information
Terminfo Compiler (mftic)
Terminfo Lister (mfinfocmp)


Special Terminal Facilities

The following sections cover special terminal considerations.

  • Wide Terminal Mode
Parent topic: Terminfo Database and Terminal Devices


Wide Terminal Mode

This facility is for use with COBOL only, and enables you to use a wide mode if it is supported on your terminal; for example vt100 style terminals have a 132 column mode. All normal methods of screen output are allowed including ANSI DISPLAY, Adis DISPLAY and the cobprintf() call. Cursor addressing must be consistent with the current terminal mode. For example, if you ask Adis to position the cursor at column 100 while in 80 column mode, this is not successful, neither does it cause an automatic switch from normal to wide mode. Wide mode must be set explicitly as shown below.

To use this facility you must include a record in the Working-Storage Section of your program as follows:

01 mode-number pic x comp-x.

then at run time you use the following call:

call "cobtermmode" using mode-number

where mode-number can have one of the following values:

Value | Meaning
0 | Standard terminal mode. The standard terminal terminfo file is used.
1 | Wide terminal mode. The standard terminal name suffixed by -w is the name of the terminfo file used.

The value of RETURN-CODE is set to zero if the call completes successfully. It is set to non-zero if the call fails, for example if the required terminfo file cannot be found. The method of searching for terminfo is described in Searching Portable and System Terminfo Databases.

If the call is successful, the screen handling system is initialized (if it was not already) and:

  • A RETURN-CODE of zero is returned.
  • Adis restarts in the new mode.
  • All character and attribute maps are cleared.
  • The screen is cleared and the cursor positioned in the home position.

As the screen handling system is now initialized, all DISPLAY statements now use it, including ANSI DISPLAY statements.

If the call fails, the RETURN-CODE is nonzero and the screen does not change. The RETURN-CODE is set as follows:

Value | Meaning
0 | Operation successful.
1 | The terminfo file has not been found, is not readable, is corrupt or there is not enough memory.
2 | The terminfo file does not contain one or more of the required capabilities.
3 | The environment does not support the requested code.

When using the cobtermmode call, you must be aware of the following:

  • The number of columns in wide mode must not exceed 255 .
  • When running under Animator, this call causes the terminal to be initialized to the new mode, which can produce some flicker of the display. Switching between Animator and user screens causes mode changes as the wide terminal mode is not supported for Animator's screen.
  • When the run-time system exits, the terminal is restored to normal mode. This applies only to mode changes made under the control of this call.
  • Since the usual path-searching rules are used, if the directory pointed to by COBTERMINFO contains an entry for the terminal in normal mode, but not wide mode, but the system terminfo directory does contain an entry for that terminal in wide mode, the normal mode uses the COBTERMINFO version and wide mode uses the system version. This can cause unexpected results where the two files differ in capabilities other than column size changes.
  • If you have already set the TERM environment variable to indicate that a wide mode is required (that is the TERM value already has a -w suffix), issuing the call to use wide mode results in a suffix of "-w-w". This almost certainly fails, unless the terminal has a double wide mode and a terminfo file for this mode is available.

To cause the terminal to switch states, six terminfo facilities are used:

Full Name | Abbreviated Name
init_1string | is1
init_2string | is2
init_3string | is3
reset_1string | rs1
reset_2string | rs2
reset_3string | rs3

These are fully documented in the AT&T UNIX System V Interface Definition (SVID) and are used as follows:

  • When the screen libraries start up normally, is1, is2 and is3 are output in that order. When the terminal mode is changed, rs1, rs2, rs3 are output, then is1, is2, is3 of the new terminfo are output in that order.
  • Standard terminfos can contain the column switching sequences in either the rsx family or the isx family, hence both need to be used. Terminfos that do not provide it in either need to be modified, or a new terminfo file needs to be supplied.

Ensure that the terminal mode and terminfo specified by the terminal name in TERM match when you run an application.

Parent topic: Special Terminal Facilities
Related information
Searching Portable and System Terminfo Databases


Terminal Emulators

This COBOL system supports a number of terminal emulators, for example xterm, which can be used with the requisite environment settings.

In the case of xterm, set the TERM environment variable to xterm, or xterm-color if your xterm supports it.

There are a number of non-native terminal emulators that can be used with this COBOL system when connecting to the host system remotely. The following section contains a list of some of the popular products and their recommended settings to help you connect:

Micro Focus Rumba+ Desktop
  • Within the UNIX Display window, select the terminal type to ANSI (SCO).
  • Set the TERM environment variable to ansi80x25.
PuTTY
Within the PuTTY Configuration screen:
  • Select Xterm R6 from the Terminal > Keyboard category.
  • Set the TERM environment variable to xterm-color, or xterm-color.
  • If line drawing is required, do not use the default UTF-8 remote character set setting. Change this in the Window > Translation category.
Cygwin
(Also known as mintty.)
Set the TERM environment variable to xterm or xterm-color.
Parent topic: Terminfo Database and Terminal Devices


The Portable Terminfo Utilities mftic and mfinfocmp

The UNIX operating system enables applications to handle terminal I/O from any terminal attached to the system, though each terminal can be of a different type with different capabilities. It does this using a database of terminal types, the terminfo database, that includes a file for each type of terminal. Each terminfo file holds details of the capabilities of the terminal-type identified by the filename. The details are stored in a machine-readable, compiled format that is specified in the entry for terminfo in your operating system documentation. The specification includes an initial generic portion and allows for a subsequent vendor-specific portion.

Each vendor's UNIX generally provides a utility, tic, that creates a terminfo file from human-readable parameters given in a terminfo "source" file and a utility, infocmp, that creates a terminfo source file from a compiled terminfo file. Both utilities assume the vendor-specific format for the terminfo file.

This COBOL system uses the terminfo database to handle any terminal I/O that your applications require. It uses the generic portion of the terminfo file and ignores any vendor-specific portion. It uses only some of the terminal capabilities that can be specified; some are mandatory and some are optional.

Two machines running UNIX from two different vendors and having identical terminal types attached can run the same COBOL application. This COBOL system can use an identical terminfo file on each machine. However, it can be difficult to exploit this capability if a UNIX vendor does not conform to the standard for the generic portion of the terminfo file or if a UNIX vendor adds a vendor-specific portion to the terminfo file that is inconsistent with that from other vendors.

You can solve this problem by using the COBOL system utilities mftic and mfinfocmp in place of the system utilities tic and infocmp. Both COBOL utilities can operate in the following two modes:

  • Micro Focus format mode
  • UNIX vendor-specific format mode

Micro Focus mode assumes that the terminfo file format comprises only the standard generic portion of the specification and that only the capabilities recognized by this COBOL system are present. This format is fully portable between different versions of UNIX; however, it might not include all the capabilities required by non-COBOL applications.

UNIX vendor-specific mode assumes that the terminfo format is fully compatible with the system tic and infocmp utilities. This format is generally not portable between different versions of UNIX, but it does enable you to define all the capabilities available to non-COBOL applications.

For a detailed description of the terminfo source and binary formats, including the list of capabilities your environment supports, see your operating system documentation. For a list of essential terminal capabilities required by the Micro Focus COBOL system, see Screen Handling Requirements.

  • Terminfo Compiler (mftic)
  • Terminfo Lister (mfinfocmp)
  • Search Sequence
Parent topic: Terminfo Database and Terminal Devices
Related information
Screen Handling Requirements


Terminfo Compiler (mftic)

The terminfo compiler, mftic, translates a terminfo source file from the source format to the compiled format, that is placed in a terminfo database. See Search Sequence for details of how this database is located.

mftic is compatible with tic. By default, mftic produces terminfo binaries in a Micro Focus generic format. It can also produce terminfo binaries in the same format as the system format.

mftic supports the concept of use= links, as tic does. When it encounters a use=name entry in a source file, mftic tries to augment the current terminal description with the description of the terminal name. mftic first searches for name in the current source file and if not found it searches the compiled terminfo database. If name is still not found then mftic reports an error and stops. mftic recursively follows use= links if necessary.

The command line to invoke mftic is:

 mftic [-vn] [-c] [-m] [-S] filename

where the parameters are:

-vn | Specifies whether or not the compiler gives verbose messages. The value of n is one of: 0 - suppress all messages 1 - give verbose messages
-c | Prevents the creation of terminfo binaries. When this option is used, mftic only checks the input source file for errors (it does not check use= links for errors).
-m | Produces terminfo binaries in Micro Focus format rather than in the UNIX vendor-specific format. These formats are described in the section The Portable Terminfo Utilities mftic and mfinfocmp. This is the default.
-S | Treats the input binary as UNIX vendor-specific format rather than in the Micro Focus format.
filename | The name of the terminfo source file to be compiled.
Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Search Sequence
Terminfo Lister (mfinfocmp)


Terminfo Lister (mfinfocmp)

The mfinfocmp utility performs either of the following functions:

  • Lists a terminfo source description from the specified binary file
  • Compares two or more terminfo binary files.

The binary, compiled, files must be held in a terminfo database. See Search Sequence for details of how this database is located if the -A or -B options are not set.

The command line for invoking mfinfocmp is:

mfinfocmp [-1] [-m] [-w n] [-A dir] [-B dir] [-S]
    [filename [...]]

where the parameters are:

-1 | (Numeric one, not a lower case "L") Outputs the results in single-column format.
-w n | Limits the width of the output to n characters. The default value of n is 60.
-m | Treats the input binary file as Micro Focus format, that is, a file produced by mftic with the -m option set. Results are undefined if this option is used to list a terminfo file in system format. This is the default.
  • -A dir
  • -B dir
 Changes the location of the terminfo database when comparing two or more files. The -A option changes the database location for the first file to the directory specified. The -B option changes the database location for the second and subsequent files to the directory specified. (Note that the binary files do not usually reside in the same directory as the database. For example, the file containing details for the vt100 terminal typically resides in a subdirectory v in the database.)
-S | Treats the input binary as UNIX vendor-specific format rather than Micro Focus format.
filename Either the name of the terminfo binary file to be listed or the names of the terminfo binary files to be compared. The function performed depends on the number of filenames specified on the command line as follows:

If no file is specified, mfinfocmp takes the name held in the TERM environment variable and lists that file's terminfo source description

If one file is specified, mfinfocmp lists the given file's terminfo source description

If two or more files are specified, mfinfocmp compares the first file with the second and subsequent given files.

Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Search Sequence
Terminfo Compiler (mftic)


Search Sequence

mftic produces, and mfinfocmp lists, compiled format terminfo files for a terminfo database. Unless an option is specified to override it, by default, the directory containing the database is located using the following search sequences:

For mftic:

If parameter -m (which is the default) is used, the sequence is as follows:

  1. The COBTERMINFO environment variable specifies the directory in which to locate the file.
  2. The TERMINFO environment variable specifies the directory in which to locate the file.
  3. The path $COBDIR/terminfo specifies the directory in which to locate the file.

If parameter -S is used, the sequence is as follows:

  1. The TERMINFO environment variable specifies the directory in which to locate the file.
  2. The path to your default system terminfo directory specifies the directory in which to locate the file.

For mfinfocmp:

If parameter -m (which is the default) is used, the sequence is as follows:

  1. The COBTERMINFO environment variable specifies the directory in which to locate the file.
  2. The path $COBDIR/terminfo specifies the directory in which to locate the file.
  3. The TERMINFO environment variable specifies the directory in which to locate the file.
  4. The path to your default system terminfo directory specifies the directory in which to locate the file.

If parameter -S is used, the sequence is as follows:

  1. The TERMINFO environment variable specifies the directory in which to locate the file.
  2. The path to your default system terminfo directory specifies the directory in which to locate the file.

See Terminfo Compiler (mftic) and Terminfo Lister (mfinfocmp) for more details on the available parameters.

Note: If Micro Focus format terminfo files (i.e. the -m parameter) are placed in a database located in a directory other than $COBDIR/terminfo, then at COBOL application run time you must use the COBTERMINFO environment variable (rather than the TERMINFO environment variable) to locate this directory. If you do not do this, either COBOL or non-COBOL applications can fail to run correctly.
Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Terminfo Compiler (mftic)
Terminfo Lister (mfinfocmp)


UNIX Key Usage Chart

Because UNIX terminals vary widely, the keys documented in this manual might not be available on your keyboard. This topic lists the actual keystrokes required to obtain the keys documented.

The table also tells you how to select soft or hard operation for the Alt and Ctrl keys. With soft operation, the Alt or Ctrl key is automatically turned off after the next keystroke. This means that whenever you want a function from the Alt menu you must hold down Alt again to get the Alt menu displayed; and similarly with Ctrl. With hard operation, the Alt and Ctrl keys work in a similar way to the Caps Lock key, in that having been pressed, they remain in effect until pressed again.

The following table lists the available functions, the key documented as resulting in that function, the keystrokes required to obtain the documented functions, and whether the keystroke can be configured (Y) or not (x).

Function | Documented Key | Mapped To | Configurable
Alternate Menu (soft) | Alt | /a | Y
Alternate Menu (hard) | Alt | /x | Y
Control Menu (soft) | Ctrl | /c | Y
Control Menu (hard) | Ctrl | /z | Y
/ | / | // | Y
Escape | Escape | /@ | Y
F1 | F1 | /1 | x
F2 | F2 | /2 | x
F3 | F3 | /3 | x
F4 | F4 | /4 | x
F5 | F5 | /5 | x
F6 | F6 | /6 | x
F7 | F7 | /7 | x
F8 | F8 | /8 | x
F9 | F9 | /9 | x
F10 | F10 | /0 | x
F11 | F11 | /- | x
F12 | F12 | /= | x
Backspace | Backspace | /b | Y
Backtab | Backtab | /T | Y
Caps Lock (upper case) | Caps Lock | /u | Y
Delete | Del | /d | Y
End | End | /e | Y
Help | F1 | /? | Y
Home | Home | /h | Y
Insert | Ins | /i | Y
Interrupt | Ctrl+Break | User defined (see Note 2) | N/A
Left Shift | Shift | /l | Y
Maphelp |  | /m | Y
Num Lock | Num Lock | /# | Y
Page Up | Page-Up | /p | Y
Page Down | Page-Down | /n | Y
Refresh | Refresh | /| | Y
Right Shift | Shift | /r | Y
Scroll Lock | Scroll | /s | Y
Tab | Tab | /t | Y

Notes:

  1. Tab is the only case-sensitive keystroke. By default, lower-case Tab (/t) provides Tab, with upper-case Tab (/T) providing Backtab.
  2. The interrupt key can be defined as follows:
    stty intr ^C
  3. The keystrokes listed above are those set up by default for your system. Those functions with a check mark (Y) in the column headed Configurable can have their associated keystroke mapped onto a keystroke of your choice. You can also configure the meta character used, which is / by default.

    To change the defaults, create the file adiskey.map and enter your choice of keys. (An example file, adiskey.xxx is supplied with this system.) On startup, your COBOL system searches for adiskey.map in the current directory, then in the directory specified by the COBDIR environment variable. If it is not found the defaults are used. The following is an example adiskey.map file:

    * Micro Focus ADISKEY keyboard mapping file. Keystrokes are
* case insensitive except for TAB which uses Upper-Case-Tab
* for the Back-Tab function. An asterisk denotes a comment.
* This file shows the default keyboard mapping

         Meta-Char   is "/"
         Soft-Alt    is "a"
         Soft-Ctrl   is "c"
         Hard-Alt    is "x"
         Hard-Ctrl   is "z"
         Left-Shift  is "l"
         Right-Shift is "r"
         Caps-Lock   is "u"
         Num-Lock    is "#"
         Scroll-Lock is "s"
         Insert      is "i"
         Delete      is "d"
         Backspace   is "b"
         Home        is "h"
         End         is "e"
         Page-Up     is "p"
         Page-Down   is "n"
         Tab         is "t"
         Escape      is "@"
         Map-Help    is "m"
         Help        is "?"
         Refresh     is "|"
Parent topic: General Reference


Deployment

  • Deploying COBOL Applications
    Describes the concepts and tasks involved in deploying COBOL applications using COBOL Server.
  • Deploying to Enterprise Server
    This is the Enterprise Server Configuration and Administration help. It contains the information you need for setting up and configuring an Enterprise Server installation.
Parent topic: Visual COBOL Development Hub 5.0


Deploying COBOL Applications

Describes the concepts and tasks involved in deploying COBOL applications using COBOL Server.
  • Overview of Deploying Your Applications
  • Deploying the Micro Focus Run-Time System
  • Deploying COBOL Applications to .NET Core
  • Deploying JVM Applications
  • Multi-Platform Deployment of JVM COBOL Applications
Parent topic: Deployment


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.

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

End users need to install COBOL run-time licenses before they can run applications that use the COBOL run-time system.

You need to:

  • Ship COBOL Server with your application.
  • Ensure that the application you have developed has the proper COBOL Server licenses. Your end users need to install the licenses before they can run the application. This is done by using the Micro Focus 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.
Parent topic: Deploying COBOL Applications
Related concepts
Deploying the Micro Focus Run-Time System
Deploying JVM Applications


Deploying the Micro Focus Run-Time System

Applications developed using Visual COBOL require a COBOL run-time server, COBOL Server, to provide the necessary run-time system and support.

Micro Focus recommends that you install the full COBOL Server with your applications.

To install COBOL Server, run the install file setup_cobol_server_5.0_platform.

You can also install COBOL Server silently - see COBOL Server Installation Options.

  • COBOL Server Install Options
    You can install Micro Focus products silently by using command line parameters to specify the installation directory, user information, and which features to install. You must execute the command with superuser permissions.
Parent topic: Deploying COBOL Applications
Related concepts
Overview of Deploying Your Applications
Deploying JVM Applications


COBOL Server Install Options

You can use the following command line arguments to install silently on UNIX/Linux. You need to execute the commands as root:

–silent -IacceptEULA

For example, execute:

setup_filename –silent -IacceptEULA

Installing into a different location

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

./setup_cobol_server_5.0_platform -installlocation="full path of new location"
Note: You can use variables when specifying an absolute path for –installlocation. For example, the following examples are equivalent:
-installlocation="/home/myid/installdir"
-installlocation="$HOME/installdir"

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

Configuring Enterprise Server

You can use the following options to configure the Enterprise Server installation: [ -ESsysLog="Y/N" ] [ -ESadminID="User ID" ] [ -CASrtDir="location" ], where:
-ESsysLog
Use this to enable ("Y") or disable ("N") Enterprise Server system logging. Logging is enabled by default. Log files are saved in /var/mfcobol/logs.
-ESadminID
Sets the Enterprise Server System Administrator Process User ID from the command line - for example, -ESadminID="esadm". The default user ID is the one that runs the installer.
-CASrtDir
Specifies the location were the Enterprise Server run-time system files are placed - for example, -CASrtDir="/home/esuser/casrt/es". The default location is /var/mfcobol/es.
Parent topic: Deploying the Micro Focus Run-Time System


Deploying COBOL Applications to .NET Core

  • Introduction to Deploying COBOL Applications to .NET Core
  • To deploy a COBOL application to .NET Core
Parent topic: Deploying COBOL Applications


Introduction to Deploying COBOL Applications to .NET Core

Attention: .NET Core on Linux is provided as an Early Adopter Product (EAP) feature only. It is being made available to allow you to test and provide feedback on the new capabilities. Be aware that file locking does not work in all instances, and may cause exceptions or the ignoring of file locks. We will continue the development of this feature and provide additional interfaces via patch updates and future releases. Please contact Micro Focus SupportLine if you require further clarification.

.NET Core is an open-source development platform that supports multiple operating systems. As such, a COBOL application that has been published for use with .NET Core can be deployed to any operating system that .NET Core 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 Core. To develop and publish a COBOL application for .NET Core you must use Visual COBOL with Visual Studio 2017 version 15.9 or later.

Parent topic: Deploying COBOL Applications to .NET Core
Related reference
Microsoft: .NET Core Guide
Related information
To deploy a COBOL application to .NET Core


To deploy a COBOL application to .NET Core

Attention: .NET Core on Linux is provided as an Early Adopter Product (EAP) feature only. It is being made available to allow you to test and provide feedback on the new capabilities. Be aware that file locking does not work in all instances, and may cause exceptions or the ignoring of file locks. We will continue the development of this feature and provide additional interfaces via patch updates and future releases. Please contact Micro Focus SupportLine if you require further clarification.

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 Core
Related information
Introduction to Deploying COBOL Applications to .NET Core


Deploying JVM Applications

JVM application are a collection of classes (.class files).

COBOL JVM applications that do not use an application server

Compile your JVM COBOL application to .class files. Optionally, package these to a .jar file (using the jar command). Ship with COBOL Server (requires a license).

COBOL JVM applications that run on an application server

You can deploy JVM COBOL applications to an application server such as JBoss, WebSphere or Tomcat.

The applications could include only JVM COBOL code or could be a mixture of JVM COBOL and Java Code. They could use EJBs or Web services - e.g. managed REST, WSDL.

In order to deploy, you need to:

  • Package the application as either a .jar, .ear, or a .war file.
  • Deploy the file to the application server according to the server's requirements.
  • You also need to deploy the Micro Focus managed run-time, mfcobolrts.jar. You can do this either separately or in the application's .ear or war file. See Java Calling JVM COBOL.

You do not need to ship COBOL Server in this case.

Parent topic: Deploying COBOL Applications
Related concepts
Overview of Deploying Your Applications
Deploying the Micro Focus Run-Time System


Multi-Platform Deployment of JVM COBOL Applications

You can compile your COBOL application as JVM byte code (.class files) on any platform that Visual COBOL supports. You can then deploy the class files to a supported target platform without the need to recompile. For example, you can compile on Windows and deploy to either UNIX or Linux platforms, and vice versa. However, you should consider the following points that can affect the portability of your code between platforms. In these situations, there might be variations in the behavior depending on the platform:

  • Byte ordering
  • Shift-JIS character encoding
  • Platform-specific APIs, ECMs, and preprocessors
  • Devices
  • Literals in the source code
  • SQL Applications
  • File Handling
  • Package Name Case
Parent topic: Deploying COBOL Applications


Byte ordering

There are two types of byte ordering. Big-endian format, this is where the byte containing the most significant bit is stored in the first memory location, followed by bytes decreasing in significance. IBM z/Architecture (Linux) mainframes use big-endian format. Intel x86 processors use little-endian format. This reverses the order of the sequence and stores the least significant byte at the first memory location.

Portability between little-endian and big-endian architecture depends on avoiding specific byte order operations, such as:

  • Checking or redefining individual bytes of a COMP-5 data item.
  • Specifying native Unicode encoding using UNICODE(NATIVE). You need to use UNICODE(PORTABLE) instead.

In addition you should avoid using data files created with native byte order.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Shift-JIS character encoding

Shift-JIS character encoding is stored in the same byte order regardless of the platform's endian format. The NCHAR compiler directive helps you work with double-byte character sets. See NCHAR for more information.

If an application containing Shift-JIS characters has been compiled using a Shift-JIS locale then the application can only be correctly interpreted by a platform that uses a Shift-JIS locale. In addition, different platforms might support a different set of Shift-JIS characters.

If you need your applications to be portable between platforms and contain Japanese character encoding then Micro Focus recommends you use Unicode.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Platform-specific APIs, ECMs, and preprocessors

You need to exercise caution when using third-party APIs, ECMs or preprocessors. If their use results in inserting OS-specific components then the generated .class files might not be portable. Check the documentation of the third-party supplier for any restrictions. Call conventions might also be platform specific, such as WinAPI.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Devices

You cannot use the Windows device names PRN or CON. The Windows NUL device and the UNIX /dev/null are functionally equivalent, however, their use in source code is not portable. You can use the CBL_GET_OS_INFO library routine to programmatically determine the OS type and then call the appropriate null device.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Literals in the source code

In order to ensure literals are compiled correctly on the source machine and then processed correctly at execution time on the deployment machine, Micro Focus recommends using an ISO-based LANG setting, such as LANG=en_GB.iso88591. This is to ensure literals can be correctly converted to Unicode.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


SQL Applications

OpenESQL and its DBMAN=JDBC directive have been tested for cross-platform JVM compatibility using standard COBOL SQL host variable specifications. See SQL Data Types for more information. In addition, OpenESQL supports the UNICODE"PORTABLE" COBOL compiler directive.

To be cross-platform compatible, OpenESQL applications must use standard, default SQLCA and SQLDA definitions which are provided with Visual COBOL. SQLCA and SQLDA definitions that use COMP items rather than standard COMP-5 items are not portable.

When compiling dynamic SQL with OpenESQL, pointers contained in the SQLDA are either 32 or 64-bit depending on whether the COBOL development system is 32 or 64-bit or if the P64 compiler directive has been set.

JVM classes generated by OpenESQL during compilation may be different across platforms, this is benign at execution time. During compilation, OpenESQL embeds timestamps and other artifacts that do not affect behavior at execution time.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


File Handling

The following file handling issues should be considered when creating applications that need to be portable between UNIX and Windows platforms:

  • The index file format default is different between Windows and UNIX. Options exist in the extfh.cfg configuration file that enable you to change the default to the source platform. See IDXFORMAT for more information.
  • Line sequential files have different line endings depending on the platform. See Line Sequential Files for more information. You can convert files when moving between platforms using a tool such as dos2unix or unix2dos.
Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Package Name Case

Package name case must be consistent across the application. On Windows, only one folder structure is created for the different case combinations used. On UNIX, a folder is created for each package name case combination used. This would prevent the Windows folder structure from being portable to UNIX. For example:

class-id Com.Company.Project.class1.

class-id com.company.project.class2.

This creates one folder on Windows but two on UNIX.

Parent topic: Multi-Platform Deployment of JVM COBOL Applications


Deploying to Enterprise Server

This is the Enterprise Server Configuration and Administration help. It contains the information you need for setting up and configuring an Enterprise Server installation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Enterprise Server configuration and administration
    Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to COBOL applications running as services that operate in an Enterprise Server environment.
  • Deploying and Configuring Modernized Applications
    Describes how to configure and administer modernized COBOL applications running in the Enterprise Server environment.
  • Enterprise Server Task Index
    Describes how to use Enterprise Server Administration to create, configure, and run an enterprise server, and perform other associated tasks.
  • Enterprise Server Reference
    Contains information on Enterprise Server configuration commands, error messages, user exits and switching modules.
  • Enterprise Server Security
    Contains information and procedures for all aspects of securing an Enterprise Server installation.
Parent topic: Deployment


Enterprise Server configuration and administration

Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to COBOL applications running as services that operate in an Enterprise Server environment.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Overview and Architecture
  • Configuration and Administration User Interface
  • Planning your Configuration
  • Configuring the Server Instance Environment
  • Configuring and Administering Enterprise Server Instances
  • Configuring Client-Server Communications
  • Configuring Enterprise Server for IBM WebSphere MQ
    This topic details the steps you need to take to configure IBM WebSphere MQ.
  • Monitoring Enterprise Server
  • User Exits for Request Handlers
  • Troubleshooting
  • Enterprise Server Administration Console Help Pages
  • Scale-Out Performance and Availability Clusters
  • Enterprise Server Common Web Administration
Parent topic: Deploying to Enterprise Server


Overview and Architecture

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

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

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


Enterprise Server Overview

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

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

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

  • COBOL applications running as services

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

Parent topic: Overview and Architecture


Enterprise Server Architecture

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

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

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

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

Parent topic: Overview and Architecture


Enterprise Server Instance Architecture

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

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

Figure 1. Enterprise Server Instance Architecture

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

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

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

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

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

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

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

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

Parent topic: Overview and Architecture


The Micro Focus Directory Server

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

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

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

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

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

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


Directory Server Information

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

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

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


Repository Statistics

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

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

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

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

Parent topic: The Micro Focus Directory Server


Service Execution Process (SEP)

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

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

  • Application container

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

  • Transaction management component

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

  • Request handler

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

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

  • Resource manager interface

    Handles requests for resources such as database and file access.

The processing of a request proceeds as follows:

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


Request Handlers

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

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

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

Parent topic: Overview and Architecture


Communications Processes

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

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

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


Listeners

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

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

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

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

Enterprise Server comes with several connectors, including:

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


Implementation Packages

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

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

Parent topic: Overview and Architecture


XA Resources

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

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

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


Enterprise Server Processes

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

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

Responsibities:

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

Responsibilities:

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

Responsibilities:

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

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

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

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

Parent topic: Overview and Architecture


Configuration and Administration User Interface

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

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

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


About the Enterprise Server Administration User Interface

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

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

Menus

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

Status line

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

Enterprise server instances

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

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

Refreshing a page

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

Parent topic: Configuration and Administration User Interface


User Interface Tables

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

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

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

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

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

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

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

Parent topic: Configuration and Administration User Interface


Navigation

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

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

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

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

Note:

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

Parent topic: Configuration and Administration User Interface


Accessing the Enterprise Server Administration UI

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

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

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

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

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

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

  • Displaying Server Information
  • Refreshing a Page
  • 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: Configuration and Administration User Interface
Parent topic: Enterprise Server Task Index


Displaying Server Information

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

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

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

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

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


Refreshing a Page

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

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

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

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


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


Planning your Configuration

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

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

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


Introduction

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

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

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

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

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


Security Options

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

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

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

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

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

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

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


About Securing an Enterprise Server Installation

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

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

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

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

  • The Directory Server (MFDS)

    The Directory Server maintains records of system components and their configurations. You use the Enterprise Server Administration user interface 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.
Parent topic: Security Options
Parent topic: Architecture and Overview


Setting up the Environment

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

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

You need to

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

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

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

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


Process User ID

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

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

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

Parent topic: Setting up the Environment


System-wide Environment Variables

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

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

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

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

Parent topic: Setting up the Environment


Firewall configuration

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

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

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

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

Parent topic: Planning your Configuration


About Communications Processes

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

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

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

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


Deployment Services and Listeners

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

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

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

  • Deployment Services
  • Deployment Listeners
  • The .mfdeploy file
    Enables deployment and configures mfdepinst, the deployment installer.
  • Restricting access to service deployment
    Configuring additional security for deploying services to COBOL Server.
Parent topic: Planning your Configuration


Deployment Services

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

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

The configuration information for a deployment service looks like this:

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

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

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

The settings for the Deployer service of ESDEMO are:

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

The configuration of a deployment service must match the configuration of the listener for the service. The URL parameter must specify the same virtual directory name for the location of the mfdeploy.exe program 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:
[virtual paths]
 <default>=/dev/null
 studioenterpriseedition=<ES>/bin
 project1=home/development/project1
 project2=home/development/project2
then you might create a deployment service named "project1" with this configuration:
[MF client]
 scheme=http
 URL=/studioenterpriseedition/mfdeploy.exe/project1
 accept=application/x-zip-compressed

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

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

Parent topic: Deployment Services and Listeners


Deployment Listeners

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

Deployment listeners allow a deployment client, such as the Visual COBOL 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 $COBDIR/bin.

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

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

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

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>=/usr/web
 docs=/usr/web/documents
 images=/home/media/images

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

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 COBOL 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 Visual COBOL (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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
The .mfdeploy file is used by the Visual COBOL 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.

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. Otherwise, the service being deployed must not already exist.

Advanced .mfdeploy configuration

From COBOL 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, COBOL 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

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

You can configure various attributes of an enterprise server instance, for example how much memory is available to it, how many service execution processes it starts up with, 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, and on UNIX, settings for environment variables (in [ES-Environment]), and values that include file or directory names are case-sensitive.

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


Shared Memory Area

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

The shared memory area is an area of memory where an enterprise server instance stores all the information it needs to run (see the section COBOL Server Architecture in the chapter Introduction). 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

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

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

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

Parent topic: Enterprise Server Instance Configuration Issues


Number of Service Execution Processes

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

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

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

Parent topic: Enterprise Server Instance Configuration Issues


Performance Considerations

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

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

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

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


I/O-bound Services

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

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

Parent topic: Performance Considerations


CPU-bound Services

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

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

Parent topic: Performance Considerations


Short-running Client Requests

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

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

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

Parent topic: Performance Considerations


Long-running Client Requests

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

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

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

Parent topic: Performance Considerations


Configuring the Server Instance Environment

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

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

[ES-Environment]
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, or to set system or COBOL run-time variables such as PATH and COBPATH. On UNIX, settings in this section are case-sensitive.

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

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

  • Configuring Environment Variables
  • Reserved Environment Variables
  • About Communications Processes
  • Configuring Fileshare
  • Using XA-compliant Resources (XARs)
Parent topic: Enterprise Server configuration and administration


Configuring Environment Variables

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

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

Tip: This section contains an alphabetical listing of environment variables, and environment variables listed by functional group. For variable values, check the alphabetical listing, and if this does not contain values, search the online help for the variable name.
  • How Enterprise Server uses Environment Variables
  • Setting Environment Variables
  • Environment Variables by Groups
  • Environment variables in alphabetical order
Parent topic: Configuring the Server Instance Environment


How Enterprise Server uses Environment Variables

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

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

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

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

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

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

The format for environment variables is:

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

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

[ES-Environment]
COBPATH=/home/adirectory:home/anotherdirectory
Note: Micro Focus recommends that you do not set the COBDIR environment variable for an enterprise server instance, especially on UNIX. This is because $COBDIR is used to point to the product location. The results of setting $COBDIR are undefined.

Use the COBPATH environment variable if you want to specify the location of service programs at the enterprise server level. If you do set the COBPATH environment variable at enterprise server level, you also need to specify "$COBPATH" in Package Path in the Add Package or Edit Package page for services that should be located using COBPATH.

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

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

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

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

FILEA=\$\$fsserver1/mydata.dat

This resolves to $$fsserver1/mydata.dat

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

Parent topic: Configuring Environment Variables


Setting Environment Variables

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

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

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

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

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


Setting Environment Variables for Micro Focus Directory Server

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

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

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

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

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


To Set Environment Variables from the User Interface

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

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

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

    Enter the information in the form:

    <variable name>=<value>

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

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

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


To Set Environment Variables from the Command Line

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

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

From the command line, set the environment variables:

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

export MF_CHARSET=EBCDIC

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

Parent topic: Setting Environment Variables


To Specify Dataset Allocation Using Environment Variables

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

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

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

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

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

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


Environment Variables by Groups

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

The following sections list the environment variables by functional group.

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


CCI Environment Variables

Lists environment variables that relate to CCI.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Generic environment variables

CCITIMEOUT

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

Syntax

CCITIMEOUT=value}
export CCITIMEOUT

Default

The default is 1200 (2 minutes).

Example
This example sets the value to 4 minutes:
SET CCITIMEOUT=2400
CCIERRLOG
Specifies the output location and filename of ccierr.log content which tracks first-instance errors reported from the operating systems. CCIERRLOG overrides any entries found in CCI.INI, where the syntax and content is explained in detail.
CCITRACE
Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

Syntax

CCITRACE=filename [options]
Parameters
  • filename The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrace.log is created in the current directory with all options set to their default states.
  • options Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless a filename any other trace option is specified, in which case it is always ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

TCP/IP specific variables

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

Syntax

CCITCP2=hostname
export CCITCP2

Parameters

hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

Comments

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, such as

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.

CCITCP2_PORT
The port that is being used for the registration process.

Syntax

CCITCP2_PORT=port
export CCITCP2_PORT
Parameters
  • port The port on which the CCITCP2 registration program operates.

Secure Connection (SSL) specific variables

RANDOM
If using SSL connections, externally generated random data that is stored as a numeric value in the RANDOM variable will be inserted into the initial salt value used to generate temporary key pairs used in SSL hand-shaking. The RANDOM value will only form part of the initial salt value and is an aid to generating more randomness and not an essential requirement.
COBSSL
If using SSL connections specifies the location of the DemoCA directory. If not found, SSLDIR is inspected instead.
SSLDIR
If using SSL connections, this value specifies the generic location of the system's OpenSSL directory.
Parent topic: Environment Variables by Groups


Database File Handling Environment Variables

The following environment variables all relate to the configuration of the database file handler, which enables you to store your data files for enterprise server applications within a supported database.

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 Native Database File Handling and Enterprise Server Region Database Management for more information.

Syntax

ES_DB_FH=value
export ES_DB_FH

Values

  • Y|y|true - file handling is directed through the Micro Focus Database File Handler (MFDBFH).
  • N|n|false - database file handler support is disabled.

Default

Database file handler support is disabled.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.

There also needs to be a corresponding <server> entry for the database server within the configuration file specified by the MFDBFH_CONFIG environment variable. <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
export ES_DB_SERVER

Values

server-instance is the name of a valid database server instance. For example, set ES_DB_SERVER=(local)\SQLEXPRESS.

Default

Not set.

Example

Using the example above, you would be required to have something similar to that below in your mfdbfh.cfg file:

<datastores>
   <server name="(local)\SQLEXPRESS" 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>
MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.

Syntax

MFDBFH_CONFIG=value
export MFDBFH_CONFIG

Values

value represents the full path and filename of your database configuration file.

Default

Not set.

MFDBFH_CONNECTION_POOLING

Specify whether database connection pooling is to be enabled or not when the database file handler is in effect.

Syntax

MFDBFH_CONNECTION_POOLING=TRUE|FALSE
export MFDBFH_CONNECTION_POOLING

Paramaters

TRUE
Connection pooling is enabled, which keeps database connections open, and then reuses them where possible in preference of creating a new connection.
FALSE
Connection pooling disabled. This setting comes at a cost to performance, as a new physical connection is established each time. You may want to disable connection pooling during testing, when databases are more frequently added and dropped: if pooling is enabled, and existing connections remain open, it may stop you from dropping that particular database.

Default

MFDBFH_CONNECTION_POOLING=TRUE

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_CONFIG=table|database
export MFDBFH_CONFIG

Paramaters

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 Database Record Locking for a list of differences for each database engine.

Default

MFDBFH_RECORD_LOCKING=table
Note: If the value of this variable is set to anything other than 'database', this default is used.
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=value
export MFDBFH_SCRIPT_DIR

Values

value represents a path to the directory containing the required resources.

Default

value defaults to the \etc\mfdbfh\scripts sub directory of your product installation directory.

Parent topic: Environment Variables by Groups


Enterprise Server Communications Environment Variables

Environment variables for configuring the input and output and the display.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
CCITCP2
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.

Syntax

CCITCP2=hostname
export CCITCP2

Parameters

hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

Comments

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, such as

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.

CCITCP2_PORT
The port that is being used for the registration process.

Syntax

CCITCP2_PORT=port
export CCITCP2_PORT
Parameters
  • port The port on which the CCITCP2 registration program operates.
CCITRACE
Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

Syntax

CCITRACE=filename [options]
Parameters
  • filename The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrace.log is created in the current directory with all options set to their default states.
  • options Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless a filename any other trace option is specified, in which case it is always ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

ES_SNATRC_DIR
Specifies the location of the SNA traces written by IMB's communication manager. You must set this environment variable before you start the region to ensure that the SNA trace files are written to a valid directory:
ES_SNATRC_DIR=path

This directory is then used to set up the SNA environment variables SNAMSG and SNATRC to appropriate values.

Parent topic: Environment Variables by Groups


File Handling and Dataset Environment Variables

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

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

COBDATA
Specifies one or more locations, separated by ; (Windows) or : (UNIX), in which to search for data files at run time. As long as the file assignment does not contain a sub-path (that is, a string containing \ or /) then the file assignment is appended to each location specified by COBDATA in order to locate the file.
Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.

Specifies the directory or directories that the run-time system is to search for data files. Provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.

Syntax

COBDATA=pathname[:pathname]...
export COBDATA
Parameters
  • A list of search directories, each item separated by a colon. The runtime system is to search these when looking for application data files. When more than one pathname is present, a null pathname represents the current working directory.

Comments

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.

Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.

Example

COBDATA=:demo:/home/data:progs
export COBDATA

causes COBDATA to be set to instruct the runtime system to search for data files in the current directory, then in the directory ./demo, then in the directory /home/data and finally in ./progs.

DB2DBDFT
The default database for the DB2 SQL precompiler to process SQL statements against.

Values

  • The location and name of the default database.
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 Native Database File Handling and Enterprise Server Region Database Management for more information.

Syntax

ES_DB_FH=value
export ES_DB_FH

Values

  • Y|y|true - file handling is directed through the Micro Focus Database File Handler (MFDBFH).
  • N|n|false - database file handler support is disabled.

Default

Database file handler support is disabled.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.

There also needs to be a corresponding <server> entry for the database server within the configuration file specified by the MFDBFH_CONFIG environment variable. <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
export ES_DB_SERVER

Values

server-instance is the name of a valid database server instance. For example, set ES_DB_SERVER=(local)\SQLEXPRESS.

Default

Not set.

Example

Using the example above, you would be required to have something similar to that below in your mfdbfh.cfg file:

<datastores>
   <server name="(local)\SQLEXPRESS" 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_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. The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file.

Syntax

ES_RLS_FILE_SUPPORT=value
export ES_RLS_FILE_SUPPORT

Values

  • Y|y - Stops dirty records being returned when a record is locked by another process.

Default

RLS file support is off.

EXTFH
Specifies a configuration file for the Callable File Handler.

Syntax

EXTFH=filename.cfg
export EXTFH

Parameters

filename.cfg The name of the configuration file.

Example

EXTFH=/home/mydir/myconfig.cfg
export EXTFH
FHREDIR
Specifies a configuration file to be used by the Fileshare Client.

Syntax

FHREDIR=filename.cfg
export FHREDIR

Parameters

filename.cfg The name of the configuration file.

Example

FHREDIR=/home/mydir/myconfig.cfg
export FHREDIR
FS

Specifies a configuration file to be used by the Fileshare Server.

Syntax

FS=filename.cfg
export FS

Parameters

filename.cfg The name of the configuration file.

Example

FS=myconfig.cfg
export FS
FSCOMMS
Specifies that the Fileshare system is to run in single user mode.

Syntax

FSCOMMS="\$local"
export FSCOMMS

Parameters

"\$local" Run the Fileshare System in single user mode.

HCOBND (deprecated)
Specifies a directory to be used for bind files generated by the DB2 External Compiler Module (ECM).
Note: 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

Parameters

pathname The directory that the DB2 ECM is to use to store bind files.

Example

SET HCOBND=/mydir/binds
export HCOBND

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.

LIB
The location of the DB2 LIB directory.
MF_CBLQDA
Determines if QSAM files are dynamically allocated when processing an OPEN I-O or OPEN EXTEND statement for an optional file (that is, a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT (regardless of whether it is optional or not). Permissible values are OFF and ON; the default is OFF, which specifies that dynamic allocation is not permitted.
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.
Note: 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.
MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.

Syntax

MFDBFH_CONFIG=value
export MFDBFH_CONFIG

Values

value represents the full path and filename of your database configuration file.

Default

Not set.

MFDBFH_CONNECTION_POOLING

Specify whether database connection pooling is to be enabled or not when the database file handler is in effect.

Syntax

MFDBFH_CONNECTION_POOLING=TRUE|FALSE
export MFDBFH_CONNECTION_POOLING

Paramaters

TRUE
Connection pooling is enabled, which keeps database connections open, and then reuses them where possible in preference of creating a new connection.
FALSE
Connection pooling disabled. This setting comes at a cost to performance, as a new physical connection is established each time. You may want to disable connection pooling during testing, when databases are more frequently added and dropped: if pooling is enabled, and existing connections remain open, it may stop you from dropping that particular database.

Default

MFDBFH_CONNECTION_POOLING=TRUE

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_CONFIG=table|database
export MFDBFH_CONFIG

Paramaters

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 Database Record Locking for a list of differences for each database engine.

Default

MFDBFH_RECORD_LOCKING=table
Note: If the value of this variable is set to anything other than 'database', this default is used.
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=value
export MFDBFH_SCRIPT_DIR

Values

value represents a path to the directory containing the required resources.

Default

value defaults to the \etc\mfdbfh\scripts sub directory of your product installation directory.

MFLOCKING
Enables Locking Support.
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.
  • 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.

Properties:

Default: OFF
IDE equivalent: None
TXFILEP
The location of Micro Focus VSAM files. This can be a location on disk or a datastore location within a database. For database-hosted files, use the notation sql://host[/instance]/datastore[?folder=/path] - see The dbfhdeploy Command Line Utility for more information.
Parent topic: Environment Variables by Groups


General Enterprise Server Environment Variables

The following environment variables are applicable to all components of Enterprise Server.

ES_CAS_API
Indicates whether casout or cassub has been executed by a call and not from the command line.
ES_CSKL_NO_MSG_CONSOLE
Stops CSKL writing messages to console.log.
ES_ESMAC_DISP_MAX_OVERRIDE
The number of items displayed in the ESMAC catalog view or lines displayed in a SYSOUT file from the job list view.
ES_LEGACY_ECI
Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG.
ES_MAX_CATALOG_LINES
Restricts the number of entries displayed in ESMAC catalog view, and the default is 5000.
ES_MEM_STRATEGY
Selects the types of memory processes supported.
ES_OTMA_TIMEOUT
The time that an OTMA client should wait for an answer.
ES_SEP_DORMANT_TIME
Allows override of Transient SEP dormant time.
ES_SERVER
Server name (used if no -r switch is specified on casstart or casstop).
ES_SYSOUT_HOLD
The status of the SYSOUT files are set to Out Hold.
ES_USR_DFLT_ESMAC
Allows you to override the default user when no user is logged on for ESMAC authentication.
ES_ESM_DISABLE_DFLTUSER_ESMAC
Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.
ES_WS_RUNAWAY_TIMEOUT
Time in seconds that the client will wait for a response from the web service. Valid values are 0 to 65535 seconds.
ISPPROF
The location of ISPF dialog profiles.
JAVA_HOME
Specifies the location of the JDK.
LANG
Specifies the locale.

Syntax

LANG=language[_territory[.codepage]]
export LANG
Parameters
  • language The language in which your program is to run.
  • _ (underscore) The delimiter for language and territory, if territory is specified.
  • territory The country in which your program is to run.
  • . (period) The delimiter for territory and codepage, if codepage is specified.
  • codepage The character set to use for your program.

Example

LANG=fr_FR
export LANG
LINES
Specifies the depth of the terminal screen or window, overriding the specified terminal default.

Syntax

LINES=n
export LINES

Parameters

n The depth of the terminal screen or window, in lines.

Comments

The default, when LINES is unset or null, is to use the lines value as defined in the specified terminal's terminfo entry, or the current depth of the terminal window if you are using X windows. The terminal type is specified via the standard UNIX environment variable, TERM.

On non-windowing environments, where the terminal screen area cannot be resized, the LINES values does not need to be set.

In windowing environments, where the size of windows can be changed, the initial size of the window is used in preference to the lines value in terminfo. When the window is resized, the new size is reread. If the new size is greater than the initial size then the extra lines might not be used.

If you want to use the full depth of the window you might need to set LINES to the current depth of the window on some platforms.

Using LINES values that do not correspond to the actual depth of the window produces unexpected results.

Example

LINES=50
export LINES
LD_LIBRARY_PATH

Specifies the directory or directories for the UNIX system, cob command, and the run-time system to search for shared libraries and callable shared objects. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib on all platforms except AIX (which uses LIBPATH). It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LD_LIBRARY_PATH=pathname[:pathname]...
export LD_LIBRARY_PATH
Parameters

pathname A path or a list of paths, each separated by a colon (:).

Comments

The list of directories must include $COBDIR/lib. The COBDIR environment variable is described earlier.

This environment variable is a system environment variable? see your UNIX documentation for more information.

Example

LD_LIBRARY_PATH=$COBDIR/lib:/home/mydir/myapp:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
LIBPATH
Specifies the directory or directories for the UNIX system, Cob and the runtime system to search for shared libraries and callable shared objects. It is only available on AIX-based systems. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib. It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LIBPATH=pathname[:pathname]...
export LIBPATH

Parameters

pathname A directory to search for shared libraries.

Example

LIBPATH=$COBDIR/lib:/lib:/usr/lib
MAINFRAME_FLOATING_POINT
Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.

Syntax

MAINFRAME_FLOATING_POINT=fpstatus
export MAINFRAME_FLOATING_POINT

Parameters

fpstatus Which format to use for floating point data items. This must be one of:

  • true Specifies that IBM hexadecimal format floating point data items are to be used.
  • false Specifies that IEEE format floating point data items are to be used.

Setting MAINFRAME_FLOATING_POINT to anything other than true has the same effect as setting it to false.

The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_AMODE31ONLY
Indicates that all programs are AMODE(31).
MF_CHARSET
Specifies the system character set (ASCII or EBCDIC).
MF_USESCA5
Specifies that the server should use version 5 of the Open Service Component Architecture.
Values:
  • ON (Default)
  • OFF
MFCODESET
Specifies which translation tables to use.
Values
  • A pre-defined country code:
    Important: To specify a Euro codeset, meaning that it includes the Euro symbol (€), prefix an "E" to the appropriate country code listed below. A country code with no "E" prefix indicates a non-Euro code.

    Country Code

    (MFCODESET)

            EBCDIC CCSIDs Language
    AUTOMATIC

    AUTO

            Operating system default - sets country code based on CBL_GET_OS_INFO
    DEFAULT | For a single-byte character set environment, 0437 (US English) selected; else 0081 (Japanese Katakana Extended) selected.
    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
    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 conversion. 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.

    Other EBCDIC CCSIDs in parentheses reflect a 'non-Euro, Euro' pair for appropriate country codes.

    For database applications accessing a UNIX database created with single-byte character sets 819 or 923, use the following table:
    Country Code

    (MFCODESET)

            EBCDIC CCSIDs Languages
    1140 | 37,1140 | Dutch US English Portuguese
    1141 | 273,1141 | German (Austrian) German
    1142 | 277,1142 | Danish Norwegian
    1143 | 278,1143 | Swedish Finnish
    1144 | 280,1144 | Italian
    1145 | 284,1145 | Spanish
    1146 | 285,1146 | UK English
    1147 | 297,1147 | French
    1148 | 500,1148 | International (Latin 1)
MFCSCFG
Specifies a configuration file to be used by the Client/Server Binding client program.

Syntax

MFCSCFG=filename
export MFCSCFG

Parameters

filename The name of the configuration file.

Example

MFCSCFG=/home/mydir/mfclisrv.cfg
export MFCSCFG

Comments

The value of MFCSCFG is overridden by any value defined in the command line. If neither of the above yields a filename, the default filename mfclisrv.cfg is assumed, and is searched for in the current directory. If that in turn is not found, the default settings for the configuration entries are used.

MFEXTMAP
Location of a mapper file.
MFLOGDIR
Specifies a directory to be used by Client/Server Binding for log files.

Syntax

MFLOGDIR=dirname
export MFLOGDIR

Parameters

dirname The name of the directory for log files.

Example

MFLOGDIR=/home/mydir/logs
export MFLOGDIR
MFLECONFIG

Specifies a configuration file for Language Environment (LE) runtime options.

Syntax

MFLECONFIG=filename
export MFLECONFIG

Parameters

filename The file containing the LE runtime options you want to use.

MFPRELOAD_USE
Calls MFPRELOAD to improve perfomance.
MFSUB
Specifies whether to use SUBI or ASUBI.
MFSYSCATDIR
The location of the system catalog directory.
MFUSER
Default user ID.
MFUSERCAT_LOC
The fully-qualified name of the SMS dataset.
MQSERVER
The location of an WebSphere MQ Server installation.
MULTMFENTMAP
Specifies whether special characters such as < and & are replaced with the equivalent HTML entities (for example &lt; and &amp;).
OOSW
OO run-time switches.
PATH

Specifies the directories to be searched by all UNIX programs, including the runtime system, when finding executables to be run.

Syntax

PATH=pathname[:pathname]...
export PATH

Parameters

pathname A directory to search for executables.

Example

PATH=$COBDIR/bin:$PATH
export PATH
TERM
Defines the type of terminal being used.

Syntax

TERM=name
export TERM

Parameters

name The name of the terminal in the terminfo database.

Example

TERM=at386
export TERM
TERMINFO

Specifies the directory to be searched by all UNIX programs, including the runtime system, for the UNIX system terminfo database.

Syntax

TERMINFO=pathname
export TERMINFO

Parameters

pathname The name of a directory that contains the UNIX system terminfo database.

Comments

The UNIX system terminfo database is used by all UNIX applications that need to use a terminal. However, COBOL applications tend to make much fuller and sophisticated use of the terminal and require a fuller terminfo description than is required by typical UNIX applications such as vi. Some terminal capabilities, such as those set during the initialization of the terminal to control the use of function keys, commonly conflict with the needs of typical COBOL applications. In such cases, the terminal information required by COBOL can be stored in a separate terminfo database and referenced using COBTERMINFO.

TMPDIR
Specifies a directory in which to store temporary files in place of the UNIX system default.

Syntax

TMPDIR=pathname
export TMPDIR

Parameters

pathname The directory used by UNIX applications for any temporary work files. Temporary work files can be created by COBOL utilities such as Cob or by the runtime system when it executes statements such as SORT. If you do not specify a directory, the system default directory is used.

Comments

You might need to use this environment variable if the runtime system needs to page data to disk when creating heaps or sorting.

USER
Default user name.
Parent topic: Environment Variables by Groups


Input, output and display environment variables

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

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

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

Syntax

CCITCP2=hostname
export CCITCP2

Parameters

hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

Comments

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, such as

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.

CCITCP2_PORT
The port that is being used for the registration process.

Syntax

CCITCP2_PORT=port
export CCITCP2_PORT
Parameters
  • port The port on which the CCITCP2 registration program operates.
CCITRACE
Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

Syntax

CCITRACE=filename [options]
Parameters
  • filename The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrace.log is created in the current directory with all options set to their default states.
  • options Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless a filename any other trace option is specified, in which case it is always ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

COBAIF

Specifies the directory path that Animator is to search for the session (.aif) file for the program being animated, if it is not found in the same directory as the information (.idy) file. Animator can update the session file to record information held between sessions. The .aif file contains details of breakpoints and monitors.

Syntax

COBAIF=pathname
export COBAIF

Parameters

  • A list of search directories, each item separated by a colon. The path where the .aif files are located.

Comments

If the .aif file is not found in the directory specified, a search is made of the directories specified by the COBIDY environment variable. If the file is still not found, the current directory is searched.

If an .aif file does not exist, Animator creates it as follows:

  • If COBAIF is set, the .aif file is created in the first directory specified by COBAIF
  • If COBAIF is not set, the .aif file is created in the directory specified in the environment variable COBIDY from which the program .idy file was loaded
  • If COBAIF and COBIDY are not set, or if the first directory specified by COBIDY is not found, the .aif file is created in the current directory
COBAIFNAME

Specifies the basename of the Animator session file (.aif ) for the program being animated. The .aif file contains details of breakpoints and monitors.

Syntax

COBAIFNAME=basename
export COBAIFNAME

Parameters

  • Basename The basename of the .aif files.

Comments

You need to specify this environment variable if you are starting Animator using COBSW=+A and you want to save breakpoints for subsequent animation sessions. You can also specify it if you are starting Animator using the command anim? in this case the basename you specify overrides the application name as the basename of the .aif file.

COBATTR

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

Syntax

COBATTR=n
export COBATTR

Parameters

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

  • 0

    Provides standard, default behavior.

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

  • 1

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

  • 2

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

  • 3

    As for 1 and 2 above

  • 4

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

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

Example

COBATTR=1
export COBATTR
COBCONFIG

Specifies a run-time configuration file that tailors the run-time configurable options in some way.

Syntax

COBCONFIG=pathname
export COBCONFIG

Parameters

  • pathname The name of the COBOL configuration file that tailors the runtime

Comments

If $COBCONFIG is not set then the file $COBDIR/etc/cobconfig is searched for instead.

Example

COBCONFIG=/home/mydir/cobconfig
export COBCONFIG
COBCONFIGJVM
Specifies a Java properties file that tailors the run-time configurable options for Java Virtual Machine applications. Use this instead of COBCONFIG in COBOL applications intended for use on a Java Virtual Machine.

Values

  • The location of a properties file.
COBCONFIG.BLOCK
The location of the application configuration file.
COBDIR

Specifies the directory where the required Micro Focus COBOL system is installed. Many of the COBOL system components and utilities require and use this information. If the COBDIR environment variable is not set then the COBOL system acts as if it had been set to the default COBOL system directory. This default directory is /opt/microfocus/VisualCOBOL on UNIX systems.

Syntax
COBDIR=pathname
export COBDIR

Parameters

  • pathname The directory that contains the required Micro Focus COBOL system software.

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

COBDIR=/home/products/cobse20
export COBDIR

This causes the Cob utility to search the directory /home/products/cobse20 for the Micro Focus COBOL system software.

COBKEYTIMEOUT

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

When a terminal key is depressed, the terminal might send in response a single character or a group of characters to the runtime 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 runtime 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 runtime system in discrete packets, then the network can alter the intervals between each character arriving at the runtime system. COBKEYTIMEOUT is available to help compensate for typical network delays so the runtime system identifies escape sequences correctly.

Syntax

COBKEYTIMEOUT=n
export COBKEYTIMEOUT

Parameters

n 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 runtime system over the line or network connection. On encountering a lone Escape character, the runtime system waits n tenths of a second before assuming that the character does not introduce an escape sequence. The runtime system calculates an appropriate default value for n from the baud rate of the terminal.

COBLANG
The language environment in which your COBOL program runs.
Values
  • A COBOL language environment (LE) value.
COBLPFORM
This configuration variable is used to define and print to printer channels C01-C12. Specify the line numbers for each channel with the COBLPFORM configuration variable. Null entries are ignored. Those channels that have line number zero, function-names S01-S052, CSP, or are undefined, are set to line 1.

Example 1:

COBLPFORM 1:3:5:7:9:11:13:15:17:19:21:23

In this example C01 equals 1, C02 equals 3, and so on.

Example 2:

COBLPFORM :3::5: :9

In this example, C01 equals 3, C02 equals 5, C03 equals 1, and C04 equals 9. You can specify only a single line number for each channel.

In example 2 above, channels C05 - C12 are undefined. If a print statement specifies channel C05 - C12, the line is printed at line 1. In addition, in the example shown, C03 equals 1 because its value is a space and therefore undefined.

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.

COBMAINSTACK

Specifies the size of the main stack.

Syntax

COBMAINSTACK=n
export COBMAINSTACK

Parameters

n A number in the range 1 through nnn that represents the size of the main stack.

Comments

You might need to set COBMAINSTACK in any of the following circumstances:

  • If you are deploying 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

COBMODE
Describes whether to start the server in 32-bit or 64-bit mode.

Syntax

COBMODE=mode;
export COBMODE

Parameters

mode = 32 or 64.

Example

COBMODE=32;
export COBMODE
COBOPT
Specifies user default options to the Cob utility.

Syntax

COBOPT="[set environment-variable=value]
[options] ...
[cobextn: .ext [.ext] ... ]"
export COBOPT

or

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

If a line does not begin with one of the identifiers set or cobextn: then it is taken as an options line.

Comments

COBOPT can either contain options that supplement or override the system default options defined in $COBDIR/etc/cobopt, or it can specify the path of a file that contains such options. The options can extend over more than one line and each line must have the same format as described for the file $COBDIR/etc/cobopt in the chapter COBOL System Interface (cob).

Examples

COBOPT="CANS85
set COBCPY=$COBDIR/srclib/:$HOME/mylib:"
export COBOPT

This enables ANSI 85 standard COBOL syntax and sets COBCPY to the specified list of paths.

COBOPT=temp/options

Specifies that cob options are contained in the file options in the directory temp.

COBPATH

Specifies the directory or directories that the runtime system is to search for dynamically loadable .int and .gnt files, or callable shared objects.

Syntax

COBPATH=pathname[:pathname]...
export COBPATH

Parameters

pathname A list of search directories, each item separated by a colon, that the runtime system is to search for a dynamically loadable program (.int, .gnt or callable shared object) file. When more than one pathname is specified, a null pathname represents the current working directory.

Example

COBPATH=u:/home/mydir/srclib:otherlib
export COBPATH
COBPRFDIR
Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Values
  • A list of search directories, each item separated by a colon.
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
export COBPRINTER

Parameters

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

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"
export COBPRINTER
COBSES

Specifies the UNIX Session Recorder functions to perform.

Syntax

COBSES={option[filename]}...
export COBSES
Parameters

option can be one or more of the following:

  • -a Include keystrokes made to and screen output from the Animator
  • -f filename Play back recording in fast forward mode
  • -p filename Play back recording in filename at normal speed
  • -r filename Record keystrokes
  • -s filename Record screen output
  • -t terminal number Indicate terminal number for multi-user screen recordings

These flags are all case sensitive. Also, you cannot combine the -r flag with either -f or -p.

Note: You must unset COBSES when you have finished using the UNIX Session Recorder, or it will interfere with the running of your COBOL programs. To do this, set COBSES to spaces, then export this setting to the shell.
COBSW
Specifies the run-time system switch settings for the run-time system to observe when running an application.

Syntax

COBSW=[+/-}s...
export COBSW
Parameters

A list of the runtime switches to set or unset.

  • + sets a switch.
  • - un-sets a switch.

Example

COBSW=+0+D
export COBSW

This enables runtime switch 0 and the ANSI COBOL debug switch.

COBTERMINFO
Specifies the directory or directories to be searched by the runtime system for a terminfo database of terminal information tailored to the needs of COBOL applications. This enables COBOL applications to use different terminfo settings to those used by non-COBOL applications, such as vi, when using the same terminal.
Syntax
COBTERMINFO=pathname[:pathname]...
export COBTERMINFO

Parameters

pathname A list of search directories, each item separated by a colon, that identify a terminfo database containing terminal settings tailored for COBOL applications. A null pathname represents the current working directory.

Comments

The COBOL system takes the value of the standard UNIX environment variable TERM as the name of the terminal in use. It uses this to search for the appropriate terminal information in a terminfo database. The runtime system first searches the databases identified in COBTERMINFO and then, if the terminal information is not found it searches the database identified in the standard UNIX environment variable TERMINFO.

If COBTERMINFO is not set, the runtime system acts as if it had been set to $COBDIR/terminfo.

Micro Focus recommend that the first directory listed in COBTERMINFO is $COBDIR/terminfo so that the terminfo database supplied with this COBOL system is found first. For commonly used terminals this terminfo contains settings that are fuller and more appropriate to COBOL than those normally available in the UNIX system terminfo database. When debugging using Animator, COBTERMINFO must be set to $COBDIR/terminfo.

COBTERMINFO can also be used to identify a terminfo database that is portable between UNIX systems. Such a database conforms to the standard UNIX database format but does not include any supplementary, UNIX implementation-dependent terminal information. Many UNIX system terminfo databases are not portable because they include such supplementary information. The COBOL system ignores any such nonportable details.

Example

COBTERMINFO=$COBDIR/terminfo:/home/mydir/terms
export COBTERMINFO
COLUMNS

Specifies the column width of the terminal screen or window, overriding the specified terminal default.

Syntax

COLUMNS=n
export COLUMNS

Parameters

n The width of the terminal screen or window, in column positions.

Comments

The default, when COLUMNS is unset or null, is to use the cols value defined in the specified terminal's terminfo entry, or the current width of the terminal window if you are using an X terminal. The terminal type is specified using the standard UNIX environment variable, TERM.

On non-windowing environments, where the terminal screen area cannot be resized, the COLUMNS values does not need to be set. Terminals that can switch into a wide mode (usually from 80 through 132 columns) have a terminal name ending in "w" and these are automatically supported, without the need to set COLUMNS.

In windowing environments, where the size of windows can be changed, the initial size of the window is used in preference to the cols value in terminfo. When the window is resized, the new size is reread. If the new size is greater than the initial size then the extra columns might not be used.

If you want to use the full width of the window you might need to set COLUMNS to the current column width of the window on some platforms.

Using COLUMNS values that do not correspond to the actual width of the window produces unexpected results.

Example

COLUMNS=100
export COLUMNS
ES_CAS_API
Indicates whether casout or cassub has been executed by a call and not from the command line.
Syntax
ES_CAS_API=value
export ES_CAS_API
Values
  • ON The utility has been invoked by a call, and messages will not be sent to the console or command line.
Default

The utility will attempt to log messages.

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
export ES_ESMAC_DISP_MAX_OVERRIDE
Value
  • An integer number denoting how many lines to display. The maximum number is 99999.
Default
10000
ES_MAX_CATALOG_LINES
Restricts the number of entries displayed in ESMAC catalog view.
Syntax
ES_MAX_CATALOG_LINES=number
export ES_MAX_CATALOG_LINES
Values
  • number The number of lines to display. The maximum is 99999.
Default
The default is 5000.
ES_MEM_STRATEGY
Selects the types of memory processes supported.
Note: Note that memory strategy can also be set via the memory_strategy runtime tunable.
ES_OTMA_TIMEOUT
The time in seconds that an OTMA client should wait for an answer. The default value is 120.
Syntax
ES_OTMA_TIMEOUT=seconds
export ES_OTMA_TIMEOUT
Values
  • seconds - The number of seconds to wait. The maximum is 43199.
Default
120 seconds.
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 the period of inactivity to be controlled.

Syntax

ES_SEP_DORMANT_TIME=seconds
export ES_SEP_DORMANT_TIME

Values

  • seconds Number of seconds' inactivity.

Default

Transient SEPs are terminated after 2 seconds of inactivity.

ES_SERVER
The default server name (used if no -r switch is specified on casstart or casstop).

Syntax

ES_SERVER=name
export ES_SERVER

Values

  • name The server name.

Default

ESDEMO/ESDEMO64

ES_SYSOUT_HOLD
The status of the SYSOUT files are set to Out Hold.
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=user
export ES_USR_DFLT_ESMAC

Values

  • user - the default user name.

Default

mfuser

ES_ESM_DISABLE_DFLTUSER_ESMAC
Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.

Syntax

ES_ESM_DISABLE_DFLTUSER_ESMAC=value
export ES_ESM_DISABLE_DFLTUSER_ESMAC

Values

  • Y|y - Default ESMAC user is disabled.

Default

Default ESMAC user is not disabled.

ISPPROF
The location of ISPF dialog profiles.
JAVA_HOME
Specifies the location of the JDK.
LANG
Specifies the locale.

Syntax

LANG=language[_territory[.codepage]]
export LANG
Parameters
  • language The language in which your program is to run.
  • _ (underscore) The delimiter for language and territory, if territory is specified.
  • territory The country in which your program is to run.
  • . (period) The delimiter for territory and codepage, if codepage is specified.
  • codepage The character set to use for your program.

Example

LANG=fr_FR
export LANG
LINES
Specifies the depth of the terminal screen or window, overriding the specified terminal default.

Syntax

LINES=n
export LINES

Parameters

n The depth of the terminal screen or window, in lines.

Comments

The default, when LINES is unset or null, is to use the lines value as defined in the specified terminal's terminfo entry, or the current depth of the terminal window if you are using X windows. The terminal type is specified via the standard UNIX environment variable, TERM.

On non-windowing environments, where the terminal screen area cannot be resized, the LINES values does not need to be set.

In windowing environments, where the size of windows can be changed, the initial size of the window is used in preference to the lines value in terminfo. When the window is resized, the new size is reread. If the new size is greater than the initial size then the extra lines might not be used.

If you want to use the full depth of the window you might need to set LINES to the current depth of the window on some platforms.

Using LINES values that do not correspond to the actual depth of the window produces unexpected results.

Example

LINES=50
export LINES
LD_LIBRARY_PATH

Specifies the directory or directories for the UNIX system, cob command, and the run-time system to search for shared libraries and callable shared objects. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib on all platforms except AIX (which uses LIBPATH). It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LD_LIBRARY_PATH=pathname[:pathname]...
export LD_LIBRARY_PATH
Parameters

pathname A path or a list of paths, each separated by a colon (:).

Comments

The list of directories must include $COBDIR/lib. The COBDIR environment variable is described earlier.

This environment variable is a system environment variable? see your UNIX documentation for more information.

Example

LD_LIBRARY_PATH=$COBDIR/lib:/home/mydir/myapp:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
LIBPATH
Specifies the directory or directories for the UNIX system, Cob and the runtime system to search for shared libraries and callable shared objects. It is only available on AIX-based systems. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib. It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LIBPATH=pathname[:pathname]...
export LIBPATH

Parameters

pathname A directory to search for shared libraries.

Example

LIBPATH=$COBDIR/lib:/lib:/usr/lib
MAINFRAME_FLOATING_POINT
Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.

Syntax

MAINFRAME_FLOATING_POINT=fpstatus
export MAINFRAME_FLOATING_POINT

Parameters

fpstatus Which format to use for floating point data items. This must be one of:

  • true Specifies that IBM hexadecimal format floating point data items are to be used.
  • false Specifies that IEEE format floating point data items are to be used.

Setting MAINFRAME_FLOATING_POINT to anything other than true has the same effect as setting it to false.

The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_AMODE31ONLY
Indicates that all programs are AMODE(31).
MF_CHARSET
Specifies the system character set (ASCII or EBCDIC).
MF_USESCA5
Specifies that the server should use version 5 of the Open Service Component Architecture.
Values:
  • ON (Default)
  • OFF
MFCODESET
Specifies which translation tables to use.
Values
  • A pre-defined country code:
    Important: To specify a Euro codeset, meaning that it includes the Euro symbol (€), prefix an "E" to the appropriate country code listed below. A country code with no "E" prefix indicates a non-Euro code.

    Country Code

    (MFCODESET)

            EBCDIC CCSIDs Language
    AUTOMATIC

    AUTO

            Operating system default - sets country code based on CBL_GET_OS_INFO
    DEFAULT | For a single-byte character set environment, 0437 (US English) selected; else 0081 (Japanese Katakana Extended) selected.
    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
    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 conversion. 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.

    Other EBCDIC CCSIDs in parentheses reflect a 'non-Euro, Euro' pair for appropriate country codes.

    For database applications accessing a UNIX database created with single-byte character sets 819 or 923, use the following table:
    Country Code

    (MFCODESET)

            EBCDIC CCSIDs Languages
    1140 | 37,1140 | Dutch US English Portuguese
    1141 | 273,1141 | German (Austrian) German
    1142 | 277,1142 | Danish Norwegian
    1143 | 278,1143 | Swedish Finnish
    1144 | 280,1144 | Italian
    1145 | 284,1145 | Spanish
    1146 | 285,1146 | UK English
    1147 | 297,1147 | French
    1148 | 500,1148 | International (Latin 1)
MFCSCFG
Specifies a configuration file to be used by the Client/Server Binding client program.

Syntax

MFCSCFG=filename
export MFCSCFG

Parameters

filename The name of the configuration file.

Example

MFCSCFG=/home/mydir/mfclisrv.cfg
export MFCSCFG

Comments

The value of MFCSCFG is overridden by any value defined in the command line. If neither of the above yields a filename, the default filename mfclisrv.cfg is assumed, and is searched for in the current directory. If that in turn is not found, the default settings for the configuration entries are used.

MFEXTMAP
Location of a mapper file.
MFLOGDIR
Specifies a directory to be used by Client/Server Binding for log files.

Syntax

MFLOGDIR=dirname
export MFLOGDIR

Parameters

dirname The name of the directory for log files.

Example

MFLOGDIR=/home/mydir/logs
export MFLOGDIR
MFLECONFIG

Specifies a configuration file for Language Environment (LE) runtime options.

Syntax

MFLECONFIG=filename
export MFLECONFIG

Parameters

filename The file containing the LE runtime options you want to use.

MFPRELOAD_USE
Calls MFPRELOAD to improve performance.
MFSUB
Specifies whether to use SUBI or ASUBI.
Values
  • SUBI
  • ASUBI
MFSYSCATDIR
The location of the system catalog directory.
MFUSER
The default User ID.
MQSERVER
The location of a WebSphere MQ Server installation.
MULTMFENTMAP
Specifies whether special characters such as < and & are replaced with the equivalent HTML entities (for example &lt; and &amp;).
OOSW
OO run-time switches.
PATH

Specifies the directories to be searched by all UNIX programs, including the runtime system, when finding executables to be run.

Syntax

PATH=pathname[:pathname]...
export PATH

Parameters

pathname A directory to search for executables.

Example

PATH=$COBDIR/bin:$PATH
export PATH
TERM
Defines the type of terminal being used.

Syntax

TERM=name
export TERM

Parameters

name The name of the terminal in the terminfo database.

Example

TERM=at386
export TERM
TERMINFO

Specifies the directory to be searched by all UNIX programs, including the runtime system, for the UNIX system terminfo database.

Syntax

TERMINFO=pathname
export TERMINFO

Parameters

pathname The name of a directory that contains the UNIX system terminfo database.

Comments

The UNIX system terminfo database is used by all UNIX applications that need to use a terminal. However, COBOL applications tend to make much fuller and sophisticated use of the terminal and require a fuller terminfo description than is required by typical UNIX applications such as vi. Some terminal capabilities, such as those set during the initialization of the terminal to control the use of function keys, commonly conflict with the needs of typical COBOL applications. In such cases, the terminal information required by COBOL can be stored in a separate terminfo database and referenced using COBTERMINFO.

TMPDIR
Specifies a directory in which to store temporary files in place of the UNIX system default.

Syntax

TMPDIR=pathname
export TMPDIR

Parameters

pathname The directory used by UNIX applications for any temporary work files. Temporary work files can be created by COBOL utilities such as Cob or by the runtime system when it executes statements such as SORT. If you do not specify a directory, the system default directory is used.

Comments

You might need to use this environment variable if the runtime system needs to page data to disk when creating heaps or sorting.

USER
Default user name.
Parent topic: Environment Variables by Groups


WebSphere MQ-Specific Environment Variables

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

ES_MQ_1PC
Indicates whether the IBM WebSphere MQ switch module ESMQXA should operate in one-phase commit mode. Set this environment variable only when advised to do so by Micro Focus.

Syntax

ES_MQ_1PC=value
export ES_MQ_1PC

Values

  • Y|y|T - ESMQXA operates in one-phase commit mode.

Default

By default ESMQXA does not operate in one-phase commit mode.

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= fully_qualified_library
export ES_MQ_LIB

Values

  • fully_qualified_library - A fully-qualified library name.

Default

By default ES will try to locate libraries in the default location for the platform.

Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_T
The full name including the path of the IBM WebSphere MQ client or server library, for threaded environments. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_T= fully_qualified_library
export ES_MQ_LIB_T

Values

  • fully_qualified_library - A fully-qualified threaded library name.

Default

By default ES will try to locate threaded libraries in the default location for the platform.

ES_MQ_LIB_XA
The full name including the path of the IBM WebSphere MQ XA library. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_XA= fully_qualified_library
export ES_MQ_LIB_XA

Values

  • fully_qualified_library - A fully-qualified library name.

Default

By default ES will try to locate libraries in the default location for the platform.

Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_XA_T
The full name including the path of the IBM WebSphere MQ XA library, for threaded environments. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_XA_T= fully_qualified_library
export ES_MQ_LIB_XA_T

Values

  • fully_qualified_library - A fully-qualified threaded library name.

Default

By default ES will try to locate threaded libraries in the default location for the platform.

ES_MQ_LISTENER (deprecated)
Defines one or more WebSphere MQ listeners.
Note: ES_MQ_LISTENER is deprecated, and provided for backward compatibility only. We recommend that you use MFDS configuration instead.

Syntax

ES_MQ_LISTENER={QueueManagerName,QueueName,ListenerName}
[,QueueManagerName,QueueName,ListenerName}...
export ES_MQ_LISTENER
Values

QueueManagerName,QueueName,ListenerName - the characteristics of the listener being defined.

Default

By default, no WebSphere MQ listeners are defined.

ES_MQ_XA
The type of XA structure to use for the two-phase commit XA switch module.

Syntax

ES_MQ_XA=value
export ES_MQ_XA
Values
  • D: use a dynamic XA structure
  • S: use a static XA structure

Default

By default, a dynamic XA structure is used.

MQSERVER
The name of a minimal channel.
Values
MQSERVER=ChannelName/TransportType/MachineName(Port)
where:
  • ChannelName specifies the name of a channel as defined on the server
  • TransportType specifies the communications protocol, which can be:
    • TCP
    • LU62
    • NETBIOS
    • SPX
  • MachineName(Port) specifies the name of the server machine and optional port number
Example:
MQSERVER=CHANNEL3/TCP/QServer(1414)
Important: If you have defined MQ as an XA resource, then the values used in this environment variable must also be contained in the XA open string. See XAR for WebSphere MQ for more information.

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

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


Security and Auditing Environment Variables

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

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

ES_CESN_NO_OS390
Overrides the default behaviour CESN transaction response for invalid user credentials. Default behaviour reports "Your userid is invalid" or "Your password is invalid".
Syntax
ES_CESN_NO_OS390=value
export CESN_NO_OS390
Values
  • Setting this variable to any value causes CESN to produce an invalid credential message instead of a specific invalid user or invalid password message.
Default

Specific invalid user/password messages will be produced.

ES_DISABLE_DFLTUSR_SIGNON
Disables the default user ("mfuser") signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=value
export ES_DISABLE_DFLTUSR_SIGNON
Values
  • Y or y Having logged on to ES administration via your MFDS internal security account, you no longer receive the auto logon as "mfuser" when accessing ESMAC.
Default
If this is not set, mfuser will be used as the default user to sign in to ESMAC.
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=value
export ES_OLD_SEC_TSTD
Values
  • Any value.
Default
By default security is enforced for TS or TD queues that are not declared in the security repository.
MF_ROOT_CERT
Enables the MF Directory Server process and any client applications to pick up the value of the root certificate file.
MFAUDIT_LOGS
The location of audit files.
Parent topic: Environment Variables by Groups


SORT Engine Environment Variables

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

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

MFJSENGINE
Specifies which sort engine the utility MFJSORT is to emulate.

Syntax

MFJSENGINE=value
export MFJSENGINE
Values:
  • DFSORT Emulates DFSORT
  • SYNCSORT Emulates SYNCSORT

Example

Default

The default is DFSORT.

MFJSTATS

For a COBOL sort not running under mainframe emulation, 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.

If you are performing a COBOL sort using mainframe emulation, you can create a statistics report by modifying the JCL statement.

Syntax

MFJSTATS=switch
export MFJSTATS

Parameters

switch Switches report creation ON or OFF. The default is OFF.

SORTCOMPRESS
Tells the system whether or not to execute a compression routine on each record to be sorted.

Syntax

SORTCOMPRESS=5
export SORTCOMPRESS

Parameters

5 This is the only value that you can supply. It allows for run-length encoding of sort records, resulting in much better performance when records contain multiple repeated characters.

Comments

This variable is recommended if the sort records contain many single repeated characters, for example, multiple spaces, as it can be very effective in improving memory usage and therefore sort performance.

Example

SORTCOMPRESS=5
export SORTCOMPRESS
SORTSCHEME
Activates a sortscheme. Use in conjunction with SORTSPACE for improved performance.

Syntax

SORTSCHEME=1
export SORTSCHEME
Values
  • SORTSCHEME=1 - this is the only valid value for the environment variable. See SORTSPACE for more information.
SORTSPACE
The amount of memory to be allocated to internal workspace for SORT operations. This can be specified in different formats: for example, you could specify 64M, 2G, and 1000000 to give sort memory areas of 64 Megabytes, 2 Gigabytes and 1000000 bytes respectively.

Syntax

SORTSPACE=n[K|k|M|m|G|g]
export SORTSPACE

Parameters

n[K|k|M|m|G|g The amount of memory to be allocated to internal workspace for SORT operations. K or k indicates kilobytes, M or m indicates megabytes and G or g indicates gigabytes. No letter indicates bytes. Defaults to 1 megabyte.

Comments

A larger value for SORTSPACE will generally result 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 will be degraded.

Example

SORTSPACE=1024K
export SORTSPACE

SORTTEMPSPACE
Specifies the amount of memory to be allocated to temporary workspace for SORT operations.

Syntax

SORTTEMPSPACE=n[K|k|M|m|G|g]
export SORTTEMPSPACE

Parameters

n[K|k|M|m|G|g] The amount of memory to be allocated to temporary workspace for SORT operations. K or k indicates kilobytes, M or m indicates megabytes and G or g indicates gigabytes. No letter indicates bytes. 32 megabytes is the lowest amount of memory that can be allocated.

Comments

The memory allocation strategy used by SORT can be adjusted through use of SORTTEMPSPACE, which generally improves performance in systems suffering from memory fragmentation.

Example

SORTTEMPSPACE=250MB
export SORTTEMPSPACE
SORTTYPE
Defines the sort type.

Syntax

SORTTYPE=2
export SORTTYPE
Values
  • SORTTYPE=2 Forces SORT to use the file handler, so that format modifications are picked up from the extfh.cfg file.
  • Not setting this variable means that SORT will try to use CBL_ routines to read and write files to improve performance.
Note: 2 is the only valid value for this environment variable.
Parent topic: Environment Variables by Groups


Tracing and Debugging Environment Variables

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

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

CCITRACE
Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

Syntax

CCITRACE=filename [options]
Parameters
  • filename The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrace.log is created in the current directory with all options set to their default states.
  • options Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless a filename any other trace option is specified, in which case it is always ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

COBANIMOPT

Specifies additional directives to be used by Character Animator.

Syntax

COBANIMOPT=directive-list
export COBANIMOPT

Parameters

  • directive-list A directive, or list of directives. Must not be a filename.

Comments

When you invoke Character Animator, it first reads the directives you have specified in COBANIMOPT and then uses any directives you specify in the command line (which might override some of the directives you set in COBANIMOPT).

Example

COBANIMOPT="MIXEDLANGDEBUG MULTITHREAD"
export COBANIMOPT
COBANIMSRV

Identifies which COBOL program a waiting Character Animator process should attach to.

Syntax

COBANIMSRV=progid
export COBANIMSRV

Parameters

  • progid An identifier that is used to identify the program to which Character Animator will attach.

Comments

This environment variable is particularly useful for starting cross-session debugging.

Example

In one console session:

export COBANIMSRV=myid

myid is now a unique identifier that you can use to match Character Animator to a program. Type the command to start Character Animator:

cobanimsrv

The Character Animator waits for a COBOL program to start that has a matching identifier. In another console session:

export COBANIMSRV=myid
cobrun prog1.int

When prog1.int starts, the unique identifier myid matches that of Character Animator? therefore, Character Animator attaches to this process. In console session 1, the Character Animator main screen is displayed and the cursor placed on the first line of prog1.int.

COBIDY

Specifies the directory that Animator is to search for the information (.idy) file for the program being animated if it is not found in the same directory as the intermediate code (.int) file. Animator can update the information file to record information held between sessions.

Syntax

COBIDY=pathname
export COBIDY
Parameters
  • pathname A list of search directories, each item separated by a colon.
ES_DDBG_PORT_RANGE
A range of ports to use for dynamic debugging.
You specify a range of port numbers separated by a hyphen or a comma; the second port number must be greater than the first.
Syntax
ES_DDBG_PORT_RANGE=value
export ES_DDBG_PORT_RANGE
Values
  • low_port-high_port
Default
If this is not set, dynamic debugging will use random ports.

Example

ES_DDBG_PORT_RANGE=8001-8040
MFTRACE_ANNOTATIONS
The location of the trace files.
MFTRACE_CONFIG
The location of the CTF configuration file.
MFTRACE_LOGS
The location of the CTF log files.
MFTSO_DEBUG
Controls the display of debug messages.
TX_MQTRACE
Enables tracing in dfh0mqis for WebSphere MQ calls.
Parent topic: Environment Variables by Groups


Reserved Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
These variables are for Micro Focus use only and must not be set unless advised to do so by Micro Focus SupportLine.
APPCLLU | ASLMFNET | BTRMAXREC
BTRPAGE | CCITCPS_servername | CCITCPT_servername
CHECKER | COBFSTATCONV | COBHNF
COMMIT_COUNT | CPDIR | DEBUGEXIT
DSQUERY | DYNDIR | ES_CESN_NO_OS388
ES_DB_APPLICATION_PLAN | ES_DB_PACKAGE_PATH | ES_DB_PACKAGESET
ES_EMP_EXIT_1(n) | ES_HOME | ES_IDEBIN
ES_IMS_TRACE | ES_LOAD_SWITCH_PLUS | ES_LOG_PERF_EVENTS
ES_MNM_SUPPORT | ES_STAGING_FOLDER | ES_TSC_TRACE
ES_USR_DFLT_JCL | ES_WORKING_MODE | ES_XDBLIB
FSIDXINTEGRITY | FSSERVER | GCC_LIB
HELPFILES | IBM_DBG_IOCRESFILE | IBM_DBG_LANG
IPF_PATH30 | LIBLIST | MAX_POOL_THREAD_CASDBC
MAX_POOL_THREAD_CASGATE | MAX_POOL_THREAD_CASMQB | MAX_POOL_THREAD_CASTMC
MAX_POOL_THREAD_CASTRC | MAX_POOL_THREAD_CASTSC | MF_JOBDIAG
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 | SSLDIR | TMF
XFH2BTR | 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
Parent topic: Configuring the Server Instance Environment


Environment variables in alphabetical order

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

C

CASSPOOL_LOCK_RETRY_COUNT
Category: JES
If errors are experienced by the spool module, the number of times it retries to obtain a record lock can be adjusted using this environment variable.

Syntax

CASSPOOL_LOCK_RETRY_COUNT=count
export CASSPOOL_LOCK_RETRY_COUNT

Values

count The number of retries made to obtain a record lock.

Default

If not specified, this variable defaults to 20.

CCITIMEOUT

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

Syntax

CCITIMEOUT=value}
export CCITIMEOUT

Default

The default is 1200 (2 minutes).

Example
This example sets the value to 4 minutes:
SET CCITIMEOUT=2400
CCIERRLOG
Specifies the output location and filename of ccierr.log content which tracks first-instance errors reported from the operating systems. CCIERRLOG overrides any entries found in CCI.INI, where the syntax and content is explained in detail.
CCITCP2
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.

Syntax

CCITCP2=hostname
export CCITCP2

Parameters

hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

Comments

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, such as

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.

CCITCP2_PORT
The port that is being used for the registration process.

Syntax

CCITCP2_PORT=port
export CCITCP2_PORT
Parameters
  • port The port on which the CCITCP2 registration program operates.
CCITCPS
To start a CCI server on a fixed port, 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.

Syntax

CCITCPS_server_name=port
export CCITCPS

Parameters

  • server_name is the name of the CCI server
  • port is the fixed TCP post to use

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.

Example

set CCITCPS_server_name=MFPORT:3000
export CCITCPS
CCITCPT

If a client is known to be trying to connect to a server with Server Name server_name, and the TCP address 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 this environment variable.

Syntax

CCITCPT_server_name=MFNODE:server_hostname,MFPORT:port_number

Note that this can be used instead of setting the client Machine Name value. This is useful if the Machine Name value the client specifies cannot be altered by an application defined method.

Parameters

  • server_name The server to which the client is trying to connect.
  • server_hostname The TCP address.
  • port_number The TCP post number.

Example

CCITCPT_server1=MFNODE:server2,MFPORT:3000
CCITRACE
Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

Syntax

CCITRACE=filename [options]
Parameters
  • filename The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrace.log is created in the current directory with all options set to their default states.
  • options Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless a filename any other trace option is specified, in which case it is always ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

COBAIF

Specifies the directory path that Animator is to search for the session (.aif) file for the program being animated, if it is not found in the same directory as the information (.idy) file. Animator can update the session file to record information held between sessions. The .aif file contains details of breakpoints and monitors.

Syntax

COBAIF=pathname
export COBAIF

Parameters

  • A list of search directories, each item separated by a colon. The path where the .aif files are located.

Comments

If the .aif file is not found in the directory specified, a search is made of the directories specified by the COBIDY environment variable. If the file is still not found, the current directory is searched.

If an .aif file does not exist, Animator creates it as follows:

  • If COBAIF is set, the .aif file is created in the first directory specified by COBAIF
  • If COBAIF is not set, the .aif file is created in the directory specified in the environment variable COBIDY from which the program .idy file was loaded
  • If COBAIF and COBIDY are not set, or if the first directory specified by COBIDY is not found, the .aif file is created in the current directory
COBAIFNAME

Specifies the basename of the Animator session file (.aif ) for the program being animated. The .aif file contains details of breakpoints and monitors.

Syntax

COBAIFNAME=basename
export COBAIFNAME

Parameters

  • Basename The basename of the .aif files.

Comments

You need to specify this environment variable if you are starting Animator using COBSW=+A and you want to save breakpoints for subsequent animation sessions. You can also specify it if you are starting Animator using the command anim? in this case the basename you specify overrides the application name as the basename of the .aif file.

COBANIMOPT

Specifies additional directives to be used by Character Animator.

Syntax

COBANIMOPT=directive-list
export COBANIMOPT

Parameters

  • directive-list A directive, or list of directives. Must not be a filename.

Comments

When you invoke Character Animator, it first reads the directives you have specified in COBANIMOPT and then uses any directives you specify in the command line (which might override some of the directives you set in COBANIMOPT).

Example

COBANIMOPT="MIXEDLANGDEBUG MULTITHREAD"
export COBANIMOPT
COBANIMSRV

Identifies which COBOL program a waiting Character Animator process should attach to.

Syntax

COBANIMSRV=progid
export COBANIMSRV

Parameters

  • progid An identifier that is used to identify the program to which Character Animator will attach.

Comments

This environment variable is particularly useful for starting cross-session debugging.

Example

In one console session:

export COBANIMSRV=myid

myid is now a unique identifier that you can use to match Character Animator to a program. Type the command to start Character Animator:

cobanimsrv

The Character Animator waits for a COBOL program to start that has a matching identifier. In another console session:

export COBANIMSRV=myid
cobrun prog1.int

When prog1.int starts, the unique identifier myid matches that of Character Animator? therefore, Character Animator attaches to this process. In console session 1, the Character Animator main screen is displayed and the cursor placed on the first line of prog1.int.

COBATTR

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

Syntax

COBATTR=n
export COBATTR

Parameters

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

  • 0

    Provides standard, default behavior.

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

  • 1

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

  • 2

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

  • 3

    As for 1 and 2 above

  • 4

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

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

Example

COBATTR=1
export COBATTR
COBCONFIG

Specifies a run-time configuration file that tailors the run-time configurable options in some way.

Syntax

COBCONFIG=pathname
export COBCONFIG

Parameters

  • pathname The name of the COBOL configuration file that tailors the runtime

Comments

If $COBCONFIG is not set then the file $COBDIR/etc/cobconfig is searched for instead.

Example

COBCONFIG=/home/mydir/cobconfig
export COBCONFIG
COBCONFIGJVM
Specifies a Java properties file that tailors the run-time configurable options for Java Virtual Machine applications. Use this instead of COBCONFIG in COBOL applications intended for use on a Java Virtual Machine.

Values

  • The location of a properties file.
COBCONFIG.BLOCK
The location of the application configuration file.
COBCPY

Specifies the directory or directories that the Compiler and Animator should search for copyfiles.

Syntax

COBCPY=pathname[:pathname]...
export COBCPY

Parameters

  • pathname

    A directory that the Compiler and Animator are to search when looking for copyfiles. When more than one pathname is present, a null pathname represents the current working directory.

Example

COBCPY=/home/group/sharedcopy::mydir/mycpy
export COBCPY

causes the Compiler to search for a copyfile in /home/group/sharedcopy, then in the current directory and finally in ./mydir/mycpy until either the copyfile is found or it can be considered not found.

COBDATA
Specifies one or more locations, separated by ; (Windows) or : (UNIX), in which to search for data files at run time. As long as the file assignment does not contain a sub-path (that is, a string containing \ or /) then the file assignment is appended to each location specified by COBDATA in order to locate the file.
Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.

Specifies the directory or directories that the run-time system is to search for data files. Provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.

Syntax

COBDATA=pathname[:pathname]...
export COBDATA
Parameters
  • A list of search directories, each item separated by a colon. The runtime system is to search these when looking for application data files. When more than one pathname is present, a null pathname represents the current working directory.

Comments

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.

Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.

Example

COBDATA=:demo:/home/data:progs
export COBDATA

causes COBDATA to be set to instruct the runtime system to search for data files in the current directory, then in the directory ./demo, then in the directory /home/data and finally in ./progs.

COBDIR

Specifies the directory where the required Micro Focus COBOL system is installed. Many of the COBOL system components and utilities require and use this information. If the COBDIR environment variable is not set then the COBOL system acts as if it had been set to the default COBOL system directory. This default directory is /opt/microfocus/VisualCOBOL on UNIX systems.

Syntax
COBDIR=pathname
export COBDIR

Parameters

  • pathname The directory that contains the required Micro Focus COBOL system software.

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

COBDIR=/home/products/cobse20
export COBDIR

This causes the Cob utility to search the directory /home/products/cobse20 for the Micro Focus COBOL system software.

COBIDY

Specifies the directory that Animator is to search for the information (.idy) file for the program being animated if it is not found in the same directory as the intermediate code (.int) file. Animator can update the information file to record information held between sessions.

Syntax

COBIDY=pathname
export COBIDY
Parameters
  • pathname A list of search directories, each item separated by a colon.
COBJVM

Specifies which Java Virtual Machine (JVM) to load.

Syntax
COBJVM=platform_nnn
export COBJVM

Parameters

platform_nnn where

platform is a threecharacter code that indicates the platform on which you are running Server Express, for example:
  • ibm IBM AIX
  • unx SCO UnixWare
  • sun Oracle SPARC
nnn indicates the version of the JVM, for example:
  • 122 Version 1.2.2
  • 130 Version 1.3.0

Comments

You might need to set COBJVM if you are developing distributed applications with both COBOL and Java components.

Example

COBJVM=ibm_122
export COBJVM
COBKEYTIMEOUT

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

When a terminal key is depressed, the terminal might send in response a single character or a group of characters to the runtime 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 runtime 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 runtime system in discrete packets, then the network can alter the intervals between each character arriving at the runtime system. COBKEYTIMEOUT is available to help compensate for typical network delays so the runtime system identifies escape sequences correctly.

Syntax

COBKEYTIMEOUT=n
export COBKEYTIMEOUT

Parameters

n 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 runtime system over the line or network connection. On encountering a lone Escape character, the runtime system waits n tenths of a second before assuming that the character does not introduce an escape sequence. The runtime system calculates an appropriate default value for n from the baud rate of the terminal.

COBLANG
The language environment in which your COBOL program runs.
Values
  • A COBOL language environment (LE) value.
COBLPFORM
This configuration variable is used to define and print to printer channels C01-C12. Specify the line numbers for each channel with the COBLPFORM configuration variable. Null entries are ignored. Those channels that have line number zero, function-names S01-S052, CSP, or are undefined, are set to line 1.

Example 1:

COBLPFORM 1:3:5:7:9:11:13:15:17:19:21:23

In this example C01 equals 1, C02 equals 3, and so on.

Example 2:

COBLPFORM :3::5: :9

In this example, C01 equals 3, C02 equals 5, C03 equals 1, and C04 equals 9. You can specify only a single line number for each channel.

In example 2 above, channels C05 - C12 are undefined. If a print statement specifies channel C05 - C12, the line is printed at line 1. In addition, in the example shown, C03 equals 1 because its value is a space and therefore undefined.

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.

COBMAINSTACK

Specifies the size of the main stack.

Syntax

COBMAINSTACK=n
export COBMAINSTACK

Parameters

n A number in the range 1 through nnn that represents the size of the main stack.

Comments

You might need to set COBMAINSTACK in any of the following circumstances:

  • If you are deploying 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

COBMODE
Whether to start the server in 32-bit or 64-bit mode.
Values
  • 32

    The system starts in 32-bit mode

  • 64

    The system starts in 64-bit mode

COBOPT
Specifies user default options to the Cob utility.

Syntax

COBOPT="[set environment-variable=value]
[options] ...
[cobextn: .ext [.ext] ... ]"
export COBOPT

or

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

If a line does not begin with one of the identifiers set or cobextn: then it is taken as an options line.

Comments

COBOPT can either contain options that supplement or override the system default options defined in $COBDIR/etc/cobopt, or it can specify the path of a file that contains such options. The options can extend over more than one line and each line must have the same format as described for the file $COBDIR/etc/cobopt in the chapter COBOL System Interface (cob).

Examples

COBOPT="CANS85
set COBCPY=$COBDIR/srclib/:$HOME/mylib:"
export COBOPT

This enables ANSI 85 standard COBOL syntax and sets COBCPY to the specified list of paths.

COBOPT=temp/options

Specifies that cob options are contained in the file options in the directory temp.

COBPATH

Specifies the directory or directories that the runtime system is to search for dynamically loadable .int and .gnt files, or callable shared objects.

Syntax

COBPATH=pathname[:pathname]...
export COBPATH

Parameters

pathname A list of search directories, each item separated by a colon, that the runtime system is to search for a dynamically loadable program (.int, .gnt or callable shared object) file. When more than one pathname is specified, a null pathname represents the current working directory.

Example

COBPATH=u:/home/mydir/srclib:otherlib
export COBPATH
COBPRFDIR
Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Values
  • A list of search directories, each item separated by a colon.
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
export COBPRINTER

Parameters

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

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"
export COBPRINTER
COBSES

Specifies the UNIX Session Recorder functions to perform.

Syntax

COBSES={option[filename]}...
export COBSES
Parameters

option can be one or more of the following:

  • -a Include keystrokes made to and screen output from the Animator
  • -f filename Play back recording in fast forward mode
  • -p filename Play back recording in filename at normal speed
  • -r filename Record keystrokes
  • -s filename Record screen output
  • -t terminal number Indicate terminal number for multi-user screen recordings

These flags are all case sensitive. Also, you cannot combine the -r flag with either -f or -p.

Note: You must unset COBSES when you have finished using the UNIX Session Recorder, or it will interfere with the running of your COBOL programs. To do this, set COBSES to spaces, then export this setting to the shell.
COBSSL
If using SSL connections specifies the location of the DemoCA directory. If not found, SSLDIR is inspected instead.
COBSW
Specifies the run-time system switch settings for the run-time system to observe when running an application.

Syntax

COBSW=[+/-}s...
export COBSW
Parameters

A list of the runtime switches to set or unset.

  • + sets a switch.
  • - un-sets a switch.

Example

COBSW=+0+D
export COBSW

This enables runtime switch 0 and the ANSI COBOL debug switch.

COBTERMINFO
Specifies the directory or directories to be searched by the runtime system for a terminfo database of terminal information tailored to the needs of COBOL applications. This enables COBOL applications to use different terminfo settings to those used by non-COBOL applications, such as vi, when using the same terminal.
Syntax
COBTERMINFO=pathname[:pathname]...
export COBTERMINFO

Parameters

pathname A list of search directories, each item separated by a colon, that identify a terminfo database containing terminal settings tailored for COBOL applications. A null pathname represents the current working directory.

Comments

The COBOL system takes the value of the standard UNIX environment variable TERM as the name of the terminal in use. It uses this to search for the appropriate terminal information in a terminfo database. The runtime system first searches the databases identified in COBTERMINFO and then, if the terminal information is not found it searches the database identified in the standard UNIX environment variable TERMINFO.

If COBTERMINFO is not set, the runtime system acts as if it had been set to $COBDIR/terminfo.

Micro Focus recommend that the first directory listed in COBTERMINFO is $COBDIR/terminfo so that the terminfo database supplied with this COBOL system is found first. For commonly used terminals this terminfo contains settings that are fuller and more appropriate to COBOL than those normally available in the UNIX system terminfo database. When debugging using Animator, COBTERMINFO must be set to $COBDIR/terminfo.

COBTERMINFO can also be used to identify a terminfo database that is portable between UNIX systems. Such a database conforms to the standard UNIX database format but does not include any supplementary, UNIX implementation-dependent terminal information. Many UNIX system terminfo databases are not portable because they include such supplementary information. The COBOL system ignores any such nonportable details.

Example

COBTERMINFO=$COBDIR/terminfo:/home/mydir/terms
export COBTERMINFO
CODEWATCH_SRCPATH
The location of source files for the debugger to use if none are found in directories specified when invoking CodeWatch
Values
  • A list of search directories, each item separated by a colon.
CODEWATCH_STBPATH
The location of STB files for the debugger to use if none are found in directories specified when invoking CodeWatch.
Values
  • A list of search directories, each item separated by a colon.
COLUMNS

Specifies the column width of the terminal screen or window, overriding the specified terminal default.

Syntax

COLUMNS=n
export COLUMNS

Parameters

n The width of the terminal screen or window, in column positions.

Comments

The default, when COLUMNS is unset or null, is to use the cols value defined in the specified terminal's terminfo entry, or the current width of the terminal window if you are using an X terminal. The terminal type is specified using the standard UNIX environment variable, TERM.

On non-windowing environments, where the terminal screen area cannot be resized, the COLUMNS values does not need to be set. Terminals that can switch into a wide mode (usually from 80 through 132 columns) have a terminal name ending in "w" and these are automatically supported, without the need to set COLUMNS.

In windowing environments, where the size of windows can be changed, the initial size of the window is used in preference to the cols value in terminfo. When the window is resized, the new size is reread. If the new size is greater than the initial size then the extra columns might not be used.

If you want to use the full width of the window you might need to set COLUMNS to the current column width of the window on some platforms.

Using COLUMNS values that do not correspond to the actual width of the window produces unexpected results.

Example

COLUMNS=100
export COLUMNS

D

DB2DBDFT
The default database for the DB2 SQL precompiler to process SQL statements against.

Values

  • The location and name of the default database.

E

ENTRYNAMEMAP
Specifies the locations of entry name map files to be used.

Syntax

ENTRYNAMEMAP={filename|directory}? ...
export ENTRYNAMEMAP

Parameters

filename An entry map file.

directory A directory containing an entry name map file. The name of the entry name map file must be mfentmap.dat.

Comments

You must set the entry_name_mapper tunable to enable entry point mapper support.

If ENTRYNAMEMAP is not set, the runtime system searches for an entry name map file called mfentmap.dat in each folder specified by the COBDIR environment variable.

If the runtime system finds more than one entry name map file and 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 runtime 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_ALLOC_EXPAND
The default value is Y, which expands an environment variable when used to specify an allocation path. Set to N to override this behavior, which is to not expand the variable used in the path.

Syntax

ES_ALLOC_EXPAND=value
export ES_ALLOC_EXPAND

Values

Y Expands an environment variable used to specify an allocation path.

N Do not expand the variable used in the path.

Default

The default value is Y.

ES_ALLOC_OVERRIDE
The default value is Y, which expands an environment variable when used to specify an allocation path. Set to N to override this behavior, which is to not expand the variable used in the path.

Syntax

ES_ALLOC_OVERRIDE=rules-file
export ES_ALLOC_OVERRIDE

Values

rules-file The file path and name of the dataset rules file.

ES_CAS_API
Indicates whether casout or cassub has been executed by a call and not from the command line.
Syntax
ES_CAS_API=value
export ES_CAS_API
Values
  • ON The utility has been invoked by a call, and messages will not be sent to the console or command line.
Default

The utility will attempt to log messages.

ES_CERT_REG
Specifies the directory in which the cascertreg user certificate utility should store its registrations.
Syntax
ES_CERT_REG=pathname
export ES_CERT_REG
Values

pathname Pathname of the directory where registrations are stored.

Default

By default no directory is specified. In this case it must be specified on the cascertreg command.

ES_CESN_NO_OS390
Overrides the default behaviour CESN transaction response for invalid user credentials. Default behaviour reports "Your userid is invalid" or "Your password is invalid".
Syntax
ES_CESN_NO_OS390=value
export CESN_NO_OS390
Values
  • Setting this variable to any value causes CESN to produce an invalid credential message instead of a specific invalid user or invalid password message.
Default

Specific invalid user/password messages will be produced.

ES_CSKL_NO_MSG_CONSOLE
Stops CSKL writing messages to console.log
Syntax
ES_CSKL_NO_MSG_CONSOLE=value
export ES_CSKL_NO_MSG_CONSOLE
Values
  • Any. CSKL messages are not written to the console log.
Default
If this is not set, CSKL messages are written to the console log.
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 Native Database File Handling and Enterprise Server Region Database Management for more information.

Syntax

ES_DB_FH=value
export ES_DB_FH

Values

  • Y|y|true - file handling is directed through the Micro Focus Database File Handler (MFDBFH).
  • N|n|false - database file handler support is disabled.

Default

Database file handler support is disabled.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.

There also needs to be a corresponding <server> entry for the database server within the configuration file specified by the MFDBFH_CONFIG environment variable. <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
export ES_DB_SERVER

Values

server-instance is the name of a valid database server instance. For example, set ES_DB_SERVER=(local)\SQLEXPRESS.

Default

Not set.

Example

Using the example above, you would be required to have something similar to that below in your mfdbfh.cfg file:

<datastores>
   <server name="(local)\SQLEXPRESS" 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_DDBG_PORT_RANGE
A range of ports to use for dynamic debugging.
You specify a range of port numbers separated by a hyphen or a comma; the second port number must be greater than the first.
Syntax
ES_DDBG_PORT_RANGE=value
export ES_DDBG_PORT_RANGE
Values
  • low_port-high_port
Default
If this is not set, dynamic debugging will use random ports.

Example

ES_DDBG_PORT_RANGE=8001-8040
ES_DISABLE_DFLTUSR_SIGNON
Disables the default user ("mfuser") signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=value
export ES_DISABLE_DFLTUSR_SIGNON
Values
  • Y or y Having logged on to ES administration via your MFDS internal security account, you no longer receive the auto logon as "mfuser" when accessing ESMAC.
Default
If this is not set, mfuser will be used as the default user to sign in to ESMAC.
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
export ES_ESMAC_DISP_MAX_OVERRIDE
Value
  • An integer number denoting how many lines to display. The maximum number is 99999.
Default
10000
ES_HSF_CFG
Enables you to configure a number of additional fields to appear in the HSF record displayed in the .csv file (cashsf-a.csv or cashsf-b.csv).

Syntax

ES_HSF_CFG=cfg-options
export ES_HSF_CFG

Parameters

Define cfg-options using the following syntax:
field_name=value;[field_name=value;]...
using the following values:
Field name | Range | Default
CUSTOM | 0-5 | 0
CICSF | 0-20 | 5
TSQ | 0-20 | 5
TDQ | 0-20 | 5
Note: If a field is not explicitly set, or the value specified is out of range, the default value for the field is used.

For example: ES_HSF_CFG=CUSTOM=2;CICSF=10;TSQ=32 generates 2 custom fields, 10 CICS file fields, 5 TSQ fields and 5 TDQ fields.

Custom fields are written to using the ES_WRITE_CUSTOM_HSF library routine.

ES_MAX_CATALOG_LINES
Restricts the number of entries displayed in ESMAC catalog view.
Syntax
ES_MAX_CATALOG_LINES=number
export ES_MAX_CATALOG_LINES
Values
  • number The number of lines to display. The maximum is 99999.
Default
The default is 5000.
ES_MEM_STRATEGY
Selects the types of memory processes supported.
Note: Note that memory strategy can also be set via the memory_strategy runtime tunable.
ES_MQ_1PC
Indicates whether the IBM WebSphere MQ switch module ESMQXA should operate in one-phase commit mode. Set this environment variable only when advised to do so by Micro Focus.

Syntax

ES_MQ_1PC=value
export ES_MQ_1PC

Values

  • Y|y|T - ESMQXA operates in one-phase commit mode.

Default

By default ESMQXA does not operate in one-phase commit mode.

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= fully_qualified_library
export ES_MQ_LIB

Values

  • fully_qualified_library - A fully-qualified library name.

Default

By default ES will try to locate libraries in the default location for the platform.

Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_T
The full name including the path of the IBM WebSphere MQ client or server library, for threaded environments. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_T= fully_qualified_library
export ES_MQ_LIB_T

Values

  • fully_qualified_library - A fully-qualified threaded library name.

Default

By default ES will try to locate threaded libraries in the default location for the platform.

ES_MQ_LIB_XA
The full name including the path of the IBM WebSphere MQ XA library. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_XA= fully_qualified_library
export ES_MQ_LIB_XA

Values

  • fully_qualified_library - A fully-qualified library name.

Default

By default ES will try to locate libraries in the default location for the platform.

Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_XA_T
The full name including the path of the IBM WebSphere MQ XA library, for threaded environments. This should only be required if MQ was NOT installed in the default location.

Syntax

ES_MQ_LIB_XA_T= fully_qualified_library
export ES_MQ_LIB_XA_T

Values

  • fully_qualified_library - A fully-qualified threaded library name.

Default

By default ES will try to locate threaded libraries in the default location for the platform.

ES_MQ_LISTENER (deprecated)
Defines one or more WebSphere MQ listeners.
Note: ES_MQ_LISTENER is deprecated, and provided for backward compatibility only. We recommend that you use MFDS configuration instead.

Syntax

ES_MQ_LISTENER={QueueManagerName,QueueName,ListenerName}
[,QueueManagerName,QueueName,ListenerName}...
export ES_MQ_LISTENER
Values

QueueManagerName,QueueName,ListenerName - the characteristics of the listener being defined.

Default

By default, no WebSphere MQ listeners are defined.

ES_MQ_XA
The type of XA structure to use for the two-phase commit XA switch module.

Syntax

ES_MQ_XA=value
export ES_MQ_XA
Values
  • D: use a dynamic XA structure
  • S: use a static XA structure

Default

By default, a dynamic XA structure is used.

ES_OLD_DYN_PDS
Determines the resulting behavior of dynamic PDS members when specified in a JCL DD statement.

Values

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

The default value is 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=value
export ES_OLD_SEC_TSTD
Values
  • Any value.
Default
By default security is enforced for TS or TD queues that are not declared in the security repository.
ES_OTMA_TIMEOUT
The time in seconds that an OTMA client should wait for an answer. The default value is 120.
Syntax
ES_OTMA_TIMEOUT=seconds
export ES_OTMA_TIMEOUT
Values
  • seconds - The number of seconds to wait. The maximum is 43199.
Default
120 seconds.
ES_PROG_PATH
Set ES_PROG_PATH=Y to display the program's load path in the JESYSMSG and SYSLOG datasets.
Note: This is only applicable for native enterprise server regions.
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. The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file.

Syntax

ES_RLS_FILE_SUPPORT=value
export ES_RLS_FILE_SUPPORT

Values

  • Y|y - Stops dirty records being returned when a record is locked by another process.

Default

RLS file support is off.

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 the period of inactivity to be controlled.

Syntax

ES_SEP_DORMANT_TIME=seconds
export ES_SEP_DORMANT_TIME

Values

  • seconds Number of seconds' inactivity.

Default

Transient SEPs are terminated after 2 seconds of inactivity.

ES_SERVER
The default server name (used if no -r switch is specified on casstart or casstop).

Syntax

ES_SERVER=name
export ES_SERVER

Values

  • name The server name.

Default

ESDEMO/ESDEMO64

ES_SYSOUT_HOLD
The status of the SYSOUT files are set to Out Hold.
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=user
export ES_USR_DFLT_ESMAC

Values

  • user - the default user name.

Default

mfuser

ES_ESM_DISABLE_DFLTUSER_ESMAC
Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.

Syntax

ES_ESM_DISABLE_DFLTUSER_ESMAC=value
export ES_ESM_DISABLE_DFLTUSER_ESMAC

Values

  • Y|y - Default ESMAC user is disabled.

Default

Default ESMAC user is not disabled.

ES_XA_LOG_SUPPRESS
Suppresses XA logging and the recovery of in-doubt XA transactions.

Syntax

ES_XA_LOG_SUPPRESS=value
export ES_XA_LOG_SUPPRESS

Values

  • Y|y - XA logging is suppressed.

Default

By default no value is specified and XA logging is not suppressed.

ES_XA_RECONNECT

This variable is used by the CRCN transaction to determine the frequency in which the enabled resource managers are checked for an available connection. Set the variable to a value that represents the delay, in seconds, between two monitoring sessions.

Syntax

ES_XA_RECONNECT=<interval>
export ES_XA_RECONNECT

Values

  • <interval> - the duration, in seconds, between checks for an available connection by the CRCN transaction.

Default

No value is set and the XA reconnect feature is not enabled.

EXTFH
Specifies a configuration file for the Callable File Handler.

Syntax

EXTFH=filename.cfg
export EXTFH

Parameters

filename.cfg The name of the configuration file.

Example

EXTFH=/home/mydir/myconfig.cfg
export EXTFH

F

FHREDIR
Specifies a configuration file to be used by the Fileshare Client.

Syntax

FHREDIR=filename.cfg
export FHREDIR

Parameters

filename.cfg The name of the configuration file.

Example

FHREDIR=/home/mydir/myconfig.cfg
export FHREDIR
FS

Specifies a configuration file to be used by the Fileshare Server.

Syntax

FS=filename.cfg
export FS

Parameters

filename.cfg The name of the configuration file.

Example

FS=myconfig.cfg
export FS
FSCOMMS
Specifies that the Fileshare system is to run in single user mode.

Syntax

FSCOMMS="\$local"
export FSCOMMS

Parameters

"\$local" Run the Fileshare System in single user mode.

H

HCOBND (deprecated)
Specifies a directory to be used for bind files generated by the DB2 External Compiler Module (ECM).
Note: 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

Parameters

pathname The directory that the DB2 ECM is to use to store bind files.

Example

SET HCOBND=/mydir/binds
export HCOBND

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.

I

ISPPROF
The location of ISPF dialog profiles.

J

JAVA_HOME
Specifies the location of the JDK.

L

LANG
Specifies the locale.

Syntax

LANG=language[_territory[.codepage]]
export LANG
Parameters
  • language The language in which your program is to run.
  • _ (underscore) The delimiter for language and territory, if territory is specified.
  • territory The country in which your program is to run.
  • . (period) The delimiter for territory and codepage, if codepage is specified.
  • codepage The character set to use for your program.

Example

LANG=fr_FR
export LANG
LD_LIBRARY_PATH

Specifies the directory or directories for the UNIX system, cob command, and the run-time system to search for shared libraries and callable shared objects. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib on all platforms except AIX (which uses LIBPATH). It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LD_LIBRARY_PATH=pathname[:pathname]...
export LD_LIBRARY_PATH
Parameters

pathname A path or a list of paths, each separated by a colon (:).

Comments

The list of directories must include $COBDIR/lib. The COBDIR environment variable is described earlier.

This environment variable is a system environment variable? see your UNIX documentation for more information.

Example

LD_LIBRARY_PATH=$COBDIR/lib:/home/mydir/myapp:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
LIB
The location of the DB2 LIB directory
LIBLIST
Reserved for use by Micro Focus. Use only if directed by Micro Focus Technical Support.
LIBPATH
Specifies the directory or directories for the UNIX system, Cob and the runtime system to search for shared libraries and callable shared objects. It is only available on AIX-based systems. If you have installed the product to a directory other than the default one, you must set this variable to include $COBDIR/lib. It should also include any directories that contain callable shared objects used by your application. If you have installed the product in the default directory (/opt/microfocus/VisualCOBOL), you do not need to set this variable.

Syntax

LIBPATH=pathname[:pathname]...
export LIBPATH

Parameters

pathname A directory to search for shared libraries.

Example

LIBPATH=$COBDIR/lib:/lib:/usr/lib
LINES
Specifies the depth of the terminal screen or window, overriding the specified terminal default.

Syntax

LINES=n
export LINES

Parameters

n The depth of the terminal screen or window, in lines.

Comments

The default, when LINES is unset or null, is to use the lines value as defined in the specified terminal's terminfo entry, or the current depth of the terminal window if you are using X windows. The terminal type is specified via the standard UNIX environment variable, TERM.

On non-windowing environments, where the terminal screen area cannot be resized, the LINES values does not need to be set.

In windowing environments, where the size of windows can be changed, the initial size of the window is used in preference to the lines value in terminfo. When the window is resized, the new size is reread. If the new size is greater than the initial size then the extra lines might not be used.

If you want to use the full depth of the window you might need to set LINES to the current depth of the window on some platforms.

Using LINES values that do not correspond to the actual depth of the window produces unexpected results.

Example

LINES=50
export LINES

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=fpstatus
export MAINFRAME_FLOATING_POINT

Parameters

fpstatus Which format to use for floating point data items. This must be one of:

  • true Specifies that IBM hexadecimal format floating point data items are to be used.
  • false Specifies that IEEE format floating point data items are to be used.

Setting MAINFRAME_FLOATING_POINT to anything other than true has the same effect as setting it to false.

The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_ALIAS
Specifies program aliases. Each set (pair) is 16 characters long - 8 characters for the program-name, and 8 characters for the alias. You can specify up to 10 pairs. This list is searched first and thus can potentially override the built-in list. If not found, the built-in alias table is searched.
MF_AMODE31ONLY
Indicates that all programs are AMODE(31).
MF_CBLQDA
Determines if QSAM files are dynamically allocated when processing an OPEN I-O or OPEN EXTEND statement for an optional file (that is, a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT (regardless of whether it is optional or not). Permissible values are OFF and ON; the default is OFF, which specifies that dynamic allocation is not permitted.
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.
Note: 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_CHARSET
Specifies the system character set (ASCII or EBCDIC).
MF_DUPJOBS
Enables jobs with identical names to run.
Values:
  • Y (Default)
  • N
MF_ROOT_CERT
Enables the MF Directory Server process and any client applications to pick up the value of the root certificate file.
MF_SMS
Enables SMS support
MF_SPOOL_HK_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
export MF_SPOOL_HK_LEX_SCAN

Values

Y The files are deleted.

N The files are not deleted.

Default

The default is 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_OUTPRT=value
export MF_SPOOL_HK_OUTPRTC

Values

Y Files from the Complete queue are deleted.

NFiles from the Complete queue are not deleted.

Default

The default is Y.

MF_SPOOL_HK_TESTDATE
Overrides the normal date for the spool housekeeping.

Syntax

MF_SPOOL_HK_TESTDATEC=YYYYMMDD
export MF_SPOOL_HK_TESTDATEC

Values

YYYYMMDD The date which is to override the normal date.

Default

If this variable is not set, the normal date for the spool housekeeping is used.

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
export MF_SPOOL_HK_WRITE_PROFILES

Values

Y Profile files are created.

N Profile files are not created.

Default

The default is Y.

MF_SYSLOGDSN
The Syslog Dataset name.
MF_USESCA5
Specifies that the server should use version 5 of the Open Service Component Architecture.
Values:
  • ON (Default)
  • OFF
MFALLOC_LOC
The default allocated data set location.
For a database-hosted data set location, you need to include the full SQL URL, for example, set 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).
MFAUDIT_LOGS
The location of audit files.
MFCSCFG
Specifies a configuration file to be used by the Client/Server Binding client program.

Syntax

MFCSCFG=filename
export MFCSCFG

Parameters

filename The name of the configuration file.

Example

MFCSCFG=/home/mydir/mfclisrv.cfg
export MFCSCFG

Comments

The value of MFCSCFG is overridden by any value defined in the command line. If neither of the above yields a filename, the default filename mfclisrv.cfg is assumed, and is searched for in the current directory. If that in turn is not found, the default settings for the configuration entries are used.

MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.

Syntax

MFDBFH_CONFIG=value
export MFDBFH_CONFIG

Values

value represents the full path and filename of your database configuration file.

Default

Not set.

MFDBFH_CONNECTION_POOLING

Specify whether database connection pooling is to be enabled or not when the database file handler is in effect.

Syntax

MFDBFH_CONNECTION_POOLING=TRUE|FALSE
export MFDBFH_CONNECTION_POOLING

Paramaters

TRUE
Connection pooling is enabled, which keeps database connections open, and then reuses them where possible in preference of creating a new connection.
FALSE
Connection pooling disabled. This setting comes at a cost to performance, as a new physical connection is established each time. You may want to disable connection pooling during testing, when databases are more frequently added and dropped: if pooling is enabled, and existing connections remain open, it may stop you from dropping that particular database.

Default

MFDBFH_CONNECTION_POOLING=TRUE

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_CONFIG=table|database
export MFDBFH_CONFIG

Paramaters

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 Database Record Locking for a list of differences for each database engine.

Default

MFDBFH_RECORD_LOCKING=table
Note: If the value of this variable is set to anything other than 'database', this default is used.
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=value
export MFDBFH_SCRIPT_DIR

Values

value represents a path to the directory containing the required resources.

Default

value defaults to the \etc\mfdbfh\scripts sub directory of your product installation directory.

MFE.SMS
Enables SMS support.
MFEXTMAP
Location of a mapper file.
MFLECONFIG

Specifies a configuration file for Language Environment (LE) runtime options.

Syntax

MFLECONFIG=filename
export MFLECONFIG

Parameters

filename The file containing the LE runtime options you want to use.

MFLOCKING
Enables Locking Support
MFLOGDIR
Specifies a directory to be used by Client/Server Binding for log files.

Syntax

MFLOGDIR=dirname
export MFLOGDIR

Parameters

dirname The name of the directory for log files.

Example

MFLOGDIR=/home/mydir/logs
export MFLOGDIR
MFPRELOAD_USE
Calls MFPRELOAD to improve performance.
MFREXX_LSEQ_RECSIZE_MAX

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

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

O

OOSW
OO run-time switches.

P

PATH

Specifies the directories to be searched by all UNIX programs, including the runtime system, when finding executables to be run.

Syntax

PATH=pathname[:pathname]...
export PATH

Parameters

pathname A directory to search for executables.

Example

PATH=$COBDIR/bin:$PATH
export PATH

R

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

S

SORTCOMPRESS
Tells the system whether or not to execute a compression routine on each record to be sorted.

Syntax

SORTCOMPRESS=5
export SORTCOMPRESS

Parameters

5 This is the only value that you can supply. It allows for run-length encoding of sort records, resulting in much better performance when records contain multiple repeated characters.

Comments

This variable is recommended if the sort records contain many single repeated characters, for example, multiple spaces, as it can be very effective in improving memory usage and therefore sort performance.

Example

SORTCOMPRESS=5
export SORTCOMPRESS
SORTSCHEME
Activates a sortscheme. Use in conjunction with SORTSPACE for improved performance.

Syntax

SORTSCHEME=1
export SORTSCHEME
Values
  • SORTSCHEME=1 - this is the only valid value for the environment variable. See SORTSPACE for more information.
SORTSPACE
The amount of memory to be allocated to internal workspace for SORT operations. This can be specified in different formats: for example, you could specify 64M, 2G, and 1000000 to give sort memory areas of 64 Megabytes, 2 Gigabytes and 1000000 bytes respectively.

Syntax

SORTSPACE=n[K|k|M|m|G|g]
export SORTSPACE

Parameters

n[K|k|M|m|G|g The amount of memory to be allocated to internal workspace for SORT operations. K or k indicates kilobytes, M or m indicates megabytes and G or g indicates gigabytes. No letter indicates bytes. Defaults to 1 megabyte.

Comments

A larger value for SORTSPACE will generally result 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 will be degraded.

Example

SORTSPACE=1024K
export SORTSPACE

SORTTEMPSPACE
Specifies the amount of memory to be allocated to temporary workspace for SORT operations.

Syntax

SORTTEMPSPACE=n[K|k|M|m|G|g]
export SORTTEMPSPACE

Parameters

n[K|k|M|m|G|g] The amount of memory to be allocated to temporary workspace for SORT operations. K or k indicates kilobytes, M or m indicates megabytes and G or g indicates gigabytes. No letter indicates bytes. 32 megabytes is the lowest amount of memory that can be allocated.

Comments

The memory allocation strategy used by SORT can be adjusted through use of SORTTEMPSPACE, which generally improves performance in systems suffering from memory fragmentation.

Example

SORTTEMPSPACE=250MB
export SORTTEMPSPACE
SORTTYPE
Defines the sort type.

Syntax

SORTTYPE=2
export SORTTYPE
Values
  • SORTTYPE=2 Forces SORT to use the file handler, so that format modifications are picked up from the extfh.cfg file.
  • Not setting this variable means that SORT will try to use CBL_ routines to read and write files to improve performance.
Note: 2 is the only valid value for this environment variable.
SSLDIR
If using SSL connections, this value specifies the generic location of the system's OpenSSL directory.

T

TERM
Defines the type of terminal being used.

Syntax

TERM=name
export TERM

Parameters

name The name of the terminal in the terminfo database.

Example

TERM=at386
export TERM
TERMINFO

Specifies the directory to be searched by all UNIX programs, including the runtime system, for the UNIX system terminfo database.

Syntax

TERMINFO=pathname
export TERMINFO

Parameters

pathname The name of a directory that contains the UNIX system terminfo database.

Comments

The UNIX system terminfo database is used by all UNIX applications that need to use a terminal. However, COBOL applications tend to make much fuller and sophisticated use of the terminal and require a fuller terminfo description than is required by typical UNIX applications such as vi. Some terminal capabilities, such as those set during the initialization of the terminal to control the use of function keys, commonly conflict with the needs of typical COBOL applications. In such cases, the terminal information required by COBOL can be stored in a separate terminfo database and referenced using COBTERMINFO.

TMPDIR
Specifies a directory in which to store temporary files in place of the UNIX system default.

Syntax

TMPDIR=pathname
export TMPDIR

Parameters

pathname The directory used by UNIX applications for any temporary work files. Temporary work files can be created by COBOL utilities such as Cob or by the runtime system when it executes statements such as SORT. If you do not specify a directory, the system default directory is used.

Comments

You might need to use this environment variable if the runtime system needs to page data to disk when creating heaps or sorting.

TX_MQTRACE
Enables tracing in dfh0mqis for WebSphere MQ calls.
TXFILEP
The location of Micro Focus VSAM files. This can be a location on disk or a datastore location within a database. For database-hosted files, use the notation sql://host[/instance]/datastore[?folder=/path] - see The dbfhdeploy Command Line Utility for more information.

U

USER
Default user name.
Parent topic: Configuring Environment Variables
Related concepts
ES_WRITE_CUSTOM_HSF
ESCSTHSF


Configuring Fileshare

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

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

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

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

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

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

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

Parent topic: Configuring the Server Instance Environment


Using XA-compliant Resources (XARs)

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

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

RM access is provided for:

  • WebSphere MQ
  • EDB PostgreSQL (technology preview)
  • ODBC (generic one-phase commit)
  • DB2 LUW
  • Oracle

XA-compliant Resources (XARs)

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

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

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

XAR ID
The XAR ID uniquely identifies your XAR.

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
  • Monitoring Resource Managers
    A CICS system transaction, CRCN, is available to monitor the state of XA connections for each resource manager (RM) entry defined in the system.
  • XA and in-doubt transactions
  • XA Troubleshooting
Parent topic: Configuring the Server Instance Environment


Planning and Designing XARs

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: This topic does not apply to WebSphere MQ.

For a great majority of the applications that use XARs, the process of implementing an XAR is simple and straightforward, requiring only that you define the XAR 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.

After building a Micro Focus RM switch module, 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:

  • IBM DB2
  • Oracle
  • Generic one-phase commit for ODBC
  • EDB PostgreSQL (technology preview)

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

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

However, in some scenarios, more than one XAR of the same type might be required for a Web services application. See Working with Multiple XARs for more information.

Is the application coded to use distinct XARs?
Typically, the SQL code of Web Services requests are stored in distinct source code modules – some modules used with only one database, and others used with another. Code constructed in this fashion can be compiled for each program module using the XAID compiler directive option set to the value of the appropriate XAR ID. This eliminates the need to change code.
Is it best to use a static or dynamic RM switch module in an XAR?
This depends on how the XAR is accessed by the application(s). See RM Switch Module Registration for more information.

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

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
Related tasks
To Define an XA Resource (XAR) for an Enterprise Server Region


RM Switch Module Registration

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

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

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

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

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

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

Parent topic: Planning and Designing XARs
Related concepts
Planning and Designing XARs
Defining XA Resource Entries


Working with Multiple XARs

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

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:

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 Web services correctly.
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.

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.

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.
F
The associated XAR uses XA distributed, global transactions. Default.
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)
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.
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
EDB PostgreSQL xa_open string


Defining XA Resource Entries

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

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the enterprise server region that you want to edit.
  2. Click the XA Resources tab.
  3. Click Add.
  4. Specify the details of the XAR:
    ID
    Specify an XA resource manager (XAR) ID, used internally to identify a particular XA configuration, and must be unique within the enterprise server region. This ID is used by . See 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 ( .so) 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.
    Reconnection attempts
    The reconnect value controls how many attempts are made to connect to the XA resource. The default value is 1. A value of 0 is not permitted. A -1 value instructs it to continually retry.
    Open string
    Specify the string that is passed to the resource manager on the xa_open() call. It usually contains at least the database name, and often the user ID and password credentials for connecting to the database. The contents of this string are database-specific.

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

    Close string
    The string that is passed to the XAR on the xa_close() call. To find out whether or not you need to supply Close string, see your database vendor's documentation.
    Description
    Specify an optional text description of the XAR definition.
    Enabled
    Check this to enable the XAR. It is checked by default.
    Important: For more information on the syntax for Open string, see the xa_open string topic for your database type, listed below.
  5. Click Add.
Note: You cannot add an XAR until all the mandatory fields have values. If you add an XAR whilst the region is running, you can connect to it as soon as the XAR is enabled.
  • EDB PostgreSQL xa_open string
  • Generic one-phase commit for ODBC xa_open string
  • IBM DB2 xa_open string
  • Oracle xa_open string
  • XAR for WebSphere MQ
  • MQ XA switch modules support the BATCHONLY option
Parent topic: Defining XA Resource Entries
Parent topic: Work with Servers
Related concepts
Planning and Designing XARs


EDB PostgreSQL xa_open string

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

To complete the definition of an EDB PostgreSQL XAR, add the following values in the Open string field:

DSN=odbc_dsn[,USRPASS=userid.password]
   [,LOCALTX={T|F}]
   [,ISOLEVEL={CR|RR|SS|SZ|UR}][,ESLOGGING=0001]
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
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

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

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]
   [,LOCALTX={T|F}][,ISOLEVEL={CR|RR|SZ|UR}][,ESLOGGING=0001]
odbc_dsn
The ODBC Data Source Name used to connect to the data source as defined within your ODBC driver configuration.
userid
The user ID required to connect to the data source. 1
password
The password required to connect the user ID to the data source. 1
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

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

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}]
   [,LOCALTX={T|F}][,ISOLEVEL={CR|RR|SZ|UR}][,ESLOGGING=0001]
   [,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).
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

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

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
   ][,LOCALTX={T|F}][,ISOLEVEL={CR|RO|SZ}]
   [,ESLOGGING=0001]
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/".
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


XAR for WebSphere MQ

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Parent topic: To Define an XA Resource (XAR) for an Enterprise Server Region
Related reference
WebSphere MQ-Specific Environment Variables


MQ XA switch modules support the BATCHONLY option

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

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

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that owns the XA resource you want to edit.
  2. Click the XA Resources tab.
  3. Click Edit next to the XA resource you want to edit.
    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 OK.
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 reconnect to an XA resource following an error

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

Parent topic: Defining XA Resource Entries
Parent topic: Work with Servers


To Enable or Disable an XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that owns the XA resource you want to enable or disable.
  2. Click the XA Resources tab.
  3. Click Edit next to the XA resource you want to enable or disable.
  4. Check or uncheck Enabled as required.
  5. Click OK on the confirmation page.
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


Monitoring Resource Managers

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
A CICS system transaction, CRCN, is available to monitor the state of XA connections for each resource manager (RM) entry defined in the system.

CRCN is a replacement for the former XA Reconnect facility that recycled SEPs on connection loss. The XA Reconnect facility was configured by setting the ES_XA_RECONNECT environment variable. CRCN also uses this environment variable, although its usage differs slightly.

  • Configuration
  • Processing Overview
  • Security
  • Known Issues and Limitations
Parent topic: Using XA-compliant Resources (XARs)


Configuration

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

To configure the CRCN transaction, set the ES_XA_RECONNECT environment variable to a value that represents the delay, in seconds, between two monitoring sessions. CRCN retrieves this value. For example: ES_XA_RECONNECT=20

This causes CRCN to monitor the list of enabled resource managers every 20 seconds. When ES_XA_RECONNECT is set, CRCN is started at region initialization and begins monitoring as soon as it is active.

Parent topic: Monitoring Resource Managers
Related information
Processing Overview
Security
Known Issues and Limitations


Processing Overview

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

At start-up, CRCN reports the initial state of the RMs by emitting the following messages:

CASXO0041I The XA connection monitoring
transaction CRCN started using a 00020 seconds interval.

This message is followed by a message similar to the following:

CASXO0034I CRCN started monitoring: XAMQ Enabled, XADB Enabled, XAOR Enabled.

Where XAMQ, XADB, and XAOR represent active and connectable resource managers marked as Enabled at region start-up.

Note: An RM marked as Disabled at region start-up is not monitored by CRCN until its state, in MFDS, is changed to Enabled using the dynamic XA feature. When this change of state takes place, CRCN starts monitoring this resource automatically.

To verify connectivity, CRCN uses a new function of the XA switch: -- xa-ping.

This entry point pings the resource manager, which then confirms that it is connectable. The ping is a simple call/API into the RM; see Pinging the Resource Manager (xa-ping) for details on the call for each XA switch.

If xa-ping does not return a code of 0, this signals to the transaction that a resource manager cannot be contacted. In this case, the following messages appear in the console:

CASXO0038I XA resource XAMQ has now been disabled.
CASXO0031W ES has lost connection to the RM XAMQ, attempting to reconnect.

The first message indicates that CRCN sent a request to all processes to close the connection to the resource managers. The last process to fulfil the request emits this message. The second message indicates that the connection to the resource manager has been lost and that Enterprise Server is attempting to restore the connection.

Note: On the first failure, the attempt to reconnect takes place after the duration of the DELAY if CRCN detected the connection. If another process flagged the CRCN disconnect, the reconnect takes place on the next CRCN monitoring cycle.
  • Pinging the Resource Manager (xa-ping)
  • RM Monitoring Exclusions
  • Further Considerations
Parent topic: Monitoring Resource Managers
Related information
Configuration
Security
Known Issues and Limitations


Pinging the Resource Manager (xa-ping)

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

The CRCN transaction invokes a new entry point, xa_ping, in the RM switch modules. This entry point executes a simple request to the target resource manager to check the connection state.

Ensure you have an up-to-date version of the switch module for which the ping entry is enabled.

The following table shows the functions/APIs invoked for the different resource managers:

Important: You must ensure that the resource manager allows execution of the APIs listed.
Resource manager | Probe APIs
Oracle | OCIPing
IBM DB2 | SQLGetConnectAttr
Microsoft SQL Server | SQLGetConnectAttr
IBM MQSeries | MQ-open with options with option inquire on object type queue manager, and MQ-close
OCI | OCIPing
ODBC | SQLGetConnectAttr
PostgreSQL | SQLGetConnectAttr
Parent topic: Processing Overview


RM Monitoring Exclusions

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

You can exclude one or more RMs from CRCN processing by setting the following environment variable:

ES_XA_EXCLUDE_MONITORING=<RM-name>
<RM-name> is a resource managers that you want to exclude. Use the ID defined in the XAR definition to prevent monitoring. Exclude multiple RMs (maximum 50) by specifying multiple names ,separated by a ";".
Note: The RM name length must not exceed 8 characters in length.

Examples:

ES_XA_EXCLUDE_MONITORING=RM1;RM2;RM3
ES_XA_EXCLUDE_MONITORING=MYRM01;MYRM003

CRCN will exclude an RM if either

  • The xa-ping pointer is set to low-values - this means no ping entry point was implemented in this xa resource switch module; or
  • The RM is specified by ES_XA_EXCLUDE_MONITORING.
Parent topic: Processing Overview


Further Considerations

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

Whilst the CRCN transaction is monitoring the resource managers, you should consider the following:

Static or dynamic XA registration?

Dynamic XA is more efficient than static XA, because the xa transaction is effectively started when the application accesses the resource manager; however static XA might be required if:

  • the application is not intercepting lost connections, or does not take appropriate action to signal to the system administrator that the connection to an RM has been lost, such as when a transaction ABENDs, or sends severe errors to the console; or:
  • there is a possibility that the connection to an RM is lost on a single SEP.

    If this SEP is running CRCN, CRCN will detect the connection loss and send a request to all SEPs to disconnect/reconnect to the RM.

    If this SEP is running an application, the application should detect the connection loss, abend, and consequently signal the RM failure to the administrator. However, this SEP cannot signal to CRCN that the connection has been lost, because with dynamic registration, the RM must register itself with the TM (in this case, Enterprise Server). If the connection to this RM has been lost, the RM will not register, and the enterprise server region will not attempt any xa-verb processing against this RM, and therefore no error can be raised.

Long-running tasks

If there are long-running tasks in the system, ensure that they regularly pass the control back to the system. For a CICS transaction, this means executing an EXEC CICS so that the system gets the opportunity to process the xa request sent to each process by CRCN. Failure to pass control back to the system causes the process emitting the request to wait until its request has been processed in all SEPs. If these requests are not processed immediately, CRCN waits until they are.

Parent topic: Processing Overview


Security

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

If you are using Enterprise Server external security, you may need to create access-control rules for this new transaction and program, such as:

###################
###### PCT : CRCN #
###################
dn: CN=CRCN,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:OPERATOR group:read
microfocus-MFDS-Resource-ACE: allow:SYSADM group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: XA connections monitoring transaction
#######################
###### PPT : DFHZCRCN #
#######################
dn: CN=DFHZCRCN,CN=MCICSPPT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: MCICSPPT
microfocus-MFDS-Resource-ACE: allow:OPERATOR group:control
microfocus-MFDS-Resource-ACE: allow:SYSADM group:control
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
Description: CRCN XA connections monitoring program
Parent topic: Monitoring Resource Managers
Related information
Configuration
Processing Overview
Known Issues and Limitations


Known Issues and Limitations

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

Monitoring resource managers in Enterprise Server, using the CRCN transaction has the following know issues or limitations:

Oracle
Oracle does not recover from a connection loss. This issue was raised as a Service Request with Oracle (SR 3-19815889131). To work around this issue, CRCN reconnect processing terminates the SEP when the re-connection to an Oracle Database throws an XA error.
WebSphere MQ Server
When WebSphere MQ Server and Micro Focus Enterprise Server are installed on the same machine, WebSphere MQ Server can establish a connection using shared memory (LOCAL SERVER). In that scenario the system cannot reconnect, because the MQ server does not release shared memory resources used for each Enterprise Server process connected to the system after an xa-close, if the MQ Server was 'stopped immediately'. This is a limitation of the MQ architecture. Check the WebSphere MQ System Administration Guide documentation for how to clear the shared memory resources.
Parent topic: Monitoring Resource Managers
Related information
Configuration
Processing Overview
Security


XA and in-doubt transactions

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

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

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

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

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

XA logging

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

Configuring the recovery of in-doubt XA transactions

By default, XA logging is enabled for qualifying resource managers which have switch modules that are configured to respond to xa_recovery() calls. The logging enables you to recover from failures that leave resource managers such as DB2 and MQ with in-doubt transactions. Depending upon your environment, logging may degrade performance. You can disable the logging as follows:
  1. In the Enterprise Server Administration page, click Edit for the enterprise server region you want to disable logging.
  2. Click the General tab.
  3. In the Configuration Information field, type:
    [ES-Environment]
ES_XA_LOG_SUPPRESS=Y
  4. Click Apply.
  5. Click OK.
Parent topic: Using XA-compliant Resources (XARs)


XA Troubleshooting

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


XA Troubleshooting

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

Reading Error Messages in console.log

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

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

Understanding Enterprise Server XIDs

The XID transaction identifier consists of the following parts:

Element | Length | Description
xid-id | 6 char | Constant "MF_CAS"
xid-sysid | 4 char | SYSID of your region
xid-applid | 8 char | APPLID of the region
xid-start-number | 9 numeric | Region instance number
xid-start-time | 8 numeric | Region instance start time
xid-mgr-id | 5 numeric | XA resource manager entry number
xid-branch-no | 5 numeric | Branch number

Reading CAS Traces

If you have enabled resource manager interface or exit traces, or if an XA call fails (in which case traces are unconditionally written) you can trace XA calls. 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

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

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

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

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

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

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


RM Switch Module Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.
SQL Server, PostgreSQL, and ODBC
The SQL Server 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. a configuration file, ctf.cfg, located by default in the $COBDIR 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
The Consolidated Tracing Facility
Components Traced by CTF


Configuring and Administering Enterprise Server Instances

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

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

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

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


Creating and Configuring Enterprise Server Instances

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

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

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


To Add an Enterprise Server Instance

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

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


To Change the Number of ES licenses

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

    The Server > Properties > General page is displayed.

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

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

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


To Copy an Enterprise Server Instance

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

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

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


To Delete an Enterprise Server Instance

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

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

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


To Delete a CCI Server

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

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

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

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

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


To Export Server Information

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

    The Server > Properties > General page is displayed.

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

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

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

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


Connecting to a Server Instance

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

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

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

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

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


To start an enterprise server instance

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

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

  2. Click OK.

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

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

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

Note:

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

Parent topic: Connecting to a Server Instance
Parent topic: Work with Servers


To stop a server Instance

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

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

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

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

  2. Click OK.

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

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

    The value in Current Status changes to "Stopped".

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


To Edit an Enterprise Server Instance

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


To Log On to Enterprise Server Administration

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

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

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


To Log Off from Enterprise Server Administration

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


Using Start and Stop Scripts

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

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

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

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

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

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

where value is the value of the environment variable.

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

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

 # Begin shutdown
 casstop

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

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

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

You can also create an "On server not responding" script. This script will be executed when all of the running communications processes for a server have entered the "Not Responding" state. That might indicate that the server is hung or has crashed, or it might result from network connectivity problems between the Directory Server and the enterprise server. 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

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

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

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

From ESMAC, you can:

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

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

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


To Start ESMAC for an enterprise server instance

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

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

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

    The ESMAC screen is displayed.

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


To Shut Down a Server from ESMAC

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

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

To start ESMAC:

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

    The Details screen for the server is displayed.

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

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

To shut down a server

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


Viewing Enterprise Server Instance Details

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

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

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

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

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

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

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

Parent topic: Administering Enterprise Server Instances using ESMAC


The ESMAC User Interface

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

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

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

Figure 1. ESMAC Server information page
ESMAC Server information page

ESMAC enables you to:

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

The ESMAC interface is split into two areas:

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


Sidebar

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

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

Parent topic: The ESMAC User Interface


Body

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

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

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

Parent topic: The ESMAC User Interface


Status Line

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

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

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


Defining Enterprise Server Instance Administrators

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic describes how to set up the users who can access Enterprise Server administration, and set the appropriate permissions for those users.

The default security access configuration depends on how your system is set up. A system can be set up with or without the special user mfuser defined:

  • If mfuser is not defined, by default all users can perform any action.

    For an installation used for development, 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


Managing an Enterprise Server Instance's SEPs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can view details of the SEPs running in an enterprise server instance using ESMAC. You do this using the Control page, which can be displayed by clicking Control on the ESMAC menu.

For example, you can view various information about an enterprise server instance, including the dump state. If you wanted to change the dump state, you would use the Control page.

The Control page enables you to veiw the following details:

  • The number of SEPs running on the enterprise server instance.
  • Dump and trace parameters, including the size of the auxiliary trace and dump file, the datasets to be used for dumps and traces, and so on.
  • Whether programs are reloaded each time they are invoked.
  • The trace control flags set.
  • The size of the data blocks passed across shared memory for HTTP output.
  • The timeout value that will be used for all users of the enterprise server instance who do not have a timeout value set for their user ID.

You can also shut down the enterprise server instance from this page, and you can obtain a dump of the server on shutdown.

  • About Service Execution Processes
  • To Change the Number of SEPs
Parent topic: Administering Enterprise Server Instances using ESMAC


About Service Execution Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Service execution processes are provided within an enterprise server. COBOL applications are executed within these service execution processes. For more information on service execution processes, see the section Service Execution Processes in the chapter Configuration in your Enterprise ServerConfiguration and Administration Guide.

You can view information on the SEPs running on an enterprise server by displaying the SEPs (Service Execution Processes) page. To do this, click SEPs in the menu.

The SEPs (Service Execution Processes) page displays details for all SEPs on the current enterprise server, including:

  • The process ID
  • The type of SEP
  • The task number
  • The number of services that have run in this SEP
You can also:
  • Terminate SEPs
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server for which you want to change the number of instances.

    The Server > Properties > General page is displayed.

  2. Specify the new number of instances in Service execution processes.
  3. Click OK.
Note: If the status of the server is "Started", you can also change the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server > Control page, specifying the new number in Requested service execution processes and clicking Update. The new processes will take a few seconds to appear in the list. However, any change you make here is temporary only; after you stop the server, the number of processes reverts to the number set on the Server > Properties > General page.
Parent topic: Managing an Enterprise Server Instance's SEPs
Parent topic: Work with Servers


Interacting with Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Programs running as services in an enterprise server can include ACCEPT FROM CONSOLE and DISPLAY UPON CONSOLE statements. When execution reaches a DISPLAY UPON CONSOLE statement, the display text is displayed in the console log, and the service continues. When execution reaches an ACCEPT FROM CONSOLE statement, the service pauses and asks for input using pages in ESMAC. You must provide the input in order for the service to continue executing.

  • To Reply to an ACCEPT FROM CONSOLE Statement
Parent topic: Administering Enterprise Server Instances using ESMAC


To Reply to an ACCEPT FROM CONSOLE Statement

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  1. Click Reply in the menu. You see a page listing all the current pending ACCEPTs. They are identified by PID (Process ID).
  2. Click Select next to the process that you want to reply to.
  3. Specify your reply in the Enter field, then click Reply just above it.
Parent topic: Interacting with Services


Stopping and Restarting an Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before stopping the Directory Server or shutting the machine down, you should stop all enterprise server instances that are running. When you stop the Directory Server using Enterprise Server Administration, there is an option to stop all servers first.

On system restart, unless Restore Servers on Startup on the Configure Options page is checked, the Directory Server does not automatically start any enterprise server instances that were not stopped before shutdown (and so are still marked as "Started" in the Directory Server repository). If the Server Monitor is enabled on the Configure Options page it will check whether these enterprise server instances are still active, and will mark them as "Not Responding" in the Enterprise Server Administration servers table on the Home page. Each enterprise server instance will then need to be restarted manually. You can do this by clicking Details and then clicking Start Server for each server.

If Restore Servers on Startup is selected, when Directory Server is restarted, it reads the list of servers that were previously marked as started, checks to see if they are running, and if not, attempts to restart them.

Parent topic: Configuring and Administering Enterprise Server Instances


Using the Command-line Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A number of commands are available for administering servers. You can run these commands from an application command prompt. For example to access the Windows application command prompt from a Micro Focus Visual COBOL installation, from the Start menu, select: > Tools > Product Name Command Prompt.

  • 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.
  • caspac
    The caspac command line utility enables you to initialize a PAC before it is started.
  • casperm.sh
    Prepares Enterprise Server for use.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
  • casutl
    An Enterprise Server utility program.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casdump [/res-name]
        [/d]
        [/f]
        [/i]
        [/b]
        [/udump-code]

Parameters:

/res-name | Name of the enterprise server to dump. Defaults to ESDEMO
/d | Do not lock shared memory
/f | Dump the FAQE chain
/b | Dump shared memory as a block
/udump-code | Sets the dump code for the dump

Dependencies:

To use this command:

  • You must have started the enterprise server named with the /r flag first.
  • You must be running under the same user ID as the enterprise server named with the /r flag. If the Directory Server was started as a system service, and the enterprise server was started using the Administration interface, then the enterprise server is probably running under the LOCAL_SYSTEM user ID, and this command will not work. For more information see the section Starting and Stopping the Directory Server in the chapter Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide.

Comments:

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casdup

Formats a system dump or auxiliary trace so that it is suitable for analysis.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casdup
       [/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


caspac

The caspac command line utility enables you to initialize a PAC before it is started.
Attention: This feature is in Early Adopter Product (EAP) release status. We will continue the development of additional features and provide additional interfaces via patch updates and future releases. Please contact Micro Focus SupportLine if you require further clarification.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use caspac to specify new binaries to be loaded into a PAC, binaries to be deleted from a PAC, or to list loaded binaries.

Syntax:

caspac -a{action}=object -s{store} [-u{userid}] [-p{password}]

Parameters:

-a
Specifies the action to perform and the object it will be performed on.
action
Specifies the action to perform and can take one of these values:
  • Load
  • Delete
  • List
  • InitPac
object
Specifies the object the action is to use and can take one of these object types, a DLL, share object, or PAC name.
Note: The object name is case-sensitive.
-sstore
Specifies the store and its connection parameters to use. his is the scale-out repository type and connection parameters to use. For example:
redis,127.0.0.1:6741
-u{userid}
Optional, authorization user ID.
-p{password}
Optional, authorization password.

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 -aLoad="c:\new files\acct.dll" -sredis,127.0.0.1:6741 -uSYSAD -pSYSAD
  • 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. All programs that were uploaded can be deployed to all active enterprise server instances in the PAC using a New Copy command:
    caspac -aLoad="c:\new files\*.*" -sredis,127.0.0.1:6741 -uSYSAD -pSYSAD
  • The following example removes acct.dll from the SOR represented by the Redis server located at 127.0.0.1 on port 6741:
    caspac -aDelete=acct.dll -sredis,127.0.0.1:6741 -uSYSAD -pSYSAD
  • The following example lists user programs that have been uploaded into the SOR:
    caspac -aList=* -sredis,127.0.0.1:6741 -uSYSAD -pSYSAD
  • 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 -uSYSAD -pSYSAD
Parent topic: Using the Command-line Interface


casperm.sh

Prepares Enterprise Server for use.

Syntax:

casperm.sh

Parameters:

None

Comments:

The casperm.sh command asks you a series of questions. For further information, refer to To run casperm

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands
Related tasks
To Run casperm


casstart

Starts an enterprise server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casstart [/res-name] [/uusername] [/ppassword] [/cgroup] [/wseconds] [/sstart-type] [/mhost:port]

Parameters:

/res-name | Name of the enterprise server to start. Defaults to ESDEMO
/uuserid An authorized user. This user must exist within the security domains of both the enterprise server and 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.

/wseconds

Introduces a delay (in seconds) to the end of the startup process, to allow other essential processes for the 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. This option specified without the seconds argument introduces a default 15-second delay.

/sstart-type Where start-type can be w for warm or c for cold. This option is used to start enterprise server instances that are part of a PAC. Only the first enterprise server instance started in a PAC can be cold started.
Note: It is not mandatory to cold start the first enterprise server in a PAC.
The remaining enterprise server instances that are part of the PAC should be performed as warm starts. See Starting a PAC for more information.

Prior to cold starting a PAC, the following caspac command should be issued:

caspac -aInitPac=pacname -stype,host:port
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.

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 /w30" 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casstop [/res-name] [/sprototype:host:WebServiceport] [/lserver-name] [/i] [/w] [/f] [/uuserid] [/ppassword] [/ggroup]

Parameters:

/res-name Name of the enterprise server to stop. Defaults to ESDEMO. To use this option:
  • You must have started the enterprise server named with the /r flag first.
Note: When calling this utility from a Web service (that is, when you are running the utility within a SEP) you cannot use the /r option to connect to the server. Where this is the case, you must use the /s or /l options to connect to the server.
or:
/sprototype:host:WebServiceport | Location of the Web Services listener for the enterprise server to be stopped. For example, /stcp:localhost:9003
or:
/lserver-name | Name of the enterprise server. This differs from the /s option, in that it performs a lookup to locate the Web Service for the enterprise server
/i Immediate shutdown

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.

Note:
  • Options /r, /s, /l are alternative ways of identifying the enterprise server to be stopped and are mutually exclusive.
  • Where an external security manager is configured for the enterprise server, a userid and password must be supplied when stopping it.

Comments:

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

Many of the command line utilities, including casstart, casstop, casfile, casout, and cassub, can be invoked by program using the call interface and passing the command line parameters to the call. For an example, see casstart.

Return Code:

If a serious error occurs, a value of 15 will be set in the return code; other, lower values may also be returned. A message explaining the error is displayed on stdout and the console log. If you are calling casstop from within your own application program, then the message is displayed only on the console log.

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casutl

An Enterprise Server utility program.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casutl [/res-name]
       [/sprototype:host:port]
       [/lservername]
       [/n]
       [/xfiles-to-switch]
       [/ccurrent-directory]
       [/uuserid]
       [/ppassword]
       [/ggroup]
       [/h{[e|d]}]
       [/te{[ tracelist],[aux],[all],[ims]}]
       [/td{[ tracelist],[aux],[all],[ims]}]
       [/a{[amax|admin]=nnn}

Parameters:

Table 1. Connection parameters
/res-name

Connects to an enterprise server with the specified name, es-name.

Restriction: When calling casutl 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 | Specifies an authorization user ID.
/ppassword | Specifies an authorization password.
/ggroup | Specifies the sign-on group to use when running commands.
/h{[e|d]} | Enables (e) or disables (d) HSF.
/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.

/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.

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.

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

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


Configuring Client-Server Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A communications process is the component of an enterprise server instance that handles communications between clients and the enterprise server instance. It contains a number of service listeners. An enterprise server instance is created with one communications process, but you can add more.

A service listener accepts incoming client requests on behalf of services. A service can have multiple listeners, and a listener can accept client requests on behalf of multiple services.

  • About Communications Processes
  • Considerations When Configuring Communications Processes
  • Displaying Communications Process and Listener Information
  • Securing Communications
  • Configuring Communications Processes
  • Configuring Listener Conversation Types
  • Configuring Listeners
  • Conversation Filtering
Parent topic: Enterprise Server configuration and administration


Considerations When Configuring Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Multiple communications processes

If you are configuring multiple communications processes for an enterprise server instance, you need to consider the following:

  • You can configure different communications processes for different types of communications, for example, one communications process for TN3270 traffic and another for Web Services and ESMAC. With this sort of configuration, a failure in one communications process does not disrupt others, so other types of communications are not affected.
  • You can also run multiple communications processes for the same kinds of clients, configuring some clients to connect to one port and other clients to connect to a different port.
  • Communications processes cannot share ports. If you use fixed ports for your communications listeners, each listener must have a different port assigned to it if they will be running at the same time.
  • There is no support in Enterprise Server for failing conversations over from one communications process to another.

Other considerations

  • Some clients, such as Rumba+ 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for communications processes and listeners by clicking Details on the Home page in the Communications Process column for the enterprise server instance that you are interested in. The communications process and listener table is shown below.

Figure 1. Communications Processes and Service Listeners Table
Communications Processes and Service Listeners Table

The information for a communications process is as follows:

  • Auto-start - whether or not the communications process is started automatically when the enterprise server instance starts.
  • Listeners - the number of listeners owned by this communications process.
  • Process ID - the process ID of this communications process. This is present only when the communications process is running.
  • Control Channel Address - this is an internal address used by enterprise server instance components for communications. An asterisk at the end of the IP address or port number indicates that this part of the address is not fixed but supplied by the host system on startup.
  • Status information - you can see the current status and the time of the last status change.
  • Status log - this supplies information about the most recent event that occurred for this communications process.
  • Version - this is the version number of the communications process software.

Communications processes do not have names; instead they have sequence numbers. The communications process that is automatically created when you add a new enterprise server instance is Communications Process 1, and any further communications processes that you create are numbered in ascending order of creation. When you delete a communications process, existing communications processes are not renumbered, however, the next communications process you create will use the same number as the process that was deleted - the lowest available number.

The information for a listener is as follows:

  • Name
  • Address - this is the network address on which the listener listens for incoming client requests. An asterisk at the end of the IP address or port number indicates that this part of the address is not fixed but supplied by the communications process on startup.
  • Status information - you can see the current status and the time of the last status change
  • Status Log - this supplies information about the most recent event that occurred for this listener
  • Conversation Type - this indicates what type of client requests the listener handles. Possible values are:
    • Web Services and J2EE for SOAP or J2EE requests
    • Web for World Wide Web (HTTP) requests; Enterprise Server uses a Web listener for service deployment
    • Fileshare for Fileshare client requests
    • Custom for any other type of requests
  • Custom configuration data - for more information see the section Configuration Information
  • Description

Listener display filters control how much listener information you can see. These appear just above the information for the first communications process. There are three listener display filters:

  • Process (communications process)
  • Conversation type
  • Status

Each has a number of options that vary depending on the field; for example the Process filter allows you to select to see no listener details, all listener details, or listener details for a particular communications process, while the Status filter allows you to see all listener details regardless of status or just listener details for listeners with a specifc status:

For example, to see listener details for communications process 2, choose 2 in Listener Display Filters Process; to see only Web Services and J2EE listeners, choose Web Services and J2EE in Listener Display Filters Conversation Type; to see all listener details choose All in all three filters. Use all the filters in combination to achieve the maximum control over the level of detail you see.

When you first see the Communications Process and Listeners table, the Process filter is set to None and the other filters are set to All.

Parent topic: Configuring Client-Server Communications
Related information
Configuration Information


Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are a number of additional configuration options, for logging and setting an SSL passphrase, that can be set in the file mf-server.dat, located in $COBDIR/etc . These are mostly options that require setting before the Micro Focus Communication Server (MFCS) contacts the MF Directory Server. In the case of logging, this can be useful where there are problems with the connection between MFCS and MFDS. For instructions on the use of mf-server.dat to configure logging for MFCS, see the topics on securing communications in the Security section, or see the topic Communications Process Log Files in the Troubleshooting section.

Parent topic: Configuring Client-Server Communications


Configuring Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your responsibilities as administrator include:

  • Adding communications processes as required, by copying and editing existing ones
  • Updating and deleting communications processes as required
  • Starting and stopping communications processes
  • Adding, updating and deleting listeners as required
  • Associating listeners with services and disassociating them
  • Starting and stopping listeners
Note: You can use the Configuration Information field on the Edit Communications Process page, and the Add Listener and Edit Listener pages for configuration data specific to a communications process or a listener.
  • Editing Communications Settings
  • To Edit a Communications Process
  • To Copy a Communications Process
  • To Delete a Communications Process
  • To Start a Communications Process
  • To Stop a Communications Process
  • To View Communications Processes and Listeners for an Enterprise Server Instance
  • To View Statistics for a Communications Process
Parent topic: Configuring Client-Server Communications


Editing Communications Settings

Restriction: This topic applies only when the Enterprise Server feature is enabled.
The Configuration Information field on the Edit Communications Process page can contain the following sections and settings:
[CCI]
timeout-grain=timeout-grain-number-of-seconds
[ezasoket]
exclusive-bind=bind-setting
select-poll-interval=time-in-milliseconds
share descriptors=share-setting
[HTTP]
maximum header value length=bytes
[ISC]
listener-wait=listener-wait-number-of-seconds
[listeners]
logging=logging-level
[MFCC]
trace=trace-setting
[tasks]
maximum latency=time-in-seconds
mutex sweep enabled=yes-or-no
thread limit=number-of-pool-threads
trace=trace-level
wait queue sweep interval=time-in-seconds
[threading]
limit=number-of-threads

The sections, settings and their parameters are explained below.

  • [CCI] section
  • [ezasoket] Section
  • [HTTP] Section
  • [ISC] Section
  • [listeners] Section
  • [MFCC] Section
  • [tasks] Section
  • [threading] Section
Parent topic: Configuring Communications Processes


[CCI] section

  • timeout-grain
    Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.
Parent topic: Editing Communications Settings


timeout-grain

Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

timeout-grain=timeout-grain-number-of-seconds

Properties:

Default: 5 seconds

Comments:

The communications process (MFCS) lets each conversation and listener set its own timeout value for receiving data, but because MFCS runs as part of CCI, and CCI only maintains one global timeout value for the whole process, the granularity of MFCS timeout values is limited by the CCI timeout setting. Setting a larger value than the default will make MFCS timeouts less precise, but will reduce CPU consumption, interrupts, and other factors, improving performance.

Parent topic: [CCI] section


[ezasoket] Section

This section enables you to specify options for Mainframe Subsystem EZ Sockets processing.

  • exclusive-bind
  • select-poll-interval
    Specifies the time in milliseconds between the checks for taken sockets and posted ECBs in the SELECTEX function.
  • share descriptors
Parent topic: Editing Communications Settings


exclusive-bind

Restriction:
  • This option only applies in Windows environments.
  • These options apply only when the Enterprise Server feature is enabled.

Syntax:

exclusive-bind=on|off

Parameters:

Off
Use the normal Winsock semantics for BIND which lets one application bind a port even if the port is already in use.
On
Specifies that the BIND semantics of the mainframe, and every other non-Windows platform, are in effect and BIND will be rejected ports that are already in use.

Properties:

Default: on
Parent topic: [ezasoket] Section


select-poll-interval

Specifies the time in milliseconds between the checks for taken sockets and posted ECBs in the SELECTEX function.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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


[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), CICS Web Interface, 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


[ISC] Section

Parent topic: Editing Communications Settings


[listeners] Section

  • logging
    Enables additional logging when starting listeners.
Parent topic: Editing Communications Settings


logging

Enables additional logging when starting listeners.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

logging=logging-level

Parameters:

logging-level
Can be one of:
0
No extra logging (default)
1 or Yes
Basic logging, which includes extra CCI error information
2
Also log CCI loading and configuration, and listener address information
3
Also log SSL configuration

Properties:

Default: 0
Parent topic: [listeners] Section


[MFCC] Section

  • trace
    Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.
Parent topic: Editing Communications Settings


trace

Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 $COBDIR/etc , but you can create your own configuration file of any name or location and identify it using the MFC_CONFIG environment variable.

MFCS uses MFCC during startup to verify that its control channel is working. If MFCC tracing is enabled in the configuration file, you can set this option to "0" to disable MFCC tracing in MFCS. Alternatively, you can set it to a non-zero value to enable MFCC tracing during MFCS startup, to diagnose a failure there.

Parent topic: [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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

mutex sweep enabled=yes-or-no

Properties:

Default: yes

Comments:

This sweep is a defensive measure that is normally performed at the end of each task. It checks to verify that the task does not end with any mutexes locked. A locked mutex at that point can only be the result of a logic error. The sweep ensures that such an error does not block the processing of any new requests.

Normally, it is not recommended to change this setting. In cases when there is a very busy enterprise server instance, however, the sweep may cause MFCS to fall behind in task processing, causing a gradual drop in throughput. In such cases, you can set this to "no" to try to alleviate the problem.

Parent topic: [tasks] Section


thread limit

Sets the number of threads in the task thread worker pool.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

limit=number-of-threads

Properties:

Default: 2000 on Windows and 200 on UNIX

Comments:

MFCS limits the number of threads it will try to start, in order to avoid exceeding system limits.

Starting with MFCS version 2.0, MFCS no longer requires one thread for each active conversation. Because of this, so it is rarely necessary to change this value. For more details, see the topic on the thread limit setting in the [tasks] section.

Note that the operating system might not allow MFCS to actually create as many threads as the number you set.

Parent topic: [threading] Section
Related reference
thread limit


To Edit a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to edit.
  3. On the Edit Server - Listeners page click Edit to the left of the row for the communications process you want to edit.
  4. Update the attributes of the communications process as required.
  5. Click OK.
Note: You can make some changes to a communications process on the Edit Server - Listeners page: toggle Auto-start, and stop and start the communications process.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Copy a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to copy.
  3. On the Edit Server - Listeners page click Copy at the top right-hand side of the area that shows the details of the communications process you want to copy.
  4. In Control Channel Address specify a host name or IP address to replace the first asterisk (*) and a port number to replace the second asterisk. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number.
  5. Check Auto-start if you want the new communications process to be started automatically when the enterprise server starts or, if the enterprise server is already running, after it is created. It is checked by default.
  6. Click OK.
Note: When you copy a communications process, you also copy all the listeners associated with it; the new communications process has exactly the same number and type of listeners as the original, with the same names. You might want to edit the names to reduce confusion.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Delete a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server > Listeners page click Delete at the top right-hand side of the area that shows the details of the communications process you want to delete.
  4. Click Delete on the confirmation page.
Note: If an enterprise server has only one communications process, you cannot delete it.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Start a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking
    expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server - Listeners page click Start at the top right-hand side of the area that shows the details of the communications process you want to start.
Note:
  • You can start a communications process only if:
    • The enterprise server is started.
    • The status of the communications process is "Stopped".

    When an enterprise server starts, any stopped communications processes are started automatically if Auto-start is set on.

  • When a communications process starts, all the service listeners it owns start too.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Stop a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server - Listeners page click Stop at the top right-hand side of the area that shows the details of the communications process you want to stop.
Note:
  • You can stop a communications process only if:
    • The enterprise server is started.
    • The status of the communications process is "Started".
  • When a communications process stops, all the service listeners it owns stop too.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To View Communications Processes and Listeners for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose listeners you want to view.
  3. If you can't see the listeners, choose All from the list of options in Listener Display Filters Process.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To View Statistics for a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to view statistics for. This server must have been started already.
  3. On the Edit Server - Listeners page click Statistics at the top right-hand side of the area that shows the details of the communications process.

    The Statistics are displayed in a new Web browser window.

Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


Configuring Listener Conversation Types

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A listener's conversation type is shown in the Conversation Type column on the listener configuration page.

The available configuration settings for a listener are grouped 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.

  • Fileshare conversation type
  • SOAP /J2EE (legacy) conversation type
  • Web conversation type
  • Web Services /J2EE conversation type
Parent topic: Configuring Client-Server Communications


Fileshare conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Fileshare connector checks these settings at the beginning of each conversation. Changes to them will take effect for subsequent conversations.

[Operation]
timeout=number-of-seconds
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

control=control-flow-trace

Parameters:

control-flow-trace Set to "yes" to trace various connector activities, such as passing a request to an enterprise server

Properties:

Default: Control flow tracing is disabled
Parent topic: Fileshare conversation type


data

Enables the tracing of sent and received data.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

data=data-trace

Parameters:

data-trace Set to "yes" to include data in the trace

Properties:

Default: Data tracing is disabled.
Parent topic: Fileshare conversation type


file

Specifies the full path of the file to receive trace messages.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

file=pathname

Properties:

Default: Trace messages are written to the MFCS log (as HTML)
Parent topic: Fileshare conversation type


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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

synchronous=yes|Yes|y|Y|1
Parent topic: Fileshare conversation type


timeout

Sets the timeout, in seconds, for receiving data from the client.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

timeout=number-of-seconds

Properties:

Default: Timeout for the communications process, which is 7200 seconds (two hours)
Parent topic: Fileshare conversation type


SOAP /J2EE (legacy) conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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


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: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services /J2EE conversation type


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 Micro Focus Customer Care.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services /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 /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 /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 /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.
Note: You should only configure this when instructed to do so by Micro Focus Customer Care.
Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services /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 Micro Focus Customer Care.
Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services /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 /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 Micro Focus Customer Care.

Parent topic: SOAP /J2EE (legacy) conversation type


Web conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

logging=logging-level

Parameters:

logging-level
Can be one of:
yes or 1 | Log various information while processing web requests, including path translation and CGI program execution
any other value | No logging

Properties:

Default: No logging
Parent topic: Web conversation type


default

Specifies the directory to which unrecognized URL top-level path elements will be mapped.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

default=default-directory

Properties:

Default: /dev/null

Comments:

The default directory must not exist, so that when the communications process translates the URL into a full path, the request will fail.

Parent topic: Web conversation type


element in [virtual paths] Section

Specifies the file-system path to which element will be mapped.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

 element=file-system-path

Parameters:

element The file-system path that element will be mapped to. element must be the top-level (first) element in the URL’s path. Some special tokens can be specified at the beginning of the value:
<ES>: | Replaced with the path to the base installation directory on Windows, or $COBDIR on UNIX
<ASEE>: | Historical synonym for ES.
<$name>: | Replaced with the contents of environment variable name
Parent topic: Web conversation type


element in [allow] Section

Lists one or more filenames or wildcard pattern specifications, separated by spaces, which the connector is allowed to serve for files on this virtual path.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

element=list-of-filenames

Parameters:

element | The file-system path that element will be mapped to.
list-of-filenames | Zero or more filenames or filename patterns, separated by spaces. Only files which match one of these filenames will be served. You can use the wildcards "?" (matches any one character) and "*" (matches zero or more characters).

Properties:

Default: Permit serving all files
Parent topic: Web conversation type


Web Services /J2EE conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Web Services /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
  • 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.
Parent topic: Configuring Listener Conversation Types


Configuring Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section covers the tasks involved in creating and configuring service listeners.

  • To Add a Service Listener to an Enterprise Server Instance
  • To Edit a Listener
  • To Associate a Listener with a Service
  • To delete a listener
  • To Disassociate a Listener from a Service
  • To Start a Listener
  • To Stop a Listener
Parent topic: Configuring Client-Server Communications


To Add a Service Listener to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server to which you want to add the listener.
  3. Click Add in the Listeners column for the communications process to which you want to add the listener.
  4. Specify a name for the service listener in Name.
  5. In Endpoint Address specify a host name or IP address to replace the first asterisk (*) and a port number to replace the second asterisk. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number. Endpoint Protocol is always TCP.
  6. Choose an initial status from the list in Initial Status. Usually you should choose "Stopped".
  7. Click one button to choose a Supported Conversation Type for the listener:
    • Web Services / J2EE for client requests that use either of the conversation protocols supported by the Micro Focus request handlers, MFRHBINP and MFRHSOAP
    • Web for World Wide Web (HTTP) requests; Enterprise Server uses a Web listener for service deployment
    • Fileshare for Fileshare client requests
    • Custom can be used for any other type of requests. You can select whethr or not to use Legacy Micro Focus Application Format.
  8. If you clicked Custom in step 6, enter the name of the connector module for this type of request in the entry field next to Custom.
  9. Specify any configuration information the listener requires in Configuration Information.
  10. Specify a text description of the listener in Description (optional).
  11. Click Add.
Note: You can also reach the Add Listener page by clicking Edit to the left of the server to which you want to add the listener, clicking the Listeners tab and clicking Add.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Edit a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to edit.
  3. If you can't see the listener you want to edit, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to edit.
  5. Update the attributes of the listener as required.
  6. Click OK.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Associate a Listener with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Objects column for the server that owns the service that you want to associate the listener with.
  2. Click Edit in the Operation column of the row containing the service that you want to associate the listener with.
  3. In Available Listeners click the service listener that you want to associate with the service.
  4. Click Add.

    The Directory Server associates the listener with the service immediately and redisplays the service table.

  5. If you want to associate another listener with this service, repeat steps 3 through 5.
Note: A service must always have at least one listener associated with it.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To delete a listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to delete.
  3. If you can't see the listener you want to delete, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to delete.
  5. Click Delete.
  6. Click Delete on the confirmation page.
Note:
  • You cannot delete a listener if it is the only listener for a communications process.
  • You cannot delete a service listener if it is associated with any service.
  • You cannot delete the deployment listener called Web that is created automatically when you create a new enterprise server.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Disassociate a Listener from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details at the bottom of the Objects column.
  2. Click Edit in the Operation column for the row containing the service from which you want to disassociate the listener.
  3. In Associated Listeners click the service listener that you want to disassociate from the service.
  4. Click Remove.

    The Directory Server disassociates the listener from the service immediately and redisplays the service table.

  5. If you want to disassociate another listener from this service, repeat steps 3 through 5.
Note: A service must always have at least one listener associated with it.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Start a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to start.
  3. If you can't see the listener you want to start, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to start.
  5. Click Started in New Status.
  6. Click OK.
Note: You can start a listener only if the server is started. When a server starts, any stopped listeners are started automatically.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Stop a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to stop.
  3. If you can't see the listener you want to stop, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to stop.
  5. Click Stopped in New Status.
  6. Click OK.
Note: You can stop a listener only if the server is started. When a server starts, any stopped listeners are started automatically.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


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 would be deny:**.

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


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 Enterprise Server Administration Web interface. Specify the rules in the Configuration Information field, in any or all of the following locations:

  • The Server page (c000), on the General tab:
    1. On the Enterprise Server Administration home page, click Edit in the row that corresponds to the region you want the rules to apply to.
    2. Click the General tab.
    3. In the Configuration Information field, type the filter rules you want to apply.
    4. Click Apply.
  • The Listener page for the communications process control listener (c400). This is the first listener listed on the Listeners tab for each communications process:
    Note: Rules configured here apply to all listeners in the communications process.
    1. On the Enterprise Server Administration home page, click Details in the Communication Process cell for the region whose communication process you want the rules to apply to.

      This opens the Listeners page.

    2. Click Edit, in the top left cell.
      Note: Most servers only have a single communications process.

      This opens the Communications Process page.

    3. In the Configuration Information field, type the filter rules you want to apply.
    4. Click OK.
  • The Listener page for each individual listener (l301):
    1. On the Enterprise Server Administration home page, click Details in the Communication Process cell for the region that owns the listener you want the rules to apply to.

      This opens the Listeners page.

    2. In the Listeners column, click Edit that correspond to the listener you want the rules to apply to.
    3. In the Configuration Information field, type the rules to apply to the listeners.
    4. Click Apply.
    5. Click OK.

In the Configuration Information 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 three 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.**.
  • 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, *.microfocus.com.
Note: Enterprise Server does not support IPv6, so there is no provision for IPv6 addresses.

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 may 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.

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.

  • Non-Mainframe Programs and WebSphere MQ
    Details how to configure Enterprise Server for non-mainframe programs under WebSphere MQ.
  • Resource Classes for WebSphere MQ
  • WebSphere MQ-Specific Environment Variables
Parent topic: Enterprise Server configuration and administration


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
  • Profiles for Queue Security
  • Process Profiles
  • Profiles for Alternate User Security
  • Profiles for Context Security
Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Parent topic: Resource Classes used by Enterprise Server


Monitoring Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Server Instance Statuses
  • Monitoring the Directory Server
  • Collecting and Viewing Data on Transactions
Parent topic: Enterprise Server configuration and administration


Server Instance Statuses

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server instance can have any of the following statuses:

Stopped | The server is currently not running.
Stopping | The server is currently in the process of terminating. This is normally a short-lived status value which should be shortly followed by a change to the value "Stopped".
Started | The server is currently running and can respond to client and server requests. At least one communications process is started.
Starting | The server is currently in the process of starting. This is normally a short-lived status value which should be shortly followed by a change to the value "Started".
Not Responding The server process was previously marked as "Started", but the server monitor has subsequently not been able to contact it. There may be some network connection error, or the server itself may have abnormally terminated without first marking itself as "Stopped".

If network communications are restored, and the server is still running, and the server monitor is on, then the server will be remarked as "Started" when the server monitor next checks whether the server is active.

The server might have encountered an unrecoverable communications error and the server process remains active, in which case you can shut it down by using Stop Server on the Server Details page.

The server might have encountered an unrecoverable communications error, that is, all the communications processes are inactive or not responding. If this happens, the server process shuts down. You can start it by using Start Server on the Server Details page.

Invalid | An error has occurred such that it has not been possible to set the status to any other value.

A CCI Server can only have the status Registered. This status indicates that the Directory Server has been notified that a CCI server has started. When the server stops, it deregisters itself and disappears from the list of servers.

Parent topic: Monitoring Enterprise Server


Monitoring the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the facilities for monitoring the activities of the Directory Server.

  • Starting and Stopping the Directory Server
  • Displaying Server Information
  • Accessing Remote MF Directory Servers
  • Monitoring Facilities
Parent topic: Monitoring Enterprise Server


Starting and Stopping the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to access the Enterprise Server Administration user interface, the Directory Server must be running.

In a UNIX environment, depending on how Enterprise Server has been installed, either you can use the mfds command to start it, or it can start automatically when the machine is started.

To stop the Directory Server, you use a menu option on the Web interface.

To access the Directory Server using the Web interface, you start a Web browser and enter the address where the Directory Server is running.

Depending on how the Directory Server has been configured, and what you want to do, you might require a user ID and password. What you see and what you can do using Enterprise Server Administration depends on the security configuration settings and the permissions granted to your user account.

  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
  • To Delete the Repository
  • To Import a Repository
  • To Restore the Repository
  • To Export the Repository
Parent topic: Monitoring the Directory Server


To Start the Directory Server from the Command Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If you are running Directory Server on UNIX, log in as root.
  2. Enter:
    mfds /param

    where param can be:

    d | Show debug information
    j journal-path | Override the journal path
    k | Use SSL and specify SSL certificate, keyfile and password
    n network-address Bind to specific adapter.
    Note: You can use the CCITCP2_PORT environment variable to bind to a non-standard port, but this option should be used with caution, as many programs depend on Directory Server using the default port (86).
    o | Specify alternate MFDS options file
    r | Refuse access to the Enterprise Server Administration interface
    z | Override initial repository location
  3. In addition to options for starting Directory Server, the mfds command also provides a number of other options for reporting and exporting information, and stopping the server.
    c | Install as a service: show debug console
    e | Export MFDS user information to an LDIF file
    i | Install as a service: do not show debug console
    l | Export MFDS schema as an LDIF file
    m | Display current repository path
    s | Request controlled shutdown
    u | Remove as a service
    v | Show version information
    t | Convert journal file to text format
    x | Export repository data
    g | Import repository data
Note: The command to start the Directory Server can be inserted into your startup shell script; then the Directory Server will be started automatically when the machine is started. The mfds command must be inserted after the command to start up TCP/IP, because Directory Server needs TCP/IP to be running. If the command has been added to your startup shell script you would normally need to start the Directory Server only if you had shut it down since you started the machine. The startup script should also set up your environment. For more information see the section Starting Directory Server for the First Time in your Configuration and Administration Guide.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Stop the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: You can leave Directory Server running all the time, whether or not you are using Enterprise Server Administration. You should not shut down Directory Server if servers are started.

From the command line

Enter:
mfds -s
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Delete the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

When you click Delete, all information in the current repository is deleted. If you have currently active clients and services, this will cause client application connection errors and loss of data.

  1. Click Delete All under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. If you are sure you want to delete the repository, click OK. Otherwise click Cancel.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Import a Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Import under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location of the repository that you want to import in Source directory containing server data to restore. By default, this is $COBDIR/etc/mfds.

    A list of recently used locations is supplied. Choosing an item from this list and clicking Select puts the value into Source directory containing server data to restore.

  3. Click Next and follow the screen prompts.
Note: When you import, you have the option of excluding any server that has the same name as one already present in the repository. Where the export contains security information, you also have the option of including or excluding it. See the context help for details.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Restore the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Restore under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location from which you want the repository to be restored in Source directory containing server data to restore. This defaults to $COBDIR/etc/mfds.
  3. Choose whether you want to set the status of all restored servers to "Stopped", or to whatever they were when the servers were last saved, by clicking one of the radio buttons under When restoring servers.
  4. Check restore even if source repository is a duplicate, in part or whole, of the current one if you want server data to be restored even if all the server names in the backup repository are duplicates of server names in the current repository.
  5. Click OK.
Note: You can go back to the repository as it was when Enterprise Server was originally installed, by restoring from the /IVP subdirectory of $COBDIR/etc/mfds.
Warning: If you want to keep the information currently in the repository make sure you have saved it before you restore. When you restore the repository all the information in the repository is overwritten with the restored data. This might cause application connection errors and loss of data.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Export the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Export under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location where you want to save the repository in Export information to this directory. This defaults to $COBDIR/etc/mfds.
  3. Choose the export option that you require and click OK.
    Note: If the target directory contains previously exported information, you will be presented with a confirmation page. This page will show the contents of the target directory. Proceeding with the export will overwrite previously exported details.
Note:
  • We recommend that you export the repository only when all the registered servers have a status of "Stopped".
  • When exporting to a file system location, if you specify a directory that does not exist, it will be created if the directory containing it exists, otherwise it will not be created and the export will fail.
  • Export enables you to export either: server definitions only, Security Manager definitions only, or server definitions and all related security configuration information.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


Accessing Remote MF Directory Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Providing you have sufficient authorization, you can log on to remote MF Directory Servers and administer the installations they maintain. You can display all directory servers accessible from your network that are listening on port 86.

  • To View and Use Remote Directory Server Instances
Parent topic: Monitoring the Directory Server


To View and Use Remote Directory Server Instances

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Directories on the menu on the left-hand side of the Enterprise Server Administration Web page.

    Enterprise Server searches the network for all MF Directory Servers that use port 86, and displays a list of the MF Directory Servers that it finds.

  2. Click the right-pointing arrow in the DNS Resolved Hostname column for the remote machine that you want to view.

    A new browser window opens at the home page of Enterprise Server Adminstration for the instance of Directory Server running on the other machine.

Parent topic: Accessing Remote MF Directory Servers
Parent topic: Monitor Directory Server


Monitoring Facilities

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Administration provides four facilities for monitoring the activities of the Directory Server:

  • The Directories Page
  • Viewing a MF Directory Server's Statistics
  • Viewing a MF Directory Server's Sessions List
  • Viewing the Journal
Parent topic: Monitoring the Directory Server


The Directories Page

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Directories page displays a table of all the other instances of Directory Server that are running on the local network and that are using the default Directory Server port (86). For each instance, it shows:

  • The version number of Directory Server
  • The IP address of the machine on which it is running
  • The DNS-resolved hostname of the machine on which it is running. Next to the hostname is a right-pointing arrow, which you can click to open a new Enterprise Server Administration window on your machine, giving you access to the other Directory Server and its objects without having to remember its IP address.
Note: You should take care to ensure that an appropriate level of security has been set up for all the instances of Directory Server on a local network, to reduce the possibility of unauthorised access using the Directories page. For more on security and the options available, see Introduction to COBOL Server Security.
Parent topic: Monitoring Facilities
Related reference
Securing an Enterprise Server Installation


Viewing a MF Directory Server's Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Statistics page displays statistics and other information about the Directory Server and the current activity on it. The information is of four types:

  • Repository location and status
  • Objects in the repository, subdivided into servers, listeners, services, request handlers and packages, with a total. The services number actually represents the number of service operations
  • Request processing statistics
  • Configuration options settings
  • File paths used by the Directory Server

You might find the information on this page helpful if you are experiencing problems, for example, if you deployed a service, but you cannot find it in the Services table, you can check whether the numbers of services and packages have changed.

  • To View Directory Server Statistics
Parent topic: Monitoring Facilities


To View Directory Server Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Statistics on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing a MF Directory Server's Statistics
Parent topic: Monitor Directory Server


Viewing a MF Directory Server's Sessions List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Sessions list is a list of all the Web browser client and program clients currently connected to the MF Directory Server. The sessions may be active, or they may be dormant but not yet removed because the time period between inactivity and removal has not yet been exceeded.

If user access is unrestricted (that is, if security has not been configured for Directory Server), only one Web browser client session is shown, with the Session ID "Developer".

If user access is restricted, individual sessions are shown for each Web browser client session user, identifed by unique user IDs.

  • To View the Sessions List
Parent topic: Monitoring Facilities


To View the Sessions List

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Sessions on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing a MF Directory Server's Sessions List
Parent topic: Monitor Directory Server


Viewing the Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Journal is a file that records some of the activity occurring on the MF Directory Server. It can track usage and help with support issues.

You can choose one of three levels of journaling:

  • Errors only (default)
  • Errors and warnings
  • All information. With this level there is a performance degradation. The scale of the degradation depends on many factors such as file system performance and client traffic; a system with a large number of highly active program clients suffers the most
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 the Micro Focus SupportLine.

You set the journaling level using the Configure Options page.

  • To View the Journal
  • To export the journal as a text file
  • To Delete Journal Entries
Parent topic: Monitoring Facilities


To View the Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing the Journal
Parent topic: Directory Server Journal
Parent topic: Monitor Directory Server


To export the journal as a text file

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Click Export as Text. The text file journal.txt will be created in the directory /var/mfcobol/logs . If the file already exists, it will be overwritten.
Parent topic: Viewing the Journal
Parent topic: Monitor Directory Server


To Delete Journal Entries

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Click Delete. A new journal is started.
Parent topic: Viewing the Journal
Parent topic: Monitor Directory Server


Collecting and Viewing Data on Transactions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can create records for tasks that have been executed and completed under Enterprise Server using the Historical Statistics Facility (HSF). These records can be written to a .csv file and also a limited number can be saved in memory to view in the Enterprise Server Monitoring and Control console (ESMAC).

The records contain information such as the ID of a user that initiates the task, the response time, and names of any files accessed.

Information is provided for the following resources:

  • Web services
  • Configuring and Starting Transaction Data Collection
  • Viewing HSF Information in ESMAC
  • Viewing HSF Information as a .csv File
  • Analyzing Aggregated HSF Data in .csv Files
Parent topic: Monitoring Enterprise Server


Configuring and Starting Transaction Data Collection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use HSF to collect data about transactions, you need to set a number of configuration options in Enterprise Server Administration. You can also use ESMAC to override these settings dynamically.

Note: In order to collect information on EXEC SQL statements, you need to compile the application with the HSFTRACE directive set.

To configure HSF

  1. Access the Enterprise Server Administration screen for your installation.
  2. Check that the server you want has stopped, and if not, stop it.
  3. In the Status column of the Enterprise Server to monitor, click Details.
  4. Select the Historical Statistics tab.
  5. Set the configuration options:
    Enable collection of Historical Statistics Facility (HSF) records
    This switches on HSF processing.
    Write to disk
    Enables writing of HSF records to comma-separated files. These are called cashsf-a.csv and cashsf-b.csv, and are written to the system directory. Only one file is written to at any one time - this is called the active file.

    You write to the active file until you click the ESMAC Switch button or when the active file reaches the maximum size, at which point the alternate file becomes active. If the alternate file already exists it will be backed up with the name cashsf.nnn where nnn is the number of the backup. When you start an enterprise server, cashsf-a.csv is always set as the active file, and if it already exists it is backed up.

    Backup extensions are numbered from .001 up to .999. When a backup with extension .999 exists then the next backup will be created as cashsf.001. If cashsf.001 already exists then it will be overwritten.

    Maximum HSF file size (KB)
    If you have selected Write to disk, this is the size in kilobytes the .csv file will reach before Enterprise Server switches to the alternate .csv file. A value 0 selects the maximum size possible (4 Gb).
    Number of records displayed by ES Monitor & Control
    The number of HSF records that Enterprise Server will hold in memory. These records can be viewed by clicking on the HSF button in ESMAC while the server is running. When this number is reached, older records will be deleted when a new one is created. Records older than one hour are deleted too.
    The minimum value is 0 (no HSF data displays in ESMAC), the maximum is 4096.

To reconfigure HSF while a server is running

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the Status column of the started Enterprise Server, click Details.
  3. Select the Server > Control tab and click ES Monitor & Control, then click Control.
  4. Set the configuration options. These are the same as those in the Enterprise Server Administration Historical Statistics tab described above apart from the following differences:
    Enable collection of HSF records
    To enable this option you must first either set Write to disk or enter a value in the Number of records to view field.
    Switch
    Clicking this button will switch collection to the alternate .csv file before the active file has reached the maximum size.
  5. Click Apply to start collecting the data.

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
To start an enterprise server instance


Viewing HSF Information in ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have enabled collection of HSF records and specified the number of records to collect in ESMAC, you can use ESMAC to view aggregated information on transactions, and details of individual runs of those transactions.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view the transaction information:

  1. Click the HSF button.

This shows the period of time (displayed in minutes and seconds next to Historical Statistics) between the earliest records displayed and the current time. Records older than one hour are deleted. The following information is shown for each transaction:

Average Latency
The average time, in hundredths of a second, between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in hundredths of a second, that the tasks ran for (not including latency time).
Count
How many times the task has run.

By clicking on the magnifying glass icon [image] next to a task you get a detailed view of the individual runs.

Latency+Resp
The sum of latency and response time averages.
Transaction
The name of task:
  • for Web services, the service name
Process ID
Process ID of the SEP which ran the task.
Task Number
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Parent topic: Collecting and Viewing Data on Transactions
Related information
To start an enterprise server instance


Viewing HSF Information as a .csv File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have enabled the collection and writing of HSF records to disk, 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=03;Custom=xx;CicsFiles=xx;TSQ=xx;TDQ=xx
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

For example: ES_HSF_CFG=CUSTOM=2;CICSF=10;TSQ=32 generates 2 custom fields, 10 CICS file fields, 5 TSQ fields and 5 TDQ fields.

Important: HSF output from earlier versions of the product may either have no header, or start with:
#HSFVer=01 or 02

Some earlier .csv files (#HSFVer=01) do not have the DSType and DSAccessType fields, and either have this header:

#HSFVer=01
Type,PID,Task,Date,Time,Tran,User,LU,Prog,Latent,Resp,API,SQL,IMS,File1,Count1,Time1,File2,Count2,Time2,
File3,Count3,Time3,File4,Count4,Time4,File5,Count5,Time5,TS1,Count1,Time1,TS2,Count2,Time2,TS3,Count3,
Time3,TS4,Count4,Time4,TS5,Count5,Time5

or, without the IMS field:

Type,PID,Task,Date,Time,Tran,User,LU,Prog,Latent,Resp,API,SQL,File1,Count1,Time1,File2,Count2,
Time2,File3,Count3,Time3,File4,Count4,Time4,File5,Count5,Time5,TS1,Count1,Time1,TS2,Count2,Time2,TS3,
Count3,Time3,TS4,Count4,Time4,TS5,Count5,Time5

Field types

Type
The type of record. One of:
  • WEB - for Web services
PID
Process ID of the SEP which ran the task.
Task
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Tran/Job
The name of task:
  • For Web services, the service name.
Latent/ReadCount
  • The time, in hundredths of a second, between Enterprise Server receiving the request and the task beginning to run.
Resp/WriteCount
  • The time, in hundredths of a second, that the task ran for (not including latency time).
SQL/DeleteCount
  • The time spent, in hundredths of a second, in SQL API (EXEC SQL statements) for this task.
DSType
This field is blank for all records
DSAccessType
This field is blank for all records

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 hundredths of a second, 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 hundredths of a second, the transaction spent accessing TS xx.

Sample content viewed in Microsoft Excel

Parent topic: Collecting and Viewing Data on Transactions


Analyzing Aggregated HSF Data in .csv Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the statistics utility program, casfhsf, to output aggregated data from the .csv files created by the Historical Statistics Facility (HSF). casfhsf outputs this data as a comma-separated value file.

You can use the information to review system performance on a regular basis and avoid going through a large volume of data in order to determine if corrective tuning action is required.

Note: The .csv files do not have to be generated on the same platform as the one on which you run casfhsf.

Using the casfhsf statistics utility program

From the Visual COBOL command prompt, launch casfhsf32 or casfhsf64, depending on your environment.

The following switches are available. A dash may replace the slash, and switches can be upper or lower case.

Switch | Description
/A | Process only cashsf-a.csv.
/B | Process only cashsf-b.csv.
/C | Process both cashsf-a.csv and cashsf-b.csv (default).
/D | Process only backup files cashsf.nnn.
/E | Process all files: cashsf-a.csv, cashsf-b.csv, and cashsf.nnn.
/S{sd,st,ed,et} | Aggregate the output data by the second. Where {sd,st,ed,et} = yyyymmdd, hhmmss, yyyymmdd, hhmmss - start date, start time, end date, end time.
/M{sd,st,ed,et} | Aggregate the output data by the minute (default if error). Where {sd,st,ed,et} = yyyymmdd, hhmm, yyyymmdd, hhmm - start date, start time, end date, end time.
/IP | The location of the input files. The default value is the current directory.
/OP | The location of the path of the output file. The default value is the current directory. The output file is called OutFile.csv.

To aggregate certain transactions or programs, you may specify these using parameters in the form:

{type},{id}[[,{type},{id}]...]
The parameters are:
type
Transaction type:
  • WEB = a Web Service
id
The identifier of the service or program ID to be aggregated.

You can specify between zero and five type,id pairs. Each type must be separated from its corresponding id by a comma. If more than one pair is specified, each pair must be separated by a comma.

If no pair is specified, an aggregate of all transactions is accumulated in the first unallocated slot. The default behavior in this case is to aggregate all data in slot one.

An extfh.cfg file is generated in the current directory, if one is not already present, to allow large file inputs.

If no switches or parameters are specified, the utility will ask if you wish to continue using the default values.

Example
casfhsf32 /op"/opt/Micro Focus/logs"
Using the input defaults, this processes both cashsf-a.csv and cashsf-b.csv in the current directory, aggregates times (in minutes) for all transactions and programs, and creates the output file in the folder /opt/Micro Focus/logs.

The Output File

This is a comma-separated value file with the following header:
time,TPS,Latency,min,max,Response,min,max,System,min,max,API,min,max,SQL,min,max,IMS,min,max...
After the time field, the rest of the fields occur five times.
Field | Description
time | The time period in minutes (hh:mm format) or seconds (hh:mm:ss format) into which the input monitoring times are aggregated. The format is determined by the /S or /M switch.
TPS | The average number of transactions per second or minute.
Latency,min,max | The average latency - delay or waiting time - for this time period, and the minimum and maximum latency.
Response,min,max | The average time taken for Enterprise Server to respond to the transaction request, and the minimum and maximum response times.
System,min,max | The total of the average latency and response times (Latency + Response) , and the minimum and maximum totals of latency plus response time of a particular transaction run.
SQL,min,max | The average time, in hundredths of a second, spent in SQL API (EXEC SQL statements) for this task, and the minimum and maximum times.

There is also a secondary header depending on the parameters supplied to the utility.

If there are no parameters, then all the aggregate values are accumulated under "Everything", and the other four columns are marked as "Unused".

Versions of input files

This version of the product generates cashsf-n.csv files that start with the line:
#HSFVer=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.

Parent topic: Collecting and Viewing Data on Transactions


User Exits for Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes how to write user exit programs that allow you to customize the behavior of the Micro Focus MFRHSOAP request handler.

The Micro Focus MFRHSOAP request handler provides a number of user exit points, enabling you to supply a user exit program that can perform additional processing of input and output parameters.

You can also provide a user exit program for use with a custom request handler, if you find this approach offers advantages over including all the code you need in the request handler itself.

  • User Exit Points Provided
  • Structure Definitions and Type Definitions
  • Linkage Section Field Names
  • Deploying a User Exit Program
  • Web Service Exits
Parent topic: Enterprise Server configuration and administration


User Exit Points Provided

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following diagram shows the interaction between request handlers, the application container and the run-time interface mapper.

Figure 1. Request Handler Exit Points
Request Handler Exit Points
The user exit points are indicated by squares numbered from 1 through 9. The table below gives the name and purpose of the exit points.
Number | Name | Description
1 | External data value modification – input parameter | Enables you to modify the external data value specified in a client request before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
2 | Internal data value modification – input parameter | Enables you to override the internal data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
3 | Unmapped named external input parameter | Enables you to provide processing of any input parameters that do not have associated input parameter mappings defined in the IDT. This exit point is invoked for each unmapped named input parameter.
4 | End of input request processing | Enables you to set up parameter values other than the external parameters specified in the client request. It also provides the opportunity for any resources allocated in exit points 1 through 3 to be released.
5 | Start of response processing | Enables you to bypass completely the default mapping used to build a client response. The exit program is responsible for the creation of the response that will be sent back to the client by the application container.
6 | Internal data value modification – output parameter | Enables you to modify the internal data value as created by the user application before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
7 | External data value modification – output parameter | Enables you to override the external data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
8 | End of response processing | Enables you to modify the response generated by the default mapping.
9 | End of request processing | Enables you to release any resources that were allocated in exit points 1 through 8.
Parent topic: User Exits for Request Handlers


Structure Definitions and Type Definitions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To help COBOL and C programmers, we provide a COBOL copybook (cbltypes.cpy) and a C header file (svext.h) with COBOL Server. These files contain definitions of the structures and interfaces that you will require to write user exits and custom request handlers.

One of these is the IDP_EXIT_INFO structure, which is used for passing the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit routine. The information passed and returned depends on the exit point.

For definitions of the information passed at each exit point see the reference Help topics Exit Points.

For definitions of support functions see the reference Help topics Functions.

Parent topic: User Exits for Request Handlers
Related information
Exit Interface Definition
External Data Value Modification - Input Parameter (Exit Point 1)
Internal Data Value Modification - Input Parameter (Exit Point 2)
Unmapped Named External Input Parameter (Exit Point 3)
End of Input Request Processing (Exit Point 4)
Start of Response Processing (Exit Point 5)
Internal Data Value Modification - Output Parameter (Exit Point 6)
External Data Value Modification - Output Parameter (Exit Point 7)
End of Response Processing (Exit Point 8)
End of Request Processing (Exit Point 9)
PFV_IDPES_FN_ALLOC_MEM
PFV_IDPES_FN_FREE_MEM
PFI
PFI_IDPES_FN_DISPLAY_TO_UTF16
PFI_IDPES_FN_UTF16_TO_DISPLAY
IDP_EXIT_INFO
IDP_EXIT_SERVICE_FUNCS


Linkage Section Field Names

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Several of the exit points are provided so that you can manipulate an input or output field. The way you pass a field name in the exit interface depends on how it is defined in the Linkage Section of the program providing the service. There are two possibilities:

  • The item is defined at level 01. In this case, the field name passed in the exit interface is the same as the field name in the Linkage Section
  • The item is defined at a level subordinate to level 01. In this case, the field name passed in the exit interface is composed of the field name prefixed by a concatenation of the names of the group items that it belongs to. The individual names are separated by "." characters. For example: field "e" in the record below would be uniquely identified as "a.b.c.e".
    01 a.
   03 b.
      05 c.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).

    If the field itself, or any of the group items that it belongs to, are tables, the required table index is specified by appending “(n)” to the name, where n indicates the position of the field or item in the table. For example, field “f” of the fourth element of “c” in the record below would be uniquely identified as “a.b.c(4).f”:

    01 a.
   03 b.
      05 c occurs 10.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
Parent topic: User Exits for Request Handlers


Deploying a User Exit Program

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To deploy a user exit program compiled to callable shared object format, copy it into a directory that is on $LD_LIBRARY_PATH (or $LIBPATH on AIX systems).

Parent topic: User Exits for Request Handlers


Web Service Exits

  • Implementing exit-soap-request and exit-soap-response
  • Implementing exit-json-request and exit-json-resp user exits
  • Implementing exit-http-headers user exits
  • Implementing exit-http-resp-headers user exits
Parent topic: User Exits for Request Handlers


Implementing exit-soap-request and exit-soap-response

Signature of Web Service SOAP-ENVELOPE 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 on SOAP-ENVELOPE
SOAP-ENVELOPlength
pointer on the length of SOAP-ENVELOPE.

The variables SOAP-ENVELOP and SOAP-ENVELOPlength are, using IMTK terminology, I/O parameters:

  • The user exit receives (get, Input) these parameters.
  • The user exit can update (set, Output) these parameters.
Parent topic: Web Service Exits


Implementing exit-json-request and exit-json-resp user exits

Signature of Web Service SOAP-ENVELOPE 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 on SOAP-ENVELOPE
SOAP-ENVELOPlength
pointer on the length of SOAP-ENVELOPE.

The variables SOAP-ENVELOP and SOAP-ENVELOPlength are, using IMTK terminology, I/O parameters:

  • The user exit receives (get, Input) these parameters.
  • The user exit can update (set, Output) these parameters.
Parent topic: Web Service Exits


Implementing exit-http-headers user exits

Web Service SOAP-HEADER exit-http-headers user exit, called before the Web Service is invoked. InvokeService02, when a function named exit-http-headers exists, calls it from once to 100 times.

This user exit is called before the HTTP-HEADER (and SOAP-ENVELOPE) 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-HEADER 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 IMTK terminology:

headerNum
Input parameter

This user exit is called repetitively from once to 100 times. The headerNum is just the index of the C for 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 Exits


Implementing exit-http-resp-headers user exits

The exit-http-resp-header user exit provides access to any and all HTTP headers present in the response message from a SOAP Web service. When present, it is called from one to 100 times by InvokeService02 before the Web service is invoked.

Signature of Web Service HTTP-RESP-HEADER user exit function

C terminology:

Function_Name(int header, char * headerName, char * headerValue)

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:

header
Number of the named value
headerName
Name of the named value
headerValue
Value of the named value

The variables use IMTK terminology:

header
Input parameter

This user exit is called repetitively from one to 100 times. The headerNum is just the index of the C for loop. The end of the loop occurs when:

  • § or header = 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 Exits


Troubleshooting

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes how to set about diagnosing common problems that can occur with running applications in Enterprise Server and gives some advice about overcoming them.

Failures fall into the following categories:

  • Incorrect output (an application or system function produces the wrong results or exhibits unexpected behaviors). These include application abends.
  • Unexpected system terminations. Either the whole enterprise server terminates or a subsystem (support process) terminates.
  • System loops. These include application loops and enterprise server subsystem loops. They are characterized by an abnormal accumulation of CPU time by an enterprise server process and may display the same external symptoms as a system hang.
  • System hangs. Any problem where the enterprise server appears to stop responding to its clients (except for loops).

    This can also be the result of problems with inter-system communications.

  • Determining the Failure Type
  • Collecting Information
  • Data Capture
  • Checking the Communications Process
  • Using a Diagnostics Server
  • What You Can Do with Dumps and Traces
  • Problems Caused by Process Limits
Parent topic: Enterprise Server configuration and administration


Determining the Failure Type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Key initial classifiers for a failure are:

  • The console log.

    This contains an easy-to-read history of enterprise server system activity leading up to the problem. When viewing the console log:

    • Investigate messages with levels other than information first.
    • Frequently, the enterprise server will continue to appear normal for some time after a failure so the 10 to 15 minutes before the failure should be investigated in detail (including the information messages).
  • The list of processes.

    Inspect the processes associated with the failing enterprise server (providing the server did not shut down). Loops may be indicated if there is a significant difference in the CPU time for a process between the list in the healthy data capture and the list in the problem data capture.

  • The list of shared memory areas and semaphores.

    An unusual number of objects may indicate an operating system problem. To evaluate this, compare the list with one obtained when the enterprise server system is in a healthy state.

These classifiers coupled with the external symptoms should provide enough information to assign the failure to one of the types of failure listed.

  • Incorrect Output
  • Unexpected System Termination
  • Invalid Credentials Error
Parent topic: Troubleshooting


Incorrect Output

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The next step here is to differentiate between application problems and enterprise server infrastructure problems.

Application failures other than abends are often application problems. Look at the active trace dataset coupled with the system trace table in the dump X dataset (casdumpx.rec) to establish the application activity before the failure.

Application abends can be due to application problems or enterprise server infrastructure problems. Look in the active dump dataset for an RTS error dump. If found, evaluate the RTS error and classify the problem from this. What module experienced the failure, application or enterprise server infrastructure?

Parent topic: Determining the Failure Type


Unexpected System Termination

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Inspect the system console log for messages indicating the cause of the shutdown and classify the failure from these.

  • Loops
  • System Hangs
Parent topic: Determining the Failure Type


Loops

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use the name of the looping process to classify the failure. If the looping process is a service execution process (SEP), the loop could either be in an enterprise server subsystem or in the application; look at the active trace dataset and the system trace table from the dump X dataset to determine which module last got control.

If the looping process is not a SEP, or the last module to get control was not part of the application, you should refer the problem to Micro Focus technical support.

Parent topic: Unexpected System Termination


System Hangs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Find out whether all client requests are suffering from lack of response from the enterprise server, or just one type of request.

Try dynamically increasing the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server Details page, specifying the new number in Requested Service Execution Processes and clicking Update. The new processes should appear in the list after a short delay. Success shows that shared memory is not locked and that the enterprise server is still functioning correctly at some level, even though the external symptoms of the problem might still be present.

Check the number of active service execution processes (SEPs), using the dump X dataset. Inspect the despatch control blocks, one for each service execution process. Are all service execution processes currently occupied with a transaction? Is the occupying transaction the same for each process or was the last command executed by each process the same? If either of these is true, consider the following possibilities:

  • That enough requests of the problem type have arrived to block all the available processes, such that it appears that the whole enterprise server has failed. This might indicate a customer application issue.
  • That enough normal long running requests have arrived to occupy all available processes, such that it appears that the whole enterprise server has failed. If this seems likely, you might be able to fix the problem by increasing the number of service execution processes.

Another possibility is that the server's shared memory is locked. The best way to check for this is to compare the date and time of the last trace entry in the dump X dataset to the date and time of the dump. The larger the gap between the two times, the more likely it is that shared memory is locked. If shared memory is not locked, try to determine what the server is waiting for. If shared memory is locked, try to determine which process left shared memory in this condition.

Another possibility is that rather than the failure being the result of some problem with the application or the enterprise server, it is instead the result of the enterprise server running up against the operating system's process limits. This is discussed at length in the section Process Limits.

  • One Type Of Request is Failing
  • All client requests are failing
Parent topic: Unexpected System Termination


One Type Of Request is Failing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Consider the possibility that the application is suffering the effects of resource contention. Consider the possibility that the service listener has failed.

Parent topic: System Hangs


All client requests are failing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Try dynamically increasing the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server Details page, specifying the new number in Requested Service Execution Processes and clicking Update. The new processes should appear in the list after a short delay. Success shows that shared memory is not locked and that the enterprise server instance is still functioning correctly at some level, even though the external symptoms of the problem might still be present.

Check the number of active service execution processes (SEPs) using the dump X dataset. Inspect the despatch control blocks, one for each service execution process. Are all SEPs currently occupied with a transaction? Is the occupying transaction the same for each SEP or was the last command executed by each process the same? If either of these is true, consider the following possibilities:

  • That enough requests of the problem type have arrived to block all the available processes, such that it appears that the whole enterprise server instance has failed. This might indicate a customer application issue.

  • That enough normal long running requests have arrived to occupy all available processes, such that it appears that the whole enterprise server instance has failed. If this seems likely, you might be able to fix the problem by increasing the number of service execution processes.

Another possibility is that the enterprise server instance's shared memory is locked. The best way to check for this is to compare the date and time of the last trace entry in the dump X dataset to the date and time of the dump. The larger the gap between the two times, the more likely it is that shared memory is locked. If shared memory is not locked, try to determine what the enterprise server instance is waiting for. If shared memory is locked, try to determine which process left shared memory in this condition.

Parent topic: System Hangs


Invalid Credentials Error

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you get an INVALID_CREDENTIALS error in the console log when an enterprise server starts up, as follows:

CASCD4002W Error (INVALID_CREDENTIALS) binding to MFDS CASCD0102F TX Daemon Failed to Initialize

this indicates a problem with the internal files that hold details of Directory Server user IDs and passwords (in encrypted form). If you see this error, you should check that the following files exist in the Micro Focus Directory Server schema directory, which by default is $COBDIR/etc/mfds:

  • usr.dat

  • ugp.dat

  • ace.dat

  • prm.dat

These files are initially created from the cciusers.dat file located in $COBDIR/etc . If there was a problem reading this file or creating the initial security information, you can attempt to recreate the data by re-importing this file. To do this:

  1. On the home page of Enterprise Server Administration, click Users in the menu on the left hand side.

  2. Click Import... under the list of users.

    This displays a page confirming the location of the cciusers.dat file, and asking whether you wish to replace all existing user information (default: yes).
    Note: Import... is not available when your Directory Server is running in restricted mode.

  3. Click OK.

To start an enterprise server requires that certain system user accounts exist. The user IDs required are mf_mdsa and mf_cs, and they should exist in the default cciusers.dat file which is shipped with the product.

Parent topic: Determining the Failure Type


Collecting Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For all troubleshooting exercises it is essential to gather as much information as possible about the state of the enterprise server when the problem occurred and about the events leading up to the problem.

When a problem occurs, you need to capture not only the current log files, dumps and traces, but also the contents of various files, directories and areas, and the output from a number of operating system tools. It is important to have data capture mechanisms in place in advance of a failure so that the data can easily be obtained when required.

In a production system, we recommend that you restore the enterprise server service to its clients before you start analyzing the data you have captured. We also recommend that you perform data capture on the enterprise server in a healthy state shortly after the supporting operating system has been rebooted and the enterprise server started. You should retain this healthy data capture to compare with the failure data capture.

You should also check whether the enterprise server is responding to client requests, and to requests from ESMAC. Lack of response points to problems with the communications process (MFCS).

  • Directory Server Journal
  • Enterprise Server Log Files
  • Enterprise Server System Directory
  • Dumps and Traces
Parent topic: Troubleshooting


Directory Server Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can change the maximum file size, the number of entries displayed and the level of logging on the Configure Options page of Enterprise Server Administration. When the journal reaches the maximum file size set, the most recent journal entries overwrite the oldest journal entries. For troubleshooting purposes, you might want to increase the maximum file size to 256 KB or more.

The three levels of logging available are:

  • Errors only
  • Errors and warnings
  • All information
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 the Micro Focus SupportLine.

For troubleshooting purposes, you might want to set the maximum level of logging.

  • To View the Journal
Parent topic: Collecting Information
Related information
To configure the Directory Server
To view the journal


Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server instance, you can view the following log files to help identify the cause of any problems:

  • The server console log (ES Console on the ESMAC tab menu) provides information about the server instance. This includes such details as when the server was started or stopped, the SEPs that were created, and so on.
  • The communications process log (CS Console on the ESMAC tab menu) provides information on the communications processes.
  • Communications Process Log Files
  • Enterprise Server Log Files
  • To View the Enterprise Server Log Files
Parent topic: Collecting Information


Communications Process Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Communications processes (MFCS) log messages to the communications process log file, log.html, in its System Directory.

If multiple communications processes are running, the date and time stamp at the beginning of each message is followed by an instance identifier in square brackets, for example, [2].

By default, there is only one log file which grows continuously until it is deleted by an administrator. However, you can use the mf-server.dat file to activate rotating log files, and to change the level of logging. The mf-server.dat file is located in $COBDIR/etc . It uses the ini-file format of section tags in square brackets followed by name=value pairs.

With rotating log files, MFCS uses multiple log files, named log-1.html, log-2.html, etc. When a log file reaches a configured size, MFCS moves on to the next file (which will be deleted first if it already exists). When it reaches the configured number of log files, it returns to log-1.html, overwriting it.

The syntax is as follows:

[logging]
 files=number-of-files
 filesize=maxsize
 dscontrol=none|standard|all
 dirsvc=none|unusual|processing|not-found|all

All the parameters are optional. However, to activate rotating log files, both files= and filesize= must be set, and files= must be set to a number greater than 1. These parameters configure rotating log files, as explained above. If both are set, then the total log file space required by MFCS will not exceed files*filesize (approximately). For example, to limit the log to three files of 100 KB each:

[logging]
files=3
filesize=100

The parameters are explained below.

  • Files
  • filesize
  • dscontrol
  • dirsvc
Parent topic: Enterprise Server Log Files
Related information
System Directory


Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
files=number-of-files
Specifies the number of log files.
Parent topic: Communications Process Log Files


filesize

Restriction: This topic applies only when the Enterprise Server feature is enabled.
filesize=maxsize
Specifies the maximum size of a log file in kilobytes (KB)
Parent topic: Communications Process Log Files


dscontrol

Restriction: This topic applies only when the Enterprise Server feature is enabled.
dscontrol=none|standard|all

Sets the level of logging for control messages. These messages normally come from Directory Server (MFDS) though they can come from other sources as well. These messages include server monitor probes, requests for log and dump data, and dynamic configuration changes.

none
Don't log control messages.
standard
Log control messages that update MFCS configuration or status. Don't log messages that just request information, such as the KEEPALIVE probe messages that MFDS uses to check if the enterprise server is still running.
all
Log all control messages.

You might want to set this to "all" if you are investigating a problem with the server monitor or other control flows, or set it to "none" if you want to avoid logging messages about configuration changes or other control requests.

Default = standard

Parent topic: Communications Process Log Files


dirsvc

Restriction: This topic applies only when the Enterprise Server feature is enabled.
dirsvc=none|unusual|processing|not-found|all
none

Don't log information about Directory Server activities.

unusual
Only log unusual results, such as duplicate object names, which may indicate configuration problems.
processing
Also log some messages about the progress of normal processing. This is the default.
not-found
Also log some messages about searches that return a not-found status. Normally these are not logged because MFCS expects some optional configuration items to be missing if they are not needed. In some cases, though, logging all not-found results may help diagnose configuration issues.
all

Log even more information, including normal MLDAP unbind operations.

Default: processing

Parent topic: Communications Process Log Files


Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server logs messages to a file, console.log, in its System Directory.

When an enterprise server starts, it renames any existing console.log file to console.bak, erasing any existing console.bak file. You should include both console.log and console.bak in your data collection. Make sure you copy them to a safe place before restarting the enterprise server.

Parent topic: Enterprise Server Log Files


To View the Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Home page click Edit to the left of the required server.
  2. Click the Diagnostics tab.
  3. Click the ES Console tab to view the console log, or click the CS Console tab to view the communications process log.
  4. If you want to see the whole log since the server was started, click Show Entire Log. The log opens in a text editor window.
  5. To return to ESMAC, click Back in your browser.
Note: You can display the console log by clicking Display in the Diagnostics group of the left-pane menu when it is available. To return to ESMAC, click Back in your browser.
Parent topic: Enterprise Server Log Files
Parent topic: Work with Servers


Enterprise Server System Directory

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each Enterprise Server writes log, dump and trace information to files in its System Directory.

The default location for the System Directory is /var/mfcobol/es/region name

Note: To change this, you must run casperm.sh as root.
Parent topic: Collecting Information
Related tasks
To Run casperm
Related information
Moving the Diagnostics Data


Dumps and Traces

Restriction: This topic applies only when the Enterprise Server feature is enabled.

We recommend that you always run a production system with some diagnostics switched on. This is necessary so that you can troubleshoot unexpected problems. Diagnostics consume resources, and there is always contention between problem determination facilities and performance. You need to decide how important it is to be able to diagnose a problem the first time it occurs rather than having to try to recreate it or having to just turn on diagnostics and wait for it to reoccur. We suggest the following level of diagnostics as a minimum:

  • Select "Auxiliary Trace Active".
  • Select the application container (API) trace flag.
  • Select "dump on system abend".

You might also need to turn on tracing for task control (KCP), storage control (SCP) and application container (RTS) components.

  • Producing a core dump for run-time errors
Parent topic: Collecting Information
Related information
To view a dump
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
casdump
casstart
Starting and Stopping the Directory Server


Producing a core dump for run-time errors

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, Enterprise Server does not create a core dump for run-time errors. For example, by default, if the operating system detects a memory access violation caused by your application, no core dump is produced. You must configure the system to produce a core dump for these situations.

Once you have produced a core dump, you can debug the core dump to help determine the cause of the error.

Note:
  • The functionality does not identify memory corruption issues. You can use it to identify application problems only.

To configure the system so that it creates a core dump for run-time errors, you need to create a run-time tunable configuration file, and add the tunable configuration file's details to your Enterprise Server region.

  • To create a run-time tunable file, create a text file, for example COBCONFIG.CORE.TXT with the following entries:
    SET CORE_ON_ERROR=131
SET CORE_FILENAME="core.%p@%t_%d"
  • To add the configuration to Enterprise Server, add the entry to your Enterprise Server region configuration. When you start the region, core dumps will be produced by run-time errors. See the illustration below for an example.
Figure 1. Configuring Enterprise Server core dumps for run-time errors
Configuring Enterprise Server core dumps for run-time errors
Parent topic: Dumps and Traces


Data Capture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The minimum items for data capture are:

  • Your enterprise server's System Directory, $COBDIR/var/mfcobol/es/WORKAREA/ESName, contains:
    • The console log: console.log and console.bak.
    • The communications process log file or files; see the topic Communications Process Log Files.
    • The trace diagnostic datasets, casauxta.rec and casauxtb.rec.
    • The system abend dump, if one exists (casdumpa.rec, casdumpb.rec or casdumpx.rec).
    • The externally triggered dump (filenames as for the system abend dump).
  • A copy of the file cobver, located in $COBDIR/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 $COBDIR/etc .
  • The Directory Server configuration directory, usually under the $COBDIR/etc/mfds directory.
  • The Directory Server log file (usually under the /var/mfcobol/logs directory); see the section Directory Server Journal.
  • Logs for other components that may be enabled such as Fileshare.
  • A list of processes running on the machine. You should obtain two lists - one at the beginning of the data capture list, and one at the end. You can obtain this by running the following command :
    ps -ef
  • A list of shared memory areas and semaphores. You can obtain this by running the following command :
    ipcs -a
  • A list of network connections and listening sockets, obtained by running the netstat command.
    Note: The syntax of this command differs between platforms.
  • Optionally, a list of open files. You can obtain this by running the following command :
    lsof

    This command is available from third-party UNIX tool suppliers.

Note:
  • The operating system tools that you can use to obtain information such as the ipcs command provide a range of options. You can obtain advice on the most useful options from Micro Focus technical support.
  • Many of these items are held in the enterprise serve directory, so it's best to start by taking the whole directory

It is important that the data capture process is non-destructive, that is, does not damage a healthy system, and that it is non-blocking, that is, does not wait on anything that may not complete in a sick system.

Parent topic: Troubleshooting
Related information
Communications Process Log Files
System Directory
Directory Server Journal


Checking the Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you take the data capture, you should also check that the communications process (MFCS) is still running. If it is, you can then check what it is currently doing. To do this:

  1. Write down the hostname of the machine where the enterprise server instance is running.
  2. Go to the Enterprise Server Administration Web interface. In the list of servers on the Home page, find the enterprise server instance that you want to check. The Communications Processes column lists one or more communications processes for that server. Write down each of the port numbers shown in the column. (The port number is the last part of the address, after the second colon.)
  3. In a web browser, go to the following URL:
    http://hostname:port/MF_KEEPALIVE

    where hostname is the hostname (or IP address) from step 1 and port is the first port number from step 2.

    If MFCS is working correctly, you should see a response similar to the following:

    Server=ESDEMO
ServerType=GKC
Version=1.2.5
Status=Started
  4. Repeat step 3 using "MF_STATISTICS" instead of "MF_KEEPALIVE". You then see a response showing what MFCS is currently doing, how many conversations it has processed, and other information.

If you are running multiple communications processes, you can check each one in turn using this method. Each of the port numbers you recorded in step 2 corresponds to a communications process. Note that some of your communications processes for a given server may be disabled; they do not need to be checked.

Parent topic: Troubleshooting


Using a Diagnostics Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can obtain the most value from the diagnostics aids if you use a dedicated enterprise server instance solely for investigating problems. This enterprise server instance is a diagnostics server.

You can then generate dumps and traces from the diagnostics server and compare them with the dump and trace data collected from the live server that experienced the problem.

  • Configuring a Diagnostics Server
  • Moving the Diagnostics Data
  • Viewing the Diagnostic Server Console Log
  • Viewing a System Trace: Diagnostics Example
  • Viewing a Dump
Parent topic: Troubleshooting


Configuring a Diagnostics Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A diagnostics server is the same as any other enterprise server instance, that is it does not provide any additional diagnostics facilities.

The only difference is that a diagnostics server is configured not to produce any diagnostic information itself. This allows it to be used to process the diagnostic information from another server. The figure below shows the recommended configuration for a diagnostics server.

Figure 1. Configuration for a Diagnostics Server
Configuration for a Diagnostics Server
Parent topic: Using a Diagnostics Server


Moving the Diagnostics Data

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can start work on the data collected from the server that experienced the problem, you need to copy it into the diagnostics server. Here are the commands you need to move the collected data and the log files into a diagnostics server, assuming that:

  • You are in the System Directory of the enterprise server that experienced the problem
  • The diagnostics server is using the default System Directory location

In the examples below, Enterprise Server is installed as part of Visual COBOL:

cp *.rec $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name
cp console.log $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name/console.aux
cp console.bak $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name/console.bak

Here is a sample script that copies the required data to a diagnostics server called diagnose.

cp *.rec $COBDIR/var/mfcobol/es/WORKAREA/diagnose
cp console.log $COBDIR/var/mfcobol/es/WORKAREA/diagnose/console.aux
cp console.bak $COBDIR/var/mfcobol/es/WORKAREA/console.bak

Restart the server that experienced the problem after you have moved the data to the diagnostics server.

Parent topic: Using a Diagnostics Server
Related information
Enterprise Server System Directory
Moving the Diagnostics Data


Viewing the Diagnostic Server Console Log

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Extra options exist for viewing a diagnostic server's console log. These commands are available with any enterprise server instance, but they are useful only in the context of a diagnostics server with the diagnostic files loaded from the problem server, copied using the commands described in Moving the diagnostics data.

To access the diagnostic server's ESMAC screen:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.

To use these extra options:

  • In the left pane in the Diagnostics area, select the Log and the C/x radio buttons (for current), then Display to view the current console log file, that is, the console.log file of the diagnostics server.
  • In the left pane in the Diagnostics area, select the Log and B radio buttons (for backup), then Display to view the backup console log of the problem server (console.bak). Note that this works only if you copied the data collection into the diagnostics server after you started it, because the process of starting it replaces the backup console log from the problem server with the backup console log of the diagnostics server
  • In the left pane in the Diagnostics area, select the Log and A radio buttons (for auxiliary), then Display to view the console log of the problem server (copied to console.aux)
Parent topic: Using a Diagnostics Server


Viewing a System Trace: Diagnostics Example

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This subject is covered in the help topic To view a system trace. However, the options are complex and it is worth looking at an example.

To obtain a trace of the system trace table:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.
  3. In the Diagnostics area in the left pane, select the Trace radio button, and select either the A or B radio button to select the A or B dataset. (Don't select C, since the in-memory trace table belongs to the diagnostics server).
  4. In the Blocks field, specify the number of trace blocks that are to be aggregated into one trace index entry.
  5. Click Display.
Figure 1. Trace Index Page
Trace Index Page

Each block is the same size as the system trace table, that is, it contains the number of trace entries specified in Trace Table Size on the Edit Server page for the server. The index entries are displayed with a timestamp against each one. This is the timestamp of the first trace entry in each set of blocks. These timestamps help you narrow down your search to particular events.

To view the actual trace, go to one of the index entries, and make selections in the following fields:

  • In Blocks (immediately to the right of Details), specify how many blocks you want to be included in the trace. This defaults to the value you entered in Blocks in the Diagnostics group of the menu. You can change it to any value you want. Having two Blocks controls helps you control what is displayed in the formatted trace more precisely.
  • In Level, (the next control to the right), specify the level of detail that you want to see in the formatted trace. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entries
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries
  • In PIDs (next to the right), check the check boxes for the process IDS of the processes in which you are interested. Check boxes are provided for all the processes that have trace entries in the blocks represented by this trace index entry. Process IDS are prefixed with a letter or number indicating the function of the process. The following letters are used:
    C | communications process (MFCS)
    F | Fileshare server (internal)
    J | journal control
    M | server manager
    R | recovery
    S | service execution process (SEP)
    U | unknown
    Z | generic terminal or client
  • In Task IDs (next to the right), check the check boxes for the task IDS of the tasks in which you are interested. Check boxes are provided for all the tasks that have trace entries in the blocks represented by this trace index entry.

The Level, PIDs and Task IDs controls are filters that help you select just the specific information of interest. If you leave the level as 0, the default, and don't check any process IDs or task IDs, you will see the minimum level of information for all processes and tasks that have entries in the block represented by the trace index entry. Note that it is possible to make selections such that no trace information is generated. This happens if you select both processes and tasks, and none of the selected tasks ran on the selected processes; a task cannot run on more than one process. If a task requires communications work, that work has its own process and task, and there is no automated way of relating the two task IDs. You always see the first trace entry in the block, irrespective of filtering.

Here is an example of how you can use the controls to select the information you want to see. Suppose you specify 10 in Blocks in the Diagnostics group of the menu. There are actually 60 blocks of information in the dataset, so 6 index entries are displayed. Suppose you were interested in a particular SEP, which you can see listed in the third and fourth index entries. You might then specify 20 in Blocks for the third index entry, check the box next to the process ID for the SEP, then click Details. Now you can only see trace entries for that SEP, in all the blocks that contain them, starting with the first block of the third index entry.

Each trace entry contains the following information:

Heading | Contents
None | An interpretation of the traced event, if one can be supplied
Seq | Sequence number of the entry in ascending order
Task-Nbr | The five-digit task number
ProcessID | The five-digit process ID
ID | the ID of the event, command, or instruction that was traced. This is a four-byte hexadecimal number.
hhmmsshh | A time stamp that indicates when the trace entry was written. The time stamp is in hours, minutes, seconds, and hundredths of a second.
aaaa bbbb | Eight bytes of entry-specific data

When you have finished viewing a trace, click Back to return to the trace index page.

Parent topic: Using a Diagnostics Server
Related information
To View a System Trace


Viewing a Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic provides an example of viewing a dump to locate the source of a problem.

You can obtain either a summary or a detailed dump. The summary information is included at the end of a detailed dump. Dumps whether summary or detailed include both system traces and local traces (traces for SEPs).

To access the diagnostic server's ESMAC screen:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.
  3. In the Diagnostics area in the left pane, select the Dump radio button, and select either the A or B radio button to select the A or B dataset. Select C to select the dump X dataset (the one created by an externally triggered dump).

    Ignore Blocks - it has no effect on the output.

  4. Click Display.
Figure 1. Dump Index Page
Dump Index Page

The index entries are displayed with the following information against each one:

  • The process ID
  • A code that helps identify the dump
  • The origin of the dump request
  • A date and timestamp

To view a dump, go to one of the index entries, and in Level, (the third control to the right), specify the level of trace detail that you want to see in the formatted dump. The options are:

0 | Service start, module start, module end, service end.
1 | Enterprise server API entries and exits
2 | Subsystem trace entries
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries. This is the default

Local trace tables (traces for SEPs) only have levels 0 and 1.

Note that this option has an effect on what you see in a detailed dump, but not in a summary dump.

Then click Details to see a full dump or Sum to see a summary dump.

When you have finished viewing a dump, click Back to return to the dump index page.

Parent topic: Using a Diagnostics Server
Related information
To View a Dump


What You Can Do with Dumps and Traces

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section details the tasks that you can perform on dumps and traces.

  • To Change the Trace Dataset
  • To Configure Dumps
  • To initiate a system dump
  • To specify what information is traced
  • To View a Dump
  • To View a Local Trace for a Client Process
  • To View a Local Trace for a SEP
  • To View a System Trace
  • To Configure Run-time Core Dumps
Parent topic: Troubleshooting


To Change the Trace Dataset

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To change the trace dataset

  1. In the left pane, click Control.

    The Control page is displayed.

  2. Click Trace n, Switch (where n is A or B). If the dataset is currently set to A, it is switched to B. If it is B, the dataset is switched to A.
Note: By default, the enterprise server uses the A dataset to record trace information.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To Configure Dumps

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To configure a dump:

  1. Click Control.

    The Control page is displayed.

  2. Check Dump on Abend, Sys if you want a dump created if the system abends. Click Dump on Abend, Trans if you want a dump created if the service abends. You can check both check boxes if you want to create dumps on both types of abend.
Note: By default, the enterprise server uses the A dataset to record dumps. If you want to change the dataset, click Dump n, Switch (where n is A or B). If the dataset is currently set to A, it is switched to B. If it is B, the dataset is switched to A.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To initiate a system dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To initiate a system dump

  1. Click Control.

    The Control page is displayed.

  2. Click Dump.
Note: You can also initiate a system dump using Enterprise Server Administration.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To specify what information is traced

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To specify what information is traced

  1. Click Control.

    The Control page is displayed.

  2. Check the required check boxes in the Trace Points group.

    The help for the Control page explains the meaning of each check box.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a dump

  1. Click Dump in the Diagnostics group.
  2. Click A or B to select the dump dataset, or C to select the X dataset.
  3. Click Display.

    A list of dumps is displayed.

  4. For the dump you want to display, in the field below the heading Level, choose a level of trace information to be included in the trace tables in the dump. The larger the number, the more detail will be shown. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entres
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries

    Each level includes all lower-level information. Local trace tables (traces for SEPs) only have levels 0 and 1.

  5. For the dump you want to display, click Details to see a detailed dump or Sum to see a summary dump.

    The dump is formatted and displayed. To return to ESMAC, click the Back button in your browser.

Note:

The X dataset contains dumps triggered by the external command casdump /d. You use casdump /d when a dump cannot be obtained normally; for example, when the enterprise server is not responding and shared memory is locked. The dataset has the filename casdumpx.rec.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC
Related reference
casdump
Related information
Viewing a Dump
To create an ESMAC user
To start ESMAC for a server
To monitor services
To configure dumps
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To view a system trace
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server
Troubleshooting


To View a Local Trace for a Client Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a local trace for a client process

  1. Click Clients in the menu.
  2. Click Trace next to the client process for which you want to view a local trace.

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Note: Local traces are available only for WebSphere MQ listeners and communications processes (MFCS).
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a Local Trace for a SEP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a local trace for a SEP

  1. Click SEPs in the menu.
  2. Click Trace next to the SEP for which you want to view a local trace. Auxiliary processes are listed underneath SEPs, and you can obtain traces for some of them: the Fileshare process, JCP (journal control program), and TDP (extra-partition transient data process).

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a System Trace

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a system trace

  1. Click Trace in the Diagnostics group.
  2. Click A or B to select the dataset, or C to select the in-memory trace table.
  3. Specify the number of trace blocks that are to be aggregated into one trace index entry in Blocks in the Diagnostics group. This defaults to 10.
  4. Click Display.

    A list of traces is displayed: this acts as an index to the detailed trace information. For each entry in the index list the following information is shown, from left to right:

    • The process IDs of all processes that have entries in the blocks represented by this trace index entry.
    • The task IDs of all tasks that have entries in the blocks represented by this trace index entry
    • The date and time stamp of the first entry in the trace.
  5. If you want to change the number of blocks to be included in the Details, specify a new number of blocks in the field immediately to the right of Details and below the heading Blocks (this defaults to the number you entered in the Diagnostics group).
  6. In the next field, below the heading Level, choose a level of tracing where the larger the number, the more detail will be shown. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entres
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries

    Each level includes all lower-level information.

  7. In the next group of fields, below the heading PIDs, if you don't want to see trace entries for all processes, check the check boxes next to the process IDs that you do want to see details for.
  8. In the next group of fields, below the heading Task IDs, if you don't want to see trace entries for all tasks, check the check boxes next to the task IDs that you do want to see details for.
  9. Click Details for the trace you want to display.

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC
Related information
Viewing a System Trace: Diagnostics Example
To create an ESMAC user
To start ESMAC for a server
To monitor services
To configure dumps
To view a dump
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server
Troubleshooting


To Configure Run-time Core Dumps

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, Enterprise Server does not create a core dump for run-time errors. To configure an Enterprise Server region to produce a core dump for run-time errors:

  1. Create a run-time tunable text file, for example COBCONFIG.CORE.TXT with the following entries:
    SET CORE_ON_ERROR=131
SET CORE_FILENAME="core.%p@%t_%d"
  2. Access the Enterprise Server Administration screen, and in the Status column, click the Details button for the enterprise server instance.
  3. To add the configuration to enterprise server instance, add the entry to your Enterprise Server region configuration. When you start the region, core dumps will be produced by run-time errors. See the illustration below for an example.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Monitor Directory Server


Problems Caused by Process Limits

Restriction: This topic applies only when the Enterprise Server feature is enabled.

UNIX systems limit how much of various system resources each process on the system can use. This prevents badly-behaved processes from using all the system resources and tying up the machine so that no other processes can run. In some cases you might need to configure the operating environment for Enterprise Server so that it can use more than the default amount of resources.

Which resources are limited, the default limits for them, and the maximum limits supported by the operating system depend on the version of UNIX and how it is configured on each system. See your operating system documentation for more details. Typically, UNIX systems can limit the memory, the amount of CPU time, and the number of open files (including network sockets) used by each process, and the size of files it creates.

An enterprise server instance might run short on resources if it is required to handle a large client load. The Enterprise Server component which is most likely to encounter resource limits is the Micro Focus Communications Process, mfcs32. There is one mfcs32 process for each started communications process in the started enterprise server.

  • Diagnosing Resource Limit Issues
  • Examining and Changing Resource Limits
Parent topic: Troubleshooting


Diagnosing Resource Limit Issues

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If mfcs32 encounters a memory or stack resource limit, it will typically not be able to create new threads to process additional conversations (until some existing conversations are finished), and might not be able to allocate memory for tasks such as parsing HTTP headers. Typical error messages in the communications console log (log.html) in this situation include:

  • error OS_FAIL: OS reported an error starting thread for conversation
  • HTTP Parser: Unable to allocate 32767 bytes
  • Unable to process conversation 37425 for listener Web Services - closing conversation

If mfcs32 encounters a file descriptor limit, it will be unable to create sockets for new conversations. In this case no error will be logged, but the conversation will be closed immediately, and the client should report an error.

If an enterprise server runs for a very long period of time, one or more enterprise server processes could encounter a CPU time limit. In this case the process will be killed by the operating system. Generally, Enterprise Server will detect this and restart the killed process, but any work the process was doing (running a service if it's a service execution process, or handling client conversations if it's a communications process) will be lost. An error message will appear in the Enterprise Server console log (file console.log) noting that a process was terminated and restarted.

Parent topic: Problems Caused by Process Limits


Examining and Changing Resource Limits

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The system-wide default and maximum values for resource limits depend on UNIX platform and configuration. For more information consult your operating system documentation.

Resource limits can be set for individual processes and the processes they start. For example, if you start an enterprise server from the Enterprise Server Administration Console, it will inherit its resource limits from the Directory Server process mfds32 (which provides the Administration Web interface). Changes to the resource limits when starting the Directory Server will also affect enterprise server processes that are started through the Web interface. If you start an enterprise server from the command line using the casstart command, on the other hand, you can set resource limits in the current shell before running casstart to control resources for that enterprise server.

Resource limits can be examined and changed for the current shell using the UNIX ulimit utility. The exact syntax and output of the ulimit command depends on UNIX version, so consult your documentation for the specific details. Typically, however, ulimit -a displays all the current resource limit settings, as follows:

$ ulimit -a
time(seconds)        unlimited
file(blocks)         2097151
data(kbytes)         131072
stack(kbytes)        32768
memory(kbytes)       32768
coredump(blocks)     2097151
nofiles(descriptors) 2000

This is the output from an AIX 5.2 system. It shows that there is no CPU time limit in effect for processes started in this shell and that regular files and core dump files are limited to 2097151 512-byte blocks (1 GB in total). The data, stack, and memory limits are all limitations on how much memory the process can use. For enterprise server, the stack setting limits how many threads mfcs32 can create to handle conversations, and the data setting limits how much virtual memory mfcs32 can allocate to process conversations. The memory setting controls how much physical memory - RAM - a process can use, and is usually less important for enterprise server. The final limit is the number of file descriptors. mfcs32 requires a few descriptors for various purposes such as its log file, plus one for each listener; the rest are for individual conversations with clients. In this example, mfcs32 would be limited to something less than 2000 clients connected simultaneously.

There are two kinds of resource limits set by the ulimit command: hard and soft. By default, ulimit shows and sets soft limits. The soft limits are the ones that actually affect processes; hard limits are the maximum values for soft limits. Any user or process can raise the soft limits up to the value of the hard limits. Only processes with superuser authority can raise the hard limits.

For example, if you were encountering a resource limit problem with an Enterprise Server, and you wanted to raise the stack limit to see if that corrected the problem, you might try the following:

  1. Display the current soft limit for stack:
    $ ulimit -s
   32768
  2. Display the current hard limit (maximum) for stack:
    $ ulimit -H -s
   4194304
  3. Set the stack soft limit to some value between the current and the maximum:
    $ ulimit -s 65536
  4. Start the enterprise server with the new stack limit in effect:
    $ casstart

Note that in step 4 you start the enterprise server from the command line. If you wanted to start the enterprise server from the Administration Web interface, you would have to start the Directory Server from the command line in this shell, after raising the limit, and then start the enterprise server from it.

Parent topic: Problems Caused by Process Limits


Enterprise Server Administration Console Help Pages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section contain the context-sensitive information that relates to the Enterprise Server user interface.

A version of this help is available directly from the Enterprise Server administration user interface.

Note: While the information available from the user interface still applies, this version is the most current.
  • Enterprise Server Administration Side Bar Menu
  • Enterprise Server Administration Home Page
  • Edit Server Instance Properties
  • Listeners
  • Services
  • Handlers
  • Packages
  • Security Configuration Screen Help
Parent topic: Enterprise Server configuration and administration


Enterprise Server Administration Side Bar Menu

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The sidebar appears at the left of the Enterprise Server Administration screen. It contains the folllowing areas and options:

Home

Click this to return to the Home page.

Actions

These menu options provide administrative actions. The options that are displayed in this area varies depending on the user's permission level.

Renew

Click this to refresh the IP address information cached by your Directory Server. Use this option when the IP address of the machine running your Directory Server changes.

Directory Server uses the IP address to locate the servers that it manages. When the cached IP address is out of date, Directory Server may be unable to connect to its servers and may report inaccurate information to clients.

Export

Click this to show the Export page. This page enables you to save a copy of the whole repository to a location of your choice. This menu option is available only if you logged on with Administrator or Schema Administrator permission level.

Import

Click this to show the Import page. This page enables you to update the repository with additional objects from an import directory. Imported objects can include servers (along with all of their child objects), and Security Manager definitions. This menu option is available only if you logged on with Schema Administrator permission level.

Delete All

Click this to show the Delete confirmation page. This page enables you to confirm that you want the repository to be completely erased and all registered objects to be deleted. This menu item is available only if you logged on with Schema Administrator permission level.

Logon

Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".

Logoff

Click this to log off from an administrative session that is currently logged on. There is no log off confirmation. This menu option is shown only if the session is currently logged on and the User Access setting on the Options page is "Restricted".

Configure

The heading for the menu option that enables you to configure Directory Server. This menu heading and its associated menu option are available only if you logged on with Administrator permission level or higher.

Options

Click this to show the Directory Server Options page. This page enables you to configure the Directory Server.

Security

Click this to show the pages used for configuring security options.

Display

The heading for menu options that enable you to view information about the state of the Directory Server and about the events that have taken place on the server.

Directories

Click this to show the Directories page. This page lists all the instances of Directory Server that are running on the network and using the default Directory Server port (86).

Statistics

Click this to show the Statistics page. This page shows statistics and status information about Directory Server.

Sessions

Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.

Journal

Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.

Shut Down

Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.

Help

The heading for menu options that enable you to view documentation about the Directory Server and Enterprise Server Administration.

This page

Click this to view help for the page you are currently viewing and for all the controls on the page.

Contents

Click this to view the Contents of the Enterprise Server documentation.

CAUTION:
This version of the help has not been updated to reflect the latest product changes. For the latest help, go to the Micro Focus Product Documentation site.
Note:

For this link to work, you must be using an enterprise server that has a Web listener with the following entry in the [virtual paths] section:

  • For Windows systems:
    docs=<ES>/help
  • For UNIX systems:
    docs=<ES>/docs/html

This enterprise server must be started.

The default enterprise server, ESDEMO, has a web listener with this configuration information. When you create a new enterprise server, a Web listener with the required configuration information entry is automatically created.

Support

Click this to contact Micro Focus Technical Support via the Supportline website to report problems or ask any questions about using Micro Focus software.

Feedback

Click this to open your email client and send general feedback to Micro Focus.

  • Export
  • Import Server Information (Page 1 of 4)
  • Configure Repository Options
  • Display Directories
  • Display Statistics
  • Display Sessions
  • Journal
Parent topic: Enterprise Server Administration Console Help Pages


Export

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Target directory

Use this page to save all server information in the Directory Server repository to a backup location.

Specify the name of the directory the server information will be exported to. If the directory does not exist, the export process will attempt to create it.

Export options:

You use these radio buttons to choose which information is included in the export. You can choose to:

  • Export Enterprise Server configuration and Security Manager definitions

    This will export all of the configuration information for your Enterprise Servers. It will also export the pool of Security Manager definitions, and the Security Manager lists for your servers, along with security configuration details. (A Security Manager list indicates which managers are used by a given server.)

  • Export just the current Enterprise Server configuration

    The Security Manager definitions, Security Manager lists and security configuration details will not be included in the export.

  • Export just the Security Manager definitions

    Only the pool of Security Manager definitions will be exported. This will not include the security configuration details or the Security Manager lists.

    Note:

    Security Manager lists are only exported when you choose the first of these options.

When you import, you can choose whether to include or exclude security details, if these have been exported. Where the import excludes the security details, or where the security details were not included in the export, the imported servers will use the Default ES Security configured on the importing system.

Where the import includes security details, all existing security information - the Security Manager pool, Security Manager lists and other security configuration details - will be removed and replaced with the imported information. One consequence of this is that servers that are not replaced during the import will have their security details set to use the Default ES Security configuration.

Parent topic: Enterprise Server Administration Side Bar Menu


Import Server Information (Page 1 of 4)

Use this page to import server definitions. The effect of this is to add the servers and their child objects (services, listeners, etc.) to your current repository.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Selected source directory containing server data to be imported
Specify the type and location of the directory from which data is to be imported. The source directory should have been previously populated by a repository export, an export of an individual Enterprise Server, or a compatible process. It can be a file system location or an LDAP repository.

For file system storage, the location is the directory in which the exported data is stored.

For LDAP storage, the location is the address of the LDAP server containing the exported data.

Note: When you specify ldap:// as the directory type, additional fields are displayed for specifying the container in which the data is stored, and the LDAP user credentials required to read from the container.
Repository Container Distinguished Name
The distinguished name of the LDAP container in which the exported data is stored.
User DN:
The distinguished name of the LDAP user with which to access the repository. This user must have permission to read from the container.
User Password:
The password of the user with which to access the repository.
Recent directories
This contains a list of directories from which you have previously imported data.
Note: By default the directory will only be added to the list if the import is successful, but you can choose to include the directory even if the import fails.
Delete
This button enables you to remove an entry from the list of recent directories.
Parent topic: Enterprise Server Administration Side Bar Menu


Configure Repository Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configuration settings for the Directory Server.

Repository Location

Specify the type of storage and the location containing the repository. You can store the repository in the file system or in an LDAP repository.

For file system storage, the location is the directory in which the repository data will be stored.

For LDAP storage, the location is the address of the LDAP server that will be used.

In order to store the repository in an LDAP server, the server must be updated to support the Micro Focus configuration objects.

CAUTION:

If you change the location and the destination already contains a repository, you will be warned and given the opportunity to overwrite it or to cancel the operation.

Note:

When you specify ldap:// as the storage mechanism, additional fields are displayed for specifying the container in which the data will be stored, and the LDAP user credentials required to write to the container.

Repository Container Distinguished Name

The distinguished name of the LDAP container in which the repository is to be stored.

User DN:

The distinguished name of the LDAP user with which to access the repository. This user must have permission to read and write to the container.

User Password:

The password of the user with which to access the repository.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Directories

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of all MF Directory Server instances that are running on the local network and using the default MF Directory Server port (86).

Version

Shows the version of the Directory Server software in use.

IP Address

Shows the IP address of the machine on which the Directory Server is running.

DNS Resolved Hostname

Shows the DNS-resolved hostname of the machine on which the Directory Server is running. If there is a right-pointing arrow next to this name, you can click it to open Enterprise Server Administration for the instance of Directory Server running on the other machine. What you can do depends on how security has been configured on the other machine.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view statistics and status information about the Directory Server.

Repository

This table shows information about the repository.

Location

Shows the directory containing the repository of all registered object information. If the path is relative it is relative to the Directory Server current directory.

Status

Shows the last action performed on the repository.

Objects

This table contains statistics about the objects stored in the local repository.

Servers

Shows the number of servers stored in the local repository.

Communications processes

Shows the number of communications processes stored in the local repository.

Listeners

Shows the number of listeners stored in the local repository.

Services

Shows the number of service operations stored in the local repository.

Handlers

Shows the number of request handlers stored in the local repository.

Packages

Shows the number of implementation packages stored in the local repository.

XA Resources

Shows the number of defintions of XA resources stored in the local repository.

Total Count

Shows the total number of objects stored in the local repository.

Request Processing

This table contains information about incoming client requests.

TCP Requests

Shows the number of TCP requests received since the Directory Server was started. These can come from either program clients or Web browser clients.

UDP Requests

Shows the number of UDP requests received since the Directory Server was started. These come only from program clients.

MLDAP Requests

Shows the number of TCP or UDP MLDAP requests received since the Directory Server was started. These can be generated by enterprise servers or program clients

Maximum Thread Count

Shows the maximum number of concurrent MLDAP requests that have been processed at any time since the Directory Server was started

Current Thread Count

Shows the number of MLDAP requests currently being processed.

Options

This table contains some of the current Directory Server option settings.

User Access

Shows what level of access is available to users. Possible values are:

Restricted | Access is allowed only by an authorized user who has logged on.
Unrestricted | Access is allowed by any user.
Server Monitor

Indicates whether the server monitor is currently active or not. The server monitor checks whether all enterprise servers registered with the Directory Server and not marked "Stopped" are responding to potential client requests. If they are, their status is marked as "Started", otherwise, if they are currently marked as "Started" and they are not responding, they are marked as "Not Responding".

Having the server monitor on ensures that the Current status field for a server is up to date, even if the server itself cannot contact the Directory Server for some reason, for example, a network connection or machine failure.

You can enable and disable the server monitor and change the time interval between checks on the Configure Options page.

Journal Level

Indicates what level of journal logging is in force.

Paths

This table contains the paths that the Directory Server is using for its own resources.

COBDIR

Shows the setting of the COBDIR environment variable, which holds the location of your installed development system or standalone Enterprise Server. This field might be empty if the Directory Server is being run as a Windows service, as this environment variable is not one that is set by the Windows system.

Executables

Shows the location of the system programs that make up Enterprise Server.

Artwork

Shows the location of the graphics files that the Directory Server uses in its interface.

Help and documentation

Shows the location of the documentation for Enterprise Server.

Trace and journaling

Shows the location of the trace files and journals created by Enterprise Server.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Sessions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of currently logged on Web browser clients and program clients. The sessions may be really active, or they may be dormant but not yet removed because the time period between inactivity and removal has not yet been exceeded.

Session ID

Shows the unique identifier string of the session. The session ID is in the format userid-string where userid is the user ID that was used to authenticate the session and string is a unique internal identifier for a Web browser session. string is not present for a program client.

Last Active

Shows the local date and time that the session last requested a response from the Directory Server, for example, a browser refresh or a client program request.

Permission Level

Shows the permission level of the session user. The possible values are:

Unauthenticated | The user is a program client that is performing a query and does not need to be authenticated.
Modify | Values stored in the schema can be modified.
Add/Delete | Values stored in the schema can be modified and objects can be added and deleted. This is normally the highest permission level a program client would need.
Administrator | All of the above, plus objects can be backed up, imported, and the Directory Server can be remotely terminated.
Schema Administrator | All of the above, plus users can be added, modified and deleted and the entire repository can be deleted.
Session Type

Shows the type of user session. The possible values are:

UI | Web browser client
API | Program client
Parent topic: Enterprise Server Administration Side Bar Menu


Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the journal, a file that records some of the Web browser client and program client activity occurring on the Directory Server.

Note:
  • You can scroll up and down the list of entries using the scroll buttons on the right-hand side of the table.
  • The most recent entries are shown first.
Entries generated

Shows the total number of journal entries generated since this journal file was started. This could be the same or more than the value in Entries held, depending on whether the oldest entries have been overwritten by more recent ones.

Entries held

Shows the total number of journal entries currently stored in the journal file. The maximum value is determined by the configured maximum journal file size; once it is reached, new journal entries overwrite the oldest journal entries.

Journal Size

Shows the current size of the journal file in bytes.

Entry

Shows the entry number of the journal record. When the journal file is restarted or deleted, the entry number is reset back to 1, and is sequentially incremented for each following journal entry.

Time

Shows the local date and time that the journal record was written to the journal file.

Requester

Shows the unique identifier string associated with a particular session. For a Web browser session logged onto the user interface, this is the same identifier as appears in the top right-hand corner of the Web page. For a program client session, the source network address for the request is also shown.

If no requester identifier is shown, the journal event was generated by an internal action or there was no information available about the requester.

Event

Shows the text of the journal event, up to 128 characters.

Green text indicates that the journal event has been generated by program client requests.

Red text indicates that the journal event has been generated by Web browser requests.

Black text indicates that the journal event has been generated by the Directory Server itself.

Delete

Click this to delete this journal and start a new one. You might want to do this if you are debugging a problem with a service and you want a well-defined journal starting-point.

Export As Text

Click this to export the journal entries to a text file. The text file will be called journal.txt and will be saved to /var/mfcobol/logs . 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Important: Use the Help > This Page option in the left side-bar to display up-to-date context help on the current Enterprise Server screen. To access up-to-date Enterprise Server product help, go to the Micro Focus Product Documentation site.

This is the Enterprise Server Administration home page that lists the Enterprise Server instances. It is displayed:

  • When you have just logged onto Enterprise Server Administration
  • Any time you click Home at the top of the menu bar on another page.
You use this page as a starting point for all the administration functions. From it you can:
  • Add a server
  • Change the attributes of a server
  • Change the status of a server
  • Go to a more detailed view of the listeners, services, request handlers and implementation packages.
Note: The options available to you depend on the permissions granted to the user groups of which your user account is a member. Those options that are not available to you are hidden.

Use the side bar menu items to access your installation's configuration options, maintained on the Micro Focus Dirctory Server (MFDS).

Expand/Contract button

Click [image] in the left-hand corner of the servers table to see an expanded version of the information in the Objects column, or the minus icon ( [image]) to see a contracted version of the information in the Service Listeners, Services, Request Handlers and Implementation Packages columns.

Refresh Icon

Click Refresh to update the display to show changes in the server status and attributes.

Show

Specify the number of servers to show at a time. Click Refresh to update the screen display.

Previous

Click this to view the previous page of servers. You can click this only if the number of servers is greater than can be shown on one page.

Next

Click this to view the next page of servers. You can click this only if the number of servers is greater than can be shown on one page.

Filter

Click this to update the display according to the Type, Name and Status attributes selected.

Filter by Type

Select the type of server from the drop-down list that you want to be displayed in the server list. Click Refresh to update the screen display with your selection.

Filter by Name

Type the name of the server you want to see in the server list. You can use wildcard characters '*' and '?' to modify your criteria. Click Refresh to update the screen display with your selection.

Filter by Status

Select the status from the drop-down list to display a list of matching servers. Click Refresh to update the screen display with your selection.

Delete

Click this to delete this server. You can see this only if this server is a CCI server.

Edit

Click this to edit configuration settings for this server.

Type

Shows the server type. There are two types of server:

  • MFES

    A Micro Focus enterprise server. This is a server type that provides a run-time environment for COBOL programs running as services.

  • MFCCI

    A Micro Focus Common Communications Interface server. This is a server that provides services using the Common Communications Interface (CCI), using the Directory Server as a naming service instead of registering with a CCITCP2 process.

The icon in the Type column will display '64' if the server has been set up for 64-bit working mode.

You can start and stop enterprise servers using Enterprise Server Administration. You cannot start and stop MFCCI servers from Enterprise Server Administration; if an MFCCI server is running on the network and has been configured to use the Directory Server, it appears in the list of servers automatically, with the status "registered". For more information about CCI, see your Configuring CCI book.

Name

Shows the name of the server.

Current Status

Shows the current status of this server. The possible values are:

Stopped | The server is currently not running.
Stopping | The server is currently in the process of terminating. This is normally a short-lived status value which should be shortly followed by a change to the value "Stopped".
Started | The server is currently running and can respond to client and server requests.
Starting | The server is currently in the process of starting. This is normally a short-lived status value which should be shortly followed by a change to the value "Started".
Not Responding | The server process was previously marked as "Started", but the server monitor has subsequently not been able to contact it. There may be some network connection error, or the server itself may have abnormally terminated without first marking itself as "Stopped".
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Registered | This status is applicable only to CCI servers. It indicates that the Directory Server has been notified that a CCI server has started.
Start

Click this to start the server. You cannot see this push button unless the server has the status "Stopped" .

Current Status Details

Click this to move to a page giving more detailed information about the current status of the server. You cannot see this push button when the server has the status "Stopped".

Stop

Click this to start the server. You cannot see this push button unless the server has the status "Started" or "Not Responding".

Communications Processes

Lists the communications processes owned by the enterprise server. By default an enterprise server owns one communications process; you can create additional ones. For each process the following information is shown:

  • The number of the process. Numbers are allocated from 1 sequentially.
  • The network address used by the communications process to accept incoming client requests. The format is:

    protocol:ip-address:port

    where:

    • protocol is tcp.
    • ip-address is the IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the enterprise server when it starts.
    • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the enterprise server when it starts.
  • The TCP/IP hostname that is equivalent to the IP address.

The total number of listeners owned by all the communications processes.

Listeners Details

Click this to move to a page giving more detailed information about the service listeners owned by the communications processes.

Licenses

Shows license information. The number before the slash is the number of licenses allocated to this server. When the server is stopped a dash is displayed, because the number of licenses that will be allocated is unknown until the server is started. When the server is running an asterisk can be displayed, indicating that unlimited licenses were allocated. The number after the slash is the number of licenses requested by this server.

Last Status Change

Shows the date and time that the server's current status was last updated; this is local to the machine where the Directory Server is running. You can see this only in the expanded view of the Home page.

Status Log

Shows information about the most recent event that occurred on this server, and how long the server has been in its current state.

Objects

Shows how many of each type of object (services, handlers, packages) the server owns. This is a summary view - it changes when you click the Expand the plus button button

Services

Shows a list of the service operations registered with the Directory Server. If there are more than five, only the first five are shown.

Service Details

Click this to move to a page giving more detailed information about the services registered with the Directory Server.

Request Handlers

Shows a list of the request handlers registered with the Directory Server.

Request Handlers Details

Click this to move to a page giving more detailed information about the request handlers registered with the Directory Server.

Implementation Packages

Shows a list of the implementation packages registered with the Directory Server. If there are more than five, only the first five are shown.

Implementation Packages Details

Click this to move to a page giving more detailed information about the implementation packages registered with the Directory Server.

Description

Shows a description of the server.

Add

Click this to add a new server.

  • Add Server instance
  • Delete Server instance
  • Start Server confirmation
  • Stop Server Confirmation
Parent topic: Enterprise Server Administration Console Help Pages


Add Server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to provide the attributes for an enterprise server (MFES).

Note:

For more information about the configurable attributes of servers, see the chapter Configuration in your Configuration and Administration Guide.

Name

Shows the name of the server.

Server Address

Specify the network address used by the server to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the enterprise server when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the enterprise server when it starts.

If this network address is not unique in the repository, this might cause enterprise server startup problems.

System Directory

Specify the location for system work files output by the Enterprise Server, such as the console log, and trace and dump diagnostics files. This directory cannot be shared between Enterprise Servers. The default is /var/mfcobol/es/es-name (where es-name is the name of the enterprise server).

If you specify a directory in this field, that directory must exist; Enterprise Server does not create it for you.

Working Mode

Choose whether this Enterprise Server is to run 32-bit or 64-bit applications.

A 32-bit working mode server can run only 32-bit applications. A 64-bit working mode server can run only 64-bit applications.

You cannot change the working mode of the server once it has been created; you can however, change the mode when you copy or import a server.

Startup Options

Use these fields to specify the server configuration you want when the server first starts up. Any changes you make to these fields while a server is running do not take effect until the next time you start the server.

Shared Memory Pages

Specify the number of shared pages in memory to be reserved for all the processes that run in the Directory Server. Each page is 4KB long.

Service Execution Processes

Specify the number of service execution processes that are to be started at server initialization.

Shared Memory Cushion

Specify the number of 4KB pages that should be reserved from the shared memory pages to allow the server to continue processing when the shared memory allocation is too small for the operational requirements of the server. The range is 1 through the number of shared memory pages.

Trace Table Size

Specify the number of entries the trace buffer can hold before it wraps back to the start. (The trace buffer is also written to disk at this point if you checked Auxiliary Trace Active.) A value of 2 means that there is space for only one entry, and if you checked Auxiliary Trace Active each entry is written straight out to disk. Each entry is 24 bytes long.

Local Trace Size

Specify the number of entries the local trace table can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Each service execution process has its own local trace table. Each entry is 24 bytes long.

Maximum Diagnostics File Size

Specify the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size.

Requested Licenses

Specify the number of licenses this enterprise server requires.

Cold Start Diagnostics File

Check this to indicate that the auxiliary trace and dump files are to be deleted when the server starts.

Dump on System Abend

Check this to indicate that the server should produce a dump if one of its own processes, such as a service execution process, terminates abnormally. The dump information can help you to determine the cause of the abnormal termination

Auxiliary Trace Active

Check this to indicate that trace records are to be flushed to disk before the trace table is overwritten. You should do this only if you have adequate disk space available, since the file can become very big very quickly. If you have a high-activity system use this field in conjunction with Maximum Diagnostics File Size to limit the disk usage. Writing out to a file also degrades performance.

Show Local Console

Check this if you want to see a text window containing enterprise server messages while the server is running. the messages are written to a file called console.log, in the directory specified in System Directory. You can see the text window only on the machine running the enterprise server. The system messages are also available on the Enterprise Server Console page.

Trace Flags

Use these flags to control what information is written to the trace file for this server. Any changes you make to these fields while a server is running take effect immediately.

Task Control

Check this to indicate that the server is to trace its task control component.

Storage Control

Check this to indicate that the server is to trace its storage control component.

Table Management

Check this to indicate that the server is to trace its table management component.

Application Container

Check this to indicate that the server is to trace its application container component.

Request Handler

Check this to indicate that the server is to trace its request handler component.

RM Interface

Check this to indicate that the server is to trace its resource manager interface component.

Communications

Check this to indicate that the server is to trace its communications component.

Exit

Check this to indicate that the server is to trace user and system exits.

Configuration Information

Specify textual configuration information that determines the start-up and run-time behavior of the server. Optional. For details of the valid entries, see the section Configuration Information in the chapter Servers in your Configuration and Administration Guide.

Description

Specify a text description of the server, for example, its purpose and owner. Optional.

Add

Click this to add the new server to the Directory Server repository.

Back

Click this to return to the previous page.

Parent topic: Enterprise Server Administration Home Page


Delete Server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected server.

Note:

Deleting a registered server may cause application connection errors and loss of data.

Type

Shows the server type. There are two types of server:

  • MFES

    A Micro Focus enterprise server. This is a special server type that provides a run-time environment for COBOL programs running as services.

  • MFCCI

    A Micro Focus Common Communication Interface server. This is a server that provides services using the Common Communication Interface (CCI), using the Micro Focus Directory Server as a name server instead of registering with a Micro Focus CCITCP2 process.

Name

Shows the unique name of the server.

Status Log

Shows information about the most recent event that occurred on this server.

Services

Shows the number of services registered with this server.

Description

Shows a text description of the server.

Stop server before deleting it

Check this if you want the server to be stopped before it is deleted.

Parent topic: Enterprise Server Administration Home Page


Start Server confirmation

Use this page to confirm user credentials for starting an enterprise server.

Type

Shows the server type. The only type of server you can stop is an MFES server. MFES stands for Micro Focus enterprise server. This is a server type that provides a run-time environment for COBOL programs running as services. MSS in brackets after MFES indicates that the server has Mainframe Subsystem Support (MSS) enabled.

Name

Shows the name of the server.

Status Log

Shows information about the most recent event that occurred on this server, and how long the server has been in its current state.

Description

Shows a description of the server.

Security settings

This section indicates whether the server is using its own security settings and associated security manager list, or the Default ES Security configuration settings, which can be shared by multiple servers.

Where it is using its own security settings, the security managers in its security manager list are displayed.

Start processes as

This specifies the operating system account under which the enterprise server 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
  • Server Instance Properties: General
  • Server Instance Properties: XA Resources
  • Server Instance Properties: MQ Support
  • Server Instance Properties: Scripts
  • Server Instance Properties: Permissions
  • Server Instance Control
  • Server Instance Diagnostics
  • Server Instance Properties: Security
  • Enterprise Server Monitor and Control (ESMAC)
Parent topic: Enterprise Server Administration Console Help Pages


Server Instance Properties: General

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the basic configurable attributes of an enterprise server instance.

To access this page:

  1. On the server instance screen, select the Server > Properties > General tabs.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
Name

Specify the unique name of the server, up to 8 characters. You can change the name only if the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

System Directory

Specify the location for system work files output by the Enterprise Server, such as the console log, and trace and dump diagnostics files. This directory cannot be shared between Enterprise Servers. The default is $COBDIR/var/mfcobol/es/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; COBOL Server does not create it for you.

Working Mode

Shows whether this Enterprise Server is to run 32-bit or 64-bit applications.

A 32-bit working mode server can run only 32-bit applications. A 64-bit working mode server can run only 64-bit applications.

You cannot change the working mode of the server once it has been created; you can, however, change the mode when you copy or import a server.

Startup Options

Use these fields to specify the server configuration you want when the server first starts up. Any changes you make to these fields while a server is running do not take effect until the next time you start the server.

Shared Memory Pages

Specify the number of shared pages in memory to be reserved for all the processes that run in the Directory Server. Each page is 4 KB long.

Service Execution Processes

Specify the number of service execution processes that are to be started at server initialization.

Shared Memory Cushion

Specify the number of 4KB pages that should be reserved from the shared memory pages to allow the server to continue processing when the shared memory allocation is too small for the operational requirements of the server. The range is 1 through the number of shared memory pages.

Requested Licenses

Specify the number of licenses this enterprise server requires.

Show Local Console

Check this if you want to see a text window containing enterprise server messages while the server is running. the messages are written to a file called console.log, in the directory specified in System Directory. You can see the text window only on the machine running the enterprise server. The system messages are also available on the Enterprise Server Console page.

Allow Dynamic Debugging

Check this if you want to use a local or remote IDE to debug applications running in this enterprise server.

Start on System Start

Check this if you want to start the ES server when the MF Directory Server process is started. The MF Directory Server process (mfds) is usually started at system startup (e.g. on Windows it is registered as a system service by default). Typical usage is to ensure a set of ES servers are re-started automatically if a machine is re-booted. If security is enabled and the default credentials are disabled, ensure valid credentials are specified in the server "Security" properties "Automated Execution Control Enterprise Server Credentials" section.

64-Bit Working Mode

This box is for information only and will be checked if the server has a working mode of 64-bit.

Purge Old Logs

Check this if you want to remove existing console.nnn backups.

Console Log Size

Specify the maximum size of the console.log. Once this size is reached, it will be backed up as console.nnn (with nnn being incremented with each new backup) and subsequent messages will be logged to a new console.log. If set to 0, a single console.log will be created (if one already exists on startup, this will be backed up as console.bak).

Configuration Information

Specify textual configuration information that determines the startup and run-time behaviour of the server. Optional. Prefix comments with the number sign (#).

Description

Specify a text description of the server, for example, its purpose and owner. Optional.

Export

Click this to export information about this server and the objects it contains in a specified location.

Copy

Click this to create a new server that is identical to this server apart from its name.

Delete

Click this to delete this server.

Validate

Click this to generate a Validation report for this server. The Validation report informs you of any server configuration errors.

Parent topic: Edit Server Instance Properties


Server Instance Properties: XA Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the external resource managers registered with the currently selected server. From this page you can also:

  • Edit the resource manager definition
  • Add a new resource manager

To access this page:

  1. On the server instance screen, select the Server > Properties > XA Resources tabs.
ID

Shows the resource manager ID, used internally to identify a particular XA configuration.

Name

Shows the name by which the resource manager is known.

Module

Shows the location of the executable file (.dll on Windows, .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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to specify the details of an external resource manager that the server needs to communicate with on behalf of container-managed applications.

To access this page:

  1. From the Enterprise Server Administration Home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > XA Resources tabs.
  3. Select the XA resource to display.
ID
Specify 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 . See 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 ( .so) 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.
Reconnection attempts
The reconnect value controls how many attempts are made to connect to the XA resource. The default value is 1. A value of 0 is not permitted. A -1 value instructs it to continually retry.
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: 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to edit advanced attributes of an enterprise server.

To access this page:

  1. On the server instance screen, select the Server > Properties > Scripts tabs.
ES Start Script

Specify a script to be executed to start the enterprise server. This will override the casstart command that is executed when you start an enterprise server. It is used only if you check Enabled (start script).

Enabled(start script)

Check this to enable the ES Start Script.

ES Stop Script

Specify a script to be executed to stop the enterprise server. This will override the casstop command that is executed when you stop an enterprise server. It is used only if you check Enabled (stop script).

Enabled(stop script)

Check this to enable the ES Stop Script.

On server not responding after n connection attempts

Specify the number of reconnection attempts that you want to take place before taking the action in the small entry field; the default is 1. Specify a script to be executed when the server has failed to respond to the server monitor the number of times specified in the large entry field. It is used only if you check Enabled (non-response script).

Enabled (non-response script)

Check this to enable the non-response script.

Process User ID

UNIX only. Specify a user ID to be attached to all processes started for this enterprise server, including the server itself. If you do not specify a Process User ID, the value set in Default Process User ID on the Configure Options page is used, if there is one. Otherwise, all processes run as user root, which can create problems with security and access to files. You can specify either a numeric user ID or a username.

Parent topic: Edit Server Instance Properties


Server Instance Properties: Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to specify the permissions of user groups for this enterprise server.

To access this page:

  1. On the server instance screen, select the Server > Properties > 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to monitor an enterprise server instance's processes, and to access the Enterprise Server Monitor and Control (ESMAC) user interface.

To access this page:

  1. On the server instance screen, select the Server > Control tabs.
  • Server Instance Control Settings
Parent topic: Edit Server Instance Properties


Server Instance Control Settings

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view and change detailed status information for a running an Enterprise Server instance, and to access ESMAC.

To access this page:

  1. On the server instance screen, select the Server > Control tabs.
ES Monitor and Control

Click this to go to Enterprise Server Monitor and Control (ESMAC), which provides a range of monitoring and control facilities for enterprise servers.

Service execution processes

Shows a list of all the service execution processes running on this enterprise server..

Count

Shows a sequence number for the service execution process.

Type
Shows the type of service execution process. The possible values are:
Debug
A service execution process that is being used to debug a service. This service execution process must have been started from the command line.
Normal
A normal service execution process started from the Home page of Server Administration.
Transient
A service execution process that is executing a service which has corrupted the application container, or a service that is responding to a long-running Java stateful session bean. The transient service execution process will terminate when the current service is complete, and be replaced by a new service execution process.
PID

Shows the process identifier of the service execution process. You can use this for tracking and debugging purposes.

TR Count

Shows the number of transactions this service execution process has handled since the server was started.

State
Shows what state the server is in. The possible values are:
Idle
The server is idle and waiting for client requests.
Running
The server is busy, that is, one of the services is currently processing a client request.
Executing

Shows the name of the service that is currently being executed.

Start Time

Shows the time that the current transaction started. This time is local to the machine where the Directory Server is running.

Local Time

Shows the current time. This time is local to the machine where the Directory Server is running.

Duration

Shows how long the current transaction has been running.

Auxiliary processes

Shows a list of all the auxiliary processes running on this enterprise server. Auxiliary processes are system processes that support the activity of the enterprise server.

Type (auxiliary processes)

Shows the type of auxiliary process.

PID (auxiliary processes)

Shows the process identifier of the auxiliary process. You can use this for tracking and debugging purposes.

Requested service execution processes

Specify a new number of service execution processes.

Allocated licenses

Shows the number of licenses allocated to this enterprise server. Can display "Unlimited" if an unlmited number of licenses were allocated.

Requested licenses

Specify a new number of licenses required for this server. You cannot specify a new number of licenses if Allocated licenses is set to "Unlimited".

Update

Click this to update the number of service execution processes or licenses available for this server. When you change the number of service execution processes, the server takes about 20 seconds to start the new processes or shut down existing processes. When you change the number of licenses, extra licenses are granted or refused immediately, and any licenses not required are returned to the pool of unused licenses. When the server is restarted it will use the number of service execution processes and the number of licenses configured in the Edit Server page.

Stop Server

Click this to stop the server.

The server begins to shut down and you are returned to the Home page.

Parent topic: Server Instance Control


Server Instance Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the basic configurable attributes of an enterprise server instance.

To access this page:

  1. On the Edit screen, select the Diagnostics tab.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
  • Server Instance Diagnostics: Trace
  • Server Instance Diagnostics: Dump
  • Server Instance Diagnostics: ES Console
  • Server Instance Diagnostics: CS Console
Parent topic: Edit Server Instance Properties


Server Instance Diagnostics: Trace

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the trace attributes of a server.

CAUTION:
Changing the properties of a registered server may cause application connection errors and loss of data.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > Trace tabs.
Trace Table Size

Specify the number of entries the trace buffer can hold before it wraps back to the start. (The trace buffer is also written to disk at this point if you checked Auxiliary Trace Active.) A value of 2 means that there is space for only one entry, and if you checked Auxiliary Trace Active each entry is written straight out to disk. Each entry is 24 bytes long.

Local Trace Size

Specify the number of entries the local trace table can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Each service execution process has its own local trace table. Each entry is 24 bytes long.

Maximum Diagnostics File Size

Specify the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size.

Cold Start Diagnostics File

Check this to indicate that the auxiliary trace and dump files are to be deleted when the server starts.

Dump on System Abend

Check this to indicate that the server should produce a dump if one of its own processes, such as a service execution process, terminates abnormally. The dump information can help you to determine the cause of the abnormal termination

Auxiliary Trace Active

Check this to indicate that trace records are to be flushed to disk before the trace table is overwritten. You should do this only if you have adequate disk space available, since the file can become very big very quickly. If you have a high-activity system use this field in conjunction with Maximum Diagnostics File Size to limit the disk usage. Writing out to a file also degrades performance.

Trace Flags

Use these flags to control what information is written to the trace file for this server. Any changes you make to these fields while a server is running take effect immediately.

Task Control

Check this to indicate that the server is to trace its task control component.

Storage Control

Check this to indicate that the server is to trace its storage control component.

Table Management

Check this to indicate that the server is to trace its table management component.

Application Container

Check this to indicate that the server is to trace its application container component.

Request Handler

Check this to indicate that the server is to trace its request handler component.

RM Interface

Check this to indicate that the server is to trace its resource manager interface component.

Communications

Check this to indicate that the server is to trace its communications component.

Exit

Check this to indicate that the server is to trace user and system exits.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of diagnostic dumps created for this server.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > Dump tabs.
Note: If no diagnostic dumps have been created, this list is empty, and instead you see some text explaining this and the Create Dump button.
Show

Click this to view the dump on this row.

Create Dump

Click this to create a diagnostic dump for this server.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: ES Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the Enterprise Server console log for this enterprise server instance.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > ES Console tabs.
Note: If the enterprise server is not running, you see the message: "No live console data returned."
Show Entries

Click the radio button to the left of this control if you want to view a subset of the entries. Then specify the start and end of the subset in the two entry fields to the right. Click Refresh to view the specified subset.

Show Last

Click this if you want to view a subset of the entries at the end of the log. Then enter the number of entries you want to view in the entry field to the right. The default is that the last 10 lines are shown. Click Refresh to view the specified subset.

Entry

Shows the number of the event. Events are numbered in chronological order, with the most recent last.

Event

Shows a description of the event. Each description starts with the date and time it occurred and the name of the enterprise server.

Show Entire Log

Click this if you want to view the entire log. It should open in whatever application your browser is configured to use for text files.

Historical data available

If the status of the server is anything other than "Started", and the Directory Server is running on your machine, shows the location on your machine of the most recent console log for the server. If you click the right-pointing arrow at the end of the location, the file should open in whatever application your browser is configured to use for text files. If the file fails to open, you can go to the location and open it from there.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: CS Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the communications processes console log for this enterprise server.

Note: If the enterprise server is not running, you see the message: "No live console data returned."

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > CS Console tabs.
Show Entries

Click the radio button to the left of this control if you want to view a subset of the entries. Then specify the start and end of the subset in the two entry fields to the right. Click Refresh to view the specified subset.

Show Last

Click this if you want to view a subset of the entries at the end of the log. Then enter the number of entries you want to view in the entry field to the right. The default is that the last 10 lines are shown. Click Refresh to view the specified subset.

Entry

Shows the number of the event. Events are numbered in chronological order, with the most recent last.

Event

Shows a description of the event. Each description starts with the date and time it occurred.

Show Entire Log

Click this if you want to view the entire log. It should open in another browser window.

Historical data available

If the status of the server is anything other than "Started", and the Directory Server is running on your machine, shows the location on your machine of the most recent 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 $COBDIR/etc .

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define the security settings to be used with this enterprise server.

Use default Security Configuration

Check this if you want to use your default security settings for this enterprise server. To define the default settings, click Security on the menu on the left hand side, and then click Security > Default Security Configuration.

Restrict user access

Check this to cause all access to the enterprise server through Enterprise Server Administration to be checked by the security managers specified in the Security Manager Priority List.

Verify against all Security Managers

Set this if you want each 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)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use ESMAC to change the basic configurable attributes of an enterprise server instance.

To access ESMAC:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Control tabs.
  3. On the Control page, click ES Monitor & Control.
  • Enterprise Server Monitor and Control - S2 Sidebar Help
  • Server
  • Monitor (1, 15)
  • HSF
  • Control
  • SEPs
    Use this page to view information about the service execution processes (SEPs) on the current server.
  • Clients
  • Diagnostics
  • Resources
  • Users
  • Env.Vars.
  • Dyn.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. The sidebar menu enables you access to these functions. When you click a button in the sidebar, the body of the page changes, providing information, or controls which you can use to modify settings. For help on the body of the page, click Help, Body.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Home

Click this to return to the Enterprise Server Administration home page.

Server

Click this to display information about the current server.

Monitor 1, 15

Click Monitor 1 to display information about tasks, collected at one minute intervals. Click Monitor 15 to display information about tasks, collected at 15 minute intervals.

Control

Click this to view and change control information for this server.

SEPs

Click this to view information about the SEPs (service execution processes) running on this server.

Clients

Click this to view information about the clients using this server.

Diagnostics

Click Display to view the console log, or a dump or trace data set. To select the diagnostic information to view, click:

  • Log - displays the console log. The buttons A, B and C/x have no effect with this button.
  • Dump - displays the dump data set specified by the button A, B or C/x. If you select C/x, the X dump data set is displayed.
  • Trace - displays the trace data set specified by the button A, B or C/x. If you select C/x, the in-memory trace table is displayed.
  • Blocks - specifies the number of blocks of diagnostic information to display.
Reply

Click this to view the list of current outstanding replies to ACCEPT FROM CONSOLE statements. You can see this button only if there is at least one outstanding reply.

Resources

Use the buttons in this group to:

  • View the services, packages and handlers available on this server.
  • View and maintain all active resource tables for this server.
  • View and maintain all resource tables for this server.

To access the relevant pages, click the dropdown box. You can choose an item from the list. When you choose an item, extra buttons are displayed that enable you to display the information required. You can select:

Services
When you select this, you can click:
  • Services - to view the services available on this server.
  • Package - to view the implementation packages available on this server.
  • Handlers - to view the request handlers available on this server.
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.
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)


Server

Use this page to view system information for the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Times

Shows the date and time at which the current server was started, and the number of days, hours, minutes and seconds that have passed since the server was started.

Counts

Shows the following information:

  • Transactions - the number of transactions that have occurred since the server was started.
  • Dumps - the number of dumps generated since the server was started.
  • Per hour - the number of transactions per hour, based on the number of transactions shown in Transactions.
  • Trace Blocks - the number of trace blocks generated since the server was started.
  • Active Clients - the number of clients that have been active since the server was started.
  • Limit - the number of concurrent client licenses allowed.
Sizes

Shows the following information:

  • Max Tasks - the maximum number of tasks that can run concurrently on this server. A task handles a process such as a SOAP service, and so on.
  • HTTP Out - the size of the data blocks passed across shared memory for HTTP output.
  • Diagnostics Size - the maximum size of a diagnostic data set. When this size is exceeded, the alternate (A or B) data set is used (and any data in that data set is overwritten). A value of 0 (zero) means that there is no maximum size.
  • ID Timeout - the global user ID timeout specified. If no ID timeout ha been defined, this field is blank.
  • Shared Memory - the number of shared pages in memory reserved for all the processes that run in the enterprise server. Each page is 4 KB long.
  • SM Total - the amount of shared memory available to this server, shown in kilobytes.
  • SM Cushion - the number of kilobytes reserved from the shared memory pages to enable the server to continue processing when the shared memory allocation is too small for the operational requirements of the server.
  • SM Free - the amount of shared memory currently free, shown in kilobytes.
States

Shows the following information:

  • Working Mode - the current working bit mode of the server.
  • Dump - shows which data set is currently set to receive dump information, which can be A or B.

    You can set the data set to be used for dump information on the Control page, which can be displayed by clicking Control.

  • Dump on Abend - the dump state. The dump state can be:
    • Sys: No Tran: No
    • Sys: Yes Tran: No
    • Sys: No Tran: Yes
    • Sys: Yes Tran: Yes

    where Sys indicates a system dump, and Tran indicates a transaction dump.

    You can set the dump state on the Control page, which can be displayed by clicking Control.

  • Trace - shows which data set is currently set to receive trace information, which can be A or B.

    You can set the data set to be used for trace information on the Control page, which can be displayed by clicking Control.

  • Active trace - indicates whether the in-memory trace is currently being recorded to the active auxiliary diagnostic data set.

    You can switch the active trace on and off on the Control page, which can be displayed by clicking Control.

Activity

Contains the following information:

  • The time at which sampling of activity was started. The time is shown in 24-hour format. The duration of sampling is 15 minutes. To see the latest activity statistics for this 15-minute period, click Refresh.
  • Average latency (100/sec) - The average latency for transactions on this server. This is shown in hundredths of a second, and as a graphical representation in yellow.
  • Average tasks (100/sec) - The average time taken to complete a task on this server. This is shown in hundredths of a second, and as graphical representation in blue.
  • Task/sec - The average number of tasks completed per second on this server. This is shown as a number, and as a graphical representation in green.
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Monitor (1, 15)

Use this page to view information on transactions that have occurred in the last n minutes, where n is 1 or 15. The display is cumulative, showing activity in n-minute intervals over the last half-an-hour for Monitor (1 minute intervals), and over the last 8 hours for Monitor (15 minute intervals).

Restriction: This topic applies only when the Enterprise Server feature is enabled.
hh:mm

Shows the time, in 24-hour format, at which the last statistics collection period ended.

The rest of the row shows:

  • The average latency for a transaction. This is shown as a figure in hundredths of a second, and as a graphical representation in yellow.
  • The average time taken to complete a task. This is shown as a figure in hundredths of a second, and as a graphical representation in blue.
  • The task count - the number of tasks completed within the one-minute interval. This is shown as a figure, and as a graphical representation in green.
Parent topic: Enterprise Server Monitor and Control (ESMAC)


HSF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • HSF (summary)
  • HSF (transaction name)
Parent topic: Enterprise Server Monitor and Control (ESMAC)


HSF (summary)

Use this page to view summary HSF information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This shows the period of time (displayed in minutes and seconds next to Historical Statistics) between the earliest records displayed and the current time. Records older than one hour are deleted. The following information is shown for each transaction:

Average Latency
The average time, in hundredths of a second, between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in hundredths of a second, that the tasks ran for (not including latency time).
Count
How many times the task has run.
Parent topic: HSF


HSF (transaction name)

Use this page to view detailed HSF information for this transaction.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Latency+Resp
The sum of latency and response time averages.
Transaction
The name of task:
  • for Web services, the service name
Process ID
Process ID of the SEP which ran the task.
Task Number
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Parent topic: HSF


Control

Use this page to view and change control information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page. This button is displayed only if you have the required permissions.

General
SEPS

Shows the number of concurrent service execution processes currently supported by this server. You can change the number by entering a value in the field.

Admin
The number of Admin SEPs defined
HTTP Out

Shows the size of the data blocks passed across shared memory for HTTP output. You can change the HTTP size by entering a value in the HTTP Size field.

Timeouts
ID

Shows the time in minutes that the system will allow an ESMAC session to remain idle before logging off the user. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown.

Runaway

Shows the maximum continuous period of time in seconds that the region will allow a transaction to run without making an API call. When this value is exceeded, the transaction is abended. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown. Note also that you can override this value for an individual transaction through the relevant Program Control Table entry.

Deadlock

Shows the maximum time in seconds that the region will permit an application to wait for a resource that has been locked by another process. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown. Note also that you can override this value for an individual transaction through the relevant Program Control Table entry.

Diagnostics
Size

Shows the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size. You can change the size by entering a value, in kilobytes, in the Diagnostic Size field. The maximum size you can enter in this field is 999999 kilobytes.

Dump

Shows the current data set used for dump information.

Switch

Click this to switch between the A and B data sets that are used to store dump information.

Dump

Click this to initiate a dump. Dump information is stored in the data set identified by Active Dump DS. If you do not initiate a dump using Dump, dumps occur when the system and/or transaction abends. A dump will occur on an abend only if Sys and/or Tran is checked in the Dump on Abend group.

Countn

Shows the number of dumps (n) that have occurred.

Trace

Shows the current data set used for trace information.

Switch

Click this to switch between A and B data sets used to store trace information.

Aux, active

If checked, the in-memory trace data is transferred to the auxiliary (diagnostic) data set at the roll-over of the system trace table.

Blocks

Shows the number of blocks of trace information captured.

Dump on ABEND
Debugger
Check this to enable dynamic debugging.
HSF Data
Enable collection of Historical Statistics Facility (HSF) records
This switches on HSF processing.
Write to disk
Enables writing of HSF records to comma-separated files. These are called cashsf-a.csv and cashsf-b.csv, and are written to the system directory. Only one file is written to at any one time - this is called the active file.

You write to the active file until you click the ESMAC Switch button or when the active file reaches the maximum size, at which point the alternate file becomes active. If the alternate file already exists it will be backed up with the name cashsf.nnn where nnn is the number of the backup. When you start an enterprise server, cashsf-a.csv is always set as the active file, and if it already exists it is backed up.

Backup extensions are numbered from .001 up to .999. When a backup with extension .999 exists then the next backup will be created as cashsf.001. If cashsf.001 already exists then it will be overwritten.

Maximum HSF file size (KB)
If you have selected Write to disk, this is the size in kilobytes the .csv file will reach before Enterprise Server switches to the alternate .csv file. A value 0 selects the maximum size possible (4 Gb).
Number of records displayed by ES Monitor & Control
The number of HSF records that Enterprise Server will hold in memory. These records can be viewed by clicking on the HSF button in ESMAC while the server is running. When this number is reached, older records will be deleted when a new one is created. Records older than one hour are deleted too.
The minimum value is 0 (no HSF data displays in ESMAC), the maximum is 4096.

Clicking the Switch button will switch collection to the alternate .csv file before the active file has reached the maximum size.

Trace Points
Shows the currently set trace points. The trace points shown are those that have been set by the SIT. You can change individual trace points by checking the check box next to each trace point, or you can use all to change all the settings at once. This overrides the trace points set by the SIT. Any changes you make are effective immediately you click Apply. The changes are lost, however, the next time the server is initialized.
all
Choose a setting to apply to all the trace points:
  • On - enables all the trace points
  • Off - disables all the trace points
Attention: When you set all the trace points on at once, the trace points CCI, fh and fh-enable are unaffected. This is because these trace points should be used only when advised by Micro Focus.
Server
lock-data
Check this to trace lock management for non-threaded processes.
tsc
Check this to trace calls to the castsc process.
sql-api
Not used.
tsc-data
Check this to trace the data in calls to the castsc process.
fh
Do not check this unless advised by Micro Focus.
tsc-thread
Check this to trace thread processing and lock management in the castsc process.
fh-enable
Do not check this unless advised by Micro Focus.
trd
Check this to trace thread processing in all threaded processes.
xfp
Check this to trace data in transformer processing.
trd-enq
Check this to trace processes and data in transformer processing.
xfp-all
Check this to trace data and processes in transformer processing.
saf(security)
Check this trace System Authorization Facility (SAF) calls.
trd-stg
Check this to trace memory management in threaded processes.
xfp-data
Check this to trace data in transformer processing for threaded processes.
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.
mfcs-cg
Check this to trace Micro Focus Communications Server (MFCS) requests
common
Check this to trace thread processing in the communications module.
data-all
Check this to trace extended data in communication module.
cg-thread
Check this to trace lock management in the communications module.
Memory Strategy
Use this diagnostic feature to control the frequency and type of runtime memory validation, as well as specifying the processes to which these settings apply. You use this facility to help track down memory violations and corruptions. Unless you are directed otherwise by Support, Micro Focus recommends that you use only the default settings, which result in the most efficient use of memory. Setting these values inappropriately may result in a degradation of system performance and excessive memory usage. Using invasive settings in a development or user acceptance environment may be acceptable and even desirable, but you should apply caution when used in a production environment. You set the desired memory strategy at the time you wish to diagnose a particular problem, and reset the strategy when the diagnosis is complete.
Note: This feature is used for diagnosing "in-flight" memory problems. To diagnose system start-up or PLT program problems, you need to use the environment variable ES_MEM_STRATEGY .
You select the processes within Enterprise Server that you wish to monitor, and are:
SEPs
Service execution processes - recommended for diagnosing most user application memory problems.
MFCS
Micro Focus Communication System - 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)


SEPs

Use this page to view information about the service execution processes (SEPs) on the current server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The page is divided into five sections:

  • Standard - SEPs executing your transactions.
  • Auxiliary - processes run by the server that provide auxiliary services to the SEPs.
  • Debug - processes handling debug requests. You see this section only if there are debug processes executing.
  • Transient - long running processes. Once the process has completed, the SEP is removed from the list.
Trace

Click this to view a system trace for the SEP.

Kill

Click this to kill the SEP while a task is running.

Stop

Click this to stop the SEP when the current task completes.

Process ID, Start Time, Service/TranID

This column shows the process ID, the time at which the service was started, and the service or transaction ID (where available).

Type, Duration

This column shows the type of service and the amount of time the service has been running. The type can be:

  • SEP - service execution process
  • CAS Manager - An enterprise server management service
  • JCP - journal control program
  • TDP - extra-partition transient data program
  • Fileshare - A Fileshare service
Task Number, Client, Function

This column shows the task number for the service, the process ID (pid) of the client using this server, and the function. You can see which clients are associated with a process ID by displaying the Clients page; click Clients to do this.

Tran. count, Wait ID/Duration, User ID

This column shows the number of transactions performed by this SEP, the wait ID and user ID. The wait ID indicates, for suspended services, the ID of the process that is waiting to complete and the amount of time the process has been waiting. The user ID displays the ID of the signed-on client that is currently being processed.

Process ID, Start Time

This column shows the process ID and the time at which the service was started.

Initiator Classes, Duration

This column shows the classes that the batch initiator SEP handles and the amount of time the SEP has been running.

SYSOUT Classes, Duration

This column shows the classes that the batch printer SEP handles and the amount of time the SEP has been running.

Device

Shows the name of the printer being used.

Exit

Shows the pathname of the printer exit program that this batch printer SEP uses when it prints jobs, if any.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Clients

Use this page to display Client information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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:

  • 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
  • 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)


Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Dump data set
  • Trace store
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Dump data set

Use this page to view dump information, contained in data set, for the transactions on this server. data set can be A, B or X.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the dump selected. The detailed information includes the summary information at the end.

Sum

Click this to see summary information for the dump selected.

Level

Choose a level of trace information that you want to be included in the trace tables in the dump. The trace information includes system trace tables and local trace tables. The options are:

0 | Service start, module start, module end, service end.
1 | Enterprise server API entries and exits
2 | Subsystem trace entres
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries. This is the default.

This option affects what you see in a detailed dump, not a summary dump. Local trace tables (traces for SEPs) only have levels 0 and 1.

PID, Code (Caller)

Shows information about the dump:

  • The process ID
  • A code that helps identify the dump
  • The origin of the dump request
Date(mm/dd/yy) Time

Shows a date and time stamp for the dump. The time stamp is in hours, minutes, seconds, and hundredths of a second.

Parent topic: Diagnostics


Trace store

Use this page to view trace information contained in a dataset or in memory. store can be A or B, for the A or B datasets, or X to indicate an in-memory trace.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the trace selected.

Blocks

Specify the number of blocks that you want to be included in the detailed trace information starting at the first block in this index entry. The default is the number you specified in Blocks in the Diagnostics group in the menu.

Level

Choose a level of trace information that you want to be included in the details:

0 | Service start, module start, module end, service end. This is the default.
1 | Enterprise server API entries and exits
2 | Subsystem trace entres
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries
PIDs

If you want to filter the details by process ID, check the check boxes next to the process IDS of the processes you want detailed trace information for.

Task IDs

If you want to filter the details by task ID, check the check boxes next to the task IDS of the tasks you want detailed trace information for.

Date(mm/dd/yy) Time

Shows a date and time stamp for the dump. The time stamp is in hours, minutes, seconds and hundredths of a second.

Parent topic: Diagnostics


Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Services
  • Active
  • ESMAC
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Lists of Services
  • Details of Individual Services
Parent topic: Resources


Lists of Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Services
  • Service Packages
  • Request Handlers
Parent topic: Services


Services

Use this page to view information about the services currently available on the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to view detailed information for the service.

The rest of the information in this row shows:

  • The location of a service
  • The protocol used by the service
Show Sys Entries

Click this to view the system services.

The page expands to include all the system services currently running. You can click Details for any of these system services to get more information.

Hide Sys Entries

Click this to hide the system services.

This button is displayed only if you have previously clicked Show Sys Entries.

Parent topic: Lists of Services


Service Packages

Use this page to view information about the implementation packages available on the current server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to display detailed information for the package.

The rest of the information in this row shows the name of the implementation package.

Parent topic: Lists of Services


Request Handlers

Use this page to view information about the request handlers available on the current server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to view detailed information for the request handler.

The rest of the information in this row shows the name of the request handler.

Parent topic: Lists of Services


Details of Individual Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Service
  • Service Package
  • Request Handler
Parent topic: Services


Service

Use this page to view information about a particular service, selected from the Services page. You can also change the log status and create a new copy of the IDT.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page. This button is displayed only if you have permission to edit the service.

Name

Shows the service namespace.

Transaction

Shows the characteristics of the service. The characteristics relate to the commit/rollback of protected resources accessed by the service. Values can be Container Managed or Application Managed.

RTS Trace

Specifies the state of entry and exit tracing for the service:

  • None - no tracing is done
  • User - user applications are traced
  • System - the system is traced
  • Both - both applications and the system are traced
Log I/O

Shows whether, for each request for this service the request and response blocks are written to the enterprise server dump data set. If None, nothing is logged. If Dump, request and response blocks are written to the enterprise server dump data set. To set the log to None or Dump, click on the dropdown box, select the required setting, and click Change.

Only use this option if you need diagnostics, as it degrades performance.

Ref. Count

Shows the number of applications that reference this service.

Service Status

Shows the current status of the service. The possible statuses are:

  • In service - the service is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the service is disabled.
Parent topic: Details of Individual Services


Service Package

Use this page to view information about a particular implementation package, selected from the Service Packages page. You can also use this page to force the load of a new copy of the IDT.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Shows the name of the implementation package for this service.

IDT

Shows the path of the IDT (interface definition table) for the package.

IDT Size

Shows the physical size of the specified IDT. The IDT size is shown only if the IDT is currently loaded and held in shared memory.

New Copy

Click this to force a new copy of the IDT to be loaded for the next execution of the service. If an IDT is resident (that is, in shared memory), New Copy removes it, forcing the system to reload the IDT from disk the next time a service requests it.

Module

Shows the name of the library that contains the package, if any.

Status

Shows the current status of the implementation package. The possible statuses are:

  • In service - the package is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the package is disabled.
Location

Shows the path where the package file is located.

Ref. Count

Shows the number of programs that have made use of this package since the server started.

Parent topic: Details of Individual Services


Request Handler

Use this page to view information about a particular request handler, selected from the Request Handlers page.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Shows the name of the request handler.

Handle ID

Shows the unique ID assigned to this handler by the server.

Status

Shows the current status of the request handler:

  • In service - the request handler is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the request handler is disabled.
Type

Shows the type of request handler:

  • Other
  • Soap
  • CGI
  • Undefined
Location

Shows the path where the handler is located.

Ref. Count

Shows the number of programs that have made use of this handler since the server started.

Parent topic: Details of Individual Services


Active

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Lists of Active Resources
  • Details of an Active Resource
Parent topic: Resources


Lists of Active Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Locks (Active)
  • XAT (Active)
  • BUNDLE (Active)
  • PIPELINE (Active)
  • WEBSERVICE (Active)
  • RNL (Active)
Parent topic: Active


Locks (Active)

Use this page to view the current resource locks on this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Lock Ownership
Lists the current locks.
PID

Shows the process ID (PID) of a process that has issued a lock or wishes to issue a lock.

res-ID

Shows a resource ID allocated to the locked resource for the purposes of linking the information in the Lock Ownership part of the table with the information in the Resource Details part of the table.

Type

Shows the type of lock.

State

Shows the state of the lock. Possible states are:

Controlled | The requester has control of the resource
Waiting | The requester is waiting to gain control of the resource (synchronous request)
Pending | The requester has issued the request but has continued with other work (asynchronous request)
Persistence

Shows how long the lock lasts. Possible values are:

LUW | The lock lasts until the logical unit of work ends
Task | The lock lasts until the task ends
Lock Manager | There is no implicit release of the lock.
Process | The lock lasts until the process ends
Seq
The order in which requesters are to be handled.
Resource Details
Lists the resources that are locked.
Res ID (Resource Details)

Shows a resource ID allocated to the locked resource for the purposes of linking the information in the Lock Ownership part of the table with the information in the Resource Details part of the table.

Queue

Shows the lock namespace.

Length

Length of the resource name in characters.

Resource Name

Shows the name of the resource given to it by the requester.

Parent topic: Lists of Active Resources


XAT (Active)

Use this page to view the list of XATs defined in resource groups used by the startup list name.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the XAT in this row.

The rest of the information in this row shows:

  • The name of the XAT
  • Whether it is currently enabled or disabled
  • XAT
Parent topic: Lists of Active Resources
Parent topic: Enterprise Server Monitor and Control (ESMAC)


BUNDLE (Active)

Use this page to view the BUNDLES available on this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details
Click this to display detailed information for the WEBSERVICE.

The rest of the information in this row shows the name of the WEBSERVICE, whether the WEBSERVICE is enabled, disabled or unusable, and its associated PIPELINE and URIMAP.

Parent topic: Lists of Active Resources


RNL (Active)

Restriction: Only relevant in an Enterprise Server Cluster environment.

A resource name list (RNL) is equivalent to global resource sharing (GRS). In an Enterprise Server CLUSTER these RNLs are used to determine how to treat the resources referenced by these RNLs. All RNLs are defined in the RNL descriptor file (ESCLRNLs.cfg) . At the start up of the Global Lock Manager (GLM) region, RNLs are verified and loaded in the GLM and pushed to all cluster participants during the initial cluster handshake. Once these initial definitions are installed, the RNLs can be updated on the GLM only by using the ACTIVE page. The GLM will push the changes to all cluster participants.

See RNL Support for more information on RNLs.

Use this page to view the RNLs available in this Enterprise Server Cluster member.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • XAT
  • BUNDLE Entry (bundle_name)
  • PIPELINE Entry (pipeline_name)
  • WEBSERVICE Entry (webservice_name)
  • RNL (RNL_sequence_number)
Parent topic: Active


XAT

Use this page to view the XATs (XA-compliant database tables) defined for the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Switch Module

The location of the executable file (.dll on Windows, 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)


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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page.

PIPELINE

Shows the name of this PIPELINE definition.

Status
  • Enabled - the PIPELINE Entry is enabled.
  • Disabled - the PIPELINE Entry is disabled.
Resp Wait

Shows the number of seconds that an application should wait for a response message from the service. DEFT indicates the default value of the transport protocol. HTTP is 10 seconds. MQ is 60 seconds.

Shelf
Must reference a valid directory, but currently unused.
Cfg File
Shows a fully qualified pipeline configuration file.
WebSvc Dir
Shows a fully qualified name of the web service binding directory. When the PIPELINE is installed, this directory is scanned for .wsbind files and a WEBSERVICE resource is created and installed for each file found.
Parent topic: Details of an Active Resource


WEBSERVICE Entry (webservice_name)

Use this page to view information and set values for the WEBSERVICE named webservice_name, selected from the WEBSERVICE (Active) page.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page.

WEBSERVICE

Shows the name of this WEBSERVICE definition.

Status
ENABLED|UNUSABLE - if the WEBSERVICE is enabled, then the Discarded option can be checked to remove it.
Pipeline

Shows the name of the PIPELINE associated with this WEBSERVICE.

Urimap
Shows the URIMap associated with this WEBSERVICE (provider).
Program
Shows the resource name of the application program being exposed as a web service (provider only).
PGMInterface
Channel|Commarea (NOTAPPLIC for requester).
WSDL File
Shows the fully qualified location of the WSDL file (currently unused).
Archive File
Unused.
WSBIND
Shows the fully qualified location of the web service binding file.
Endpoint
Shows the endpoint in the wsdl.
Binding
Shows the value of the binding parameter in the .wsbind file.
Dynamically Installed
Yes|No - indicates whether this resource was dynamically installed via a scan of the WebSvc directory of the associated PIPELINE.
Trace SOAP application handler
Checking this option switches on tracing of each request/response in the application handler for this WEBSERVICE.
Parent topic: Details of an Active Resource


RNL (RNL_sequence_number)

Restriction: This page is only available on the GLM region.

Use this page to view information on the RNL RNL_sequence_number item selected from the RNL (Active) page.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page.

Sequence

Shows the position of this RNL in the global RNLs list, this is a read-only field.

RNL
Can be set to Include or Exclude.
Type

Can be set to Specific, Generic or Pattern.

QNAME
Set to SYSDSN and is a read-only field.
RName
Shows the resource name target of the include or exclude lock.

On Apply the updates will be pushed to the Enterprise Server Cluster participants.

Parent topic: Details of an Active Resource


ESMAC

  • MQ Listeners
  • MQ Writers
  • MQ Listener (listener-name)
  • MQ Writers (writer-name)
Parent topic: Resources


MQ Listeners

Use this page to view information about the MQ listeners available on the current server.

Details
Click this to display detailed information for the listener. Each detail row shows the following:
  • Name of the listener
  • Status of the listener
  • Type of listener
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue that is being listened to
Parent topic: ESMAC


MQ Writers

Use this page to view information about the dynamically created MQ writers available on the current server.

Details
Click this to display detailed information for the writer. Each detail row shows the following:
  • Name of the writer
  • Status of the writer
  • Type of writer
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue being written to
Parent topic: ESMAC


MQ Listener (listener-name)

Use this page to view information about a particular MQ listener selected from the MQ Listeners page.

Start / Stop

Starts or stops the MQ listener. Toggle.

Name
The name of the MQ listener.
Queue
The name of the MQ queue being listened to.
Queue Manager
The name of the Websphere MQ queue manager that defines the queue being listened to.
Type
The type of MQ listener.
Message Count
The number of messages processed.
Error Count
Number of messages that produced errors.
Dump
Click this to write dump information for this for this MQ listener to the casdump.rec file.
Parent topic: ESMAC


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


Users

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Users List
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Users List

Use this page to view the users defined for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
New

Click this to create a new user.

Details

Click this to display information about a user.

The information in the rest of the row shows you the name of the user, the operator ID, and a short description of the user.

Parent topic: Users


Env.Vars.

Use this page to view information about the environment variables used by this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Lists all of the environment variables currently in use by the server.

Value

Lists the values for all of the environment variables listed in the Name column.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Dyn.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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Type

The type of application or service being debugged.

Criteria

The criteria used to identify the application or service instance to debug.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Log Off

Use this page to sign on to the system. You can also use this page to change your password.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Sign On

Click this to sign on. You must first enter your user ID and password.

ID

Enter your user ID.

Password/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)


Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the communications processes and service listeners registered for the currently selected server. From this page you can also:

  • Make some specific edits to a communications process
  • Create a communications process by copying an existing one
  • Delete a communications process
  • Edit the configurable settings of a listener
  • Add a new listener

To access this page:

  1. On the server instance screen, select the Listeners tab.
Listener Display Filters

Use this group of fields to apply filters to the list of listeners so that you can just view a subset.

Note:

It is possible to specify filters such that no information is displayed.

Process

Choose an option for filtering by communications process:

All | To list all service listeners regardless of communications process
None | To list no service listeners
n | To list just the service listeners that belong to communications process n
Conversation Type (filter)

Choose an option for filtering by conversation type:

All | To list all service listeners regardless of conversation type
Custom | To list service listeners with a custom conversation type
Web Services and J2EE | To list Web Services and J2EE service listeners
Web | To list Web service listeners
Fileshare | To list Fileshare service listeners
Status

Choose an option for filtering by status:

All To list all service listeners regardless of status
status-type To list service listeners with the status status-type, where status-type can be one of:
  • Started
  • Stopped
  • Disabled
  • Blocked
  • Not Responding; this means any listener whose status is unknown because the server it is registered with is not responding to the server monitor
  • Not Started; this means any listener with a status other than Started
  • Not Stopped; this means any listener with a status other than Stopped
Auto-start

Check this to indicate that this communications process is started automatically when the enterprise server starts.

Statistics

Click this to see detailed information about the listener activity on this enterprise server. The information is shown in a new window. You can click this only if the enterprise server is started.

Change

Changes into Stop or Start when the enterprise server is started.

Stop

Click this to stop the communications process and all its listeners. You can click this only if the enterprise server is started, the communications process is started, and this communications process is not Communications Process 1.

Start

Click this to start the communications process and all its listeners. You can click this only if the enterprise server is started, the communications process is not started, and this communications process is not Communications Process 1.

Copy

Click this to create a new communications process by copying this one.

Delete

Click this to delete this communications process. If a server only has one communications process you cannot delete it.

Edit (communications process)

Click this to edit configurable settings for this communications process.

Listeners

Shows the number of listeners owned by this communications process.

Add

Click this to add a new listener.

Process ID

Shows the process ID of this communications process.

Control Channel Address

Shows the internal address used by the communications process for communicating with other components of the enterprise server. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

Under the network address is the DNS-resolved TCP/IP hostname.

Status (communications process)

Shows the current status of the communications process. The possible statuses are:

Not responding | The communications process status is unknown because the server it is registered with is not responding to the server monitor.
Started | The communications process is running.
Stopped | The communications process is stopped.
Last Status Change (communications process)

Shows the time that the communications process's current status was last updated; this time is local to the machine where the Directory Server is running.

Status Log (communications process)

Shows information about the most recent event that occurred on this communications process.

Version

Shows the version string of the communications process. This consists of three elements in decreasing order of significance: major version, minor version, build version. This can be used to distinguish between communications processes of the same name.

Edit (listener)

Click this to edit configurable settings for this listener.

Name

Shows the name of the service listener.

Address

Shows the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

Under the network address is the DNS-resolved TCP/IP hostname.

Status (listener)

Shows the current status of the service listener. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests.
Disabled | The listener is stopped and is therefore not available to any client
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Not responding | The listener status is unknown because the server it is registered with is not responding to the server monitor
Started | The server listener is running.
Stopped | The listener is stopped.
Start Pending | The SSL-enabled communications process is waiting for you to enter a password to give access to its private key. Less commonly, a password may also be required to give access to its certificate. To do this, click Authorize. On the page that appears in a second browser, enter the password (leave the certificate password blank unless it's required) and click Set Passphrases. Then close that browser.
Last Status Change (listener)

Shows the time that the listener's current status was last updated; this time is local to the machine where the Directory Server is running.

Status Log (listener)

Shows information about the most recent event that occurred on this listener.

Conversation Type

Shows the conversation type of the listener.

Custom Configuration Data

Shows optional textual configuration information that determines the start-up and run-time behavior of the listener. For details of the entries, see the section Configuration Information in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide.

Description

Shows an optional text description of the listener, for example, its purpose and owner.

  • Add Listener
  • Edit Listener
  • Delete Listener
  • Copy Communications Process
  • Edit Communications Process
  • Delete Communications Process
Parent topic: Enterprise Server Administration Console Help Pages


Add Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new service listener to the selected communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Name

Specify the unique name of the new service listener, up to 255 characters in length. You cannot include angle brackets (<>) or ampersands (&) in the name.

Endpoint Protocol

Specify the communications protocol used by the listener to accept incoming client requests. TCP is the only option.

Endpoint Address

Specify the network address used by the listener to accept incoming client requests. The format is:

ip-address:port

where:

  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is the IP address of the current machine.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

If this network address is not unique in the repository, this may cause listener startup problems.

Secure Sockets Layer
Check this to enable the Secure Sockets Layer (SSL) which provides encrypted communication between server and client applications and authentication of online entities.
Certificate
Specify the filename of your server certificate - for example, srvcert.pem.

The server certificate proves your identity to people you communicate with online and enables them to send you data in encrypted form. If the server certificate file is not in the default directory (which is the certs directory in the location defined by the SSLDIR environment variable), you must also specify the full path to the file.

Keyfile
Specify the filename of your private key file - for example, srvkey.pem. The private key is used to decrypt encrypted data you receive.

If this file is not in the default directory (which is the keys directory in the location defined by the SSLDIR environment variable), you must also specify the full path to the file.

Legacy Micro Focus Application Format

Check this if you want the listener to handle non-standard TCP/IP flows, for example, for Fileshare clients.

Initial Status

Choose a status from the list. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests. One use for this status is where you want to allow requests from only one client, perhaps for debugging purposes. You could amend the client code to ignore a status of "Blocked"and allow requests through.
Disabled | The listener is not started when the server starts and is therefore not available to any client
Stopped | The listener is available but stopped. This is the default. To start a listener use the Edit Listener page. When you add a stopped listener to a server that has a status of "Started", the server will attempt to start the listener immediately. If you add a stopped listener to a server that has a status of "Stopped", when the server is started it will attempt to start the listener.
Supported Conversation Type

if you chose TCP in Endpoint Protocol, click one button to choose a conversation type:

  • Web Services / J2EE for client requests that use a conversation protocol supported by the request handlers provided by Micro Focus, MFRHBINP and MFRHSOAP.
  • Web for World Wide Web (HTTP) client requests. Enterprise Server uses a Web listener for service deployment.
  • Fileshare for Fileshare client requests.
  • Custom for other kinds of client requests. Specify the name of the connector module in the entry field next to Custom.
Configuration Information

Specify textual configuration information that determines the startup and run-time behavior of the listener. Optional. For details of the valid entries, see the section Configuration Information in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide.

Description

Specify an optional text description of the listener, for example, its purpose and owner. Optional.

Add

Click this to add the listener to the current server.

Parent topic: Listeners


Edit Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a listener.

To access this page:

  1. On the Listeners screen, next to the listener to edit, click Edit.
Servers

Click this to return to the list of all the servers on this Directory Server, on the Home page.

Listeners

Click this to view a list of all the service listeners registered with the current server.

Services

Click this to view a list of all the services registered with the current server.

Handlers

Click this to view a list of all the request handlers registered with the current server.

Packages

Click this to view a list of all the packages registered with the current server.

Name

Specify the unique name of the listener, up to 255 characters in length. You cannot include angle brackets (<>) or ampersands (&) in the name.

Connection Endpoint

Specify the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

If this network address is not unique in the repository, this may cause listener start-up problems.

Secure Sockets Layer

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected listener.

To access this page:

  1. On the Listeners screen, next to the listener to edit, click Delete.
CAUTION:

Deleting a registered listener may cause application connection errors and loss of data

Name

Shows the name of the listener.

Connection Endpoint

Shows the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.
Current Status

Shows the current status of the service listener. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests.
Disabled | The listener is stopped and is therefore not available to any client
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Not responding | The listener status is unknown because the server it is registered with is not responding to the server monitor
Started | The server listener is running.
Stopped | The listener is stopped.
Description

Shows a text description of the listener.

Parent topic: Listeners


Copy Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to create a new communications process by copying the details of an existing communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Control Channel Address

Specify the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is the IP address of the current machine.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

If this network address is not unique in the repository, this may cause communications process startup problems.

Secure Sockets Layer

Not currently used.

Auto-start

Check this to indicate that the new communications process is started automatically when the enterprise server is started. If you copy a communications process while the enterprise server is running, and you check this, the new communications process is started immediately.

Parent topic: Listeners


Edit Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Control Channel Address

Specify the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

If this network address is not unique in the repository, this may cause communications process startup problems.

Secure Sockets Layer

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected communications process.

CAUTION:

Deleting a communications process may cause application connection errors and loss of data.

Name

Shows the name of the communications process.

Address

Shows the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.
Listeners

Shows the number of listeners owned by the communications process.

Parent topic: Listeners


Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the services registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of a service
  • Add a new service
Service Display Filters

Use this group of fields to apply filters to the list of services so that you can just view a subset.

Note:

It is possible to specify filters such that no information is displayed.

Service

Specify a service namespace to see just the details for that service namespace.

Class

Choose an option for filtering by service class:

All | To list all service namespaces regardless of service class
Some | To list those service namespaces that have a value in Service Class
None | To list those service namespaces that have no value in Service Class
Handler

Choose an option for filtering by request handler:

All | To list all service namespaces regardless of which request handler is associated with the service
Some | To list those service namespaces that have a value in Request Handler
None | To list those service namespaces that have no value in Request Handler
Package

Choose an option for filtering by implementation package:

All | To list all service namespaces regardless of which implementation package is associated with the service
Some | To list those service namespaces that have a value in Implementation Package
None | To list those service namespaces that have no value in Implementation Package
Show

Specify the number of service namespaces to show at a time. If you change this, you have to click Refresh to see the effect.

Previous

Click this to view the previous page of service namespaces. You can click this only if the number of service namespaces is greater than can be shown on one page.

Next

Click this to view the next page of service namespaces. You can click this only if the number of service namespaces is greater than can be shown on one page.

Edit

Click this to edit configurable settings for the service.

Service Namespace

Shows the service namespace. For more information about service namespace and service operation see your Configuration and Administration book.

Operation

Shows the name of the operations in the service namespace.

Service Class

Shows the class of the service. This field provides a means of grouping services, so that a client program can ask for a class of service rather than a specific named service. Service classes beginning with MF are reserved for Micro Focus use.

Search Order

Shows the search order of the service. The lower the search order, the higher the search priority where there is more than one service object of the same name in the repository.

Listeners

Lists the listeners allocated to this service. For each listener the fofllowing information is shown:

  • The communications process that it belongs to, for example CP1 (communications process 1)
  • Its name
  • Its address in both IP address and hostname formats
Request Handler

Shows the name and path of the request handler for this service.

Implementation Package

Shows the name of the implementation package for this service.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The service is disabled.
Status Log

Shows information about the most recent event that occurred on this service.

Custom Configuration

Shows optional textual configuration information that determines the start-up and run-time behavior of the service. For details of the entries, see the section Configuration Information in the chapter Services, Packages and Request Handlers in your Configuration and Administration Guide.

Description

Shows an optional text description of the service.

Add

Click this to add a new service.

  • Edit Service
  • Delete Service
  • Delete Service Operation
Parent topic: Enterprise Server Administration Console Help Pages


Edit Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a service.

CAUTION:
Changing the properties of a registered service may cause application connection errors and loss of data
Name

Specify the name of the service, up to 255 characters. You cannot include angle brackets (<>) or ampersands (&) in the name.

A service name can consist of a service namespace and an operation name, separated by a special character. The character depends on which request handler is being used, MFRHSOAP or MFRHBINP.

If there is no separating character, the name of the operation is considered to be the same as the service namespace.

If the service will be using the MFRHSOAP request handler, the text before the first pound character (#) in the name is considered to be the service namespace and the text after is considered to be the name of the operation.

If the service will be using the MFRHBINP request handler, the text before the last period character (.) in the name is considered to be the service namespace and the text after is considered to be the name of the operation.

Note: You can change the name of a service only when the server has a status of "Stopped".
Search Order

Specify the search order of the service. If more than one service object has the same name, then a program client can use Search Order to decide which service to use. The lower the search order is, the higher the search priority.

Service Class

Specify the service class of the service (optional). This field provides a means of grouping services, so that a client program can ask for a class of service rather than a specific named service. Service classes beginning with MF are reserved for Micro Focus use. Service Class can be up to 32 characters in length.

Version

Specify the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version. This can be used to distinguish between services of the same name or class.

Logging
Check this to request that for each request for this service the request and response blocks are written to the enterprise server dump data set. Only use this option if you need diagnostics as it degrades performance.
Restriction: This option only applies to services that represent COBOL applications that are executed by a request handler. It has no effect for services that are used only for directory lookup purposes, such as the MF JES service.
Transaction Management

Click one button to choose the type of transaction management that this service uses:

  • Application for a service in which the COBOL application manages their own transactions.
  • Container for a service in which the COBOL application leaves transaction management to the application container.

If the client is transactional, such as a J2EE transactional request, this setting is ignored and the service is forced to be container-managed. Container-managed services should not make any explicit transactional requests, for example, EXEC SQL COMMIT WORK statements.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The service is disabled.
New Status

Choose a status from the list. The possible statuses are:

Available | The service is available.
Disabled | The service is disabled.
Accepting Listeners

Shows the listeners that will accept incoming client requests.

Available Listeners

Lists the listeners that are available to be allocated to this service. Click a listener to select it for adding to Accepting Listeners. A service can have more than one listener.

Remove

Click this to remove the selected listener from Accepting Listeners. There must be more than one listener in Accepting Listeners before you can click this.

Add

Click this to add the selected listener to Accepting Listeners.

Available Handlers

Lists the available request handlers. Click a request handler to select it to become the Associated Handler. You must add a listener before you can see Available Handlers and associate a handler with the service.

Select Handler

Click this to make the selected request handler the Associated Handler.

Associated Handler

Shows the request handler that is associated with this service, if any.

Available Packages

Lists the available implementation packages. Click a package to select it to become the Associated Package. You must add a listener before you can see Available Packages and associate a package with the service.

Select Package

Click this to make the selected package the Associated Package.

Associated Package

Shows the implementation package that is associated with this service, if any.

Configuration Information

Specify textual configuration information that determines the startup and run-time behavior of the service. Optional. For details of the valid entries, see the section Configuration Information in the chapter Services, Packages and Request Handlers in your Configuration and Administration Guide.

Description

Specify a text description of the service, for example, its purpose and owner. Optional.

Parent topic: Services


Delete Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete a service and all of its operations. You can also optionally delete the packages associated with the operations.

CAUTION:

Deleting registered services and packages may cause application connection errors and loss of data.

Full Name

Shows the full name of the service, consisting of service namespace, separator and operation name

Service Class

Shows the service class of the service.

Version

Shows the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version.

Listener

Shows the listener associated with the service operation.

Request Handler

Shows the request handler associated with the service operation.

Implementation Package

Shows the implementation package associated with the service operation.

Description (service)

Shows a text description of the service operation.

Name

Shows the name of the package associated with the service operation.

IDT

Shows the pathname of the interface definition table (IDT) associated with the service operation.

Description (package)

Shows a text description of the package.

Delete associated packages

Check this to delete the packages associated with the service.

Delete

Click this to delete this service, its operations and optionally the associated packages.

Parent topic: Services


Delete Service Operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete an individual service operation, or a service that contains no operations.

CAUTION:

Deleting a registered service may cause application connection errors and loss of data.

Name

Shows the name of the service.

Service Class

Shows the service class of the service.

Version

Shows the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version.

Listener

Shows the listener associated with the service.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The service is disabled.
Status Log

Shows information about the most recent event that occurred on this service.

Description

Shows a text description of the service.

Delete

Click this to delete this service.

Parent topic: Services


Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the request handlers registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of a request handler
  • Add a new request handler
Edit

Click this to edit configurable settings for the server or one of the request handlers.

Module Name

Shows the filename of the request handler.

Module Path

Shows the path where the request handler file is located.

Current Status

Shows the current status of the request handler. The possible statuses are:

Enabled | The handler is enabled
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The handler is disabled
Status Log

Shows information about the most recent event that occurred on this handler.

Custom Configuration

This field is not used.

Description

Shows an optional text description of the handler.

Add

Click this to add a new request handler.

  • Edit Handler
  • Add Handler
Parent topic: Enterprise Server Administration Console Help Pages


Edit Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a request handler

Module Name

Specify the name of the request handler, up to 255 characters.

Note: Note:

You can change the name of a handler only when the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

Current Status

Shows the current status of the request handler. The possible statuses are:

Enabled | The handler is enabled
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The handler is disabled
New Status

Choose a status from the list. The possible statuses are:

Enabled | The handler is enabled. This is the default
Disabled | The handler is disabled
Note:

You can change the status of a handler only when the server has the status "Stopped".

Module Path

Specify the path where the request handler file is located.

Configuration Information

This field is not used.

Description

Specify a text description of the request handler, for example, its purpose and owner. Optional.

Delete

Click this to delete the handler.

Note:

You cannot delete the MFRHBINP request handler.

Parent topic: Handlers


Add Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new request handler to a server.

Module Path

Specify the path where the request handler file is located.

Status

Choose a status from the list. The possible statuses are:

Enabled | The handler is enabled. This is the default.
Disabled | The handler is disabled.
Configuration Information

This field is not used.

Description

Specify a text description of the request handler, for example, its purpose and owner. Optional.

Add

Click this to add the handler to the selected server.

Parent topic: Handlers


Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the implementation packages registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of an implementation package
  • Add a new implementation package
Show

Specify the number of packages to show at a time. If you change this, you have to click Refresh to see the effect.

Previous

Click this to view the previous page of packages. You can click this only if the number of packages is greater than can be shown on one page.

Next

Click this to view the next page of packages. You can click this only if the number of packages is greater than can be shown on one page.

Edit

Click this to edit configurable settings for the implementation package.

Name

Shows the name of the package.

Current Status

Shows the current status of the package. The possible statuses are:

Available | The package is available. This is the default.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The package is disabled.
Status Log

Shows information about the most recent event that occurred on this package.

Package Module

Shows the name of the library that contains the package, if any.

IDT

Shows the path of the IDT (interface definition table) for the package.

Package Path

Shows the path where the package file is located.

Custom Configuration

This field is not used.

Description

Shows an optional text description of the package.

Add

Click this to add an implementation package.

  • Add Package
  • Edit Package
  • Delete Package
Parent topic: Enterprise Server Administration Console Help Pages


Add Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add an implementation package to the server.

Name

Specify the name of the new package, up to 255 characters. You cannot include angle brackets (<>) or ampersands (&) in the name.

Status

Choose a status from the list. The possible statuses are:

Available | The package is available. This is the default.
Disabled | The package is disabled.
Package Module

Specify the name of the library that contains the new package. You need to specify this only if the program is in a library that has a different name than the package name. Include the extension; library files have the extension .lbr or .dll on Windows, .lbr or .so on UNIX.

IDT

Specify the pathname of the IDT (interface definition table) for the package.

IDT Remains Resident

Check this if you want the IDT to be loaded into the shared memory area while the service is running. This can help performance if the service is frequently used and there are no constraints on shared memory.

Package Path

Specify the path or paths where the executable program or programs are located. Separate paths with semicolons on Windows, and with colons on UNIX. If you do not specify this, the Directory Server looks for the file first in the path included in the interface definition table, and then in the paths specified by the COBDIR environment variable.

Configuration Information

This field is not used.

Description

Text description of the package. Optional.

Add

Click this to add the new package to the server. You must add a listener before you can click Add.

Parent topic: Packages


Edit Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of an implementation package.

Name

Specify the name of the package, up to 255 characters. You can change the name only if the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

Current Status

Shows the current status of the package.

New Status

Choose a status from the list. The possible statuses are:

Available | The package is available.
Disabled | The package is disabled.
Package Module

Specify the name of the library that contains the new package. You need to specify this only if the program is in a library that has a different name than the package name. Include the extension; library files have the extension .lbr or .dll on Windows, .lbr or .so on UNIX.

IDT

Specify the pathname of the IDT (interface definition table) for the package.

IDT Remains Resident

Check this if you want the IDT to be loaded into the repository while the service is running. This can help performance if the service is frequently used and there are no constraints on shared memory.

Package Path

Specify the path where the package file is located. If you do not specify this, the Directory Server looks for the file first in the path included in the interface definition table, and then in the paths specified by the COBDIR environment variable.

Configuration Information

This field is not used.

Description

Specify a text description of the package. Optional.

Delete

Click this to delete the package. You cannot delete a package if it is associated with a service.

Parent topic: Packages


Delete Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected package.

CAUTION:

Deleting a registered package may cause application connection errors and loss of data

Name

Shows the name of the package.

Package Module

Shows the name of the library that contains the package.

IDT

Shows the path of the IDT (interface definition table) for the package.

Description

Shows a text description of the package.

Parent topic: Packages


Security Configuration Screen Help

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains the context sensitive help available when configuring Enterprise Server security. This help is also available from the user interface. To access the help, select Help > This Page from the left pane.

Note: The context help in this section is the most up-to-date version.
  • MF Directory Server Users, Add or Edit
  • Add Resource Class
  • Add Resource Entity
  • Add Security Manager
  • Add to Default ES Security Manager List
  • Add to ES Security Manager List
  • Add to MF Directory Server Security Manager List
  • Configure General Options
  • Confirm Password
  • Configure Journal Options
  • Configure Monitor Options
  • Configure Repository Options
  • Default ES Security Configuration
  • Directory Server Users
  • Edit Resource Class
  • Edit resource entity
  • Edit Security Manager
  • Left Pane Menu Items
  • MF Directory Server Security
  • Remove Security Manager Reference Confirmation
  • Security Managers Pool
  • SSL Options
  • Shut Down the MF Directory Server
  • Update User
  • User Group Members
  • User Groups
  • User Import: another user registry
  • User Import: previous version
Parent topic: Enterprise Server Administration Console Help Pages
Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


MF Directory Server Users, Add or Edit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add new users, select a user for updating or deleting, and to import user accounts. This screen is divided into tabs. The label of the tab indicates the start character(s) of the account IDs that are listed on the tab.

Account ID
The ID for the user account.
Add
Click this to add a new user.
Advanced Configuration (read only)
Displays user information retrieved from the LDAP.
Allow Logon
Indicates whether this user can logon.
Custom Configuration
An area where you can add custom user configurations, if your LDAP allows it.
Description
A description of the user account.
Edit
Click this to select the highlighted user ID for updating or deleting
Import
Click this to import user data from an installation of a previous version of Micro Focus Directory Server.
Journal
Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.
Logon
Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".
Member of
A comma separated list of the user groups of which the user is a member.
Name
The full name of the person assigned to this account.
Sessions
Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.
Shut Down
Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.
Parent topic: Security Configuration Screen Help


Add Resource Class

Use this page to add the details of a new resource class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Add

Click here to add the new definition.

Class name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

Parent topic: Security Configuration Screen Help


Add Resource Entity

Use this page to add the details of a new resource entity to the current resource class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Entity name

Specify the name of the resource entity. This must be unique within the resource class.

Description

Specify a description of the resource entity.

Add

Click here to add the new definition.

Parent topic: Security Configuration Screen Help


Add Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new security manager.

Authorized ID and Password

If the module requires credentials to connect to the external security manager, specify them here.

As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

Cache limit:

If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

This parameter is currently ignored by the ESM Module.

Cache TTL:

If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

This parameter is currently ignored by the ESM Module.

Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
Configuration information

Specify any additional configuration settings that the module requires.

Connection Path:

If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

Description

Specify a description of the security manager.

Enabled

Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc .

Name

Specify the name used to identify the security manager.

Parent topic: Security Configuration Screen Help


Add to Default ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Managers to the Default ES Security Manager List. This is the list of security managers (taken from the available pool) that enterprise servers can use to perform security queries.

The screen shows a table that contains the available pool of Security Managers.

Select

Use this to select a security manager for addition to the Default ES Security Manager List.

Name

This column indicates the name that used to identify a security manager.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Used by

This column shows the security manager lists that include this security manager.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Add

Click this to add the currently selected security manager to the Default ES Security Manager List.

Parent topic: Security Configuration Screen Help


Add to ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Manager to a particular enterprise server's Security Manager List. This is the list of security manager (taken from the available pool) that the enterprise server can use to perform security queries.

The screen shows a table that contains the available pool of Security Managers.

Select

Use this to select a security manager for addition to the Security Manager List.

Name

This column indicates the name that used to identify a security manager.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Add

Click this to add the currently selected security manager to the Security Manager List.

Parent topic: Security Configuration Screen Help


Add to MF Directory Server Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Managers to the MFDS Security Manager List. This is the list of security manager (taken from the available pool) that Directory Server can use to perform security queries.

The screen shows a table that contains the available pool of Security Manager.

Add

Click this to add the currently selected security manager to the MF Directory Server Security Manager List.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column indicates the name that used to identify a security manager.

Select

Use this to select a security manager for addition to the MFDS Security Manager List.

Used by

This column shows the security manager lists that include this security manager.

Parent topic: Security Configuration Screen Help


Configure General Options

Use this page to change configuration settings for the Directory Server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Maximum Directory Server object count

Specify the maximum number of objects that the repository can hold.

The minimum is 64 objects. The maximum is 9999 objects. The default value is 128 objects.

Generate UDP search requests

When a CCI client request cannot be satisfied by this Directory Server it can forward the request to any other compatible naming services on the local network by issuing the request using a UDP broadcast. You might want to minimize broadcast traffic or force clients to search for locally registered servers by disabling this feature.

The default is enabled.

Restore server states when Directory Server starts up

Check this if you want servers that were previously started when the Directory Server closed down to be restarted when the Directory Server is started. For example, if your system is configured to run Directory Server automatically at system startup, and this flag is checked, then whenever you reboot your machine, Directory Server will attempt to restart any servers that were running when it closed down.

The default is "Disabled".

Save Legacy Micro Focus Servers

Check this if you want legacy Micro Focus servers to be included when you save the Directory Server repository. Legacy Micro Focus servers are CCI servers.

The default is "Disabled".

Servers marked "Started" only when all listeners started

Check this if you want the server status to remain "Stopped" until all of the auto-start and startable listeners (those not marked as Disabled) have been set to "Started" status.

If this is unchecked, the server status is set to "Started" when the first MFCS instance that starts up modifies the server status. This will be shortly after the Communications Process Control Channel listener becomes active. At this point, any remaining listeners for that Communications Process, and any other Communications Processes for that server, will probably still be starting up.

By default this is unchecked.

Clear dynamically assigned address values when servers stop

Check this box to override the option on the individual stop server confirmation page so that the dynamic address values for the server are cleared when it stops. This will happen regardless of whether it is started remotely, from the command line, or from the Enterprise Server Administration GUI.

By default this is unchecked.

Default Process User ID

UNIX only. Specify a default user ID to be attached to all processes started from the Directory Server, for example, service execution processes. You can override this default process user ID for an individual enterprise server by specifying a value for Process User ID on the Edit Server Advanced page. If you do not specify a user ID in either place, all processes run as user root, which can create problems with security and access to files. You can specify either a numeric user ID or a username.

Defaults

Click this to restore the default settings.

Note:
  • If the current number of objects exceeds the default object count, the default is not restored.
Parent topic: Security Configuration Screen Help


Confirm Password

Use this page to confirm your user ID and password after you have changed the mode of Directory Server from Unrestricted to Restricted.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
User ID

Specify your user ID. User IDs are case sensitive.

Password

Specify your password. Passwords are case sensitive.

Parent topic: Security Configuration Screen Help


Configure Journal Options

Use this page to change configuration settings for the Directory Server journal.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Journal

The journal is a file that records some of the Web browser client and program client activity occurring on the Directory Server. It can track usage and help with support issues.

The level of journaling in force affects performance; the more entries written, the more performance is degraded. The scale of the degradation depends on many factors such as file system performance and client traffic; a system with a large number of highly active program clients suffers the most.

Maximum file size

Specify the maximum file size in kilobytes (KB) of the journal file. Once the journal file grows to this size, the most recent journal entries overwrite the oldest journal entries.

The minimum is 32 KB. The default value is 256 KB.

CAUTION:

Changing the size of the journal erases any previous journal entries.

Entries displayed

Specify the number of journal entries that will be displayed on the page at a single time.

The minimum is 5 entries. The default value is 23 entries.

Journal level - Errors only

Check this if you want journal entries to be written for errors only.

Journal level - Errors and warnings

Check this if you want journal entries to be written for errors and warnings only.

Journal level - All 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 Micro Focus SupportLine.

CTF trace

Check this if you want journal entries to be written through the Consolidated Trace Facility.

Defaults

Click this to restore the default settings.

Note:
  • Restoring the default maximum file size of the journal has the effect of erasing the journal, unless the maximum size is already set to the default.
Parent topic: Security Configuration Screen Help


Configure Monitor Options

Use this page to change configuration settings for the Server Monitor.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Acceptable response time

Specify the interval (in seconds) that the server monitor is to wait for a response after sending a keep-alive request to a server before assuming it is not responding. If you know that the network is normally quiet or busy, you can adjust this time accordingly.

The default value is 5 seconds.

Defaults

Click this to restore the default settings.

Enabled

Check Enabled to start the server monitor. Uncheck it to stop the server monitor at the next keep-alive interval timeout.

The default is Enabled.

Keep-alive interval

Specify the interval (in seconds) that the server monitor is to wait between each cycle of server interrogations. Since each cycle of interrogations takes a finite amount of time, depending on how many servers are registered and how responsive they and the network are, the actual time taken between checks is longer than this interval.

The default value is 60 seconds.

Server Monitor

The server monitor checks whether all enterprise servers registered with the Directory Server and not marked "Stopped" or "Disabled" are responding to potential client requests. If they are, their status is marked as "Started", otherwise, if they are currently marked as "Started" and they are not responding, they are marked as "Not Responding".

Having the server monitor on ensures that Current Status for a server is up to date, even if the server itself cannot contact the Directory Server for some reason, for example, a network connection or machine failure.

Parent topic: Security Configuration Screen Help


Configure Repository Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configuration settings for the Directory

Repository Location

Specify the type of storage and the location containing the repository. You can store the repository in the file system or in an LDAP repository.

For file system storage, the location is the directory in which the repository data will be stored.

For LDAP storage, the location is the address of the LDAP server that will be used.

In order to store the repository in an LDAP server, the server must be updated to support the Micro Focus configuration objects.

Warning: If you change the location and the destination already contains a repository, you will be warned and given the opportunity to overwrite it or to cancel the operation.
Note: When you specify ldap:// as the storage mechanism, additional fields are displayed for specifying the container in which the data will be stored, and the LDAP user credentials required to write to the container.
Repository Container Distinguished Name

The distinguished name of the LDAP container in which the repository is to be stored.

User DN
The distinguished name of the LDAP user with which to access the repository. This user must have permission to read and write to the container.
User Password
The password of the user with which to access the repository.
Parent topic: Security Configuration Screen Help


Default ES Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define default security settings that can be used with Directory Server and enterprise servers. You can override these defaults for individual servers

Add

Click this to add a security manager from the pool of available definitions.

Allow unknown resources

Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

You might use this in circumstances where you only want to restrict access to some resources.

Allow unknown users

Check this if you want to allow unknown users to log in.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Cache limit:

Enter the maximum size in kilobytes that the Directory Server or enterprise server's security facility can use for caching the results of security queries.

Cache TTL:

Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Create audit events

Check this to enable the enterprise server or Directory Server to generate security audit events. These events can be captured and logged by the Audit Facility.

Configuration information

Specify any additional configuration settings that the security facility requires.

Default ES Security Manager List

This is the list of security managers (taken from the available pool) that can be used to perform security queries.

Note: Security managers are queried in the order that they appear in the list. If the Verify against all Security Managers checkbox is not checked, the first manager in the list that responds with a definite answer will determine the result of a security query. See the text for Verify against all Security Managers for more details.

Use the up and down arrows to reposition the selected entry.

Module

This column shows the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column shows the name that used to identify a security manager.

Priority

Indicates the position of the security manager in the sequence in which the security managers are queried.

Select

Use this to select a security manager for removal or for moving to a different position in the list.

Description

The description column shows the description for a security manager.

Remove

Click this to remove the currently selected definition from this list.

Note: The definition is only removed from this list, not from the available pool of definitions.
Use all groups

Check this if a user requesting authorization is to have the permissions of every group to which he or she belongs.

Uncheck this if the user is to have only the permissions of the group specified in the initial security API call that requested verification (authentication) of the user's credentials. Where no group is specified in the verify call, a default group is used.

Verify against all Security Managers

Set this if you want each security query to be checked by all entries on the Security Manager Priority List.

If this is not set, the entries will be queried in the order that they appear on the Priority List until one gives a response of Allow, Deny, or Fail (equivalent to Deny). This response will then be used to decide what action should be taken.

If this field is set, all entries on the list will be queried, and if any returns a Deny or Fail, the access request will be denied. If there are no Deny or Fail responses and at least one of the entries on the list gives Allow as its response, the request will be allowed.

If a security manager does not have a rule for the resource or user specified in the request, it gives a response of Unknown. Whatever the setting of the Verify against all Security Managers field, if all of the entries on the priority list respond with Unknown, the request will be denied unless you have checked Allow unknown resources or Allow unknown users.

Parent topic: Security Configuration Screen Help


Directory Server Users

Use this page to add new users, select a user for updating or deleting, and to import user accounts. This screen is divided into tabs. The label of the tab indicates the start character(s) of the account IDs that are listed on the tab.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Account ID

The ID for the user account.

Name

The full name of the person assigned to this account.

Member of

A comma separated list of the user groups of which the user is a member.

Description

A description of the user account.

Allow Logon

Indicates whether this user can logon.

Edit

Click this to select the highlighted user ID for updating or deleting

Add

Click this to add a new user.

Import

Click this to import user data from an installation of a previous version of Micro Focus Directory Server.

Parent topic: Security Configuration Screen Help


Edit Resource Class

Use this page to edit the details of a resource class and to add resource entities to the class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Description

Specify a description of the resource class in this field.

Apply

Click this to apply any change that you have made to the description text.

Delete

Click this to delete this resource class. Note that you cannot delete a resource class that contains resource entities.

Entity

This column specifies the name of each resource entity that is included in this resource class.

Entity Description

This column specifies the description of each resource entity that is included in this resource class.

ACL String

This column specifies the Access Control List (ACL) string of each resource entity that is included in this resource class. The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

setting:actor:action-1,...,action-n

Where:

  • setting is allow or deny
  • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
  • action-1 through action-n are permission tokens:
    • none
    • execute
    • read
    • update
    • add
    • delete
    • control
    • alter
    • all
Edit

Click this to edit the resource entity in this row.

Add

Click this to add a new resource entity to this resource class.

Parent topic: Security Configuration Screen Help


Edit resource entity

Use this page to edit the details of a resource entity.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Description

Specify a description of the resource entity.

ACL String

Specify the Access Control List(ACL) string for the resource entity. The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

setting:actor:action-1,...,action-n

Where:

  • setting is allow or deny
  • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
  • action-1 through action-n are permission tokens:
    • none
    • execute
    • read
    • update
    • add
    • delete
    • control
    • alter
    • all

For example, the following ACL string:

allow:Test group:Execute,Read,Update,Add,Delete;allow:Operator group:Read

assigns the Test group execute, read, update, add and delete permissions for the resource, and assigns the Operator group read permission.

Parent topic: Security Configuration Screen Help


Edit Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to amend the details of a security manager.

Name

Specify the name used to identify the security manager.

Module

Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc .

Connection Path

If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

Authorized ID and Password

If the module requires credentials to connect to the external security manager, specify them here.

As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

Enabled

Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Cache limit

If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

This parameter is currently ignored by the ESM Module.
Cache TTL

If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

This parameter is currently ignored by the ESM Module.

Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
Description

Specify a description of the security manager.

Configuration information

Specify any additional configuration settings that the module requires.

Properties

Click this to access pages for the management of users, groups and resources controlled by this security manager.

Important: You will only be able to manage users, groups and resources where the security manager is on the priority list used by Directory Server. That is:
  • if Directory Server uses the Default ES Security configuration, the security manager must be on the Default ES Security manager list
  • if Directory Server uses its own configuration options, the security manager must be on the Directory Server's own security manager list

In addition, the ESM module and the external security manager to which it connects must also support user, group and resource administration via the Security Facility.

Parent topic: Security Configuration Screen Help


Left Pane Menu Items

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following items appear on the left pane menu:

Home menu option

Click this to return to the Home page.

Actions

The heading for menu options that provide administrative actions. The actual number of options displayed below this heading is variable, depending on the permission level of the user.

Logon

Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".

Logoff

Click this to log off from an administrative session that is currently logged on. There is no log off confirmation. This menu option is shown only if the session is currently logged on and the User Access setting on the Options page is "Restricted".

Renew

Click this to refresh the IP address information cached by your Directory Server. Use this option when the IP address of the machine running your Directory Server changes.

Directory Server uses the IP address to locate the servers that it manages. When the cached IP address is out of date, Directory Server may be unable to connect to its servers and may report inaccurate information to clients.

Export

Click this to show the Export page. This page enables you to save a copy of the whole repository to a location of your choice. This menu option is available only if you logged on with Administrator or Schema Administrator permission level.

Import

Click this to show the Import page. This page enables you to update the repository with additional objects from an import directory. Imported objects can include servers (along with all of their child objects), and Security Manager definitions. This menu option is available only if you logged on with Schema Administrator permission level.

Delete All

Click this to show the Delete confirmation page. This page enables you to confirm that you want the repository to be completely erased and all registered objects to be deleted. This menu item is available only if you logged on with Schema Administrator permission level.

Shut Down

Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.

Configure

The heading for the menu option that enables you to configure Directory Server. This menu heading and its associated menu option are available only if you logged on with Administrator permission level or higher.

Options

Click this to show the Directory Server Options page. This page enables you to configure the Directory Server.

Security

Click this to show the pages used for configuring security options.

Display

The heading for menu options that enable you to view information about the state of the Directory Server and about the events that have taken place on the server.

Directories

Click this to show the Directories page. This page lists all the instances of Directory Server that are running on the network and using the default Directory Server port (86).

Statistics

Click this to show the Statistics page. This page shows statistics and status information about Directory Server.

Sessions

Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.

Journal

Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.

Help

The heading for menu options that enable you to view documentation about the Directory Server and Enterprise Server Administration.

This page

Click this to view help for the page you are currently viewing and for all the controls on the page.

Contents

Click this to view the Contents of the Enterprise Server documentation.

Note: Note:

For this link to work, you must be using an enterprise server that has a Web listener with the following entry in the [virtual paths] section:

docs=<ES>/docs/html

This enterprise server must be started.

The default enterprise server, ESDEMO, has a web listener with this configuration information. When you create a new enterprise server, a Web listener with the required configuration information entry is automatically created.

Support

Click this to contact Micro Focus Technical Support via the Supportline website to report problems or ask any questions about using Micro Focus software.

Feedback

Click this to open your email client and send general feedback to Micro Focus.

Parent topic: Security Configuration Screen Help


MF Directory Server Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define the security settings to be used with Directory Server.

Add

Click this to add a security manager from the pool of available definitions.

Authenticated client sessions

There are two main methods that a remote user can use to connect to the Directory Server:

  • Using Enterprise Server Administration, which runs in a Web browser. This method is intended for the administrative functions. These clients are known as Web browser clients.
  • Using the underlying MLDAP API, usually via some higher level application interface or product, to carry out some short-lived operation such as to search for the address of a service or to modify the properties of an object. These clients are known as program clients.

If Directory Server is running in Restricted mode, Web browser clients have to authenticate themselves to the Directory Server, carry out any operations, and then log off. (Program clients always run in Restricted mode.) During the time period between the authentication and removal the client is entered into the authenticated client list maintained internally by the Directory Server process. To s the list from accidentally growing too large (not all users or applications log off correctly after they have been authenticated) and also to maintain security, the Directory Server removes both Web browser and program client sessions after a configurable timeout period.

Certificate
Custom server certificate path.
Certificate passphrase

Custom server certificate passphrase (optional).

Change

Click this to add a security manager from the pool of available definitions. This button is only present if you are using the MFDS Internal Security Manager. As MFDS Internal Security cannot be used alongside other security managers, when you add the new manager MFDS Internal Security will be removed.

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 user access

Check this to cause all administrative access to the Directory Server to be authenticated and authorized by the entries on the Security Manager Priority List.

Secure Port

Unless a specific secure port is specified, the SSL connection will use a dynamically assigned port each time the MF Directory Server process is restarted. A fixed known port may be useful if configuring firewall settings.

Security Manager List

This is the list of security managers (taken from the available pool) that MF Directory Server can use to perform security queries.

Note: Security managers are queried in the order that they appear in the list. If the Verify against all Security Managers checkbox is not checked, the first manager in the list that responds with a definite answer will determine the result of a security query. See the text for Verify against all Security Managers for more details.

Use the up and down arrows to reposition the selected entry.

Select

Use this to select a security manager for removal or for moving to a different position in the list.

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.

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 this is turned off, the default DemoCA root certificate, server certificate, keyfile and passphrase that are installed with the product will be used. For production purposes it is recommended that the default certificates are not used, and that the customers own certificates are specified. In addition, the MF_ROOT_CERT environment variable will need to be set so that the MF Directory Server process can pick up the value of the root certificate path.

Update when external Security Manager properties change
Check this to update the configuration to reflect changes made to any external Security Manager used.
Use default ES Security Manager List

Check this if you want to use your default ES security manager list for Directory Server, rather than the Security Manager List below. To define the default ES Security settings, click Security on the menu on the left hand side, and then click Security > Default ES Security.

Use encrypted connections

Select this if you want to start Enterprise Server Administration so that it requires authorized browser connections to use SSL. If the state is changed from the current active selection then the MF Directory Server process will need to be re-started to use the new setting. If encrypted connections are selected, administrative access must also be set to restricted.

Web browser timeout

Specify the maximum interval in seconds since the last activity of a Web browser client, for example, a browser refresh, before it is automatically logged off.

The minimum value is 60 seconds (1 minute). A value of -1 indicates an infinite timeout period. We recommend you use this value sparingly and always reset to a finite period as soon as possible. This is because if the Directory Server is running with an infinite Web client timeout, there is more likelihood that an unauthorised user might gain access to the system using an unattended machine; also the Directory Server will tend to become overloaded with clients who have not logged off.

The default value is 300 seconds (5 minutes).

Security Facility Configuration

The Security Facility Configuration parameters are available on this screen only when MFDS is configured to use an ESF (i.e. set up to use a Security Manager other than "MFDS Internal Security"). Otherwise no ESF security configuration options (including the caching options) will be seen on this MFDS Security tab screen:

Allow unknown resources

Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

You might use this in circumstances where you only want to restrict access to some resources.

Allow unknown users

Check this if you want to allow unknown users to log in.

Cache limit

Enter the maximum size in kilobytes that enterprise server's security facility can use for caching the results of security queries.

Cache TTL

Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be 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 in the product Help for more information.

For additional information on cipher suite configuration please refer to the OpenSSL documentation, click here.

Parent topic: Security Configuration Screen Help


Remove Security Manager Reference Confirmation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Administration displays this page in the following situations:

  • when you choose to remove a security manager from the MF Directory Server's security manager list and that security manager is the only one present in the list. When the security manager is removed, it is automatically replaced by the MFDS Internal security manager.
  • The MFDS Internal security manager cannot be used in a list that contains other security managers. Therefore, when you choose to add a different security manager to the MF Directory Server's security manager list, the MFDS Internal security manager, if present in the list, will be automatically removed.

This screen checks that you want to proceed with the removal.

Parent topic: Security Configuration Screen Help


Security Managers Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to manage the pool of security managers available for Directory Server and enterprise servers to use for resolving security queries.

You can have multiple definitions for any given external security manager. Each definition may be used by Directory Server and one or more enterprise servers.

Add

Click this to add a new security manager.

Description

The description column shows the description for a security manager.

Edit

Click this to edit details of the currently selected security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

This column shows the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column shows the name that used to identify a security manager.

Select

Use this to select a security manager for editing or removal.

Update All
Click this to update the security managers so that they display the correct current status.
Used by

This column shows the security manager lists that include this security manager.

Parent topic: Security Configuration Screen Help


SSL Options

Use this page to set options for encryption and for authentication of online entities.

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 certificates of root CAs that you trust. This file must contain the CA root certificate of the CA that signed the client's certificate. For example, in the demoCA environment, this is CARootcert.pem in the private directory of the DemoCA area in the client system.

Note: Visual COBOL 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.

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 in the product Help 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to confirm that you want to shut down the MF Directory Server.

Note: This is available only if MFDS is running as a program. Under normal circumstances, MFDS runs as a service, and this screen is unavailable.
CAUTION:

Shutting down the server might cause application connection errors and loss of data if currently running applications rely on reaching data registered in the Directory Server repository.

Stop servers before shutting down

Check this if you want the servers to be stopped before the Directory Server stops.

Yes

Click this to shut down the Directory Server. Enterprise Server Administration will no longer be available after you have shut down the Directory Server.

Parent topic: Security Configuration Screen Help


Update User

Use this page to modify the details of registered users and to delete users.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Account ID

Indicates the ID of the accout being edited.

Name

Specify the full name of the person assigned to this account.

Description

Specify a description of the user.

Default Group

Specify a default user group for this user.

Where a user verification request does not specify a group, this default group is used.

Allow Logon

Check this to permit the user to logon.

Member of:

Lists the user groups of which this user is a member. Click a group to select it for removal from this list.

User groups:

Lists all available user groups. Click a group to select it for adding to the Member of list.

Remove-->

Click this to remove the selected group from Member of.

<--Add

Click this to add the selected group to Member of.

New Password

Specify the new password of the user. Passwords can contain alphabetical and numeric characters only and are case sensitive. If you leave this field blank, the existing password is unchanged.

Confirm Password

Specify the case-sensitive new password of the user. If you enter a value that does not match the value in New Password, an error is generated and the existing password is unchanged.

Delete

Click this to delete this user.

Parent topic: Security Configuration Screen Help


User Group Members

Use this page to edit the details of a user group.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Group Members

Lists the members of this user group. Click a member to select it for removal from this list.

Add

Click this to add the specified user to the group. Note that the user must exist.

Remove

Click this to remove the selected member from the group.

Parent topic: Security Configuration Screen Help


User Groups

Use this page to add new groups, and to select a group for updating or deleting.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

The name of the group.

Description

A description of the group.

Members

Shows the number of users in the group.

Edit

Click this to select the adjacent group for updating or deleting

Add

Click this to add a new group.

Parent topic: Security Configuration Screen Help


User Import: another user registry

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to import user data to another user registry.

Note: User data is stored in a user definition file called CCIUSERS.dat, located in $COBDIR/etc .

Also, the fields available on this screen depend on whether you are importing from a file or from an LDAP server.

User registry

Specify the location of the user registry from which you want to import users.

If the registry is in a file, the location is the full name of the file.

If the registry is in an LDAP server, the location is the address of the LDAP server.

Note: When you specify ldap:/// as the type of registry, additional fields are displayed for specifying which users are to be imported, and the user credentials required for reading the data from the LDAP server.
Base DN

Specify the base distinguished name for the container from which the user entries will be obtained.

Filter

Specify any filter condition to restrict the list of users imported.

Credentials

Specify the credentials required to access the LDAP server.

User DN:

The distinguished name of the LDAP user with which to access the repository.

Password:

The password of the user with which to access the repository.

Replace all existing user information

Check this if you want all existing users to be removed and replaced with the users that you are importing. If this is not checked, existing users will not be changed and only those users in the import file that are not already present in your repository will be imported.

Replace existing duplicate user information

Check this to replace any existing user that is a duplicate of one being imported.

Import only users who are members of these groups

Restrict the users imported to those within the groups named in this field.

Add imported users into this group

Specify a group to which all imported users should be assigned.

Parent topic: Security Configuration Screen Help


User Import: previous version

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to import user data from a previous version of Micro Focus Directory Server.

Note: Prior to this release, user data was stored in a user definition file called CCIUSERS.dat. This was located in the install-dir\base\bin\ for Net Express or install-dir\bin\ where Enterprise Server was installed standalone.

Note also, the fields available on this screen will depend on whether you are importing from a file or from an LDAP server.

User registry

Specify the location of the user registry from which you want to import users.

If the registry is in a file, the location is the full name of the file.

If the registry is in an LDAP server, the location is the address of the LDAP server.

Note:

When you specify ldap:/// as the type of registry, additional fields are displayed for specifying which users are to be imported, and the user credentials required for reading the data from the LDAP server.

Base DN

Specify the base distinguished name for the container from which the user entries will be obtained.

Filter

Specify any filter condition to restrict the list of users imported.

Credentials

Specify the credentials required to access the LDAP server.

User DN:

The distinguished name of the LDAP user with which to access the repository.

Password:

The password of the user with which to access the repository.

Replace all existing user information

Check this if you want all existing users to be removed and replaced with the users that you are importing. If this is not checked, existing users will not be changed and only those users in the import file that are not already present in your repository will be imported.

Replace existing duplicate user information

Check this to replace any existing user that is a duplicate of one being imported.

Import only users who are members of these groups

Restrict the users imported to those within the groups named in this field.

Add imported users into this group

Specify a group to which all imported users should be assigned.

Parent topic: Security Configuration Screen Help


Scale-Out Performance and Availability Clusters

Attention: This feature is in Early Adopter Product (EAP) release status. We will continue the development of additional features and provide additional interfaces via patch updates and future releases. Please contact Micro Focus SupportLine if you require further clarification.

Enterprise server instances are typically deployed as a scale-up server. This means that performance is improved by adding or replacing the existing hardware components. Ultimately, the servers performance is limited by the machines existing resources.

A Performance and Availability Cluster (PAC) enables you to configure enterprise server instances in a scale-out architecture. In a PAC, multiple enterprise server instances work together, appearing to act as a single logical entity.

A PAC can provide the following advantages over a single scale-up enterprise server instance:

  • Availability - A PAC that utilizes distributed enterprise server instances improves robustness to hardware or network issues.
  • Performance - Multiple enterprise server instances working together to maximize the overall performance and throughput, potentially performing better than a single enterprise server instance. It also provides the benefits of future horizontal scaling.

The enterprise server instances in a PAC need to be able to share synchronised 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). There are two specific types of SOR:

  • A PAC SOR (or PSOR) - This stores system, configuration, and other data that needs to be accessible by all enterprise server instances in the PAC
    Note: A PAC must have only one PSOR.
  • A SOR that can be used to store 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.

  • Redis as a Scale-Out Repository
  • PAC and SOR Environment Variables
  • Supported CICS Resources
  • Starting a PAC
  • PAC Requirements and Best Practices
Parent topic: Enterprise Server configuration and administration


Redis as a Scale-Out Repository

Visual COBOL supports Redis as a Scale-Out Repository (SOR). Redis is an open source in-memory data structure store, although there are commercial versions available, such as Redis Enterprise. AWS also provides Elasticache for Redis which enables easy management and maintenance of Redis instances. Visual COBOL for Windows and UNIX, ships with a version of Redis.
Note: Micro Focus recommends that you deploy Redis to UNIX when being used as part of a PAC in a production environment.
To start the Redis server for UNIX environments, start a command prompt, and then type:
$COBDIR/AdoptRedis/redis-server
Note: This starts the Redis server on the default port 6379.

For more information on Redis click here.

Parent topic: Scale-Out Performance and Availability Clusters


PAC and SOR Environment Variables

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]
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.
sorType
This is the type of data store being used. Currently, Redis is the only supported SOR type.
connectionDetails
This is the host name and port number of the scale out repository, in the form host:port. For example, localhost:6379
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.
Parent topic: Scale-Out Performance and Availability Clusters


Supported CICS Resources

The following CICS resources can be stored in the PSOR when configured and operating:

PCT
Active PCTs in a PAC will have two different count values:
  • A count of the number of times the transaction has been executed across the PAC.
  • A local count for each enterprise server instance of the number of executions in that instance.
FCT
The VSAM file referred to by the resource of this type may be stored in an RDBMS. See the MFDBFH configuration for requirement.

Issuing a file close command in any enterprise server instance will result in the file being closed by all instances in the 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 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.
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 SOR by a 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.

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.
TST
Only non-recoverable queues can be stored in a SOR.
Parent topic: Scale-Out Performance and Availability Clusters


Starting a PAC

PACs cannot be started with a single action. All enterprise server instances within the PAC need to be started individually. You can script the individual actions to automate the process.

Micro Focus recommends that you only remove items from a SOR using the caspac utility. See caspac for more information.

CAUTION:
Use the InitPac action on the caspac command with caution. It must only be used when all enterprise server instances in the PAC are stopped and you want to cold start the PAC.

There is only one method of cold starting a PAC, to do that you need to run caspac with the InitPac action and then run casstart with /s:c.

In a PAC, you must use either /s:c or /s:w 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.

When using the casstart command, use the /s option with either w or c for warm or cold starts respectively to override the SIT setting for cold or warm starts of a TS or TD. If the /s option is not used then the SIT settings for TS or TD will be 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 enterprise server instances 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. At least one Redis instance for the PSOR and one for each additional SOR models.
  3. Run the following caspac command to initialize the PAC:
    caspac -aInitPac=pacname -stype,host:port
    Where the value for the -s option specifies the PSOR for the PAC, for example:
    caspac -aInitPac=MyPac -sredis,127.0.0.1:6379
    Note: This command will remove all data from the specified SOR. If the SOR contains TS or TD queue data, then it will be deleted.
  4. Cold start an enterprise server instance that is in the PAC1 by specifying /s:c on the casstart command2:
    casstart /rregionName /s:c
  5. You can start additional enterprise server instances that are part of the PAC using the following command:
    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.

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, (this is limited to PCT, FCT, PPT, DCT, and TST) will be placed in the PSOR. Enterprise server instances 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.

2 There is currently no option to cold start enterprise server instances via the user interface.

Parent topic: Scale-Out Performance and Availability Clusters


PAC Requirements and Best Practices

PAC requirements

Your PACs 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.
  • TRANCLASS is not supported in a PAC.
  • Prior to cold starting a PAC, ensure that you have run the caspac command to initialize the PAC.

PAC best practice

Micro Focus recommends you use the following best practice guidelines when using PACs:

  • Each enterprise server instance requires its own resource definition file (dfhdrdat). Only a subset of resources are stored in the 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.
  • The same SIT and startup list should be used for every enterprise server instance in the PAC.
  • Use the same program and file paths across a PAC.
  • Only use the caspac command to modify entries in the SOR. Removing entries manually might lead to unexpected behavior.
Parent topic: Scale-Out Performance and Availability Clusters


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 which provide CICS and JES functionality.
  • Administer Directory Servers, across multiple hosts, which provides the ability to stop, start and configure their Enterprise Server instances.
  • 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.
  • Enable administration of scale-out enterprise server instances for improved performance of systems under load. See Scale-Out Performance and Availability Clusters for more information.
  • Administer, monitor, and control Enterprise Server (ES) for .NET regions and listeners.

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.
  • Prerequisites
  • To Start ESCWA
  • Dashboard
  • Native
  • ES .NET
  • Security
  • ESCWA Client Web API
Parent topic: Enterprise Server configuration and administration
Related reference
Configuring External Security Facility (ESF) from the Command Line


Prerequisites

The Enterprise Server Common Web Administration interface has the following software requirements:

  • A Web browser (with a minimum required version):
    • Microsoft Edge (version 41.16299.820.0)
    • Firefox (version 65.0.1)
    • Google Chrome (version 72.0.3626.119)
    • Opera (version 58.0.3135.68)
    Note: Internet Explorer (IE) is not supported.
  • ESCWA is not supported on HP-UX and Solaris Sparc.
  • ESCWA only supports MFDS version of 1.25.37 or later.
  • 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.
Parent topic: Enterprise Server Common Web Administration


To Start ESCWA

To start ESCWA:

  1. Run services.msc to open the Windows Service Manager.
  2. In the Services list, click Micro Focus Enterprise Server Common Web Administration.
    Note: The service has a default startup type of Manual. Micro Focus recommends that you do not change this to Automatic until you have configured your security managers.
  3. To start the ESCWA service, click Start.
  4. Once the service is running you can access the Web interface with the following URL http:localhost:10004/
    Note: On the fist occasion you access the Web interface, two warning messages will be 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.
    • Access and administration of the ESCWA server is not restricted. Micro Focus recommends that you configure user access 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.

  • Enterprise Server Administration Configuration
  • Configuring TLS for the ESCWA Client
Parent topic: Enterprise Server Common Web Administration
Related reference
Specifying an External Security Manager


Enterprise Server Administration Configuration

You can configure the properties for the following categories:

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.
Note: Micro Focus recommends that you secure your Enterprise Server Common Web Administration installation by restricting access and enabling TLS.
  • Server Settings
  • Security Settings
  • Tracing and Logging Settings
Parent topic: To Start ESCWA


Server Settings

Protocol
Protocol used to connect to endpoint.
Requested Endpoint
The network address used by the listener to accept incoming client requests.
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.
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.
Parent topic: Enterprise Server Administration Configuration
Related reference
Configuring a TLS Protocols List
Configuring a Cipher Suites List


Security Settings

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.
Enable Single Sign On for Unsecured Resources
If this setting is enabled, ESCWA will use the current user's credentials to sign on to Directory Servers and other external entities, even if they are not TLS enabled. When disabled, this will only happen to TLS enabled resources.
Note: Micro Focus does not recommend using this option.

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.

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


Tracing and Logging Settings

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.

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.
SHOW LOG
Click this to display the Micro Focus ES Communications Process Message Log.
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.
Parent topic: Enterprise Server Administration Configuration


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. Check TLS SETTINGS.

    This opens the TLS Settings dialog box.

  4. Click Enable TLS.
  5. In the Certificate File field, type the absolute path to your certificate file (.pem).
  6. In the Certificate Password field, type your certificate password.
  7. In the Keyfile field, type the absolute path to your private keyfile (.pem).
  8. In the Keyfile Password field, type your private keyfile password.
  9. Click APPLY.

    This logs you out of the ESCWA interface.

  10. Log back in, and then click TLS SETTINGS.
  11. Click ADVANCED to expand the options available.
  12. In the Client Authentication field, select Accept all clients.
  13. Check Honor Server Cipher List.
  14. In the Protocols field, type +ALL.
    Note: This supports TLS1.3.
  15. In the Cipher Suites field, type DEFAULT.
  16. Click APPLY.
  17. Click BACK.
  18. Logout and restart the Micro Focus Enterprise Server Common Web Administration service.
  19. Now access ESCWA using the URL, or Common name, used when specifying the certificate being used.
    Note: The FireFox browser does not use the Windows certificate store. This means that you need to add the CARoot certificates 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 Visual COBOL bin directory. By default, this is located in $COBDIR/etc

Parent topic: To Start ESCWA


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. 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 $COBDIR\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.aux, 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 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.
Managed Region List
Displays either CICS or JES managed regions.
Parent topic: Enterprise Server Common Web Administration


Native

  • Directory Servers
  • Groups
Parent topic: Enterprise Server Common Web Administration


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 (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, 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.

  • Regions
Parent topic: Native


Regions

The REGION LIST page lists the regions that are associated with the parent directory server. To add a new region, click ADD and specify its details in the ADD 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.

  • General
  • Monitor
  • CICS
  • JES
  • IMS
Parent topic: Directory Servers


General

  • General Properties
  • Control
  • Listeners
  • Services
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.
Requested Licenses
Specify the number of licenses this enterprise server requires.
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

Mainframe Subsystem Support (MSS) configuration:

MSS Enabled
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.
PL/I Enabled
Indicates whether or not PL/I is enabled 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 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


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
Check this if you know that all the processes for this server are already stopped.

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 an 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.

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 start the region.
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.

Parent topic: General


Listeners

Communications processes handle communications between clients and the enterprise server instance, and consist of a number of service listeners.

To create a new communication process, click ADD 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.

To create a new listener:

  1. Click ADD LISTENER.
  2. Modify the listener properties as required.
  3. Click APPLY.

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.
Requested Endpoint
Specify the network address used by the listener to accept incoming client requests. The format is:
protocol:ip-address:port
where:
protocol
This is tcp.
ip-address
This 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
This 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.

Status
Displays 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.
Requested Status
The status the listener has been requested to change to:
  • Started
  • Stopped
  • Blocked
  • Disabled
Conversation Type
Displays the conversation types that are supported:
Web Services and J2EE
For client requests that use either of the conversation protocols supported by the Micro Focus request handlers, MFRHBINP and MFRHSOAP.
SOAP and J2EE (legacy)
This is a legacy conversation type.
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
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 whether or not to use Legacy Micro Focus Application Format.
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.
Parent topic: General


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.
Parent topic: General


Monitor

  • Live Properties
  • Monitor
  • Console
  • ES Control
  • SEPs
  • Clients
  • Locks
  • Environment Variables
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.
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.
Clients
The number of clients that have been active since the server was started.
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.
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.
HTTP Out
The size of the data blocks passed across shared memory for HTTP output.
ID Timeout
The global user ID timeout specified. If no ID timeout has 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 in size.
SM Total
The amount of shared memory available to this server, shown in KB.
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
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 the state of the Historical Statistics Facility (HSF).
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.
Local CCSID
The number of the CCSID to use for CICS Web services. The value must correspond to an EBCDIC CCSID. See CCSID Conversion Tables for further details.
ASCII CCSID
Identifies the ASCII CCSID that corresponds to the EBCDIC local CCSID specified in the SIT
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 the refresh icon.

Average latency (100/sec)
The average latency for transactions on this server. This is shown in hundredths of a second, and as a graphical representation in yellow.
Average tasks (100/sec)
The average time taken to complete a task on this server. This is shown in hundredths of a second, and as a 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: Monitor


Monitor

Use this page to 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 in yellow and is the average latency for a transaction in hundredths of a second.
Task Time
This is plotted in blue and is the average time taken to complete a task in hundredths of a second.
Task Rate
This is plotted in green 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


Console

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.

Parent topic: Monitor


ES Control

Use this page to view and change control information for this server.

To shutdown the current server, click SHUTDOWN:

  • To take a system dump when the server shuts down, check Dump.
  • To force an immediate shutdown, check Immediate. 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.

To send a message to all clients, type the message in the Enter Message field, and then click MESSAGE ALL.

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.
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 the A and B data sets that are 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 Count
Displays the number of dumps 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 indicate that MSS should produce a dump if an abend occurs in its own code.
Dump on ABEND 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, you can control whether or not a dump is produced for an individual program by checking or unchecking Dump on ABEND on the PCT properties dialog box. If you leave this field unchecked, MSS ignores the setting of Dump on abend on the PCT properties dialog box.
Debugger
Check this to enable dynamic debugging.

HSF Data

SWITCH
Clicking the SWITCH button will 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 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 that 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).
Active HSF set
Number of ESMAC Records
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.

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
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.
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.
pcp
Communications
cci
Do not check this unless advised by Micro Focus.
data
Check this to trace basic data in the communication module and IMS TM.
mfcs-cg
Check this to trace Micro Focus Communications Server (MFCS) requests.
common
Check this to trace thread processing in the communications module.
data-all
Check this to trace extended data in communication module and IMS TM.
cg-thread
Check this to trace lock management in the communications module.

Memory Strategy

Use this diagnostic feature to control the frequency and type of runtime memory validation, as well as specifying the processes to which these settings apply. You use this facility to help track down memory violations and corruptions. Unless you are directed otherwise by SupportLine, 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


SEPs

This page displays information about the Service Execution Processes (SEPs) on the current server.

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.
XFH Function
Parent topic: Monitor


Clients

Use this page to view client information for this server:

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


Locks

Use this page to view the current resource locks on this server.

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.
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.
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


CICS

  • CICS Configuration
  • 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:
  • FCT
  • PCT
  • PPT
  • Term
  • TST
  • T-Type
  • PLT
  • DCT
In Startup List
Active
Lists active resources.

To create a new SIT click SIT, and then click +ADD

To create a new Startup List click Startup Lists, and then click +ADD

To create a new Group click Groups, and then click +ADD

  • CICS Resources - SIT
  • CICS - Startup Lists
  • CICS - Groups
Parent topic: CICS


CICS Resources - SIT

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.
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.
Local CCSID
The number of the CCSID to use for CICS Web services. The value must correspond to an EBCDIC CCSID. See CCSID Conversion Tables in your product Help for more information.
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.
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.

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 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. 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 20 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.

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 temporary storage 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 temporary storage 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


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 startup list.

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 OK.

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 page to view, add, or edit a resource group.

To create a new group, click +ADD.

Name
The name of the group.
Description
A short description of the group.
Save
Click this to save changes you have made.
  • PCT
  • FCT
  • PPT
  • Term
  • T-Type
  • TST
  • PLT
  • Transient Data Queue
Parent topic: CICS Resources


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.
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.
Status
A status for the transaction program:
  • Enabled - The transaction program is enabled.
  • Disabled - The transaction program is disabled.
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.
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.
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.
Resource Keys
  • All - Check this to activate all the resource keys.
  • 1 - 24 - Check any of the boxes 1 through 24 to activate that resource key.
Security Keys
  • All - Check this to activate all the security keys.
  • 1 - 64 - Check any of the boxes 1 through 64 to activate that security key.
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.
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.
HTTP
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.
Resource Keys
All
Check this to activate all the resource keys.
1 - 24
Check any of the boxes 1 through 24 to activate that resource key.
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).
Status
A status for the resource:
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.
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.
Resource Keys
All
Check this to activate all the resource keys.
1 - 24
Check any of the boxes 1 through 24 to activate that resource key.
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.

If you displayed this page by clicking * NEW on a previous page, some values on this page are already set to their default values.

Click DUMP to create and view dump information for this Term. This button is displayed only after you click * NEW.

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.

Resource Keys

All
Check this to enable all the resource keys.
1-24
Check any of the boxes 1 through 24 to activate that resource key.
Parent topic: CICS - Groups


T-Type

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.

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.
  • Active Terminal Type
Parent topic: CICS - Groups


Active Terminal Type

Use this page to view information about the active Terminal Type named ttype_name. You can also view a dump of the Terminal Type.

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: T-Type


TST

Use this page to view and edit the Temporary Storage Queue (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.

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 Sys or the number of 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.

Resource Keys

All
Click this to enable all the resource keys.
1-24
Check any of the boxes 1 through 24 to activate that resource key.
  • Active Temporary Storage Queue List
  • Active Temporary Storage Queue
Parent topic: CICS - Groups


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.
Parent topic: TST


Active Temporary Storage Queue

Use this page to view information about the Temporary Storage (TST) queue named tst_name. You can also view a dump of the TST.

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.

Resource Keys

All
Click this to enable all the resource keys.
1-24
Check any of the boxes 1 through 24 to activate that resource key.
Parent topic: TST


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


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.

Resource Keys

All
Enables all the resource keys.
1-24
Check any of the boxes 1 through 24 to activate that resource key.
  • Active Transient Data Queue List
  • Active Transient Data Queue
Parent topic: CICS - Groups


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.
Parent topic: Transient Data Queue


Active Transient Data Queue

Use this page to view information about the Destination Control Table (DCT) named dct_name. You can also view a dump of the DCT.

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.

Resource Keys

All
Click this to enable all the resource keys.
1-24
Check any of the boxes 1 through 24 to activate that resource key.
Parent topic: Transient Data Queue


JES

  • JES Configuration
  • Spool
  • Catalog List
  • JES Control
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.
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.
Note: You cannot share a catalog between servers.
Default Allocated Dataset Location
The default directory to be used for the creation of new data sets.
System Procedure Library
The name of your system procedure library.
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 +ADD.

    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 OK.

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 +ADD.

    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 OK.
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.

You can filter the list by clicking FILTER. Selecting from the filter options, and then click APPLY.

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.
Output Types
Input
Jobs waiting to start. Typically, because no initiator for the correct class is currently available.
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
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 the results by:
  • Name
  • Job ID
  • Submitted
Order
Click Descending to sort the output by descending order.
From
Limit the result to Job Submitted after the given date.
To
Limit the result to Job Submitted before the given date.
  • 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 RELEASED 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.

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 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 RELEASED button when you click it.

SAVE Click this to save any changes made.

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 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.
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 SAVE.
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 SAVE.
File
The full path of the file containing the JCL that was run.
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.
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.
DCB
Click [image] to view and modify information for a cataloged data set.
Display
Click [image] to display the content of the catalog file. If the DS Org is partitioned (PO) then a list of the Partitioned Data Set (PDS) members will be displayed.
  • PO List
Parent topic: JES


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.
Parent topic: JES


IMS

  • IMS Configuration
  • IMS Transaction List
  • IMS Control
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.
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


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.
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.
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:
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.
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.
Status
Choose the status of the transaction program:
Enabled
The transaction program is enabled.
Disabled
The transaction program is disabled.
ULC
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.
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

Security Keys

All
Check this to enable all the security keys.
1-64
Check any of the boxes 1 through 24 to activate that security key.
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 INSTAL 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.
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.
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.
Status
Choose the status of the transaction program:
Enabled
The transaction program is enabled.
Disabled
The transaction program is disabled.
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.
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.

Security Keys

All
Check this to enable all the security keys.
1-64
Check any of the boxes 1 through 24 to activate that security key.
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.
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
This displays how many thread requests have been processed since the last keypoint.

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


Groups

  • Logical
  • Performance and Availability Clusters
Parent topic: Native


Logical

  • Region Group List
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
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

You can configure Performance and Availability Clusters (PACs), these clusters 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.

Important: Before you start working with PACs you need to specify SORs for use in your PACs.
  • Configuring PACs and SORs
  • Scale-Out Repositories
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 Performance and Availability Cluster (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 PSOR which will store the system and configuration data that will be shared between all the enterprise server instances that are part of the PAC:

  1. In the menu bar, click NATIVE.
  2. In the navigation pane, click Groups > PACs > 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 field, select Redis.
  6. Optionally, in the Description field, type a description for your PSOR.
  7. 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, you can specify the connection details for multiple Sentinels. Each connection must be delimited by a comma. For example:
    host1:5000,host1:5001,host2:5000
  8. Click SAVE.
Important: Only one PSOR can be associated with a given PAC. A PSOR can be specified with multiple Redis Sentinel connections. This configuration can help support high availability. You can specify multiple connections in the Connection Path(s) field, each delimited by a comma.

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.
  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 SCALE-OUT REPOSITORY CONFIGURATION 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. 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. 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.
  6. In the right pane, click 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


Scale-Out Repositories

You can view, add, edit, and delete Scale-Out Repositories (SORs). These resources represent a connection to a third-party configuration store for use in scale-out infrastructure.

To create a SOR:

  1. In the menu bar, click NATIVE.
  2. In the navigation pane, click Groups > PACs > 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. The default is Redis.
  6. In the Connection Path(s) field, type the server name and port number.
    Note: If you are using Redis Sentinel, you can specify the connection details for multiple Sentinel. Each connection must be delimited by a comma. For example:
    host1:5000,host1:5001,host2:5000
  7. Click SAVE.
To edit a SOR:
  1. 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 connections. This configuration can help support high availability. You can specify multiple connections in the Connection Path(s) field, each delimited by a comma.
Parent topic: Performance and Availability Clusters


ES .NET

Items under this node in the navigation tree are for administering Enterprise Server for .NET. Currently limited functionality for ES for .NET administration is available in ESCWA. For other functions, use the Microsoft Management Console (MMC) Enterprise Server for .NET snap-in and the command-line utilities, as described in the ES for .NET product Help.

To use the .NET functions in ESCWA, the ES for .NET administration service, seeadminserver, must be running. Some operations also require the ES for .NET monitor service, seemonitor; the ES for .NET listener service, seelistener; and/or the SQL Server instance(s) which host the ES for .NET system databases.

  • CICS
  • JES
  • Listener Control
  • Managed Region
Parent topic: Enterprise Server Common Web Administration


CICS

Use this page to administer ES for .NET CICS regions, also known as Managed CICS regions.

To administer a region, you must add it to the list of known regions.

Note: The ES for .NET MMC snap-in and seeadminserver maintain separate collections of known regions. Regions must be added to the two administration tools individually.

To add a new region:

  1. Click +ADD.

    This opens the ADD REGION dialog box.

  2. In the Name field, type your region's name.
  3. In the Database Server field, type the server instance location where you want your region database to be created.
  4. In the Start/Stop Server field, type the default service host name where the region will be run.
  5. Optionally, in the Startup File field, click the folder icon and choose the startup file required or type the file.
  6. Click OK.

To view the properties and operations for a region, double-click on a region in the list, or click the Edit Edit icon, or expand the CICS node in the navigation pane and select a region below it.

Parent topic: ES .NET


JES

Use this page to administer ES for .NET JES (batch) regions, also known as Managed JES regions.

To administer a region, you must add it to the list of known regions.

Note: The ES for .NET MMC snap-in and seeadminserver maintain separate collections of known regions. Regions must be added to the two administration tools individually.

To add a new region:

  1. Click +ADD.

    This opens the ADD REGION dialog box.

  2. In the Name field, type your region's name.
  3. In the Database Server field, type the server instance location where you want your region database to be created.
  4. In the Start/Stop Server field, type the default service host name where the region will be run.
  5. Optionally, in the Startup File field, click the folder icon and choose the startup file required or type the file.
  6. Click OK.

To view the properties and operations for a region, double-click on a region in the list, or expand the JES node in the navigation pane and select a region below it.

Parent topic: ES .NET


Listener Control

Use this page to view and control ES for .NET listener processes.

A given ES for .NET listener process is displayed on this page when it has registered itself with one or more of the database instances configured on the page. A listener will register itself with a database instance the first time it successfully connects to a region that uses that database instance.

To add or remove database instances for the page:

  1. Click DATABASE INSTANCES.

    This opens the Database Instances dialog box.

  2. Type the name of the database instance to use.
  3. Click OK.

Instances will appear in the navigation tree on the Listener Control page. Under each instance a list of known Listener Processes will appear when that instance is expanded.

Selecting a listener process will display its URL, host, and process ID. Expanding it will display the regions for which the listener has channels.

To temporarily add a region to a listener process:

  1. Click + ADD REGION.

    This opens the ADD REGION dialog box.

  2. In the Name field, type the name of the region.
  3. In the Database Server field, type database server instance where you want your region database to be created.
  4. Click OK.
Note: To permanently add a region to a listener, edit the listener's configuration file, using the ES for .NET MMC snap-in or by editing the seelistener.exe.config file in a text editor.

Expanding a region under a listener process will display the current channels.

To temporarily add a channel:

  1. Click + ADD CHANNEL.

    This opens the Add Channel dialog box.

  2. In the Name field, type the name of the channel.
  3. In the Protocol field, click the required protocol.
  4. In the Port field, type the port number the channel will listen on.
  5. Alternatively, expand the ADVANCED properties and specify as required.
  6. Click OK.
Note: To permanently add a channel to a region, edit the listener's configuration file.

Selecting a channel will display its properties. You can also edit, disable, enable, or delete the channel.

Channel Properties

Name
The name of the channel.
Protocol
The protocol the channel uses:
  • TN3270
  • MFBINP
  • HTTP
  • MQ
  • P2P
Port
The port the channel will listen on.

Advanced Channel Properties

Enabled
Click this to enable the channel.
Heartbeat
Heartbeat (keepalive) time in seconds.
Idle Conversation Timeout
Timeout for idle persistent HTTP conversations.
Cookie Timeout
Timeout specified for HTTP session cookies.
Idle Session Timeout
Timeout for idle persistent HTTP sessions.
IP Version
The version of the IP protocol to use:
  • IPv4
  • IPv6
  • Both
Cookie Path
Path specified for HTTP session cookies.
Data Trace
File path or URL for data-trace output.
Send 100 Continue
Whether the listener should respond to 100-Continue requests from HTTP clients.
Parent topic: ES .NET


Managed Region

The page for a managed region provides the following information and functions. If the region database does not exist, for example, if the region has been defined in ESCWA but never started, or if the region database exists but the region is not running, not all information and functions will be available.

General Properties

The optional properties in the region definition. These are the hostname of the server where region start/stop operations will run. This defaults to the host where seeadminserver is running, and the name of the startup file, which defaults to Region_region-name.config.

Control

Start or stop the region.

Monitor

Monitor activity in the region, if it is running. For a scale-out region, you can monitor all region activity or only activity on a single host. The view can be set to refresh automatically at a specified interval.

Console

View the region console log. The view can be set to refresh automatically at a specified interval.

Statistics

View basic region statistics, including average latency, task time, and rate of task processing by either 1-minute or 15-minute intervals. The view updates automatically.

SEP Traces

View the local Service Execution Process (SEP) trace tables. These show a trace of recent operations for application program processing.

Historical Statistics Facility

View data recorded by the Historical Statistics Facility (HSF), if it is enabled for the region. HSF data is a detailed record of application activity.

Note: Currently for CICS regions only.
  • General
  • Monitor
Parent topic: ES .NET


General

  • Properties
  • Control
Parent topic: Managed Region


Properties

Use this screen to assign a properties file for a region, to define pseudo-variables, and to configure a server other than the current one on which to run the region.

Start/Stop Server
The name of the server that starts the region. When the region starts, the region's event monitor runs on this server.
Startup File
The path and filename of the region startup file.

You can amend the properties and then click APPLY to save your changes.

Parent topic: General


Control

Use this screen to start a region, or to stop a region that is running. Displayed options depend on the region status.

Normal Stop
Performs a normal stop by doing the following:
  • Blocks any new transaction requests.
  • Allows completion of running transactions.
  • Runs the PLTSD shutdown procedure after running transactions complete.
Immediate Stop
Performs an immediate stop by doing the following:
  • Blocks any new transaction requests.
  • Aborts any running transactions.
  • Runs the PLTSD shutdown procedure.
Force Stop
Performs a forced stop. The system does whatever is necessary to stop the region immediately. The PLTSD shutdown procedure does not run.
STOP
Click this to stop the region with the selected option.
Parent topic: General


Monitor

  • Monitor
  • Console
  • Statistics
  • SEP Trace
  • Historical Statistics
Parent topic: Managed Region


Monitor

Use this screen to view the operating statistics of a running region.

Refresh Rate(s)
The refresh rate in seconds.
Max Tasks
The maximum number of tasks the region is configured to run.
Next Task ID
The id of the task scheduled to run next.
Region Start Time
The time the region started.
Active Tasks
The current number of active tasks.
Active Session
The current number of active sessions.
Max Active Tasks
The maximum number of tasks that have run at once during the current session.

Running tasks and their details are displayed in the active tasks list.

  • Start Time
  • Duration(s)
  • Transaction ID
  • CICS Command
  • Task ID
  • Session
  • URL
Parent topic: Monitor


Console

The console displays messages that a region generates as it performs tasks. You can configure information displays and the order of the information columns. Date, Time, and Message columns display by default.

Note: You can also configure the console message level for a region.

You can configure the console to display the following message information:

Refresh Rate (s)
Refresh rate in seconds.
Date
The date on which the message was generated.
Message
The generated message. You can configure the level of messages displayed for each region.
Thread
The processing thread for the task that generated the message.
AppDomain
The application domain in which the task is running.
Process
The process ID that generates the message.
Severity
Parent topic: Monitor


Statistics

Use this page to 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 half-an-hour for Monitor (1 minute intervals), and over the last 8 hours for Monitor (15 minute intervals).

Latency
This is plotted in yellow and is the average latency for a transaction in hundredths of a second.
Task Time
This is plotted in blue and is the average time taken to complete a tasks in hundredths of a second.
Task Rate
This is plotted in green 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


SEP Trace

A trace table is an in-memory collection of the most recent key events to have occurred within a SEP. Any given SEP may contain one or more local trace tables depending on the activity that has occurred within it. For example, there will be a separate trace table for each region's CICS transaction or JCL activity.

Parent topic: Monitor


Historical Statistics

This view shows the Historical Statistics Facility (HSF) aggregated data view. If your managed region config file has HSF enabled, you can:

  • View transactions in a chart format to see transaction counts and mean response times. If you click on a chart in this view you can go to the raw view for that transaction.
  • View more extensive data in the table view.
  • Search by transaction names.
  • Filter this data via a dialog.
  • Delete this data via a dialog.
Parent topic: Monitor


Security

  • Restricting ESCWA with ESF
  • Security Manager Administration Operation
  • Security Manager's Properties
  • ESF Authentication and ESCWA
  • Transport Layer Security (TLS) in ESCWA
Parent topic: Enterprise Server Common Web Administration


Restricting ESCWA with ESF

Security configuration is performed from the Security node in the navigation pane. 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
  • Changing the order of Security Managers
  • Group Permissions Cached in ESCWA
Parent topic: Security


Specifying an External Security Manager

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 security manager to use. If you are integrating with an LDAP you can use the mldap_esm with both Microsoft Active Directory or OpenLDAP.
  7. In the Connection Path field, type the hostname or IP address and port number of the security manager being connected to. For example ad-host:389.
  8. In the Description field, type a description of the security manager.
  9. In Authorized ID field, type the DN of a user with appropriate permissions for the security manager. For example, CN=Administrator,CN=users,DC=somecorp,DC=com.
  10. In the Password field, type the password for the user specified in the Authorized ID field.
  11. In the Description, type a description that can identify the use of the security manager.
  12. In the Config field, type the required configuration options. See Configuring mldap_esm Security Manager for an LDAP for more information.
  13. By default, the Cache Limit and Cache TTL are fields are set to 1024 kB and 600 seconds respectively. See Enabling and Configuring Caching for more information.
  14. Click SAVE.

    This adds the specified security facility to the DEFINED EXTERNAL SECURITY MANAGERS list.

  15. To add the specified external security manager to the security managers list, click + ADD.

    This opens the Defined External Security Managers dialog box.

  16. Click the external security managers that you want to add to the security managers list.
  17. Click SELECT.
Parent topic: Restricting ESCWA with ESF
Related reference
Enabling and Configuring Caching
Configuring mldap_esm Security Manager for an LDAP


Changing the order of Security Managers

You can change the order of the security managers in the security managers list using either of these methods:

  1. You can drag and drop security managers to its new position in the list.
  2. 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

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 refresh the ESCWA cache. To refresh the ESCWA cache, click UPDATE, and then click UPDATE when prompted in the UPDATE SECURITY CONFIGURATION? dialog box.

Parent topic: Restricting ESCWA with ESF


Security Manager Administration Operation

You can access the security administration component from the navigation tab, click Security > 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


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


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


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


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


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


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 restrict their 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
  • Restricting Regions with ESF
  • Restricting ES for .NET with ESF
Parent topic: Security


Restricting Directory Servers with 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 Defining a Security Manager List 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 Setting MF Directory Server Security Configuration for more information.
  • Amend the ESF configuration settings to be used with the stack. See MF Directory Server Security 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

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 Default ES Security Configuration and Add to Default ES Security Manager List for more information.
  2. Alternatively, you can override the default option on a per region basis. See Server Instance Properties: Security 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 ES for .NET with ESF

Security managers and security configurations for ES for .NET are configured separately from those used by other Enterprise Server components. Use the ES for .NET MMC snap-in to create and administer security managers and security configurations for ES for .NET.

To restrict ES 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 to ensure that your data and applications remain secure. Communications that are not secured risk being attacked and/or intercepted, leading to 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.
  • That if your DemoCA installation on UNIX is in a non-standard location, you can use the COBSSL environment variable to point to the new location.

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 ESMAC using TLS
  • 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 MF Directory Server Security Configuration page. See MF Directory Server Security for more information.

To enable TLS security:

  1. In Enterprise Server Administration, click Security.
  2. Click MF Directory Server tab.
  3. Click Restrict administration access, and then click Use encrypted connections.
  4. In the Secure Port field, type the port number to be used.
  5. Click Use custom server ID certificate
  6. In the Certificate and Keyfile fields, type the path to your certificate and keyfile respectively.
Note: The Secure Port specified is not required by the ESCWA configuration for the Directory Server.

The Certificate Authority (CA) list which ESCWA checks will either be at the location of the MF_ROOT_CERT environment variable or in your DemoCA installation (if installed) under private/CARootcert.pem. 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.

Parent topic: Transport Layer Security (TLS) in ESCWA


Securing Communications between ESCWA and ESMAC using TLS

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. This JSON interface is part of the component known as ESMAC.

Communications between ESCWA and ESMAC can be secured by configuring the Web Services and J2EE listener. See To Create a Secure Listener and SSL Options for more information.

ESCWA will communicate with ESMAC as a client and should be configured as such. See Installing a Client Certificate for Enterprise Server for more information. You should configure the root in mf-client.dat on the ESCWA host machine such that it points to the Certificate Authority (CA) list .pem file which contains the public CA certificate information that has signed the certificate used by the Web Services and J2EE listeners. Otherwise, your DemoCA installation under private/CARootcert.pem will be checked.

Parent topic: Transport Layer Security (TLS) in ESCWA
Related reference
To Create a Secure Listener
SSL Options
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. Otherwise, your DemoCA installation under private/CARootcert.pem is checked.

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 instances. 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.

Communications between Communications Process and a Directory Server can be secured by configuring TLS settings on the MF Directory Server Security page. See MF Directory Server Security for more information. Click Use encrypted connections, and then click Use custom server ID certificate. Specify the your certificate and keyfile information.

Note: The Certificate Authority (CA) list which the Communications Process checks will be on a different host to ESCWA if that is where the process runs. The CA list is either located at the location specified by the MF_ROOT_CERT environment variable or in your DemoCA installation (if installed) at private/CARootcert.pem. Ensure 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.

The Directory Server currently does not support authentication to a Communications Process using a client certificate. The Directory Server is not 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


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
  • Session Management
  • ESCWA Interactive API Library
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 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:10004.
  • One of the Origin or Referer headers must be set to the location of the ESCWA instance, for example, https://localhost:10004.
  • 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

Whether ESCWA is restricted or not, all clients must use a session to perform their actions. To 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:10004/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.
Parent topic: ESCWA Client Web API


Deploying and Configuring Modernized Applications

Describes how to configure and administer modernized COBOL applications running in the Enterprise Server environment.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • About Modernized Applications
  • Managing Resources
  • Adding and Deleting Services
  • Configuring and Monitoring Services
  • Configuring Implementation Packages
Parent topic: Deploying to Enterprise Server


About Modernized Applications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

COBOL applications can be modernized so that they run in the Enterprise Server environment. A modernized COBOL application can be deployed as a service that perform the application's operations.

A service provides access to specific business functionality. A COBOL program implemented as a service reads in a parameter block, processes it and returns a results block.

A service that you create within Enterprise Server can contain one or more operations, depending on the name you give the service and which request handler is associated with it (if any). If you create a service with no request handler associated with it or if the name you use does not contain a valid separator, the service and the operation are one and the same. The Enterprise Server documentation uses the term "simple service" for services of this type. System services such as the Deploy service of the default enterprise server instance, ESDEMO are simple services.

  • Service Names and Operations
  • Types of Services Supported
Parent topic: Deploying and Configuring Modernized Applications


Service Names and Operations

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Service names can be of two forms, depending on whether or not the service contains any operations. The two forms are:

  • Names consisting of one part, for example, Test or my_service. Simple services have this type of name.
  • Names consisting of three parts, for example, http:/tempuri.org/wmapserv#Add. The parts are:
    • The service namespace. This is the part of the name before the first pound (#) character
    • The separator, in this case, the pound (#) character
    • The operation name, in this case Add

    Services with operations have this type of name.

    Service names for Web services use the first pound (#) character as a separator, while names for services that form part of a J2EE application use the last period ( ) character, for example, mybinpservice.operation.

    You can include more than one pound character or period in a service name; Enterprise Server will interpret the first pound character or last period character it finds as the separator.

  • The Services Table
  • Configuring Services
Parent topic: About Modernized Applications


The Services Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for services by clicking Details against Services in the table of servers on the Home page. The services table is shown below.

Figure 1. Services Table
Services Table

The information is as follows:

  • Service namespace - a unique label within the enterprise server that identifies the service and if it contains operations, groups the operations together
  • Operation - a list of the individual operations within a service; if the service is a simple service, there is just one item in this list, and it bears the same name as the service itself
  • Service class - for Micro Focus use only; set to MF deployment for all deployment services
  • Search order - the order in which services of the same name are sorted for searching purposes
  • Listeners - a list of the listeners allocated to this service
  • Request handler - the request handler for this service
  • Implementation package - the implementation package that provides the business functionality
  • Status information - you can see the current status and the time of the last status change
  • Status log - this supplies information about the most recent event that occurred on this service
  • Custom configuration data - for more information see the section Configuration Information
  • Description

Service display flters control how much service information you can see. These appear at the top of the services table. There are four service display filters:

  • Service: to use this filter, specify the name of the service you want to view; you need only enter enough characters to identify the service uniquely
  • Class
  • Handler
  • Package

Except for Service, each has three options

  • None: choose this to see no services for this filter
  • Some: choose this to see services that have a value for this filter
  • All: choose this to see all services for this filter

For example, to see service details for services of class 1, choose Some in Service Display Filters Class; to see only services that do not have a request handler associated with them, choose None in Service Display Filters Handler; to see all services choose All in all three filters that have options and leave Service blank. Use all the filters in combination to achieve the maximum control over the level of detail you see.

When you first see the Services table, all the filters that have options are set to All and the Service filter is blank.

Parent topic: Service Names and Operations
Related information
Configuration Information


Configuring Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the Configuration Information field on the Add Service and Edit Service pages for configuration data specific to services.

The [MF client] settings provide configuration for MFCC when it is creating the deployment request.

The [destination] settings are used by mfdepinst when it creates service and package objects in the Directory Server while installing a deployment package (.car file).

Note: These settings are only used when deployment is done via MFCS, using the IMTK or another deployment client. If you run mfdepinst manually from the command line to install a .car file, it is not invoked for a particular deployment service, so it has no deployment service configuration to consult.
[MF client]
scheme=protocol
URL=virtual-directory-name-1/mfdeploy.exe/virtual-directory-name-2
accept=request-data-type
[destination]
listener=listener-name
server=server-name
Parent topic: Service Names and Operations


Types of Services Supported

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server applications deployed as services can be one of three types:

  • Web services

    These are components using standards and mechanisms that enable software components to be invoked across the Web. A client application using a Web service can invoke the service, and pass data to and from it in the form of XML files sent using a standard protocol such as HTTP.

  • J2EE services
Parent topic: About Modernized Applications


Managing Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A COBOL application providing a service that uses external resources, such as databases and files, can manage its own resources or let the application container manage them. A service that manages its own resources is known as application-managed, while a service that does not manage its own resources is known as container-managed.

If a service updates files through Fileshare, you must specify the name and location of an fhredir.cfg file for the enterprise server in which the service runs.

  • Application-managed Services
  • Container-managed Services
  • Mixing Container-managed and Application-managed Services
Parent topic: Deploying and Configuring Modernized Applications


Application-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A service must manage its own resources if:

  • The application accesses files or databases (or both) in a transactional way, and contains transactional logic: that is, it includes COMMITs and ROLLBACKs
  • The application uses a resource manager that we do not support in the Enterprise Server environment; see the list in Supplementary Information.

A service in which the application accesses files in a non-transactional way, 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.
Parent topic: Managing Resources


Container-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If an application running as a service uses databases and files but does not contain any transactional logic, it can let the application container manage its resources.

The application container must know in advance what resource managers will be required. You define resources not by service, but by enterprise server instance. You can only define resource managers that are XA-compliant.

When an enterprise server instance and its service execution processes start up, the enterprise server manager opens connections to all the resources that might be needed by the services that run in that enterprise server instance. When a container-managed service is invoked, the enterprise server manager performs all file and database actions that it requires.

The application container manages databases by issuing XA commands.

The application container decides whether to commit or roll back resources using information supplied when the enterprise server instance was created and deployed in your COBOL development system. However, if there is an error in the application container itself, resources are always rolled back.

Parent topic: Managing Resources


Mixing Container-managed and Application-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can mix container-managed and application-managed services in the same enterprise server, but in these circumstances it is even more important that the application-managed services complete with all resources either committed or rolled back. This is because when the application container commits or rolls back resources on behalf of a container-managed application, it commits or rolls back all outstanding updates, including any outstanding from application-managed services that ran previously.

Parent topic: Managing Resources


Adding and Deleting Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can add services and implementation packages to an enterprise server instance, and update and delete them whether or not the enterprise server instance is running.

If the enterprise server instance is running (that is, if it has the status "Started") when you are adding services and packages, the changes are immediately reflected in the enterprise server. As long as the service is not currently responding to a client request, any updates are also accepted and take immediate effect.

You cannot delete a service, package or request handler if the resources are in use by a client request. You cannot delete a package if it is associated with a service, whether or not the service is running. If a service has operations, you can delete a service and all its operations and packages in one step, or you can delete individual operations and packages.

When you delete services, packages and request handlers, you are deleting objects in the Directory Server repository, not physical files. Every time a developer deploys a service using the Deploy tool or the imtkmake command, a new directory is created in the enterprise server's deploy directory to hold all the deployed files. If a developer redeploys a service that has already been deployed, the old deployment directory is no longer referenced, since the old service and package objects will have been deleted. You might want to delete old deployment directories from time to time.

If an enterprise server instance is running and you add, edit or delete resources, administration messages are sent to the enterprise server console indicating the success or otherwise of your changes.

It is possible for the Directory Server repository to become out-of-step with an enterprise server instance if the Directory Server accepts updates that the enterprise server instance rejects. If this happens you should stop the server and restart it to enable it to pick up the updates.

  • Creating Services Manually
  • To Add a Service to an Enterprise Server Instance
  • To Associate a Package with a Service
Parent topic: Deploying and Configuring Modernized Applications


Creating Services Manually

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you add services manually to an enterprise server instance, you need to create the objects for them and their relationships in a certain order, as follows:

  1. Add the implementation package to the enterprise server instance
  2. Add one or more service listeners
  3. Add the service, and associate the listener or listeners, implementation package and request handler with it
Parent topic: Adding and Deleting Services


To Add a Service to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details against Services in the Objects column for the server you want to add the service to.
  2. Click Add.
  3. Specify a name for the service in Name.
  4. If you have more than one service of the same name in the repository, specify a search order for the service in Search Order. The lower the search order, the higher the search priority .
  5. If you want to enable clients to search for services by class, specify the class in Service Class.
  6. Change the default value in Version, if required.
  7. Choose the type of transaction management appropriate to this service: check either Application or Container.
  8. Click a listener you want to use on this service in Available Listeners and then click Add. You can repeat this step to add extra listeners. The listener is added immediately.
  9. Click the request handler you want to use on this service in Available Request Handlers and then click Select Handler. The selection is active immediately.
  10. Click the implementation package that is to provide the service functionality in Available Packages and then click Select Package. The selection is active immediately.
  11. Choose a status for the service from the list in Initial status.
  12. Specify any configuration information the service requires in Configuration Information.
  13. Specify a text description of the service in Description (optional).
  14. Click Add.
Note:
  • You can also reach the Add Service page by clicking Edit to the left of the server to which you want to add the service, clicking the Services tab and clicking Add.
  • You do not have to select a request handler and package for the service when you first add it to the server. You can do this at a later time by going to the Edit Service page.
Parent topic: Adding and Deleting Services
Parent topic: Work with Services
Related information
To Add a Package to an Enterprise Server Instance


To Associate a Package with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Click Edit to the left of the row containing the service with which you want to associate the package.
  4. In Available Packages click the package that you want to associate with the service.
  5. Click Select Package.
Note:

A service can have just one package associated with it.

Parent topic: Adding and Deleting Services
Parent topic: Work with Packages


Configuring and Monitoring Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you are running services on an enterprise server instance, you need to ensure that services are starting and stopping as expected, and that no service is using more resources than expected.

The Monitor page enables you to view the performance of services, providing information about:

  • The average latency, in hundredths of a second.
  • The average time taken to complete a task, in hundredths of a second.
  • The number of tasks completed per second.

For example, if the average time taken to complete a task is large, this would indicate that a service is a long running or stateful service. If the number of tasks completed per second suddenly rises beyond what you expect, this might indicate that a task is repeatedly calling another task in error.

  • Services and Permissions
  • To Monitor Services
  • To Record Service Input and Output
  • To Add a Service for Integration with the Micro Focus Development Tools
  • To Change the Status of a Service
  • To Delete a Simple Service or an Operation
  • To Delete a Service with Operations
  • To Edit a Service
  • To Switch Logging On for a Service
  • To View Services for an Enterprise Server Instance
Parent topic: Deploying and Configuring Modernized Applications


Services and Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a service
  • Switch logging on or off for a service. When logging is on, the service's request and result blocks are written to the enterprise server's dump data set
  • Change the status of a service between available and disabled

If you have Add/Delete permission level or higher you can also:

  • Add a service
  • Delete a simple service or operation
  • Delete a service with operations. When you delete a service with operations you delete all the operations associated with it. You can also delete the packages associated with it
Parent topic: Configuring and Monitoring Services


To Monitor Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To monitor services

  • Click either:

    • Monitor, 1 - This displays the Monitor (1 Minute Intervals) page. Use this to monitor the current situation. This page displays information on the last 32 minutes of activity.
    • Monitor, 15 - This displays the Monitor (15 Minute Intervals) page. Use this to gain information on how the system is performing overall. This page displays information on the last eight hours of operation.
Parent topic: Configuring and Monitoring Services
Parent topic: Administer a Server Using ESMAC


To Record Service Input and Output

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To record service input and output

  1. Click Services.

    The Services page is displayed.

  2. Click Details for the service for which you want the input and output to be recorded.

    The Services page is displayed.

  3. Click the Log I/O dropdown.

    Select Dump.

  4. Click Change.
Note:

If you set input and output to be recorded, they are only recorded during this enterprise server session. If you stop and restart the enterprise server, input and output will no longer be recorded.

If you want input and output to always be recorded, you can specify this using Enterprise Server Administration.

Parent topic: Configuring and Monitoring Services
Parent topic: Administer a Server Using ESMAC


To Add a Service for Integration with the Micro Focus Development Tools

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Object column for the server you want to add the service to.
  2. Click Add.
  3. In both Name and Service Class type: MF ES
  4. Leave the type of transaction management as Application.
  5. In Available Listeners, select the line containing Web Services and J2EE. Then click <-Add below this field.
  6. In Description type a suitable description, such as ES utility service.
  7. Click Add.
Note:
  • You can also reach the Add Service page by clicking Edit to the left of the server to which you want to add the service, clicking the Services tab and clicking Add.
  • Do not associate this service with a handler.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Change the Status of a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details against Services in the Objects column for the server you want to change.
  2. Click Edit in the Operation column for the service whose status you want to change.
  3. Choose the new status from the list in New Status.
  4. Click Apply.
Note:

Depending on the status of the change request, one of three messages is displayed in the Enterprise Server Administration GUI status bar:

  • MDS0112I Update success
  • MDS0111W Update request failure

In the case of a failure the state of the service, as reported by the ES Administration GUI, changes from "Available" or "Disabled" to a pending state. The next time the ES instance starts it will use the new configuration.

  • MDS0110W The specified configuration change may not take effect until the server is restarted

The state of the service, as reported by the Enterprise Server Administration GUI, changes from "Available" or "Disabled" to "Changes made to service: a server restart may be required for the new configuration to take effect". To check whether the service update was effective, use the ES Monitor and Control HTML GUI and select the "Services" resource list page.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Delete a Simple Service or an Operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Deleting a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server that owns the service you want to delete.
  3. Click Edit in the Operation column for the simple service or operation that you want to delete.
  4. Click Delete.
  5. Click OK on the confirmation page.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Delete a Service with Operations

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Deleting a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking
    expand button
  2. Click Details against Services in the Objects column for the server that owns the service you want to delete.
  3. Click Delete to the left of the row containing the service with operations that you want to delete. You see a page summarizing what you have requested.
  4. If you want to delete the packages associated with the operations, check Delete associated packages.
  5. Click OK.
Note:

When you delete a service, you are removing the service object from the Directory Server repository; the actual deployed files that make up the service are not deleted. For information on deleting old deployed files, see the link in Related Topics.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Edit a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Changing the properties of a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server you want to edit.
  3. Click Edit in the Operation column for the service that you want to edit.
  4. Update the attributes of the service as required.
  5. Click OK.
Note:

If you make any changes to the listener or listeners, request handler or package associated with the service, the changes take effect immediately, not when you click OK.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Switch Logging On for a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Objects column for the server that owns the service for which you want to switch logging on.
  2. Click Edit in the Operation column for the service for which you want to switch logging on.
  3. Check Logging.
  4. Click OK.
Note: The effect of switching logging on is that the service's request and response blocks are written to a diagnostics file each time the service is invoked. This file is stored in the server's system directory, which defaults to %USERPROFILE%\Documents\Micro Focus User\Visual COBOL\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).

You can format and view the information from the Edit Server > Diagnostics > ES Console page. The client request is shown in a block named user-storage-type under the part of the dump entitled CAS-REQ. The server response is shown in a similar block under the title CAS-RESP.

Only switch logging on if you need diagnostics as it degrades performance.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To View Services for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server for which you want to view services.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


Configuring Implementation Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An implementation package defines the application that provides the business functionality.

  • The Packages Table
  • Configuring Packages
  • Configuring Request Handlers
Parent topic: Deploying and Configuring Modernized Applications


The Packages Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for packages by clicking Details next to Packages in the table of servers on the Home page. The packages table is shown below.

Figure 1. Packages Table
Packages Table

The information is as follows:

  • Name – this is unique in an enterprise server
  • Current status
  • Status log – this supplies information about the most recent event that occurred on this package
  • Package module – the name of the library containing the package, if it is part of a library
  • IDT – the name of the interface definition table (IDT) for this package
  • Package path – the location of the package module
  • Custom configuration data - this field is not used
  • Description
Parent topic: Configuring Implementation Packages


Configuring Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a package
  • Change the status of a package between available and unavailable
  • Associate a package with a service
  • Disassociate a package from a service

If you have Add/Delete permission level or higher you can also:

  • Add a package to an enterprise server
  • Delete a package, as long as it is not associated with any service

Outside Enterprise Server Administration, you can delete old deployment directories.

  • To Add a Package to an Enterprise Server Instance
  • To Delete a Package
  • To Edit a Package
  • To Disassociate a Package from a Service
  • To View Packages for an Enterprise Server Instance
  • To Delete Old Deployed Package Files
Parent topic: Configuring Implementation Packages


To Add a Package to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Specify a name for the package in Name.
  4. Choose a status from the list in Status.
  5. If the entry point that exposes this service is in a library that has a different name than the package itself, specify the name of the library in Module Package. Include the extension; library files have the extension .lbr or .so.
  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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab to display the packages for the enterprise server instance.
  3. Click Edit to the left of the row containing the package that you want to delete.
  4. Click Delete for the package.
  5. Click Delete on the confirmation page.
Note:
  • You can also delete a package by using the mfpackage command.
  • You cannot delete a package if it is associated with any service.
  • When you delete a package, you are removing the package object from the Directory Server repository; the actual deployed files that make up the package are not deleted.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Edit a Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click Edit to the left of the row containing the package that you want to edit.
  3. Update the attributes of the package as required.
  4. Click Apply.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Disassociate a Package from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Click Edit to the left of the row containing the service from which you want to disassociate the package.
  4. In Available Packages click the package that you want to replace the currently associated package.
  5. Click Select Package.
Note:

A service can have just one package associated with it.

Parent topic: Configuring Packages
Parent topic: Work with Packages


To View Packages for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab to display the packages for the enterprise server instance.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Delete Old Deployed Package Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
Use this procedure with great care. Be sure that you are deleting the correct directory, and delete the service containing the packages from the Directory Server repository before you delete the old package files.
  1. Go to the Deploy folder of the enterprise server to which the service was deployed. By default this is $COBDIR/deploy. Here you will find several directories with names of the form: service-name.random-string where service-name is the name of the service supplied during the creation of the service interface, and random-string is a string of random characters generated by the deploy process.
  2. Identify the directory that you want to delete; the date and time of creation of the directory are probably the best guide.
  3. Right-click the directory and click Delete on the popup menu.
Parent topic: Configuring Packages
Parent topic: Work with Packages


Configuring Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A request handler is software that receives a client request for access to the service, and translates the request into a form that the application providing the business functionality can understand. The following request handlers are provided with Enterprise Server :

  • MFRHSOAP – handles requests that use SOAP (Simple Object Access Protocol). These are requests for Web services. They are coded in XML.
  • MFRHBINP – handles binary requests made by the Micro Focus J2EE connector.
  • MFRHJSON - handles REST requests that use JSON content bodies.
  • The Request Handlers Table
  • Configuring Handlers
Parent topic: Configuring Implementation Packages


The Request Handlers Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for request handlers by clicking Details against Request Handlers in the table of servers on the Home page. The request handlers table is shown below.

Figure 1. Request Handlers Table
Request Handlers Table

The information is as follows:

  • Module name
  • Module path
  • Current status
  • Status log – this supplies information about the most recent event that occurred on this request handler
  • Custom configuration data - this field is not used
  • Description
Parent topic: Configuring Request Handlers


Configuring Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a request handler
  • Change the status of a request handler between available and unavailable
  • Associate a request handler with a service
  • Disassociate a request handler from a service

If you have Add/Delete permission level or higher you can also:

  • Add a request handler to an enterprise server instance
  • Delete a request handler. You cannot delete MFRHBINP
  • To Add a Request Handler to an Enterprise Server Instance
  • To Edit a Request Handler
  • To Associate a Request Handler with a Service
  • To Disassociate a Request Handler from a Service
  • To Delete a Request Handler
  • To View Request Handlers for an Enterprise Server Instance
Parent topic: Configuring Request Handlers


To Add a Request Handler to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server you want to add the request handler to.
  3. Click Add.
  4. Specify a name for the request handler in Module Name.
  5. Specify a full pathname for the request handler in Module Path.
  6. Choose a status from the list in Status.
  7. Ignore Configuration Information; this field is not used.
  8. Specify a text description of the request handler in Description (optional).
  9. Click Add.
Note:

You can also reach the Add Handler page by clicking Edit to the left of the server to which you want to add the handler, clicking the Handlers tab and clicking Add.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Edit a Request Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the request handler you want to edit.
  3. Click Edit to the left of the row containing the request handler that you want to edit.
  4. Update the attributes of the request handler as required.
  5. Click OK.
Note:

Any changes that you make only affect the request handler object that the current server owns. Request handler objects of the same name in other enterprise servers are unaffected.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Associate a Request Handler with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button.
  2. Click Details against Handlers in the Objects column for the server that owns the service with which you want to associate the request handler.
  3. Click Edit to the left of the row containing the service that you want to associate the request handler with.
  4. In Available Request Handlers click the request handler that you want to associate with the service.
  5. Click Select Handler.
Note:

A service can have just one request handler associated with it.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Disassociate a Request Handler from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the service from which you want to disassociate the request handler.
  3. Click Edit to the left of the row containing the service from which you want to disassociate the request handler.
  4. In Available Request Handlers click the request handler that you want to replace the currently associated request handler.
  5. Click Select Handler.
Note:

A service can have just one request handler associated with it.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Delete a Request Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the handler you want to delete.
  3. Click Edit to the left of the row containing the request handler that you want to delete.
  4. Click Delete.
  5. Click OK on the confirmation page.
Note: You cannot delete a request handler if it is associated with any service. You cannot delete the MFRHBINP request handler.
Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To View Request Handlers for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server for which you want to view request handlers.
Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


Enterprise Server Task Index

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • Accessing the Enterprise Server Administration UI
  • Accessing the ESMAC User Interface
  • Administer a Server Using ESMAC
  • Configure the Directory Server
  • Deploy to Java EE Application Servers
  • Log On and Off
  • Monitor Directory Server
  • Start and Stop the Directory Server
  • Work with Communication Processes and Service Listeners
  • Work with Packages
  • Work with Request Handlers
  • Work with Servers
  • Work with Services
  • Work with the Directory Server Repository
  • WebSphere MQ
Parent topic: Deploying to Enterprise Server


Accessing the ESMAC User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use the Enterprise Server Monitoring and Control (ESMAC) user interface to monitor and control the enterprise server instances that your installation is running. From the ESMAC user interface, you can monitor and control all aspects of each enterprise server instance.

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details..

    The Details screen for the server is displayed.

  4. On the Details screen, click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

Parent topic: Enterprise Server Task Index


Administer a Server Using ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Change the Trace Dataset
  • To Configure Dumps
  • To Create an ESMAC User
  • To initiate a system dump
  • To stop or kill a SEP
  • To Monitor Services
  • To Record Service Input and Output
  • To specify what information is traced
  • To Start ESMAC for an enterprise server instance
  • To Transfer the In-memory Trace Data to the Auxiliary Dataset at Rollover
  • To View a Dump
  • To View a Local Trace for a Client Process
  • To View a Local Trace for a SEP
  • To View a System Trace
Parent topic: Enterprise Server Task Index


To Create an ESMAC User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: This procedure is supported for backward compatibility only.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To create an ESMAC user:

  1. Click Users.

    The Users page is displayed

  2. Click New.

    The CICS SNT page is displayed.

  3. In the field Name, enter the name to be used by this user when logging in.
  4. Optionally, you can enter a short description for the user; enter it in the field Description.
  5. In the field Password, enter a password for the user.
  6. In the field Repeat PW, re-enter the password. This ensures that you type the password correctly.
  7. If you want the password always to be entered in upper case, check Upper case.
  8. In the field Operator ID, enter an operator ID for this user. This is optional.
  9. In the field Timeout, enter a timeout period, in minutes, for this user. This is optional.

    If the user does not interact with ESMAC for more minutes than defined in this field, security permissions revert to the default permissions.

  10. To set what aspects of a server and its definitions a user can change:
    1. Check Yes in the Definition Access group
    2. Click on the required dropdown, and select one of:
      • No - the user cannot read or update the selected definition
      • Upd - the user can read and update the selected definition
      • Rd - the user can read the selected definition

    By default, the user cannot read or update definitions; that is, the Definition Access, Yes check box is unchecked, and all definitions are set to No.

    If you set the definitions to Rd or Upd, these only have an effect if the Definition Access, Yes check box is checked.

    To set all definitions to No, Upd or Rd, click the all dropdown and select No, Rd or Upd, respectively.

  11. Click Add.

    The user is added to the list of users. The CICS SNT page is redisplayed, enabling you to change any details for this user.

Note:

You can ignore the controls Group prefix, Oper Class, and those for resource keys, security keys, and surrogate security keys.

Parent topic: Administer a Server Using ESMAC
Related information
To start ESMAC for a server
To monitor services
To configure dumps
To view a dump
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To view a system trace
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server


To stop or kill a SEP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can stop or kill a service execution process (SEP).

If you stop a SEP it will stop when the SEP has completed the current task. Stopping a SEP is most useful if t is a SEP with a debugger attached.

Killing stops the SEP when it is currently running a task. If the task terminates prior to the kill process being initiated, ESMAC returns a message explaining that the target task was no longer active.

Note: After stopping a process, Enterprise Server will automatically replace the SEP to keep the configured number of SEPs - unless it is a debug SEP or a SEP that was started from the command prompt. In these cases it will stop the SEP but not replace it.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To stop or kill a SEP

  1. Click SEPs in the menu.
  2. Click Stop next to the SEP.

To kill a SEP

  1. Click SEPs in the menu.
  2. Click Kill next to the SEP.
Parent topic: Administer a Server Using ESMAC
Related information
To shut down a server
To view a local trace for a SEP


To Transfer the In-memory Trace Data to the Auxiliary Dataset at Rollover

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To transfer the in-memory trace data to the auxiliary dataset at rollover

  1. Click Control.

    The Control page is displayed.

  2. Check Active Trace DS, active
Note:

By default, the enterprise server uses the A dataset to record trace information.

Parent topic: Administer a Server Using ESMAC


Configure the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Configure the MF Directory Server
  • To Run casperm
Parent topic: Enterprise Server Task Index


To Configure the MF Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Configure > Options on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Update the attributes of the Directory Server as required.
  3. Click OK.
Note:

If you check Restricted under User Access, as soon as you click Apply you will be asked for a valid user ID and password with at least Administrator permission level, which you must provide to continue working.

Parent topic: Configure the Directory Server


To Run casperm

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Log in as root.
  2. Set COBDIR to the location of the installed product.
  3. Enter:
    casperm.sh

    You see a message asking you to ensure you have the alphanumeric user ID of the Enterprise Server System Administrator to hand. This becomes the Process User ID.

    You then see the message:

    Do you want Error and Warning messages to be displayed via the syslog daemon (y/n)?

    The console messages are always directed to the file console.log. Responding Y to this prompt will also direct them to the syslog daemon as Info type messages.

  4. Enter Y or N.

    You then see the message:

    Enter the alphanumeric user ID of the Enterprise Server System Administrator.
    Press return to use (hub):

    This is the user id which will be the owner of all Enterprise Server processes with the exception of the Directory Server, which must run as root. It is known as the Process User ID. When an enterprise server is started from the Administration Server Administration it will run under this user ID. Since all the server's processes will run with this user's authority this has implications for file creation and access. The Directory Server has to run as root because the Directory Server process (Enterprise Server Administration) uses port 86. This port is only accessible to processes running with root authority.

  5. Enter the Process User ID or press Enter to use the default value.

    You then see the message:

    Enter the directory where you want the Enterprise Server
 run-time system files to reside. Please enter the absolute path.
 Do not use environment variables. Press return to use (/var/mfcobol/es):

    You should take the default unless you have a good reason not to.

    The directory given here will be the root for the working directory for all enterprise servers run in this installation. A new directory will be created for each server the first time it is run and a number of files will be created in this location including the console.log file and diagnostics files. It is imperative that the Process User ID has create and write permissions in this directory.

  6. Press Enter to accept the default or enter the directory you want to use.

    The script executes and processes the settings you entered above. Once complete, it displays the following message:

    Processing –f option...

    Then the command terminates.

Parent topic: Configure the Directory Server


Deploy to Java EE Application Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Deploy to WebSphere
  • To Deploy to WebLogic
  • To Deploy to JBoss
  • To 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable tracing

Before starting WebSphere, you can optionally configure it to enable tracing. Do this in WebSphere by adding trace to the custom properties on the Resource Adapters > Micro Focus Cobol Adapter (NoTx) > J2C connection factories > CCIMFCobol_v1.5 < Custom properties page. See your WebSphere documentation for details.

To start WebSphere server

  1. Log in as WebSphere administrator. See the WebSphere documentation.
  2. Run the startup script by entering the following command from the bin directory of your WebSphere installation:
    startserver.sh myServer

To start WebSphere administrative console

  1. Start WebSphere server and WebSphere Administrative Console.
  2. In the left pane click Resources > Resource Adapters
  3. Click Install RAR on the page on the right, and follow the instructions on the screen.

    When you are asked for the resource adapter file, specify the required mfcobol*.rar file.

  4. The new resource adapter is now listed on the right. Click it to display its properties.
  5. Add a connection factory for the resource adapter. You might need to scroll to Additional Properties at the end and then click J2C Connection Factories. Then click New and follow the instructions on the screen to specify:
    • CCIMFCobol_v1.5 as the reference name for the connection factory
    • eis/MFCobol_v1.5 as the JNDI name for the connection factory
  6. Confirm that the new resource adapter is now listed on the right.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If you have not set up a WebLogic server domain, set one up using the WebLogic Domain Configuration Wizard, following the instructions in the wizard. You can start the wizard from the Start menu.
  2. If your COBOL system (either Visual COBOLor COBOL Server) is installed in a location that uses a spacey path, you need to copy the following files to a non-spacey location:
    mfcobolpure.jar
    Located in the $COBDIR/lib directory by default.
    mfconnector.jar
    Located in the subdirectory of $COBDIR/javaee/javaee7 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.sh , and is located in your domain's bin directory of your WebLogic installation.
  4. Go to the end of the file.
  5. Above the line # START WEBLOGIC that starts the WebLogic server, add the following lines:
    JAVA_HOME=jdk_path
export JAVA_HOME
MF_HOME=mfcobolpure_path
export MF_HOME
CLASSPATH=$JAVA_HOME/lib/tools.jar:
          $MF_HOME/mfconnector_path/mfconnector.jar:
          $MF_HOME/mfcobolpure.jar
export CLASSPATH

    Where:

    • jdk_path is the location of the JDK installation to use for WebLogic.
    • mfcobolpure_path is the path containing mfcobolpure.jar.
    • mfconnector_path is the path containing the required mfconnector.jar. If you have copied this jar into the same directory as mfcobolpure.jar, you don't need to specify this path.
  6. Save the file.
  7. You can now run the startup script.

To start WebLogic

  1. Set up a WebLogic server domain and edit the startup script, if you have not already done so.
  2. Change directory to your WebLogic server domain directory.
  3. As root user, run the startup script by typing:
    startWebLogic.sh

To start WebLogic server console:

  1. Start WebLogic.
  2. Open a browser.
  3. Enter the URL, http://localhost:7001/console where 7001 is the default port for the server console.

To deploy a resource adapter to WebLogic

  1. Start WebLogic server and the WebLogic Server Console.
  2. In the left pane of WebLogic Server Console, expand your-domain >Deployments>Connectors
  3. Click Configure a new Connector Component and follow the steps on the page. When you are asked to upload the resource adapter file, upload the required mfcobol*.rar file.

    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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.

JBoss EAP 7.1
  • Run jboss_home/bin/standalone.bat to start it.
  • Run jboss_home/bin/jboss-cli --connect command="shutdown to stop it.

Deploying the Resource Adapter

JBoss EAP 7.1
To deploy a resource adapter for JBoss EAP 7.1, 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.

JBoss EAP 7.1
Copy the application .ear file from the directory my-project/repos/my-service.deploy/my-service.ear into your JBoss deployment directory which is, by default, jboss_home/standalone/deployments.

Logging

JBoss EAP 7.1
JBoss stores log files and traces by default in jboss_home\standalone\log\server.log.

Configuring a JDBC Data Source for XA Transactions

If the application being deployed connects to a third-party database, you need to configure a JDBC data source and specify information such as the JNDI name of the data source.

JBoss EAP 7.1
Add a data source to the standalone.xml file.

For full details see the JBoss administration documentation on configuring JDBC data sources.

Further Information

For further information, see the Release Notes for your JBoss Application Server installation and the JBoss Web site.

Parent topic: Deploy to Java EE Application Servers


To deploy to Tomcat

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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. 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
Parent topic: Deploy to Java EE Application Servers


To Create an .ear File for your EJB

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have generated a client and EJB together, they are automatically packaged into an enterprise archive file (.ear) and you do not need to do this. Otherwise:

  1. Package the EJB's .jar file into an .ear for your application. To do this use a jar command similar to the following:

    jar -cvf myApplication .ear myService.jar

    If you have a client .war file you can add that to the .ear file in the same way.

  2. Create a deployment descriptor application.xml either using your application server's tools or by copying and editing a sample, as follows:
    1. Locate a sample .ear, which is in examples directory in mapdemo/mapdemo/repos/myService.deploy/JMapServ-WL.ear
    2. Extract the descriptor application.xml from the .ear file, using the following jar command:
      jar -xvf JMapServ-WL.ear META-INF/application.xml
    3. Make a copy of the application.xml descriptor and edit it, replacing JMapServ with the name of your .jar file. You can also add the name of your .war file if you added that to the .ear file.
    4. Put the descriptor in the meta-inf subdirectory of the directory containing your .ear file.
    5. Package the descriptor into your .ear file using a jar command similar to:
      jar -uvf myService.ear META-INF/application.xml
Parent topic: Deploy to Java EE Application Servers


To Add Micro Focus Support for EJBs

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Locate the file mfejblib.jar, which contains the Micro Focus support for EJBs.

    Specific versions of this file are supplied for each supported application server and J2EE version. They are available in the following subdirectories under $COBDIR/javaee/javaee7 :

    • ibmwebsphere90
    • jboss71EAP
    • oracleweblogic1221
  2. Copy mfejblib.jar to the root directory of your enterprise archive file (.ear). By default, the mfejblib.jar belongs in the root because the classpath is set to this in the EJB's manifest.mf file.

    If you copy mfejblib.jar to a different directory, you need to change the classpath in the manifest.mf file in the EJB's .jar file, which is in myservice/Repos/myservice.deploy .

  3. Add the mfejblib.jar file to the archive file that you want to deploy.

    For most application servers, you can do this using their administrative tools. Alternatively, you can use a jar command similar to the following:

    jar -uvf myApplication .ear mfejblib.jar

Parent topic: Deploy to Java EE Application Servers


To add support for Micro Focus resource adapters

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Locate the appropriate mfcobolpure.jar and mfconnector.jar files. These files contain the classes that support the Micro Focus resource adapters. They are provided in the following locations by default:
    mfcobolpure.jar
    $COBDIR/lib
    mfconnector.jar
    Subdirectories of that correspond to supported application servers as follows:
    • ibmwebsphere90
    • jboss71EAP
    • oracleweblogic1221
  2. Update the classpath to point to the mfcobolpure.jar and mfconnector.jar archive files using one of the following methods:
    From the IDE
    CLASSPATH=$COBDIR/lib/mfcobolpure.jar:jar_path/mfconnector.jar:$classpath

    where jar_path is the path to the archive files appropriate to your application server.

Parent topic: Deploy to Java EE Application Servers


To Deploy a Micro Focus Resource Adapter to a Java Application Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 COBOL Server or Visual COBOL is installed.

  2. Specify the resource adapter to deploy. These can be one of the following:
    • mfcobol-notx.rar - does not support transactions
    • mfcobol-localtx.rar - supports local transactions
    • mfcobol-xa.rar - supports XA transactions

    Specific versions of these files are supplied for each supported application server and Java version. They are supplied with your Visual COBOL installation under $COBDIR/javaee/javaee7 by default, as follows:

    • ibmwebsphere90
    • jboss71EAP
    • oracleweblogic1221
  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 COBOL Server Web Services and J2EE listeners.
    Valid value: The port number used by COBOL 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 COBOL 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 COBOL Server waits before closing a socket

    Default: 72
Parent topic: Deploy to Java EE Application Servers


Log On and Off

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Log On to Enterprise Server Administration
  • To Log Off from Enterprise Server Administration
Parent topic: Enterprise Server Task Index


Monitor Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To View the Sessions List
  • To View the Journal
  • To View and Use Remote Directory Server Instances
  • To View Directory Server Statistics
  • To export the journal as a text file
  • To Delete Journal Entries
  • To Configure Run-time Core Dumps
Parent topic: Enterprise Server Task Index


Start and Stop the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
Parent topic: Enterprise Server Task Index


Work with Communication Processes and Service Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Service Listener to an Enterprise Server Instance
  • To Associate a Listener with a Service
  • To 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 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


Work with Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Package to an Enterprise Server Instance
  • To Edit a Package
  • To Associate a Package with a Service
  • To Disassociate a Package from a Service
  • To View Packages for an Enterprise Server Instance
  • To Delete a Package
  • To Delete Old Deployed Package Files
Parent topic: Enterprise Server Task Index


Work with Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Request Handler to an Enterprise Server Instance
  • To Edit a Request Handler
  • To Associate a Request Handler with a Service
  • To Disassociate a Request Handler from a Service
  • To View Request Handlers for an Enterprise Server Instance
  • To Delete a Request Handler
Parent topic: Enterprise Server Task Index


Work with Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add an Enterprise Server Instance
  • To Define an XA Resource (XAR) for an Enterprise Server Region
  • To Change the Number of ES licenses
  • To Change the Number of SEPs
  • To Copy an Enterprise Server Instance
  • To Create and View a Diagnostic Dump for an Enterprise Server Instance
  • To Delete an Enterprise Server Instance
  • To Delete an XA Resource
  • To Delete a CCI Server
  • To Edit an Enterprise Server Instance
  • To Edit an XA Resource
  • To Enable or Disable an XA Resource
  • To start an enterprise server instance
  • To stop a server Instance
  • To View the Communications Console Log for an Enterprise Server Instance
  • To View the Enterprise Server Log Files
  • To View the Control Page for an Enterprise Server Instance
Parent topic: Enterprise Server Task Index


To Create and View a Diagnostic Dump for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Home page click Edit to the left of the server whose console log you want to view.
  2. Click the Diagnostics tab.
  3. Click the Dump tab.
  4. Click Create Dump.

    The page is refreshed showing a table of dumps with one row for the dump you just created.

    Note:

    Create Dump is only available when the server is started.

  5. Click Show against the dump you just created. You briefly see a console window, then the dump file overwrites the contents of the Dump page.
  6. When you have finished viewing the dump, click Datasets to return to the Server > Diagnostics > Dump page.
Parent topic: Work with Servers


To View the Communications Console Log for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration Home page click Edit to the left of the server whose communications console log you want to view.
  2. Click the Diagnostics tab.
  3. Click the CS Console tab.
  4. To view the entire log since the server was started, click Show Entire Log. The log opens in a new Web browser window. To return to ESMAC, click Back in your browser.
Parent topic: Work with Servers


To View the Control Page for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • In the Enterprise Server Administration screen, click Details in the Current status column of the enterprise server instance you want.
    Note:

    You can click Details only if the status of the Server is "Started".

Parent topic: Work with Servers


Work with Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To View Services for an Enterprise Server Instance
  • To Add a Service to an Enterprise Server Instance
  • To Edit a Service
  • To Change the Status of a Service
  • To Switch Logging On for a Service
  • To Add a Service for Integration with the Micro Focus Development Tools
  • To Delete a Service with Operations
  • To Delete a Simple Service or an Operation
Parent topic: Enterprise Server Task Index


Work with the Directory Server Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Import a Repository
  • To Export the Repository
  • To Restore the Repository
  • To Delete the Repository
Parent topic: Enterprise Server Task Index


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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Copy the supplied file CSQ4TRMN.JCL to an appropriate location. This file can be found in the $COBDIR/src/enterpriseserver/ims/mq 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: WebSphere MQ


To stop a WebSphere MQ trigger monitor

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Copy the supplied file CSQ4STOP.JCL to an appropriate location. This file can be found in the $COBDIR/src/enterpriseserver/ims/mq 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: WebSphere MQ


To generate a PSB for a Trigger Monitor

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Copy the supplied file CSQ4TRMN.PSB to an appropriate location. This file can be found in the $COBDIR/src/enterpriseserver/ims/mq folder.
  2. At a command prompt enter the following command:
    mfims psbgen csq4trmn.psb nocls echo(enderr,0,55)
Parent topic: WebSphere MQ


To create an XA resource for a trigger monitor

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Follow the steps in the topic To define an XA resource (XAR) for an enterprise server region using the following properties:

For one-phase commit transactions
ID | MQXA
Name | MQSERIES
Module | DFHEIBMQ
Open string | TPM=ESCICS,AXLIB=casaxlib,QMNAME=queue manager name
Enabled | checked

Example

TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
Parent topic: WebSphere MQ
Related tasks
To Define an XA Resource (XAR) for an Enterprise Server Region


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: 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: 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: 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: 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: 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: WebSphere MQ


Enterprise Server Reference

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • Administration and Configuration Commands
  • Enterprise Server Error Messages
  • User Exits
  • MQ Listener and Writer Types
    Describes MQ listener and writer types used by COBOL Server.
Parent topic: Deploying to Enterprise Server


Administration and Configuration Commands

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following commands are available for performing Enterprise Server administration procedures.

  • 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.
  • casperm.sh
    Prepares Enterprise Server for use.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
  • fixcat
    A UNIX shell executable file (.sh) 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 UNIX shell executable file (.sh) that rebuilds corrupt spool control files.
Parent topic: Enterprise Server Reference


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.

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


fixcat

A UNIX shell executable file (.sh) that rebuilds a corrupt catalog.dat file.

Syntax:

fixcat.sh 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:

mv /myFiles/CATALOG.DAT /myFiles/CATALOG.DAT.bkup
fixcat.sh /myFiles/CATALOG.DAT.bkup /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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfdepinst command handles the server-side part of the process of deploying a service to 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 myservice.car

Parameters:

myservice.car
The name of the .car file containing the service to be deployed.

Dependencies:

Before running mfdepinst, copy the .mfdeploy file in the $COBDIR/deploy to the parent directory of the directory that contains the .car file.

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.

Run mfdepinst from a Visual COBOL command prompt from the same directory that contains the .car file.

Comments:

The mfdepinst command extracts files from the .car file and installs them on the enterprise server specified in the .mfdeploy file.

mfdepinst records its progress in the file deploylog.txt in the current directory, overwriting any existing deploylog.txt. After mfdepinst completes, you can examine this file to find out if deployment succeeded.

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 Visual COBOL 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax for starting or stopping the Directory Server:

mfds [/d|/dn network-address|/n network-address] [/j journal-path] [/r] [/p port-number]

Syntax for stopping the Directory Server:

mfds [/p port-number] -s option [username password]

Syntax for reporting and exporting information:

mfds /v
mfds /m
mfds /e root-DN user-partition-DN group-partition-DN
          resource-partition-DN schema-format ldif-filename
          sec-path
mfds /l [schema partition Distinguished Name] option ldif-filename [schema-version-1] [schema-version-2]

Syntax for exporting the currently active MFDS process repository to a specified path:

mfds -x [repository type] [repository address] [server name] <options> <user id> <password>

Examples:

"mfds -x 1 c:\myrepository *"
"mfds -x 1 c:\myrepository * S"
"mfds -x 1 c:\myrepository * O"
"mfds /x 1 c:\myrepository * SO"
"mfds /x 1 c:\myrepository ESDEMO"
"mfds /x 1 c:\myrepository ESDEMO D myid mypwd"

Syntax for creating a readable journal file from a binary journal file:

mfds /t output-filename input-filename
Note:

If output-filename is not specified, a default file of journal.txt will be created in the same directory as the input-filename

If input-filename is not specified, the default journal.dat file as specified by the default MFDS options file (mfdsacfg.dat) will be used.

This option can only convert journal.dat files to text if they have originated on the same hardware and software platform; it is not guaranteed that journal files imported from UNIX can be read by Windows and visa versa.

Syntax for secure access to MFDS:

mfds /b

Use this startup option to block anonymous read access to the MFDS ES configuration data. If this option is specified, applications that connect to the MFDS process to query ES 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.

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:

/d
Show debug information; this is a record of activity on the Directory Server that can be useful when investigating problems
/dn network-address
Show debug information and bind to the specific network adapter at network-address, where network-address can be either the IPv4 address or the hostname.
/e root DNuser partition DNgroup partition DNresource partition DNschema formatldif-filenamesec-path
Export Directory Server users and groups from the MF Directory Server repository to an LDIF file:
  • root-DN

    The application partition to which all of the exported entries will be assigned.

  • user-partition-DN

    The name of the container within the application partition to which the exprted users will be assigned.

  • group-partition-DN

    The container within the application partition to which the exported groups will be assigned.

  • root-DN

    The container within the application partition to which the exported resource definitions will be assigned.

  • schema-format

    Values: 1 = Active Directory (Default).

  • sec-path

    The location of the MF Directory Server repository.

/j directory-path
Override the journal path. Journal data will be written to the filesystem directory that you specify. For example: mfds /j e:\journal
/l [schema partition Distinguished Name] optionldif-filename [schema-version-1] [schema-version-2]
Export the schema extensions that an LDAP server will require to support Micro Focus applications.
  • schema partition Distinguished Name

    Specifies the DN of the partition in the Directory Information Tree where the schema definition is held. The schema partition holds, amongst other things, attributeSchema and classSchema objectclass instances.

  • option

    Specifies the target directory server type: 0 = Microsoft Active Directory Application Mode (ADAM), 1 = Active Directory (Default), 2 = OpenLDAP, 3 = Sun Directory

    Note:

    If you specify the ldif-filename , you must also specify a value for this parameter.

  • ldif-filename

    Specifies the name of the destination file.

    Default: mfds_schema_[ mfds version ].ldf (e.g. mfds_schema_1.05.09.ldf)

  • schema-version-1

    Specifies the version of the schema extensions to be generated: 0 = current schema version (Default). Numbers greater than 0 specify older schema versions.

  • schema-version-2

    This option is used for upgrading from a previous schema. If schema-version-2 is specified and is less the schema-version-1, the output file is a delta between the schema-version-1 and schema-version-2.

    If schema-version-2 is greater than or equal to schema-version-1, this option is ignored.

/m
Display the location of the Directory Server repository.
/n network-address
Bind to the specific network adapter at network-address, where network-address can be either the IPv4 address or the hostname.
/p port-number
Bind to a non-standard port.
Note:

Many programs depend on Directory Server using the default port (86). Therefore, if you use an alternative port, you may experience interoperability problems.

You should also consider carefully before using this option to run more than one Directory Server on the same machine. By default, both would use the same options file and repository, and might therefore encounter conflicts.

/r
Refuse access to the Enterprise Server Administration interface.
/s option [usernamepassword]
Request a controlled shutdown of a Directory Server and optionally the associated enterprise servers. If the Directory Server is not using the default port, the /p option must be used to specify the port that is being used.
Option:
  • Value 1: Shutdown the Directory Server only
  • Value 2: Shutdown the Directory Server and any associated enterprise servers.

Username and password: These must be supplied if the Directory Server is running with Restrict administration access checked.

/v
Show version information for Directory Server
/x [repository type]
1 = file:///
5 = XML
[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]
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.

Comments:

The command to start the Directory Server can be inserted into your startup shell script; then the Directory Server will be started automatically when the machine is started. The mfds command must be inserted after the command to start up TCP/IP, because Directory Server needs TCP/IP to be running. If the command has been added to your startup shell script you would normally need to start the Directory Server only if you performed a shutdown since you started the machine.

Note: Issuing an mfds command with any of the parameters /e, /l, /m, /v does not start the Directory Server.

On UNIX you should use a dash (-) before a parameter as an alternative to a forward slash (/).

Parent topic: Administration and Configuration Commands


mfpackage

This utility is used for maintaining services and packages installed on an enterprise server. Its function is to delete all services and packages in a given namespace for a given enterprise server region, and is equivalent to deleting the services and packages using the Micro Focus Administration Console (MFDS). It can also be used to prepare the server before deploying a new version of the service..
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

mfpackage [options] command service-namespace [parameters]

Parameters:

command | undeploy. Deletes the services and packages in the supplied namespace.
options | -m URL | host | Directory. Supported URL schemes are "file", "mrpi", and "ldap". Default is MFDS on the local system using the default port (equivalent to mrpi://localhost:86).
 | -s server | Operates on packages and services for this server. Required for undeploy.
 | -p password | Optional password for binding to directory.
 | service- namespace | The namespace for the services and packages. For a web service, this is everything before the "#" character in the service/package name. For a J2EE service, it is everything before the final "." character.

Example:

mfpackage -m mrpi://localhost -s ESDEMO undeploy http://tempuri.org/wmapserv
Parent topic: Administration and Configuration Commands


SPLREPAIR

A UNIX shell executable file (.sh) 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.sh 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.sh /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
Related information
Enterprise


Client Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists the messages that clients of Enterprise Server can display.

Error number | Meaning
-1 | Error status is unknown
0 | Success
00001 | Internal error in common client
00002 | Feature has not been implemented
00003 | Unsupported protocol version or feature
00004 | Requested object not found (in Directory Server repository)
00005 | Not used
00006 | Error in parameters to function
00007 | Resource unavailable, for example, memory allocation failed
00008 | Communications error
00009 | Object is in wrong state for operation
00010 | Bad data problem (for example, non-HTTP response to HTTP request)
00011 | Operating system error
00012 | An external component failed (for example MLDAP unable to bind to Directory Server)
00013 | Data was truncated
00014 | No data was available, possibly because the server was not available
00015 | Client request timed out
00016 | Requested service is not available
00017 | No user data was returned by the server
00100 | Invalid IDT version
00101 | Invalid message type
00102 | Servicename not found in IDT
00103 | Unsupported mapping
00150 | Unable to initialise request handler
00151 | Unable to initialise interface mapper
00250 | Unable to initialise SOAP parser
00400 | Invalid binary protocol version
00401 | Unrecognised binary protocol message
00402 | Program/entry point not found
00450 | Invalid namespace for SOAP envelope
00451 | Invalid namespace for SOAP header
00452 | Invalid namespace for SOAP body
00453 | Invalid SOAP message
00454 | No SOAP URI in SOAP message
00455 | SOAP action URI differs from SOAP Body URI
00456 | Unable to resolve href in SOAP message
00457 | Unrecognised encoding style
00458 | Illegal character in SOAP string
00500 | Parameter not found in IDT
00501 | External data not located
00502 | Invalid implementation language
00503 | Unsupported mapping
00504 | Expected mapping not defined
00505 | Invalid ODO item
00506 | Invalid structured mapping
00507 | Insuffient subscripts for external item
00508 | Subscript for external item does not exist
00509 | Too many subscripts for external item
00510 | Error in exit handler
00600 | External field not found
00601 | Unsupported external data type
00602 | Expected parameter not supplied by external interface
00603 | Expected external structure field not found
00604 | Expected external array field not found
00605 | Incorrect number of parameters supplied
00606 | Incorrect number of fields in supplied structure
00607 | External data type mismatch
00608 | Unknown external data type
00609 | Incorrect number of array elements
00610 | Too many array elements passed in message
01400 | HTTP response: bad request
01401 | HTTP response: unauthorized
01403 | HTTP response: forbidden
01404 | HTTP response: not found
01405 | HTTP response: method not allowed
01406 | HTTP response: not acceptable
01407 | HTTP response: proxy authentication required
01408 | HTTP response: request timeout
01409 | HTTP response: conflict
01410 | HTTP response: gone
01411 | HTTP response: length required
01412 | HTTP response: precondition failed
01413 | HTTP response: request entity too large
01414 | HTTP response: request-URI too long
01415 | HTTP response: unsupported media type
01416 | HTTP response: requested range not satisfiable
01417 | HTTP response: expectation failed
01500 | HTTP response: internal server error
01501 | HTTP response: not implemented
01502 | HTTP response: bad gateway
01503 | HTTP response: service unavailable
01504 | HTTP response: gateway timeout
01505 | HTTP version not supported
02000 | SOAP response fault
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists the messages that the Directory Server can display, and gives an explanation or advice or both for those that are not self-explanatory.

Format of Messages

The Directory Server displays messages in the status line in the format:

MDSnnnns message-text

where MDS stands for Micro Focus Directory Server and the variables are:

nnnn | A four-digit message number
s | One of the following severity codes: I Information only; no action is required W Warning: the action you attempted succeeded but with results that you need to be aware of E Error: the action you attempted failed
message-text | The text of the message

Messages with the severity E (for Error) appear in red.

  • Directory Server Error Messages 0 to 20
    Lists the Directory Server error messages from 0 through to 20
  • Directory Server Error Messages 21 to 40
    Lists the Directory Server Error Messages 21 to 40
  • Directory Server Error Messages 41 to 60
    Lists the Directory Server Error Messages, 41 to 60
  • Directory Server Error Messages 61 to 80
    Lists the Directory Server Error Messages 61 to 80
  • Directory Server Error Messages 81 to end
    Lists the Directory Server Error Messages 81 to the last error message in the range.
Parent topic: Enterprise Server Error Messages
Related information
Enterprise


Directory Server Error Messages 0 to 20

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0000I OK
    The Directory Server has executed your previous instruction successfully
  • MDS0001I Logged on OK
    You have successfully logged on.
  • MDS0002E Logon failed
    Either the user ID or password used to log on were incorrect.
  • MDS0003I Logged off OK
    You have successfully logged off.
  • MDS0004I Repository cleared OK
    All the information in the current repository has been deleted successfully.
  • MDS0005I Network search complete
    The Directory Server has finished searching the network for other instances of Directory Server.
  • MDS0006I All objects copied successfully
    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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Retype your user ID and password, ensuring that you enter them correctly. User IDs and passwords are case sensitive.

Parent topic: Directory Server Error Messages 0 to 20


MDS0003I Logged off OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0004I Repository cleared OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0005I Network search complete

Parent topic: Directory Server Error Messages 0 to 20


MDS0006I All objects copied successfully

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Parent topic: Directory Server Error Messages 0 to 20


MDS0010E Invalid endpoint specified

Parent topic: Directory Server Error Messages 0 to 20


MDS0012E Duplicate service name exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0013E Duplicate listener exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0014E Duplicate user already exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0015E Schema Administrators cannot reduce their own permission level

Parent topic: Directory Server Error Messages 0 to 20


MDS0016E Invalid endpoint specified

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify an endpoint of the form:

protocol:ip-address:port

where:

  • protocol is tcp
  • ip-address is either the text host name or IP address of the listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts
Parent topic: Directory Server Error Messages 0 to 20


MDS0017E Object must have a name

Parent topic: Directory Server Error Messages 0 to 20


MDS0018I New server session

Parent topic: Directory Server Error Messages 0 to 20


MDS0019I Client session has timed out: please log on again

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

You can change the client timeout period on the Configure Options page.

Parent topic: Directory Server Error Messages 0 to 20


MDS0020E Minimum client timeout is 60 seconds

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Enter a value of 60 or greater, or 01, which indicates an indefinite timeout period.

Parent topic: Directory Server Error Messages 0 to 20


Directory Server Error Messages 21 to 40

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0021E Minimum page size is 5 entries
    You entered an invalid minimum page size for the journal.
  • MDS0022E Minimum journal size is 32 KB
    You entered an invalid minimum journal size for the journal.
  • MDS0023E Insufficient memory for this operation
    There was insufficient computer memory for this operation to succeed.
  • MDS0024E Password mismatch
    Password mismatch.
  • MDS0025E Confirmation password mismatch
    The confirmation password does not match the password you first entered.
  • MDS0026E Old password required
    Old password required.
  • MDS0027E New password required
    You have not specified a password when creating a new user.
  • MDS0028E Invalid characters in password
    Invalid characters in password.
  • MDS0029E Selected object does not exist
    You tried to edit an object that another user has just deleted.
  • MDS0030W Some or all objects not copied: see journal for details
    You tried to copy a server but the Directory Server was unable to copy all objects related to the server.
  • MDS0031E Maximum port value is 65535
    You entered a port value in an endpoint that exceeds 65535.
  • MDS0032E Object could not be added
    There was an error adding the object. See 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Try closing some application programs.

Parent topic: Directory Server Error Messages 21 to 40


MDS0024E Password mismatch

Parent topic: Directory Server Error Messages 21 to 40


MDS0025E Confirmation password mismatch

Parent topic: Directory Server Error Messages 21 to 40


MDS0026E Old password required

Parent topic: Directory Server Error Messages 21 to 40


MDS0027E New password required

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify a valid password. Passwords can contain alphabetical and numeric characters only and are case sensitive.

Parent topic: Directory Server Error Messages 21 to 40


MDS0028E Invalid characters in password

Parent topic: Directory Server Error Messages 21 to 40


MDS0029E Selected object does not exist

Parent topic: Directory Server Error Messages 21 to 40


MDS0030W Some or all objects not copied: see journal for details

You tried to copy a server but the Directory Server was unable to copy all objects related to the server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

You can change the maximum object count on the Configure Options page.

Parent topic: Directory Server Error Messages 21 to 40


MDS0038E Minimum object limit is smaller than the current number of objects

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0043I Journal exported as text into file journal.txt OK
    The journal file has been successfully converted to a text file called journal.txt, located in the $COBDIR\bin directory.
  • MDS0044E Server name missing
    You tried to add a server without the mandatory server name value.
  • MDS0045E Duplicate request handler or package name exists
    You tried to create a request handler or a package with the same name as one that already exists for this enterprise server.
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Refresh the Enterprise Server Administration display to see if the action has now completed. Check the enterprise server console log and communications console log to see if any additional information is available. If the action you requested is temporary, such as changing a listener's status, you might want to try again. Otherwise, your change will take effect the next time you start the enterprise server.

Parent topic: Directory Server Error Messages 41 to 60


MDS0049E Server refused state change request reason code:

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Refresh the Enterprise Server Administration display to see if the action has now completed. Check the enterprise server console log and communications console log to see if any additional information is available. If the action you requested is temporary, such as changing a listener's status, you might want to try again. Otherwise, your change 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0061I Stopping and deleting all servers...
    You made a "Delete All" request and asked for servers to be stopped before they are deleted. This status is shown while the servers are in "Stopping" state.
  • MDS0062E Entry range invalid
    You asked to view an enterprise server console entry outside the range of existing entries.
  • MDS0063E Cannot delete a listener which is associated with a service
    You tried to delete a listener which is associated with a service.
  • MDS0064E Cannot delete a package which is associated with a service
    You tried to delete a package which is associated with a service.
  • MDS0065E Requested new listener status not possible when server is stopped
    You tried to make a change to the status of a listener that is not possible when the enterprise server is not started.
  • MDS0066E There are no servers to delete
    You tried to perform a "Delete All" when no server information is stored in the current repository.
  • MDS0067E less than greater than ampersand characters are not allowed in object names
    You tried to add an object using a name containing one or more of the characters < > and &, which are not allowed.
  • MDS0068I Schema updated
    You have successfully updated the schema.
  • MDS0069I All servers deleted
    You have deleted the Directory Server schema.
  • MDS0070I Data imported
    You have imported a repository into the Directory Server schema.
  • MDS0071E Data import failed
    You have attempted to import a repository into the Directory Server schema, but the import failed.
  • MDS0072I Server data saved
    You have successfully saved the data for the current server.
  • MDS0073E Server data save failed
    You have attempted to save the data for one server, but the save failed.
  • MDS0074E User name required
    You tried to add a new user without supplying a user ID.
  • MDS0075E Too many multi-byte characters in name
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0076E Too many multi-byte characters in path
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0077E Too many multi-byte characters in type
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0078E Too many multi-byte characters in ID
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0079E Too many multi-byte characters in module
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0080E Too many multi-byte characters in string
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
Parent topic: Directory Server Error Messages


MDS0061I Stopping and deleting all servers...

Parent topic: Directory Server Error Messages 61 to 80


MDS0062E Entry range invalid

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Disassociate the package from the services with which it is associated, or delete the services that reference it. Then delete it.

Parent topic: Directory Server Error Messages 61 to 80


MDS0065E Requested new listener status not possible when server is stopped

Parent topic: Directory Server Error Messages 61 to 80


MDS0066E There are no servers to delete

Parent topic: Directory Server Error Messages 61 to 80


MDS0067E less than greater than ampersand characters are not allowed in object names

Parent topic: Directory Server Error Messages 61 to 80


MDS0068I Schema updated

Parent topic: Directory Server Error Messages 61 to 80


MDS0069I All servers deleted

Parent topic: Directory Server Error Messages 61 to 80


MDS0070I Data imported

Parent topic: Directory Server Error Messages 61 to 80


MDS0071E Data import failed

You have attempted to import a repository into the Directory Server schema, but the import failed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0076E Too many multi-byte characters in path

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0077E Too many multi-byte characters in type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0078E Too many multi-byte characters in ID

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0079E Too many multi-byte characters in module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0080E Too many multi-byte characters in string

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


Directory Server Error Messages 81 to end

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0081W A duplicate port value has been used: this may cause server startup errors
    You specified a port number for a listener or a server that is already in use. If both are started at the same time then this will cause startup problems. Depending on the operating system and the TCP stack implementation the second one to start might take the port or may refuse to start up, or some other problem might occur, which might or might not be reported to you.
  • MDS0082E Requested license value invalid, minimum value is 0
    You have asked for a negative number of licenses when creating an enterprise server. The enterprise server will be created with no licenses.
  • MDS0083W Cannot set auto-refresh period if web browser timeout is set
    You tried to set an auto-refresh period when a Web browser timeout period is set on the Configure Options page. This is not allowed if user access on that page is also set to restricted, because each refresh restarts the timeout countdown.
  • MDS0084E Cannot restore from current repository path
    You have tried to restore the repository from the location of the current repository.
  • MDS0085W Value changed but not saved
    You have changed a value on one of the Edit Server tabs, then switched to another tab or page without saving your changes.
  • MDS0086I At least one Communications Process must auto-start
    You have attempted to turn off auto-start for all the communications processes that belong to an enterprise server. At least one must auto-start. The change is ignored.
  • MDS0087E MFRHBINP cannot be renamed
    You have attempted to rename the Micro Focus request handler MFRHBINP. This is not permitted because if it were possible to rename it, it could then be deleted. Enterprise Server will not work without the presence of this request handler.
  • MDS0091E ISC listener port must have a valid value
    MDS0091E ISC listener port has an invalid value,
  • MDS0095E Duplicate group name exists
    The group name exists. A user group name must be unique.
  • MDS0096I Server configuration updated
    This message is displayed after an administrator has run the Validate operation on a configuration, and then applied any suggested updates.
  • MDS0097E Duplicate initiator name exists
    An initiator name must be unique within the enterprise server configuration.
  • MDS0098W Cannot over-write existing repository data
    There is existing repository data in the chosen directory. Choose a different directory.
  • MDS0099I Server already in requested state
    Displayed 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Update the number of licenses on the Edit Server > Properties > General page.

Parent topic: Directory Server Error Messages 81 to end


MDS0083W Cannot set auto-refresh period if web browser timeout is set

Parent topic: Directory Server Error Messages 81 to end


MDS0084E Cannot restore from current repository path

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify a valid backup location from which to restore the repository.

Parent topic: Directory Server Error Messages 81 to end


MDS0085W Value changed but not saved

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

If you intended to make the change, return to the tab on which you made the change, make it again and click OK.

Parent topic: Directory Server Error Messages 81 to end


MDS0086I At least one Communications Process must auto-start

Parent topic: Directory Server Error Messages 81 to end


MDS0087E MFRHBINP cannot be renamed

Parent topic: Directory Server Error Messages 81 to end


MDS0091E ISC listener port must have a valid value

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
  • 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
  • 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
  • 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
  • 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 SupportLine.
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


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 initialisation failed. Exit name: "exit-name"
    The exit returned a return code specifying its initialisation failed.
  • CASAM3012E Initialisation 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 unregister the server from active servers list for Monitoring and Management. Error Accessing registry
    Event Manager is unable to unregister the server from the active servers for Monitoring and Management list.
  • 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 SupportLine.
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 initialisation failed. Exit name: "exit-name"

The exit returned a return code specifying its initialisation failed.
Resolution:
check the exit to find out why initialisation of the exit failed.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3012E Initialisation 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 SupportLine.
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 SupportLine.
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 SupportLine.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3015W Unable to unregister the server from active servers list for Monitoring and Management. Error Accessing registry

Event Manager is unable to unregister the server from the active servers for Monitoring and Management list.
Resolution:
Contact Micro Focus SupportLine.
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 occured.
  • 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 programatic control.
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 occured.
Resolution:
Check the return code, and contact Micro Focus SupportLine.
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 SupportLine.
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 programatic control.

This may have been to cater for DST changes.

Module:
casmgr
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 exixting 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 warinng 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 exixting Input Spool Repository for this Server was not found and therefore a new one was created.

The Input Spool Repository is efectively 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 efectively 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 warinng 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 pringer 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 pringer 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 problen 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 problen 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 problen 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 problen 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 problen 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 SupportLine 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 SupportLine 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 SupportLine 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
  • 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
    Adhock message.
  • CASCD0018I Batch job user impersonation active
    Confirmation that user impersonation for batch job execution has been configured.
  • CASCD0019I Batch job user impersonation initialisation failed for user : '%1$s'
    Environment initialisation 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
All output on standard error and system log on UNIX.
Resolution:
Free up space on the system disk.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Terminate existing Daemon if restart is required.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Adhock message.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
cascd
Destination:
Console
Parent topic: CASCD0000 - CASCD0019


CASCD0018I Batch job user impersonation active

Confirmation that user impersonation for batch job execution has been configured.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None.
Resolution:
None.
Module:
cascd
Destination:
Console
Parent topic: CASCD0000 - CASCD0019


CASCD0019I Batch job user impersonation initialisation failed for user : '%1$s'

Environment initialisation of user impersonation for batch job execution has been unsuccessful.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0022E TX Daemon not running, Shutdown request ignored

There is no TX Daemon to shutdown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Retry the request with a valid option.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Retry the request with the correct number of arguments.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by errno, where:

1 = msgget
2 = msgsnd
3 = fgets
4 = fopen
5 = mknod
System Action:
The 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Determine the cause of the error and retry if appropriate.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None - the exit is responsible for starting the requested server instance.
Resolution:
Take action approprate to the exit program's return code.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

server-number server start requests have been issued.

Module:
cascd
Destination:
system 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region is not started.
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by errno, where:

1 = msgget
2 = msgsnd
3 = fgets
4 = fopen
5 = mknod
System Action:
The region is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhserv
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0061F Server was not started

The request to start a server was not successful.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The server is not started.
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by errno, where:

1 = msgget
2 = msgsnd
3 = fgets
4 = fopen
5 = mknod
System Action:
The 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0101I ES Daemon Terminated

The TX Daemon has completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD0100 - CASCD0119


CASCD0102F ES Daemon failed to initialize

The TX Daemon has failed to initialize.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shutdown request is rejected.
Resolution:
shutdown the active regions and retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by function, where:

1 = msgget
2 = msgsnd
3 = fgets
4 = fopen
5 = mknod
System Action:
The 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.
  • 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

It will run with a process-id of pid.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Do not attempt to start regions or servers during shutdown.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Retry with a valid region name (if required).
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Start the REM for region-name before attempting to start servers again.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to start a REM or server.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0130I Server manager region-name has terminated normally

Region region-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to inform the region manager of the process which has terminated.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to inform the region manager of a terminated process.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to terminate a region. The region will continue to run.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the child process.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to terminate a region. The region will continue to run.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some common values for CCI-error are:

   2 - Comms buffer too small for received message
   3 - Invalid session identifier given
   4 - Server of same name already defined (warning)
   5 - Server of same name already defined (error)
   6 - Invalid public or machine name
   7 - Invalid request on closed session
   8 - Previous connection not responding
   9 - Miscellaneous error
  10 - Request could not be executed
  11 - Run out of memory
  12 - Unknown error
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected.
Resolution:
Terminate existing Daemon if restart is required.
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 Unrecognised 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 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server.
Resolution:
Determine and fix cause of failure then retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0170S Unrecognised 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The Enterprise Server is not started.
Resolution:
Report the failure to Micro Focus Support.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0173S ES Console Thread Create failed - RC = return-code

The ES Console tried to start a receive-all thread.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
port range processing is disabled, unless no more port available. Verify configuration and correct error.
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.
  • 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed.
Resolution:
Correct the region setup or define the region.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed.
Resolution:
Correct the region setup or define the region.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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


CASCD1010S Error while processing global configuration file

An error occurred whilst processing the global configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 Proces 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 Proces for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue.
Resolution:
Evaluate the impact of the error and take approprate action.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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
  • 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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1083I Debug SEP created for Server server-name, process-id = pid

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 occured whilst binding to the MF Directory Server.
  • CASCD4003W Error (error-message) retrieving ES configuration from MFDS
    An error occured whilst retrieving the ES configuration from the MF Directory Server.
  • CASCD4004W Error binding to MFDS, unable to load support module
    An error occured 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.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD4002W Error (error-message) binding to MFDS

An error occured whilst binding to the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4003W Error (error-message) retrieving ES configuration from MFDS

An error occured whilst retrieving the ES configuration from the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4004W Error binding to MFDS, unable to load support module

An error occured whilst binding to the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Report the error to Micro Focus SupportLine.
Module:
cascd
Destination:
Console and standard error
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Determine and fix the cause of the problem.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The error-type describes the type of error, and error-qualifier gives further information depending on error-type as follows

1 - The region name (error-qualifier) was not valid
2 - Line number error-qualifier of the configuration file is not valid
3 - The configuration file did not exist when OPEN was called,
    error-qualifier contains the COBOL return code from CBL_OPEN_FILE
4 - Failure when creating configuration save file, error-qualifier contains
    COBOL return code from CBL_CREATE_FILE
5 - Failure reading from file, error-qualifier contains the COBOL return
    code from CBL_READ_FILE
6 - Failure writing to file, error-qualifier contains the COBOL return
    code from CBL_WRITE_FILE
System Action:
Terminate the requesting process.
Resolution:
Determine and fix the cause of the problem.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some values for RC are:

     01  - No region name specified
     02  - Bad line in file
     03  - File not found
     04  - Error creating file
     05  - Error opening file
     06  - Error reading file
     07  - Error writing to file
     08  - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check that the directory that is specified in 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check that the directory that is specified in 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check that region name is correct and the directory exists.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check that RDTDIR item is correct and the directory exists.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Check that region name is correct and the directory exists.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some values for RC are:

     01  - No region name specified
     02  - Bad line in file
     03  - File not found
     04  - Error creating file
     05  - Error opening file
     06  - Error reading file
     07  - Error writing to file
     08  - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

This may result in an invalid value so the initialization will be aborted. Some values for ID are:

     01  - $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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 authorised 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 authorisation 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.
Parent topic: CASCF - CICS Configuration Support Error Messages


CASCF0060F config-module: User not authorised to run system module

The user is not a member of the group owning this module.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Ensure that dfhtx.cfg contains entries for system groups.
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 authorisation process.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Contact system administrator. Group owner not declared in groups.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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


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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0001S Auto-install error, ENQ on NETNAME netname error

During the auto-install process the requested or generated netname could not be ENQed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0002S Auto-install error, NETNAME netname already in use

During the auto-install process the requested or generated netname was already being used.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0003S Auto-install error, TERMTYPE termtype locate error

During the auto-install process the termtype entry referenced could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0004S Auto-install rejected by user exit

During the auto-install process the user exit rejected the Transaction System client's connection.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the name of the user auto-install exit is correct and the program is located on the search path.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the user exit is working correctly.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0009S Auto-install error, NETNAME netname out of service

During the auto-install process the tcts selected was marked as out of service.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the user exit is working correctly.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0010S Auto-install error, NETNAME netname definition not client type

During the auto-install process the tcts selected was not a client tcts.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the terminal definition is correct.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0019


CASCL0011S Auto-install error, NETNAME netname TCTUA allocation failure

During the auto-install process the tcts selected requested a shared storage TCTUA.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the exit named specified is correct and the exit is available on the search path.
Module:
dfhzai
Destination:
TDQ CAIL and console
Parent topic: CASCL0000 - 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 selcected 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 recognised
    the userid specified in the term resource definition could not be identified.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer is now available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0039


CASCL0021I Printer term-id disconnected successfully

The 3270 printer daemon has disconnected successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer is no longer available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0039


CASCL0022W Printer terminal-id auto-install failure, RC: tca-return-code

An error occurred in the auto-install of printer terminal-id.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0039


CASCL0023W Printer registration failure, return code = return-code

An error occurred in the registration of a printer.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0039


CASCL0024S Printer memory allocation failure, return code = malloc-return-code

An error occurred in the initialization of a printer.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected system dump generated.
Resolution:
Report error to Micro Focus Technical Support supplying generated dump file.
Module:
dfhzai
Destination:
Console Standard error
Parent topic: CASCL0020 - CASCL0039


CASCL0027E Auto-install error, LU1 NETNAME(netname) MODEL(model), device does not support SCS

The device does not report SCS support but the selcected terminal model requires SCS support.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The client is rejected.
Resolution:
Correct the terminal model or the client configuration and retry.
Module:
dfhzai
Destination:
Console Standard error
Parent topic: CASCL0020 - 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0020 - CASCL0039


CASCL0029W Terminal security user Terminal security userid for term definition for netname Terminal name. not recognised

the userid specified in the term resource definition could not be identified.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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


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, remoterequesters 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, remoterequesters 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 connction 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 connction 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 regestering 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 regestering the master session.

The reason code is reason-code.

System Action:
The communications facility is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casgate
Destination:
Console
Parent topic: 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 approprate 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


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 controlprocess 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 controlprocess 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 availabel.
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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: CASDU0000 - CASDU0019


CASDU0004I Switched diagnostic output to diagnostic-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: 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 intigrated 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 occured 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.
Parent topic: CASFC - CICS File Control Error Messages


CASFC0001I ES Fileshare services initialized

The Fileshare facility is initialized and ready to accept requests.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0002I ES Fileshare terminated

The Fileshare facility has terminated normally.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0003S ES Fileshare initialization terminated abnormally

The Fileshare facility terminated during initialization.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The process is terminated. File services are not available to the region.
Resolution:
Correct the error and restart the region.
Module:
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0007I ES Fileshare service process (PID:process-id) recovery initiated

The intigrated Fileshare process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 occured while accessing the file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Check PSOR is accessible.
Module:
dfhefctl
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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The dump request is ignored.
Resolution:
Check that the region is active.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The dump request is ignored.
Resolution:
Correct the region specification and retry the operation.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The dump request is ignored.
Resolution:
Correct the region specification and retry the operation.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The dump request is ignored.
Resolution:
Correct the configuration specification and retry the operation.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The dump request is aborted.
Resolution:
Correct the installation setup and retry the operation.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0012E Input Dump/Trace dataset not found

No input dump/trace dataset could be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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


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'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5008I Fileshare Control Process termination complete

The Fileshare Control Process has terminated.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 controlprocess 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 controlprocess has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 recieved 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 recieved 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 cancelled at user request
    The requested log shipment has been cancelled 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The reason code is reason-code.

System Action:
The Fileshare Control Process is terminated and Fileshare functionality is not availabel.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

All ES processing is suspende 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

All ES processing is suspende 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 recieved the complete T-Log update transmission and the next replication sequence number is sequence-number.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 recieved a request for a T-Log update for node node-name starting from log offset sequence-number.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 cancelled at user request

The requested log shipment has been cancelled by the user exit.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shipment is cancelled.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5072I Fileshare user exit procedure successfully loaded

The provided user exit proc was successfully loaded.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shipment is cancelled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shipment is cancelled 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shipment is cancelled 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 registered for classes "IMS-Classesname"
    The IMS Message Processin region registered with the control region for classes IMS-Classesname.
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 registered for classes "IMS-Classesname"

The IMS Message Processin region registered with the control region for classes IMS-Classesname.
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 Processin 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 Processin 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.
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


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 porcess 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
  • CASKC5000 - CASKC5019
  • CASKC6000 - CASKC6019
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 pages in the SIT.
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 opperation failed with reason code reason-code.

System Action:
Transaction aborted. The MQ Message is retained on the input queue queue-name.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
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 opperation failed with reason code reason-code.

System Action:
Transaction aborted. The MQ Message is retained on the input queue queue-name.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
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 opperation failed to return a record.

System Action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation 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 opperation failed with reason code reason-code.

System Action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation 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 opperation 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 hexidecimal representation of the error might indicate a COBOL RTS error, for example 0x390D is a 9/13 which means file not found.

System Action:
The service request is failed.
Resolution:
Correct the location or deployment error and retry the request.
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.
  • CASKC0051W 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.
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


CASKC0051W 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


CASKC0200 - CASKC0219

  • 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.
Parent topic: CASKC - CICS Task Control Error Messages


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


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


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.
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 aparently has failed to remove the process.

System Action:
The process DCA is released and internal recovery is initiated.
Resolution:
Resolve the issue that caused the timeout.
Module:
casmgr
Destination:
System Console
Parent topic: 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
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
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
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
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 aparently has failed to remove the process.

System Action:
The process DCA is released and internal recovery is initiated.
Resolution:
Resolve the issue that caused the timeout.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


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 occured whilst binding to the MF Directory Server.
  • CASMQ5010W ES MQ Service Process Error (error-message) retrieving ES configuration from MFDS
    An error occured 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 occured 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 occured 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 Prcess 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 Prcess 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 instilation 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 Prcess 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 Prcess 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 controlprocess 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 accessable.
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 controlprocess 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


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.
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


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.
    The scan for pipeline pipeline has completed.
  • 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.

The scan for pipeline pipeline has completed.

The number of wsbind files found in the directory specified for this pipeline by the WSDIR parameter is reported by Number of wsbind files found. The number that successfully created WebService resources is report.

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 resourcename 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 resourcename'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 resourcename 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 resourcename'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
  • 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 terminalid is specified then a remote system ID must be specified.
  • CASRA0041E Minimum record length greater than the maximum record length
    The maximum record length must be equal to or greater than the minimum record length.
  • CASRA0042E More than one database has been defined
    Only one database (other than IMS) may be defined.
  • CASRA0043E No indirect name specified when Queue type is indirect
    An indirect destination must be specified for an indirect transient data queue.
  • CASRA0044E Universal Client specified, but session count is 0
    Universal Client has been specified without a correct number of sessions.
  • CASRA0045E Both MFNODE and MFPORT must be entered
    When specifying a CCI connection using MFNODE, the port number (MFPORT) must also be specified.
  • CASRA0046E PROTOCOL(HTTP|USER) and AUTH(ASSERTED) meaningless
    The value ASSERTED for AUTHENTICATE is meaningless when the PROTOCOL is HTTP or USER.
  • CASRA0047E PROTOCOL(ECI|IPIC) and AUTHENTICATE meaningless
    Any value for AUTHENTICATE is meaningless when the PROTOCOL is ECI or IPIC.
  • CASRA0048E PROTOCOL(IIOP) and AUTH(BASIC|AUTOREGISTER|AUTOMATIC) meaningless
    The values BASIC, AUTOREGISTER and AUTOMATIC for AUTHENTICATE are meaningless when the PROTOCOL is IIOP.
  • CASRA0049E ATTACHSEC must be blank for PROTOCOL(HTTP|USER|IIOP)
    ATTACHSEC may be specified only when you specify PROTOCOL ECI or IPIC.
  • CASRA0050E ALT file type requires base file name
    A base file name must be specified for an FCT of type ALT.
  • CASRA0051E Base file name only required for an FCT of type ALT
    A base file name need only be specified for an FCT of type ALT.
  • CASRA0052E Remote parameters specified for FCT of type ALT
    An FCT of type ALT cannot specify a remote system.
  • CASRA0053E Transaction ID contains invalid characters
    Transaction ID contains invalid characters.
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA0040E Remote terminal ID specified but no remote system ID specified

If a remote terminalid is specified then a remote system ID must be specified.
Resolution:
Specify a remote system ID or delete the remote terminal id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - 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 Unrecognised field identifier
    The field identifier passed into the function was not recognised.
  • CASRA0064E System resource - read access only
    The resource is owned by the system modification not allowed.
  • CASRA0065I No more resources of this type in the group
    There are no more resources of this type in the specified group.
  • CASRA0066E Resource entry has been changed by external process
    The resource has been modified by another process since last read.
  • CASRA0070E The maximum number of groups in a list has been reached
    The maximum number of groups in a list has been reached.
  • CASRA0071I The list does not contain any groups
    The list does not contain any groups.
  • CASRA0072I No more groups in the list
    No more groups in the list.
  • CASRA0073E The specified group is not a member of the list
    The specified group is not a member of the list.
  • CASRA0074E Remote system ID must be supplied for files of type 'Undefined'
    The specified group is not a member of the list.
  • CASRA0075W Specified dataset name is not cataloged
    The use catalog flag has been set but the specified DSN is not defined to the catalog.
  • CASRA0076E Remote system ID must not be supplied for cataloged files
    A cataloged file cannot be remote.
  • CASRA0077W The attributes previously specified do not match those defined in the catalog
    The attributes (record lengths, key information) are different from those specified in the catalog.
  • CASRA0078E The catalog entry is a non-VSAM file
    The selected catalog entry is not a VSAM file.
  • CASRA0079E SYNCLEVEL WRONG
    SYNCLEVEL.
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 Unrecognised field identifier

The field identifier passed into the function was not recognised.
Resolution:
Pass a valid field identifier on the function call.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - 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 recognise 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 EXPIRYINTMIN field
    The value entered in the EXPIRYINTMIN 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 EXPIRYINTMIN field

The value entered in the EXPIRYINTMIN field is incorrect.

Accepted values are: 0 or a number < 15001.

Resolution:
Correct the EXPIRYINTMIN 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 '.' .
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


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. not locked.
  • CASRA1017E Invalid record type
    A request contained an invalid value set for the key record type.
  • CASRA1018E An IO error was encountered when processing the command
    An IO error occurred while processing the current record.
  • CASRA1019E An IO error was encountered when processing the command
    An IO error occurred while processing the current record.
Parent topic: CASRA - 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. not locked.
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. not continue.
  • CASRA1202S Error processing the region configuration file
    While reading the regions configuration file and error was encountered and the operation can not continue.
  • CASRA1203S Initialization failure
    A required support module was not present.
  • CASRA1204S Initialization failure
    A required support module was not present.
  • CASRA1205S Initialization failure
    A required support module was not present.
  • CASRA1206S Initialization failure
    A required support module was not present.
  • CASRA1207S Initialization failure
    A required support module was not present.
  • CASRA1208S Initialization failure
    A required support module was not present.
  • CASRA1209S Initialization failure
    A required support module was not present.
  • CASRA1211S Error, incorrect resource definition file version
    The version of the resource definition file is not recognized.
  • CASRA1212E The resource definition file can not be found
    The file that is configured for the region being operated on can not be found.
  • CASRA1214E Error opening the resource definition file.
    An error was encountered while opening the resource definition file.
  • CASRA1215E Invalid request issued.
    A request was passed to the resource definition interface prior to it being properly initialized.
  • CASRA1216E The region name is not valid
    An override region name was passed on the initialization call and the region could not be found.
  • CASRA1217E Already initialized
    A initialization command was passed to the RDO API and it is already initialized.
  • CASRA1218S Initialization failure
    A required support module was not present.
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA1201S Initialization failure

A required support module was not present. not continue.
Resolution:
Investigate the cause of the missing module - dfh0cfg.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: 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 in not valid
    A initialization command was passed a password that is not defined in the target resource definition file.
  • CASRA1303E Authorization failed
    An attempt was made to access a resource that you did not have the proper authority for.
  • CASRA1304E Authorization failed for PCT table access
    An attempt was made to access a PCT entry and the user does not have the proper authority level.
  • CASRA1305E Authorization failed for FCT table access
    An attempt was made to access a FCT entry and the user does not have the proper authority level.
  • CASRA1306E Authorization failed for PPT table access
    An attempt was made to access a PPT entry and the user does not have the proper authority level.
  • CASRA1307E Authorization failed for DCT table access
    An attempt was made to access a DCT entry and the user does not have the proper authority level.
  • CASRA1308E Authorization failed for SIT table access
    An attempt was made to access a PCT entry and the user does not have the proper authority level.
  • CASRA1309E Authorization failed for SNT table access
    An attempt was made to access a SNT entry and the user does not have the proper authority level.
  • CASRA1310E Authorization failed for TST table access
    An attempt was made to access a TST entry and the user does not have the proper authority level.
  • CASRA1311E Authorization failed for JCT access
    An attempt was made to access a JCT entry and the user does not have the proper authority level.
  • CASRA1312E Authorization failed for TYPE TERM table access
    An attempt was made to access a TTYPE entry and the user does not have the proper authority level.
  • CASRA1313E Authorization failed for TERM table access
    An attempt was made to access a TERM entry and the user does not have the proper authority level.
  • CASRA1314E Authorization failed for PLT table access
    An attempt was made to access a PLT entry and the user does not have the proper authority level.
  • CASRA1315E Authorization failed for STARTUP table access
    An attempt was made to access a STARTUP entry and the user does not have the proper authority level.
  • CASRA1316E Authorization failed for XLT access
    An attempt was made to access a XLT entry and the user does not have the proper authority level.
  • CASRA1317E Authorization failed for PRO table access
    An attempt was made to access a PRO entry and the user does not have the proper authority level.
  • CASRA1318E Authorization failed for security record access
    An attempt was made to access a RID entry and the user does not have the proper authority level.
  • CASRA1319E Authorization failed for group description table access
    An attempt was made to access a RID entry and the user does not have the proper authority level.
Parent topic: CASRA - 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 in not valid

A initialization command was passed a password that is not defined in the target resource definition file.
System Action:
The request is not processed.
Module:
dfhrapi
Destination:
standard error
Parent topic: 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 unrecognised error has occured - file may be corrupt
    An error occured which has not been recognised.
  • CASRA1502E The requested record was not found
    An attempt was made to process a record that does not exist in the RDO file being processed.
  • CASRA1503E Duplicate record found
    An attempt was made to add a record that already exists in the resource file being operated on. not locked.
  • CASRA1504E The record is locked by another process
    An attempt was made to process a record that is locked by another process.
  • CASRA1505E The resource definition file ((substDir$)) cannot be found
    The file that is configured for the region being operated on can not be found.
  • CASRA1506E Invalid record type
    A request contained an invalid value set for the key record type.
  • CASRA1507E Invalid request issued
    An invalid request was passed to the resource definition interface prior to it being properly initialized.
  • CASRA1508S A mis-match error has occured
    A mis-match error has occured.
  • CASRA1509E Failed to create resource definition file ((substDir$))$!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. not continue.
  • 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 alerady open.
  • CASRA1513S The resource definition file ((substDir$)) version is incorrect
    The version of the resource definition file is not recognized.
  • CASRA1514E The resource definition file ((substDir$)) is secure and a valid user has not signed on
    An attempt was made to access a resource file and a proper user passed as part or RDO API initialization.
  • CASRA1515E An I/O error ((substFS$)) was encountered accessing the resource definition file ((substDir$))$!An 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 unrecognised error has occured - file may be corrupt

An error occured which has not been recognised.

The resource definition file may be corrupt.

Module:
RDOWrapper
Destination:
Standard Error
Parent topic: 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. not locked.
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 occured

A mis-match error has occured.
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. not continue.
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 alerady 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 dferdio
  • CASRB0035E Conversion Table File not found
    Your conversion file (dfhdrcnv) was not found.
  • CASRB0036E Unexpected dfherdcv error: request=request-code result=result-code status=file-status
    An unexpected error was returned from the conversion file I/O handler (dfherdcv).
  • CASRB0037E A valid SNT administrator sign-on is required to toggle security.
    You have not identified yourself as a user with SNT-Update authority, which is required in order to toggle security on or off.
  • CASRB0038E Error reading security record. Security unchanged.
    An unexpected error occurred reading the RDF security record, preventing the changing of security settings.
  • 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 dferdio

System Action:
Processing terminated.
Resolution:
Check that you are not using a newer RDF file with an older version of this system.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0035E Conversion Table File not found

Your conversion file (dfhdrcnv) was not found.
System Action:
Processing of the conversion file ends.
Resolution:
Check that the dfhdrcnv and dfhdrcnv.idx files exist in your $TXDIR/files/sys or $REGIONBASE/{region}/files/reg subdirectory.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0036E Unexpected dfherdcv error: request=request-code result=result-code status=file-status

An unexpected error was returned from the conversion file I/O handler (dfherdcv).
System Action:
The file is closed (if it was open), and processing continues, if possible.
Resolution:
file-status may provide some insight into the cause of the problem. If not, contact Micro Focus SupportLine.
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 SupportLine.
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 specifiy data set name will not be checked against the catalog.
Resolution:
Check that the file "catalog.dat" exists in the project folder, and that it is not open to another process.
Module:
dfhrdtup
Destination:
Build tab
Parent topic: CASRB0060 - CASRB0079


CASRB0070I Modified FCT entry FCT-name in group group-name, FS Server ID was "Old-FS-ID" now "New-FS-ID"

The FCT resource record was modified to bulk change the Fileshare server ID.

The previous and new Fileshare server IDs are displayed.

System Action:
Update FCT entry.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0071I Processing FCT entries in group group-name, bulk update of Fileshare server (FS-ID)

Setting all FCT entries in the group to the specified Fileshare server ID.
System Action:
Process FCT entries.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0072I Group group-name not found

The specified group is not found in the RDT.
System Action:
Processing ends.
Resolution:
Correct the name for the requested group.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0073E Group group-name is invalid

The specified group name contains invalid characters.
System Action:
Processing ends.
Resolution:
Correct the name for the requested group.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0074E Resource definition path not specified

The resource definition path has not been specified on the command line.
System Action:
Processing ends.
Resolution:
Correct the command line.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0075E Options /s(sit-name,FS-ID) and /f(group-name,FS-ID) mutually exclusives

Both parameters /ssit-name and /f(group-name...) were requested but only one of them can be requested at a time.
System Action:
Processing ends.
Resolution:
Correct the command line and specify either /s or /f.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0076E SIT sit-name contains invalid characters

The name of the SIT contains invalid characters.
System Action:
Processing ends.
Resolution:
Correct the sit name.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0077E SIT sit-name not found

The name of the SIT does not exist.
System Action:
Processing ends.
Resolution:
Correct the sit name.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0078I Modified SIT sit-name. FS-ID for recoverable TS was old-recoverable-TS-name now new-recoverable-TS/TD-name.

The name of the FS-ID for recoverable TS/TD has changed.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0079I Modified SIT sit-name. FS-ID for recoverable TD was old-recoverable-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.
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


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 unrecognised 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 unrecognised 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 unrecognised request handler definition.
  • CASRD1041E Unrecognized ES package administration request
    A request to add, update or delete a package failed due to an unrecognised 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 unrecognised 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 unrecognised 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The process is terminated. ODBC services are not available to the region.
Resolution:
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Processing will continue normally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM0000 - CASRM0019


CASRM0005S ODBC resource manager error error-message

The ODBC resource manager encountered an unrecoverable error.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The ODBC resource manager will terminate abnormally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM0000 - CASRM0019


CASRS - CASRAS Process Error Messages

  • CASRS2000 - CASRS2019
  • CASRS2040 - CASRS2059
  • CASRS2060 - CASRS2079
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.
  • CASRS2065E Region lost connection to Redis server Redis server name at Redis server address port Redis port number
    The region lost the connection to Redis.
  • CASRS2066I Region reconnected to Redis server Redis server name at Redis server address port Redis port number
    The region reconnected to Redis.
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


CASRS2065E 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: 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


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 occured 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 occured processing the signon request.

The security daemon may not be present or functioning correctly.

System Action:
The signon attempt is rejected.
Resolution:
Try again or use the CESN transaction if problems persists.
Module:
dfhzcesg
Destination:
User terminal, console and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0020 - 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
  • CASSI1000 - CASSI1019
  • CASSI1400 - CASSI1419
  • CASSI1420 - CASSI1439
  • CASSI1440 - CASSI1459
  • CASSI1500 - CASSI1519
  • CASSI1600 - CASSI1619
  • CASSI1700 - CASSI1719
  • CASSI1720 - CASSI1739
  • CASSI1740 - CASSI1759
  • CASSI1800 - CASSI1819
  • CASSI1820 - CASSI1839
  • CASSI1840 - CASSI1859
  • CASSI1860 - CASSI1879
  • CASSI1900 - CASSI1919
  • CASSI2000 - CASSI2019
  • CASSI2100 - CASSI2119
  • CASSI2140 - CASSI2159
  • CASSI2200 - CASSI2219
  • CASSI4000 - CASSI4019
  • CASSI5000 - CASSI5019
  • CASSI5020 - CASSI5039
  • CASSI5040 - CASSI5059
  • CASSI6000 - CASSI6019
  • CASSI7000 - CASSI7019
  • CASSI8000 - CASSI8019
  • CASSI9000 - CASSI9019
  • CASSI9020 - CASSI9039
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 occured 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 occured 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 occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
System Action:
The region will not be started.
Resolution:
Verify the settings for AMODE and number of shared pages in the SIT.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0010S Error registering storage-type with requested AMODE

An error occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
System Action:
The region will not be started.
Resolution:
Verify the settings for AMODE and number of shared pages in the SIT.
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


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 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.
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 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


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.
  • 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


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
    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 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 modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronisation.
    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

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 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 modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronisation.

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 initialisation failed or no cross region database configured.
    The current region failed to start as the region initialisation for MFDBFH failed a cross region database is not configured.
  • CASSI1448E Region cannot be started because Tranclass is not supported in a PAC environment.
    The current region failed to start as the region was configured for both Tranclass and PAC.
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 initialisation failed or no cross region database configured.

The current region failed to start as the region initialisation 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


CASSI1448E Region cannot be started because Tranclass is not supported in a PAC environment.

The current region failed to start as the region was configured for both Tranclass and PAC.

Tranclass is not supported in a PAC environment.

System Action:
Shutdown the region.
Resolution:
Check your configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


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 enviroment variable cannot be accessed.
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 enviroment 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


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 initialisation 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 initialisation 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


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=%1s
    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=%1s

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 intialization 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 intialization 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 databse, 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 occured whilst binding to the MF Directory Server.
  • CASSI4003W Error (error-message) retrieving ES configuration from MFDS
    An error occured whilst retrieving the ES configuration from the MF Directory Server.
  • CASSI4004W Error binding to MFDS, unable to load support module
    An error occured 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.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI4000W Error accessing project databse, 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 occured 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 occured 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 occured 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


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 occured 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 occured 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-evey-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 occured 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 occured 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-evey-SEP (phase 2) PLT PI (Program List Table Post Initialization) programs have run on this SEP successfully.

Critical post initialization processing has been completed using the plt-name list.

System Action:
Startup proceeds normally.
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 you are starting a 64bit server from a 32bit environment or a 32bit server from a 64bit environment.

Resolution:
Check that both the server definition and the environment 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 are Global resources).
    The file ESCLRNLs.cfg does not exits.
  • 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 ESCLRNLs.cfg 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 %2$.
    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.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI9020I Default RNLDEF created in Name of the file containing the RNL definitions (All SYSDSNs are Global resources).

The file ESCLRNLs.cfg does not exits.
System Action:
If specific RNLs are required, create the file in the folder containing the CATALOGUE.
Resolution:
Check region configuration.
Module:
casmgr
Destination:
Console
Parent topic: 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 ESCLRNLs.cfg 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 %2$.

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


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 Process termination due to RTS error. 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 faliure 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region manager cannot be informed of the process's termination. The region may continue successfully.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region manager cannot be informed of the process's termination. The region may continue successfully.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed and restore the database resource managers to a known position.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 Process termination due to RTS error. RTS-error-message

The process terminated due to a COBOL RTS error.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Depending on the process type the system will restart the process.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

A bad response was returned and the resource managers were rolledback to the previous syncpoint.

System Action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed 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 faliure where shared memory is locked.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

This should not occure 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
Make sure that the region being shutdown is running and retry.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will continue running.
Resolution:
To shut the region down log on the region and enter the transid required to shutdown the region.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not be shutdown.
Resolution:
Make sure that the userid and password being specified has the correct security keys set in the SNT to run the shutdown transaction.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not be shutdown.
Resolution:
Make sure that the transaction is local.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not be shutdown.
Resolution:
Make sure that the transaction is in the correct case and has been installed to the region.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not be shutdown.
Resolution:
If there is no shared memory available try to shutdown the region without a transid.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region cannot be shutdown.
Resolution:
Use other system OS tools for terminating the region.
Module:
casstop
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0018S Safmgr initialization failed, reason = reason-code

The Casstop process failed to initialize safmgr.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The reporting Enterprise Server is terminated.
Resolution:
Correct the Safmgr initialization problem and restart ES.
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.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Termination continues.
Resolution:
None.
Module:
casstop
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown processing aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown processing aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing is terminated; Shutdown is aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing. Determine the cause of the transaction program abend and correct it. If the problem cannot be determined, the Resource Definitions can be updated to omit the program from the PLT or to use a different (or no) PLT.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing continues, the named program is ignored.
Resolution:
Make sure that the program exists and has been compiled correctly. The compiled program must been in a directory specified on TRANPATH.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing is terminated; Shutdown is aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing. Determine the cause of the transaction program abend and correct it. If the problem cannot be determined, the Resource Definitions can be updated to omit the program from the PLT or to use a different (or no) PLT.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing continues, the named program is ignored.
Resolution:
Make sure that the program exists and has been compiled correctly. The compiled program must been in a directory specified on TRANPATH.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
casevmgr
Destination:
Console
Parent topic: CASST5220 - CASST5239


CASST5231I Event Manager Process termination complete

The Event Manager Process has terminated.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
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


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 SupportLine if you see this reason
    code.
4 - Unable to read ACB file from disk. This is likely
    to be because of invalid permissions.
5 - ACB file size incorrect. The physical file size
    does not match that stored in the ACB, indicating
    a corruption of the file.
6 - ACB name error. The name of the ACB file does not
    match name of the file it was generated from.
7 - Invalid ACB type, possible corruption. Please
    contact Micro Focus SupportLine if you see this
    reason code.
8 - ACB content failed CRC checking. This is most
    likely to be due to file corruption.
System Action:
Transaction aborted.
Resolution:
Correct ACB and retry.
Module:
castmc
Destination:
Console
Parent topic: 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 secruity 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 secruity 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 secruity 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 secruity 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 secruity 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 secruity group security-group from logical unit logical-unit.

The signon was rejected as an ID error.

System Action:
The user signon is rejected.
Resolution:
Present valid credentials.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5023E Signon password error: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit.

The signon was rejected as a password error.

System Action:
The user signon is rejected.
Resolution:
Present valid credentials.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5024S Signon SAF error: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit.

The signon was rejected because of a SAF error. An unexpected external security system error was returned on the verify call.

System Action:
The user signon is rejected.
Resolution:
Notify security personell.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5025E Signon ID revoked: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit.

The signon was rejected because the ID has been revoked.

System Action:
The user signon is rejected.
Resolution:
Notify security personell.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5026E Signon password expired: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit.

The signon was rejected because the password has expired.

System Action:
The user signon is rejected.
Resolution:
Retry and supply a new password.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5027I IMS TM MFS is operating with character attribute bias

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as character attributes.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5028I IMS TM MFS is operating with binary attribute bias

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as binary attributes.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5029I IMS TM MFS ASCII null character system bias is null-character

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied messages using null-character as the MFS null character.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5030I IMS TM resource definitions and statistics cold started

Resource definitions and statistics from the previous run's keypoint have been discarded.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5031I IMS TM resource definitions restored, statistics cold started

Resource statistics from previous run's keypoint have been discarded.

The resource definitions have been restored to the state recorded in the last keypoint.

Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5032I IMS TM resource definitions and statistics restored

The resource definitions and statistics have been restored to the state recorded in the last keypoint.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5033S IMS TM message queue corruption detected: block queue-file-block

The IMS TM message queue disk storage is corrupted.
System Action:
System attempts to correct error.
Resolution:
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. ystem. 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
    Fush aggregation has been dynamically disabled.
  • CASTM5043I IMS TM Message Queue File flush enabled
    Flush operations for this file are now enabled.
  • CASTM5044I IMS TM exit programs loaded: 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 controlprocess 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

Fush 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 subsiquent message will be issued if the transaction is stopped.

System Action:
Stop the transaction and suspend the input message.
Resolution:
Correct the transaction.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - 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 approprate distanition(s).
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5054I IMS TM control process (PID:process-id) recovery initiated

The IMS TM controlprocess 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 origional 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.
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


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.
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


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 nonblank 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 occured during the processing of a BMS Paging operation.
  • CASTP4902 PAGING unexpected error accessing page queue. EIBRESP = eibresp-value.
    An unexpected TS Queue error occured 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 occured 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 occured 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


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
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 orphined.

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 trancient 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 trancient 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 trancient 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 trancient 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 trancient 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 trancient 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 orphined.

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 trancient 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 atual 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 trancient 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 trancient data queue queue-name.

The reported first and last records each have invalid addresse. 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 trancient 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.
  • 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 orphined.

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(%3$s) 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


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 respostory 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 respository 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 respostory 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
    Fush 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 controlprocess 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

Fush 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 controlprocess 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 origional 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 respository 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


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 SupportLine 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 SupportLine 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 Rolledback 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 intiialize on this process.
  • CASXO0017S Unrecoverable error in XAT resource name XA interface, RM interface disabled
    An unrecoverable error occured 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Where the return code means :

       -1  An error occured in the transaction manager
       -2  Asynchronous operation already outstanding
       -3  A resource manager error occurred
       -4  The XID is not valid
       -5  Invalid arguments were given
       -6  Routine invoked in an improper context
       -7  Resource Manager unavailable
       -8  the XID already exists
       -9  Resource Manager doing work outside global transaction
System Action:
The 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined.
Resolution:
Contact your administrator for the resource.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined.
Resolution:
Contact your administrator for the resource.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined.
Resolution:
Contact your administrator for the resource.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined.
Resolution:
Contact your administrator for the resource.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 Rolledback transaction: reason return-code

The Resource manager for the XAT resource indicated it had rolled back the transaction.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 intiialize on this process.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None.
Resolution:
Determine the cause of the failure and restart the system.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0000 - CASXO0019


CASXO0017S Unrecoverable error in XAT resource name XA interface, RM interface disabled

An unrecoverable error occured interfacing with the XA Resource Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions.
Resolution:
Determine the cause of the failure and restart the system.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 occured 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.
  • CASXO0031W ES has lost connection to the RM XA RM Name, attempting to reconnect.
    An RM has lost connection, CRCN will attempt to reconnect the RM.
  • 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 CRCN Part of the message output by the Monitoring CRCN, CRCN LIST or CRCN REFRESH: XA RMs state list
    Displays, at CRCN startup or on a CRCN LIST/REFRESH request, the RMs list actively monitored.
  • 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 resoruce 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Transactional support for JCL via IKJEFT01 will not be supported.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0023S Severe error detected in XAT resource name XA interface, RM interface disabled

A severe error occured interfacing with the XA Resource Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions.
Resolution:
Determine the cause of the failure and re-enable it.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0024I XA Switch XAT resource name, RM interface disabled on demand

A user disabled the XA Resource Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions.
Resolution:
None.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will be called for future transactions.
Resolution:
None.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will be called for future transactions.
Resolution:
None.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been committed on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been rolled back on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: 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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been rolled back on this resource manager.
Resolution:
None.
Module:
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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


CASXO0031W ES has lost connection to the RM XA RM Name, attempting to reconnect.

An RM has lost connection, CRCN will attempt to reconnect the RM.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Verify why the RM disconnected.
Resolution:
None.
Module:
dfhzcrcn
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None.
Resolution:
None.
Module:
dfhzcrcn
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None.
Resolution:
None.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0034I CRCN Part of the message output by the Monitoring CRCN, CRCN LIST or CRCN REFRESH: XA RMs state list

Displays, at CRCN startup or on a CRCN LIST/REFRESH request, the RMs list actively monitored.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
If an expected active RM is not listed verify why CRCN could not connect.
Resolution:
None.
Module:
dfhzcrcn
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 resoruce has now been executed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None.
Resolution:
Contact Micro Focus SupportLine.
Module:
casasys
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0040 - CASXO0059

  • CASXO0040S Severe error detected in XAT resource name XA interface. System short on storage. RM interface disabled
    A severe error occured interfacing with the XA Resource Manager and the system is short on storage.
  • CASXO0041I The XA connection monitoring transaction Transaction name started using a Monitoring interval in seconds interval.
    The xa monitoring transaction has been started using a nnnnn second(s) interval.
  • CASXO0042I No Resource Managers enabled, stopping XA connection monitoring transaction.
    No xa resources to monitor.
  • CASXO0043I The XA connections monitoring transaction stop request sent.
    The CRCN STOP request has been sent.
  • CASXO0044I The XA connections monitoring transaction stopped.
    CRCN stop request has been accepted.
  • CASXO0045W XA RMs currently monitored are not active, verify the XA connections.
    The connections have been disabled by CRCN in an attempt to reconnect.
  • CASXO0046I XAT resource name RM Switch is not at the latest version, consider rebuilding the switch.
    When called on xa-ping the XA RM type was not returned.
  • CASXO0047S Severe error on Oracle entry XAT resource name, Oracle does not always recover, please use Dynamic XA to regain connection.
    A severe error occured processing an Oracle static XA Resource Manager.
  • CASXO0048S Severe error on MQSeries entry XAT resource name, using MQseries Server install is not supported for CRCN reconnection.
    A severe error occured processing a MQSeries Server installation.
Parent topic: CASXO - CICS Transaction Manager Error Messages


CASXO0040S Severe error detected in XAT resource name XA interface. System short on storage. RM interface disabled

A severe error occured interfacing with the XA Resource Manager and the system is short on storage.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions.
Resolution:
Determine the cause of the failure and re-enable it.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0041I The XA connection monitoring transaction Transaction name started using a Monitoring interval in seconds interval.

The xa monitoring transaction has been started using a nnnnn second(s) interval.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
None.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0042I No Resource Managers enabled, stopping XA connection monitoring transaction.

No xa resources to monitor.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Verify your xa connections.
Resolution:
None.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0043I The XA connections monitoring transaction stop request sent.

The CRCN STOP request has been sent.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
none.
Resolution:
None.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0044I The XA connections monitoring transaction stopped.

CRCN stop request has been accepted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
none.
Resolution:
none.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0045W XA RMs currently monitored are not active, verify the XA connections.

The connections have been disabled by CRCN in an attempt to reconnect.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
If expected active RMs are not listed verify the XA Connections.
Resolution:
None.
Module:
dfhzcrcn
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0046I XAT resource name RM Switch is not at the latest version, consider rebuilding the switch.

When called on xa-ping the XA RM type was not returned.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
For full support of the CRCN transaction, rebuild XA switch modules.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0047S Severe error on Oracle entry XAT resource name, Oracle does not always recover, please use Dynamic XA to regain connection.

A severe error occured processing an Oracle static XA Resource Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Use Dyamic XA to disable/enable the Oracle RM.
Resolution:
See Micro Focus documentation for more info.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0048S Severe error on MQSeries entry XAT resource name, using MQseries Server install is not supported for CRCN reconnection.

A severe error occured processing a MQSeries Server installation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The xa reconnect transaction CRCN does not support MQ Server installation.
Resolution:
None.
Module:
dfheserv
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 (signalling 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 modfication 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 shuold 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 synbolic 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 synbolic 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 synbolic 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 (signalling 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 modfication 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 shuold not occur.
System Action:
The invalid text is ignored.
Resolution:
Correct the EXEC CICS statement by removing the invalid text or supplying the appropriate addiitonal 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 synbolic 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 synbolic 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 synbolic 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 cotinues 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 qualilfication 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 weas 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 weas 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 sepcified (i.e., that the parentheses were not present).
Resolution:
Verify that the argument was not inadvertently omitted from the option. Correct ifnecessary.
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 SupportLine
    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 SupportLine

The maximum nesting level of 30 has been exceeded.
System Action:
The curent 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 spceial 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 occured.
  • COBEC9036S CICSECM licensing error error-code
    An unexpected licensing error occured.
  • 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 occured.

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 occured.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This contains the available user exits:

  • Exit Points
  • Support Functions
  • Structures
Parent topic: Enterprise Server Reference


Exit Points

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following exit points are available:

  • Exit Interface Definition
    Contains the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit function.
  • External Data Value Modification - Input Parameter (Exit Point 1)
    Allows you to override the external value provided by the client request for the given COBOL program's Linkage Section item.
  • Internal Data Value Modification - Input Parameter (Exit Point 2)
    Allows you to override the internal value provided by the client request for the given COBOL program's Linkage Section item.
  • Unmapped Named External Input Parameter (Exit Point 3)
    Allows you to handle an unmapped named external input parameter that has been specified in the client request.
  • End of Input Request Processing (Exit Point 4)
    Allows you to initialize parameter values in the internal data areas addressed by argv other than those initialised during external parameter mapping.
  • Start of Response Processing (Exit Point 5)
    Allows you to bypass completely the default response processing.
  • Internal Data Value Modification - Output Parameter (Exit Point 6)
    Allows you to override the internal data value created during the execution of the application.
  • External Data Value Modification - Output Parameter (Exit Point 7)
    Allows you to override the internal data value created during the execution of the application.
  • End of Response Processing (Exit Point 8)
    Allows you to override the internal data value created during the execution of the application.
  • End of Request Processing (Exit Point 9)
    Allows you to release any resources that were allocated in exit points 0 through 8.
  • Configuring Whether a Message Shows in the Console
Parent topic: User Exits


Exit Interface Definition

Contains the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit function.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
Exit point in the request handler:
1 | External data value modification - input parameter
2 | Internal data value modification - input parameter
3 | Unmapped named external input parameter
4 | End of input request processing
5 | Start of response processing
6 | Internal data value modification - output parameter
7 | External data value modification - output parameter
8 | End of response processing
9 | End of request processing
exit_info
Usage depends on the exit point

On Exit:

exit_info
Usage depends on the exit point

Return codes:

Depends on the exit point.

Parent topic: Exit Points


External Data Value Modification - Input Parameter (Exit Point 1)

Allows you to override the external value provided by the client request for the given COBOL program's Linkage Section item.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
1 = External data value modification - input parameter
exit_info
version | Version of structure format
flags | 0
ext_value_size | Size of data addressed by ext_value
funcs | User exit support functions
field_name | Name of data item in COBOL program's Linkage Section
ext_param_name | Name of external parameter
ext_value | External data value associated with field_name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
ext_value_size | Size of data addressed by ext_value. Needs to be updated only if the user exit allocates memory for a new ext_value string
ext_value | External data value to be associated with field_name. Needs to be updated only if the user exit allocates memory for a new ext_value string
exit_data | User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied external value. Use this value to perform default mapping for the given COBOL program Linkage Section field name.

Comments:

This exit gives you the opportunity to override the external value provided by the client request for the given COBOL program Linkage Section field name. If the exit chooses to override the external value, it must return IDP_EXIT_HANDLED and either update ext_value in place (if the replacement value is less or equal to ext_value_size), or allocate a replacement string using the support function fn_alloc_mem and set ext_value and ext_value_size accordingly. The request handler then performs default mapping for the original (IDP_EXIT_CONTINUE) or overridden (IDP_EXIT_HANDLED) external data value.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Internal Data Value Modification - Input Parameter (Exit Point 2)

Allows you to override the internal value provided by the client request for the given COBOL program's Linkage Section item.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
2 = Internal data value modification - input parameter
exit_info
version | Version of structure format
flags | 0
data_size | Size of data ddressed by data_ptr
ext_value_size | Size of data addressed by ext_value
funcs | User exit support functions
field_name | Name of data item in COBOL program's Linkage Section
data_ptr | Internal data value associated with field_name
ext_param_name | Name of external parameter
ext_value | External data value associated with field_name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
exit_data User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied internal value

Comments:

This exit gives you the opportunity to override the internal data value created by the request handler’s default mapping from the external data value provided by the client request for the given COBOL program Linkage Section data item name. data_ptr addresses the memory created by the request handler to be passed to the user program as part of its Linkage Section. If the exit chooses to override this parameter, it must only modify up to data_size bytes starting at data_ptr, and must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Unmapped Named External Input Parameter (Exit Point 3)

Allows you to handle an unmapped named external input parameter that has been specified in the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
3 = Unmapped named external input parameter
exit_info
version
Version of structure format
flags
0
ext_value_size
Size of data addressed by ext_value
funcs
User exit support functions
ext_param_name
Name of external parameter
ext_value
External data value associated with field_name
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
service_type | Type of client request
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
exit_data
User exit-specific data

On Exit:

exit_info
flags
0
request_cxt
accept_buf_len | Length of data in accept_buf
cmd_line _len | Length of data in cmd_line
flags | Request context control flags
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden one or more of the returned request context fields

Comments:

This exit gives you the opportunity to handle an unmapped named external input parameter that has been specified in the client request. The exit program would typically handle the parameter by setting an appropriate value in one or more of the data areas addressed by argv, setting up data to be used for ANSI ACCEPT statements (accept_buf), or setting up the application’s command line (cmd_line). The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used for the setting up of accept_buf or cmd_line. If the exit chooses to override any of the request context fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Input Request Processing (Exit Point 4)

Allows you to initialize parameter values in the internal data areas addressed by argv other than those initialised during external parameter mapping.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32   exit_point,
                                  IDP_EXIT_INFO *exit_info);

On Entry:

exit point
4 = End of input request processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
service_type | Type of client request
accept_buf_len | Length of data in accept_buf
cmd_line_len | Length of data in cmd_line
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

On Exit:

exit info
flags
0
request_cxt
argc | Parameter count of loaded service
service_type | Type of client request
accept_buf_len | Length of data in accept_buf
cmd_line_len | Length of data in cmd_line
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden one or more of the returned request context fields

Comments:

This exit gives you the opportunity to initialize parameter values in the internal data areas addressed by argv other than those initialized during external parameter mapping. The exit can optionally modify any of the returned request fields listed above. The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used to replace request context strings (for example, service_name or epoint_name) or argv fields. If the exit chooses to override any of the request context fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Start of Response Processing (Exit Point 5)

Allows you to bypass completely the default response processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
5 = Start of response processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
return_code | Service's return code, or run-time error generated by service
service_type | Type of client request
display_buf_len | Length of data in display_buf
flags | Request context control flags
protocol_attrs | An array of pointers to protocol-specifc attributes
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
display_buf | Concatenation of strings output by ANSI DISPLAY statements
response
flagss | Control flags
response_type | Server's response type
exit_data
User exit-specific data

On Exit:

exit_info
flags
0
response
response_len | Length of response_buf
flags | Control flags
response_buf | Server's response buffer
content_type | NULL-terminated content type string (HTTP) only
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default response processing
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
2 = The entire response has been built by the exit. No further processing is required. The response is ready to be sent back to the client.

Comments:

This exit gives you the opportunity to bypass completely the default response processing. If the exit wants the default response processing to be bypassed, it must set up the response fields indicated above as being returned fields, using the fn_alloc_mem support function of the exit_info funcs structure to allocate the memory for the response buffer, and return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Internal Data Value Modification - Output Parameter (Exit Point 6)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
6 = Internal data value modification - output parameter
exit_info
version | Version of structure format
flags | 0
data_size | Size of data addressed by the data_ptr field
funcs | User exit support functions
field name | Name of data item in COBOL program's Linkage Section
data_ptr | Internal data value associated with field_name
ext_param_name | External parameter name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
The exit has overridden the supplied internal data value

Comments:

This exit gives you the opportunity to override the internal data value created during the execution of the application. data_ptr addresses the memory assigned to the internal data value. If the exit chooses to override this parameter, it must only modify up to data_size bytes starting at data_ptr, and must return IDP_EXIT_HANDLED. The request handler will subsequently perform default mapping for the original (IDP_EXIT_CONTINUE) or overridden (IDP_EXIT_HANDLED) internal data value.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


External Data Value Modification - Output Parameter (Exit Point 7)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
7 = External data value modification - output parameter
exit_info
version | Version of structure format
flags | 0
ext_value_size | Size of data addressed by the ext_value field
funcs | User exit support functions
field name | Name of data item in COBOL program's Linkage Section
ext_param_name | Name of external parameter
ext_value | External data value associated with the field_name field
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
ext_value_size | Size of data addressed by the ext_value field. Needs to be updated only if the user exit allocates memory for a new ext_value string
ext_value | External data value to be associated with field_name. Needs to be updated only if the user exit allocates memory for a new ext_value string
exit_data | User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied external data value. Use this value to perform default mapping for the given COBOL Linkage Section field name
IDP_EXIT_OMIT
3 = The exit has determined that the given parameter should not be included in the response

Comments:

This exit gives you the opportunity to override the external value created by the request handler in its default mapping processing for the given COBOL Linkage Section field name. If the exit chooses to override the external value, it must return IDP_EXIT_HANDLED and either update ext_value in place (if the replacement value is less or equal to ext_value_size), or allocate a replacement string using the support function fn_alloc_mem and set ext_value and ext_value_size accordingly. The request handler will use the returned ext_value (IDP_EXIT_CONTINUE or IDP_EXIT_HANDLED) in its default response processing.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Response Processing (Exit Point 8)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
8 = End of response processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
service_type | Type of client request
display_buf_len | Length of data in display_buf
flags | Request context control flags
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
display_buf | Concatenation of strings output by ANSI DISPLAY statements
response
response_len | Length of response_buf
flags | Control flags
response_buf | Response buffer created by default mapping or overridden by the exit
content_type | NULL-terminated content type string (HTTP only)
exit_data
User exit-specific data

On Exit:

exit_info
response
response_len | Length of response_buf
response_buf | Response buffer
content_type | NULL-terminated content type string (HTTP only)
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate response processing. The default response is not to be sent. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the default response

Comments:

This exit gives you the opportunity to override the full response generated by default mapping. The exit can optionally modify any of the returned request fields listed above. The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used to replace the response_buf field. If the exit chooses to override any of the response structure fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Request Processing (Exit Point 9)

Allows you to release any resources that were allocated in exit points 0 through 8.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
9 = End of request processing
exit_info
version | Version of structure format
flags | 0
funcs | User exit support functions
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

None

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = An error has occurred during end of request processing

Comments:

This exit gives you the opportunity to release any resources that were allocated in exit points 0 through 8.

Parent topic: Exit Points


Configuring Whether a Message Shows in the Console

The user exit casmguex controls whether a particular message is output to the console or not.

To enable the user exit, it must be in a directory included on the appropriate program search concatenation. casmguex is then invoked by the SEP before sending the processed message to the console daemon.

The entry point of casmguex is a single parameter defined as a group item:

           03 MsgRB-Buffer.
              05 MsgRB-Buffer-Length   pic x(2) comp-x value 256.
              05 MsgRB-Buffer-Text.
                 07 MsgRB-Buffer-Char pic x
                    occurs 256 times depending on MsgRB-Buffer-Length.

The user exit examines the message and then determines whether to display it in the console or not. This is controlled through the use of return-code using the following values:

1
Display message
0
Do not show message

Example

The following sample program shows how you can use casmguex to prevent the error message FC0009I from showing:

       identification division.
       program-id. casmguex.
       environment division.
       configuration section.
       data division.
       working-storage section.
       local-storage section.
       linkage section.
       01  MsgRB-Buffer.
           03  MsgRB-Buffer-Length     pic x(2) comp-x.
           03  MsgRB-Buffer-Text.
               05  MsgRB-Buffer-Char   pic x
                occurs 256 times depending on MsgRB-Buffer-Length.
       procedure division using MsgRB-Buffer.
           move 1                      to return-code
           if MsgRB-Buffer-Text(4:7) = 'FC0009I'
           move 0                  to return-code
           end-if

           goback.

       end program casmguex.
Parent topic: Exit Points


Support Functions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following support functions are available:

  • PFI
    A generic type definition for a function that returns an integer value.
  • PFI_IDPES_FN_DISPLAY_TO_UTF16
    Converts COBOL DISPLAY encoded strings to UTF-16 encoded strings.
  • PFI_IDPES_FN_UTF16_TO_DISPLAY
    Converts UTF-16 encoded strings to COBOL DISPLAY encoded strings.
  • PFV_IDPES_FN_ALLOC_MEM
    Allocates memory for user exits to use.
  • PFV_IDPES_FN_FREE_MEM
    Frees memory previously allocated for user exits to use.
Parent topic: User Exits


PFI

A generic type definition for a function that returns an integer value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cobrtncode_t (*PFI)();

On Entry:

None

On Exit:

None

Function returns:

An integer

Parent topic: Support Functions


PFI_IDPES_FN_DISPLAY_TO_UTF16

Converts COBOL DISPLAY encoded strings to UTF-16 encoded strings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDPES_FN_DISPLAY_TO_UTF16)(
                                                cobuns8_t  in_string,
                                                cobuns32_t in_len,
                                                cobuns8_t  out_string,
                                                cobuns32_t *out_len);

On Entry:

in_string | COBOL DISPLAY encoded string
in_len | Size of in_string
out_len | Maximum size of out_string, or 0 for function to return the required size of out_string

On Exit:

out_string | UTF-16 encoded string
out_len | Size of out_string, or required size if 0 specified on input, or if function returns IDPES_BUFFER_TOO_SMALL

Return codes:

0 | IDPES_SUCCESS
1 | IDPES_BUFFER_TOO_SMALL

Comments:

Used by user exits to convert COBOL DISPLAY encoded strings into UTF-16 encoded ones

Parent topic: Support Functions


PFI_IDPES_FN_UTF16_TO_DISPLAY

Converts UTF-16 encoded strings to COBOL DISPLAY encoded strings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDPES_FN_UTF16_TO_DISPLAY)(
                                                cobuns8_t  in_string,
                                                cobuns32_t in_len,
                                                cobuns8_t  out_string,
                                                cobuns32_t *out_len);

On Entry:

in_string | UTF16 encoded string
in_len | Size of in_string
out_len | Maximum size of out_string, or 0 for function to return the required size of out_string

On Exit:

out_string | COBOL DISPLAY encoded string
out_len | Size of out_string, or required size if 0 specified on input, or if function returns IDPES_BUFFER_TOO_SMALL

Return codes:

0 | IDPES_SUCCESS
1 | IDPES_BUFFER_TOO_SMALL

Comments:

Used by user exits to convert UTF-16 encoded strings into COBOL DISPLAY encoded ones

Parent topic: Support Functions


PFV_IDPES_FN_ALLOC_MEM

Allocates memory for user exits to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void *(*PFV_IDPES_FN_ALLOC_MEM)(cobuns32_t mem_size);

On Entry:

mem_size Number of bytes to allocate

On Exit:

None

Function returns:

A pointer to the allocated space, or NULL if there is insufficient memory available or an error occurs during the allocation process.

Comments:

Used by user exits to allocate memory, for example, for the creation of a replacement external data value during exit point 7, External Data Value Modification - Output Parameter. If you allocate memory using this function you should subsequently free it using the fn_free_mem support function of IDP_EXIT_SERVICE_FUNCS.

Parent topic: Support Functions


PFV_IDPES_FN_FREE_MEM

Frees memory previously allocated for user exits to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void *(*PFV_IDPES_FN_FREE_MEM)(void *mem);

On Entry:

mem Memory to be freed

On Exit:

None

Function returns:

Nothing

Comments:

Used by user exits to free memory previously allocated via the fn_alloc_mem support function of IDP_EXIT_SERVICE_FUNCS.

Parent topic: Support Functions


Structures

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following structures are available:

  • IDP_EXIT_INFO
    Contains the information passed between the request handler and the user exit program.
  • IDP_EXIT_SERVICE_FUNCS
    Contains the information passed between the request handler and the user exit program.
  • REQHAND_RESPONSE
    Contains the response to the client request.
  • REQUEST_CONTEXT
    Contains information about the client request.
Parent topic: User Exits


IDP_EXIT_INFO

Contains the information passed between the request handler and the user exit program.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct idp_exit_info
{
    cobuns32_t             version;         Version of structure format
    cobuns32_t             flags;           Reserved for future use
    cobuns32_t             data_size;       Size of data addressed by data_ptr
    cobuns32_t             ext_value_size;  Size of data addressed by ext_value
    cobuns32_t             reserved1[10];   Reserved for future use
    IDP_EXIT_SERVICE_FUNCS *funcs;          User exit support functions
    cobuns8_t              *field_name;     COBOL Linkage Section item’s name (COBOL DISPLAY encoded)
    void                   *data_ptr;       Internal data value associated with field_name
    cobuns8_t              *ext_param_name; External parameter name (COBOL DISPLAY encoded)
    cobuns8_t              *ext_value;      External data value associated with field_name (UTF-16 encoded)
    REQUEST_CONTEXT        *request_cxt;    Request context
    REQHAND_RESPONSE       *response;       Response details
    void                   *exit_data;      User exit-specific data
    void                   *reserved2[10];  Reserved for future use
}IDP_EXIT_INFO;
Parent topic: Structures


IDP_EXIT_SERVICE_FUNCS

Contains the information passed between the request handler and the user exit program.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct idp_exit_service_funcs
{
    cobuns32_t                    version;         Version of structure format
    cobuns32_t                    reserved;        Reserved for future use
    PFV_IDPES_FN_ALLOC_MEM        fn_alloc_mem;    Function to allocate memory
    PFV_IDPES_FN_FREE_MEM         fn_free_mem;     Function to free memory allocated by fn_alloc_mem
    PFI_IDPES_FN_DISPLAY_TO_UTF16 fn_disp_to_utf16 Function to convert from a COBOL DISPLAY encoded format to a UTF-16 encoded format
    PFI_IDPES_FN_UTF16_TO_DISPLAY fn_disp_to_utf16 Function to convert from a UTF-16 encoded format to a COBOL DISPLAY encoded format
    PFI                           fn_reserved[10]; Reserved for future use
} IDP_EXIT_SERVICE_FUNCS;
Parent topic: Structures


REQHAND_RESPONSE

Contains the response to the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct reqhand_response
{
    cobuns32_t version;       Version of structure format
    cobuns32_t response_len;  Length of response buffer
    cobuns32_t flags;         Control flags
    cobuns32_t response_type; Server response type
    void       *response_buf; Server response buffer
    void       *content_type; NULL terminated string (HTTP)
}REQHAND_RESPONSE;
Parent topic: Structures


REQUEST_CONTEXT

Contains information about the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct request_context
{
    cobuns32_t            version;            Version of structure format
    cobuns32_t            handler_id;         ID of request handler being used to process the request
    cobuns32_t            request_len;        Length of request buffer
    cobuns32_t            argc;               Parameter count of loaded service
    cobrtncode_t          return_code;        Service’s return code, or run-time error error generated by service
    cobuns32_t            service_type;       Type of service request
    cobuns32_t            accept_buf_len;     Length of data in accept_buf
    cobuns32_t            display_buf_len;    Length of data in display_buf
    cobuns32_t            cmd_line_len;       Length of data in cmd_line
    cobuns32_t            flags;              Request context control flags
    cobuns32_t            reserved1[11];      Reserved for future use
    REQHAND_SERVICE_FUNCS *funcs;             Request handler support functions
    void                  *request_buf;       Request buffer
    void                  **protocol_attrs;   An array of pointers to protocol-specific attributes
    cobuns8_t             **argv;             Parameter list of loaded service
    void                  *handler_data;      Request handler-specific data
    cobuns8_t             *reserved1a;        Reserved for future use
    cobuns8_t             *service_name;      Name of loaded service
    cobuns8_t             *pgm_name;          Name of the main program associated with the service
    cobuns8_t             *epoint_name;       Name of entry point of the program to invoke
    void                  *idt;               Interface definition for service; the interpretation of the memory addressed by this field is request handler-specific
    cobuns8_t             *accept_buf;        Data to be used for ANSI ACCEPT statements
    cobuns8_t             *display_buf;       Concatenation of strings output by ANSI DISPLAY statements
    cobuns8_t             *cmd_line;          String to be used to resolve ACCEPT FROM COMMAND-LINE
    cobuns8_t             *rts_err_str;       Run-time error message text
    void                  *reserved2[9];      Reserved for future use
} REQUEST_CONTEXT;
Parent topic: Structures


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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • 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: Deploying to Enterprise Server


Securing an Enterprise Server Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the security features available in an Enterprise Server installation, and how you can use these features to implement a security policy.

This help also includes the context-sensitive information available from the user interface. To access the help, select Help > This Page from the left pane.

Note: The context information in this help volume is the most up-to-date version.
  • Architecture and Overview
  • Configuring Enterprise Server Security
  • Configuring External Security Facility (ESF) from the Command Line
  • Using the MFDS Internal Security Module
  • MLDAP ESM Module
  • 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.
  • Security Reference Information
  • Using External Security Facility (ESF) Features
  • Glossary
Parent topic: Enterprise Server Security


Architecture and Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the Enterprise Server security architecture, and provide an overview of the configuration process.

  • About Securing an Enterprise Server Installation
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Enterprise Server security architecture accommodates mainframe-style security for:

  • Migrated applications
  • The security mechanisms found in distributed systems
  • Custom solutions

This architecture allows you to configure multiple security mechanisms and repositories, so that you can separate the management of different types of resources.

Communication between clients and the server can be secured through the use of SSL.

  • System Components and Process Flows
  • About the External Security Facility (ESF)
  • About Security Managers
  • About Security Queries
  • Designing the Security Policy
Parent topic: Architecture and Overview


System Components and Process Flows

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When a user attempts to access an Enterprise Server feature or application, or when an application attempts to access a controlled resource, Enterprise Server's External Security Facility (ESF) submits a security query to the appropriate ESMs to authenticate or authorize the action.

The illustration below shows the components involved in securing an installation, and the communications between each.

  • When they log on to a system, Enterprise Server administrators are authenticated against any security managers that are configured for the Directory Server. Access to Enterprise Server configuration is denied unless the authentication is successful.
  • When an Enterprise 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.

Parent topic: Security Architecture


About the External Security Facility (ESF)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The ESF operates for both Enterprise Server and Directory Server access.

The ESF relays application and resource access authorization request queries to the security manager or Managers. It is responsible for:

  • Loading and invoking security managers
  • Sending security queries to the security managers
  • Managing a cache of the modules and security access query results
  • maintaining configuration information for itself and the security managers

The ESF performs security checks by making API calls to the ESMs, and processing the result that is returned. You can use this API to develop your own security managers. You can then use these security managers to process authentication requests, and allow or deny access as appropriate. A security manager can be anything that can process ESF API calls.

The External Security Facility API documentation is available, in doxygen format, on the Micro Focus Supportline website's Examples and Utilities page.

  • Follow this link to the Examples and Utilities page:

    Micro Focus Supportline Examples and Utilities page

  • Follow this link to the External Security Facility API documentation, which contains information on how to configure your ESF to work with any ESMs that are deployed. The API also contains error message and return code explanations:

    External Security Facility Manager API

If no security manager recognizes a user, that is each security manager returns unknown, you can configure a default response.

Parent topic: Security Architecture


About Security Managers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Security managers process the security queries generated by the ESF, and return either an allow, deny or unknown status. You can configure multiple security managers in an installation's security manager pool. From the pool, you can create a default list of the security managers to use and lists for individual Enterprise Servers.

Note: Security managers are sometimes 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, determine a user's access level and apply permissions accordingly.
mldap_esm
This security manager allows you to integrate your Enterprise Server security with an LDAP. You can use mldap_esm with both Microsoft Active Directory, and other LDAPs, for example OpenLDAP. With mldap_esm, you can implement access control for users, and for the resources and files that an application uses.
MFDS Internal Security
Directory Server security can be implemented 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 allows you to define users and groups, and restrict access to Enterprise Server administration functions.

In addition to the above, a security managers can be anything that processes the API security queries that the ESF generates, and can return results to the ESF. You can develop a security manager to suit your requirements. A security manager could be a database, a directory, or an operating system mechanism.

Parent topic: Security Architecture


About Security Queries

Restriction: This topic applies only when the Enterprise Server feature is enabled.

During applications processing and the running of the Directory Server, Enterprise Server submits security queries to the External Security Facility (ESF), to verify that a user or system action is authorized. The ESF generates the appropriate API call and forwards this request to each configured security manager in turn.

The most common security queries are:

  • Authenticating user credentials, for example when the user signs on.
  • Checking that a user has the appropriate authorization to perform a particular task on a particular resource

A successful verify query establishes a security context (such as a session logon) within which further operations are performed. If the user or application performs subsequent operations outside this context, further authorization calls are made to check that he or she has appropriate authorization.

The verify query is used only by MF Directory Server. It implements more modern discretionary access controls (DACs). Permissions are separate from one another. For example, a user can have write access but not read access to a resource.

Parent topic: Security Architecture


Designing the Security Policy

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The design and introduction of security policy requires careful planning to ensure that the measures adopted are appropriate to the systems being used. Such considerations are beyond the scope of this documentation. This topic gives a brief overview of the steps involved in using the Security Facility to control user authentication and authorization, and resource access control.

  1. Before you can use the Security Facility, you must decide which external security managers you are going to use and, if you plan to use multiple security managers, how you want to divide the responsibilities between them. Most installations use a single external security manager.
  2. Having done this you must define, within the repositories used by those managers, the users, resources and rules that you require. This may involve migration of user and resource details from legacy Directory Server and Enterprise Server security definitions, and in the case of LDAP repositories used with the MLDAP ESM Module, modifications to the schema to support the security information.
  3. The next step is to specify within Directory Server the security managers, the ESM Modules that will be used to connect to them, and the associated configuration information. In doing this you create a pool of security manager definitions from which you can choose the ones that you require for particular enterprise servers.
  4. At this point, you can begin to define security configuration options. You can have different configuration options for individual enterprise servers, and for Directory Server. You can also have a default configuration that applies to any enterprise server that does not have its own configuration.
  5. The configuration options include an ordered list of references to the security managers that you will use. Hence, as with the other options, you can use different lists for Directory Server and individual enterprise servers, and you can have a default list used by multiple servers.

    The order of the managers on the list determines the order in which they are queried when handling a security request, and this may, depending on other configuration options, affect the result of a query.

    You can now add the appropriate security managers from the security manager pool to the list that you are using.

Parent topic: Security Architecture


Configuring Enterprise Server Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You configure security using the Enterprise Server Administration user interface. You can use this interface to configure installation-wide security configurations, and to configure security for each enterprise server in the installation. This section details the tasks required to do this.

  • Security Configuration Stages
  • Adding a Security Manager to the Pool
  • Enabling a Security Manager
  • Defining a Security Manager List
  • Setting MF Directory Server Security Configuration
  • Customizing the Security Settings for an Enterprise Server Instance
  • Implementing Security Manager Changes
Parent topic: Securing an Enterprise Server Installation
Related concepts
About the External Security Facility (ESF)


Security Configuration Stages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Configuring the security managers to use involves the following stages:

  1. Add the security managers that you plan to use to the pool, so that they are available for use in your configurations.
  2. Define the list of the security managers to use with Enterprise Server instances, and the order in which they are used.

    You can then use this configuration with multiple Enterprise Server instances

  3. Repeat the previous step to define the security configuration for the Micro Focus directory server.
    Note: To avoid issues with resource access, it is recommended that you use the same configuration for Micro Focus directory server and the enterprise server instances that it manages.
  4. Customize the security configuration for each enterprise server that requires it.
  5. Update security managers as required, and implement the changes.
Parent topic: Configuring Enterprise Server Security


Adding a Security Manager to the Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can use an External Security Manager (ESM) in your configuration, either in the default security configuration or to configure individual enterprise servers, you need to make it available by adding it to the MFDS security manager pool.

Once it is in the pool, you can configure it and set it to verify access.

  • To Add or Remove a Security Manager in the Pool
  • To Edit a Security Manager's Properties
Parent topic: Configuring Enterprise Server Security


To Add or Remove a Security Manager in the Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security .
  2. Click the Security Managers tab, and click Add.
  3. Specify the details of the ESM to add. The minimum information required is a unique name with which to identify the definition, and the name of the external security manager module that will be used to pass security queries to the relevant external security manager. At the left of the screen, select the Help > This Page option for detailed information on the options.
  4. Click Add.

    The ESM is added to the pool and is available for use in your configurations.

To remove an ESM from the pool, select it and click Remove.
Parent topic: Adding a Security Manager to the Pool


To Edit a Security Manager's Properties

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Once you have added a security manager to the pool, you can edit its properties.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the Security Managers tab, and in the list, select the security manager to edit.
  3. Click Edit.
  4. Specify the details of the security manager.
    Name

    Specify the name used to identify the security manager.

    Module

    Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc .

    Connection Path

    If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

    The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

    Authorized ID and Password

    If the module requires credentials to connect to the external security manager, specify them here.

    As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

    Enabled

    Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

    Cache limit

    If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

    This parameter is currently ignored by the ESM Module.
    Cache TTL

    If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

    This parameter is currently ignored by the ESM Module.

    Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
    Description

    Specify a description of the security manager.

    Configuration information

    Specify any additional configuration settings that the module requires.

    Properties

    Click this to access pages for the management of users, groups and resources controlled by this security manager.

    Important: You will only be able to manage users, groups and resources where the security manager is on the priority list used by Directory Server. That is:
    • if Directory Server uses the Default ES Security configuration, the security manager must be on the Default ES Security manager list
    • if Directory Server uses its own configuration options, the security manager must be on the Directory Server's own security manager list

    In addition, the ESM module and the external security manager to which it connects must also support user, group and resource administration via the Security Facility.

  5. Click OK to save the changes and return to the Security Managers screen. Alternatively, click Apply to save the changes and remain on the current screen.
Parent topic: Adding a Security Manager to the Pool


Enabling a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A security manager must be enabled before it can be used to manage securit. If a security manage is disabled, it is ignored by Micro Focus Directory Server and by all enterprise servers instances.

To disable the security manager for Micro Focus Directory Server only, or for a particular enterprise server in your installation, you must remove it from the relevant security manager list.

  • To Enable or Disable a Security Manager
Parent topic: Configuring Enterprise Server Security


To Enable or Disable a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security.
  2. Click Security Managers.
  3. Select the security manager to enable or disable, and click Edit.
  4. Check or un-check Enabled, and click OK.
    Note:

    This globally disables the security manager, so that it is ignored by Directory Server and by all enterprise servers. If you only wish to disable the security manager for Micro FocusDirectory Server or for a particular enterprise server, you must remove it from the relevant security manager list.

Parent topic: Enabling a Security Manager


Defining a Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Once you have added security managers to the pool, you can create a default list of the security managers to use, and select to enable or disable each. If you disable a security manager, it is not used in the authorization process, even when it appears in the list of security managers to apply.

This list is used by default for each new Enterprise Server instance that you create.

  • To Add a Security Manager to the Default ES Security Manager List
  • To Set Default Enterprise Server Security Configuration
Parent topic: Configuring Enterprise Server Security


To Add a Security Manager to the Default ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Default ES Security.
  3. In the Security Manager List, click Add.
  4. Select the definition that you want to add to the list by clicking the relevant radio button in the Select column.
  5. Click Add .
Note:
  • You cannot add the same definition to the list more than once. You can however have more than one security manager definition that uses the same external security module in the security managers pool.
  • Where you are running MF Directory Server with Restrict administration access set, and you make a change to the security manager list that it uses, you are challenged to supply:
    1. a set of credentials that are valid with the configuration prior to the changes being applied

      and

    2. a set of credentials that will be valid with the configuration after the changes are applied. This is to ensure that you can still access the MF Directory Server screens.

    If appropriate credentials are not supplied or are not valid, the changes will not be applied.

Parent topic: Defining a Security Manager List


To Set Default Enterprise Server Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can create a list of security managers to use as a default. Enterprise servers can use this as the default configuration. You must have added security managers to the pool before they can be configured in the default list.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security .
  2. Click the Default ES Security tab.

    The default security manager list is displayed.

  3. Select the security manager, and use the Up and Down arrows at the right of the list to position the security manager where you want it.

    When performing security checks, Enterprise Server validates against the security managers in the order in which they appear in the list.

  4. Complete the rest of the configurations on the screen.

    At the left of the screen, select the Help > This Page option for detailed information on the options.

Parent topic: Defining a Security Manager List


Setting MF Directory Server Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure the security configuration for the directory server. You can select to use the default MFDS Internal Security or you can configure security managers to validate against.

Note:
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server, you can use the default security manager configuration, or you can configure the security managers to use for the particular server.

  • To Set Security Configuration Options for an Enterprise Server
Parent topic: Configuring Enterprise Server Security


To Set Security Configuration Options for an Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server, you can use the default ESM configuration, or you can configure the ESMs to use for the particular server.

  1. From the Enterprise Server Administration home page, click Edit for the relevant enterprise server.
  2. Click the Security tab.
  3. To use the default set of configuration settings, check Use default security configuration.
  4. To use a non-default configuration, add the ESMs to use in the Security Manager List area at the bottom of the screen.
  5. Use the Up and Down arrows at the right of the list to position the ESM where you want it.

    When performing security checks, Enterprise Server validates against the ESMs in the order in which they appear in the list.

  6. Complete the rest of the configurations on the screen.

    At the left of the screen, select the Help > This Page option for detailed information on the options.

  • 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:

[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.

By default, this is set to 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.

By default, this is set to no.

[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.

[Cache] section

flush on change=yes | no
Set to yes to tell the cache that it should 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.
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.

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 may 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 be 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.

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.

By default, redundant is set to no.

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 may 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.

[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.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are using an external security manager and you make changes to the security information (such as adding a user or changing group membership), there are two ways in which you can notify Enterprise Server so that it uses the updated information:

  • The Enterprise Server Administration interface
  • The esfupdate utility
  • To Update using the Enterprise Server Administration Interface
  • To Update Security Manager Changes Using esfupdate
Parent topic: Configuring Enterprise Server Security


To Update using the Enterprise Server Administration Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use the Enterprise Server Administration Interface to update a server instance with changes to a security manager:

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the Security Managers tab.
  3. Below the list of configured security managers, click Update Allon the Security Manager Pool page.

    This retrieves the latest security information from the external security manager.

Use the following steps to update the security managers used by the Directory Server:

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the MF Directory Server tab.
  3. Check the Update when external Security Manager properties change check box.
Parent topic: Implementing Security Manager Changes


To Update Security Manager Changes Using esfupdate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are using an external Security Manager and changes are made to the security information (such as adding a user or changing group membership), there are two ways in which you can notify Enterprise Server so that it uses the updated information:

  • The Enterprise Server Administration interface
  • The esfupdate utility

This topic describes the steps required to use the esfupdate utility.

The syntax of the esfupdate utility is as follows:

esfupdate [options]update-type[entity-name]
Options
A series of actions to perform. Possible values are:
Switch | Action | Meaning
-a | action | The update action to perform. One of "add", "delete", "modify" or "other". The default is "modify".
-u | user | The username for binding to Directory Server.
-p | password | The password for binding to Directory Server.
-m | host[:port] | The location of Directory Server. The default is localhost:86.
-r | server | The name of the server(s) to update. This can include wildcards.
-M | Updates the Directory Server.
-v | Displays version information and exit.
-h | Displays syntax information and exit.
update-type
One of "user", "group", "resource", "users", "groups", "resources", or "all".
entity-name
Must be supplied if update-type is "user", "group" or "resource". Otherwise omitted.

Comments

If user and password are not supplied, esfupdate attempts to bind to Directory Server anonymously.

If user is supplied but not password, you will be prompted for it.

If neither -M nor -r are specified, update notifications are sent to Directory Server and all running servers.

The example below notifies the Directory Server and any running enterprise servers that the user SAFU has been modified. This could mean that it has been added to (or removed from) a group. It will bind to Directory Server as the "SYSAD" user.

esfupdate -u CN=SYSAD -p SYSAD user SAFU
Parent topic: Implementing Security Manager Changes


Configuring External Security Facility (ESF) from the Command Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.

esfadmin is a command-line utility that calls the ESF Admin API to request administrative actions against ESMs. It is a part of Visual COBOL and COBOL Server, and can be found in the $COBDIR\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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The esfadmin command line includes options, a subcommand, and one or more parameters.This section discusses subcommands and parameters.

Each subcommand is a single word, telling esfadmin what task you want to perform. Parameters are name and value pairs in the form name=value. If the value contains spaces or other characters that are significant to the command processor or shell you’re using, you’ll need to quote or escape them. Subcommands and parameter names are case-insensitive, but parameter values may be case-sensitive, depending on the parameter and the ESMs that process the request.

For each subcommand, one or more parameters identifies the object (user, group, resource class, or resource access control definition) you’re operating on. These parameters are required. Other parameters set attributes of that object; they are optional in most cases. Note that some ESMs may require certain parameters be set even if ESF doesn’t. For example, the standard LDAP schema supplied by Micro Focus requires that resource objects have a value for the microfocus-MFDS-Resource-class attribute (even though it’s not used—this is for historical reasons), which is set by the “class” parameter when using esfadmin, so if you try to add a resource object without specifying class=somevalue you will get an error. These requirements are noted below.

The UID attribute is a special case. It is required by the LDAP schema, but if you do not supply one for an ADD operation, the MLDAP ESM Module will generate one for you.

Most of the subcommands have the same form: ADD, ALT (alter), DEL (delete), or LIST, followed by an object type: USER, GROUP, CLASS, or RESOURCE. There are also SETPASSWORD and SETOPTIONS commands. ADD and ALT commands are described in the same topic, since they use the same parameters.

The LISTx commands list all matching objects (see the LISTUSER topic for an example of using a pattern with wildcards for a list command) and their attributes. The SETPASSWORD command is used to reset a user’s password. The SETOPTIONS command is not currently used.

  • esfadmin Command Syntax
  • esfadmin Usage Notes
  • Setting User Passwords with esfadmin
Parent topic: Configuring External Security Facility (ESF) from the Command Line
Related reference
esfadmin Command Syntax


esfadmin Command Syntax

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

esfadmin [options] subcmd [keyword=value | keyword]...

Used to update the security definitions in active External Security Managers. It calls the Enterprise Server External Security Facility (ESF) to submit requests.

Parameters:

The options are:

-a | Do not audit. By default, esfadmin sends audit information for each request to the ESF Audit Facility.
-cconfig file Specifies the name of a configuration file for the MLDAP ESM Module. This is a text file, in the same format as the "Configuration Information" area in the Security Manager definition.

Usage: esfadmin -cldap-config.txt where ldap-config.txt contains:

[LDAP]
base=CN=Micro Focus,
CN=Program Data,
DC=mycorp,DC=com
-uESF user A valid ES account that is being used to sign on to the ESF. The default is: SYSAD

Usage:

esfadmin -uSYSAD

-pESF password. | The associated password. The default is: SYSAD
-UESM user A valid username for the External Security Manager; for example, with MLDAP, a user account with appropriate access to the LDAP repository.

If this is not supplied, then for commands other than the LIST commands, esfadmin prompts for the ESM username. (For LIST commands, esfadmin lets the ESM module use its default credentials.

-PESM password The associated password.

If this is not supplied, then for commands other than the LIST commands, esfadmin prompts for a password.

-Sserver URL Specifies the connection path for the LDAP server.

Usage:

esfadmin -S ldap://adhost

-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.

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 should be entered with no spaces between the keyword, the equal sign, and the value. Values that contain spaces or other special characters should be quoted, as required by the shell.

Parent topic: About the esfadmin Command
Related concepts
esfadmin Usage Notes
About the esfadmin Command
esfadmin Sub-commands
Related information
Setting User Passwords with esfadmin


esfadmin Usage Notes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Note the following points when using esfadmin:

  • You cannot move or rename an object in the security manager because you cannot specify the parameter once to identify it, and then again to give it a new name. You must use ADDx to create the new one, and then DELx to delete the old one. The ALTx commands will let you change the other parameters of an object, for the most part.
  • You can't change a resource's class by changing its CLASS attribute. That attribute exists (and must have a value), but that is a historical vestige. To change a resource's class, you have to create a new resource of the same name under the new class using ADDRESOURCE, and then delete the old one.
  • LISTUSER shows a user's group memberships, for convenience, but that is not actually an attribute of a user. You can't use ALTUSER to change what groups a user belongs to (except for the user’s default group). You have to use ALTGROUP to change a group to add or delete a user from it.
  • If you are listing many users, or have many groups, it might take a long time for LISTUSER to generate the group-membership information. You can tell LISTUSER not to include group membership by adding COMPUTED=NO to the esfadmin command line.
  • LISTRESOURCE can only list resources from a single class. To list all resource definitions matching a certain pattern, you must use one LISTRESOURCE command per resource class.
  • By default, the LISTUSER, LISTGROUP, LISTCLASS, and LISTRESOURCE commands will perform wildcard searches if you specify a name with the "*" wildcard character. For example, esfadmin LISTUSER USER=A* will list all users with names beginning with "A".

    This might not be the desired behavior, particularly when listing resource rules, since those often contain wildcard characters. You can tell the LIST commands to treat the "*" character as a literal character (and not a wildcard) by adding LITERAL=YES to your esfadmin command line.

  • When you change a group member list with ALTGROUP, you completely rewrite it. Be careful to ensure that only one administrator is changing a group’s membership at a time, or changes could be lost. Alternatively, use the new ADDMEMBER and DELMEMBER commands.
  • To change a resource's access control list (ACL), you list the ACEs as the value of the ACL parameter, separated by semicolons or newlines. For example:

    esfadmin ... ALTRESOURCE ...

    ACL="allow:SYSADM group:read;allow:CICSUSER:read"

    This has the same issue as updating group membership—it replaces the entire ACL, so make sure you have all the ACEs you want in the string, and watch out for races if multiple people might be making updates at the same time. Alternatively, use the new ADDACE, ALTACE, and DELACE commands.

Parent topic: About the esfadmin Command
Related reference
esfadmin Command Syntax
ADDGROUP and ALTGROUP
ADDCLASS and ALTCLASS
ADDRESOURCE and ALTRESOURCE
ADDUSER and ALTUSER
DELCLASS
DELGROUP
DELRESOURCE
DELUSER
LISTCLASS
LISTGROUP
LISTRESOURCE
LISTUSER


Setting User Passwords with esfadmin

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you edit a user's password (the microfocus-MFDS-User-Pwd attribute) directly in the LDAP repository, using a tool such as ADSIEdit, you can only set a literal password value. This is often not satisfactory because the password can be seen by anyone who can read the repository.

If you have enabled MFDS administration of the LDAP repository, you can use MFDS to change a user's password. To do this, go to the MFDS security options, view the list of Security Managers, select the MLDAP manager, click the Properties button, edit the user, and set a new password. See the MFDS documentation for more information.

Another alternative is to use the esfadmin utility.

To set a password using the esfadmin command, you will need a valid ES username and password (not necessarily the user whose password you're setting), and an LDAP username and password for an account with write access to the user's record in the repository. esfadmin has to sign on to ESF before it can perform an admin request, which is why you need an ES username / password.

You set a password using the setpassword option:

esfadmin [options] setpassword user=username password=new-password

esfadmin will prompt for the LDAP user ID and password. (The user ID is usually specified as an LDAP DN, eg CN=admin,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local; or as a Windows username with domain, eg domain\admin.) You can also specify these on the command line using the -U and -P options (note these must be uppercase-U and uppercase-P).

By default esfadmin uses "SYSAD", one of the default accounts created during setup, for the ES username and password it uses to sign on to ESF. You can supply a different username and password with the -u and -p (both lowercase) options.

Parent topic: About the esfadmin Command
Related reference
esfadmin Command Syntax


esfadmin Sub-commands

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The esfadmin command can use the following sub-commands:

  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new class/modify an existing class.

Required parameters

CLASS=name
Name of the resource class

Optional parameters

DESC=description
Description text.
Note: Classes are just standard LDAP container objects, so all they have is a name and an optional description.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDGROUP and ALTGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new group/modify an existing group.

Required parameters

GROUP=name
Name of the group.

Optional parameters

MEMBERS=user list
List of users, separated by semicolons. See the note regarding setting group membership in the esfadmin Usage Notes topic.
DESC=description
Description text.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID (is automatically generated if not supplied with the request).
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDMEMBER and DELMEMBER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new resource/modify an existing resource.

Required parameters

RESOURCE=name
Name of the resource.
CLASS=name
Name of its class. Required, but not used by Micro Focus.

Optional parameters

ACL=list of ACEs
ACEs separated by semicolons.
DESC=description
Description text.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID. If not supplied, one is generated automatically.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDUSER and ALTUSER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new user/modify an existing user.

Required parameters

USER=username
Name of the user to add or change.

Required by standard MF LDAP schema for ADDUSER:

ALLOW=TRUE|FALSE
Whether user can sign on.
Note: The TRUE|FALSE values must be in block capitals as shown.

Optional:

NAME=display name
User’s display name.
DESC=description
Description text.
DEFGROUP=group name
Default group.
EXPIRES=yyyymmdd
Account expiration date.

The date format depends on the ESM in use. With the MLDAP ESM, you need to use the date format required by the LDAP server. You need to check to determine what this format is.

For example:
EXPIRES=YYYYMMDDHHMMSS.0Z
where 0Z represents the GMT zone.
PASSWORD=string
Password (will be stored as MF-MD5 salted hash). The PASSWORD attribute is supported for ADDUSER only. To change an existing user's password, use the SETPASSWORD sub-command.
PASSEXP=<date>

Password expiration date.

The date format depends on the ESM in use. With the MLDAP ESM, you need to use the date format required by the LDAP server. You need to check to determine what this format is.

For example:
PASSEXP=YYYYMMDDHHMMSS.0Z
where 0Z represents the GMT zone.
PASSCHG=TRUE|FALSE
Whether user must change password.
Note: The TRUE|FALSE values must be in block capitals as shown.
GETTOKEN=none|self|any
Permission to create passtokens.
USETOKEN=none|self|any
Permission to use passtokens.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID. If not supplied, one is generated automatically.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELCLASS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a class.

Required parameters

CLASS=name
Name of the resource class to delete.
Warning: All resource access control definitions in this class will also be deleted!
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a group.

Required parameters

GROUP=name
Name of the group to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELRESOURCE

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a resource.

Required parameters

RESOURCE=name
Name of the resource to delete.
CLASS=name
Name of its class.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELUSER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Required parameters

USER=name
Name of the user to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTCLASS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the classes.

Required parameters

CLASS=pattern
Pattern name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the groups.

Required parameters

GROUP=pattern
Group name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTREFERENCES

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the resources.

Required parameters

RESOURCE=pattern
Resource name, optionally with “*” wildcards.
CLASS=name
Name of class to search.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the users.

Required parameters

USER=pattern
User name, optionally with “*” wildcards.

Optional parameters

COMPUTED=NO
Disables the generation of the GROUPS attribute in the output, which lists groups the user belongs to. This attribute must be computed when processing the command, and can take a long time to generate if you are listing many users or have many groups.

Example

esfadmin listuser user="A*"

Lists all users with names beginning with “A”.

Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


SETOPTIONS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Not currently in use.

Parent topic: esfadmin Sub-commands


SETPASSWORD

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Sets or resets a user password.

Required parameters

USER=name
Name of user whose password is being reset.
PASSWORD=string
New password (will be stored as MF-MD5 salted hash).
Parent topic: esfadmin Sub-commands


Using the MFDS Internal Security Module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the MFDS Internal Security Module to secure the directory server or enterprise servers.

Note: This module cannot be used with any other security managers. It must be the only module configured.

With the MFDS Internal Security Module, the ability to view, and to alter, objects and schema settings within Directory Server is controlled through a system of user accounts, user groups and permissions.

With this module in place, Enterprise Server administrators must log on. The features available to login IDs are controlled by permissions. You grant permissions to a user group. The users within that group can then perform the actions governed by those permissions.

  • Working with Users, Groups and Resources
  • Application Access and Administration Access
  • Understanding Users and Groups
  • Understanding Permissions
  • Managing Users and Groups
Parent topic: Securing an Enterprise Server Installation


Working with Users, Groups and Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Typically, you can maintain user, group and resource information for the MFDS Internal Security manager only. If you use an external security manager, you would normally use the updating functionality associated with the particular LDAP that you are using to maintain this information. Check the documentation provided with your ESM module for details.

The property screens for the MFDS Internal Security manager can be used for adding, editing and deleting user, group and resource definitions held in this manager, and for specifying resource permissions.

In addition to the conditions listed above, the MFDS Internal Security manager definition must be used by MF Directory Server.

In order to use these property screens, your user account must have User Administration permissions. See Resource Classes for MF Directory Server for details.

Parent topic: Using the MFDS Internal Security Module


Application Access and Administration Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When Directory Server is using the MFDS Internal Security Manager, any enterprise server that connects to the Directory Server to obtain or modify configuration information must supply valid user credentials. If, in addition, you have set the Restrict administration access configuration option, any user wanting to use the administrative features must provide credentials to log on. The features available to the user or application are controlled by permissions. You grant permissions to a user group. The users within that group can then perform the actions governed by those permissions.

Parent topic: Using the MFDS Internal Security Module


Understanding Users and Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you connect to Enterprise Server Administration for a Directory Server that is running in restricted mode, you are presented with a summary screen. This screen shows basic details of the enterprise servers managed by the Directory Server.

Before you can perform any other actions, you must log on. To do this you require a user account. Directory Server comes with a number of preconfigured user accounts but you can create others.

When you have logged on, the features that you can use depend on the permissions granted to the user groups of which your user is a member.

Each user can be in many user groups. Again, Directory Server has several preconfigured groups and you can create others. Each of the preconfigured groups has appropriate permissions for a particular administrative task. One or more of the supplied users are assigned to each of the groups, with the exception of the System group, which is used by Micro Focus applications.

Group | Description | Preconfigured users assigned
All Users | This is the most limited group. Its default Enterprise Server permissions are set as Read only. This permission enables a user in the group to view configuration information for enterprise servers. All users are included in this group. | schemaadmin, adddelete, modify, administrator
Add/Delete This group has default Enterprise Server permissions that enable:
  • the addition and deletion of servers
  • the addition and deletion of services, listeners and packages to servers
adddelete, administrator
General Administrators | This group has default enterprise server permissions that enable all administration activities for enterprise servers. It also has permissions allowing all Directory Server administration activities with the exception of user managements. | administrator
Directory Server Administrators | This group has full permissions for the administration of the Directory Server and all enterprise servers. | schemaadmin
Modify | This group has default enterprise server permissions that enable the modification of enterprise server configuration information. | modify
System | This group is for the use of Micro Focus applications.
Parent topic: Using the MFDS Internal Security Module


Understanding Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A permission controls use of a feature of Directory Server. For example, there is a permission that governs the administration of users and groups. You grant permissions to user groups.

There are two categories of permissions:

Directory Server Administration | These govern the administration of the Directory Server repository (for example, the management of user accounts).
Server | These govern the administration of the enterprise servers that are controlled by the Directory Server.

Some permissions include others. For example, the permission to modify an enterprise server includes the permission to start and stop the server. When a permission is granted, all those that it includes are automatically granted.

  • Directory Server Permissions
  • Server Permissions
Parent topic: Using the MFDS Internal Security Module


Directory Server Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following table describes the available Directory Server permissions.

Name | Description
Save Repository | Permits saving a copy of the repository to a file system directory.
Import Repository | Permits importing data from a file system directory. Includes the following permissions: Save Repository.
Restore Repository | Permits restoring a repository from a file system directory. The process of restoring overwrites all of the information in the current repository. Includes the following permissions: Save Repository, Import Repository.
Delete Repository | Permits deletion of the entire Directory Server repository including all enterprise servers, and all users and groups. Includes the following permissions: Save Repository, Import Repository.
Change MF Directory Server options | Permits changing of Directory Server options. Includes the following permissions: Save Repository, Import Repository.
Set Server Permissions | Permits the allocation of permissions on individual enterprise servers. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server.
Display Directories | Permits the viewing of a list of the Directory Servers that your Directory Server can detect on the network. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions.
Shutdown MF Directory Server | Permits the shutting down of the Directory Server. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions.
Administer Users | Permits the management of user accounts and user groups, and the setting of permissions. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions, Display Directories, Shutdown MF Directory Server.
Parent topic: Understanding Permissions


Server Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following table describes the available server permissions.

Name | Description
Read | Permits viewing of an enterprise server configuration information.
Start/Stop | Permits the starting and stopping of an enterprise server. Includes the following permissions: Read
Modify | Permits the modification of configuration information for an enterprise server. Includes the following permissions: Read, Start/Stop
Add | Permits the adding of listeners, services and packages to an enterprise server. When set as a default permission for the group, it also permits the adding of enterprise servers. Includes the following permissions: Read, Start/Stop, Modify
Delete | Permits the deletion of enterprise servers, and of listeners, services and packages from an enterprise server. Includes the following permissions: Read, Start/Stop, Modify

You can set default server permissions for a group, but you can also override these defaults for individual enterprise servers. For example, you might have an operator group with default permissions to start and stop servers. You could override these for your test server, specifying that the operator group also has modify permission.

Note:

To permit a group to create new servers, you must set its default Add permission.

Parent topic: Understanding Permissions


Managing Users and Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use screens within Enterprise Server Administration to manage users and user groups. To do this, you must be logged on to a user account that is a member of a group with appropriate permissions. The preconfigured user, schemaadmin is suitable for this task.

  • Setting Permissions
  • Best Practice
Parent topic: Using the MFDS Internal Security Module


Setting Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You set the permissions for each group using screens within Enterprise Server Administration. To do this, you must be logged on to a user account that is a member of a group with appropriate permissions. The preconfigured user, schemaadmin is suitable for this task.

Parent topic: Managing Users and Groups


Best Practice

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Change the passwords of the preconfigured accounts at the earliest possible opportunity.

Ensure that only those users who need access have user accounts.

Ensure that users have only the permissions that they require in order to do their jobs.

Limit the number of administrative users.

Parent topic: Managing Users and Groups


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
  • Using All Groups to Which a User Belongs
  • Federation in the MLDAP ESM Module
Parent topic: Securing an Enterprise Server Installation
Related concepts
Username Substitution
Compatibility Rule Matching


LDAP Client and Server Software

The MLDAP ESM Module uses an LDAP client library, also called a provider, to communicate with an LDAP server.

The MLDAP ESM Module uses the Micro Focus LDAP library to provide a common API to LDAP providers. The ESM Module tells MLDAP what LDAP provider library to load and call. Micro Focus does not supply an LDAP provider library of our own. On Windows, the default provider is the one Microsoft includes with the operating system. On Unix, we bundle the OpenLDAP open source client library as the default provider.

You can also configure the ESM Module to use a different provider library by setting the provider option in the Security Manager configuration.

The LDAP server maintains a directory (sometimes called a repository) of security, configuration, and other data. Micro Focus does not supply its own LDAP server, but we do bundle the Microsoft ADAM (Active Directory / Application Mode) server on Windows.

This documentation assumes you already have an LDAP provider library installed on the system where you're using the MLDAP ESM Module, and an LDAP server available on your network. If not, you can contact your operating system vendor or try the free OpenLDAP implementation from http://www.openldap.org.

Parent topic: MLDAP ESM Module
Related concepts
MLDAP ESM Module Custom Configuration Information
Module Configuration
MLDAP ESM Module Custom Configuration Information
Wildcards for Resource, User, and Group Names


The Micro Focus LDAP Schema

LDAP directories are composed of objects with attributes. The objects are arranged hierarchically within special objects called containers; containers can hold both regular objects and other containers. Each object is of a particular class, which defines what attributes that object can have and other information.

The definition of object classes and the hierarchy of containers in an LDAP directory is called a schema. Each LDAP directory has a schema, which can be extended by importing another schema into it. The MLDAP ESM comes with the Micro Focus Schema which can be imported into your LDAP server. It is also possible to adapt an existing schema to replace part of the Micro Focus schema, but that requires advanced LDAP knowledge. The rest of this discussion assumes you are using the standard Micro Focus schema.

All objects have a Distinguished Name or DN, which is a string made up of components in the form type=value, separated by commas. The DN is unique among all the objects in the directory. Objects also have a Common Name or CN, which is a simple string (possibly including spaces). CNs are not unique across the directory, but may be required to be unique within a certain scope, such as within the object's container.

The standard Micro Focus LDAP Schema puts all of its objects in an outer container called the Application Partition. By default this is named:

CN=Micro Focus,CN=Program Data,DC=local

Within the application partition, we define containers for users, user groups, and resources:

CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local
CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local
CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

The Enterprise Server Users container will hold one object of class microfocus-MFDS-User for each user defined for Enterprise Server. This object class, also defined by the Micro Focus schema, includes the user name (as its CN), password (or a password verifier such as a hash value), user information used within MTO such as an optional operator class, and security information such as expiration date and whether login is allowed.

Note: The MLDAP ESM Module can be configured to use an LDAP class other than microfocus-MFDS-User. For example, if you have existing LDAP users defined using the LDAP class user, you can extend your LDAP schema to add the user attributes defined by Micro Focus to the user class and then configure the ESM module to use it for user definitions. Note, though, that adding new users through the ESM Module (using MFDS or the esfadmin utility) may not work (due to additional object constraints) if you do not use the microfocus-MFDS-User class, in which case you will have to use third-party LDAP or provisioning tools to create new users.

The Enterprise Server User Groups container holds objects of class microfocus-MFDS-Group, which simply contain the name of the group (as CNs) and the list of users who belong to that group. User groups simplify writing resource security rules for multiple users, as rules can be applied to entire groups as well as to users.

Each group member can be either the name of a user, or the group keyword followed by the name of another group. In the latter case, all the members of the named group are included in the group being defined. These "nested groups" can be used to define a hierarchy of groups, for example collecting several groups of developers into a single "ALLDEV" group. They can also be used to create very large groups, when the number of users for a group exceeds the maximum size of a multi-valued attribute supported by your LDAP server.

The Enterprise Server Resources container holds additional containers, one for each resource class. All protected resources (programs, transactions, datasets, etc) belong to a resource class (not to be confused with an LDAP object class), which in effect specifies the namespace for the resource name. That is, you can define resources with the same name, provided they belong to different classes. MTO resources use various class names defined by IBM. Non-MTO resources, such as Enterprise Server configuration definitions in MFDS, use resource class names defined by Micro Focus (using syntax that's not permitted for MTO resource class names, to avoid collisions). Users can also define their own resource classes for performing explicit access checks in applications.

Each resource class is defined as a container in Enterprise Server Resources, with the class name becoming the CN of the class container.

Within each class container are zero or more resource objects, of class microfocus-MFDS-Resource. For these objects, the CN can either be a full resource name, such as a transaction name or a dataset name, or it can be a partially- or fully-wildcarded name, which will match various resource names. This lets you write a single rule to apply to multiple resources. Wildcards are discussed in more detail in the Wildcards topic.

Each resource object also has an attribute named microfocus-MFDS-Resource-ACE, which is a multivalued attribute that holds the Access Control List (ACL) that specifies access rights for that resource. (Each entry in an ACL is referred to as an Access Control Entry, or ACE.) ACLs are discussed in more detail in the Resource Access Control Lists topic.

  • Wildcards for Resource, User, and Group Names
  • Username Substitution
  • Nested Groups
Parent topic: MLDAP ESM Module


Wildcards for Resource, User, and Group Names

The MLDAP ESM Module supports three wildcards:

* | Match zero or more characters, except the period "." (full stop, dot) character. This exception is generally only useful in dataset names, where it indicates that the wildcard applies only to the current DSN qualifier.
** | Match zero or more characters, including the period ".". Usually used only in dataset names, to indicate any number of qualifiers, since the period character does not usually appear in other names.
+ | Match exactly one character, except the period ".". This is not treated as a wildcard by default; it must be enabled in the module configuration using the plus-wildcard option.

Wildcards can appear in two places:

  • In the names of resource objects in the LDAP directory. When a resource object in the directory has a name with a wildcard (sometimes called a generic name), its ACL applies to all the resources with a name that matches that pattern, unless another resource definition with a more-specific name (see Match Rank) exists.
  • In user and group names in an Access Control Entry. Such an entry will apply to all users or groups with names that match the pattern, unless another ACE with a more-specific name (see Match Rank) exists in that ACL.
Parent topic: The Micro Focus LDAP Schema
Related concepts
Match Rank


Username Substitution

Beginning with version 2 of the MLDAP ESM Module (available in Enterprise Server 2.3 and some hotfixes for Enterprise Server 2.2 Update 2), you can also define resource-rule names based on the name of the user who is requesting access. This lets you create generic rules that apply to resources that include the user's name in the resource name. Typically this is used for rules in the DATASET and JESSPOOL classes, to give users access to resources that include their name as a qualifier.

To use this feature:
  • You must be using MLDAP ESM Module version 2 with the new rule-matching algorithm defined. That is the default for Enterprise Server 2.3. For Enterprise Server 2.2 Update 2 Hotfix 7 and later, you must enable the new algorithm by setting Version 1 authentication=no in the [Operation] section of the Security Manager configuration.
  • In the Security Manager configuration area, set Rule substitutions=yes in the [Operation] section.
  • Use the token ${user} in resource access rule names where you would like the requesting user's name to be substituted; for example, 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.

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


Nested Groups

Beginning with version 2 of the MLDAP ESM Module (available in Enterprise Server 2.3 and some hotfixes for Enterprise Server 2.2 Update 2), you can specify groups as members of other groups. This nested groups feature lets you add users to groups through a form of inheritance and create large user groups.

No special module configuration is required to use nested groups. To include group A in group B, simply add group A to the list of members for group B. In this case group B is known as a supergroup of group A. Users who belong to group A will now also belong to group B.

Nested groups are generally most useful when All-Groups Mode is enabled, but do not require it.

Applications

Nested groups may be useful for various purposes:

  • Large groups. In the Micro Focus LDAP Schema, user groups are implemented as LDAP objects with membership information stored in the multivalued microfocus-MFDS-Group-Member attribute. LDAP servers generally have restrictions on how large an attribute can be, which limits the number of members that a group can have. Nested groups can be used to create a group with a large number of members. For example, to create an ALLUSERS group with thousands of users, you might create a USERSA group with all the users whose user IDs begin with "A", a USERSB group, and so on; then make the USERSA, USERSB, ... groups members of ALLUSERS. USERSA and its sibling groups may never be used for any other purpose (for example, there may not be any ACEs that assign permissions to those groups); they exist just to let ALLUSERS contain all the user accounts.
  • Group hierarchies. Sometimes user groups conceptually form a hierarchy. For example, there might be groups for individual project areas (UI, ENGINE, etc), all of which are part of a larger DEVEL group. Nested groups lets you represent this arrangement by including the more-specific groups in the larger group.
  • Simplified group and permission management. Nested groups can reduce the number of groups a user needs to be explicitly added to, in order to correctly represent that user's position in the organization and assign the correct permissions. That can make it simpler to update group membership when adding and removing users.

Limitations

Not all ESF Administration features currently work correctly with nested groups. If you use nested groups, Micro Focus recommends administering them with the esfadmin command's ADDMEMBER and DELMEMBER sub-commands, or with LDAP tools operating directly on the LDAP repository, rather than using the MFDS graphical user interface. The LISTREFERENCES sub-command (and ESF Admin API function) does not currently show supergroup membership; that also means that the Referential Integrity Sample User Exit does not recognize that users belong to supergroups.

Group membership changes, including changes in how groups are nested, are recognized when a user signs on to a region for the first time after that region is started. You can also instruct the region to update its information about group membership by sending it an ESF update request using the MFDS administration user interface or the esfupdate command-line utility.

Nesting a group using esfadmin

Assume Alice belongs to the PROJ1 group. We can add PROJ1 to the DEV group using the esfadmin command:

esfadmin options ADDMEMBER GROUP=DEV MEMBER="PROJ1 group"

Now Alice will belong to both PROJ1 and DEV.

Nesting a group using LDIF

The following LDIF fragment creates the AUDIT and FINANCE groups, and makes AUDIT part of FINANCE:

dn: cn=AUDIT,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
adminDisplayName: Audit group
objectClass: microfocus-MFDS-Group
microfocus-MFDS-UID: AUDIT
description: ES auditors group

dn: cn=FINANCE,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
adminDisplayName: Finance group
objectClass: microfocus-MFDS-Group
microfocus-MFDS-UID: FINANCE
description: ES finance group
microfocus-MFDS-Group-Member: AUDIT group
Parent topic: The Micro Focus LDAP Schema


Resource Access Control

The MLDAP ESM Module lets you control access to resources managed by Enterprise Server, by specifying rules in the LDAP repository. A rule associates one or more resources with an Access Control List (ACL), and the ACL defines what type of access various users and groups have to the resource. When an application tries to use a resource, Enterprise Server asks ESF whether the request (a particular action, such as updating, applied to a particular resource, such as a dataset) should be allowed. If ESF is configured to use the MLDAP ESM Module, the module will find the most-appropriate resource access rule and apply its ACL to decide whether the request is permitted.

  • Matching Rules and ACEs
  • Resource Access Control Lists
Parent topic: MLDAP ESM Module


Matching Rules and ACEs

When the MLDAP ESM Module receives a request to authorize a user's access to some resource, it checks the rules stored in the LDAP repository to 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 behaviour 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 well-known port for LDAP).
Authorized ID
The username used to bind to the LDAP server. The format for this is server-dependent, but is usually a Distinguished Name. This user should have read access to the Enterprise Server user, group, and resource objects in the LDAP repository, and needs to have modify access to user definitions if you wish to support letting users change their passwords from Enterprise Server (for example from the CICS signon screen). The default is CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last three components can be changed by setting the base DN; see below), which is the user object created for this purpose in the sample configuration.
Password
The password used to bind to the LDAP server. The default is the password used in the sample configuration.
Enabled
If this box is unchecked, ESF Manager will not load, initialize, or pass requests to this ESM Module. In a future release it will be possible to dynamically enable and disable ESM Modules while the region is running.
Cache limit
This parameter is currently ignored by the ESM Module.
Cache TTL
This parameter is currently ignored by the ESM Module.
  • MLDAP ESM Module Custom Configuration Information
Parent topic: Module Configuration


MLDAP ESM Module Custom Configuration Information

The MLDAP ESM Module also supports some additional configuration that can be set by editing the text in the Configuration Information area. Text in this area is organized into sections which begin with a "tag" in square brackets, followed by lines in the form name=value.

Here are the various configuration sections, and the options that can be set in each section.

[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) or shared object (Unix), exporting the standard LDAP C API functions. On UNIX, if module does not include a file extension, the standard Micro Focus file extension for that platform (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 openldap, which is the Micro Focus port of the OpenLDAP client library.
For example:
[LDAP]
 provider=libldap.a
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 is 3. Normally this does not need to be changed, since if either the client or server does not support version 3, they should automatically fall back to version 2.
base=DN
Set the base container for Enterprise Server security information in the LDAP server. The default is CN=Micro Focus,CN=Program Data,DC=local, which is the container used in the sample configuration. The value should be the common part of the DNs of the Enterprise Server Users, Enterprise Server User Groups, and Enterprise Server Resources containers.
Note: If your user, group, and resource containers are in separate branches of your LDAP repository, you can set Base to an empty string and use full DNs for user container, group container, and resource container.
user class=LDAP class name
Set the name of the LDAP object class used to hold user information. The default is microfocus-MFDS-User, but installations with existing user definitions in an LDAP repository might want to extend those definitions with the Micro Focus MTO user attributes and use them instead.
user container=partial DN
Set the name of the LDAP container that holds Enterprise Server user objects. The value should be one or more LDAP DN components; the LDAP "base" DN (see Base above) is appended to the value to create the full DN of the user container. The default is CN=Enterprise Server Users.
user ID attribute=name
Set the name of the LDAP attribute that holds the MTO user name in an Enterprise Server user object. This is useful if your LDAP schema already uses the default "cn" (Common Name) attribute for some other purpose.
Note: 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 is CN.
group class=LDAP class name
Set the name of the LDAP object class used to hold group information. The default is microfocus-MFDS-Group.
group container=partial DN
Set the name of the LDAP container that holds Enterprise Server group objects. The default is CN=Enterprise Server User Groups.
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 is microfocus-MFDS-Resource.
resource container=partial DN
Set the name of the LDAP container that holds Enterprise Server resource access rule objects. The default is CN=Enterprise Server Resources.
bind=simple | negotiate | es-user
Set the method for binding to the LDAP server:
  • The simple method sends the LDAP credentials in plain text. If you have the ESM Module configured to use a privileged LDAP account (for example, if it has authority to set user attributes, in order to support user password-change requests), and the network connection between the module and the LDAP server is not secure, use one of the other methods. With this method, the "Authorized ID" in the Security Manager configuration should be an LDAP distinguished name.
  • The negotiate method lets the ESM Module and the LDAP server negotiate the most secure method to use. With most LDAP servers this should prevent the LDAP credentials from being sent in the clear. With this method, the "Authorized ID" in the Security Manager configuration depends on the LDAP server; for Active Directory, it should be a Windows username, optionally prefixed with a domain name followed by a backslash (domain\user).
  • The es-user method is only supported on Windows, and only when connecting to Active Directory. It tells the module to bind to LDAP using the user account of the current process (ES/MTO or MFDS). The credentials are not sent in the clear. With this method, the "Authorized ID" and "Password" fields in the Security Manager configuration are ignored.

The default is simple.

search scope=child | tree
Set the scope for LDAP searches. child 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 is child.

referrals=yes | no | default
Enable or disable LDAP referrals. LDAP referrals let one LDAP server pass a query along to another server. Usually referrals do not need to be enabled, and in some cases enabling referrals may cause servers to reject certain queries. For example, Active Directory rejects subtree queries (see search scope above) if referrals are enabled.

If this is set to default (or not set at all), the MLDAP ESM Module leaves the LDAP provider's referrals setting unchanged, and the behavior depends on the provider and server.

The default is default, for compatibility with earlier versions of the MLDAP ESM Module, unless you have search scope=tree also configured, in which case the default is no.

timeout=seconds
Set the timeout for lengthy LDAP operations. This affects LDAP searches; depending on the LDAP provider, it may also affect binding or other operations. If this option is not configured or the value is 0, the provider's default timeout is used.
connect timeout=seconds
Set the timeout for LDAP connection attempts. This affects only the first stage of connecting to the LDAP server: opening the TCP conversation. In most cases, this either succeedes 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 that 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).

[Operation] section

maxgroups=number
Set the maximum number of user groups supported in Use-all-groups mode. This must be at least as large as the number of groups that include any user who will sign on to the region. The default is 64; the maximum value is 9999. Increasing this value consumes more shared memory and increase processing time for authorization requests, Micro Focus recommend keeping it close to the actual number of user groups you have defined. It has no effect when the "Use all groups" option is not enabled.
Note: If you have multiple MLDAP ESMs stacked in a security configuration, they must have the same setting for maxgroups, unless Federation is explicitly disabled. This requirement is enforced by the module; you 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 is 0, which disables this feature.
plus-wildcard=yes | no
If this is set to yes, the plus (+) character is interpreted as a wildcard when it appears in a resource rule name. It functions like the * and ** wildcards, except that it always matches exactly one character.

The default is no.

set login count=yes | no
If the user class includes the microfocus-MFDS-User-LoginAttempts attribute, and this option is set to yes (the default), the MLDAP ESM Module 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 default is no), the Compatibility Rule Matching algorithm is used.
rule substitutions=yes | no
Set this to yes to enable the use of the ${user} token (which is replaced with the userid of the user making the access request) in resource access control rules. See Username Substitution for more information. Compatibility rule matching must not be enabled.
check TLQ first=yes | no
If this option is set to yes (the default is no), 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.

[Passwords] section

expiration=number
Set the default password expiration interval, in days. It only applies if MF-hash verify mode (that is, Micro Focus password hashes) is being used. (This is the default, but many organizations use bind verify mode, in which case password expiration has to be managed by your LDAP server.) If a user changes their password, and their account is configured with a password expiration date (the microfocus-MFDS-User-Pwd-ExpirationDate attribute), and that date is in the past or less than this many days in the future, then it is changed to this many days in the future. The default is 90 (days). The microfocus-MFDS-User-Pwd-ExpirationDate attribute must be set to a string of digits representing the four-digit year, the two-digit month, and the two-digit day of the day the password expires (yyyymmdd). Anything following the day is ignored. The standard "UTC Coded Time" format used by many LDAP clients and servers works. You can set an initial password expiration date using a regular LDAP client, or using the esfadmin utility with the ALTUSER command and the PASSEXP attribute.

For example:

esfadmin -uADMIN -pADMIN -U"cn=..." -Pxxx altuser user=SYSAD
passexp=20091231

sets the password expiration date for the user SYSAD to the last day of 2009.

expiration-check=setting
Enables a heuristic that attempts to determine if a user bind was rejected by the LDAP server because the user's password was expired. If this set to "1" or a string beginning with "y", and bind-mode verification is enabled (see the [Verify] section), and a password expiration interval is configured, then when a user's bind request is rejected, the module checks to see if their password expiration date has passed. If so, it returns an error code indicating the password is expired, rather than a generic verify-failed error code.
history=number
Remember number previous password hashes for each user; when users try to change their passwords, if the new password matches one of the stored hashes, reject the request. This option has no effect if the module configuration does not let the module update the user's attributes. The default is 0, 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 may 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 may 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) in all.

The various password restriction options can be used in combination, for example:

[Passwords]
 minimum length=6
 required=mixed-case
 complexity=2

would enforce passwords of at least 6 characters, with both upper- and lower-case letters and at least one non-letter character.

[Passtoken] section

default=none | self
Set the default passtoken creation and use privileges. Normally, whether a user can create or use ESF Passtokens with this ESM Module is controlled by per-user attributes. If those attributes are not set, they default to none, which means by default users can neither create passtokens nor be signed on using them. Setting this value to self changes the default behavior to allowing the creation and use of self-only passtokens.
secret=string
Set the secret data which 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.
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 is 60 (one minute).
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 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.
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 may be useful if you are investigating an issue with network traffic to the LDAP server.
Locks=setting
Enable the logging of intra-process and inter-process locking. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log entry when it tries to acquire, acquires, or releases a lock. Micro Focus SupportLine may ask you to enable this tracing mode to diagnose certain unlikely problems.
Update=setting
Enable the logging of update requests, which are ESF control requests (made using MFDS or the esfupdate command-line utility) that notify ESF and the ESM Modules of changes to security configuration or data. If this is set to "y" or "yes", update requests 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 format:

function:actor[:parameters]:result

where:

  • function is verify or auth
  • actor is a username; for auth rules, it can also be a group name followed by the word group. Wildcards are allowed.
  • parameters specific to the function:
    • For verify, there are no parameters
    • For auth, this must be class:entity, where:
      • class is a resource class name (for example "TCICSTRN"); wildcards are allowed
      • entity is a resource entity name (for example "CINQ"); wildcards are allowed
  • 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 somewhat, since each request must be examined to see if it matches a trace rule.

Be sure to use a double asterisk (**) in wildcard specifications for 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.

[Verify] section

mode=MF-hash | bind
Determine how user credentials (username and password) are verified:
  • The MF-hash method retrieves the value of the microfocus-MFDS-User-Pwd attribute, which contains a verifier (a salted cryptographic hash) for the password. It computes the equivalent hash of the supplied password, and verifies that they match. With this method, the passwords used for verifying users under ESF are private to ESF, and not associated with the operating system or LDAP server.
  • The bind method uses the LDAP server itself to verify the user's credentials, by using them to bind to the server. With this method, the user's password for ESF 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 may be somewhat slower and consume more resources.

Other modes may be supported in the future, such as testing other types of password hashes. The default is MF-hash.

password type=MF | 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 (same as MF-A2).
  • MF-A2 or MF-Argon2 creates 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 setting first tries to set unicodePwd using the Microsoft syntax, then tries to set userPassword using the MD5 method. This will usually work when the ESM Module is configured to use the bind verification method: if the LDAP server is Active Directory, the unicodePwd attribute setting will work, and if another LDAP server is being used, there 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.
The default is MF, 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.
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.
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.
Parent topic: MLDAP ESM Module Configuration Fields
Related concepts
Federation in the MLDAP ESM Module
"Use all groups" Mode
Configuring the ESF LDAP Security Administration Web Interface
Configuring LDAP User Group Mode


Using All Groups to Which a User Belongs

Each user can belong to one or more user groups, and resource permissions can be assigned to groups as well as to individual users. Like some mainframe security managers, ES MSS has the concept of a "sign-on group": during sign-on, users can also specify which group they're signing on with. (If the user isn't in the specified group, the sign-on is denied.) Users who don't specify a group sign on under their "default group", as determined by the ESM.

By default, when a user requests access to some resource, some ESMs will only apply rules that refer to that user and the user's current sign-on group. (Other ESMs may ignore the concept of sign-on group entirely, and always apply rules that refer to any group the user belongs to.) Rules for other groups will be ignored, whether the user belongs to them or not.

You can set the Use all Groups option in an enterprise server's security configuration to change this behavior. If Use all Groups is set, it doesn't matter what a user's sign-on group is; the user will always have all the permissions that apply to any group that user belongs to.

Parent topic: MLDAP ESM Module


Federation in the MLDAP ESM Module

The ESF Federation setting affects how instances of the MLDAP ESM Module work together, when multiple ESMs using the MLDAP ESM Module are stacked in the security configuration. Federation is not a concern if there is only one MLDAP ESM Module in the stack.

If federation is disabled, the MLDAP ESM Module will ignore any Auth and XAuth operations that refer to users which are not known to that module. For example, suppose you have two LDAP repositories, with some of your users defined in the first repository and the other users defined in the second. To accommodate this configuration you have created a security configuration with two MLDAP ESM Modules on the stack, one pointing to the first LDAP repository and the other to the second. Assume the user Alice is defined in the second repository and that federation is disabled. When Alice tries to access a resource, ESF will make an Auth request to each ESM in turn. The first ESM does not have information about Alice, as she's defined in the second ESM, so it will return "unknown" for the Auth request. The second ESM will then process the request normally. That means resource ACLs defined in the first ESM will not be consulted when determining Alice's access.

If federation is enabled, or is set to compatibility mode (currently the default), then the first ESM will look for resource ACLs that apply to the Auth request, even though it was not the ESM that verified the user Alice.

Federation also affects use-all-groups mode. If federation is enabled, all MLDAP ESM Modules in the process will share a single set of group names and group membership information. If federation is disabled, each MLDAP ESM Module will have its own set of group names and group membership information. In federation compatibility mode, there is only one set of group names shared by all modules, but each module has its own information about what users belong to each group.

The compatibility federation setting can lead to unexpected results, since an ESM may not have group information for a user and so may not apply group-based ACLs as you expect. When using multiple MLDAP ESM Modules, it's usually best to explicitly enable or disable federation, especially if use-all-groups mode is enabled.

In general, you should enable federation if you want your LDAP security information combined, as if it all came from a single LDAP repository. You should disable federation if your LDAP repositories are designed to be independent (so, for example, resource access rules from one LDAP repository should not be applied to users from the other repository).

If redundant (also known as high-availability) mode is enabled for ESF itself, federation is automatically enabled.

Parent topic: MLDAP ESM Module
Related concepts
Access Levels and Permissions
"Use all groups" Mode


Configuring Security Using OpenLDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The MLDAP ESM module mldap_esm enables the Security Facility to use an LDAP server as an external security manager. The MLDAP ESM module can communicate with a variety of LDAP servers including OpenLDAP servers. The server can operate either on the same machine as your Enterprise Server installation, or it can be remote.

The content in this section assumes that you have already installed on your server machine, OpenLDAP and the OpenLDAP server, and the Enterprise Server software that is used by your Micro Focus product.

Important: You can use the information in this section to configure LDAP types other than OpenLDAP.
  • Using an LDAP client library
  • About OpenLDAP for the Micro Focus Environment
  • Installing the Required Schema Extensions
  • Configuring the OpenLDAP server
  • Configuring mldap_esm Security Manager for an LDAP
Parent topic: Securing an Enterprise Server Installation


Using an LDAP client library

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use an LDAP server for Enterprise Server security, or to hold Enterprise Server configuration data (also known as an MFDS repository), you must have an LDAP client library installed.

Some operating systems include one with the default installation, or as an optional package. Microsoft Windows includes Microsoft's LDAP client as part of the base OS. AIX ships with IBM Directory Server, an installable option, which includes an LDAP client. Solaris also includes an LDAP client which is usually part of the default installation. OpenLDAP packages are available for Red Hat and SUSE Linux distributions and can be installed with rpm or yum respectively.

You can also obtain the OpenLDAP sources from http://www.openldap.org/ and build the OpenLDAP client library by following the instructions there.

Parent topic: Configuring Security Using OpenLDAP


About OpenLDAP for the Micro Focus Environment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Within the LDAP directory, you define users, user groups, resource classes, and resources, and these objects contain the attributes used to make security checks (for the Verify, Auth, and XAuth procedures). Micro Focus defines an LDAP schema for these objects and their attributes, but in many cases you can adapt an existing directory for at least part of this information, for example in order to reuse an existing repository of user information.

When it processes a security request, the module searches the configured LDAP repository for relevant rules and applies whatever it finds.

The External Security Facility API documentation is available, in doxygen format, on the Micro Focus Supportline website's Examples and Utilities page.

  • Follow this link to the Examples and Utilities page:

    Micro Focus Supportline Examples and Utilities page

  • Follow this link to the External Security Facility API documentation:

    External Security Facility Manager API

Parent topic: Configuring Security Using OpenLDAP


Installing the Required Schema Extensions

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Before you commence this procedure, ensure that you have sufficient access, for example root access, to create files in the $COBDIR/lib directory.
  1. Make sure that the Micro Focus bin directory is in your path.
  2. Start a command prompt and go to the OpenLDAP install directory.
  3. cd to the schema directory.
  4. Generate the MFDS OpenLDAP schema by issuing the following command:
    mfds -l dc=x 2
    This creates a schema file, for example mfds_1.08.43.schema in the $COBDIR/lib directory.
  5. Now create a new file called container.schema, which must look like this:
    objectclass (
       1.2.840.113556.1.3.23
       NAME 'container'
       SUP top
       STRUCTURAL
       MUST ( cn )
       MAY ( description ) )
    The container objectclass is used to group collections of like objects within the LDAP server Directory Information Tree in the Micro Focus extensions.
    Note:

    It is very important that when this schema file is created, there is no trailing whitespace on any of the lines that the schema file contains.

  • Adding default MFDS users, user groups and resources
Parent topic: Configuring Security Using OpenLDAP


Adding default MFDS users, user groups and resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Create an LDIF file file containing the user, group and resource definitions by using the mfds -e command. For example:
    mfds -e "cn=Micro Focus,dc=my-domain,dc=com" "cn=Enterprise Server Users" "cn=Enterprise Server User Groups" "cn=Enterprise Server Resources" 2 "c:\program files\openldap\mfds_users.ldf"
  2. Import the generate file using ldapadd. For example:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f mfds_users.ldf
  3. Confirm the creation of the containers using ldapsearch. To dump the contents of the Micro Focus container use:
    ldapsearch -x -b "dc=my-domain,dc=com" -s sub +
Parent topic: Installing the Required Schema Extensions


Configuring the OpenLDAP server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. At the command prompt, cd to the OpenLDAP install base directory.
  2. Edit the OpenLDAP server configuration file, slapd.conf, to add the following include statements:
    include      ./schema/cosine.schema
include      ./schema/inetorgperson.schema
include      ./schema/container.schema
include      ./schema/mfds.schema

You can now start the OpenLDAP server.

  • Confirming Extension Installation
  • Creating Standard Micro Focus application containers
Parent topic: Configuring Security Using OpenLDAP


Confirming Extension Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Issue the following command:
    ldapsearch -x -b "cn=subschema" -s base + > schema.txt
  2. Check the contents of the resulting file, schema.txt, to verify that there are attribute and objectClass entries that begin with "microfocus-".
Parent topic: Configuring the OpenLDAP server


Creating Standard Micro Focus application containers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before adding the standard Micro Focus containers, the initial domain context object needs to be added.

  1. Create a file called top.ldf with contents similar to those shown below.
    dn: dc=my-domain,dc=com
objectClass: dcObject
objectClass: organization
dc: my-domain
description: My domain description
o: My domain
  2. To add the domain context object use:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f top.ldf

    The successful output should look something like the following:

    add objectClass:
        dcObject
        organization
add dc:
        my-domain
add description:
        My domain description
add o:
        My domain
adding new entry "dc=my-domain,dc=com"
modify complete

You can now add the standard Micro Focus containers.

  1. Create a file called mf-containers-open.ldf, with contents as follows:
    dn: cn=Micro Focus,dc=my-domain,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Enterprise Server Resources,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server Resources
objectClass: container

dn: cn=Enterprise Server Users,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server Users
objectClass: container

dn: cn=Enterprise Server User Groups,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server User Groups
objectClass: container
  2. Create the containers by issuing the following command:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f mf-containers-open.ldf
  3. Confirm the creation of the containers by using ldapsearch to dump the contents of the Micro Focus container:
    ldapsearch -x -b "dc=my-domain,dc=com" -s sub +
Parent topic: Configuring the OpenLDAP server


Configuring mldap_esm Security Manager for an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The default mldap_esm security manager settings are designed for the simple LDAP configuration using AD LDS and the Micro Focus user class. Before the mldap_esm security manager can update the information in an LDAP server, you need to set a number of configuration options.

  • Set Connection Path to the IP address and port of the LDAP server (for example ad-host:389)
  • Set Authorized ID to the DN of a user with appropriate permissions for the LDAP repository (for example CN=Administrator,CN=users,DC=somecorp,DC=com ). This user must have at least read access to the containers for user definitions and their contents. If you want to use the MFDS administration console to change user groups and resource access rules, this ID will also need update access to those portions of the repository.
  • Set Password to the password for the user specified in Authorized ID.
  • In Configuration Information, you will need to set a number of LDAP parameters:
    [LDAP]
base=DN-suffix
user class=user class
user container=user-container
resource container=resource-container
    DN-suffix | The common part of the DN for your user container.
    user class The LDAP object class used for your users. The following options are available:
    • microfocus-MFDS-User

      This is the default setting.

    • user

      Microsoft standard users are used and you cannot add or modify users from the MFDS user interface.

    user-container | The DN of the container for user objects, without the "base" suffix, for example: CN=users
    resource-container | The DN of the container for resource access class containers (which in turn hold resource access definition objects), without the "base" suffix, for example CN=Enterprise Server Resources,CN=MF
Parent topic: Configuring Security Using OpenLDAP
Related concepts
Configuring the ESF LDAP Security Administration Web Interface


Examples

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains examples of using LDIF to define Enterprise Server security information in Active Directory.

  • Defining a User with LDIF
  • Defining a Group with LDIF
  • Defining CAS Resources with LDIF
  • Defining Files with LDIF
Parent topic: Securing an Enterprise Server Installation


Defining a User with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=SEC01,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local | Identifies user SEC01
changetype: delete | Action is set to delete, the current definition for user SEC01 will be deleted
 | You must leave a blank line between actions
dn: CN=SEC01,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local | Identifies user SEC01
changetype: add | Action is set to add
objectClass: microfocus-MFDS-User | Object class, we are defining a User
description: User Description | User description, used for documentation purposes
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
microfocus-MFDS-CustomText | Optional. 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 himself. (Used for single signon, 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 no timeout. (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 the user using ESMAC
microfocus-MFDS-User-Pwd-ExpirationDate | Optional. If set, 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 himself (Used for single signon)
Parent topic: Examples


Defining a Group with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: cn=PAYROLL,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local | Identifies group PAYROLL
changetype: delete | Action is set to delete, the current definition for group PAYROLL will be deleted
 | You must leave a blank line between actions
dn: cn=PAYROLL,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local | Identifies group PAYROLL
changetype: add | Action is set to add
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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies resource 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies resource 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 controlling access to datasets | Description
 | You must leave a blank line between actions
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local |
changetype: delete | Action set to delete, we remove any existing definition
 | You must leave a blank line between actions
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to create
changetype: add | Action set to add in order to create the entity
objectClass: microfocus-MFDS-Resource | We are creating a resource
microfocus-MFDS-Resource-Class: DATASET | Name of the 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
Parent topic: Examples


Managing LDAP Security Manager from the Enterprise Server UI

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use the mldap_esm security manager to configure an LDAP 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
  • Changing User Passwords Stored in an LDAP
  • About Users, Groups and Resources
  • Managing User Access
  • Managing Groups
  • Assigning Resource Permissions
  • Security Configuration Screen Help
Parent topic: Securing an Enterprise Server Installation


About Managing an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the property screens for a security manager definition that uses mldap_esm to add, edit and delete user, group and resource definitions held in the associated LDAP repository, and for specifying resource permissions.

The mldap_esm security manager binds at configuration time only to the LDAP server, using credentials supplied as part of its configuration. All the privileges that it has for that repository are determined by those credentials. Therefore, in order to manage users, groups and resources through these property screens, you will need to ensure that these credentials have sufficient permissions on the LDAP server.

Note:

The MF Directory Server user ID with which you access the property screens is not related in any way to the credentials with which the mldap_esm security manager connects to the LDAP server. For added protection, when you attempt to access the security manager property screens, MF Directory Server will switch to "Restrict administration access" mode, requiring you to enter valid MF Directory Server user credentials.

Note also that when no authorized ID and password is specified in the security manager definition, the mldap_esm security manager uses the user ID, CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last two components can be changed by setting the base DN), which is the user object created for this purpose in the sample configuration, and the password "mf_rdr" to connect to the LDAP repository. Of course, as these values are well known, you should not give MFReader write permission to your LDAP repository.

Instead of storing user passwords in the LDAP repository, the Security Facility stores password verifiers, in the form of salted MD5 hashes.

Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


Changing User Passwords Stored in an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are various ways for Enterprise Server users to change passwords stored in an LDAP. The Security Facility relays these requests to the security managers that are used to verify the user. Whether or not a password change request is honoured by a security manager depends on that manager and the security manager module that is used to connect to it.

When using the mldap_esm security manager, changing a user's password involves changing an attribute of the associated user object in the LDAP repository. This in turn requires that the mldap_esm security manager has write access to the repository. However, the mldap_esm security manager does not connect to the repository with the credentials of the user requesting the password change; it uses the authorized id and password that are specified in the Edit Security Manager screen.

In order to enable the mldap_esm security manager to support the changing of user passwords, you need to modify the security manager definition to specify an authorized user ID and password that has write access to the Enterprise Server user objects within the LDAP repository. The ID and password combination that you supply should, of course, be secret. To do this:

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. In the Authorized ID field, supply the username used to bind to the LDAP server. The format for this is server-dependent, but is usually a Distinguished Name.

    This user should have read access to the Enterprise Server user, group, and resource objects in the LDAP repository, and modify access to user definitions to support letting users change their passwords from ES.

  6. In the Password field specify the password used to bind to the LDAP server.
  7. Click OK.
Note:

When no authorized ID and password is specified in the security manager definition, the MLDAP ESM uses the user ID, CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last two components can be changed by setting the base DN), which is the user object created for this purpose in the sample configuration, and the password mf_rdr to connect to the LDAP repository. Of course, as these values are well known, you should not give MFReader write permission to your LDAP repository.

Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


About Users, Groups and Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each item (for example, program, file, transaction) to which access is controlled is a called a resource. A resource has a name and a class, which indicates the type of the resource. For example, each enterprise server is a resource, and all enterprise servers belong to the same resource class.

A resource name must be unique within its class. That is, you can define two or more resources with the same name, provided that they belong to different classes.

When a user requests access to a resource the security facility relays the request to the external security manager, specifying the user, the resource and the resource class. The security manager will then look for resource rules that match the resource name. The processing of a request is dependent on the external security manager.

Where your ESM module provides suitable support, as is the case with the mldap_esm module, you can use the Enterprise Server Administration screens to define users, groups, resource classes and resources (referred to as resource entities). In defining a resource entity, you are specifying a rule against which an authorization request can be matched. Depending on your ESM, the resource entity might have a full resource name, or might contain wildcards. This allows you to write a single rule to apply to multiple resources.

With the mldap_esm module, for example, each resource entity has an Access Control List (ACL) that specifies access rights for that resource. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries identify a user or group, and what permissions are to be granted or denied to them.

Users can be assigned to many user groups, and depending on your security manager and your security configuration a user may be allowed the permissions of all the groups to which he or she belongs, a particular group specified when the user signed on, or a default group specified as part of the user definition. For more details see Using all groups to which a user belongs.

Note: For Micro Focus Directory Server access, users always have the permissions of all the groups to which they belong.
Parent topic: Managing 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Please check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server.

  • To Add a User
  • To Edit a User
  • To Delete a User
  • To View Permissions for a User
Parent topic: Managing 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.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers, and for the security manager to which the user is to be added, click the radio button in the Select column.
  3. Click Edit.
  4. Click Properties.
  5. Click Users.
  6. Click Add.
  7. Specify the user's details.

    For information about the entry fields, refer to the page help for this screen.

  8. Click Next.
  9. Type a description of the user in Description.
  10. For each user group of which the user is to be a member, select the group from User groups, and click <--Add.
  11. If you change your mind and want to remove the user from any group, select the group from Member of and click Remove-->.
  12. Click Add.
Enter the tasks the user should do after finishing this task (optional).
Parent topic: Managing User Access


To Edit a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to edit.
  8. Click Edit for the user.
  9. Specify the user's details.

    For information about the entry fields, please refer to the page help for this screen.

  10. Click OK.
Parent topic: Managing User Access


To Delete a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user to be deleted by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to delete.
  8. Click Edit for the user that you wish to delete.
  9. Click Delete.
  10. Click OK on the User Delete Confirmation page.
Parent topic: Managing User Access


To View Permissions for a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user definition that you want to view by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to edit.
  8. Click Edit for the user.
  9. Click Permissions.

    The screen displays a tree structure. Expanding the top level node displays the various resource classes. Expanding a class displays the resource entities that it contains and the permissions that the user has for those entities. Please note, the permissions displayed are for those Access Control List entries that apply to the user, either by fully specifying the user's ID or by a wildcard match.

Parent topic: Managing User Access


Managing Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server

  • To Add a Group
  • To Edit a Group
  • To Delete a Group
  • To View Permissions for a Group
Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


To Add a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager to which the group will be added by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties.
  6. Click Groups.
  7. Click Add.
  8. Specify the details for the group.

    The group name cannot exceed eight characters and longer names will be truncated to the first eight characters. For more information about the entry fields, please refer to the page help for the screen.

  9. Click Next.
  10. Under Permissions, check each permission that you want to grant to the group. If you want to grant all permissions under the Directory Server Administration or Servers sections, click the appropriate Allow All button.

    The permissions are displayed in an inverted tree structure. Those on lower branches include the permissions on the branches from which they descend. For example, the permission to restore a repository includes the permission to import a repository. Therefore, restore is shown as a descendant of import.

    When you grant a particular permission, any permissions that it includes are automatically granted. Hence, when you check the Restore Repository permission, the Import Repository permission is automatically checked as well.

    Where a check box for a permission is greyed out, it indicates that the permission is included by other permissions that have been granted to the group. To revoke a permission that is included by others, you must first revoke those other permissions.

  11. Type a description of the user in Description.
  12. For each user group of which the user is to be a member, select the group from User groups, and click <--Add.
  13. If you change your mind and want to remove the user from any group, select the group from Member of and click Remove-->.
  14. Click Add.
Parent topic: Managing Groups


To Edit a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to perform this, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to edit.
  8. Specify the details for the group.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click OK.
Parent topic: Managing Groups


To Delete a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to perform this, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group that you want to delete by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to delete.
  8. Click Delete.
  9. Click OK on the Delete User Group confirmation page.
Parent topic: Managing Groups


To View Permissions for a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

Note:

Please note that the display and setting of permissions for MFDS Internal Security differs from that for other Security Managers, and is covered separately by To assign resource permissions when using MFDS Internal Security.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group definition that you want to view by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click Edit for the group.
  8. Click Permissions.

    The screen displays a tree structure. Expanding the top level node displays the various resource classes. Expanding a class displays the resource entities that it contains and the permissions that the group has for those entities. Please note, the permissions displayed are for those Access Control List entries that apply to the group, either by fully specifying the group ID or by a wildcard match.

Parent topic: Managing Groups


Assigning Resource Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Please check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server.

In order to use these property screens, your user account must have User Administration permissions. .

  • About Resource Security
  • To Add a Resource Class
  • To Add a Resource Entity
  • To Assign Resource Permissions
  • To Edit a Resource Class
  • To Edit a Resource Entity
  • To Assign Resource Permissions When Using MFDS Internal Security
  • To Delete a Resource Class
  • To Delete a Resource Entity
Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


About Resource Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can control access by a transaction to the following types of resource:

  • Files
  • Transient data queues
  • Temporary storage queues
  • Journals
  • Other transactions
  • To Enable Resource Security
Parent topic: Assigning Resource Permissions


To Enable Resource Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable resource security, do the following:

  1. Specify that a transaction is to perform resource security checking, by checking Security: Resource Level Checking on the PCT page in ESMAC for the transaction. (By default, transactions do not perform resource security checking.)
  2. Specify a set of resource keys in the resource table entry (for example, the FCT entry for a file). Each resource key is a number in the range 1 through 24.
  3. Specify a set of resource keys in a user's SNT entry. A user can access a resource if one or more of the resource keys for the resource matches a resource key specified in that user's SNT entry.

The figure below illustrates the process of resource key checking.

Figure 1. Resource key checking
Resource key checking
Parent topic: About Resource Security


To Add a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.
  7. Click Add.
  8. Specify the details for the resource class.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click Add.
Parent topic: Assigning Resource Permissions


To Add a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager to which the resource will be added by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the new resource will belong.
  8. Click Add.
  9. Specify the details for the resource.

    For information about the entry fields, please refer to the page help for the screen.

  10. Click Add.
Parent topic: Assigning Resource Permissions


To Assign Resource Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties.
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Specify the Access Control List(ACL) string for the resource.

    The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

    Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

    setting:actor:action-1,...,action-n

    Where:

    • setting is allow or deny
    • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
    • action-1 through action-n are permission tokens:
      • none
      • execute
      • read
      • update
      • add
      • delete
      • control
      • alter
      • all

    For example, the following ACL string:

    allow:Test group:Execute,Read,Update,Add,Delete;allow:Operator group:Read

    assigns the Test group execute, read, update, add and delete permissions for the resource, and assigns the Operator group read permission.

  10. Click OK.
Parent topic: Assigning Resource Permissions


To Edit a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class you want to update.
  8. Specify the details for the class.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click Apply.
Parent topic: Assigning Resource Permissions


To Edit a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Specify the details for the resource.

    For information about the entry fields, please refer to the page help for the screen.

  10. Click OK.
Parent topic: Assigning Resource Permissions


To Assign Resource Permissions When Using MFDS Internal Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The display and setting of permissions when using MFDS Internal Security differs from that of other security managers. In its model, you cannot create resource entities, or define Access Control Lists for them. Instead there is a predefined set of permissions, which you view and set through the permissions tab when editing user groups. Users inherit their permissions from the groups to which they belong.

The instructions below are for setting permissions for a group. For instructions on adding users to groups, see To assign one or more users to a user group and To assign a user to one or more user groups.

Note:

The permissions that you grant to a group for starting, stopping, adding, deleting and modifying enterprise servers can also be overridden for individual enterprise servers. For details, see To assign permissions on a specific enterprise server when using MFDS Internal Security.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the MFDS Internal Security Manager by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to assign permissions to.
  8. Under Permissions, check each permission that you want to grant to the group. If you want to grant all permissions under the Directory Server Administration or Servers sections, click the appropriate Allow All button.

    The permissions are displayed in an inverted tree structure. Those on lower branches include the permissions on the branches from which they descend. For example, the permission to restore a repository includes the permission to import a repository. Therefore, restore is shown as a descendant of import.

    When you grant a particular permission, any permissions that it includes are automatically granted. Hence, when you check the Restore Repository permission, the Import Repository permission is automatically checked as well.

    Where a check box for a permission is greyed out, it indicates that the permission is included by other permissions that have been granted to the group. To revoke a permission that is included by others, you must first revoke those other permissions.

Parent topic: Assigning Resource Permissions


To Delete a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to delete by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class you want to delete.
  8. Click Delete.
  9. Click OK on the Delete Confirmation page.
Restriction: You cannot delete a class which contains resources.
Parent topic: Assigning Resource Permissions


To Delete a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Click the Delete.
  10. Click OK on the Delete Confirmation page.
Parent topic: Assigning Resource Permissions


ESF LDAP Security Administration Web Interface

You can use the ESF LDAP security administration Web interface to configure LDAP for use with your Enterprise Server installation. This alternative browser-based interface enables you to administer the LDAP information outside of the MFDS user interface. It enables you to display and administer large numbers of users, groups and resources.

Note: The user used to login to the Web interface requires Update, Add, Delete access from the User Administration resource. This resource can be found under the Enterprise Server Administration resource class in LDAP.

Features

The ESF LDAP security administration Web interface has the following features:

  • Browser based graphical display of the users, groups, resource classes, and resource entities that are defined in a configured LDAP-compatible security manager such as Microsoft Active Directory, AD LDS or OpenLDAP.
  • Ability to easily sort and filter users, groups, classes, and resources.
  • Enhanced experience independent of the MFDS user interface enabling segregation of the LDAP security manager administration role from the Enterprise Server configuration and operational role.
  • Takes advantage of the new ESF LISTREFERENCES feature to enable easy determination of relationships among security objects and rules.

Limitations

The ESF LDAP security administration Web interface has the following limitations:

  • Support for nested groups is not provided within the interface. If required, you can administer nested groups from the esfadmin command-line utility.
  • Actions taken in the interface are applied to all the security managers in the security manager list. Therefore, Micro Focus recommends you only have one security manager in the security manager list. You can administer multiple different security managers by defining separate Enterprise Server regions to host the ESF LDAP security administration Web interface for each security manager required.
  • Prerequisites
  • Configuring the ESF LDAP Security Administration Web Interface
  • Operation
  • ESF LDAP Properties
Parent topic: Securing an Enterprise Server Installation


Prerequisites

The ESF LDAP administration Web interface has the following software requirements:

  • A Web browser (with a minimum required version):
    • Internet Explorer (version 11.0)
    • Firefox (version 39.0)
    • Chrome (version 43.0)
  • A listener configured as described in Configuring the ESF LDAP Security Administration Web Interface.
Parent topic: ESF LDAP Security Administration Web Interface
Related reference
Configuring the ESF LDAP Security Administration Web Interface


Configuring the ESF LDAP Security Administration Web Interface

The following steps provide guidance on how to enable the ESF LDAP security administration Web interface for a typical security manager configuration. See Configure ES Security for more information on configuring a security manager. Amend some of these steps as required for your particular configuration.

Although a listener is required to access the new ESF LDAP security Web interface, it is not necessary to manually create a listener as one is created automatically by performing the following steps:

  1. Navigate to the Enterprise Server Administration home page by clicking Home on the left pane.
  2. Click Edit on the row corresponding to the server that you want to use to access the Web interface.
    Note: Ensure that the server you create the listener for is stopped.
  3. Click Server > Properties > Security.
  4. Uncheck Use default ES Security Manager configuration.
  5. Click Apply.
  6. You need to check Use all groups in Security Facility Configuration if the user you intend to login with is not in the User Administration resource. For example, if you are using the default SYSAD user.
    Note: You need a user that has administration privileges, checking Use all groups ensures that the user has the permissions of all the groups they currently belong to, including the #DSAdmin group which provides access to user administration. If you have created a custom user with administration privileges associated with their default group you can use this without the need to check Use all groups.
  7. Click Apply.
  8. In the Security Managers List, click Add.

    This opens the Security Managers List page.

  9. Click Select for the row that contains the security manager that you want to associate with this server.
  10. Click Add.

    This adds the security manager to the server's Security Manager List. This server is then accessible with the new Web interface.

  11. Type the port number that you want the ESF LDAP security administrator Web interface to be accessed on, in the Use port field.

    If you use 0 as the port number then a dynamic port number will be allocated when the server is restarted.

  12. Check Enable Security Manager Administration GUI, and then click Apply.

    You can verify that the listener has been added by looking for an ESF Administration GUI entry in the listeners tab

  13. Click Server > Control, and then click Start.
  14. Use credentials appropriate to your security manager, and then click OK to continue.

    This reopens the Enterprise Server Administration home page.

  15. You must wait till the server has started, and then click Edit on the server you have been configuring.
  16. Click Server > Properties > Security.
  17. Click the URI provided just below the Enable Security Manager Administration GUI checkbox.

    This opens the ESF LDAP security administration Web interface within a browser. Alternatively, you can type the URI into one of the supported browsers listed in Prerequisites. You are prompted to type in your username and password before the interface opens.

    Note: If the security administration Web interface does not open after the username and password are entered, check the communications log (log.html) for errors. Certain browsers may cache information and it may be necessary to clear the cache and/or restart the browser in order to enter correct or different security credentials.
Parent topic: ESF LDAP Security Administration Web Interface
Related concepts
Prerequisites
Related reference
MLDAP ESM Module Custom Configuration Information
Configuring mldap_esm Security Manager for an LDAP


Operation

You can access the ESF LDAP security administration Web interface using the URI provided on the Server > Properties > Security tab, under the Enable Security Manager Administration GUI checkbox. Depending on the how you have configured the security manager, you might be prompted for an administrator's username and password.

The interface has a number of tabs, where each tab has a number of columns presenting various information. You can:

  • Filter the rows by typing a string in the Search field and pressing Enter.

    The number of entries is displayed right next to the Search field.

  • Change the order of the columns - drag a column to a new position.
  • Perform an action on a column - click [image] on the column header to see a list of the available actions:

    Every tab has an Action column. Click [image] to view a list of the actions that can be performed on the item in the selected row.

  • Sort the columns in ascending or descending order.
  • Hide columns by unchecking the column name.
Note: Refreshing the page or reopening the browser resets the columns displayed and their order to the default configuration.

Users tab

By default, the User tab displays the Action, Order, Account Id, Name and Description columns. You can search in this tab which filters the users and only displays the users that contain the string in the Account Id or Name columns.

Group tab

By default, the Group tab displays the Action, Order, Group and Description columns. You can search in this tab which filters the groups and only displays the groups that contained the string in the Group or Description columns.

Resources tab

By default, the Resources tab displays the Action, Classes / Resources, Description and ACL String columns. The Classes / Resources column provides a tree view of the resource classes and associated resource entities. Click [image] to expand the resource class and view any associate resource entities. You can search in this tab which filters the class resources and only displays the class resources that contain the string in the Classes / Resources or Description columns.
Note: Searching in this tab only filters the resource classes and does not return any matching resource entities.

Configuration tab

By default, the Configuration tab displays the Action, Order, Name and Module columns. This tab lists the security manager configurations of the Enterprise Server region in use.

Click [image] to display the Advanced Configuration Information dialog box and view the information used to configure the security manager such as:

  • Name
  • Module
  • Connection Path
  • Authorized ID
  • Enabled
  • Cache Limit (KB)
  • Cache TTL
  • Configuration Information
Note: This tab does not include a Search field or a count of the entries.
  • Managing Users
    Adding, editing and deleting a user.
  • Managing Groups
    Adding, editing, deleting and viewing group permissions.
  • Managing Resource
    Adding, editing and deleting resource classes and resource entities.
Parent topic: ESF LDAP Security Administration Web Interface
Related reference
Users
Groups
Resource Classes
Resource Entities


Managing Users

Adding, editing and deleting a user.
Note: In order to manage users, your user's account must have administrator's permissions.
  • To Add a User
  • To Edit a User
  • To Delete a User
Parent topic: Operation


To Add a User

To add a user perform the following steps:

  1. On the User tab, click Add User.

    This opens the Add a User dialog box.

  2. Specify the user's details.

    For further information about the fields refer to the User section.

  3. Click OK.
Parent topic: Managing Users
Related reference
Users


To Edit a User

To edit a user perform the following steps:

  1. On the User tab, click [image] in the row containing the user you want to edit, then click Edit User.

    This opens the User Config dialog box.

  2. Edit the fields as required.

    For further information about the fields refer to the User section.

  3. Click OK.
Parent topic: Managing Users
Related reference
Users


To Delete a User

To delete a user perform the following steps:

  1. On the Users tab, click [image] in the row containing the user you want to delete, then click Delete User.

    This opens the Confirm dialog box. This prompts you to confirm the action to delete the user.

  2. Click Yes.
Parent topic: Managing Users


Managing Groups

Adding, editing, deleting and viewing group permissions.
Note: In order to manage the group, your user's account must have administrator's permissions.
  • To Add a Group
  • To Edit a Group
  • To Delete a Group
Parent topic: Operation


To Add a Group

To add a group perform the following steps:

  1. On the Group tab, click Add Group.

    This opens the Add a Group dialog box.

  2. Type the group name in the Name field.
  3. Type the group description in the Description field.
  4. Click OK.
Parent topic: Managing Groups
Related reference
Groups


To Edit a Group

To edit a group perform the following steps:

  1. On the Group tab, click [image] in the row containing the group you want to edit, then click Edit Group.

    This opens the Group Config dialog box.

  2. Specify the details for the group.

    For further information about the fields refer to the Groups section.

  3. Click OK.
Parent topic: Managing Groups
Related reference
Groups


To Delete a Group

To delete a group perform the following steps

  1. On the Group tab, click [image] in the row containing the group you want to delete, then click Delete Group.

    This opens the Confirm dialog box.

  2. Click Yes.
Parent topic: Managing Groups


Managing Resource

Adding, editing and deleting resource classes and resource entities.
Note: In order to manage resources, your user's account must have administrator's permissions.
  • To Add a Resource Class
  • To Add a Resource Entity
  • To Edit a Resource Class
  • To Edit a Resource Entity
  • To Delete a Resource Class
  • To Delete a Resource Entity
Parent topic: Operation


To Add a Resource Class

To add a resource class perform the following steps:

  1. On the Resources tab, click Add Class.

    This opens the Add a Class dialog box.

  2. Specify the Class details

    For further information about the fields refer to the Resource Class section.

  3. Click OK.
Parent topic: Managing Resource
Related reference
Resource Classes


To Add a Resource Entity

Resource entities can only be added to resource classes. To add a resource entity perform the following steps:

  1. On the Resources tab, click [image] in the row containing the class resource you want to edit, then click Edit Class.

    This opens the Class Config dialog box.

  2. Click Resources tab.
  3. Click Add a Resource.

    This opens the Add a Resource dialog box. For further information about the fields refer to the Resource Entity section.

  4. Click OK.

    The resource entity is added to the list in the Class Config dialog box.

  5. Click OK.
Parent topic: Managing Resource
Related reference
Resource Entities


To Edit a Resource Class

To edit a resource class perform the following steps:

  1. On the Resources tab, click [image] in the row containing the resource class you want to edit, then click Edit Class.

    This opens the Class Config dialog box.

  2. Specify the details for the resource class.

    For information about the fields, please refer to the Resource Class section.

  3. Click OK.
Parent topic: Managing Resource
Related reference
Resource Classes


To Edit a Resource Entity

To edit a resource entity perform the following steps:

  1. On the Resources tab, expand the tree view for the class that contains the resource entity that you want to edit. You can expand the tree nodes by clicking on the [image] icon.
  2. Click [image] in the row containing the resource entity you want to edit, then click Edit Resource.
  3. Specify the details for the resource entity in the Resource Config dialog box.

    For information about the fields, please refer to the Resource Entity section.

  4. Click OK.
Parent topic: Managing Resource
Related reference
Resource Entities


To Delete a Resource Class

To delete a resource class perform the following steps:

  1. On the Resources tab, click [image] in the row containing the resource class you want to delete, then click Delete Class.

    This opens the Confirm dialog box.

  2. Click Yes to confirm the permanent deletion of the resource class.
    Note: You can not delete a resource class if it has attached resource entities. You must delete all attached resource entities before you can delete the parent resource class.
Parent topic: Managing Resource


To Delete a Resource Entity

To delete a resource entity perform the following steps:

  1. On the Resources tab, expand the tree view for the class that contains the resource entity that you want to delete. You can expand the tree nodes by clicking on the [image] icon.
  2. Click [image] in the row containing the resource entity you want to edit, then click Delete Resource.

    This opens the Confirm dialog box.

  3. Click Yes to confirm the permanent deletion of the resource entity.
Parent topic: Managing Resource


ESF LDAP Properties

You can configure the ESF LDAP properties from the various tabs by clicking on the action icon and specifying the following:

  • Users
    You can specify properties about your ESF LDAP users on the User Config dialog box.
  • Groups
    You can specify properties about your ESF LDAP groups on the Group Config dialog box.
  • Resource Classes
    You can specify properties about your ESF LDAP resource classes on the Class Config dialog box.
  • Resource Entities
    You can specify properties about your ESF LDAP resource entities on the Resource Config dialog box.
Parent topic: ESF LDAP Security Administration Web Interface


Users

You can specify properties about your ESF LDAP users on the User Config dialog box.

Properties

List of properties and their definitions.

Account ID
The ID for the user account.
Name
The full name of the person assigned to this account.
Default Group
Specify a default user group for this user.

Where a user verification request does not specify a group, this default group is used.

Allow Logon
Indicates whether this user can logon.
Must Change Password
Forces the user to specify a new password the first time they login.
Description
A description of the user account.
Password
Specifies the new password of the user. Password lengths are restricted to 8 or fewer characters if you are logging into an MSS such as CICS, JES or IMS. The password length is limited to 20 or fewer characters if you are logging into MFDS. If you leave this field blank, the existing password is unchanged.
Note: Multibyte characters, whitespace, some punctuation characters, and control characters may cause problems in passwords. Some external security managers restrict which characters can be used in passwords, and some characters may be altered by ASCII-EBCDIC translation if passwords are entered through 3270 terminal sessions. Micro Focus recommends using letters, numbers, and punctuation characters that are in both ASCII and the default EBCDIC code page.
Confirm Password
Specify the case-sensitive new password of the user. If you enter a value that does not match the value in Password, an error is generated and the existing password is unchanged.

Advanced

Advanced properties and their definitions.

UID
Specifies the Unique reference ID, if this is not supplied then one is generated automatically when the user is created.
Operator ID
Specifies the 3-byte MSS operator ID associated with the unique reference ID.
Timeout (mins)
Specifies the MSS user timeout in minutes.
Password Expires
Specifies the account expiration date. The date format depends on the ESM in use. With the MLDAP ESM, you need to use the date format required by the LDAP server. You need to check to determine what this format is.
For example:
EXPIRES=YYYYMMDDHHMMSS.0Z
where 0Z represents the GMT zone. To simplify the selection of an expiry date, click [image] to display a calendar.
Use Token
Permission to use passtokens.
Create Token
Permission to create passtokens
Custom Configuration
Custom text (not used by Micro Focus).

Group Membership

List of groups that the user has joined on the left side and a list of all available groups on the right side.

Joined
This is a list of all the groups that the user has joined.
Groups
This is a list of all the groups that are available to join.

References

Lists the references associated with the user. This includes a reference to the user itself and the default group if defined in the Properties tab.

Type
Displays the object type and can be USER, GROUP or RESOURCE.
Name
Name of the references.
Comment
Provides information on the type of reference and can be one of the following:
  • The user itself
  • User's default group
  • Explicit group member
Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a User
To Edit a User


Groups

You can specify properties about your ESF LDAP groups on the Group Config dialog box.

Properties

List of properties and their definitions:

Description
A description of the group.

Members

Users member properties and their definitions:

Members
This is a list of all the users that are members of the group.
Users
This is a list of all the users that are available to join the group.

References

Lists the references associated with the user. This includes a reference to the group itself as a default:

Type
Displays the object type and can be USER, GROUP or RESOURCE.
Name
Name of the reference.
Comment
Provides information on the type of reference and can be one of the following:
  • The group itself
  • Explicit group member
Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a Group
To Edit a Group


Resource Classes

You can specify properties about your ESF LDAP resource classes on the Class Config dialog box.
Name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a Resource Class
To Edit a Resource Class


Resource Entities

You can specify properties about your ESF LDAP resource entities on the Resource Config dialog box.
Name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

ACL String

Specify the Access Control List(ACL) string for the resource entity. The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

setting:actor:action-1,...,action-n

Where:

  • setting is allow or deny
  • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
  • action-1 through action-n are permission tokens:
    • none
    • execute
    • read
    • update
    • add
    • delete
    • control
    • alter
    • all

For example, the following ACL string:

allow:Test group:Execute,Read,Update,Add,Delete;allow:Operator group:Read

assigns the Test group execute, read, update, add and delete permissions for the resource, and assigns the Operator group read permission.

Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a Resource Entity
To Edit a Resource Entity


Migrating from Enterprise Server Early Versions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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
Parent topic: Securing an Enterprise Server Installation


Integrating Security from Early Releases: casesm

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The CAS ESM Module (casesm) uses the Enterprise Server legacy security definitions (stored in the CICS resource tables).

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the process you use to export the configurations defined in the MFDS Internal Security module so that you can use them to configure an Active Directory.

  • To Export Micro Focus LDAP Schema Extensions
  • To Export Users and Groups to an LDIF File
  • To store the directory server repository in an LDAP server
Parent topic: Migrating from Enterprise Server Early Versions


To Export Micro Focus LDAP Schema Extensions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can use an LDAP repository to hold information for Micro Focus applications, its schema must be extended to support the Micro Focus objects. To do this, you create an LDIF (Lightweight Directory Interchange Format) file containing the extensions.

Use themfds -L command line options to do this.

Syntax:

mfds -L [schema partition Distinguished Name] option ldif-filename [schema-version-1] [schema-version-2]

Parameters:

schema partition Distinguished Name | Specifies the DN of the partition in the Directory Information Tree where the schema definition is held. The schema partition holds, amongst other things, attributeSchema and classSchema objectclass instances.
option | Specifies the target directory server type: 0 = Microsoft Active Directory Lightweight Directory Server (AD LDS), 1 = Active Directory (Default), 2 = OpenLDAP, 3 = Sun Directory. Note: If you specify the ldif-filename, you must also specify a value for this parameter.
ldif-filename | Specifies the name of the destination file. Default: mfds_schema_[ mfds version ].ldf (e.g. mfds_schema_1.05.09.ldf)
schema-version-1 | Specifies the version of the schema extensions to be generated: 0 = current schema version (Default). Numbers greater than 0 specify older schema versions.
schema-version-2 | This option is used for upgrading from a previous schema. If schema-version-2 is specified and is less the schema-version-1, the output file is a delta between the schema-version-1 and schema-version-2. If schema-version-2 is greater than or equal to schema-version-1, this option is ignored.

Example:

To create a LDIF file called mfds-schema.ldf specifically for an Active Directory using the this_machine.mycom.com AD server, issue:

mfds -L DC=mycom,DC=com 1 c:\mfds-schema.ldf

However, in practice, rather than using a specific schema partition DN value, administrators may want to have a portable LDIF file where the root DN can be specified externally. If the Windows LDFIDE tool is used to extend the repository schema, the generated LDF file could use DC=X as the schema partition name. This can then be replaced at import time. For example,

mfds -L DC=X 1

should be sufficient for most installations.

Parent topic: Exporting MFDS Internal Security Definitions


To Export Users and Groups to an LDIF File

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. To export existing Directory Server users and groups from the MF Directory Server repository to an LDIF file, use the mfds -e command. The syntax is as follows:

    mfds -e root DNuser partition DNgroup partition DNresource partition DNschema formatldif-filenamesec-path

    root DN | The application partition to which all of the exported entries will be assigned.
    user partition DN | The name of the container within the application partition to which the 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Update the schema of the target LDAP server to support the Enterprise Server configuration objects. How you do this will vary slightly depending on the particular LDAP server that you are using. In all cases, you will use the MFDS -L command to create an LDIF file containing the necessary extensions and then use the relevant import command for your LDAP server.
  2. Click Options under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  3. From the drop-down list under Repository location select ldap://.
  4. Specify the LDAP server, connection information and the LDAP credentials required to write to the server.
Parent topic: Exporting MFDS Internal Security Definitions


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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 typical 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: Beginning with Enterprise Server 4.0:
  • 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, the Enterprise Server Administration 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.

Recommendations

Micro Focus recommends you consider the following:

  • 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 information
Deployment Listeners


Security Reference Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains security-related reference information.

  • Environment Variables used in Enterprise Server Security
  • Resource Classes used by Enterprise Server
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following topics are concerned with the environment variables that you are likely to use in the context of Enterprise Server security.

  • Enterprise Server Default Users and Associated Environment Variables
Parent topic: Security Reference Information


Enterprise Server Default Users and Associated Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Enterprise Server has a set of default users that are used when no user is logged on for ESMAC authentication:
Environment | User | Associated Environment Variable
ESMAC | mfuser | ES_USR_DFLT_ESMAC

Using the environment variables, the default users can be overwritten by the users of your choice. For instance we could overwrite the ESMAC default user using in the region configuration.

configuration:
[ES-Environment]
ES_USR_DFLT_ESMAC=ESMACUSR
Parent topic: Environment Variables used in Enterprise Server Security


Resource Classes used by Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each item (e.g. program, file, transaction) to which access is controlled is a called a resource. A resource has a name and a class, which indicates the type of the resource. For example, each enterprise server is a resource, and all enterprise servers belong to the same resource class.

A resource name must be unique within its class. That is, you can define two or more resources with the same name, provided that they belong to different classes.

Resources, such as ES configuration definitions in MFDirectory Server, use resource class names defined by Micro Focus. Users can also define their own resource classes for performing explicit access checks in applications.

When a user requests access to a resource the security facility relays the request to the external security manager, specifying the user, the resource and the resource class. The security manager will then look for resource rules that match the resource name. The processing of a request is dependent on the external security manager.

The entities and classes used are specified in the tables listed below.

  • Resource Classes for Communications Server
  • Resource Classes for ESF Features
  • 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
Parent topic: Security Reference Information


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
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 ESMAC and Operator Command Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.
The list below defines the name of each default resource class used in Enterprise Server for ESMAC and operator command security, its meaning, the type of resource entities it contains, and the minimum permission that a user requires on the entities.
OPERCMDS
Relation
Class for operator commands used by casstart/casstop/casfile/cassub/casout... commands
Entities
Entity | Description
JESALIAS | If the user has 'Update' access to this resource, they are able to update or delete entries from the Alias table. If the user only has 'Read' access to this resource, the Update and Delete options are not available. If the user has 'None' access to this resource, they cannot access the Alias table at all.
Access Level
None, Read, or Update.
MFESMAC
Relation
MAC Class for controlling access to ESMAC Resources.
Entities
Entity | Description
TABLE | If your user has "Update" access to this resource then they will have the ability to interact with the majority of ESMAC function. Primary items controlled by this setting are the appearance of the buttons for controlling the SEPS (Tracing, Stopping), Stopping the Server, Accessing the console.log, trace data, dump data. If a user has "None" then they will not be shown any buttons other than the Server Status Button and the Monitoring button in addition to the Chg User button which allows them to sign-on. The basic effect of no access to this resource is that they are treated in the same way as an unauthenticated user. If they have "Read" access they will be shown the options but will be unable to perform any updates. If they have "Update" access or greater than they have full control of these functions.
GRP This resource controls access to the buttons under the Resources 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.
BAT, RNL, SIT, SNT, SUP, URI, XAT, XLT | This controls the access a user has to the various resources when selected via the By Type or Active menus under the Resources 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.
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
Access Level
None, Read, Update.
Parent topic: Resource Classes used by Enterprise Server


Resource Classes for MF Directory Server

Describes the resource classes and entities that are used to control access to the functionality of Enterprise Server Administration.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: The management of permissions for MFDS Internal Security differs from that for other Security Managers, and is covered separately by Legacy Directory Server Security Model.
  • Class - Enterprise Server Administration
  • Class - Servers
Parent topic: Resource Classes used by Enterprise Server


Class - Enterprise Server Administration

Restriction: This topic applies only when the Enterprise Server feature is enabled.
This class contains a set of predefined entities that correspond to the screens and functions used to manage the configuration of MF Directory Server and to access the user, group and resource property screens for security managers. The entities, the functions that they control, and the permissions that a user requires are as follows:
Entity | Controls | Permission required
Repository Access | Saving a copy of the repository to a file system directory. | Read
Importing data from a file system directory. | Add
Restoring a repository from a file system directory. The process of restoring overwrites all of the information in the current repository. | Add, Delete
Deletion of the entire Directory Server repository including all enterprise servers. | Add, Delete
Options | Changing of Directory Server options. | Update
Object Permissions Allocation of permissions on individual enterprise servers.

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 Adminstration GUI
  • Security Manager List
Update, Add, Delete
Parent topic: Resource Classes for MF Directory Server


Class - Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The entities contained in this class correspond to, and control the configuration of, Enterprise Servers.

Entity | Controls | Permission required
Server Name | Viewing of enterprise server configuration information. | Read
 | Starting and stopping of enterprise servers. | Execute
 | Modification of configuration information for an enterprise server. | Update
 | Adding of listeners, services and packages to an enterprise server. When set as a default permission for the group, it also permits the adding of enterprise servers. | Add
 | Deletion of enterprise servers, and of listeners, services and packages from an enterprise server. | Delete
Parent topic: Resource Classes for MF Directory Server


WebSphere MQ Switch Profiles

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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


Profiles for Queue Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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


Solutions, Restrictions, and Changes in Behavior

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Service Deployment and Security
  • Configuring Credentials for Starting and Stopping Enterprise Servers
  • Sign-on Disabled for Default Users
  • Configuring Sun Java System Directory as a Security Manager
Parent topic: Security Reference Information


Service Deployment and Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server provides a deployment feature to 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


Configuring Credentials for Starting and Stopping Enterprise Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you start or stop an enterprise server from MF Directory Server, you are given the option of supplying two sets of credentials. The first is the operating system credentials under which the processes are to run (this is labelled Start/Stop processes as). The second, labelled Use Enterprise Server credentials of: is checked by the security features of MF Directory Server and Enterprise Server. The requirements of this second set of credentials are described below.

When an enterprise server starts, it connects to MF Directory Server to obtain its configuration details and to update its status information. To do this, it requires suitable Directory Server user credentials (that is, credentials that Directory Server will verify and authorize through the External Security Facility). You can specify that it should connect using a built-in default user or using the credentials with which you are currently logged on to Enterprise Server Administration. Alternatively, you can specify a different Directory Server username and password.

If you choose to use the built-in default user, the process is as follows:

  1. The enterprise server is started by the casstart command.
  2. It connects to MF Directory Server to obtain its configuration settings via the default user, mf_mdsa.
  3. The enterprise server subsequently spawns its communications server(s), referred to as MFCS.
  4. MFCS connects to MF Directory Server using the default user, mf_cs. This user requires permissions to do things like reading and writing data to the MF Directory Server repository. For example, it can read what configuration the server has, and write changes to the status field.
  5. The enterprise server will then use another default user, mfuser, as the identity for operations.
  • mf_cs and mf_mdsa must exist in the security context of MF Directory Server. That is, depending on the security configuration, they must exist in one of the security repositories used by MF Directory Server. The users must also have suitable permissions. At this point in time, the users must be members of a group called "#System" and this group must have modify permission on the resource entity in the Servers class that corresponds to the enterprise server. For more on the resource classes and entities controlling access to MF Directory Server resources, see Resource Classes for MF Directory Server.
  • mfuser must exist within the security context of the enterprise server and must have appropriate permissions on the casstart entity in the OPERCMDS class. For more about OPERCMDS, see Resource Classes for ESMAC and Operator Command Security.

If you choose to use the credentials with which you are currently logged on to Enterprise Server Administration, or if you specify alternative credentials, the enterprise server and MFCS will use those credentials when connecting to MF Directory Server. The enterprise server will also use the credentials internally.

Therefore, the user that you specify must exist within the security domain of both the MF Directory Server and the enterprise server. In addition:

  • To read and update information in MF Directory Server

    In the MF Directory Server domain, it must be a member of the #System group, and this group must have modify permission on the resource entity in the Servers class that corresponds to the enterprise server

  • To run the start command in Enterprise Server

    In the context of the enterprise server, it must have alter permission on the casstart entity within the OPERCMDS resource class

To stop an enterprise server, the requirements are the same, except that the user requires alter permission on the casstop entity with the OPERCMDS resource class.

Note:

Where an external security manager is configured for the enterprise server, a userid and password must be supplied when stopping it through any external method, such as casstop.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Sign-on Disabled for Default Users

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When security is enabled, the default users can no longer sign-on to the system from a terminal.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Configuring Sun Java System Directory as a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the steps you need to perform in order to configure Sun Java System Directory to use it as an Enterprise Server security manager and configuration repository. Micro Focus has developed and tested under Sun Java System Directory Server Enterprise Edition 6.1. Later revisions of Sun Java System Directory should be compatible with Micro Focus Enterprise Server Security Manager and Configuration Repository but this is not guaranteed. Micro Focus will review any issues found in later releases of Sun Java System Directory but cannot guarantee compatibility.

Note:

The commands in this section make the following assumptions:

  • You have downloaded and installed Sun Java System Directory Server Enterprise Edition 6.1 as described on the Sun web site.
  • You have installed into /usr/local/dsee.
  • You are using port 3880. This is an arbitrarily-chosen port. Check with your system administrator to find out what ports are available on your system.
  • You are using the dsadm command-line tool instead of the Sun Java Web Console GUI Directory Service Control Centre.
  • You are using the scratch directory /usr/local/dsee/var/example.

You will need to change the commands if your installation uses settings other than these.

When configuring an external Security Manager connection on Solaris, it is possible to specify the use of the Sun-provided LDAP client module for LDAP communications with the external Security Manager. The following configuration text is required in the Security Manager Configuration Information area:

[LDAP]
provider=/usr/lib/libldap.so
Note: A Security Manager connection configured on Solaris is not limited to using Sun Java Directory Server. It can communicate with other LDAP-based external Security Managers such as Microsoft Active Directory or Open LDAP.
  1. To set up the Sun Directory Server configuration and database directories:
    1. Enter the following command:
      dsadm create -p 3880 /usr/local/dsee/var/example

      The following information is displayed: Choose the Directory Manager password:

    2. Specify the Directory Manager password.

      The following information is displayed: Confirm the Directory Manager Password

    3. Confirm the password.

      The following information is displayed: Use 'dsadm start '/usr/local/dsee/var/example'' to start the instance.

  2. To start the instance and confirm that it is running:
    1. Enter the following command:
      dsadm start /usr/local/dsee/var/example

      The following information is displayed: Server started: pid=24879

    2. Enter the following command:
      dsadm info /usr/local/dsee/var/example
      The following information is displayed:
      Instance Path | /usr/local/dsee/var/example
      Owner | hub(staff)
      Non-secure port | 3880
      Secure port | 1636
      Bit format | 64-bit
      State | Running
      Server PID | 24879
      DSCC url -
      SMF application name -
      Instance version | D-A00
    3. Use an LDAP browser to connect to the instance at machine-address:3880 using id DN: "cn=Directory Manager" and password "password" to confirm it is running. Currently only the RootDSE data is displayed.
  3. To extend the schema, create a text file called 99container.ldif in /usr/local/dsee/var/example/config/schema. The file should contain the following:
    dn:cn=schema
objectClasses:(1.2.840.113556.1.3.23 NAME 'container' SUP top STRUCTURAL MUST (cn))
  4. To generate the Micro Focus Schema Extension file, enter the following command:
    mfds -l DC=X 3	/usr/local/dsee/var/example/config/schema/99microfocus.ldif
  5. To ensure the Directory Server instance picks up the new schema files, enter the following command:
    dsadm restart /usr/local/dsee/var/example
  6. To confirm the Micro Focus schema has been installed, enter the following command:
    /usr/local/dsee/dsrk6/bin/ldapsearch -b cn=schema -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password "objectclass=*" > schema.txt

    This command dumps the active schema to a file called schema.txt . You can search this file to confirm that it includes the expected "container" and "microfocus" attributeTypes and objectClasses.

  7. To create a default suffix for an example DIT:
    1. Enter the following command:
      dsconf create-suffix -p 3880 dc=example,dc=com

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.
  8. To confirm that the new suffix exists:
    1. Enter the following command:
      dsconf list-suffixes -p 3880

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.

      The following information is displayed: dc=example,dc=com

  9. To import the standard shipped example LDIF file.
    1. Enter the following command:
      dsconf import -p 3880 /usr/local/dsee/ds6/ldif/Example.ldif dc=example,dc=com

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.

      The following information is displayed:

      New data will override existing data of the suffix "dc=example,dc=com".

      Initialization will have to be performed on replicated suffixes.

      Do you want to continue [y/n] ?

    3. Press 'Y'

      The following information is displayed:

      ## Index buffering enabled with bucket size 40
      ## Beginning import job...
      ## Processing file "/usr/local/dsee/ds6/ldif/Example.ldif"
      ## Finished scanning file "/usr/local/dsee/ds6/ldif/Example.ldif" (160 entries)
      ## Workers finished; cleaning up...
      ## Workers cleaned up.
      ## Cleaning up producer thread...
      ## Indexing complete.
      ## Starting numsubordinates attribute generation. This may take a while, please wait for further activity reports.
      ## Numsubordinates attribute generation complete. Flushing caches...
      ## Closing files...
      ## Import complete. Processed 160 entries in 4 seconds. (40.00 entries/sec)
      Task completed (slapd exit code: 0).
  10. Refresh the LDAP browser to ensure that you can see the new DIT contents. There should be a new "example" DC, containing organizational units for groups and people.
  11. Add the standard Micro Focus containers:create a file /home/hub/staff/example/mf-containers-sun.ldif containing the following:
    dn: cn=Micro Focus,dc=example,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Micro Focus,dc=example,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Enterprise Server Users,cn=Micro Focus,dc=example,dc=com
cn: Enterprise Server Users
objectClass: container

dn: cn=Enterprise Server User Groups,cn=Micro Focus,dc=example,dc=com
cn: Enterprise Server User Groups
objectClass: container

dn: cn=MFDS Repository,cn=Micro Focus,dc=example,dc=com
cn: MFDS Repository
objectClass: container
  12. Add containers to the DIT:
    1. Enter the following command:
      /usr/local/dsee/dsrk6/bin/ldapmodify -a -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password -f /home/hub/staff/example/mf-containers-sun.ldif

      The following information is displayed:

      bin_ldapmodify: started Wed Sep 19 16:31:26 2007
      ldap_init( 127.0.0.1, 3880 )
      add cn:
      Micro Focus
      add objectClass:
      container
      adding new entry cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server Resources
      add objectClass:
      container
      adding new entry cn=Enterprise Server Resources,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server Users
      add objectClass:
      container
      adding new entry cn=Enterprise Server Users,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server User Groups
      add objectClass:
      container
      adding new entry cn=Enterprise Server User Groups,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      MFDS Repository
      add objectClass:
      container
      adding new entry cn=MFDS Repository,cn=Micro Focus,dc=example,dc=com
      modify complete
  13. Refresh the LDAP browser to ensure that you can see the new DIT contents. There should be a new "Micro Focus " container with the user "Enterprise Server" subcontainers.
  14. Add the Directory Server resources and users.
    1. Enter the following command:
      mfds -e "cn=Micro Focus,dc=example,dc=com" "cn=Enterprise Server Users" "cn=Enterprise Server User Groups" "cn=Enterprise Server Resources" 2 "/home/hub/staff/example/mfds-users-sun.ldif"
      Note:

      There is no difference between the OpenLDAP and Sun syntax for the generated LDIF file, so no Directory Server changes have been required.

  15. Import the generated mfds_users_sun.ldif file.
    1. Enter the following command:
      /usr/local/dsee/dsrk6/bin/ldapmodify -a -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password -f /home/hub/staff/example/mf-users-sun.ldif
  16. Refresh the LDAP browser to ensure that you can see the new DIT contents. The "Enterprise Server" subcontainers now contain the "Enterprise Server Administration", "schemaadmin" and "#"-prefixed Directory Server default user groups.
  17. In Directory Server, configure a new external security manager as follows:
    Name | Sun Directory 6.1 machine-address:3880
    Module | mldap_esm
    Connection Path | machine-address:3880
    Authorized ID | cn=Directory Manager
    Description | Test Sun Directory ESM
    Configuration Information | [LDAP]
    Base=cn=Micro Focus,DC=example,dc=com
    user container=CN=Enterprise Server Users
    group container=CN=Enterprise Server User Groups
    resource container=CN=Enterprise Server Resources
  18. Change the MF Server Directory Security Manager List to use this external security manager and turn on administrative security.
Parent topic: Solutions, Restrictions, and Changes in Behavior


Using External Security Facility (ESF) Features

ESF features that might be useful in your organization include:

  • 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
Parent topic: Securing an Enterprise Server Installation


ESF Caching

ESF supports caching (remembering) the results of some security requests. This can improve performance, sometimes dramatically, by eliminating some calls to the configured Security Managers.

There are two types of ESF caching. The ESF manager itself can cache results. When a request matches one in the ESF cache, the ESM Modules are not called, and the cached result is returned. ESF also has a mechanism for ESM Modules to cache information that may be expensive to retrieve, but currently no ESM Modules make use of that feature. That means caching is only active if it is enabled in the ESF configuration, not in the security manager configuration.

  • What is Cached?
  • Enabling and Configuring Caching
Parent topic: Using External Security Facility (ESF) Features
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 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 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 Caching


Requests

The requests setting specifies what types of ESF requests can be cached. It is set to a list of tokens, separated by commas or spaces. The possible tokens are:

auth-allow
Cache Auth requests that result in access allowed
auth-deny
Cache Auth requests that result in access denied
auth-unknown
Cache Auth requests for resources that are not known to the ESM(s)
auth
Same as "auth-allow auth-deny"
verify-allow
Cache Verify requests that result in sign-on allowed
verify-deny
Cache Verify requests that result in sign-on denied
verify
Same as "verify-allow verify-deny"
xauth-allow
Cache XAuth requests that result in access allowed
xauth-deny
Cache XAuth requests that result in access denied
xauth-unknown
Cache XAuth requests for resources that are not known to the ESM(s)
xauth
Same as "xauth-allow xauth-deny"

The default is requests=auth xauth.

Parent topic: Enabling and Configuring Caching
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 Caching


Flush on Change

Set flush on change to yes or 1 to tell the cache that it should discard any cached Verify result if it sees another request for the same user with a different result. See Using Flush on Change for more information. This is only useful when Verify caching is enabled.

Parent topic: Enabling and Configuring Caching
Related concepts
Using Flush on Change


Report Interval

Periodically, processes that use ESF will report some statistics about the cache, such as how many entries are in use and what percentage of requests are fulfilled using the cache (the cache "utilization" or "hit rate"). The information is reported as an ESF message, so it will appear in the console log (for CAS processes) or the MFDS journal. By default, this happens about every hour, though processes will only report it when an ESF request is made, so idle processes (for example, SEPs that are never used) won't report.

You can configure how often this reporting happens by setting the report interval option. Its value is an integer, representing the approximate time between reports in seconds. Setting this to 0 disables reporting.

Parent topic: Enabling and Configuring Caching


Example

[Cache]
 # Enable Verify caching, as well as Auth and XAuth, including the result of
 # requests for unknown resources
 requests=verify, auth, xauth, auth-unknown, xauth-unknown
 # Discard Verify result when a different request for the same user is processed
 flush on change=yes
 # Report cache statistics about every half-hour (1800 seconds)
 report interval=1800
Parent topic: Enabling and Configuring Caching


External Administrative Update Notification

ESF uses external security managers to make security decisions. Because those managers are not part of ESF, administrative changes to security information - changes to the security information for users, groups, or resources - are often made directly to the managers without any interaction with ESF. In some cases, it's necessary to notify ESF of these changes, so it (and its ESM Modules) can flush any cached results and update any internal information regarding the updated entity.

The ESF Administrative Update Notification request is part of the ESF API. It lets the calling environment notify ESF that one or more administrative changes have been made in an external security manager, so it should update any internal information that may be affected.

  • Using Update Notification Requests
  • Making an Update Notification Request
  • Handling Update Notifications in an ESM Module
Parent topic: Using External Security Facility (ESF) Features


Using Update Notification Requests

Administrative updates could include deleting a user, changing membership in a group, updating the access controls for a resource, and so on.

Enterprise Server components that use ESF provide various ways for an administrator to trigger an Administrative Update Notification request to ESF. After making security changes, you may need to tell MFDS and/or one or more Enterprise Servers to notify ESF, so that running systems pick up the security changes. This might be done through a GUI or with a command-line client; see the Enterprise Server administration documentation for details.

The Enterprise Server component will then make an Administrative Update Notification request to its ESF subsystem. ESF will flush any related cached results, and notify the affected ESM Module to do the same.

In environments where multiple processes use ESF and communicate through shared memory, such as ES/MTO, one process will handle each Update request. That process will flush any affected data from shared memory. However, each individual process will also need to be notified of the update before they handle any other ESF requests, in case those processes have cached security information in private memory.

So each time CAS SEPs make an ESF call, they check to see if any updates have been processed by other SEPs. If so, they will flush any relevant process-private data, and call the affected ESM Modules to instruct them to do the same.

These "pending update" operations come in two types. If only one update has been processed since the last time ESF was called, ESF will flush any data affected by that single update. However, if multiple updates have been processed, ESF flushes all cached information (also called a "refresh"). This avoids having to save an unbounded number of old update requests for processes that are rarely activated.

Parent topic: External Administrative Update Notification


Making an Update Notification Request

Administrative Update Notification uses the UPDATE form of the ESF API.

The Update Notification request has only one required parameter, a pointer to a valid ACEE (returned by an VERIFY request). Note that this means that Update Notifications require a valid set of user credentials. This allows Update Notifications to be audited with user information, and in the future may be used to restrict access to the Update Notification feature.

The Update Notification request can contain additional information that describes what was updated. Setting this information may reduce the amount of cached information that ESF and the ESM Modules have to discard, or the additional work needed to be done by the ESM Modules to update other internal state (such as information about group membership).

Not setting this additional information has some performance cost, but will probably only be noticeable under relatively heavy loads.

The optional fields include:

  • safpb_update::safpb_update_ENTITY_len and safpb_update::safpb_update_ENTITY_ptr: These fields can be set to indicate what entity (user, group, or resource) was affected by the change.
  • safpb_update::safpb_update_ACTION: This field can be set to indicate what action was performed: adding, changing, or removing an entity in the external security manager. The default (0) is other, which ESF treats as a generic request to flush information about the entity.
  • Safpb_Parameter_Block::safpb_type (note this is a field in the ESF parameter block itself, not in the Update structure): This field can be set to indicate what type of entity is affected. Possible values are:
    • saf78_TYPE_UPDATE_USER: A user definition was updated. Set safpb_update::safpb_update_ENTITY_ptr to point to a string with the username, and safpb_update::safpb_update_ENTITY_len to the length of the username.
    • saf78_TYPE_UPDATE_GROUP: A group definition was updated. Use safpb_update::safpb_update_ENTITY_ptr and safpb_update::safpb_update_ENTITY_len for the group name.
    • saf78_TYPE_UPDATE_RESOURCE: A resource access control definition was updated. Use safpb_update::safpb_update_ENTITY_ptr and safpb_update::safpb_update_ENTITY_len for the resource name.
    • saf78_TYPE_UPDATE_USERS: Multiple users were updated. ESF will flush all user-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_GROUPS: Multiple groups were updated. ESF will flush all group-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_RESOURCES: Multiple resources were updated. ESF will flush all resource-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_ALL (default): ESF will flush all cached information.

Note that if a user's primary group is changed, that will generally be a user update. Supplementary group membership may be stored as part of a user's definition or as part of a group's definition, depending on the ESM. For the MLDAP ESM Module, changes to a user's supplementary group information should be signalled with a saf78_TYPE_UPDATE_GROUP Update request.

You can also set the ESM Index in the request block to a non-zero value to indicate that the specified ESM Module is the one to receive the update notification. (ESM Modules are numbered consecutively from 1, in the order that they're shown in the security configuration in MFDS.) Unless performance becomes an issue, however, we recommend leaving this set to 0 and letting all ESM Modules be notified, to avoid errors that could leave an ESM Module with stale data.

Parent topic: External Administrative Update Notification


Handling Update Notifications in an ESM Module

ESF uses the optional ESM Update callback to notify ESM Modules of Update Notification requests. ESM Modules need to support this callback if they want to be informed of updates. See the ESF ESM Module Interface for more information.

Parent topic: External Administrative Update Notification


ESF Passtokens

Passtokens are an optional ESF feature for communicating a user's identity between security domains. Passtokens let one Enterprise Server component (an enterprise server region or MFDS) 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 may be used for these purposes:

  • Administrator convenience. When an administrator is signed on to either the MFDS administrative user interface or ESMAC, and switches to the other, the component that the administrator is coming from 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.

  • Access to Passtokens
  • Using Passtokens
  • Passtoken API
Parent topic: Using External Security Facility (ESF) Features
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, on the other hand, tells ESM Modules to attempt to act independently of each other. With federation disabled, the access control rules defined in one ESM should only apply to users who are also defined in that ESM.

There is also a "compatibility" federation setting, which maintains the behavior of ESF 1.13 and earlier. If compatibility federation mode is set, ESM Modules may have some interaction, possibly leading to unexpected results in some cases. This is the default, to avoid introducing incompatible behavior in existing installations. However, if you have multiple ESMs configured ("stacked"), you should probably explicitly enable or disable federation.

If you are not sure what setting to use, try the following guidelines:

  • If your configuration only has one ESM, you don't need to worry about configuring federation.
  • If your configuration has multiple ESMs, but you aren't using the MLDAP ESM Module, or you only have one instance of the MLDAP ESM Module, you don't need to configure federation. You might want to, though, in case it becomes relevant in a later release.
  • Do you define users in one ESM, and the groups they belong to in another? If so, you should enable federation (you expect your security information to be combined).
  • Do you define users and/or groups in one ESM, and resource access rules that apply to them in another? If so, you should enable federation.
  • Are the resource access rules defined in each ESM meant only to apply to users and groups known to that ESM? If so, you should disable federation (you expect your ESMs to act independently).

If none of the above apply, you can probably disable federation.

Parent topic: Security Federation


Configuring Federation

Federation is configured using the configuration text area of the relevant Security Configuration page in the MFDS administration user interface. This is the security configuration tab for an individual server, or the "Default ES Security" page in the global security settings, or the "MFDS Security" page.

Note: It is not the Security Manager Configuration page, where you specify the ESM Module name.

To configure federation, add the following section:

[Operation]
Federate=setting

where setting is yes, no, or compatible. The default is compatible, which preserves the behavior of ESF 1.13 or older.

Parent topic: Security Federation


ESF Manager Messages and Logging

ESF Manager generates various log messages regarding errors, warnings, and successful completion of infrequent activities (such as loading and initializing an ESM Module). These messages are sent to an environment-specific logging facility, such as the CAS Console Log and the MFDS Journal. (See saf-env.c for more information on ESF Manager environments.)

Each ESF log message has:

  • A number. Each of the different messages is assigned an integer number in the range 0-8999; messages 9000-9999 are reserved for customer use. Message numbers are more or less grouped by ESF Manager component:
    Manager Interface | Messages 0-99
    ESF API Processing | Messages 100-199
    ESM Module Interface | Messages 200-299
    Environment Support | Messages 300-399
    Cache | Messages 400-499
    User Exit Processing | Messages 500-599
    Auditing | Messages 600-699
    ESM Modules | Messages 1000-1999
    Temporary | Messages 2000-2999
  • A level: informational, warning, error, or critical (fatal error), indicated by the letters "I", "W", "E", and "C".
  • Message text. ESF Manager message text is retrieved from a message catalog for internationalization purposes; if a catalog for the current language is not available, a default English message is used.
  • For some messages, substitution parameters are replaced with event- specific details.
  • Manager Interface Messages
  • ESF API Processing Messages
  • ESM Module Interface Messages
  • Processing Environment Messages
  • Cache Messages
  • User Exit Messages
  • Auditing Messages
  • ESM Module Messages
  • Temporary Messages
Parent topic: Using External Security Facility (ESF) Features


Manager Interface Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


ESF API Processing Messages

  • 103W Admin "type" request failed: "value"
    An ESF Admin request of the given type failed, returning error code value.
  • 104W Update ("type") request failed: "value"
    An ESF Update request of the given type failed, returning error code value.
  • 105W ESM Module number ("name") returned error code value ("description") from Update (type)
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update operation for a cached update.
  • 110E ESM Module number ("name") returned error code value ("description") from Verify
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from a Verify (authenticate user) operation. This constitutes a Fail result for the Verify request.
  • 111E ESM Module number ("name") returned error code value ("description") from Auth
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Auth (authorize resource access) operation.
  • 112E ESM Module number ("name") returned error code value ("description") from XAuth
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Xauth (authorize resource access) operation.
  • 113E ESM Module number ("name") returned error code value ("description") from Admin
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Admin (administrative action) operation.
  • 114E ESM Module number ("name") returned error code value ("description") from Update
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update (update notification) operation.
Parent topic: ESF Manager Messages and Logging


103W Admin "type" request failed: "value"

An ESF Admin request of the given type failed, returning error code value.
Parent topic: ESF API Processing Messages


104W Update ("type") request failed: "value"

An ESF Update request of the given type failed, returning error code value.
Parent topic: ESF API Processing Messages


105W ESM Module number ("name") returned error code value ("description") from Update (type)

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update operation for a cached update.
The type is either "single update" or "refresh all", indicating whether the ESM Module was asked to refresh its private data associated with one update, or clear all of its privately cached security information. See External Administrative Update Notification for more information.
Parent topic: ESF API Processing Messages
Related concepts
External Administrative Update Notification


110E ESM Module number ("name") returned error code value ("description") from Verify

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from a Verify (authenticate user) operation. This constitutes a Fail result for the Verify request.
Parent topic: ESF API Processing Messages


111E ESM Module number ("name") returned error code value ("description") from Auth

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Auth (authorize resource access) operation.
Parent topic: ESF API Processing Messages


112E ESM Module number ("name") returned error code value ("description") from XAuth

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Xauth (authorize resource access) operation.
Parent topic: ESF API Processing Messages


113E ESM Module number ("name") returned error code value ("description") from Admin

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Admin (administrative action) operation.
Parent topic: ESF API Processing Messages


114E ESM Module number ("name") returned error code value ("description") from Update

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update (update notification) operation.
Parent topic: ESF API Processing Messages


ESM Module Interface Messages

  • 200I Loaded ESM Module "name"
    The binary file name has been loaded as an ESM Module and initialized.
  • 201C Unable to load ESM Module "name": reason
    The ESM Module in the binary file name could not be loaded; reason is a numeric reason code.
  • 202C ESM Module "name" returned invalid procedure table
    The ESM Module name returned an invalid result when its initial entry point was called.
  • 203C ESM Module "name" initialization failed
    The ESM Module name returned an error from its initialization procedure.
  • 204W ESM Module index returned error code value from Exit
    The ESM Module (indicated by its position in the ESM Module list, index) returned a non-zero value from its exit procedure.
Parent topic: ESF Manager Messages and Logging


200I Loaded ESM Module "name"

The binary file name has been loaded as an ESM Module and initialized.
Parent topic: ESM Module Interface Messages


201C Unable to load ESM Module "name": reason

The ESM Module in the binary file name could not be loaded; reason is a numeric reason code.
Parent topic: ESM Module Interface Messages


202C ESM Module "name" returned invalid procedure table

The ESM Module name returned an invalid result when its initial entry point was called.

Parent topic: ESM Module Interface Messages


203C ESM Module "name" initialization failed

The ESM Module name returned an error from its initialization procedure.

Parent topic: ESM Module Interface Messages


204W ESM Module index returned error code value from Exit

The ESM Module (indicated by its position in the ESM Module list, index) returned a non-zero value from its Exit procedure.

Parent topic: ESM Module Interface Messages


Processing Environment Messages

  • 301W Unable to open log file "name": ("value") description
    ESF was unable to open the log file "name". The value is the error code and description is a short description. (The file is specified by the MF_SAFLOG environment variable. This function only applies to standalone utilities that use ESF, and not to main Enterprise Server components.)
  • 320C CAS support function "name" is not available
    The required CAS support function name is not available to ESF Manager, possibly due to a version mismatch between modules or a resource constraint. This is a fatal error.
  • 321E Unable to allocate ACEE (error code)
    ESF Manager was unable to allocate an ACEE structure, which is required for user verification. code is the error returned by the environment's ACEE allocation function.
  • 322E Unable to allocate named shared memory (error code)
    ESF Manager was unable to allocate a named shared memory area, either for its own use or to satisfy a request from an ESM Module. code is the error returned by the environment's shared-memory allocation function.
Parent topic: ESF Manager Messages and Logging


301W Unable to open log file "name": ("value") description

ESF was unable to open the log file "name". The value is the error code and description is a short description. (The file is specified by the MF_SAFLOG environment variable. This function only applies to standalone utilities that use ESF, and not to main Enterprise Server components.)
Parent topic: Processing Environment Messages


320C CAS support function "name" is not available

The required CAS support function name is not available to ESF Manager, possibly due to a version mismatch between modules or a resource constraint. This is a fatal error.
Parent topic: Processing Environment Messages


321E Unable to allocate ACEE (error code)

ESF Manager was unable to allocate an ACEE structure, which is required for user verification. code is the error returned by the environment's ACEE allocation function.
Parent topic: Processing Environment Messages


322E Unable to allocate named shared memory (error code)

ESF Manager was unable to allocate a named shared memory area, either for its own use or to satisfy a request from an ESM Module. code is the error returned by the environment's shared-memory allocation function.
Parent topic: Processing Environment Messages


Cache Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


User Exit Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


Auditing Messages

  • 601C Auditing subsystem startup failed: ("value") description
    ESF was unable to connect to the auditing subsystem. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
  • 602C Auditing: cobaudit_event failed: ("value") description
    The auditing subsystem failed to audit a security event. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: ESF Manager Messages and Logging


601C Auditing subsystem startup failed: ("value") description

ESF was unable to connect to the auditing subsystem. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: Auditing Messages


602C Auditing: cobaudit_event failed: ("value") description

The auditing subsystem failed to audit a security event. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: Auditing Messages


ESM Module Messages

See the documentation for your MLDAP ESM Module for information on its log messages.

Parent topic: ESF Manager Messages and Logging
Related concepts
MLDAP ESM Module


Temporary Messages

These messages will not normally be logged by released products. They may appear in Early-Adopter releases. If you receive a message in this range, contact SupportLine for more information.

Parent topic: ESF Manager Messages and Logging


ESF User Exit

The ESF User Exit is a feature of the Enterprise Server External Security Facility (ESF). It lets custom actions be performed at certain points while processing security requests. The custom functionality is performed by a loadable module which may be provided by Micro Focus, a customer, or a third party. The User Exit may be used to modify or filter particular security requests, for example. A sample User Exit module, called the "Referential Integrity" exit, is included with Enterprise Developer and the source code is available upon request. The sample module must be enabled by the product administrator. By default no user exit module is enabled.

The user exit is available starting with ESF 2.1, released as part of Enterprise Developer 2.2 Update 2 Hotfix 7 and Enterprise Developer 2.3.

Currently the only exit point in ESF is prior to processing ESF Admin requests. ESF Admin is a mechanism for adding, removing, updating, and querying security objects (users, groups, and resource access control rules). See the documentation for the esfadmin command for more information. The Admin user exit point can be used to block particular admin requests or perform other actions based on them, as the Referential Integrity sample user exit module demonstrates.

More exit points may be added in future product releases. (New releases will remain backward-compatible with older exit modules.)

  • ESF User Exit File Names
    An ESF User Exit module file must follow certain rules for how it is built and named.
  • Enabling an ESF User Exit
  • Configuring an ESF User Exit
Parent topic: Using External Security Facility (ESF) Features
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 Micro Focus support representative.

Micro Focus supports the Referential Integrity sample as it is shipped with the product. Customer changes to the sample are supported only on an advice basis.

Parent topic: The Referential Integrity Sample User Exit


Rules Enforced by the Referential Integrity User Exit

These are the constraints (consistency rules) enforced by the Referential Integrity User Exit.

The constraints listed here are the default behavior of the exit module. The user exit configuration can relax some constraints or add others. See Configuration options for the Referential Integrity User Exit.

User Operations

  • Add user
    • Deny request if the user already exists
  • Delete user
    • Deny request if the user does not exist
    • Automatically remove the user from all groups
    • Automatically remove all resource Access Control Entries (ACEs) that refer to the user
      Note: ACEs with wildcard actors, such as allow:U*:read, are not automatically removed.

Group Operations

  • Add group
    • Deny request if the group already exists
  • Delete group
    • Deny request if the group does not exist
    • Deny request if any users still belong to the group
    • Automatically remove all resource ACEs that refer to the group
      Note: ACEs with wildcard actors are not automatically removed.
  • Add user to group
    • Deny request if the user or group does not exist
    • Deny request if the user already belongs to the group
  • Remove user from group
    • Deny request if the user or group does not exist
    • Deny request if the user is not a member of the group

Resource Access Rule Operations

  • Delete resource class
    • Deny request if the class contains any resource access rules
  • Add resource rule
    • Deny request if the rule already exists in the given class
  • Delete resource rule
    • Deny request if the rule does not exist
    • Deny request if the rule contains any ACEs
  • Add ACE to resource rule
    • Deny request if the rule or actor (user or group) does not exist
    • Deny request if the rule already contains an ACE for the given actor
  • Delete ACE from resource rule
    • Deny request if the rule or actor does not exist
    • Deny request if the ACE does not exist in the specified rule
Parent topic: The Referential Integrity Sample User Exit


Result Codes in the ESF API Parameter Block

Verify, Auth, XAuth, and Admin indicate that a request was granted, was denied, or could not be processed (and in some cases indicate additional information such as password expiration) by setting values in the ESF API parameter block.

Result codes go in three one-byte values in the RETCODES structure in the parameter block. There are three fields, labelled:

  • safpb_api_rc
  • safpb_mgr_return
  • safpb_mgr_reason

The safpb_api_rc codes depend on the function (Verify /Auth /XAuth) being invoked; the other two codes depend on the value of safpb_api_rc. Various valid combinations are listed in safapi.h.

  • Typical Result Codes for Verify
  • Typical Result Codes for Auth and XAuth
  • Typical Result Codes for Admin
Parent topic: Using External Security Facility (ESF) Features


Typical Result Codes for Verify

For a Verify request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | Verification succeeded, no additional information (this is an Allow result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_USER_PROFILE (4) | saf78_RS_NORMAL (0) | The ESM does not have a record for this user (this is an Unknown result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | The ESM rejected this request, and does not wish to provide any additional information (note this is a Deny result, not a Fail result, despite the name of the associated constant). This code can be used if the organization's security policy requires not revealing information about why a signon request was denied.
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_INVALID (8) | saf78_RS_NORMAL (0) | Verification failed because the supplied password was incorrect (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_EXPIRED (12) | saf78_RS_NORMAL (0) | Verification failed because the supplied password has expired (this is a Deny result). Some ESM Modules will accept the request if it is repeated with a new password supplied in the optional new-password field.
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_CHANGE_ERR (16) | saf78_RS_NORMAL (0) | Verification failed because the supplied new password was not accepted by the ESM (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_USER_REVOKED (28) | saf78_RS_NORMAL (0) | Verification failed because signon is disabled for the user's account (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | Verification failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)
Parent topic: Result Codes in the ESF API Parameter Block


Typical Result Codes for Auth and XAuth

For an Auth or XAuth request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_USER_IS_AUTH (0) | saf78_RS_NORMAL (0) | Authorization is granted, no additional information (this is an Allow result)
saf78_SAF_RC_SUCCESS (0) | saf78_RC_ACCESS_INFO (20) | saf78_RS_ACCESS_{NONE (0), READ (4), UPDATE (8), CONTROL (12), ALTER (16)} | (Auth only) The user has the specified level of access to the resource
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_RESOURCE_NOT_PROT (4) | saf78_RS_NO_RESOURCE_PROF (0) | The ESM does not have a record for this resource (this is an Unknown result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_USER_NOT_AUTH (8) | saf78_RS_NORMAL (0) | Authorization is denied (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | Authorization failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)
Parent topic: Result Codes in the ESF API Parameter Block


Typical Result Codes for Admin

For an Admin request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules.

An Admin request can succeed or fail, or it can be ignored if the ESM Module does not implement the requested administration subcommand. (If the module determines that it cannot process the request because of an unsuitable or missing parameter, it can fail or ignore the request as the author feels is appropriate.) The return codes below are classified as Success, Failure, or Ignored results.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | The request was processed, no additional information (this is a Success result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure (this is an Ignored result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_DECLINED (4) | The ESM Module declined to process the request (this is an Ignored result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_KEYWORD_ERROR (4) | saf78_RS_KEYWORD_UNKNOWN (4) | The request specified a parameter keyword that the ESM Module does not recognize (this is an Ignored result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_VALUE_ERROR (4) | saf78_RS_VALUE_INVALID (4) | The request specified a parameter value that is not valid for this ESM Module or its ESM (this is a Failure result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_VALUE_ERROR (4) | saf78_RS_VALUE_LENGTH (8) | The request specified a parameter value that was too long or short for this ESM Module or its ESM (this is a Failure result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | The ESM Module or its associated ESM was unable to process the request (this is a Failure result)
Parent topic: Result Codes in the ESF API Parameter Block


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


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


Glossary

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • ACE
  • ACL
  • ADSI Edit
  • Auditing
  • CLASS
  • ESF
  • ESM
  • LDAP
  • LDIF
  • Resource
  • schema
  • security manager
  • SNMP
Parent topic: Securing an Enterprise Server Installation


ACE

Access Control Entry: an entry in an Access Control List (ACL). It specifies an actor (e.g. a user or group) and the kinds of access that the actor has to a particular resource.
Parent topic: Glossary


ACL

Access Control List: a rule specifying what actors (typically users and groups) are allowed what kinds of access (e.g. read, update) to a resource (file, transaction, configuration object, etc). (Some ESMs may not implement ACLs as such, but they provide an equivalent scheme.)
Parent topic: Glossary


ADSI Edit

Lightweight Directory Access Protocol (LDAP) editor that you can use to manage objects and attributes in Active Directory.
Parent topic: Glossary


Auditing

Auditing refers to collecting information on security-related events and preserving it in for later review.
Parent topic: Glossary


CLASS

In Micro Focus security terms, a CLASS is used to identify a collection of ENTITIES.
Parent topic: Glossary


ESF

The Micro Focus External Security Facility, which relays security queries to external security managers. This facility can run within both Enterprise Server and MF Directory Server.
Parent topic: Glossary


ESM

External Security Manager, another name for Security manager: any system outside MF Server that can respond to security queries. It might be the OS itself, or an LDAP server, or some other facility.
Parent topic: Glossary


LDAP

Lightweight Directory Access Protocol: a standard for configuration-data directories, particularly user directories. Microsoft Active Directory is an LDAP implementation.
Parent topic: Glossary


LDIF

LDAP Directory Interchange Format: a standard for transporting LDAP data and schema definitions between LDAP servers.
Parent topic: Glossary


Resource

Any item to which access is controlled. A resource has a name and a class. A resource name is unique within its class.
Parent topic: Glossary


schema

In LDAP, the organization of information in the directory. The schema defines the types of configuration objects, their attributes, and their relationships.
Parent topic: Glossary


security manager

The module and associated configuration information that the External Security Facility connects to.
Parent topic: Glossary


SNMP

Simple Network Monitoring Protocol: a standard protocol for communicating system status and administration information. SNMP clients (usually called "agents") send information about changes in system status ("alerts") to an SNMP server ("monitor" or "manager"). They also respond to the monitor's queries for current status, and may be written to accept some administrative commands from the manager as well. The current version of SNMP is SNMPv3, which includes security provisions.
Parent topic: Glossary


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 Visual COBOL 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
  • Using the Security Audit Manager (deprecated)
    The topics in this section describe how to configure and use the Enterprise Server Security Audit Manager.
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 installation, which by default is .

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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
  • Object class
  • String "MFDS auditing starting..."
2 14
Auditing turned off
  • Receive count
  • Object class
  • String "MFDS auditing stopped..."
2 100
Found Server
2 101
Found Comms Server
2 102
Found Listener
2 103
Found Handler
2 104
Found Package
2 105
Found Service
2 106
Found XRM
2 107
Found JES Initiator
2 108
Found JES Printer
2 109
Found IMS MPR
2 110
Found MQL
2 120
Found ESM
2 121
Found User
2 122
Found Group
2 123
Found Resource Class
2 124
Found Resource Entity
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=")

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.

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 even 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.

Parent topic: Enterprise Server Auditing
Parent topic: Audit Manager APIs (deprecated)
Related concepts
Accessing Audit Data (deprecated)


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 /opt/microfocus/VisualCOBOL/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


Using the Security Audit Manager (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager logs the records of auditable events that take place during Enterprise Server operation. You can use these records for things such as checking for security breaches or unauthorized access, or for monitoring usage.

  • About the Audit Manager (deprecated)
  • Audit Manager Architecture (deprecated)
  • Getting Started with Auditing (deprecated)
  • Starting and Stopping the Audit Process (deprecated)
  • Configuring the AUDITFILE Emitter (deprecated)
  • Configuring the SNMP Emitter (deprecated)
  • Accessing Audit Data (deprecated)
  • Audit Manager Errors (deprecated)
  • Configuring a User Exit (deprecated)
  • Audit Manager APIs (deprecated)
Parent topic: Enterprise Server Auditing


About the Audit Manager (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager can collect audit events generated by MFDS and by the SEPs running in an Enterprise Server installation. It can either write the information to a set of secure files, or output the information as SNMP events.

  • In a Windows environment, you can run the Audit Manager as a service. To install and configure the Micro Focus Audit Manager service, see To Install the Audit Event Consolidator as a Service (Windows only).
    • If it's not already running, you can start this service from the Windows Services dialog box, or with the command:
      net start mfauditmgr
    • For flexibility, you can also run the Audit Manager directly, by running the mfauditmgr program located in $COBDIR/bin.
  • In a UNIX environment, you can run the Audit Manager service as a daemon.

You can configure Audit Manager behaviour using a configuration file. You specify this configuration file with the -c <filename> option.

You can log auditable events to file, or as SNMP events. With SMMP, you can use SNMP management software to analyze the events.

The Audit Manager provides a utility, and APIs, that you can use to generate reports from the audit files that the system generates. The Audit Manager also provides APIs with which you can perform operations such as customizing logging destinations, and configuring your applications to generate audit events.

Parent topic: Using the Security Audit Manager (deprecated)
Related concepts
Audit Setup Configuration File (deprecated)
Related reference
To Start the Audit Manager (deprecated)
To stop the Audit Manager (deprecated)


Audit Manager Architecture (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Audit event information is generated by SEPs, and by Micro Focus Directory Server (MFDS).

  • On a SEP, an Audit Manager process collects the audit events.
  • A Micro Focus Directory Server (MFDS) generates audit events and forwards these to the system's Inter-Process Communications (IPC).

The IPC sends the audit events to the Audit Manager.

The Audit Manager's event consolidator process combines these events, and the Audit event emitter or emitters output them, either to a secure file, or as SNMP events.

This process is illustrated by the figure below:

  • About Audit Emitters (deprecated)
  • Audit Setup Configuration File (deprecated)
  • Default Audit Configuration (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


About Audit Emitters (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager uses audit emitters to output the audit data.

There are two emitters that you can configure:

  • The AUDITFILE emitter writes audit data to a file. You use the Audit Facility Administration utility to access this data.

    The AUDITFILE emitter writes records to a collection of secure audit files. You configure the number and the size of the audit files in the collection when you set up the emitter definition.

    To access the audit details, you use a command to produce reports from the audit files. Once you have accessed the data, you can dump the file, and it becomes available for re-use by the audit process.

  • The SNMP emitter generates audit data as SNMP events.

    You can use an SNMP management tool to access this data.

Note: If there are no emitters configured, audit events are discarded.
Parent topic: Audit Manager Architecture (deprecated)


Audit Setup Configuration File (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use a configuration file to configure audit setup. Specify the configuration file with the auditmgr -c command when you start auditing. In a Windows environment, you can use the Micro Focus Audit Manager service Start Parameter to specify the configuration file.

An example configuration file is below:
mfaudit.dest=AUDITFILE
# Sets the output type to secure file.
mfaudit.emitter.auditfile#collectionsize=3
# Sets that the audit process uses three files only.
mfaudit.emitter.auditfile#location=C:\MFAudit\logs
# Sets the location where the files are to be created.
mfaudit.emitter.auditfile#file= audit.aud_$(GEN)
# Sets the auditing file names. The $(GEN) parameter
# sets that the filenames are numbered sequentially.
mfaudit.emitter.auditfile#maxfilesize=200
# Sets that audit files are closed when they reach
# a size of 200 KB
mfaudit.timeout=300
# Sets the duration (in milliseconds) that an event will
# retry writing to output before it times out.
Parent topic: Audit Manager Architecture (deprecated)
Related concepts
About the Audit Manager (deprecated)
Related reference
To Start the Audit Manager (deprecated)
To stop the Audit Manager (deprecated)


Default Audit Configuration (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you start auditing without using a configuration file, the following defaults are used:

  • Shared memory is used as the IPC mechanism.
  • The Secure file emitter only is enabled, with the following characteristics:
    • Audit file collection size of 5.
    • Maximum size of each audit file in the collection is 20MB.
  • The timeout period for sending events is set to zero; that is, no timeout period is in effect.
  • The location in which the audit files are created is set by the environment variable MFAUDIT_LOGS.
Parent topic: Audit Manager Architecture (deprecated)


Getting Started with Auditing (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The sections in this topic provide an example of how to configure secure file auditing in a Windows environment. You can use a similar process to configure auditing in a UNIX environment.

Note: In the Windows environment, auditing runs as a Windows service. You can also run auditing from a command line, as a separate process. To do this, you use the mfauditmgr command.

1. Create a configuration file

In this section, you create the configuration file that the audit process is to use. The configuration file controls the audit process: sets up the location, number, and maximum size of the files that the Audit Manager creates.

The lines beginning with the # character are comments only.

  1. Create a folder to hold your configuration file and auditing logs, for example: C:\MFAudit
  2. In the directory you created, use a text editor to create the audit.cfg file, and add the following content. The lines starting with # are comments only:
    mfaudit.dest=AUDITFILE
# Sets the output type to secure file.
mfaudit.emitter.auditfile#collectionsize=3
# Sets that the audit process uses three files only.
mfaudit.emitter.auditfile#location=C:\MFAudit\logs
# Sets the location where the files are to be created.
mfaudit.emitter.auditfile#file= audit.aud_$(GEN)
# Sets the auditing file names. The $(GEN) parameter
# sets that the filenames are numbered sequentially.
mfaudit.emitter.auditfile#maxfilesize=200
# Sets that audit files are closed when they reach
# a size of 200 KB

2. Start the auditing service

In this section, you re-start the auditing service so that it uses the configuration file.

  1. In Windows Services, locate the Micro Focus Audit Manager service, and if it is started, stop it.
  2. Right-click the service, and select Properties.
  3. Select the General tab, and in the Start parameters field at the bottom of the dialog box, enter the following:
    -c C:\MFAudit\audit.cfg

  4. On the dialog box, click Start and check that the service starts without errors.
  5. In Windows Explorer, check that the log files have been created ready for use.

3. Configure an External Security Manager (ESM)

In this section, you configure the Operating System ESM so that it is available for use.

  1. Start an Enterprise Server Administration session, and in the left hand pane under Configure, select Security.

    The Security Options screen appears.

  2. Select the Security Managers tab, and click Add to display the Add Security Manager screen.
  3. In the Name field, enter a name, for example Windows ESM, and in the Module field, enter osesm to specify the security manager. Ensure that the Enabled checkbox is checked, and click Add to add the security manager.

4. Generate MFDS auditing events

In this section, you configure the Operating System External Security Manager (ESM) to generate auditing events for Micro Focus Directory Server.

  1. In the left hand pane, select Security.
  2. Select the MF Directory Server tab and at the bottom of the screen, and click the Change button.
  3. Select the radio button next to the Windows ESM item you created, and click Add. You are prompted for a login with MF directory server administration permissions.
  4. Enter a valid Enterprise Server Administration user ID, for example the default SYSAD, password SYSAD, and click OK. You are prompted for a user ID and password with Administer Users permissions. Enter your system login and click OK.
  5. Under the MF Directory Server tab, in the Security Facility Configuration area, select the Create audit events checkbox, and at the bottom of the screen, click Apply.

MFDS operations that are performed are now logged to the audit files.

5. Generate Enterprise Server audit events

In this stage, you configure the Audit Manager to collect records of events generated by Enterprise Servers that are running.

  1. In the left hand pane, select Security.
  2. Select the Default ES Security tab and under Default ES Security Manager List, click Add.
  3. Select the radio button next to the Windows ESM entry, and click Add.

6. Perform secure operations

In this section, you generate audit events to be logged.

  1. Log off the directory server and log back on again.
  2. Perform some enterprise server processes, for example starting and stopping regions.
  3. Repeat the process to generate some audit events that you can check.

7. View the audit logs

In this section, you make the audit records accessible for viewing, and generate a report.

  1. In Windows Explorer, check the audit files and verify by the file size and datestamp that the first audit file has logged the audit data.

  2. Open a command prompt, and navigate to the C:\MFAudit\logs folder.
  3. Use the following command to make the first audit file available for dumping:
    mfauditadm -p -f audit.aud_1
  4. Use the following command to generate an audit report from the dumped file:
    mfauditadm -r -o audreport.txt -f audit.aud_1
    The above command creates a file named audreport.txt, that contains the audit information.
Parent topic: Using the Security Audit Manager (deprecated)


Starting and Stopping the Audit Process (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

You control auditing by starting or stopping the Audit Manager.

To capture audit events generated by audit-enabled products, you must configure and start the Audit Manager. You can start the process from the command line.

  • In the Windows environment, by default the Audit Manager runs as a service. You can control auditing by starting or stopping the Micro Focus Audit Manager service.
  • Under Unix and Linux you can configure the Audit Manager consolidator to run as a background process.

The Audit Manager consolidator obtains its configuration information from a file specified with a command line option.

  • To Start the Audit Manager (deprecated)
  • To stop the Audit Manager (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


To Start the Audit Manager (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

Use this command to start the Audit Manager.

mfauditmgr [-c cfg-file] [-n name]

Parameters:

cfg-file Specifies the name of the configuration file that is to be used for defining which emitters are to be enabled etc.

If no configuration file is specified, the audit event consolidator instance is configured as follows:

  • Shared memory is used as the IPC mechanism.
  • The Secure file emitter only is enabled, with the following characteristics:
    • Audit file collection size of 5.
    • Maximum size of each audit file in the collection is 20MB.
  • The timeout period for sending events is set to zero; that is, no timeout period is in effect.
  • Location in which the audit files are created is set using the environment variable MFAUDIT_LOGS.
name Specifies the name of the audit event consolidator instance. This is the name that applications will use to communicate with this audit event consolidator instance.

If this option is not specified, the machine name is used.

Parent topic: Starting and Stopping the Audit Process (deprecated)
Related concepts
About the Audit Manager (deprecated)
Audit Setup Configuration File (deprecated)
Related reference
To stop the Audit Manager (deprecated)


To stop the Audit Manager (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

This command stops the Audit Manager.

mfauditmgr -x [-n name]

Parameters:

-x | Stop the audit event consolidator instance
name | Specifies the name of the audit event consolidator instance. This is the name that applications will use to communicate with this audit event consolidator instance. If this option is not specified, the machine name will be used.

Comments:

You will only be allowed to stop an audit event consolidator instance if you are the owner (that is, the user that started it).

Parent topic: Starting and Stopping the Audit Process (deprecated)
Related concepts
About the Audit Manager (deprecated)
Audit Setup Configuration File (deprecated)
Related reference
To Start the Audit Manager (deprecated)


Configuring the AUDITFILE Emitter (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The AUDITFILE emitter writes audit records to a collection of files. These files hold the records in a binary format, and can be processed using the audit file APIs or the Audit Manager Administration Utility.

When the current file in the collection has reached its maximum size, the emitter writes to the next file in the collection. When all files in the collection have reached their maximum file, the emitter attempts to re-use the first file in the collection. This fails if the contents of the audit file have not yet been dumped.

When no files are available, the emitter attempts to cache audit events in memory until a file becomes available. When there is no memory available, the emitter removes events from the cache to allow it to cache the most recent events. When an audit file becomes available, the emitter generates an audit event that details how many audit events were lost, and writes this as the first event in the file.

An audit file cannot be dumped until it has reached its maximum size, or has been set by an administrator as available for dumping. Marking an active files as available for dumping causes the file to be closed immediately, and the next file in the collection becomes the active file.

  • Setting AUDITFILE Emitter Properties (deprecated)
  • Setting the Audit Output Type (deprecated)
  • Specifying a User-defined Emitter (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)
Related reference
Setting AUDITFILE Emitter Properties (deprecated)
AUDITFILE User Exit (deprecated)
To Make the Active Audit File Available for Dumping (deprecated)
To Dump an Audit File (deprecated)
To Generate a Report for an Audit File (deprecated)
To Generate a Report for All Audit Files in a Collection (deprecated)


Setting AUDITFILE Emitter Properties (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the Audit Manager Configuration file, you use the following line to specify the AUDITFILE emitter output properties.

mfaudit.emitter.emitter-name#property=property-value

Parameters:

emitter-name | The name of the audit emitter for which the property is to be set.
property-name | The name of the emitter property to set.
property-value | The value of the emitter property to be set. Emitter names and property names are case-insensitive. See the table below for details.
property-value | Description
AuditfileExit | The name of a DLL(Windows) or shared object (Unix/Linux) that is to be invoked by the AUDITFILE emitter to report on emitter status changes (see AUDITFILE User Exit). The name of the exit specified should reside in a directory on PATH (Windows) or LIBPATH / LD_LIBRARY_PATH / SHLIB_PATH on Unix/Linux.
CollectionSize The number of audit files that will be created in a collection.

Used in conjunction with MaxFileSize.

Default: 5. Maximum 10.
File The name of the audit file to be written.

The following pseudo-variables may be used for the construction of the audit file name:

  • $(AUDITID) - the name of the audit event consolidator that invoked this emitter.
  • $(GEN) - the generation of the file starting from 1.
Default: mfaudit.$(AUDITID).aud_$(GEN)

For example, the second file in the audit file collection created by this emitter when invoked by the audit event consolidator named nwb-cpjdell would be: mfaudit.nwb-cpjdell.aud_2

Note: If the $(GEN) pseudo-variable is not included in the file specification, this emitter appends it.
Location The directory where the audit files are to be written.

Default: the location specified by the MFAUDIT_LOGS environment variable or the current directory if MFAUDIT_LOGS is not set. The emitter will write an error event to the to the Unix syslog, if it is unable to create audit files in the specified directory.

Note: The Audit Manager attempts to create the output audit file location if it does not already exist. If the creation of the directory specified by the Location property fails, it will use the default location. If the creation of the directory specified by the MFAUDIT_LOGS environment variable fails, the current directory will be used.
.
MaxFileSize The directory where the audit files are to be written.

The maximum size of an audit file in KB that will be written before the file is closed, and the next audit file in the collection is opened.

A file in the collection is identified by the $(GEN) pseudo-variable (see File property above). The first audit file in a collection will result in the $(GEN) pseudo-variable being set to 1, the second in the sequence will result in it being set to 2, and so on until CollectionSize is exceeded. Once the CollectionSize number of files has been reached, the sequence number will revert back to 1.

Default: 0x00005000, indicating 20 MB max file size

Comments:

mfaudit.emitter.emitter-name#property is used to set a property with the a name and value for the given emitter. Any property name and value can be set, irrespective as to whether the emitter will actually make use of it. The CBL_AUDIT_EMITTER_PROPERTY_GET API can be used by an emitter to retrieve property values as strings or numeric values.

Multiple mfaudit.emitter.emitter-name#property entries can occur in the configuration file, but for duplicates, the last-most entry is used.

Property names are case insensitive.

When any of the following common case-insensitive property values are used, they are held in two forms: the string as given, and a corresponding numeric value. An emitter can then use the CBL_AUDIT_EMITTER_PROPERTY_GET API to retrieve the numeric value of the property directly without needing to perform its own string conversion.

String Value | Numeric Value
ON | 1
OFF | 0
YES | 1
Y | 1
NO | 0
N | 0
TRUE | 1
FALSE | 0
ENABLED | 1
DISABLED | 0
numeric-string | n

Examples:

Set the audit file name, the number of files in the audit file collection, and the maximum size of each audit file in the backup set for the AUDITFILE emitter.

...
mfaudit.emitter.auditfile#collectionsize=3
mfaudit.emitter.auditfile#location=e:\audit
mfaudit.emitter.auditfile#file= myaudit.aud_$(GEN)
mfaudit.emitter.auditfile#maxfilesize=200
...

Audit files myaudit.aud_1, myaudit.aud_2, and myaudit.aud_3 are created in the directory e:\audit. Each of these files has a maximum size of 200kb.

Parent topic: Configuring the AUDITFILE Emitter (deprecated)
Related reference
AUDITFILE User Exit (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


Setting the Audit Output Type (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the Audit Manager Configuration file, you use the mfaudit.dest parameter to specify audit event output types or emitter destinations to use: to file or as SNMP events, or both.

mfaudit.dest=audit-emitter-list

Parameters:

audit-emitter-list
A list of comma or space separated audit emitter names. Emitter names are case-insensitive. The supplied emitter names are:
  • AUDITFILE

    Trace events are written to an audit file in a binary format. The resulting file can be processed using the audit file APIs or the Audit Manager Administration Utility.

  • SNMP

    Trace events are generated as SNMP events.

The default is: mfaudit.dest=AUDITFILE

Comments:

mfaudit.dest is used to specify the audit event output types that are to be used by the audit event consolidator instance . You can configure multiple types.

Examples:

The following entry specifies that tracing events are to be output to an audit file.

...
mfaudit.dest=AUDITFILE
...

The following entry specifies that tracing events are to be output using both the audit file and SNMP emitters.

...
mfaudit.dest=AUDITFILE,SNMP
...
OR
...
mfaudit.dest=AUDITFILE
mfaudit.dest=SNMP
...
Parent topic: Configuring the AUDITFILE Emitter (deprecated)


Specifying a User-defined Emitter (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the Audit Manager Configuration file, you use the following line to define an audit emitter that you have created. That is, it assigns an emitter name to your emitter program. Once you use this command, you can then use this emitter with the mfaudit.dest configuration.

mfaudit.emitter.emitter-name=program-name

Parameters:

emitter-name | The name of the emitter being defined. This name can be specified in mfaudit.dest entries elsewhere in the configuration file. Emitter names are case-insensitive.
program-name | The name of the program that implements the emitter interface and that will be invoked by the audit facility when outputting events to the destination named by emitter-name.

Default:

Not applicable.

Comments:

mfaudit.emitter is used to define a user-specific emitter. Where there are multiple mfaudit.emitter for the same emiter, the last-most is used.

Note: We recommend that custom emitters that you use should be written in C. They should not be written in COBOL due to potential recursion issues during CTF tracing.

Examples:

1) Define a user-specific emitter named MYAUDIT and make it a default audit emitter.

...
mfaudit.emitter.MYAUDIT=myauditemitter.dll
mfaudit.dest=MYAUDIT
...

2) Replace the well-known AUDITFILE emitter.

...
mfaudit.emitter.AUDITFILE=myauditfileemitter.so
...
Parent topic: Configuring the AUDITFILE Emitter (deprecated)


Configuring the SNMP Emitter (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

SNMP installations are split into two parts: an SNMP Agent runs on the systems being managed, whilst a central Management Console or other Management Tool runs elsewhere to monitor and maintain the systems that are running the Agents. There may be more than one Agent on a given system, provided that they are all configured to avoid using the same UDP and/or TCP ports, and that the Management Tool is told which ports to use to contact the Agents.

Various specifications of SNMP exist. v1 is not widely used today. v2, and specifically v2c, is most common. Whilst v3 can be thought of as being v2c using encrypted data flows.

There are many Agent systems. These may be software used on various operating systems, or firmware operating within hardware devices such as network routers. Micro Focus does not supply any Agent software.

The SNMP Emitter for the Micro Focus Audit Manager supports multiple logical interfaces which in turn interface with specific Agent services. The following SNMP Agent interfaces are provided for use with Net Express.

Agent interface module | Supplied with | Supported SNMP version | Description
mf_audit_win_snmp.dll | All installations of Net Express and Server | v2 and v2c | This module supports installations of Microsoft's WinSNMP embedded SNMP service, which works with SNMP v2 and v2c.
mf_audit_net_snmp.dll | All installations of Net Express and Server | v2, v2c and v3 (with no authentication or encryption of data) | This module supports installations of Net-SNMP v5.4 and upwards.
mf_audit_net_snmp.dll | The optional Security Pack for Net Express and Server | v2, v2c and v3 (with authentication and encryption of data) | This module supports installations of Net-SNMP v5.4 and upwards.

To use any of these modules, make the appropriate entries in the configuration file used by the Micro Focus Audit Consolidator Process. For details of the configuration file, see The Audit Consolidator Process Configuration File. For details on starting the consolidator process and specifying the location of the configuration file, see To start an audit event consolidator.

For each of these modules, a sample configuration file is shipped. The files are mf_audit_net_snmp.cfg and mf_audit_win_snmp.cfg. These contain elements specific to each of the variants of Windows SNMP support, but they are not complete mfauditmgr configuration files. The contents of the relevant sample file, or files, must first be merged with the existing Audit Manager configuration file, and then the Audit Manager system service must be re-started before the changes will take effect.

Many configuration options are common to both agent installations, but there are some entries that are specifically for use with Net-SNMP: the WinSNMP agent only supports SNMP v1 and SNMP v2 Trap generation, whilst the Net-SNMP agent also supports SNMP v3. However, the only configuration element that changes between WinSNMP and Net-SNMP when using SNMP v2 Traps is the agent name item.

It is perfectly acceptable to switch between Agents by using a single configuration file and alternating the agent used between mf_audit_win_snmp and mf_audit_net_snmp then re-starting the mfauditmgr service. Any extra SNMP v3 parameters that may have been supplied for Net-SNMP will simply be ignored by the WinSNMP emitter. A v2 Trap will always be issued when WinSNMP is in use, regardless of the SNMP version configured.

However, to use v3 authentication you must have the mf_audit_net_snmp module supplied with the Security Pack. If you configure the use of authentication when using the mf_audit_net_snmp module with the base Net Express or Server product, the emitter will log an error message.

Here's an example of a configuration file which will trace Audit events to both SNMP and the standard AUDITFILE emitter. This configuration uses WinSNMP to send the SNMP Trap messages.

mfaudit.emitter.snmp                = snmpaudit
mfaudit.dest                             = auditfile,snmp

mfaudit.emitter.auditfile#collectionsize = 5
mfaudit.emitter.auditfile#location       = c:\logs
mfaudit.emitter.auditfile#maxfilesize    = 1

mfaudit.emitter.snmp#agent      = mf_audit_win_snmp
# location of the Trap receiver, the Management Console that will view the audit events
mfaudit.emitter.snmp#agent.hostname  = <target host name or IP address>
# use port 162, the IANA default port for UDP and TCP traps
mfaudit.emitter.snmp#agent.port  = 162
# default is to exclude the events 0,2,3,4,5,6, the example below excludes
# events with a category >9
mfaudit.emitter.snmp#agent.exclude.events=>9

# Mode of transport, either UDP or TCP
# The default is UDP. Although an option for v2 installations
# TCP is normally only used for SNMP v3
# and is still only optional for v3
mfaudit.emitter.snmp#agent.transport = UDP

# the SNMP community of installations in which this system exists
# community default is "public"
mfaudit.emitter.snmp#agent.community = public

# snmp_version can be either "2" or "3". If v3, extra parameters
# are also required, see below.
# The default is "2"
mfaudit.emitter.snmp#agent.snmp_version = 2

The only change required to re-configure this audit manager installation to emit Audit events to SNMP using Net-SNMP instead of WinSNMP is shown below.

mfaudit.emitter.snmp#agent       = mf_audit_net_snmp

There are several extra parameters that are required in order to configure an SNMP v3 environment for the sending of encrypted audit messages. These are covered in Working with SNMP v3.

  • Using the SNMP Audit Emitter (deprecated)
  • Using the SNMP Emitter with a Net-SNMP Agent (deprecated)
  • Working with SNMP v3 (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


Using the SNMP Audit Emitter (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use the SNMP Emitter, you must:

  1. Configure the SNMP Agent to emit Trap messages to a monitoring Management Tool location. To do this:
    1. Configure the SNMP Emitter to tell the Agent the location of the Management Tools that should receive the emitter Audit Events.
    2. If you are using the Net SNMP Agent, install the Micro Focus MIB file (see below) into the Net SNMP MIB database.
  2. Configure the Management Tool that is to monitor the trap output.
    1. Import the Micro Focus MIB file (see below) into the Management Tool's MIB database so that it can recognise the message content that it is going to receive from the Agent.
    2. Tell the Management Tool to accept SNMP Trap events from the location (and the port number if the Agent is not using default ports) of the originating Agent.

The Micro Focus MIB file, mf_audit_snmp.mib, is located in the $COBDIR\bin directory by default.

Note: Some MIB import tools require specific file extensions such as .mib or .mb, or just .txt. Ensure that you rename this file to match the requirements of your software before attempting to install the Micro Focus MIB extension.
Note: With the Microsoft WinSNMP Agent, the WinSNMP emitter will work without any further configuration beyond that contained in the audit configuration file.
Parent topic: Configuring the SNMP Emitter (deprecated)


Using the SNMP Emitter with a Net-SNMP Agent (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Windows systems always have WinSNMP installed unless it has been specifically removed or disabled - although, without a little configuration it is quiescent. This is not the case with Net-SNMP, which you must install by hand.

The installation and configuration of Net-SNMP is beyond the scope of this document. Please refer to the Net-SNMP documentation for details. The main project, along with binary distributions, can be found at www.net-snmp.org (binaries are at www.net-snmp.org/download.html).

Once you have installed Net-SNMP, you must add the Micro Focus MIB definitions to the Net-SNMP MIB database before it will accept any actions from the audit emitter. You do this by running mf_audit_net_snmp_deploy.bat, which is supplied in the $COBDIR\bin directory by default.

The default installation drive for Net-SNMP is c:\usr. However, this location is used is at the discretion of the installer. Therefore, the mf_audit_net_snmp_deploy.bat file has an optional location parameter for specifying the location in which it will attempt to install the MIB. This parameter takes long and spacey names, provided that they are delimited with quote characters. If no parameter is found, the file will attempt to install the MIB into a Net-SNMP installation located in c:\usr.

When you have installed and configured the Agent software, you can configure the audit emitter (see below).

  • Configuring the emitter (deprecated)
  • Specifying the location of management tools (deprecated)
  • Configuring logging for problem diagnosis (deprecated)
Parent topic: Configuring the SNMP Emitter (deprecated)


Configuring the emitter (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The configuration of each emitter can be viewed as two separate sections: where do you want the Trap messages to be received, and how do you want to send them. This breaks down into a series of location and format options.

The location information is always the same collection of:
  • Local agent (WinSNMP or Net-SNMP)
  • Destination location
  • Destination port
  • Transmission method
  • Events to be audited
  • SNMP version to be used
  • SNMP community identity

The format options vary widely depending upon the version of SNMP to be used.

Parent topic: Using the SNMP Emitter with a Net-SNMP Agent (deprecated)


Specifying the location of management tools (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Specifying the location of management tools that will receive events

In the configuration file for the SNMP emitter, the agent.host and agent.port entries configure the snmp emitter to tell the Agent which of its configured management tools should receive the emitted Audit Events. For example:

mfaudit.emitter.snmp#agent.hostname = 127.0.0.1

WinSNMP cannot handle DNS (text) names and will only accept dotted decimal notation IP addresses like the one shown in the example above.

Net-SNMP can handle DNS or Dotted Decimal notation for the host location.

The Internet Assigned Names Authority (IANA) defines the standard ports to be used for SNMP traffic. Although it is entirely possible that specific installations may choose to use other ports, the following are the defined standard group of ports:

  • snmp 161/tcp SNMP
  • snmp 161/udp SNMP
  • snmptrap 162/tcp SNMPTRAP
  • snmptrap 162/udp SNMPTRAP

The SNMP Audit Emitter only uses the SNMPTRAP ports. If any installations require an override of the port definitions, follow the guidance below for configuring the SNMP agents on your installation, and modify the mfaudit.emitter.snmp#agent.port line in the configuration file. Failure to do both sets of configuration will lead to indeterminate results.

mfaudit.emitter.snmp#agent.port = 162

The transmission method is either UDP or TCP. UDP is widely used as it is fast and has few system overheads. UDP was also the only transmission method available in the early days of SNMP. TCP is slower but it can be used to transmit more than a single IP packet of information, and if audited events are being truncated the user should switch to using TCP. When changing a working system, remember that both the receiver and sender must share a similar configuration, so the changes must be made at both ends of the link.

To select UDP, set transport = UDP. For TCP, set transport = TCP. The default is to use UDP.

mfaudit.emitter.snmp#agent.transport = UDP

The SNMP Trap versions are set using the "snmp_version" configuration option. Acceptable values are either "2" or "3". The default snmpv value is "2".

If SNMP v3 is selected and you wish to use the authentication and privacy features, several extra parameters are also required and you must have the Net SNMP emitter module that is supplied with the Security Pack. See Working with SNMP v3 for more details.

mfaudit.emitter.snmp#agent.snmp_version= 2

The actual range of events that will be audited through this emitter can be masked using the agent.exclude.events option. For more details of this option, see the general Audit Manager documentation. The default behaviour is to exclude events below those at category 9.

mfaudit.emitter.snmp#agent.exclude.events=>9

All SNMP v2 and v3 installations operate within logical communities of installations. If no community name is specified all SNMP installations will use the default community name "public".

To specify the community of your local installations and, in particular, that of the receiver of the SNMP audit events, you will need to add a community option to your configuration file. This name must not be spacey in form.

mfaudit.emitter.snmp#agent.community = community_name

Parent topic: Using the SNMP Emitter with a Net-SNMP Agent (deprecated)


Configuring logging for problem diagnosis (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Because audit emitters cannot use the Micro Focus Consolidated Tracing Facility (CTF) to produce diagnostic information, the SNMP emitter supports an alternative logging mechanism. This enables you to send log information to a file and optionally to the screen.

To use the logging mechanism, you use the agent.log_emitter, agent.log_to_screen and agent.logfilename entries in the configuration file. The sample below, illustrates the use of these entries. The comment lines (those preceded with #) document the allowable values.

# Emitters cannot use Micro Focus CTF trace facilities, so
# a basic alternative logging method has been provided.
#
# Logging can go to file and screen, or just to file.
#
# mfaudit.emitter.snmp#agent.log_emitter options
#
# on                  - enable all logging options
# off                 - do not log anything
# errors              - log only errors
# flow                - log module process flow
# content             - log audit message (partial) content
# errors_flow         - log errors and logic flow
# errors_flow_content - log errors and logic flow and content
mfaudit.emitter.snmp#agent.log_emitter = errors

# mfaudit.emitter.snmp#agent.log_to_screen options
# on                   - log to console screen
# off                  - do not log to screen, log to file
mfaudit.emitter.snmp#agent.log_to_screen = on

# mfaudit.emitter.snmp#agent.logfilename options
# if screen logging is disabled log to file name given here
mfaudit.emitter.snmp#agent.logfilename = c:\snmpemitter.log
Parent topic: Using the SNMP Emitter with a Net-SNMP Agent (deprecated)


Working with SNMP v3 (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

SNMP v3 adds two optional levels of security to SNMP v2c Traps: Authentication and Privacy (Content Encryption).

To enable generated Audit events be sent using SNMP v3 flows, we rely upon software produced by the OpenSource Net-SNMP project. The main project along with binary distributions can be found at www.net-snmp.org. (Binaries are at www.net-snmp.org/download.html). This release of Micro Focus SNMP Audit Emitter was created to use Net-SNMP v5.4. It does not require a 3rd party OpenSSL installation, nor does it require an OpenSSL compliant Net-SNMP installation.

Note:
  • Microsoft Windows SNMP services do not include native SNMP v3 support, so the WinSNMP option will not provide SNMP v3.
  • The SNMP V3 Specific Configuration Options (deprecated)
  • Configuring the Micro Focus Audit Emitter for SNMP V3 (deprecated)
Parent topic: Configuring the SNMP Emitter (deprecated)


The SNMP V3 Specific Configuration Options (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The use of SNMP v3 with authentication and privacy introduces the need to configure several basic options before the SNMP v3 Traps can be generated and sent. If you are not using authentication and privacy, you can ignore these options. They are as follows:

  • Security Engine ID
  • Username
  • Hash method (MD5 or SHA1)
  • Authentication password
  • Cipher (DES or AES128)
  • Cipher password

There are two further options which will only be used in a limited number of installations:

  • Context EngineID
  • ContextName

Depending upon the transmission privilege settings all of the options may be used. In most installations, all of the options are going to be required to enable correct authentication and cryptographically protected transmissions that can be received correctly at the management console where the trap messages are monitored.

The SNMP Audit Emitter can only send SNMP v3 traps under a single user identity. In order for the traps to be deciphered correctly, this identity must also be configured with exactly the same content at the receiver of the trap messages.

Parent topic: Working with SNMP v3 (deprecated)


Configuring the Micro Focus Audit Emitter for SNMP V3 (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The first change to a standard V2 installation is to enable V3 operations.

mfaudit.emitter.snmp#agent.snmp_version = 3

Now we must select the level of security privilege that we require on our transmissions.

Whilst Authentication can be enabled or disabled at will, Privacy can only be enabled when Authentication is already enabled. So the three transmission privilege permutations are:

NoAuth No authentication or encryption of data

AuthPriv Authenticate and use private (encrypted) data

AuthNoPriv Authenticate user with no encryption of data

When configuring the SNMP Audit Emitter, this choice is held in the "privilege" setting. The following example enables both Authorisation and Privacy.

mfaudit.emitter.snmp#agent.privilege = AuthPriv

When either Privacy or Authentication and Privacy are disabled, the relevant sections of the configuration are ignored.

To provided Authorisation, a user identity is configured at the monitoring trap receiver and the issuing Emitter. Five options define a user, and a further option defines the Security EngineID that groups the user within a logical group of users.

We shall now take a look at the User options in detail.

The Username
The username is a single text string with a simple name. This name cannot contain spaces.
mfaudit.emitter.snmp#agent.security_username = fred_jones
The Hash Method
The Hash Method and Authentication Pass Phrase (the Shared Secret in cryptographic terms) are combined to form a cryptic value. This value which will be compared with the receiver's similarly configured pairing which has a matching Username and Security EngineID. A mismatch will cause the authentication attempt to be rejected.

Most installations support the MD5 hash method, and later installations may also support SHA1. If configuring a new V3 user, you should choose to use the latest hash method installed at the monitoring location that will receive the traps. The original MD5 method is the default hash method as it will currently be pre-configured in more installations than SHA1.

mfaudit.emitter.snmp#agent.hmac = MD5

The chosen hash method is applied to a configured pass phrase. The pass phrase must be at least 8 characters in length and may be spacey if the phrase is contained within a single pair of quote characters. Non-spacey passwords may omit the quote characters.

mfaudit.emitter.snmp#agent.auth_passphrase = "auth password"
The Encryption Cipher
The Privacy cipher can be either DES or AES128. Like the SHA1 hash above, AES is a recent addition to SNMP V3 and may not be in place in all installations. As a result, the default setup is to use the DES cipher. As with choosing a hash method, if you are configuring a new v3 user you should choose to use the latest cipher method that is installed at the monitoring location that will receive the traps. This should ideally be AES, however the default setting is DES as this will match the majority of installations in the field today.

The three options are DES, AES and AES128. The latter two are equivalent. It is anticipated that additions to the SNMP V3 standard will add AES192 and AES256 support in the future. When this happens AES will refer to AES128.

mfaudit.emitter.snmp#agent.cipher = DES

Exactly the same rules apply to Privacy (Cipher) pass phrases and Authentication pass phrases.

mfaudit.emitter.snmp#agent.cipher_passphrase = "crypt password"
The Security Engine ID
Several copies of a given username can exist within an SNMP installation, however only one copy can exist within the scope of any one Security Engine. So the group of five options shown above are always paired with a Security Engine ID. This is a numerical string represented in hex format. There are many long and varied methods for determining what value to use for a security engine ID and there is as yet no formal consensus. This document is not the place to examine the arguments, however in the setup you will need to choose a value to use as the Security Engine ID. This must match the receiver's Engine ID and Username's config grouping of options.

The following example would work as an initial test value, however it lacks meaning in a wider SNMP context and your network management team should assign a security Engine ID for the Audit Emitter monitoring, or advise the user of an existing Engine ID that should be used.

mfaudit.emitter.snmp#agent.security_engineID = 0x0102030405

Putting this group together we have a collection that describes the user, the user's Security Engine in which it will work, and the methods of both proving the user's identity and encrypting the audit event's data content. Taken together this is the complete configuration describing a single user.

mfaudit.emitter.snmp#agent.privilege = AuthPriv
mfaudit.emitter.snmp#agent.security_engineID = 0x0102030405
mfaudit.emitter.snmp#agent.security_username = fred_jones
mfaudit.emitter.snmp#agent.hmac = MD5
mfaudit.emitter.snmp#agent.auth_passphrase = "auth password"
mfaudit.emitter.snmp#agent.cipher = DES
mfaudit.emitter.snmp#agent.cipher_passphrase = "crypt password"
The ContextID and ContextName
The final configuration items not mentioned so far are the Security Context ID and ContextName. These are paired together in much the same fashion as the SecurityEngineID and UserName to form a restricted connection entity.

Contexts can be useful in installations where several applications will be receiving SNMP data and the users do not wish all the applications to receive all the incoming data.

By giving different applications the same SecurityEngineID and UserName configuration, but different ContextEngine and ContextName configurations, data destined for specific locations can be sent to those locations without the need to configure extra Users in the SecurityEngine domain in order to distinguish the destinations and sources.

Again, in a similar fashion to the SecurityEngineID and UserName configuration items, the ContextEngineID is expected to be a hex string, and the ContextName a character string which usually has human readable content.

mfaudit.emitter.snmp#agent.context_engineID = 0x0102030405
mfaudit.emitter.snmp#agent.context_name = primary_audit_monitor
Parent topic: Working with SNMP v3 (deprecated)


Accessing Audit Data (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Audit data is either written to files, or output as SNMP events. You use the mfauditadm command to access the audit output data.

Before you can access data from the active file, you must make it available for dumping.

Note: See Audit Event Codes for more information on event codes contained in audit output data.
  • mfauditadm command (deprecated)
    Runs the Audit Manager Administration utility, which enables you to access, dump, and create reports for audit information generated by Enterprise Server.
  • To Generate a Report for an Audit File (deprecated)
  • To Generate a Report for All Audit Files in a Collection (deprecated)
  • To Dump and Generate a Report for an Audit File (deprecated)
  • To Dump and Generate Reports for All Audit Files in a Collection (deprecated)
  • To Make the Active Audit File Available for Dumping (deprecated)
  • To Dump All Audit Files in a Collection (deprecated)
  • To Dump an Audit File (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)
Related reference
To Make the Active Audit File Available for Dumping (deprecated)
To Dump an Audit File (deprecated)
To Generate a Report for an Audit File (deprecated)
To Generate a Report for All Audit Files in a Collection (deprecated)
Audit Event Codes


mfauditadm command (deprecated)

Runs the Audit Manager Administration utility, which enables you to access, dump, and create reports for audit information generated by Enterprise Server.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Important: Execute mfauditadm at the command line or in a batch file from a command prompt.

Syntax:

mfauditadm {[-n instance-name |
            [-p [-n instance-name | -f dump-audit-file]] |
            [-r [[-date yyyy/mm/dd] [-time hh.mm[.ss[.nnn]]
              [-c] [-d] [-o output-file-name] -f report-audit-file]
            [-d [-c] -f dump-audit-file]}

Parameters:

-n instance-name
Specifies the name of the audit event consolidator instance, which is the name that applications use to communicate with the audit event consolidator.
-p
Make the active audit file available for dumping.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-f dump-audit-file
The audit file to be dumped or to be made available for dumping.
-r
Generate a report.
-date yyyy/mm/dd
In the generated report file, include only events on the given date.
-time hh.mm[.ss[.nnn]]
In the generated report file, include only events from the given time.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-d
Mark the file as dumped or mark each audit file available for dumping as dumped.

Examples:

See Related Tasks below.

Parent topic: Accessing Audit Data (deprecated)
Related tasks
To Make the Active Audit File Available for Dumping (deprecated)
To Dump an Audit File (deprecated)
To Generate a Report for an Audit File (deprecated)
To Generate a Report for All Audit Files in a Collection (deprecated)
To Dump and Generate a Report for an Audit File (deprecated)
To Dump and Generate Reports for All Audit Files in a Collection (deprecated)
To Dump All Audit Files in a Collection (deprecated)


To Generate a Report for an Audit File (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this. To generate a report for the active audit file, you must first make it available for dumping. See To Make the Active Audit File Available for Dumping.

mfauditadm -r [-o output-file-name] -f report-file-name [-d]

Parameters:

-r
Generate a report.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-d
Mark the file as dumped.

Example:

mfauditadm -r -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related tasks
To Make the Active Audit File Available for Dumping (deprecated)
Related reference
mfauditadm command (deprecated)
Related information
Accessing Audit Data (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


To Generate a Report for All Audit Files in a Collection (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this. To generate a report for an active audit file, you must first make it available for dumping. See To Make the Active Audit File Available for Dumping.

mfauditadm -r [-o output-file-name] -f report-audit-file -c [-d]

Parameters:

-r
Generate a report.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-d
Mark each audit file available for dumping as dumped.

Example:

mfauditadm -r -c -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related tasks
To Make the Active Audit File Available for Dumping (deprecated)
Related reference
mfauditadm command (deprecated)
Related information
Accessing Audit Data (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


To Dump and Generate a Report for an Audit File (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r [-date yyyy/mm/dd] [-time hh.mm[.ss[.nnn]]]
                -d [-o output-file-name] -f report-audit-file

Parameters:

-r
Generate a report.
-date yyyy/mm/dd
In the generated report file, include only events on the given date.
-time hh.mm[.ss[.nnn]]
In the generated report file, include only events from the given time.
-d
Mark the file as dumped.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.

Example:

mfauditadm -r -d -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related reference
mfauditadm command (deprecated)


To Dump and Generate Reports for All Audit Files in a Collection (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r [-o output-file-name] -f report-audit-file -c -d

Parameters:

-r
Generate a report.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-d
Mark the file as dumped.

Example:

mfauditadm -r -c -d -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related reference
mfauditadm command (deprecated)


To Make the Active Audit File Available for Dumping (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

To access the active file's audit data, you must first make it available for dumping. Afterwards, it is no longer the active file, and you can access the data it contains.

mfauditadm -p [-n instance-name | -f dump-audit-file]

Parameters:

-p
Make the active audit file available for dumping.
-n instance-name
Specifies the name of the audit event consolidator instance, which is the name that applications use to communicate with the audit event consolidator.
-f dump-audit-file
The audit file to be made available for dumping.
Note: If neither -n nor -f are specified to identify the audit file, the command uses the current active file.

Example:

mfauditadm -p -f mfaudit.DOCTEST.aud_5
Parent topic: Accessing Audit Data (deprecated)
Related tasks
To Generate a Report for All Audit Files in a Collection (deprecated)
To Generate a Report for an Audit File (deprecated)
Related reference
mfauditadm command (deprecated)
Related information
Accessing Audit Data (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


To Dump All Audit Files in a Collection (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -c -f dump-audit-file

Parameters:

-d
Mark the file as dumped or mark each audit file available for dumping as dumped.
-c
Generate a report for each available file in the collection.
-f dump-audit-file
The audit file to be dumped.

Example:

mfauditadm -d -c -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related reference
mfauditadm command (deprecated)


To Dump an Audit File (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -f dump-audit-file

Parameters:

-d
Mark the file as dumped or mark each audit file available for dumping as dumped.
-f dump-audit-file
The audit file to be dumped.

Example:

mfauditadm -d -f mfaudit.DOCTEST.aud_5
Note: Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again until it has been reused by the audit consolidator process.
Parent topic: Accessing Audit Data (deprecated)
Related reference
mfauditadm command (deprecated)
Related information
Accessing Audit Data (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


Audit Manager Errors (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager can generate the following error messages:

  • AUD0002E: Failed to start server (deprecated)
  • AUD0003E: Failed to connect to server (deprecated)
  • AUD0004E :Failed to initialise audit facility (deprecated)
  • AUD0005E: Failed to allocate memory (deprecated)
  • AUD0006E: File does not exist (deprecated)
  • AUD0007E: File is not available for dumping (deprecated)
  • AUD0008E: No file is available for dumping (deprecated)
  • AUD0009E: Invalid file format (deprecated)
  • AUD0010E: Invalid file name (deprecated)
  • AUD0011E: File not dumped (deprecated)
  • AUD0012E: Operation failed (deprecated)
  • AUD0013E: Failed to create output file (deprecated)
  • AUD0029E: Failed to initialise CTF (deprecated)
  • AUD0030E: You are not authorised to stop the server (deprecated)
  • AUD0031E: Failed to install service (deprecated)
  • AUD0032E: Failed to uninstall service (deprecated)
  • AUD0033E: File is not active (deprecated)
  • AUD0034E: You are not authorised to perform this operation (deprecated)
  • AUD0036E: Semaphore fault (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


AUD0002E: Failed to start server (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit manager server has failed to start.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0003E: Failed to connect to server (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit process has failed to connect to the audit manager server.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0004E :Failed to initialise audit facility (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit facility has failed to initialise.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0005E: Failed to allocate memory (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that a memory allocation process has failed.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0006E: File does not exist (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that

Indicates that you attempted a dump operation on a non-existent file.

Resolution

Check your syntax and try again.

Parent topic: Audit Manager Errors (deprecated)


AUD0007E: File is not available for dumping (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the file you attempted to dump has not been made available for dumping.

Resolution

Use the mfauditadm -p command to make the file available for dumping.

Parent topic: Audit Manager Errors (deprecated)


AUD0008E: No file is available for dumping (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that you attempted a dump operation and no files have been made available for dumping.

Resolution

Use the mfauditadm -p command to make the file you want available for dumping.

Parent topic: Audit Manager Errors (deprecated)


AUD0009E: Invalid file format (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit file that you are attempting to dump is not a valid audit file.

Resolution

Check that the audit file you specified is valid and has been made available for dumping.

Parent topic: Audit Manager Errors (deprecated)


AUD0010E: Invalid file name (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit output file configuration attempts to allocate an incorrect filename for the output files.

Resolution

Check that the audit output filename (configured in the Audit Manager Configuration file) is valid. Don't forget that the process attempts to append a number to each sequential output filename.

Parent topic: Audit Manager Errors (deprecated)


AUD0011E: File not dumped (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that an audit file dump operation failed.

Resolution

Check that the audit file has been made available for dumping, and that the location set to hold the dump output is valid, and has sufficient access permissions and space available to hold the dumped output.

Parent topic: Audit Manager Errors (deprecated)


AUD0012E: Operation failed (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

An audit operation failed.

Resolution

Note the sequence of events that lead up to the message, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0013E: Failed to create output file (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The audit process failed in its attempts to create the file to hold the audit output.

Resolution

Check that the location set to hold audit output (configured in the Audit Manager Configuration file) is valid, and has sufficient access permissions and space available to hold the audit output.

Parent topic: Audit Manager Errors (deprecated)


AUD0029E: Failed to initialise CTF (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Facility uses parts of the Consolidated Tracing Facility (CTF) infrastructure to provide functionality. The Audit Facility failed to initialise Consolidated Tracing Facility in order to access the functionaity it needs.

Resolution

If the problem persists, note the sequence of events leading up to the error and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0030E: You are not authorised to stop the server (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your login ID does not have sufficient security access permissions to perform the operation.

Resolution

Use a login with the required permissions set, or contact your system administrator.

Parent topic: Audit Manager Errors (deprecated)


AUD0031E: Failed to install service (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfauditmgr -i command failed to install the consolidator service.

Resolution

Try starting the service manually. If the problem persists, contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0032E: Failed to uninstall service (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfauditmgr -u command failed to uninstall the consolidator service.

Resolution

Try uninstalling the service manually. If the problem persists, contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


AUD0033E: File is not active (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The file from which you are attempting the dumping operation is not the active audit file.

Resolution

Use the following command to set the file as the active file:
mfauditadm -p -f <filename>
Parent topic: Audit Manager Errors (deprecated)


AUD0034E: You are not authorised to perform this operation (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your login ID does not have sufficient security access permissions to perform the operation.

Resolution

Use a login with the required permissions set, or contact your system administrator.

Parent topic: Audit Manager Errors (deprecated)


AUD0036E: Semaphore fault (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

An internal communications process has failed.

Resolution

Note the events leading up to the error condtition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors (deprecated)


Configuring a User Exit (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can invoke the AUDITFILE emitter user exit to report on emitter status changes. It is enabled by specifying its name to the AUDITFILE emitter using the configuration file's mfaudit.emitter.emitter-name#property entry.

  • AUDITFILE User Exit (deprecated)
  • Sample file auditfile_exit.c (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


AUDITFILE User Exit (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The interface to the AUDITFILE_EMITTER_EXIT entry point is as follows:

  • AUDITFILE emitter initialising: The exit may change the emitter's properties during its invocation.
  • AUDITFILE emitter deinitialising: The exit would typically release any resources it has acquired during its previous invocations.
  • The name of the audit file being made active.
  • The name of the audit file that is now full.
  • No audit files are available for outputting events to.

The AUDITFILE emitter loads the DLL or shared object named by the AuditfileExit property and invokes the AUDITFILE_EMITTER_EXIT entry point within it whenever an emitter status change occurs.

Syntax:

typedef cobrtncode_t (*PFI_AUDITFILE_EMITTER_EXIT)(cobuns32_t function,
                                                   cobuns8_t *emitter_name,
                                                   ...);

On Entry:

function
AUDITFILE emitter status change:
0 | AUDITFILE emitter initialising. The exit may change the emitter's properties during its invocation
1 | AUDITFILE emitter deinitialising. The exit would typically release any resources it has acquired during its previous invocations
2 | A new audit file is being made active
3 | The active audit file is now full
4 | There are no audit files available for outputting events into
emitter name
The name of the emitter invoking the exit
...
A variable number of parameters depending on the value of function. When:
function=0 | no additional parameters
function=1 | no additional parameters
function=2 | 1 additional parameter: a null-terminated filename
function=3 | 1 additional parameter: a null-terminated filename
function=4 | no additional parameters

On Exit:

Nothing

Return Codes:

Dependent upon the exit function. At present this should always be 0.

Comments:

Please note that the user exit should not be written in COBOL. See Sample file auditfile_exit.c for a sample user exit calling the AUDITFILE emitter.

Parent topic: Configuring a User Exit (deprecated)
Related reference
Sample file auditfile_exit.c (deprecated)
Setting AUDITFILE Emitter Properties (deprecated)
Configuring the AUDITFILE Emitter (deprecated)


Sample file auditfile_exit.c (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.

The following sample .c code is a user exit that calls the AUDITFILE emitter.

/*******************************************************************************
 *
 * Copyright (C) 1984-2015 Micro Focus International Ltd.
 * All rights reserved.
 *
 ******************************************************************************/

#ifdef _WIN32

# define DLLEXPORT	    __declspec(dllexport)

#else  /* _WIN32 */

# define DLLEXPORT

#endif /* _WIN32 */

#include <string.h>
#include <stdarg.h>
#include <stdio.h>

#include "mfaudit.h"

/******************************************************************************/
/*  AUDITFILE emitter exit						      */
/*									      */
/*  AUDITFILE_EMITTER_EXIT(cobuns32_t function,				      */
/*			   cobuns8_t  *emitter_name,			      */
/*			   ...)						      */
/*									      */
/*  On input:								      */
/*									      */
/*	function	=   exit function				      */
/*									      */
/*	emitter_name	=   emitter instance name			      */
/*									      */
/*	...		=   dependent upon exit function		      */
/*									      */
/*  On output:								      */
/*									      */
/*	<nothing>							      */
/*									      */
/*  Function returns:							      */
/*									      */
/*	0		=   normal completion				      */
/*	non-zero	=   dependent upon exit function		      */
/******************************************************************************/
DLLEXPORT cobrtncode_t
AUDITFILE_EMITTER_EXIT(
    cobuns32_t	function,
    cobuns8_t	*emitter_name,
    ...)
{
    va_list	args;
    cobuns8_t	*filename;

    va_start(args, emitter_name);

    switch(function)
    {
    case AUDITFILE_EXIT_FUNC_INIT:
        printf("Initialising emitter %s\n", emitter_name);
        break;

    case AUDITFILE_EXIT_FUNC_DEINIT:
        printf("De-initialising emitter %s\n", emitter_name);
        break;

    case AUDITFILE_EXIT_FUNC_FILE_ACTIVE:
        filename = (cobuns8_t *)va_arg(args, cobuns8_t *);
        printf("Emitter %s; active file %s\n", emitter_name, filename);
        break;

    case AUDITFILE_EXIT_FUNC_FILE_FULL:
        filename = (cobuns8_t *)va_arg(args, cobuns8_t *);
        printf("Emitter %s; full file %s\n", emitter_name, filename);
        break;

    case AUDITFILE_EXIT_FUNC_NO_FILES:
        printf("Emitter %s; no available files\n", emitter_name);
        break;

    default:
        printf("Emitter %s; unknown function %d\n", emitter_name, function);
        break;
    }

    va_end(args);
    return 0;
}
Parent topic: Configuring a User Exit (deprecated)
Related reference
AUDITFILE User Exit (deprecated)


Audit Manager APIs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager provides APIs that you can use to audit-enable your applications, create your own audit emitters and process audit files.

  • API Return Codes (deprecated)
  • Audit Events (deprecated)
  • Audit Event Codes
  • Audit Configuration APIs (deprecated)
  • Audit Event Generation APIs (deprecated)
  • Audit Event Consolidator APIs (deprecated)
  • Audit File Processing APIs (deprecated)
  • Audit Emitter Interface (deprecated)
  • Structure and Typedefs (deprecated)
Parent topic: Using the Security Audit Manager (deprecated)


API Return Codes (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

These return codes are provided in the mfaudit.cpy copybook for COBOL programs, and the mfaudit.h include file for C programs.

Value | Name | Description
0 | 78-AUD-RET-SUCCESS | Success
-1 | 78-AUD-RET-FAILURE | Unspecified Failure
1 | 78-AUD-RET-INVALID-HANDLE | Invalid audit or audit file handle specified
2 | 78-AUD-RET-INVALID-AUDIT-CATEGORY | Invalid audit category specified
5 | 78-AUD-RET-NOT-ENOUGH-MEMORY | Memory allocation error
6 | 78-AUD-RET-OUTPUT-ERROR | Error outputting to one or more output destinations
7 | 78-AUD-RET-PROPERTY-NOT-FOUND | Property not found
8 | 78-AUD-RET-BUFFER-TOO-SMALL | Buffer length too small
9 | 78-AUD-RET-VALUE-NOT-INTEGER | Value is not an integer
10 | 78-AUD-RET-EMITTER-NOT-FOUND | Emitter not found
12 | 78-AUD-RET-ZERO-LENGTH-DATA | Zero length data specified
13 | 78-AUD-RET-INVALID-PROP-NAME | Invalid property name specified
14 | 78-AUD-RET-INVALID-COMP-NAME | Invalid component name specified
15 | 78-AUD-RET-INVALID-EMITTER-NAME | Invalid emitter name specified
19 | 78-AUD-RET-NO-SERVER-PROCESS | mfauditmgr process is not running
20 | 78-AUD-RET-ACCESS-DENIED | Unable to access resource(s)
21 | 78-AUD-RET-TIMEDOUT | Sending of event timed out
1000 | 78-AUD-RET-FILE-NOT-EXIST | File does not exist
1001 | 78-AUD-RET-FILE-NOT AVAILABLE | File(s) not available for dumping
1002 | 78-AUD-RET-FILE-INVALID-FORMAT | Unrecognised audit file format
1003 | 78-AUD-RET-FILE-EOF | End of file
1004 | 78-AUD-RET-FILE-NO-MORE-RECORDS | No more records left to process
1005 | 78-AUD-RET-FILE-INVALID-NAME | Invalid audit file name
1006 | 78-AUD-RET-FILE-NOT-DUMPED | Audit file has not been dumped
Parent topic: Audit Manager APIs (deprecated)


Audit Events (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Event Category | Component Identifier | Event Identifier | Event Data | Description
Audit Facility (1) MF.AUDITMGR 0
  1. mfauditmgr instance name (text)
  2. mfauditmgr instance type (4-byte comp-5)

    0 = command line

    1 = Windows service

mfauditmgr starting
1
  1. mfauditmgr instance name (text)
mfauditmgr stopping
2 | None | Request received from mfauditadm -p to deactivate the active file
Parent topic: Audit Manager APIs (deprecated)


Audit Configuration APIs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Configuration APIs are available:

  • CBL_AUDIT_CONFIG_PROPERTY_GET (deprecated)
    Get an audit configuration property value.
  • CBL_AUDIT_CONFIG_PROPERTY_SET (deprecated)
    Sets an audit configuration property value.
Parent topic: Audit Manager APIs (deprecated)


CBL_AUDIT_CONFIG_PROPERTY_GET (deprecated)

Get an audit configuration property value.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_CONFIG_PROPERTY_GET" using by value     flags
                                           by reference property-name
                                           by reference property-vallen
                                           by reference property-value
                                              returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)

On Entry:

Control flags

Bit | Value | Meaning
0 | 0 | Return string value. Use bit 1 to determine string terminator
 | 1 | Return integer value. Ignore bit 1.
1 | 0 | Return the value as a space-terminated string
 | 1 | Return the value as a null-terminated string
2-28 |  | Reserved for future use (must be 0)
29 | 0 | property-name is space-terminated
 | 1 | property-name is null-terminated
30-31 |  | Reserved for future use (must be 0)

property-name: Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name.

NAME | mfauditmgr instance name to connect, or are connected, to
NOSERVER_ACTION | indicates the desired behaviour of the CBL_AUDIT_EVENT API when the mfauditmgr process is not running. A value of "wait" indicates the API will block (the default). A value of "nowait" indicates the API will return an error.
SYSTEM | name of the system to be associated with audit events output by this process
TIMEOUT | the duration (in milliseconds) that an event will retry to be written to output before it times out.

property vallen: Length of property-value buffer in which property value is to be returned. The routine fails if this is too small for the value to be returned. This parameter is ignored if value is being returned as an integer.

On Exit:

property-vallen | Length of returned string value in property-value buffer. Length does not include termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen will be set to the required buffer length. This parameter is not set if the value is being returned as an integer.
property-value | Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer. A null property-value may be specified to request that the API returns the required buffer length to hold the specified property value.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-PROPERTY-NOT-FOUND
78-AUD-RET-BUFFER-TOO-SMALL
78-AUD-RET-VALUE-NOT-INTEGER
78-AUD-RET-INVALID-PROP-NAME

Comments:

CBL_AUDIT_CONFIG_PROPERTY_GET is used to retrieve a named property value associated with the audit facility's configuration for the current process.

Supported properties are yet to be defined.

Examples:

Get the value associated with the audit facility's "system" property.

copy "mfaudit.cpy" .

01 flags           pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move length of prop-string to prop-len

call "CBL_AUDIT_CONFIG_PROPERTY_GET" using
                                     by value flags
                                     by reference "system "
                                     by reference prop-len
                                     by reference prop-string
...
Parent topic: Audit Configuration APIs (deprecated)


CBL_AUDIT_CONFIG_PROPERTY_SET (deprecated)

Sets an audit configuration property value.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_CONFIG_PROPERTY_SET" using by value     flags
                                           by reference property-name
                                           by reference property-value
                                              returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | String value. Use bit 1 to determine string terminator
1 | Integer value. Ignore bit 1.
1 | 0 | String value is space-terminated
1 | String value is null-terminated
2-28 | Reserved for future use (must be 0)
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
property-name
Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name. Recognised property names are:
NAME | the mfauditmgr instance name to connect, or are connected, to
NOSERVER_ACTION | indicates the desired behaviour of the CBL_AUDIT_EVENT API when the mfauditmgr process is not running. A value of "wait" indicates the API will block (the default). A value of "nowait" indicates the API will return an error.
SYSTEM | name of the system to be associated with audit events output by this process
TIMEOUT | the duration (in milliseconds) that an event will retry to be written to output before it times out.
Note: Other property names may be set, but they will be ignored by the facility.
property-value
The alphanumeric or numeric (in the case of TIMEOUT) value of property-name.

On Exit:

Nothing.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-PROP-NAME

Comments:

CBL_AUDIT_CONFIG_PROPERTY_SET is used to set a named property value for the audit facility's configuration for the current process. If a property with the same name already exists, its value will be replaced with the new value.

Supported properties are yet to be defined.

Examples:

Set the audit facility's "system" property value.

copy "mfaudit.cpy ".

01 flags           pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move "ESDEMO" & x"00" to prop-string

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using
                                    by value flags
                                    by reference "system "
                                    by reference prop-string
...
Parent topic: Audit Configuration APIs (deprecated)


Audit Event Generation APIs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Event Generation APIs are available:

  • CBL_AUDIT_EVENT (deprecated)
    Outputs an audit event.
  • CBL_AUDIT_HANDLE_GET (deprecated)
    Get an audit handle.
  • cobaudit_event (deprecated)
    Outputs an audit event.
Parent topic: Audit Manager APIs (deprecated)


CBL_AUDIT_EVENT (deprecated)

Outputs an audit event.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EVENT" using by value     flags
                             by reference component-id
                             by reference audit-event
                                returning status-code
Table 1. Parameters
 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
audit-event | cblt-aud-event | Group containing
cblte-audevt-version | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-flags | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-id | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-category | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-data-count | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-reserved1 | cblt-x4-comp5 | pic x(4) comp-5 occurs 7
cblte-audevt-event-len | cblt-pointer | pointer
cblte-audevt-event-type | cblt-pointer | pointer
cblte-audevt-event-data | cblt-pointer | pointer
cblte-audevt-reserved2 | cblt-pointer | pointer occurs 7

On entry

Control flags

Bit | Value | Meaning
0-12 | Reserved | for future use (must be 0)
13 | 0 | cblte-audevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-audevt-event-len and cblte-audevt-event-type arrays need to be set up.
 | 1 | cblte-audevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-audevt-event-len and cblte-audevt-event-type need to be set up.
14-29 |  | Reserved for future use (must be 0)
30 | 0 | component-id is space-terminated
 | 1 | component-id is null-terminated
 |  | (ignored if bit 31 unset)
31 | 0 | component-id is an audit handle created by CBL_AUDIT_HANDLE_GET (pic x(4) comp-5).
 | 1 | component-id is a text string (pic x(n)) . The termination character for the string is defined by bit 30.
component-id
Component identifier. This will either be a pic x(4) comp-5 tracer handle (See CBL_AUDIT_HANDLE_GET() - Get an Audit Handle for details about how a component acquires an audit handle) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
cblte-audevt-version
Structure version. Must be 0.
cblte-audevt-flags
Control flags. Must be 0.
cblte-audevt-id
Component specific audit event identifier used to identify the type of event being output
cblte-audevt-category
Category of the audit event being output.
Value Category
0 Unknown
1 Audit Facility
2 System
3 Security API request check
4 Security API request define
5 Security API request other
6 Security API result allow
7 Security API result deny
8 Security API result error
9 Security API result success
cblte-audevt-data-count
Number of audit data items. Indicates the number of elements in the cblte-audevt-event-len, cblte-audevt-event-type, and cblte-audevt-event-data arrays. May be 0.
cblte-audevt-event-len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item in the cblte-audevt-event-data array. May be NULL if cblte-audevt-data-count is 0.
cblte-audevt-event-type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the cblte-sudevt-event-data array. May be NULL if cblte-audevt-data-count is 0.
Value Type
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
cblte-audevt-event-data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the cblte-audevt-event-type and cblte-audevt-event-len arrays respectively. May be NULL if cblte-audevt-data-count is 0.

N.B. for address type items, the array element is the address value, and not a pointer to the address value.

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-INVALID-AUDIT-CATEGORY
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-OUTPUT-ERROR
78-AUD-RET-INVALID-COMPONENT-NAME
78-AUD-RET-NO-SERVER-PROCESS
78-AUD-RET-ACCESS-DENIED
78-AUD-RET-TIMEDOUT

Comments:

None

Examples:

copy "mfaudit.cpy".

78 78-EVENT-TYPE-A      value 1.
78 78-EVENT-TYPE-B      value 2.

01 audit-event          cblt-aud-event.
01 audit-event-lengths  pic x(4) comp-5 occurs 1.
01 audit-event-pointers pointer occurs 1.
01 audit-event-types    pic x(4) comp-5 occurs 1.
01 audit-handle         pic x(4) comp-5.
01 audit-info           pic x(10).
01 component-id         pic x(7) value "mycomp ".
01 flags                pic x(4) comp-5.

...
move low-values to audit-event

set cblte-audevt-event-len of audit-event to
    address of audit-event-lengths(1)
set cblte-audevt-event-type of audit-event to
    address of audit-event-types(1)
set cblte-audevt-event-data of audit-event
    to address of audit-event-pointers(1)

1) Acquire an audit handle to trace "mycomp" component audit events, and then output two audit events: one with event data, one without.

call "CBL_AUDIT_HANDLE_GET" using by value 0
                                  by reference component-id
                                  by reference audit-handle
...
move 0 to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags
                             by reference audit-handle
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags
                             by reference audit-handle
                             by reference audit-event
...

2) Output two informational events for the "mycomp" component without acquiring an audit handle

...
move 78-AUD-FLAG-COMPID-STRING to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags
                             by reference component-id
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags
                             by reference component-id
                             by reference audit-event
...
Parent topic: Audit Event Generation APIs (deprecated)


CBL_AUDIT_HANDLE_GET (deprecated)

Get an audit handle.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_HANDLE_GET" using by value     flags
                                  by reference component-name
                                  by reference audit-handle
                                     returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-name | pic x(n) | pic x(n)
audit-handle | cblt-x4-comp5 | pic x(4) comp-5

On Entry:

flags
Bit | Value | Meaning
0-29 | Reserved for future use (must be 0)
30 | 0 | component-name is space-terminated
1 | component-name is null-terminated
(ignored if bit 31 unset)
31 | Reserved for future use (must be 0)
component-name
Space- or null-terminated (depending upon bit 30 setting) case-insensitive component identifier string.

On Exit:

audit-handle
Audit handle to be specified to the CBL_AUDIT_EVENT API.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-COMPONENT-NAME

Comments:

Components should invoke this API to acquire an audit handle before performing any auditing operations. This API returns an audit handle that should be passed to the CBL_AUDIT_EVENT API.

Please note that the CBL_AUDIT_EVENT API allows a component to be specified as a handle or as a string depending upon its flags parameter specification. This allows events to be output without first acquiring an audit handle by specifying a component identifier string instead. However, this will have an impact on performance as the component identifier will be validated each time.

Examples:

Acquire an audit handle to output "mycomp" audit events.

copy "mfaudit.cpy".

01 audit-handle    pic x(4) comp-5.
01 component-name  pic x(7) value "mycomp".
...
call "CBL_AUDIT_HANDLE_GET" using by value 0
                                  by reference component-name
                                  by reference audit-handle
...
Parent topic: Audit Event Generation APIs (deprecated)


cobaudit_event (deprecated)

Outputs an audit event.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

cobrtncode_t cobaudit_event(cobuns32_t      flags_p,
                   const cobuns8_t *component_id,
                   AUDIT_EVENT     *audit_event)

Table 1. Parameters
 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
audit-event | cblt-aud-event | Group containing
cblte-audevt-version | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-flags | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-id | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-category | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-data-count | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-reserved1 | cblt-x4-comp5 | pic x(4) comp-5 occurs 7
cblte-audevt-event-len | cblt-pointer | pointer
cblte-audevt-event-type | cblt-pointer | pointer
cblte-audevt-event-data | cblt-pointer | pointer
cblte-audevt-reserved2 | cblt-pointer | pointer occurs 7

On Entry:

Control flags
Bit | Value | Meaning
0-12 | Reserved | for future use (must be 0)
13 | 0 | cblte-audevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-audevt-event-len and cblte-audevt-event-type arrays need to be set up.
 | 1 | cblte-audevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-audevt-event-len and cblte-audevt-event-type need to be set up.
14-29 |  | Reserved for future use (must be 0)
30 | 0 | component-id is space-terminated
 | 1 | component-id is null-terminated
 |  | (ignored if bit 31 unset)
31 | 0 | component-id is an audit handle created by CBL_AUDIT_HANDLE_GET (pic x(4) comp-5).
 | 1 | component-id is a text string (pic x(n)) . The termination character for the string is defined by bit 30.
component_id
Component identifier. This will either be a 32-bit unsigned integer tracer handle (See CBL_AUDIT_HANDLE_GET() - Get an Audit Handle for details about how a component acquires an audit handle) if bit 31 of flags is not set, or a text identifier if bit 31 of flags is set.
audit_event
Audit event structure
version | Structure version. Must be 0.
flags | Control flags. Must be 0.
event_id | Component specific event identifier used to identify the type of event being output.
event_category | Audit event category.
data_count | Number of audit data items. Indicates the number of elements in the event_len, event_type, and event_data arrays. May be 0.
event_len | Pointer to array of 32-bit unsigned integers. Each array element indicates the length of the corresponding audit data item in the event_data array. May be NULL if data_count is 0.
event_type Pointer to array of 32-bit unsigned integers. Each array element indicates the type of the corresponding audit data item in the event_data array. May be NULL if data_count is 0.
Any value other than the ones specified above will be treated as type 0 (binary).
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
event_data Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the event_type and event_len arrays respectively. May be NULL if data_count is 0.

N.B. for address type items, the array element is the address value, and not a pointer to the address value.

On Exit:

Nothing

Return Codes:

AUDIT_RET_SUCCESS
AUDIT_RET_INVALID_HANDLE
AUDIT_RET_INVALID_AUDIT_CATEGORY
AUDIT_RET_NOT_ENOUGH_MEMORY
AUDIT_RET_OUTPUT_ERROR
AUDIT_RET_INVALID_COMPONENT_NAME
AUDIT_RET_NO_SERVER_PROCESS
AUDIT_RET_ACCESS_DENIED
AUDIT_RET_TIMEDOUT

Comments:

cobaudit_event() is intended for use by C programs. It outputs the specified event identified by event_id to one or more output destinations.

Parent topic: Audit Event Generation APIs (deprecated)


Audit Event Consolidator APIs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Event Consolidator APIs are available:

  • CBL_AUDIT_EMITTER_PROPERTY_GET (deprecated)
    Get an audit emitter property value.
  • CBL_AUDIT_EMITTER_PROPERTY_SET (deprecated)
    Set an audit emitter property value.
Parent topic: Audit Manager APIs (deprecated)


CBL_AUDIT_EMITTER_PROPERTY_GET (deprecated)

Get an audit emitter property value.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using by value     flags
                                            by reference emitter-name
                                            by reference property-name
                                            by reference property-vallen
                                            by reference property-value
                                               returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | Return string value. Use bit 1 to determine string terminator
1 | Return integer value. Ignore bit 1.
1 | 0 | Return the value as a space-terminated string
1 | Return the value as a null-terminated string
2-27 | Reserved for future use (must be 0)
28 | 0 | emitter-name is space-terminated
1 | emitter-name is null-terminated
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
emitter-name
Space- or null-terminated (depending upon setting of bit 28) case-insensitive emitter name.
property-name
Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name.
property-vallen
Length of property-value buffer in which property value is to be returned. The routine fails if this is too small for the value to be returned.

Ignored if value is being returned as an integer.

On Exit:

property-vallen | Length of returned string value in property-value buffer. Length does not include termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen will be set to the required buffer length. Not set if the value is being returned as an integer.
property-value | Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer. A null property-value may be specified to request that the API returns the required buffer length to hold the specified property value.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-PROPERTY-NOT-FOUND
78-AUD-RET-BUFFER-TOO-SMALL
78-AUD-RET-VALUE-NOT-INTEGER
78-AUD-RET-EMITTER-NOT-FOUND

Comments:

CBL_AUDIT_EMITTER_PROPERTY_GET is used to retrieve a named property value for the emitter with name emitter-name. The function would typically by used by an emitter during its initialisation to determine how it had been configured.

Examples:

Get two property values associated with the "AUDITFILE" emitter: one a space-terminated string value, one an integer value.

copy "mfaudit.cpy ".

01 emitter-name    pic x(10) value " AUDITFILE".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move length of prop-string to prop-len

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "location "
                                    by reference prop-len
                                    by reference prop-string
...
compute flags = 78-AUD-FLAG-PROP-INT-VALUE

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "collectionsize "
                                    by value 0
                                    by reference prop-integer
...
Parent topic: Audit Event Consolidator APIs (deprecated)


CBL_AUDIT_EMITTER_PROPERTY_SET (deprecated)

Set an audit emitter property value.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using by value     flags
                                            by reference emitter-name
                                            by reference property-name
                                            by reference property-value
                                               returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | String value. Use bit 1 to determine string terminator
1 | Integer value. Ignore bit 1.
1 | 0 | String value is space-terminated
1 | String value is null-terminated
2-27 | Reserved for future use (must be 0)
28 | 0 | emitter-name is space-terminated
1 | emitter-name is null-terminated
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
emitter-name
Typedef: pic x(n)

Picture: pic x(n)

property-name
Typedef: pic x(n)

Picture: pic x(n)

property-value
Typedef: pic x(n)

Picture: pic x(n)

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-EMITTER-NOT-FOUND
78-AUD-RET-INVALID-EMITTER-NAME
78-AUD-RET-INVALID-PROPERTY-NAME

Comments:

CBL_AUDIT_EMITTER_PROPERTY_SET is used to set a named property value for the emitter with name emitter-name. If a property with the same name already exists for the emitter, its value will be replaced with the new value.

Examples:

Set two property values associated with the "AUDITFILE" emitter: one a null-terminated string value, one an integer value.

copy "mfaudit.cpy ".

01 emitter-name    pic x(10) value "AUDITFILE".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE b-or
                78-AUD-FLAG-PROP-NULL-TERM
move "xxx" & x"00" to prop-string

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "location "
                                    by reference prop-string
...
compute prop-flags = 78-AUD-FLAG-PROP-INT-VALUE
move 10 to prop-integer

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "collectionsize "
                                    by reference prop-integer
...
Parent topic: Audit Event Consolidator APIs (deprecated)


Audit File Processing APIs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit File Processing APIs are available:

  • CBL_AUDIT_FILE_CLOSE (deprecated)
    Close an audit file.
  • CBL_AUDIT_FILE_OPEN (deprecated)
    Open an audit file.
  • CBL_AUDIT_FILE_READ (deprecated)
    Read a record from an audit file.
  • cobaudit_file_read (deprecated)
    Read a record from an audit file.
Parent topic: Audit Manager APIs (deprecated)


CBL_AUDIT_FILE_CLOSE (deprecated)

Close an audit file.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_CLOSE" using by value     flags
                                  by value     auditfile-handle
                                     returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer

On Entry:

Control flags

Bit | Value | Meaning
0 | 0 | Close all files associated with the handle
 | 1 | Close the current file associated with the handle (use when processing a file collection).
1 | 0 | Do not set 'dumped' flag
 | 1 | Set 'dumped' flag
2-31 |  | Reserved for future use (must be 0)
auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-FILE-NOT-DUMPED

Comments:

CBL_AUDIT_FILE_CLOSE() is used to close the audit file, or audit file collection, identified by the auditfile-handle parameter. The flags parameter can be used to control whether or not the file, or files if an audit file collection is associated with the handle, is marked as being 'dumped'. Once a file is marked as 'dumped', it can be reused by the audit event consolidator process.

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 flags             pic x(4) comp-5.
...
compute flags = 78-AUDITFILE-FLAG-CLOSE-CURRENT b-or
                78-AUDITFILE-FLAG-CLOSE-DUMPED

call "CBL_AUDIT_FILE_CLOSE" using by value flags
                                  by value auditfile-handle
...
Parent topic: Audit File Processing APIs (deprecated)


CBL_AUDIT_FILE_OPEN (deprecated)

Open an audit file.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_OPEN" using by value     flags
                                 by reference auditfile-handle
                                 by reference auditfile-name
                                    returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer
auditfile-name | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | Open the specified audit file
1 | Open the audit file collection for which the specified file is a member
1 | 0 | auditfile-name is space-terminated
1 | auditfile-name is null-terminated
2-31 | Reserved for future use (must be 0)

On Exit:

auditfile-handle Audit handle to be specified to the CBL_AUDIT_FILE_READ and CBL_AUDIT_FILE_CLOSE APIs.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-FILE-NOT-EXIST
78-AUD-RET-FILE-NOT-AVAILABLE
78-AUD-RET-FILE-INVALID-FORMAT
78-AUD-RET-FILE-INVALID-NAME

Comments:

CBL_AUDIT_FILE_OPEN() is used to open an audit file, or audit file collection. Only files that are available for dumping will be opened by this API (i.e. files in a collection which are marked as 'dumped' or 'active' will not be opened).

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 auditfile-name    pic x(32)
                     value "mfaudit.nwb-cpjdell.aud_1" & x"00".
01 flags             pic x(4) comp-5.
...
compute flags = 78-AUDITFILE-FLAG-OPEN-COLLECTION b-or
                78-AUDITFILE-FLAG-OPEN-NAME-NULL-TERM

call "CBL_AUDIT_FILE_OPEN" using by value flags
                                 by reference auditfile-handle
                                 by reference auditfile-name
      ...
Parent topic: Audit File Processing APIs (deprecated)


CBL_AUDIT_FILE_READ (deprecated)

Read a record from an audit file.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_READ" using by value     flags
                                 by value     auditfile-handle
                                 by reference auditfile-record
                                    returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer
auditfile-record | cblt-aud-record | Group containing
cblte-audrec-version | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-flags | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-tid-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-32 | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-64 | cblt-x8-comp5 | pic x(8) comp-5 redefines cblte-audrec-pid-32
cblte-audrec-tid-32 | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-tid-64 | cblt-x8-comp5 | pic x(8) comp-5 redefines cblte-audrec-tid-32
cblte-audrec-event-id | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-event-category | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-data-count | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-appname-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-cmdline-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-os-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-mc-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-sys-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-comp-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-encoded-time | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-hour | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-minute | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-second | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-millisecond | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-encoded-date | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-year | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-month | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-day | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-reserved1 | cblt-x4-comp5 | pic x(4) comp-5 occurs 7
cblte-audrec-appname | cblt-pointer | pointer
cblte-audrec-cmdline | cblt-pointer | pointer
cblte-audrec-os-name | cblt-pointer | pointer
cblte-audrec-mc-name | cblt-pointer | pointer
cblte-audrec-sys-name | cblt-pointer | pointer
cblte-audrec-comp-name | cblt-pointer | pointer
cblte-audrec-event-len | cblt-pointer | pointer
cblte-audrec-event-type | cblt-pointer | pointer
cblte-audrec-event-data | cblt-pointer | pointer
cblte-audrec-reserved2 | cblt-pointer | pointer occurs 7

On Entry:

flags
Bit | Value | Meaning
0-31 | Reserved for future use (must be 0)
Auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.

On Exit:

cblte-audevt-version
Structure version
cblte-audevt-flags
Control flags
cblte-audrec-pid-len
Length of process identifier (4 or 8)
cblte-audrec-tid-len
Length of thread identifier (4 or 8)
cblte-audrec-pid-32
4-byte process identifier
cblte-audrec-pid-64
8-byte process identifier
cblte-audrec-tid-32
4-byte thread identifier
cblte-audrec-tid-64
8-byte thread identfier
cblte-audrec-event-id
Component specific audit event identifier
cblte-audrec-category
Audit event category
Value | Category
0 | Unknown
1 | Audit Facility
2 | System
3 | Security API request check
4 | Security API request define
5 | Security API request other
6 | Security API result allow
7 | Security API result deny
8 | Security API result error
9 | Security API result success
cblte-audrec-data-count
Number of audit data items. Indicates the number of items in the cblte-audrec-event-len, cblte-audrec-event-type and cblte-audrec-event-data arrays
cblte-audrec-appname-len
Length of application name
cblte-audrec-cmdline-len
Length of command line
cblte-audrec-os-name-len
Length of operating system name
cblte-audrec-mc-name-len
Length of computer/machine name
cblte-audrec-sys-name-len
Length of system name
cblte-audrec-comp-name-len
Length of component name
cblte-audrec-encoded-time
Encoded time of event
cblte-audrec-hour
Decoded hour
cblte-audrec-minute
Decoded minute
cblte-audrec-second
Decoded second
cblte-audrec-millisecond
Decoded millisecond
cblte-audrec-encoded-date
Encoded date of event
cblte-audrec-year
Decoded year
cblte-audrec-month
Decoded month
cblte-audrec-day
Decoded day
cblte-audrec-appname
Pointer to null-terminated name of application that generated audit event
cblte-audrec-cmdline
Pointer to null-terminated command-line of application that generated audit event
cblte-audrec-os-name
Pointer to null-terminated name of operating system that generated audit event
cblte-audrec-mc-name
Pointer to null-terminated name of computer that generated audit event
cblte-audrec-sys-name
Pointer to null-terminated name of system that generated audit event
cblte-audrec-comp-name
Pointer to null-terminated name of component that generated audit event
cblte-audrec-event-len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item. Will be NULL if cblte-audrec-data-count is 0
cblte-audrec-event-type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the cblte-audrec-event-data array. Will be NULL if cblte-audrec-data-count is 0.
Value | Type
0 | Binary
1 | Text (local encoding)
2 | Address
3 | COMP-5
4 | COMP-X
5 | UTF8
6 | Signed COMP-5
7 | Signed COMP-X

Any value other than the ones specified above will be treated as type 0 (binary).

cblte-audrec-event-data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the cblte-audrec-event-type and cblte-audrec-event-len arrays respectively. Will be NULL if cblte-audrec-data-count is 0.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-FAILURE
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-FILE-INVALID-FORMAT
78-AUD-RET-FILE-EOF
78-AUD-RET-FILE-NO-MORE-RECORDS

Comments:

CBL_AUDIT_FILE_READ() is used to return the next audit record from the file(s) associated with the current handle.

The function will return 78-AUD-RET-FILE-EOF when attempting to read past the last record in a file for the first time. The next attempt to read past the last record will either return the first record of the next file in the collection if a collection has been opened and another file is available, or 78-AUD-RET-FILE-NO-MORE-RECORDS.

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 auditfile-record  cblt-aud-record.
01 flags             pic x(4) comp-5.
...
compute flags = 0

call "CBL_AUDIT_FILE_READ" using by value flags
                                 by value auditfile-handle
                                 by reference auditfile-record
...
Parent topic: Audit File Processing APIs (deprecated)


cobaudit_file_read (deprecated)

Read a record from an audit file.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

cobrtncode_t cobaudit_file_read(cobuns32_t       flags,
                                cbl_os_pointer_t auditfile_handle,
                                AUDIT_RECORD     *auditfile_record)

On Entry:

Control flags
Bit | Value | Meaning
0-31 | Reserved for future use (must be 0)
auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.
auditfile_record
Audit event structure
version | Structure version (must be 0)
flags | Control flags (must be 0)

On Exit:

Auditfile_record

Audit event structure

version
Structure version
flags
Control flags
process_id_len
Length of process identifier (4 or 8)
thread_id_len
Length of thread identifier (4 or 8)
p.process_id_32
4-byte process identifier
p.process_id_64
8-byte process identifier
t.thread_id_32
4-byte thread identifier
t.thread_id_64
8-byte thread identfier
event_id
Component specific audit event identifier
event_category
Audit event category
Value | Category
0 | Unknown
1 | Audit Facility
2 | System
3 | Security API request check
4 | Security API request define
5 | Security API request other
6 | Security API result allow
7 | Security API result deny
8 | Security API result error
9 | Security API result success
data_count
Number of audit data items. Indicates the number of items in the event_len, event_type and event_data arrays
appname_len
Length of application name
cmdline_len
Length of command line
os_name_len
Length of operating system name
mc_name_len
Length of computer/machine name
sys_name_len
Length of system name
comp_name_len
Length of component name
time
Encoded time of event
hour
Decoded hour
minute
Decoded minute
second
Decoded second
millisecond
Decoded millisecond
date
Encoded date of event
year
Decoded year
month
Decoded month
day
Decoded day
appname
Pointer to null-terminated name of application that generated audit event
cmdline
Pointer to null-terminated command-line of application that generated audit event
os_name
Pointer to null-terminated name of operating system that generated audit event
mc_name
Pointer to null-terminated name of computer that generated audit event
sys_name
Pointer to null-terminated name of system that generated audit event
comp_name
Pointer to null-terminated name of component that generated audit event
event_len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item. Will be NULL if data-count is 0
event_type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the event_data array. Will be NULL if data_count is 0.

Any value other than the ones specified above will be treated as type 0 (binary).

Value | Type
0 | Binary
1 | Text (local encoding)
2 | Address
3 | COMP-5
4 | COMP-X
5 | UTF8
6 | Signed COMP-5
7 | Signed COMP-X
event_data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the event_type and event_len arrays respectively. Will be NULL if data_count is 0.

Return Codes:

AUDIT_RET_SUCCESS
AUDIT_RET_FAILURE
AUDIT_RET_INVALID_HANDLE
AUDIT_RET_NOT_ENOUGH_MEMORY
AUDIT_RET_FILE_INVALID_FORMAT
AUDIT_RET_FILE_EOF
AUDIT_RET_FILE_NO_MORE_RECORDS

Comments:

cobaudit_event() is intended for use by C programs. It is used to return the next audit record from the file(s) associated with the current handle.

The function will return AUDIT_RET_FILE_EOF when attempting to read past the last record in a file for the first time. The next attempt to read past the last record will either return the first record of the next file in the collection if a collection has been opened and another file is available, or AUDIT_RET_FILE_NO_MORE_RECORDS.

Parent topic: Audit File Processing APIs (deprecated)


Audit Emitter Interface (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Emitter Interface information and APIs are available:

  • Audit Emitter Interface Overview (deprecated)
  • PFI_AUD_EMITTER_DEINIT (deprecated)
  • PFI_AUD_EMITTER_INIT (deprecated)
  • PFV_AUD_EMITTER_NOTIFY (deprecated)
  • PFI_AUD_EMITTER_OUTPUT (deprecated)
Parent topic: Audit Manager APIs (deprecated)


Audit Emitter Interface Overview (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each emitter configured for use by the Audit Manager, whether well-known or dynamically loaded, will conform to the interface outlined in this section.

A dynamically loaded emitter is loaded by the Audit Manager using the program name specified by an mfaudit.emitter configuration file entry (see mfaudit.emitter.emitter-name).

Once loaded, the GET_AUDIT_EMITTER_FUNCS entry point of the loaded program is invoked to retrieve the address of a function pointer table (see Structures and Typedefs for AUDIT_EMITTER_FUNCS). This table contains pointers for a set of functions responsible for initialising the emitter, deinitialising the emitter, outputting an audit event, and handling notifications of emitter property changes. The example below shows how the main entry point for an emitter would typically be coded to return an AUDIT_EMITTER_FUNCS structure:

....
#include "mfaudit.h"
....
static int audit_emitter_deinit(cobuns32_t flags,
                                void       *emitter_data);

static int audit_emitter_init(cobuns32_t          flags,
                              const cobuns8_t     *emitter_name,
                              AUDIT_EMITTER_EVENT *audit_event,
                              void                **emitter_data);

static void audit_emitter_notify(cobuns32_t notif_type,
                                 void       *notif_buf,
                                 void       *emitter_data);

static int audit_emitter_output(cobuns32_t          flags,
                                AUDIT_EMITTER_EVENT *audit_event,
                                Void                *emitter_data);

static AUDIT_EMITTER_FUNCS audit_emitter_funcs =
{
    0,                         /* Version of structure format      */
    0,                         /* Reserved for future use          */
    audit_emitter_init,        /* Function to initialise the       */
                               /* emitter                          */
    audit_emitter_deinit,      /* Function to deinitialise the     */
                               /* emitter                          */
    audit_emitter_output,      /* Function to output a trace event */
    audit_emitter_notify,      /* Function to handle notifications */
                               /* of emitter config changes        */
};
....

AUDIT_EMITTER_FUNCS *
GET_AUDIT_EMITTER_FUNCS()
{
    return &audit_emitter_funcs;
}
....

Emitter initialisation (the invocation of the fn_init AUDIT_EMITTER_FUNCS function) is deferred by the Audit Manager until just prior to the first audit event needing to be output. During emitter initialisation the emitter would typically invoke the CBL_AUDIT_EMITTER_PROPERTY_GET API to pick up the value associated with each of its known properties.

Emitter de-initialisation (the invocation of the fn_deinit AUDIT_EMITTER_FUNCS function) occurs during Audit Manager de-initialisation. During emitter de-initialisation the emitter would release any resources it had acquired during any previous invocations.

The outputting of an audit event (the invocation of the fn_output AUDIT_EMITTER_FUNCS function) occurs when a component invokes the CBL_AUDIT_EVENT API (see CBL_AUDIT_EVENT() - Output an Audit Event).

The emitter is notified (the invocation of the fn_notify AUDIT_EMITTER_FUNCS function) of each configuration change (e.g. property value change) that occurs for it after it has been initialised.

Parent topic: Audit Emitter Interface (deprecated)


PFI_AUD_EMITTER_DEINIT (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_DEINIT)(cobuns32_t flags,
                                      void       *emitter_data);

On Entry:

flags
Reserved for future use (must be 0)
emitter_data
Emitter-specific data

On Exit:

Nothing

Return Codes:

EMITTER_DEINIT_SUCCESS | 0
EMITTER_DEINIT_FAIL | -1

Comments:

This function is invoked by the audit facility during its deinitialisation to allow the emitter to release any resources it had acquired during any previous invocations.

Parent topic: Audit Emitter Interface (deprecated)


PFI_AUD_EMITTER_INIT (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_INIT)(cobuns32_t          flags,
                                    const cobuns8_t     *emitter_name,
                                    AUDIT_EMITTER_EVENT *audit_event,
                                    void                **emitter_data);

On Entry:

flags
Reserved for future use (must be 0)
emitter_name
Name of emitter being initialised
audit_event
Details of the first audit event to be output. (N.B. the event is not expected to be emitted during initialisation, but the information provided may be useful for file header creation (e.g. date/time))

On Exit:

emitter_data
Emitter-specific data

Return Codes:

EMITTER_INIT_SUCCESS | 0
EMITTER_INIT_FAIL | -1

Comments:

This function is invoked by the audit facility to perform the emitter's initialisation. Initialisation would typically involve the interrogation of the audit facility for the emitter's configuration properties via calls to the CBL_AUDIT_EMITTER_PROPERTY_GET() API (see CBL_AUDIT_EMITTER_PROPERTY_GET() - Get an Audit Emitter Property Value).

Emitter initialisation is deferred by the audit facility until just prior to the first audit event needing to be output.

Parent topic: Audit Emitter Interface (deprecated)


PFV_AUD_EMITTER_NOTIFY (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void (*PFV_AUD_EMITTER_NOTIFY)(cobuns32_t notif_type,
                                       void       *notif_buf,
                                       void       *emitter_data);

On Entry:

notif_type
Notification type:
0: Property value change has occurred. notif_buf is a pointer to an EMITTER_NOTIF_PROP_CHANGE structure.
notif_buf
Notification buffer. The contents of this buffer are dependent upon notif_type.
emitter_data
Emitter-specific data

On Exit:

Nothing

Return Codes:

Nothing

Comments:

This function is invoked by the audit facility for each configuration change that occurs for the emitter after it has been initialised.

Parent topic: Audit Emitter Interface (deprecated)


PFI_AUD_EMITTER_OUTPUT (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_OUTPUT)(cobuns32_t   flags,
                                      AUDIT_EMITTER_EVENT *audit_event,
                                      void		    *emitter_data);

On Entry:

flags | Reserved for future use (must be 0)
audit_event | Audit event to output
emitter_data | Emitter-specific data

On Exit:

Nothing

Return Codes:

EMITTER_OUTPUT_SUCCESS | 0
EMITTER_OUTPUT_FAIL | -1

Comments:

This function is invoked by the audit facility to output an audit event to an output destination.

Parent topic: Audit Emitter Interface (deprecated)


Structure and Typedefs (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Structure and Typedefs APIs are available:

  • Structures and Typedefs for AUDIT_EMITTER_FUNCS (deprecated)
  • Structures and Typedefs - AUDIT_EVENT (deprecated)
  • Structures and Typedefs - AUDIT_EMITTER_EVENT (deprecated)
  • Structures and Typedefs - AUDIT_RECORD (deprecated)
  • Structures and Typedefs - EMITTER_NOTIF_PROP_CHANGE (deprecated)
Parent topic: Audit Manager APIs (deprecated)


Structures and Typedefs for AUDIT_EMITTER_FUNCS (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_event
{
    cobuns32_t                version;               Version of structure format
    cobuns32_t                reserved;	             Reserved for future use
    PFI_AUD_EMITTER_INIT      fn_init;               Function to initialise the emitter
    PFI_AUD_EMITTER_DEINIT    fn_deinit;             Function to deinitialise the emitter
    PFI_AUD_EMITTER_OUTPUT    fn_output;             Function to output a trace event
    PFV_AUD_EMITTER_NOTIFY    fn_notify;             Function to handle notifications of emitter config changes
    PFI                       fn_reserved[4];        Reserved for future use
} AUDIT_EMITTER_FUNCS;

Version types (version):

    #define AUDIT_EMITTER_FUNCS_VERSION	0
Parent topic: Structure and Typedefs (deprecated)


Structures and Typedefs - AUDIT_EVENT (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_event
{
    cobuns32_t	version;	Version of structure format
    cobuns32_t	flags;	Control flags
    cobuns32_t	event_id;	Audit event identifier
    cobuns32_t	event_category;	Audit event category
    cobuns32_t	data_count;	Number of audit data items
    cobuns32_t	reserved1[7];	Reserved for future use
    cobuns32_t	*event_len;	Audit data item lengths
    cobuns32_t	*event_type;	Audit data item types
    void	*event_data;	Audit data items
    void	*reserved2[7];	Reserved for future use
}AUDIT_EVENT;

Version types (version):

    #define AUDIT_EVENT_VERSION	0

Control flags (flags):

    #define AUDIT_EVENT_FLAGS_NONE	0x00000000

Audit event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN	0

Audit data item types (event_type):

    #define AUDIT_EVENT_TYPE_BINARY     0
    #define AUDIT_EVENT_TYPE_TEXT       1
    #define AUDIT_EVENT_TYPE_ADDRESS    2
    #define AUDIT_EVENT_TYPE_COMP5      3
    #define AUDIT_EVENT_TYPE_COMPX      4
    #define AUDIT_EVENT_TYPE_UTF8       5
    #define AUDIT_EVENT_TYPE_COMP5S     6
    #define AUDIT_EVENT_TYPE_COMPXS     7
Parent topic: Structure and Typedefs (deprecated)


Structures and Typedefs - AUDIT_EMITTER_EVENT (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_emitter_event
{
    cobuns32_t          version;          Version of structure format
    cobuns32_t          flags;            Control flags
    cobuns32_t          date;             Encoded date
    cobuns32_t          time;             Encoded time
    cobuns32_t          process_id_len;   Length of process identifier
    cobuns32_t          thread_id_len;    Length of thread identifier
    cobuns32_t          comp_id;          Component identifier
    cobuns32_t          event_id;         Audit event identifier
    cobuns32_t          event_category;   Audit event category
    cobuns32_t          data_count;       Number of audit data items
    cobuns32_t          reserved1[6];     Reserved for future use
    const cobuns8_t     *process_id;      Process identifier
    const cobuns8_t     *thread_id;       Thread identifier
    const cobuns8_t     *appname;         Null-terminated application name
    const cobuns8_t     *cmdline;         Null-terminated process cmd line
    const cobuns8_t     *os_name;         Null-terminated operating system name
    const cobuns8_t     *mc_name;         Null-terminated machine name
    const cobuns8_t     *sys_name;        Null-terminated system name
    const cobuns8_t     *comp_name;       Null-terminated component name
    const cobuns8_t     *auditmgr_name;   Null-terminated auditmgr instance name
    const cobuns32_t    *event_len;       Audit data item lengths
    const cobuns32_t    *event_type;      Audit data item types
    const void          **event_data;     Audit data items
    void                *reserved2[7];    Reserved for future use
}AUDIT_EMITTER_EVENT;

Version types (version):

    #define AUDIT_EMITTER_VERSION	0

Control flags (flags):

    #define AUDIT_EMITTER_FLAGS_NONE         0x00000000
    #define AUDIT_EMITTER_FLAGS_ARRAY_DATA   0x00000002

Event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN             0
    #define AUDIT_EVENT_CATEGORY_AUDIT_FACILITY      1
    #define AUDIT_EVENT_CATEGORY_SYSTEM              2
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK   3
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_DEFINE  4
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_OTHER   5
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW   6
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY    7
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR   8
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS 9

Audit data item types (event_type):

    #define AUDIT_EMITTER_TYPE_BINARY     0
    #define AUDIT_EMITTER_TYPE_TEXT       1
    #define AUDIT_EMITTER_TYPE_ADDRESS    2
    #define AUDIT_EMITTER_TYPE_COMP5      3
    #define AUDIT_EMITTER_TYPE_COMPX      4
    #define AUDIT_EMITTER_TYPE_UTF8       5
    #define AUDIT_EMITTER_TYPE_COMP5S     6
    #define AUDIT_EMITTER_TYPE_COMPXS     7
Parent topic: Structure and Typedefs (deprecated)


Structures and Typedefs - AUDIT_RECORD (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_record
{
    cobuns32_t         version;                 Version of structure format
    cobuns32_t         flags;                   Control flags
    cobuns32_t         process_id_len;          Process identifier length (4 or 8 bytes)
    cobuns32_t         thread_id_len;           Thread identifier length (4 or 8 bytes)

    union
    {
    cobuns32_t            process_id_32;           Process identifier (32-bit)
    cobuns64_t            process_id_64;           Process identifier (64-bit)
    }p;

    union
    {
    cobuns32_t            thread_id_32;            Thread identifier (32-bit)
    cobuns64_t            thread_id_64;            Thread identifier (64-bit)
    }t;

    cobuns32_t         event_id;                Audit event identifier
    cobuns32_t         event_category;          Audit event category
    cobuns32_t         data_count;              Number of audit data items
    cobuns32_t         appname_len;             Application name length
    cobuns32_t         cmdline_len;             Process command line length
    cobuns32_t         os_name_len;             Operating system name length
    cobuns32_t         mc_name_len;             Machine name length
    cobuns32_t         sys_name_len;            System name length
    cobuns32_t         comp_name_len;           Component name length

    cobuns32_t         time;                    Encoded time
    cobuns32_t         hour;                    Decoded hour
    cobuns32_t         minute;                  Decoded minute
    cobuns32_t         second;                  Decoded second
    cobuns32_t         millisecond;             Decoded millisecond
    cobuns32_t         date;                    Encoded date
    cobuns32_t         year;                    Decoded year
    cobuns32_t         month;                   Decoded month
    cobuns32_t         day;                     Decoded day
    cobuns32_t         reserved1[7];            Reserved for future use

    const cobuns8_t    *appname;                Null-terminated application name
    const cobuns8_t    *cmdline;                Null-terminated process command line
    const cobuns8_t    *os_name;                Operating system name
    const cobuns8_t    *mc_name;                Machine name
    const cobuns8_t    *sys_name;               Null-terminated system name
    const cobuns8_t    *comp_name;              Null-terminated component name
    cobuns32_t         *event_len;              Audit data item lengths
    cobuns32_t         *event_type;             Audit data item types
    void               *event_data;             Audit data items
    void               *reserved2[7];           Reserved for future use
}AUDIT_RECORD;

Version types (version):

    #define AUDIT_RECORD_VERSION	0

Event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN             0
    #define AUDIT_EVENT_CATEGORY_AUDIT_FACILITY      1
    #define AUDIT_EVENT_CATEGORY_SYSTEM              2
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK   3
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_DEFINE  4
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_OTHER   5
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW   6
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY    7
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR   8
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS 9

Audit data item types (event_type):

    #define AUDIT_EVENT_TYPE_BINARY    0
    #define AUDIT_EVENT_TYPE_TEXT      1
    #define AUDIT_EVENT_TYPE_ADDRESS   2
    #define AUDIT_EVENT_TYPE_COMP5     3
    #define AUDIT_EVENT_TYPE_COMPX     4
    #define AUDIT_EVENT_TYPE_UTF8      5
    #define AUDIT_EVENT_TYPE_COMP5S    6
    #define AUDIT_EVENT_TYPE_COMPXS    7
Parent topic: Structure and Typedefs (deprecated)


Structures and Typedefs - EMITTER_NOTIF_PROP_CHANGE (deprecated)

Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct emitter_notif_prop_change
{
    cobuns32_t           version;  Version of structure format
    cobuns32_t           flags;    Control flags
    cobuns32_t           namelen;  Length of property name
    cobuns32_t           vallen;   Length of value
    cobuns32_t           valint;   Integer representation of value
    cobuns8_t            *name;    Property name
    cobuns8_t            *value;   Property value
}EMITTER_NOTIF_PROP_CHANGE;

Version types (version):

    #define EMITTER_PROP_CHANGE_VERSION	0

Control flags (flags):

    #define EMITTER_PROP_CHANGE_FLAGS_NONE         0x00000000
    #define EMITTER_PROP_CHANGE_FLAGS_VAL_INTEGER  0x00000001
Parent topic: Structure and Typedefs (deprecated)


Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Before you attempt to secure communications, it is important that you understand PKI and SSL concepts. The SSL and PKI Technology Primer contains information on these concepts.
  • Introduction to Securing Communications
  • Configuring Secure Communications for Client Applications
  • Setting Up Secure Communications
  • Troubleshooting a Secure Connection
  • Using the Demonstration Certificate Authority
  • Tutorial: Requesting and Issuing Server Certificates
  • Tutorial: Configuring SSL Security in the Server
  • Information on OpenSSL
  • SSL and PKI Technology Primer
    The topics in this section describe the basics of SSL and PKI technology, and how they work together to secure communications.
  • Specifying a Server Protocol and Cipher Suite Preference
  • Secure Communications (SSL) Legal Information
Parent topic: Enterprise Server Security


Introduction to Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can enable secure communication between Micro Focus systems and clients who access those systems. This is done using Secure Sockets Layer (SSL) encryption. With secure communications, all communications between a client and a server are encrypted.

You typically use PKI certificates issued from a trusted Certifying Authority (CA) to secure your installation.

Web browser access is secured with the HTTPS web browser protocol. This mechanism secures web access, for example the Enterprise Server configuration user interface.

You can use the demonstration CA software to generate certificates and test your secure communications setup before using certificates issued by a trusted CA. The demonstration CA software is based on the OpenSSL software.

You can use these to familiarize yourself with the setup without the need to obtain cerrtificates from a trusted CA. The online help includes a tutorial that describes the process of using the DemoCA to secure your system.

Parent topic: Securing Communications


Configuring Secure Communications for Client Applications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A client application is an application that communicates with Enterprise Server Enterprise. You can require a certificate from any clients that communicate with your server. This sets up SSL links for peer-to-peer communication (as opposed to client/server communication).

In order to communicate securely, a client application needs access to the root certificates of any trusted CAs that the server uses. The trusted CAs are those who signed the certificates of the servers you are communicating with securely.

  • Securing Peer to Peer Communications
  • Installing a Client Certificate for Enterprise Server
  • Adding a CA Root Certificate to your Client Application
  • Installing a CA Root Certificate in a Client Browser
  • Installing server certificates for secure communication
  • To configure TLS default properties for clients
Parent topic: Securing Communications


Securing Peer to Peer Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure that any clients that communicate with your server must supply a certificate. This sets up SSL links for peer-to-peer communication (as opposed to client/server communication)

To request or require a certificate from clients who communicate with your server:

  1. Connect to ES Admin, for example by entering http://localhost:86 in your Web browser.
  2. Select the enterprise server you want, such as ESDEMO. Stop it if it is started, and then click Edit.
  3. Go to the Listeners page.
  4. Select the HTTPS listener you want (if you can't see the one you want, set the Process filter to All), and click Edit .
  5. Check Secure Sockets Layer.
  6. Click SSL Options and then:
    • Check the appropriate option to request or require client certificates.
    • Enter the CA root certificate of the CA who signed the client cerificate.

If the CA who signed the client's certificate is not trusted, communication is prevented. If you want to trust the signing CA, you can add it to your trusted CAs by updating the relevant certificates options in your browser.

Parent topic: Configuring Secure Communications for Client Applications


Installing a Client Certificate for Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

On client systems such as COBOL Web Services clients, and clients that use client/server binding, and COBOL XML I/O, you need to set client information in a file, as follows:

To set up client certificate, key file and pass phrase information in a file:

  1. On the Enterprise Server machine, create the file mf-client.dat in the $COBDIR/etc directory if the file doesn't already exist.
  2. Add an [SSL] section to this file and set parameters for the root certificate, the client certificate, the client key file, and the client key file passphrase, as follows:
         [SSL]
    root=/path/to/root/cert.type
    certificate=/path/to/client/cert.type
    key=/path/to/client/keyfile.type
    passphrase=keyfile passphrase

    where:

    • root defaults to ssldir/private/CArootcert.pem, where ssldir is the directory where Security Pack is installed, and is by default /opt/microfocus/DemoCA/openssl or $COBSSL (if set).
    • If certificate isn't specified, no client-side certificate is used
Note:
  • If you use a client certificate, the pass phrase for the key file appears in plain text in the mf-client.dat file. For security purposes, you should make this file readable only by the user or users who run applications that use this certificate.
  • Instead of mf-client.dat, you can create a file of any name or location, but you must identify it using the MFC_CONFIG environment variable.
Parent topic: Configuring Secure Communications for Client Applications


Adding a CA Root Certificate to your Client Application

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have written a client application that communicates with server applications such as Enterprise Server, the client application needs access to the root certificates of any trusted CAs. The trusted CAs are those who signed the certificates of the servers you are communicating with securely.

This pack includes a collection of well-known CA root certificates plus the self-signed certificate of the demonstration CA. These root certificates are contained in a single file called CARootCerts.pem, found in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default. This file is not protected by a pass phrase, so you can modify it. You need to add other CA root certificates to the CA root certificate file, if your client application communicates with servers whose certificates are signed by CAs whose certificates are not already in the file.

To add a CA root certificate to the root certificate file:

  1. Convert the new certificate to the same format as the certificates in the file, which in this case is PEM format with DER content encoding. Use openssl to do this. For example, to convert a PKCS7 format file, such as IECert.p7b, to PEM format:
    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem
  2. Append the new certificates to the existing file CARootCerts.pem. For example:
    cat CARootCerts.pem IECert.pem > NewCARootCerts.pem
Note: The CARootCerts.pem file is subject to being updated when a new version of the Micro Focus Security Pack is installed. If you add certificates to this file, you will need to repeat those additions when you update the Micro Focus Security Pack.
Parent topic: Configuring Secure Communications for Client Applications


Installing a CA Root Certificate in a Client Browser

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The root certificates of well-known trusted CAs are often installed with the client browser, so you might not need to install any. The security policy in your organization might restrict your access to the Web and might have removed the trusted CA root certificates. In this case you need to install root certificates for the CAs that signed the server certificates of the servers you need to communicate with securely.

Note: The root certificate for the demonstration CA is not pre-installed, and so you need to install this certificate to enable you to use the demonstration CA.

CA root certificates can be specified as any of the following:

  • A single file containing a single certificate.
  • A single file containing multiple certificates. This file defines your trusted CAs (plus their chains if appropriate).
  • A directory containing PEM files that each contain a single certificate. These files are named with the hash value of the certificate content, using the hash.0 format. For example, you can display this hash value, using the command:
    openssl X509 -hash -in CARootcert.pem

    This produces the following output:

    1a584193
----BEGIN CERTIFICATE
....

    Where:

    • The number that is displayed before the certificate is the hash value of the certificate.
    • The filename of the certificate would be 1a584193.0

To install a CA root certificate:

  1. In your browser, go to the options where you manage certificates. For example:
    • In Internet Explorer, click Tools > Internet Options > Content > Certificates. Go to the Trusted Root Certification Authorities tab.
    • In Mozilla Firefox, click Tools > Options > Advanced. Scroll down, click Manage Certificates and then click Authorities.
  2. Click Import and select the CA's root certificate.

    For the demonstration, select the self-signed certificate CARootCert.cer, which is in the private subdirectory of /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default.

    Internet Explorer requires certificates in DER format, so only those are listed in the File Open field, and not the PEM format files. Mozilla Firefox can handle several types, so several are listed and you can install the PEM-format certificate.

  3. In Internet Explorer, use the Browse button to enter Trusted Root Certification Authorities in the Certificate Store field.

    In Mozilla Firefox, check Trust this CA to identify Web sites.

  4. Look down the list under Trusted Root Certification Authorities (for Internet Explorer) and Authorities (for Firefox). You'll see your Demo CA is now listed; look for its Common Name. If when you installed Micro Focus Security Pack you chose to use your computer DNS name as the DemoCA's Common Name, it will probably look an odd-one-out, because real CAs tend to give themselves user-friendly Common Names.
Parent topic: Configuring Secure Communications for Client Applications


Installing server certificates for secure communication

Restriction: This topic applies only when the Enterprise Server feature is enabled.
In the role of administrator of Enterprise Server, you need to install the SSL server certificate so that remote client software and Web users can request it. Installing a certificate entails storing the certificate and key file in a folder accessible to the server software.
Note: The DemoCA is intended to provide certificates and keyfiles for development and testing purposes. Micro Focus strongly recommends that commercial certificates are used for production environments.

To install a server certificate:

  1. Connect to ES Admin, for example by entering http://localhost:86 in your Web browser.
  2. Select the enterprise server you want, such as ESDEMO. Stop it if it is started, and then click Edit.
  3. Go to the Listeners page.
  4. Select the HTTPS listener you want (if you can't see the one you want, set the Process filter to All), and click Edit .
  5. If Secure Sockets Layer is not checked, check it and configure this listener as a secure listener.
  6. Enter the filenames of your server certificate and private key in the Certificate and Keyfile fields. If these are not in the default directories, you also need to supply the paths to these files. For example:
    • ssldir/certs/srvcert.pem
    • ssldir/keys/srvkey.pem

    Where ssldir is the directory where Security Pack is installed, and is by default /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

    Note: Visual COBOL 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.
  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 $COBDIR\bin or \bin64 directory (Windows), or $COBDIR/bin folder (UNIX). 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To set up secure communications, you need the following:

  • For machine on which the server operates, a certificate and a private key file for the server.

    Typically these are issued by a trusted Certifying Authority (CA). To set up secure communications, you need to know the path location where these files are stored.

  • The pass phrase for the server certificate and keyfile.
  • For machines that access the listener, the CA's root certificate.

    Root certificates for many trusted authorities are installed by default with many web browsers.

The process you use to set up secure communications for an Enterprise Server instance is outlined below:

  1. Install the certificate and a private key file on the machine running Enterprise Server, and note the path.
  2. For the Enterprise Server instance to configure, create a secure listener and configure it to use the key file that you installed.
  3. Start the server and the listener, and configure the private key file's pass phrases.

    You can set the certificate and keyfile pass phrases either in a configuration file, or you can enter them manually whenever you start the server.

  4. On machines that use the listener, if required, configure the CA root certificate.

Steps 2, 3, and 4 are described in detail in this help.

  • To enable secure communications with SSL
  • To 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
Parent topic: Securing Communications


To enable secure communications with SSL

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Make sure the enterprise server you're going to use, for example ESDEMO, is stopped.
  2. Create and configure an HTTPS listener.
  3. If you want to keep your pass phrases in a file, add them to the file.
  4. Return to the Home page of ES Admin and start ESDEMO.
  5. Check that all the listeners have started, by looking on the Listeners page. If you entered the pass phrases using a file, you should find that the HTTPS listener has started like all the other listeners. If you didn't, then the status of the HTTPS listener is Start pending.
  6. If you didn't set the pass phrase using a file, set it now:
  7. Optionally, enable additional logging of listener startup for debugging purposes.
Parent topic: Setting Up Secure Communications


To Create a Secure Communications Process

For an enterprise server instance, you can create a secure Communications Process control listener to encrypt the communications it handles.

  1. On the Enterprise Server Administration screen, click Details in the Communications Processes column that corresponds to the server which you want to secure.

    This opens the Communications Process page.

  2. Click Edit next to the Communications Process you want to secure.
  3. In the Endpoint options area, check Secure Sockets Layer.
  4. In the Certificate field, type the absolute path to the certificate file.
  5. 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.
  6. Click OK.

If the enterprise server is configured to use a security manager, then in addition to enabling SSL (TLS) 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For an Enterprise Server instance, you can create a secure listener, to encrypt the communications that the listener handles.

  1. On the Enterprise Server Administration screen, edit the server to which you want to add the secure listener.
  2. Select the Listeners tab, and next to the listener you want to secure, click Edit.
  3. In the Endpoint Options area, select the Secure Sockets Layer checkbox.

    The Certificate and the Keyfile fields become active.

  4. Enter the path locations of the certficate and the private key file.
  5. Click OK to save your configurations.
Parent topic: Setting Up Secure Communications


To Start a Secure Listener and Set the Pass Phrase

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use this task for Enterprise Server instances with secure listeners where you want to set the pass phrases each time you start the server.

  1. On the Enterprise Server Administration screen, click the Start button for the server that you want to start, and on the confirmation screen, click OK to continue.
  2. When the server starts, click the server's Details button.
  3. On the server's Details screen, select the Listeners tab.
  4. In the listener list, locate your secure listener, and in the Status column, click Authorize.

    The Communications Process screen is displayed.

  5. Enter the Certificate Passprhase and the Keyfile Passphrase and click Set Passphrases The passphrases are set and the listener starts and becomes available for use.
Note: If the listener fails to start, it can be useful to look in the CS console. To access the CS console, on the server's Details page, select: Server > Diagnostics > CS Console
Parent topic: Setting Up Secure Communications


To Configure the Passphrase in a File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 region as the listener name.

By default, the mf-server.dat file is in the $COBDIR/etc 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.
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 $COBDIR\bin or \bin64 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


Troubleshooting a Secure Connection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If a secure listener fails to start, there are some options you can use to locate the cause.

  • Accessing the Communications Server Console
  • To enable logging for listener startup
  • Troubleshooting Certificate Problems
Parent topic: Securing Communications


Accessing the Communications Server Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To determine the cause of a secure listnener failure, it can be useful to look in the Communications Server (CS) console and review the messages that the listener generated. To access the CS console:

  1. On the Entereprise Server Administration Home page, click Edit at the left of the server you want to check.
  2. Click the Diagnostics tab, then click the CS Console tab.
  3. To view the entire log since the server was started, click Show Entire Log. The log opens in a text editor window.
Parent topic: Troubleshooting a Secure Connection


To enable logging for listener startup

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To help locate the causes of listener problems, you can enable additional logging of the listener startup process.

  1. On the 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your application refuses to trust a certificate from a specific location, it might be because the one of the signers in the chain of CAs, or even the originating CA root, is not trusted. To locate the problem, you need to get the server's certificate chain, from its own identity certificate right through to the originating CA root in the server's chain of trust.

To get the chain of certificates for a specific server, you use the s_client function of OpenSSL. This function implements a generic SSL/TLS client that can establish a transparent connection to a remote server speaking SSL/TLS. It's intended for testing purposes only and provides only rudimentary interface functionality but internally uses mostly all functionality of the OpenSSL ssl library.

You connect to a SSL service on the server, as follows:

openssl s_client -showcerts -connect <myserver>:<ssl_port>

This returns all the certificates in the chain, starting with the server certificate and ending with the root CA certificate. They are all in PEM format. This command opens a session with the server. After responding to your request for the certificates, the session sits waiting for you to send further requests. You can send Ctrl+Z to exit the session or wait for the server to time out the connection.

For example:

openssl s_client -showcerts -connect ibank.myBank.co.uk:443

The above command returns:

Loading 'screen' into random state - done
CONNECTED(00000790)
depth=2 /C=US
        /O=VeriSign, Inc.
        /OU=Class 3 Public Primary Certification Authority

verify error:num=19:self signed certificate in certificate chain
verify return:0

Error 19 status is expected, because the CA root certificate in all certificate chains is self-signed. See Error 19 Details later for more details.

---
Certificate chain
 0 s:/C=GB/ST=Bucks/L=Chesham/O=myBank PLC
     /OU=Enable
     /OU=Terms of use at www.verisign.co.uk/rpa (c) 03
     /OU=Authenticated by VeriSign
     /OU=Member, VeriSign Trust Network
     /CN=ibank.myBank.co.uk
   i:/O=VeriSign Trust Network
     /OU=VeriSign, Inc.
     /OU=VeriSign International Server CA - Class 3
     /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
-----BEGIN CERTIFICATE-----
MIIE3TCCBEagAwIBAgIQXM1dOQs/cV03UDAru58mEjANBgkqhkiG9w0BAQQFADCB
ujEfMB0GA1QBChMWVmVyaVNpZ24gVHJ1c3QgTmV0d29yazDJEEUGA1UECxMOVmVy
ONfYgdrkI7Bwhc58KJR4zqwppdl0QgsspXgmz7gJFgsgfZdptm/QvXfs+N4mxDm8
b0I6p9RtmLq82Itr6q1wUWssjHm5PlZRoQ8YaYJkaUN2rLsRT1SyQxygRo9xu81d
0Q==
-----END CERTIFICATE-----

This marks the end of certificate “0”, which identifies the server system. The next section labeled "s:" refers to the certificate owner ("subject") and the following section "i:" refers to the issuer.

 1 s:/O=VeriSign Trust Network
     /OU=VeriSign, Inc.
     /OU=VeriSign International Server CA - Class 3
     /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
   i:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
-----BEGIN CERTIFICATE-----
MIIDgzCCAuygAwIBAgIQJUuKhThCzONY+MXdriJupDANBgkqhkiG9w0BAQUFADBf
MQswCQYDVQQGEwJVUzEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xNzA1BgNVBAsT
1RPuKSvD5HKNRO3RrCAJLeH24RkFOLA9D59/+D3R3IYChmFOJl9en5IeDCSk9dBw
E88mw0M9SR2egi5SX7w+xmYpAY5Okiy8RnUDgqxz6dl+C2fvVFIa
-----END CERTIFICATE-----

We have reached the end of certificate “1” which identifies the signer of the server system’s certificate. Looking at the “s” section we can see that there is less detail in this certificate than in certificate “0”, but still enough to give a legal identity to the signer. This is important to understand. When creating certificate to use in real world situations, the creator must provide enough information within the certificate content to legally identify the item or entity being represented by the certificate.

 2 s:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
   i:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
-----BEGIN CERTIFICATE-----
MIICPDCCAaUCEHC65B0Q2Sk0tjjKewPMur8wDQYJKoZIhvcNAQECBQAwXzELMAkG
A1USXhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFzlbwdj2wsqFHMc9ikwFPwTtYmwHYBV4GSXiHx0bH/59AhWM1pF+NEHJwZRDmJXNyc
AA9WjQKZ7aKQRUzkuxCkPfAyAw7xzvjoyVGM5mKf5p/AfbdynMk2OmufTqj/ZA1k
-----END CERTIFICATE-----
---
Server certificate
subject=/C=GB/ST=Bucks/L=Chesham/O=myBank PLC
        /OU=Enable
        /OU=Terms of use at www.verisign.co.uk/rpa (c) 03
        /OU=Authenticated by VeriSign/OU=Member, VeriSign Trust Network
        /CN=ibank.myBank.co.uk
issuer=/O=VeriSign Trust Network
       /OU=VeriSign, Inc.
       /OU=VeriSign International Server CA - Class 3
       /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
---
No client certificate CA names sent
---
SSL handshake has read 2894 bytes and written 352 bytes
---
New, TLSv1/SSLv3, Cipher is RC4-MD5
Server public key is 1024 bit
SSL-Session:
    Protocol  : SSLv3
    Cipher    : RC4-MD5
    Session-ID: 56931DEEE4EDB5808FAC374D3AD7EC1C90A4FB4E2FF6DA16749203A87C7FA169

    Session-ID-ctx:
    Master-Key: C87463A6C17BFC2A8817F9B6B302C8EAE53B2BC25AB63A3DEA461EA495B20C78
B4AAF17DEED14661D8A09488215DCA7B
    Key-Arg   : None
    Start Time: 1112711406
    Timeout   : 300 (sec)
    Verify return code: 19 (self signed certificate in certificate chain)
---
closed

You can close the session using Ctrl+Z and then Enter, to which the server should respond:

DONE

Error 19 Details

In the above example, you can see that the ultimate CA root certificate is self-signed. The ultimate CA root certificate in all certificate chains is self-signed.

The error 19 occurs because the s_client function doesn't check the default OpenSSL CA certificate store against the CA root certificates being passed in the replies by the server. So, even if this certificate is already present in the CARootCerts file, and this file is correctly configured in the openssl.cnf file, this function 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


Using the Demonstration Certificate Authority

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Demonstration Certificate Authority (CA) is delivered as part of a Micro Focus Security Pack. The installer for it is within the Visual COBOL installation directory.

You can use the demonstration CA software to generate certificates and test your secure communications setup before using certificates issued by a trusted CA. The demonstration CA software is based on the OpenSSL software.

You can familiarize yourself with the setup without the need to obtain certificates from a trusted CA. The online help includes a tutorial that describes the process of using the DemoCA to secure your system.

  • About the Demo CA
  • OpenSSL and Micro Focus Demo CA
  • Installing Micro Focus Demo CA
  • Contents of the Demonstration CA
  • Your CA Certificate, Key and Password
  • Your Distinguished Name and Policy
  • Is the Demonstration CA a Real CA?
Parent topic: Securing Communications


About the Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA enables you to configure secure communication for an Enterprise Server listener.

Encryption uses Secure Sockets Layer (SSL) and is fully interoperable with standard (non-Micro Focus) SSL clients and servers. Micro Focus Demo CA also provides support for integration with Public Key Infrastructures (PKIs) and PKI functions, such as processing certificates.

The demonstration CA software enables you to operate as a Certifying Authority. An operating CA needs to create certificates, and it needs an LDAP to store the certificates it creates along with its own certificate (self-signed in the case of a root CA). For training and testing you will be acting as both a CA and a server requesting certificates, so you need certificates and keys for both.

The demonstration CA comprises a directory structure and the files needed for the demonstration. The demonstration CA is set up with the following:

  • A public/private key pair.
  • A certificate containing your Distinguished Name, your public key and signed with your private key. The Distinguished Name comprises the details you gave during installation, such as your computer name (known as Common Name in PKI terminology), address, and so on.
  • A pass phrase, which you use to access the private key. This pass phrase is srvrootpwd, which you can change later. OpenSSL uses pass phrases, which can include spaces, whereas passwords cannot.
  • A configuration file openssl.cnf, which contains the SSL defaults and other information.

You use the demonstration CA to create certificates. Since the CA is local, these certificates are not recognized outside your organization. For production use you should obtain certificates from a well-known Certifying Authority and use those. The Demo CA is suitable for training and testing.

Note:

If you consider using the demonstration for anything other than training or testing, it is essential that you read the warnings in the section Is the Demonstration CA a Real CA?.

Parent topic: Using the Demonstration Certificate Authority
Related information
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


OpenSSL and Micro Focus Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA includes the utility openssl.exe. You can use the demonstration CA to generate and process certificates and keys during training, development and testing.

OpenSSL is an organization that has developed a toolkit for implementing SSL. A subset of this toolkit is provided with this pack, as a command-line utility called openssl.exe. It provides functions you need for using SSL and PKIs - notably, functions for creating and checking certificates. For details on the OpenSSL organization, see their Web site www.openssl.org.

The SSL support in the Micro Focus Demo CA is based on the OpenSSL source distribution, and provides a subset of the features in full OpenSSL source. Therefore, documentation on the Web regarding OpenSSL applies to the SSL support provided by this pack, although some features might not be relevant. The SSL documentation on the Web can be a useful guide.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Installing Micro Focus Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, the Micro Focus Demo CA installation file, DemoCA_Setup.sh is located in $COBDIR/DemoCA.

To install Micro Focus Demo CA:

  1. Use the following command to run the installable shell script DemoCA_Setup.sh:
    sh DemoCA_Setup.sh
  2. Follow the prompts in the install wizard.
    Note: The values that you set in the installation screen define the default distinguished name (DN) for the sample certificates created in the Demo CA.
Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Contents of the Demonstration CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Demo CA installation creates the following directories and contents:

Name | Description
certs | You use this directory to store copies of all certificates and key files that you as a CA issue
crl | When you revoke a certificate, it is added to file crl.pem in here
newcerts | Holds the database of certificates you have issued. When you create a certificate, it is created in here with a numeric name, for example 01.pem.
private | Contains your self-signed CA root certificate in several formats and your private key

The following files are installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set):

Name | Description
create_srv_req.cmd | Script that creates a request for a server certificate
create_cli.cmd | Script that creates a client certificate
index.txt | Index to the certificates stored in newcerts
install_demoCA.cmd | Script that creates a CA that can be used to sign and verify certificates. This is for demonstration and development purposes only and should not be used in production.
sign_srv.cmd | Script that processes a server certificate request and signs the certificate
openssl.exe | OpenSSL command-line utility
openssl.cnf | Configuration file that specifies directories and defaults for SSL support
.rand | Random number used in generating keys. This number is generated anew each time you create a key.
serial | Number to be allocated to the next certificate you issue.
srv.pem | Certificate request (together with the private key in the one file) from which the server certificate was created
srvcert.pem | Your server certificate
srvkey.pem | Your server's private key
Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Your CA Certificate, Key and Password

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The private subdirectory contains the root CA certificate and matching private key.

The certificate is provided in several formats, because different entities that you communicate with, such as different browsers, may require different formats. The .pem files contain a format called PEM. This is a way of modifying a binary string so that the bit pattern in each byte coincides with an ASCII character, so that the string is printable and displayable as text. The .cer file contains a format called DER, which is not plain text.

The files provided in the private subdirectory are:

  • CAkey.pem - the CA's private key file. You can open this file in a text editor and see that the key is just one long number. In PEM format, it is preceded and followed by headers - these identify it as an RSA private key. It has been encrypted, by combining it with the pass phrase mentioned above. It appears as a string of characters.
  • CARootcert.pem - the CA's certificate in PEM format, the default for OpenSSL. In a text editor, the PEM-format certificate looks similar in layout to the key, but in fact a certificate has a complex structure. You can open the certificate file using the x509 command of the openssl utility. For example from the private subdirectory, enter:
    ..\openssl x509 -in carootcert.pem -text

    This shows the certificate first in human-readable form, and then in machine-readable form between the BEGIN CERTIFICATE and END CERTIFICATE lines. It shows that the public key was generated using the RSA algorithm and is 1024 bits long. The signature was created using the MD5 hashing algorithm and the RSA encryption algorithm. Notice that the Issuer and Subject are the same, because this is a self-signed certificate, as you would expect of a root CA's certificate.

  • CARootcert.cer - The CA's certificate in another format, P7B format, the default for Internet Explorer, which might be required because different browsers require different formats. You can view the certificate using the x509 command and the -inform parameter to specify that this certificate is in DER format. For example from the private subdirectory, enter:
    ..\openssl x509 -in carootcert.cer -text -inform DER

    Compare the x509 displays of the PEM and DER versions of this certificate, and notice that their contents are identical. However, you cannot display the DER one with a text editor.

The CAKey.pem and srvkey.pem files are installed with the same password "srvrootpwd". See Is the Demonstration CA a Real CA? for recommendations.

You should regard the contents of this private folder as sacrosanct. These are the public/private key pair that you must have in order to operate your CA. Do not alter or lose anything in here. Note that anyone who gets hold of your private key can masquerade as you. In production, you would take precautions such as making these files read-only, and keeping secure backups.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Your Distinguished Name and Policy

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you installed the Micro Focus Security Pack, you provided details of your site, such as Common Name, locality, and so on. All these details together are known as your Distinguished Name, and are intended to identify your site uniquely in the world. These details were put into your certificates.

Especially important is the Common Name. If this is not exactly the same as the fully qualified domain name of the machine running your SSL software, people you communicate with will get warnings that your certificate may not be valid. This field defaults to the name as known to your operating system, so you will probably not need to change it. You can however use wildcards in the Common Name, so you can use the same certificate for several machines. You will need to do this if, for example, you are running a Web site with a cluster of Web servers.

The elements of the Distinguished Name - Common Name, Locality, and so on - are standard, but it's up to you as the CA to have a policy on which of them you require. You can define the policy and specify the required elements, using the policy directive of the openssl ca function. You can specify several default groups of content within openssl.cnf and refer to each group by its name as a policy. See OpenSSL Configuration File.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Is the Demonstration CA a Real CA?


Is the Demonstration CA a Real CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

We strongly recommend that you do not use the demonstration CA to set up a commercial CA or other generally available CA service.

If you intend to set up a PKI within your organization, the demonstration CA is suitable software to use to run your real-life CAs. However, Micro Focus does not provide support for this use. As with any production software system, you must take great care to back up vital information and keep it secure.

The demonstration CA is suitable for creating certificate signing requests to be sent to a commercial or official CA.

Note:

The demonstration CA is installed with the same password "srvrootpwd" for the CA root private key CAkey.pem and the server private key Srvkey.pem files. We recommend that to ensure any form of real security you regenerate the demonstration CA content and recreate a server certificate.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy


Tutorial: Requesting and Issuing Server Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This tutorial shows how to request and issue server certificates, using the scripts supplied with the demonstration CA.

  • Introduction
  • Requesting a Server Certificate
  • Issuing a Server Certificate
Parent topic: Securing Communications


Introduction

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this tutorial, you first request a server certificate from the CA. Then you take the role of the CA and issue the requested certificate. To do this, you use the following scripts:

  • create_srv_req.cmd creates a request for a server certificate, using the OpenSSL command openssl req. It creates a public/private key pair for your server, putting the public key in a certificate request, which you subsequently send to the CA.
  • sign_srv.cmd, which processes a server certificate request created with the above script, and signs it using the openssl ca command. It creates a signed certificate, which contains the public key from the certificate request.

These scripts are supplied with Micro Focus Demo CA and are by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) after you have run the Micro Focus Demo CA installation.

Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Requesting a Server Certificate
Issuing a Server Certificate


Requesting a Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Prerequisites

Before you request a certificate, you must:

  • Install Micro Focus Demo CA. The installer for this is supplied with Visual COBOL, and by default is DemoCA_Setup.sh in $COBDIR/DemoCA.

In this section, you ask the certifying authority (CA) for a server certificate. As the server owner you create a private key and a public key. The public key is created in a certificate request (usually called a Certificate Signing Request, CSR) that you would send to the CA.

With a commercial CA, you would typically contact them first, learn about what types of certificates they supply, and find out their prices, terms and conditions.

  1. With administrative privileges, run the batch utility create_srv_req.cmd, located in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default.

    The batch file creates a public/private key pair for your server, and creates a certificate request with the public key, to send to the CA.

    The private key is generated first and is stored in srvkey.pem.

  2. At the prompt, enter a pass phrase. Use a pass phrase that is easy for you to remember and yet hard for others to guess, for example: open sesame You must supply this pass phrase to access your server's private key. You are prompted to confirm the pass phrase.
  3. The utility prompts you for the following details. These default to the values that you entered when you installed Micro Focus Demo CA:
    • Country Name
    • State or Province
    • Locality
    • Organization Name
    • Organizational Unit
    • Common Name

    For example, you can enter something like:

    Country Name: US
State or Province Name: California
Locality Name: Palo Alto
Organization Name: Bloggs Widgets Inc
Organizational Unit Name: Marketing
Common Name: svr-blogw
Email Address: bloggs@widgets.com

    The details you enter are included in your server certificate to identify you.

  4. At the A challenge password prompt, press Enter to ignore it. You can specify a pass phrase to protect your public certificate, but since it is a public certificate, it is seldom appropriate to protect it in this way.
  5. Press Enter at the next prompt also.
  6. When the batch file finishes, confirm that the following were created in the installation directory:
    • Your server's private key in srvkey.pem. You can view this in a text editor.
    • Your public key in a certificate request file called srvcertreq.csr. The CSR file is formatted according to the PKCS #10 standard, and is informally known as a PKCS #10 file, P10 file, or CSR file. You can view this using the req as follows:
      openssl req -in srvcertreq.csr -text
  7. In a real case you would now send srvcertreq.csr to the CA.
Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Introduction
Issuing a Server Certificate


Issuing a Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section, you issue the server certificate.

  1. Run the batch file sign_srv.cmd, which is in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default. When the batch file asks if you are ready, press any key.

    The batch file calls the ca command of the openssl utility to create a signed certificate, srvcert.pem, containing the public key from the certificate request.

  2. When you are prompted for the pass phrase, enter the CA pass phrase srvrootpwd. This confirms your right to access the CA private key file cakey.pem, and then displays the certificate request (from the CSR file srvcertreq.csr).
  3. When asked whether to sign the certificate, reply y twice.

    The certificate is then created and signed with your private key from cakey.pem. It is in PEM format. It is saved in srvcert.pem, with a copy in newcerts\01.pem. If this tutorial has been run before, and 01.pem already exists, the copy will be called 02.pem and so on.

  4. As before, view the certificate using the openssl command:
    openssl x509 -in newcerts\01.pem -text

    Notice that the Issuer is shown as the Distinguished Name of your Demo CA, while the Subject - the entity to whom the certificate has been issued - is the Distinguished Name of your server.

  5. Copy 01.pem from the newcerts directory to the certs directory, which is your Demo CA's database of certificates it has issued.
  6. In a real case the CA would now send srvcert.pem to the server owner to install it in their SSL software so that Web users can download it.
Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Introduction
Requesting a Server Certificate


Tutorial: Configuring SSL Security in the Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This tutorial shows how to configure SSL security in Enterprise Server.

  • Introduction
  • Creating a Secure HTTPS Listener
  • Installing the Server Certificate
  • Setting a Pass Phrase
  • Interpreting a Security Alert
  • Importing the CA's Root Certificate
  • Verifying the Certificate
  • Tidying Up
Parent topic: Securing Communications


Introduction

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this tutorial:

  • As the server administrator, you configure SSL security for Enterprise Server.

    You create an HTTPS listener and you install the server certificate and private key file that you created in the previous tutorial.

  • As an Enterprise Server user, you connect to the server from a Web browser. You install the CA's root certificate in order to access Enterprise Server.

    Typically, you rarely need to install CA root certificates. These are already configured for most trusted Certifying Authorities.

Note:

You must have completed the previous tutorial, Requesting and Issuing Server Certificates before you can run this tutorial.

In this tutorial, you configure the ESDEMO server to use secure communications. ESDEMO is created by the Enterprise Server installation. Within an enterprise server, you can create listeners for different kinds of communication.

One of ESDEMO's default listeners is HTTP Echo. This listener provides a simple test of Web communication. When a Web browser connects to HTTP Echo, the listener responds by sending a simple Web page with some identifying details.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Creating a Secure HTTPS Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the process that the server owner uses to configure an enterprise server to use SSL. In this tutorial, you create an HTTPS version of the HTTP Echo listener. You will use this listener in the stage: Interpreting a Security Alert

  1. Start Enterprise Server Administration, access the Home screen and make sure the ESDEMO enterprise server is stopped.
  2. For ESDEMO, click Edit > Listeners to access the Listeners page. Make sure the Process filter is set to All so you can see all the listeners.
  3. Click Add to create a listener for HTTPS.
  4. In the Name field, enter HTTPS Echo as the name.
  5. Change the Endpoint Address to *:9443.

    Although you can use port 443, it might already be in use. For example, IIS listens by default on port 443. If you want to use port 443, you can check whether it is in use, by running the following command:

    netstat -an | findstr 443
  6. Specify that this will be an "HTTP echo" listener, which provides a simple response to HTTP requests. To do this, select Custom under Supported Conversation Type and enter http-echo in the field alongside.
  7. In the Description field, type:
    Simple secure HTTP test
  8. Click Add.

On the Listeners page, the new entry for HTTP Echo appears.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Installing the Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section, as server administrator, you install the server certificate on the server so that remote Web users can request it. To install a certificate, you store the certificate and the key file in a folder accessible to your server software.

  1. Edit the new HTTPS Echo listener. To do this, select the new listener on the Listeners page and click Edit.
  2. Check Secure Sockets Layer.
  3. Enter the full path and filenames of your server certificate and private key in the Certificate and Keyfile fields. These are by default srvcert.pem and srvkey.pem, installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).
  4. Click OK.

    On the Listeners page, the entry for HTTP Echo now has a padlock symbol, which shows that it uses SSL.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Setting a Pass Phrase

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable the HTTPS listener to run, you need to enter the pass phrase that you defined for the private key file. In other situations, you might also have a pass phrase for the server certificate, which you would also need to enter. This tutorial does not require one.

There are two ways of setting the pass phrases. One way is to store the pass phrases in a file, and the other is to enter them once the enterprise server is started.

To set the pass phrase in a file:

  1. Edit the file mf-server.dat, located in $COBDIR/etc . If the file does not exist, create it.
  2. Add the following lines to mf-server.dat:
    [HTTPS Echo/SSL/passphrases]
certificate=
keyfile=open sesame

    It does not matter where in the file you add this section. If you like, you can add a comment (preceded by a ";") to describe the entry. Make sure the name HTTPS Echo is spelled exactly as it is in ES Admin.

    Note: If you are configuring the listener to start without a passphrase then use empty double quotes (keyfile="").
  3. Start ESDEMO from the home page of ES Admin.
  4. When ESDEMO has started, look at the Listeners page to make sure that the new listener HTTPS Echo has started, as with the other listeners.

To set the pass phrase manually without using a file:

  1. Start ESDEMO from the home page of ES Admin.
  2. When ESDEMO has started, go to the Listeners page. If you didn't enter the pass phrase in the above file, the status of the listener HTTPS Echo is Start Pending.
  3. Click Authorize in the Status column of HTTPS Echo. This displays the SSL Listeners page in a separate browser window.
  4. Enter open sesame in the Keyfile Passphrase field, then click Set passphrases. You can leave the Certificate Passphrase field blank, since you did not define a certificate pass phrase.
  5. Confirm that the HTTPS Echo is now started by viewing the main Listeners page (and clicking Refresh if necessary).

If you ever have problems starting or running an SSL-enabled listener, it can be useful to look at the MFCS log. Click Server > Diagnostics > CS Console.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Interpreting a Security Alert

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section as a user connecting to the server, you verify that you have connected to the correct Web site, and that it is trustworthy.

Since the Web site was certified by your Demo CA, you need your Demo CA's self-signed certificate installed in your browser in order for the Web site's certificate to be accepted. The necessary Demo CA's self-signed certificate is not installed, so that you can see the messages that this causes.

  1. In your browser, enter https://localhost:9443.

    This uses the secure version of HTTP Echo that you created in the stage Creating a Secure HTTPS Listener.

    You could enter your machine's actual DNS host name or even its dotted decimal IP address rather than localhost. Normally, it should make no difference, but for the purposes of this tutorial, use localhost.

  2. A Security Alert is displayed. It warns you that the Web site's security certificate may not be trustworthy, and it lists what is right and what is wrong with it.

    If this tutorial has already been run and the CA certificate is still installed, you do not get this alert. You can remove the certificate and then restart this section to display the alert.

  3. Close the security alert.

This security alert indicates that you have not installed the self-signed certificate of the CA that issued this server certificate.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Importing the CA's Root Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Browsers typically come with certificates for well-known CAs already installed, and you rarely need to install them. If you need a CA's root certificate, you can usually download it from the CA's Web site.

The demonstration CA's certificate is not pre-installed in your browser, so you need to install it. It is supplied in the private directory of the DemoCA directory. You install this certificate as follows:

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. In Internet Explorer, click Tools > Internet Options > Content > Certificates. Go to the Trusted Root Certification Authorities tab and click Import.
  2. Use the wizard to install the CA's self-signed certificate, which is in the private folder of your DemoCA directory. Specify the file CARootCert.cer. Internet Explorer requires X509 certificates, in DER format, so only those are listed, and not the PEM format files. Other browsers can handle several types, and so they may also be listed.
  3. Look down the list under Trusted Root Certification Authorities. You will see that your Demo CA is now listed; look for its Common Name. If when you installed Micro Focus Demo CA, you chose to use your computer DNS name as the DemoCA's Common Name, it will appear different to the rest, because real CAs tend to give themselves user-friendly Common Names.
Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Verifying the Certificate
Tidying Up


Verifying the Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Now that the CA's certificate is installed, you should be able to connect from the client Web browser.

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. Try to connect again. In the Web browser, enter https://localhost:9443.
  2. Read the security alert again. This time it shows only one problem, which is that the name in the certificate doesn't match the URL you tried to connect to. This is a warning that the certificate might not have come from the desired Web site, but from another Web site masquerading as it.
  3. Since this is in fact the desired Web site, click Continue to this website (not recommended) .

    The connection is made, and HTTPS Echo sends a page with identification details to your browser, confirming that the connection has been made successfully. It is normal for most of the strings to be empty, as shown.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Tidying Up


Tidying Up

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You should remove your Demo CA's self-signed certificate from your Web browser, both to avoid confusion in real use of your browser, and to enable this tutorial to be run again if required.

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. In Internet Explorer, click Tools > Internet Options > Content > Certificates.
  2. Click the Trusted Root Certification Authorities tab, locate your Demo CA's certificate (the Common Name, not the organization name), then remove it.
  3. Close the browser and re-open it.
Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate


Information on OpenSSL

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The openssl.exe utility is installed by default in the directory: /opt/microfocus/DemoCA/openssl or $COBSSL (if set). This directory is pointed to by the SSLDIR environment variable, which is created when you install this pack. The directory is not automatically added to your path, but you might find it useful to add it.

The openssl utility supplied with this pack is a full implementation of the utility, except that certain algorithms that are subject to patents or other legal restrictions have been excluded. See Supported Algorithms in the Readme for a list of the supported algorithms.

You can run openssl from the command line.

For details of the OpenSSL utility, see www.openssl.org and www.mkssoftware.com.

  • OpenSSL Utility
  • OpenSSL Configuration File
  • Algorithms
  • Interpreting OpenSSL Error Messages
  • Supported SSL Protocol Versions and Cipher Suites
Parent topic: Securing Communications


OpenSSL Utility

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The OpenSSL utility is installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

The OpenSSL utility supplied with this pack is a full implementation of the utility, except that certain algorithms that we believe to be subject to patents or other legal restrictions have been excluded.

To start the OpenSSL utility, run openssl from the command line.

Parent topic: Information on OpenSSL
Related information
Supported SSL Versions and Supported Algorithms
www.openssl.org
www.mkssoftware.com
OpenSSL Configuration File
Some Common Algorithms
Definitions for OpenSSL


OpenSSL Configuration File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The OpenSSL configuration file provides SSL defaults for items such as:

  • The location of your certificate files.
  • Your Distinguished Name. This comprises the details of your site (your Common Name, your locality and so on). Initially your Distinguished Name comprises the details you entered during installation.
  • Defaults for the openssl ca policy command, which specifies which elements of the Distinguished Name are required.

The configuration file is called openssl.cnf by default and belongs in the same directory as openssl.exe by default. You can specify a different configuration file by using the OPENSSL_CONF environment variable or you can specify alternative configurations within one configuration file.

The configuration file is a text file and comprises several sections, such as:

  • The ca section, which configures the CA. You can have several ca sections, each specifying a different configuration for a different CA, and switch between them by changing the default_ca option. You can also override this choice from the command line, using the -name parameter. This is useful in development and testing, enabling you to try out different configurations.
  • The policy section, which specifies how closely the Distinguished Name in a certificate presented to SSL software must agree with the Distinguished Name in an installed certificate, for the two certificates to be considered to match.
  • The req section, which configures the openssl req command.
  • The distinguished_name section, which specifies the Distinguished Name fields required when the openssl req command is creating a certificate request or a self-signed certificate. The actual name of this section is specified in the distinguished_name entry in the req section. This enables you to switch between different distinguished_name configurations, by changing the entry in the req section.
  • The attributes, which has attributes such as challengePassword or unstructuredName. Like the distinguished_name section, the actual name of the attributes section is specified in the req section, so that you can have several attributes sections, and switch between them.

In the options in the configuration file, all filenames must be given complete with absolute path.

For full details see OpenSSL CA function on the MKS Software site and page down to the section on the Configuration File .

If you receive a warning message like "WARNING: can't open config file: /usr/local/ssl/openssl.cnf" from the OpenSSL utility, set the environment variable OPENSSL_CONF to the location of a suitable openssl.cnf file. One is included with the Micro Focus DemoCA, in the main directory of the DemoCA installation. For example:

Windows:

set OPENSSL_CONF=C:\Program Files (x86)\Micro Focus\DemoCA\openssl.cnf

UNIX:

export OPENSSL_CONF=$COBDIR/DemoCA

Note: This message is only a warning; the openssl command may still perform the function you requested. The openssl.cnf file is primarily used to set default values for the CA function, key sizes for generating new key pairs, and similar configuration. Consult the OpenSSL documentation available at openssl.org for more information.

OpenSSL CA function openssl.org

Parent topic: Information on OpenSSL


Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can list the available algorithms using the openssl ciphers and openssl speed functions as follows. Note that not all the algorithms listed are supported. See below.

openssl ciphers

The openssl ciphers function lists the full cipher and hash suite available in the supplied openssl utility. Most of the ciphers available in OpenSSL are supported by Micro Focus Security Pack, but not all of them.

The openssl ciphers function produces output like this:

DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA:...

Where:

  1. The first element is the method
  2. The next one or more elements (except the last) are the ciphers and might indicate the symmetric and asymmetric ciphers
  3. The last element is the hashing algorithm used for signing

openssl speed

The openssl speed function lists the algorithms supported by the Micro Focus Security Pack and available in the supplied openssl utility. The speed function also lists how long each algorithm takes on your computer. This function takes some minutes to run.

Parent topic: Information on OpenSSL
Related information
Supported SSL Versions and Supported Algorithms
OpenSSL Utility
Some Common Algorithms


Interpreting OpenSSL Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

OpenSSL produces many error messages which are cryptic at times. This topic does not explain all the OpenSSL error messages, but it gives some guidance on how to interpret the messages.

Here is a typical OpenSSL error message that is caused by failing to set the SSLDIR environment variable to a directory containing openssl.cnf:

C:\Program Files\Micro Focus\DemoCA>openssl ca -revoke srvsert3.p12
Using configuration from /usr/local/ssl/openssl.cnf
error loading the config file '/usr/local/ssl/openssl.cnf'
3792:error:02001003:system library:fopen:No such process:.\crypto\bio\bss_file.c
:104:fopen('/usr/local/ssl/openssl.cnf','rb')
3792:error:2006D080:BIO routines:BIO_new_file:no such file:.\crypto\bio\bss_file
.c:107:
3792:error:0E064072:configuration file routines:CONF_load:no such file:.\crypto\
conf\conf_def.c:197:

The structure breaks down as follows:

  • Command line and parameters
  • Confirmation of configuration file to be used
  • Initial indication of error status
  • Low level code layer error information
  • Medium level code layer error information
  • Top level code layer error information

Within each code layer specific location information is given about what status was generated, within which source module and guidance as to the parameter that caused the error.

The important information is usually found in the final line. In this case the text “no such file” indicates the symptom of the failure. The file might no exist, but we might be looking in the wrong place and need to adjust the SSLDIR accordingly.

The OpenSSL Web site www.openssl.org has several relevant sections, in particular the HOW TO sections.

openssl dsa -in srvkey.pem -out keyout.pem
read DSA key
Enter PEM pass phrase:
unable to load Key
2588:error:06078081:digital envelope routines:EVP_PKEY_get1_DSA:expecting a dsa
key:.\crypto\evp\p_lib.c:241:
Parent topic: Information on OpenSSL
Related information
www.openssl.org
OpenSSL Configuration File


Supported SSL Protocol Versions and Cipher Suites

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA supports the following versions of SSL, in both client and server mode:

Protocol | Default state
SSL2 | Disabled (permanently)
SSL3 | Disabled
TLS1 | Enabled
TLS1.1 | Enabled
TLS1.2 | Enabled
TLS1.3 | Enabled

The following algorithms are supported:

  • AES-128 / 192 / 256
  • Blowfish CBC
  • CAST CBC
  • DES CBC / DES EDE3
  • DSA
  • HMAC(MD5)
  • MD2 / MDC2 / MD4 / MD5
  • SHA1
  • RMD160
  • RC2-CBC / RC4
  • RSA
  • SHA256
  • Camelia
  • SHA2 (224,256,384,512)
  • SHA3 (224,256,384,512)
  • CHACHA20 (TLS v1.3 only)
  • POLY1305 (TLS v1.3 only)
Parent topic: Information on OpenSSL


SSL and PKI Technology Primer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are new to securing communications, it is important that you understand the concepts of how communications are secured.

  • SSL
    This section gives an overview of the whole subject of SSL encryption.
  • CAs and PKIs
    This section describes CAs and PKIs.
  • Checking, Exporting and Importing Certificates Overview
    This tutorial talks through the certificates already installed on your machine, regardless of the Micro Focus Security Pack.
  • Certificates
    This chapter provides some background to certificates.
  • Standards and Organizations
    A great many standards have been created covering SSL and PKI, and as is often the way with new areas some of these standards are rivals or at least alternatives. This chapter briefly introduces the standards referred to in the coming chapters, and the organizations behind these standards.
  • Some Common Algorithms: Overview
    This topic names some of the best known encryption algorithms, and describes how to choose what algorithm to use.
  • Definitions for OpenSSL
    This topic briefly explains some terms that, while they are not part of SSL, often appear in discussions and documentation of SSL, especially of OpenSSL.
  • Attacks
    This topic explains some of the best known strategies for breaking a code, and what features SSL has that you can use to protect yourself from these attacks.
  • Designing a PKI
    This chapter advises on points to remember, ideas to consider, and pitfalls to avoid if you are designing a PKI for your organization. This is by no means an exhaustive list, but is intended to be helpful in suggesting points to consider.
Parent topic: Securing Communications


SSL

This section gives an overview of the whole subject of SSL encryption.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

For most of this section we'll assume, for simplicity, that you are the sender of messages and someone else is the recipient. In practice, of course, you're likely to be sending messages to each other, and so everything we describe is actually happening in both directions.

Throughout this explanation, we have taken care to say "your SSL software does so-and-so" not "you do so-and-so". This is partly to emphasize that all the detailed work is done by the software - as a user, or even as a programmer, of SSL-enabled software you generally just set options. It is also to emphasize that you must keep your computer secure, with such things as login passwords. If someone else can use your SSL software in your place, obviously all security is lost.

  • What is SSL?
  • SSL and TLS Terminology
  • Encryption and Decryption
  • Hashing
  • Signing
  • Certificates
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: What is SSL?


What is SSL?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SSL is a standard mechanism for sending and receiving electronic communications in encrypted form. SSL can be used wherever confidential information is to be sent between machines, such as a network, a company intranet, or the Internet. For brevity, this book generally talks about the Internet.

SSL is heavily reliant on the use of Public Key Infrastructures (PKIs). A PKI is a system of issuing online certificates to people and organizations involved in electronic communications - such as Web sites - to confirm their authenticity and trustworthiness.

SSL is widely used by organizations large and small. For example, if you use online banking, you may notice that the Web addresses - also known as universal resource locators (URL) - of many pages on your bank's Web site have addresses beginning https rather than http. This indicates that messages between that Web page and the Web site are sent via a version of HTTP that uses SSL.

Any two software programs that communicate with one another and have SSL support can send their messages to one another in encrypted form, provided that they also have a trust relationship with a PKI.

SSL can provide the following benefits:

  • Confidentiality – keeping information private
  • Integrity – ensuring information has not been tampered with
  • Authentication – confirming the identity of the individual who sent the information
  • Non-repudiation – proving that the individual who sent the information did so

Some of the above benefits are provided by PKIs that are used by SSL.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: SSL
Next topic: SSL and TLS Terminology


SSL and TLS Terminology

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SSL was originally defined by Netscape. The first publicly released version, SSL v2, came out in 1994. Several vendor-specific variants appeared, notably Private Communications Technology (PCT) from Microsoft. PCT was effectively a rival to SSL v3 when that came out in 1995. The Internet Engineering Task Force (IETF) took on the task of creating an industry-wide standard, and developed what was effectively SSL v3.1. However, they adopted for this the vendor-neutral name of Transport Layer Security (TLS). The terms TLS and SSL are sometimes used interchangeably. In this book we generally keep to the term SSL.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: What is SSL?
Next topic: Encryption and Decryption


Encryption and Decryption

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When software with SSL enabled sends a message, it sends it encrypted - that is, in a secret code. The software that receives the message, provided it too has SSL enabled and knows the secret code used, decrypts it - turns it back into the original uncoded message.

This gives you the first of the benefits of SSL mentioned above: confidentiality. If some unintended recipient - known as an eavesdropper, or attacker - picks up the message, they can't decipher it, because they don't know the code.

To encrypt a message, you need a key and an algorithm. A key is a number, and an algorithm is a method of combining this number with your message to create the encrypted message. To take a simple example, imagine you encrypt a message by replacing each letter by the letter two places farther along the alphabet, so that, for example, IBM becomes KDO. Here, "replace each letter by the letter n places farther along the alphabet" is your algorithm, and 2 is your key.

If you were to use a different key, you'd get a completely different code, although you're still using the same algorithm. So if for example n = 1, IBM becomes JCN.

  • Keys and Algorithms
  • Public Keys, Private Keys, and Secret Keys
  • Using Asymmetric and Symmetric Algorithms Together
Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: SSL and TLS Terminology
Next topic: Keys and Algorithms


Keys and Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Now it seems obvious that the intended recipient of your coded message needs to know the algorithm and the key, so as to decode the message; and equally it seems obvious that the algorithm and key must be kept secret from everyone else. And so you get the problem of how to let your intended recipient know them - after all, anyone who might be eavesdropping on your messages might be also eavesdropping when you send the algorithm and key.

Luckily, it's not as simple as that.

The algorithms typically used by SSL are so complex (typically taking several pages of mathematics to describe), and the keys used are typically so long (sometimes hundreds of digits long, when written in hex or decimal), that even if someone does know the algorithm, the chances of them guessing the key, or finding it by trial and error, are virtually nil. So, far from keeping algorithms secret, SSL uses well-known algorithms, which have been developed and published over the years by experts in cryptography.

When you are configuring software that uses SSL, it will generally ask you which of these well-known algorithms you want to use. Since the software does all the encryption/decryption for you, you don't need to understand these algorithms (you'd need considerable mathematical knowledge to do so), but you do need to know the names of the best-known ones and a little about their relative advantages and disadvantages. We'll cover this later. We'll mention some well-known ones as we go along.

You don't need to decide a key yourself, either. Instead, your SSL software uses a random number generator to create one.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Encryption and Decryption
Next topic: Public Keys, Private Keys, and Secret Keys


Public Keys, Private Keys, and Secret Keys

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As for keeping the key secret from all but your intended recipient, well, some of the well-known algorithms need two keys - and a message encrypted with one of the keys can only be decrypted with the other. So once you and your intended recipient have agreed which algorithm to use, your recipient's software generates a pair of keys, and sends you one (called his/her public key) while keeping the other one secret, even from you (this one is called his/her private key). Your software then encrypts and sends your message using the public key, and the recipient's software decrypts it using the private key.

So there's no danger of the private key being discovered by an eavesdropper - it never gets sent anywhere. It is known only to its owner.

As for the public key, there's no need to keep it secret. On the contrary, it can safely be made available to anyone who requests it. We'll come back later to how this is done.

An algorithm like this, using a private key and a public key, is called asymmetric. An algorithm that uses just one key, which has to be a secret between the sender and recipient, is called symmetric, and the key is called a secret key.

An algorithm that uses a private key and a public key is also called a public key algorithm. One of the best known ones is RSA, developed by Ron Rivest, Adi Shamir, and Leonard Adleman in 1977. An algorithm that uses just one key, a secret key, is called a secret key algorithm. One of the best known ones is Data Encryption Standard (DES), published as a US standard in 1977.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Keys and Algorithms
Next topic: Using Asymmetric and Symmetric Algorithms Together


Using Asymmetric and Symmetric Algorithms Together

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An asymmetric system has one major disadvantage - the algorithms are very complex and therefore very time-consuming. No matter how fast your computer is, you wouldn't want to use them to encrypt/decrypt large amounts of data.

So encryption software normally uses a symmetric algorithm on the data itself, meaning the secret key has to be sent to the recipient - but in case an eavesdropper intercepts the secret key, the software sends the secret key encrypted, using an asymmetric algorithm.

In this kind of system, the secret key is called a session key, since it is generated when the would-be sender and recipient first connect, sent using the asymmetric algorithm, and then used for all the data transmissions until the session is complete and the connection broken. A new secret key is generated for every new session.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Public Keys, Private Keys, and Secret Keys
Next topic: Hashing


Hashing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As explained in the chapter SSL, a hash is created by applying an algorithm that combines the characters of a message in some way to produce a string that is meaningless but nevertheless can be regarded as characteristic of the message - the chances of any other message, subjected to the same algorithm, giving the same hash are tiny.

It is neither necessary nor desirable that the hash should be unique; the algorithm should be such that the hash does not contain enough information to reconstruct the original message. So there actually will be other messages (though a tiny subset of the set of all possible messages) that would give the same hash. This important property of a good hashing algorithm is called irreversibility. Nevertheless, it should be difficult to deliberately create two messages that produce the same hash. This property is called collision-resistance.

Just as with encryption, there are various well-known algorithms used for hashing, and your SSL software may let you choose which it uses.

  • MD5
  • SHA
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

But imagine the following:

  1. You send a message, encrypted and accompanied by a hash.
  2. An hacker intercepts it and prevents it reaching your intended recipient.
  3. The hacker, pretending to be you, sends a new message, encrypted and accompanied by a hash.
  4. The recipient decrypts this, and finds the hash matches the hash he or she calculates, so believes he or she has received an uncorrupted message from you.

This is called a man-in-the-middle attack.

The solution to this is for your software to send the hash encrypted as well - but encrypted using your own private key. Since you have published your public key, the recipient's software will be able to decrypt the hash and use it. And the recipient can be sure it came from you, since only your software knows the private key that matches your public key.

A hash encrypted with your private key is called a digital signature.

So if you send a message signed in this way, the recipient knows it came from you. This is the third of the benefits of SSL mentioned above: authentication.

In fact, with a digital signature, your recipient can prove it came from you. If you should ever want to deny it, you can't. This is the fourth benefit mentioned above: non-repudiation. In some parts of the world, a digital signature has legal force, like a traditional hand-written signature.

Notice though that, unlike a hand-written signature, a digital signature is different every time - it is an encryption of the hash of the message it is attached to.

A similar idea to this is a message authentication code (MAC), which is a hash encrypted with the secret key of a symmetric algorithm. MACs are used instead of digital signatures to provide integrity, authentication, and non-repudiation in some systems.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Hashing
Next topic: Certificates


Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When asymmetric algorithms were first invented, it was suggested that people should publish their public keys in books like phone books. That idea didn't catch on. Instead, a new standard file type was invented, called a certificate.

A certificate contains its owner's public key and everyday elements of their identity such as their name, company, location, and the DNS host name of their computer. Your SSL software normally includes a function to create your certificate, but it's more usual to get an independent body, called a Certificate Authority, to create it. We'll go into this in the next chapter.

Anyone can have a certificate, and anyone needing to prove their identity online needs one. Notably, they are needed by organizations such as online banks and other Web sites that need clients or other organizations to communicate with them securely.

When you connect to such a Web site, the initial contact (called the handshake) between your SSL software and theirs includes their SSL software sending yours their certificate. This is how you get their public key, so that encrypted communication between you can begin, as described above.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Signing


CAs and PKIs

This section describes CAs and PKIs.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Two of the many well-known CAs on the Internet are VeriSign (http://www.verisign.com) and Thawte (http://www.thawte.com). You may find it useful to look at their Web sites from time to time while reading this chapter.

At this point we need to introduce the term "entity". A user of a network or intranet or the Internet might not be an individual person - it could be an organization, or even a machine. So we'll use the more general term "entity" from now on.

  • Trust
  • What is a CA?
  • What is a PKI?
  • Root and Subordinate CAs
  • How Do you Check a Certificate?
  • Certificate Validity Period and Revocation
  • Types of Certificates - Purpose
  • Authentication Modes
  • Typical Process
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Trust
Related information
Verisign
Thawte


Trust

Restriction: This topic applies only when the Enterprise Server feature is enabled.

So far, we've assumed that you and the people you communicate with know and trust each other. In real life, this is unlikely to be the case. On the Internet, or a big organization's intranet, you are one of a great many people, all potentially communicating with each other, and unlikely ever to know each other personally.

In the previous chapter, we introduced certificates as a way of making an entity's public key available to anyone who wants it.

To prove that the entity is trustworthy, an entity's certificate is created and digitally signed by someone who knows the entity personally, or at least is able to check up on them personally, and who is in turn trusted by others. In this way the certificate also serves - like a traditional paper certificate - as a proof of the entity's trustworthiness. SSL software includes a function to display a certificate on the screen so a user can check the details of the owner and the signatory.

And the person who signed the certificate can in turn have a certificate signed by a third person, and that person can in turn have a certificate signed by a fourth, and so on. Each certificate includes a record of this chain of certificates.

This is called a "web-of-trust model", and in a small organization it may be sufficient, since it's fairly easy to ensure that anyone checking a certificate will find someone he or she knows and trusts in the chain of signatories on the certificate. But it's not scalable; that is, it won't work for a big organization consisting of thousands of people mostly unknown to each other - and certainly not for the Internet.

The solution to this is a PKI, which we describe later in this chapter.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: CAs and PKIs
Next topic: What is a CA?


What is a CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Since you yourself can't possibly check up on all your contacts, you need someone who can - someone who can investigate entities, perhaps meet them in person, and then provide a statement to other entities that they are trustworthy. A Certification Authority (CA) is a body that does this. For an intranet, the CA might be a department within your organization. For the Internet, there are well-known CAs that provide this service.

  • How does the CA show it trusts an entity?
  • How does the CA check on entities?
  • Why should you trust the CA?
  • How do you know the certificate really came from the CA?
Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Trust
Next topic: How does the CA show it trusts an entity?


How does the CA show it trusts an entity?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

They issue certificates. Once they have satisfied themselves that an entity is genuine and trustworthy, they create a certificate as described above, containing the entity's public key, and the entity's identity details such as name, location, DNS host name, etc. They send this certificate to the entity to store, and keep a copy themselves.

The CA generally has a server dedicated to this function, and this machine is also known as the CA.

You can configure your SSL software to compare a received certificate to a list of known trusted CAs. As described above, you can also have your SSL software display a certificate on your screen for you to check the details.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: What is a CA?
Next topic: How does the CA check on entities?


How does the CA check on entities?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is an important point, and a CA will have a Certificate Policy (or Practice) Statement (CPS) explaining how they do it. Typically this is available on the CA's Web site for anyone to read.

This check is what anchors electronic communications to the real world. Typically it involves the entity, or its representatives if it is an organization, actually presenting themselves in person to the CA, with proof of identity. If this is not practicable because entities wanting certification are geographically wide-spread, the CA will have Registration Authorities, local branches that carry out the in-person checks and then forward approval to the central CA.

Again, the RA uses a server which is itself known as the RA. The connection between the RA and CA is likely to be an electronic one - the RA notifies its approval to the CA, which then issues the certificate. At both levels, though, there are likely to be actual human beings making the decisions to recognize the proofs of identity, and to grant the certificates.

If the entities wanting certification are too widespread even for RAs to be within reach of them all, then the CA may use notaries - individuals authorized to check identification in person and forward the details to the CA or one of its RAs.

All these policies should be detailed in the CA's CPS - this document and the policies it describes are as important a part of a PKI as the SSL technology itself.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: How does the CA show it trusts an entity?
Next topic: Why should you trust the CA?


Why should you trust the CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The above all depends on the CA themselves being trustworthy. Who gave them the right to check identities and issue certificates pronouncing people trustworthy?

For the intranet of a company or other organization, the CA is likely to be a department set up at the management's direction. For the Internet, a number of privately run CAs have been established, which have become widely trusted simply because they have earned a world-wide reputation.

To maintain its reputation, a CA would be expected to keep its CA server extremely secure, not only from hackers, but also from physical on-site interference, to ensure that certificates cannot be created other than by the official route. If you read a CA's CPS, you should expect to find strict, detailed rules about physical access to the server by the CA's staff.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: How does the CA check on entities?
Next topic: How do you know the certificate really came from the CA?


How do you know the certificate really came from the CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

They sign it.

In addition to the data described earlier (the public key, name , etc of the certified entity), a certificate contains the CA's digital signature. As described earlier, this provides proof - in some countries, legal proof - that it came from the CA.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: Why should you trust the CA?
Next topic: What is a PKI?


What is a PKI?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A PKI is the whole system described in the preceding sections - one or more CAs, their procedures (defined in their CPS's) for vetting applicants for certificates, and for handling and issuing certificates, and the SSL software used by entities to send, receive, and check certificates.

The Internet has, in effect, its own world-wide PKI, based around internationally known CAs such as Thawte, VeriSign and others. An organization, such as a company, can set up its own PKI for use within its intranet or network.

The same SSL software and world-wide standards (such as certificate formats) would normally be used in either case. The principal distinction between the world-wide PKI and a private one is that in a private one the organization would set up its own CAs, recognized within the organization.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: How do you know the certificate really came from the CA?
Next topic: Root and Subordinate CAs


Root and Subordinate CAs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If there were only a few CAs in the world, they would soon become overloaded. In fact, there are many. But how does a new CA show its trustworthiness? Usually, by applying for and being granted a certificate from one of the established CAs. A CA certified by another is called a subordinate CA.

A CA that is not certified by any other, but relies solely on its own reputation, is called a root CA. Even a root CA needs a certificate (we'll see below why), and the format of a certificate requires that it be signed, so they create and sign their own certificate. This is called a self-signed certificate or a root certificate.

Similarly, in a large organization, there might be subordinate CAs - for example, each department might run its own CA, each certified by the organization's root CA.

Also, a big CA such as those on the Internet might find that to cope with demand they need several CA machines. Each of these is a subordinate CA, with a certificate granted by one root CA machine.

A subordinate CA can itself certify subordinate CAs, so the standard format for a certificate includes a record of a chain of CAs, each certified by the next, back to a root CA. This chain of certificates is called the certification path. Thus a PKI is hierarchical. You trust the certificate if you know and trust any of the CAs on the certification path.

So in contrast to the web of trust described earlier, a PKI is a tree of trust, with one or more root CAs at the top, subordinate CAs below them and the actual users (client or server) at the bottom.

In a minor departure from this hierarchical nature, CAs can also cross-certify each other. For example, two government departments might each have its own PKI, with its own CA. Within each department, every member has been vetted and then certified by the relevant CA. They might then find that members of the two departments frequently need to communicate with each other. To establish trust between all the members of the two departments, effectively linking the two PKI's into one, all that is needed is for the two CAs to grant each other certificates.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: What is a PKI?
Next topic: How Do you Check a Certificate?


How Do you Check a Certificate?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

We said above that the SSL software compares a certificate to a list of known CAs. We'll describe more precisely what happens.

A CA itself has a certificate - a self-signed one in the case of a root CA. Your SSL software can store certificates (known as installing a certificate), and typically comes with the certificates of a number of well-known CAs already installed. You can install more, if you come across more CAs you wish to trust. Also, might provide automatic updates that install additional CA certificates in Internet Explorer.

When your SSL software receives an entity's certificate as part of a handshake, it compares the hierarchy of CAs named in the certificate to the installed CA certificates. If any in the hierarchy matches any in the installed list, then the entity is considered to have been certified by a known and trusted CA.

Your SSL software also needs to check that the CA's digital signature in the entity's certificate is genuine. Remember that to check a digital signature your SSL software decrypts it using its owner's public key, and then compares the resulting decrypted hash with the hash that the SSL software has itself worked out from the message (in this case the entity's certificate). The SSL software obtains the CA's public key from the CA's certificate.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Root and Subordinate CAs
Next topic: Certificate Validity Period and Revocation


Certificate Validity Period and Revocation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Optionally, a certificate can contain start and end dates, when it starts and ceases to be valid. End dates are especially common, since most CAs consider it good policy to require a certificate to be renewed from time to time. Not only does it enable them to check that the holder is still genuine, but it enables them to charge for renewing the certificate.

It is sometimes necessary for a CA to revoke a certificate, for example if the holder's matching private key is lost or revealed, or if the CA ceases to consider the holder trustworthy. There are two ways a CA can do this. Both have shortcomings.

The first is to maintain a certificate revocation list (CRL), which it makes remotely accessible. A CRL can be installed in SSL software, for example in a browser, and when the SSL software is examining a certificate to see if it is trustworthy, part of the procedure is to see if the certificate is on any of the installed CRLs.

This approach has the problem that CA updates are issued periodically, so there is a delay between a CA deciding to revoke a certificate and the fact appearing in the latest issue of the CRL.

A more recent solution is for the CA to provide online certificate status - meaning that SSL software checking a certificate can contact the CA's server online and get a signed response saying whether the certificate has been revoked. The Online Certificate Status Protocol (OCSP) has been introduced for this.

This approach has the problem that it puts a high load on the CA's server.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: How Do you Check a Certificate?
Next topic: Types of Certificates - Purpose


Types of Certificates - Purpose

Restriction: This topic applies only when the Enterprise Server feature is enabled.

CAs issue different kinds of certificates, differing in what kind of checks the CA has made on the owner and consequently what purpose the certificate serves - in what roles it guarantees the owner as trustworthy. For example:

  • Typically, a CA issues its own root CA machine with a self-signed root certificate
  • If you are the owner of a Web site accessed by the general public, you can request a server identification certificate (server certificate for short), confirming to your clients the identity of your server
  • If you are engaged in business-to-business communications (B2B), you will probably want a client certificate, confirming the identity of your site

Exactly what the certificate certifies - in other words, its purpose - is stated in the certificate.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificate Validity Period and Revocation
Next topic: Authentication Modes


Authentication Modes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a client/server scenario, it may be that only the server has a certificate, so that the clients can confirm the identity of the server; or it may be that clients too are required to have certificates, so that the server can identify their identities.

If only the server has a certificate, the online service is said to be operating in server-only authentication mode. If the clients too have certificates, the service is operating in full authentication mode.

If as a Web site owner you want the benefits of non-repudiation, that is, you want to be able to prove that data really was sent to you from a particular client, then you should use full authentication.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Types of Certificates - Purpose
Next topic: Typical Process


Typical Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Here's a brief, simplified overview of what typically happens when you contact a secure Web site, that is, one using SSL. Let's say you are a Web user contacting your online bank.

In the following, remember that a symmetric algorithm is normally used to encrypt the data itself, while an asymmetric algorithm is used only to send the secret key for the symmetric algorithm.

In the following, we refer to "your browser" and "the bank's server". Of course we mean the SSL software in each.

  1. You enter the URL of the bank's login page.
  2. Your browser sends a list of symmetric algorithms it can support to the bank's server, and requests the bank's certificate.
  3. Their server replies saying which symmetric algorithm to use, and sends the requested certificate. It also sends a random number to be used in generating the secret key.
  4. Your browser checks the hierarchy of CAs shown in the bank's certificate against the CA certificates you've got installed. If there is no match, the browser flags a warning.
  5. If there is any match, the browser checks the bank's certificate against the CA that issued it, typically making the following checks and flagging a warning if any fail:
    • Checks the CA's digital signature in the bank's certificate.

      Remember this signature is the encrypted hash of the bank's certificate - encrypted using the CA's private key. Your browser gets the CA's public key from the CA's certificate, and uses it to decrypt the signature, thus getting back the hash. Your browser then itself hashes the bank's certificate, and checks the two hashes match.

    • Checks the start and expiry dates in the certificate to confirm the certificate is current.
    • Checks the URL in the certificate is exactly the same as the URL DNS name of the machine that sent the Web page.
    • Checks in the CA's certificate revocation list (CRL), or contacts the CA's server using OCSP, to see if the certificate has been revoked.
  6. Your browser generates a random number, encrypts it with the asymmetric algorithm using the bank's public key, and sends it to the bank's server.
  7. The bank's server uses the bank's private key to decrypt the random number the browser sent.
  8. Your browser and the bank's server now independently calculate the secret key from the two random numbers.
  9. As a final check, your browser and the bank's server send each other MACs of all the above messages, and check them to ensure no attacker has altered any of the messages.
  10. Your browser and the bank's server can now send each other your data confidentially, using the chosen symmetric algorithm.
Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Authentication Modes


Checking, Exporting and Importing Certificates Overview

This tutorial talks through the certificates already installed on your machine, regardless of the Micro Focus Security Pack.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Viewing Certificates
  • Checking a Certificate
  • Exporting a Certificate from Internet Explorer
  • Importing a Certificate into Mozilla Firefox
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Viewing Certificates


Viewing Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are probably some certificates already installed on your machine. Applications that use SSL, such as a Web browser, usually come with certificates for well-known Web sites and CAs. New certificates for Web sites with newly established reputations are often included in the regular updates that are published for the applications.

  • With Internet Explorer
  • With Mozilla Firefox
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Checking, Exporting and Importing Certificates Overview
Next topic: With Internet Explorer


With Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Internet Explorer:

  1. Click Tools > Internet Options > Content.
  2. Click Certificates and then the Trusted Root Certification Authorities tab on the far right.

    This lists the root CAs known and trusted by your Web browser - that is, the CAs whose certificates have been installed in the SSL software in your Web browser. A default set of these, consisting of many of the world's best known ones, is installed when Internet Explorer is installed.

    The terminology used in Internet Explorer is slightly different from that used in this book, as follows:

    Internet Explorer | This book
    Personal certificate | Your client certificate
    Other people's | Client or server certificate of some other entity
    Intermediate CA | Subordinate CA
    Trusted root CA | Root CA
  3. Double-click any one of the certificates shown. This displays the certificate on the screen. In many cases the "Issued To" and "Issued by" names are the same, indicating a self-signed certificate - one issued by a root CA to itself.
  4. Double-click one of the certificates. This displays the certificate. Notice that the "Issued To" and "Issued by" names are the same. This is what you would expect from a self-signed certificate - one issued by a root CA to itself.
  5. Click the Certification Path tab. This lists the chain of CAs from the certificate back to the root CA. Because this certificate is for a root CA, there is just one entry.
  6. Click OK to close the certificate.
  7. Click the Intermediate Certification Authorities tab. This shows a list of subordinate CAs whose certificates have been installed in your Internet Explorer.
  8. Double-click one of the certificates.
  9. Click Certification Path. You now see the chain of CAs, from the subordinate CA that issued this certificate, back up through the hierarchy to the root CA.
  10. Close the dialog boxes.
Parent topic: Viewing Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Viewing Certificates
Next topic: With Mozilla Firefox


With Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Mozilla Firefox:

  1. Click Tools > Options > Advanced. Then, depending on your version, either scroll down and click Manage Certificates, or click the Security tab and then View Certificates.
  2. Click the Authorities tab. This lists the CAs known and trusted by your Web browser - that is, whose certificates have been installed in the SSL software in your Web browser. A default set of these, consisting of many of the world's best known ones, is installed when Firefox is installed.
  3. Double-click any one of the certificates shown. This displays the certificate on the screen. In many cases the "Issued To" and "Issued by" names are the same, indicating a self-signed certificate - one issued by a root CA to itself.
  4. Click the Certification Path tab. This lists the chain of CAs from the certificate back to the root CA. If this certificate is for a root CA, there is just one entry.
  5. Click OK to close the certificate.
  6. Look at some other certificates in the same way. You may find that all the certificates are for root CAs. If you find one for a subordinate CA, you can see the chain of CAs, from the subordinate CA that issued this certificate, back up through the hierarchy to the root CA.
  7. Close the dialog boxes.
Parent topic: Viewing Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: With Internet Explorer
Next topic: Checking a Certificate


Checking a Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Frauds have sometimes been perpetrated in which fake Web sites masquerade as genuine sites - when you think you are connecting to the genuine site, for example your online bank, you are in fact diverted to a fraudulent one designed to look like it, and trick you into revealing your confidential details. This kind of fraud is called "phishing".

As a safeguard against this, you can view the certificate of the site you are connecting to.

  • With Internet Explorer
  • With Mozilla Firefox
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: With Mozilla Firefox
Next topic: With Internet Explorer


With Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Internet Explorer:

  1. Go to the Web site for any online entity that needs secure communications, such as an online bank.
  2. Follow the links to the first logon page. You do not need to logon.
  3. Look at the URL. You should find that it begins with https instead of http. HTTPS is Secure HTTP, the version of HTTP that uses SSL.
  4. Look at your Web browser's status line. You should see a symbol like a padlock. This shows that communications on this page use SSL.

    Some pages contain both secure (that is, encrypted) and insecure (unencrypted) information. If you view such a page, your browser might display a warning to this effect, and ask you if you want to continue. If you choose to continue, the padlock symbol disappears, because Internet Explorer does not treat such pages as secure. You will need to try some other HTTPS page to continue with this tutorial.

  5. Double-click the padlock symbol. This displays the entity's certificate.

    Click the Certification Path to show the hierarchy of CAs from the one that issued the certificate up to the root CA.

    A Web site that was masquerading as the one you believe you've contacted could not fake a certificate, because no reputable CA, having checked up on them, would sign a certificate for them. And since the list of CAs in your browser includes only genuine, reputable CAs, there will be no match and your browser will reject their certificate.

    However, even for the most respectable organizations, you will sometimes find warning messages on the General tab saying that in some respects the certificate is faulty. This is because some detail on the certificate is incorrect - for example, the expiry date may have passed. It is up to you to look at the details on the certificate, and decide whether you trust the Web site despite this flaw.

Parent topic: Checking a Certificate
Parent topic: SSL and PKI Technology Primer
Previous topic: Checking a Certificate
Next topic: With Mozilla Firefox


With Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Mozilla Firefox:

  1. Go to the Web site for any online entity that needs secure communications, such as an online bank.
  2. Follow the links to the first logon page. You do not need to logon.
  3. Look at the URL. You should find that it begins with https instead of http. HTTPS is Secure HTTP, the version of HTTP that uses SSL.
  4. Look at your Web browser's status line. You should see a symbol like a padlock. This shows that communications on this page use SSL.

    Some pages contain both secure (that is, encrypted) and insecure (unencrypted) information. If you view such a page, your browser should display a warning to this effect, and ask you if you want to continue. If you choose to continue, the padlock symbol appears with a line through it, because Firefox does not treat such pages as secure. You can still view the certificate though.

  5. Double-click the padlock symbol.
  6. On the Page Info dialog box that appears, click View. This displays the entity's certificate. If you click the Details tab, you will see the hierarchy of CAs from the one that issued the certificate up to the root CA.

    A Web site that was masquerading as the one you believe you've contacted could not fake a certificate, because no reputable CA, having checked up on them, would sign a certificate for them. And since the list of CAs in your browser includes only genuine, reputable CAs, there will be no match and your browser will reject their certificate.

    However, even for the most respectable organizations, you will sometimes find warning messages on the General tab saying that in some respects the certificate is faulty. This is because some detail on the certificate is incorrect - for example, the expiry date may have passed. It is up to you to look at the details on the certificate, and decide whether you trust the Web site despite this flaw.

Parent topic: Checking a Certificate
Parent topic: SSL and PKI Technology Primer
Previous topic: With Internet Explorer
Next topic: Exporting a Certificate from Internet Explorer


Exporting a Certificate from Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To export a certificate from Internet Explorer in the appropriate format, ready for importing into Firefox:

  1. In Internet Explorer click Tools > Internet Options.
  2. Go to the Content tab and double-click Certificates.
  3. Go to the Trusted Root Certificate tab and find the certificates marked Verisign Trust Network. There are several notable features of these certificates:
    1. There are multiple certificates and each one is unique.
    2. These different types of certificates are used to confirm the trust of different types of identification certificates.
    3. Some of these certificates have passed their expiry date. However they are still valid and should be present to prove the trust path for certificates that were signed during their working life span.
    4. Some of these certificates are direct replacements for expired or about-to-expire certificates.
    5. The life of the replacement certificates is typically far longer than that of the original certificates. Replacing certificates is problematic as it involves a significant amount of manual work and therefore distribution that is not often undertaken. To avoid the distribution complication it is in the interest of all identification certificate users to use certificates with a long life.
  4. Select a certificate and click Export.
  5. In Certificate Export Wizard, click Next.
  6. You choose the format required by your target browser. If you don't know the format required, you can generate a few of the most common formats and save them to different files, so that the correct format is available.

    Select DER encoded binary X.509 and click Next.

  7. Specify the /opt/microfocus/DemoCA/openssl/Verisign as the name of the file to export to and click Next.
  8. On the final screen notice:
    • Export Keys is always "No” when handling CA root certificates.
    • Include all certificates in the certification path is always “No” when using file formats that cannot support multiple certificates. When using a server certificate signed by an intermediate CA you would usually export the complete chain of trust back to the fully trusted CARoot. In this case we would have chosen a different format at step 6.
    • File Format should match the filename extension in most cases,. Although there are times when various subformats such as .p7b and .p7c are interchanged to aid portability of the generated output file.
  9. Click Finish > OK and the file appears in the chosen directory.
  10. Close all the open IE dialog boxes.
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: With Mozilla Firefox
Next topic: Importing a Certificate into Mozilla Firefox


Importing a Certificate into Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In Firefox, go to Tools > Options.
  2. Go to the Advanced tab and the Security sub-tab and click View Certificates.
  3. Go to the Authorities tab and click Import. Note that different tabs show different files without an extension indicating that they are native format
    • Files with a .p12 extension are shown without the extension when you import from the Your Certificates tab
    • Files with a .cer are shown without the extension when you import from the other certificate type tabs

    This emphasises the value of understanding how the different types of certificate usage affect the type of file being used to transport a certificate. Other certificate stores may have different rules about formats. It is worth investigating they destination locations requirements before attempting to create certificate files for their use.

  4. Specify the file that you exported from Internet Explorer.

    A message should popup telling you that this certificate already exists. This confirms that file was correctly formatted and read by the import tool.

Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Exporting a Certificate from Internet Explorer


Certificates

This chapter provides some background to certificates.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Certificate and Key Formats
  • Don't Edit Certificates and Key Files
  • To Convert Certificate Formats
  • 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Certificates are often known as X.509 certificates, since X.509 is the standard that defines their context and layout. The commonest algorithms for creating public and private keys are RSA and DSA, and keys are often referred to as RSA keys or DSA keys. None of these, however, define the format of the file in which a certificate or key is held. There are many rival formats for these files. Some of the commonest standard formats are:

  • DER. This format can contain private keys (RSA or DSA), public keys (RSA or DSA) and X.509 certificates. It is headerless. It is the default format for most browsers. A file can contain only one certificate. Optionally the certificate can be encrypted. The standard extension is .cer, but might be .der in some installations.
  • PEM. This format can contain private keys (RSA or DSA), public keys (RSA or DSA) and X.509 certificates. It is the default format for OpenSSL. It stores the data in either ASN.1 or DER format, surrounded by ASCII headers, so is suitable for sending files as text between systems. A file can contain multiple certificates. The standard extension is .pem.
  • PKCS #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: Don't Edit Certificates and Key Files


Don't Edit Certificates and Key Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You must never edit the contents of a certificate or keyfile. If you change anything within a certificate, any SSL software examining the certificate to authenticate your identity will detect it has been tampered with and declare it invalid.

A keyfile, and in certain circumstances a certificate file, will always be protected by its own security pass phrase. This pass phrase prevents certificate and key file management tools from making unauthorized access to the file content.

Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificate and Key Formats
Next topic: To Convert Certificate Formats
Related information
Certificates


To Convert Certificate Formats

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To convert certificate formats, use openssl.exe, as follows:

  • To convert binary-only PKCS7 (.p7 .p7a .p7b .p7c) files as output from Windows Internet Explorer Certificate Manager, with single or multiple certificate content, and generate human readable text content in the output file:
        openssl pkcs7 -inform DER -in filename.p7b -text -print_certs -out outfilename.pem

    For example:

    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem
  • To convert binary-only PKCS7 files as output from Windows Internet Explorer Certificate Manager, with single or multiple certificate content, and generate only binary content in the output file leave out the “-text” element:

openssl pkcs7 -inform DER -in filename.p7b -text -print_certs -out outfilename.pem

    Example:

    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem

    When handling many certificates in one file you might encounter issues of space being taken for the descriptive text content. In these circumstances you may wish to remove the text content, however this is not recommended for normal use as it make handling of the certificates harder because their content is not immediately viewable.

    Some applications do not accept X509v3 certificates when accompanied by a text description within the certificate file. You can overcome this for most applications, by editing the certificate to trim the text sections, but take care to leave intact the lines beginning and terminating the binary certificate data.

  • To convert PEM to PKCS#12 (to install in a Web browser or for storage):
    • If your PEM-format certificate and key are both in one file, use:
      openssl pkcs12 -export -in pem-cert-and-key-file -out pkcs12-cert-and-key-file
    • If they are in separate files, use:
      openssl pkcs12 -export -in pem-cert-file -inkey pem-key-file -out pkcs12-cert-and-key-file

    Both these commands put the certificate and keyfile into one file. If you intend to store your private key and certificate together in this fashion you should apply a pass phrase to the resultant file.

  • To convert PKCS#12 to PEM:

    • openssl pkcs12 -in pkcs-12-cert-and-key-file -out pem-cert-and-key-file
  • To convert ASN.1 PEM files to DER PEM :
    • If the PEM file contains DSA keys, use:
      openssl dsa -inform PEM -outform DER -in pem-file -out der-file
    • If it contains RSA Keys, use:
      openssl rsa -inform PEM -outform DER -in pem-file -out der-file
  • To convert DER (.cer in most implementations) to PEM:
    • If the DER file contains DSA keys, use :
      openssl dsa -inform DER -outform PEM -in der-file -out pem-file
    • If it contains RSA Keys, use:
      openssl rsa -inform DER -outform PEM -in der-file -out pem-file
Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Don't Edit Certificates and Key Files
Next topic: Multi-Certificate files


Multi-Certificate files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • X.509
  • PKCS Standards
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: X.509


X.509

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The most important standard for PKI's is X.509, which defines the format and content of digital certificates and how to validate them. It is an International Telecommunications Union (ITU) Recommendation, published as ITU-T X.509 and ISO/IEC/ITU 9594-8.

Standards are still evolving, and different companies have implemented it in different ways. For example, Netscape and Microsoft both use X.509 certificates in their Web servers and browsers, but an X.509 certificate created by Netscape may not be readable by Microsoft products, and vice versa.

Parent topic: Standards and Organizations
Parent topic: SSL and PKI Technology Primer
Previous topic: Standards and Organizations
Next topic: PKCS Standards


PKCS Standards

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There is a set of de facto cryptographic message standards called Public Key Cryptography Standards (PKCS) which were originally developed and are still maintained by RSA Laboratories. (For more detailed information, see the Web page at RSA Laboratories.

The standards that are most relevant to PKI are:

  • PKCS #7, Cryptographic Message Syntax Standard. A general syntax for data to which cryptography can be applied, such as digital signatures and encryption. It also provides a syntax for disseminating certificates or certificate revocation lists (CRLs).
  • PKCS #10, Certification Request Syntax Standard. Provides a format for a request for a certificate.
  • PKCS #12, Personal Information Exchange Syntax Standard. Primarily provides a format for storing keys or a certificate in a file.
Parent topic: Standards and Organizations
Parent topic: SSL and PKI Technology Primer
Previous topic: X.509
Related information
RSA Laboratories


Some Common Algorithms: Overview

This topic names some of the best known encryption algorithms, and describes how to choose what algorithm to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Algorithms and Key Lengths
  • Choosing an Algorithm
  • Symmetric Algorithms
  • Asymmetric Algorithms
  • Hashing
  • Digital Signatures
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Algorithms and Key Lengths


Algorithms and Key Lengths

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Two things that your SSL software may let you choose are the algorithm and the key length to be used for encryption. One thing to consider in choosing is how easy the code will be to crack.

In general, for the same algorithm, the longer the key the harder the code is to break. This is simply because a would-be attacker can easily use a computer to try key after key until hitting on the right one. The longer the key, the longer it takes to generate all possible numbers of that length, looking for the right one. You need a key that is so long that even with the most powerful computers this would take an impracticably long time.

Of course, computers are constantly becoming more powerful. Therefore, the length of key considered necessary is constantly increasing as the years pass. 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In choosing which algorithm to use, there are several factors to consider.

Cryptography, the invention of new algorithms and of ways to break the codes they create, is a branch of mathematics that is constantly advancing. Attempts to crack a particular algorithm are often undertaken by serious researchers anxious to confirm whether the algorithm is really secure.

It may be possible for an expert cryptographer to find a mathematical way of breaking an algorithm, or it may be vulnerable to a "brute force" attack - just trying different keys until the correct one is found.

Just because an algorithm has been cracked in the past does not necessarily mean you must not use it - you should consider whether your data is valuable enough to tempt a hacker to devote the resources that have been shown to be needed to crack it.

Two problems with all symmetric algorithms are that the key has to be known to both sender and receiver, and so it could be intercepted when being sent from one to the other; and that if the same key is used for all your messages, any eavesdropper who finds out the key can decrypt all your messages.

Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Algorithms and Key Lengths
Next topic: Symmetric Algorithms


Symmetric Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section we briefly describe some of the best-known symmetric (secret key) algorithms.

A symmetric algorithm that treats the message to be encrypted as a continuous stream of bits is called a stream cipher. A symmetric algorithm that splits the message up into chunks and encrypts each chunk is called a block cipher. The only stream cipher to have been widely used is RC4.

  • RC4
  • DES
  • Triple DES
  • AES
  • Blowfish
  • Twofish
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Choosing an Algorithm
Next topic: RC4


RC4

Restriction: This topic applies only when the Enterprise Server feature is enabled.
RC4 was designed by Ron Rivest of RSA Security in 1987. It stands for "Rivest Cipher 4", or alternatively for "Ron's Code". RC4 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

One of the most well-known secret key algorithms is the US Data Encryption Standard (DES). It was published in 1977. In the past the US government encouraged users to adopt this as the main or only secret key algorithm in use. In 1998, it was shown that a dedicated hacker with moderate computer power can crack it (see EFF DES cracker project), but it is often considered secure enough for some trivial uses. It is to be replaced as a US standard by the Advanced Encryption Standard (AES).

DES uses a fixed key length of 64 bits. Of these, 8 are used for parity, so in effect the key is 56 bits long.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A variation on DES is simply to encrypt the message three times in succession, using DES. One long key is split into three shorter keys, one for each encryption, so the overall key length is three times that of regular DES. Triple DES is usually written as 3DES. It is considered secure enough for most uses

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: DES
Next topic: AES


AES

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is US standard FIPS-197, and is designed as a replacement for DES. It uses an algorithm designed by Joan Daemen and Vincent Rijmen (see csrc.nist.gov/CryptoToolkit/aes/rijndael/Rijndael-ammended.pdf, and known as the Rijndael algorithm.

AES is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Triple DES
Next topic: Blowfish
Related information
csrc.nist.gov/CryptoToolkit/aes/rijndael/Rijndael-ammended.pdf


Blowfish

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This was developed by Bruce Schneier of Counterpane Labs. It is used in a great many products, and is standard in the OpenBSD operating system. For details see www.counterpane.com/blowfish.html.

Blowfish is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: AES
Next topic: Twofish
Related information
www.counterpane.com/blowfish.html


Twofish

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This too was developed by Bruce Schneier, and is efficient when implemented in hardware and smart cards. For details see www.counterpane.com/twofish.html.

Twofish is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Blowfish
Next topic: Asymmetric Algorithms
Related information
www.counterpane.com/twofish.html


Asymmetric Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The two best known asymmetric (public key) algorithms are D-H and RSA.

  • Diffie-Hellman (D-H)
  • RSA
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Twofish
Next topic: Diffie-Hellman (D-H)


Diffie-Hellman (D-H)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Whitfield Diffie and Martin Hellman were the first to show, in a paper published in 1976, that a code could be devised that was encoded using one key and decoded using another.

James Ellis wrote a paper in 1970 on similar work done by himself and Clifford Cocks, but it was covered by the UK's Official Secrets Act, and was not published until many years later.

Using the Diffie-Hellman (D-H) algorithm, one key is specifically for encryption and the other for decryption - you can't use them the other way around. This makes it unsuitable for a PKI system as normally used.

Parent topic: Asymmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Asymmetric Algorithms
Next topic: RSA


RSA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

It was Ron Rivest, Adi Shamir, and Leonard Adleman who later developed an algorithm where you could use either key to encrypt. This is known as the RSA algorithm. This made possible the full use of asymmetric encryption for the purposes we have discussed - certificates, non-repudiation, etc, as well as confidentiality - and thus made PKI systems possible.

Parent topic: Asymmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Diffie-Hellman (D-H)
Next topic: Hashing


MD5

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is probably the most commonly used hash function. It produces a 128-bit hash. It has largely superseded earlier MD functions (for example, MD2, MD4). It is defined in RFC1321.

MD5 has been shown to be vulnerable to collisions in some applications. 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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Secure Hash Algorithm (SHA) is a US standard, developed by the National Institute of Standards and Technology (NIST). SHA-1 is a revised version, published in 1994. It produces a 160-bit hash, which is more secure than MD5's 128-bit hash. It is defined in RFC3174 .

There are several further revisions of SHA, described on the NIST Web site at www.csrc.nist.gov/cryptval/shs.htm.

It is expected that a revision of SHA will replace MD5 as the most popular hashing algorithm.

Parent topic: Hashing
Parent topic: SSL and PKI Technology Primer
Previous topic: MD5
Next topic: Digital Signatures
Related information
RFC3174
www.csrc.nist.gov/cryptval/shs.htm


SHA2

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As explained earlier, a digital signature on a message consists of an encrypted hash of the message - first the message is hashed, and then the hash is encrypted using the private key of the signatory (usually a CA).

The recipient can check the signature by decrypting it using the signatory's public key, then hashing the message him/herself and comparing the two results.

Many methods of hashing are possible, combining different encryption algorithms with different hashing algorithms. One is particularly worth mentioning.

  • Digital Signature Standard (DSS)
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: SHA
Next topic: Digital Signature Standard (DSS)


Digital Signature Standard (DSS)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is a US standard. It specifies that SHA-1 is to be used for the hashing, and a specially designed asymmetric algorithm called Digital Signature Algorithm (DSA) is to be used for the encryption. DSA can only be used for signing, not for other encryption.

Parent topic: Digital Signatures
Parent topic: SSL and PKI Technology Primer
Previous topic: Digital Signatures
Related information
FIPS PUB 186


Definitions for OpenSSL

This topic briefly explains some terms that, while they are not part of SSL, often appear in discussions and documentation of SSL, especially of OpenSSL.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Overview
  • Base64 Encoding
  • SSLeay
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Overview


Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Abstract Syntax Notation number One (ASN.1) is a notation used extensively by standards committees and other bodies for defining protocols for use in data communications. It resembles a programming language, but consists mostly of features for defining data structures. There are various data types, and syntax for building up complex data structures out of these elementary types. You might think of a protocol specification written in ASN.1 as resembling the Data Division of a COBOL program, although the actual syntax of the language is more like C.

You may well never see an example of ASN.1, since it is for use in defining protocols, and even protocols themselves tend to be things that the user does not see directly. Nevertheless, ASN.1 is very widely used, and a great many electronic devices in every day use - from air traffic control systems to washing machines - use data transmission protocols that were designed using ASN.1.

Many of the standards used in SSL that we have been discussing were designed in ASN.1, and consequently you will sometimes come across ASN.1 terminology when reading about SSL. This is especially true of the documentation for OpenSSL. Although as an end-user, or as a COBOL developer, you are unlikely to come directly in contact with these concepts, you will find the OpenSSL documentation easier to follow if we explain some of them.

  • ASN.1 Compiler
  • Encoding Rules
  • Distinguished or Canonical Encoding Rules
  • Object Identifiers
  • Octets
  • UTF8String
  • Further Information
Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Definitions for OpenSSL
Next topic: ASN.1 Compiler


ASN.1 Compiler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

People who are implementing protocols designed in ASN.1 often use an ASN.1 compiler, which translates a protocol specification from ASN.1 into source code in a programming language. For the C programming language, for example, the compiler would probably output a C header file (similar to a COBOL copyfile), for inclusion in a C program.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Overview
Next topic: Encoding Rules


Encoding Rules

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A protocol specification in ASN.1 specifies the data structures in a source-like, human-readable way. It says nothing about how those data structures are to be represented when actually transmitted. The bodies responsible for defining ASN.1 have defined encoding rules, which specify how each data structure that you can specify in ASN.1 is to be represented as a bit pattern.

There are in fact several alternative sets of encoding rules that the committees have designed over the years. The earliest set is called the Basic Encoding Rules (BER), and a later one, which produces much more compact messages, is called the Packed Encoding Rules (PER).

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: ASN.1 Compiler
Next topic: Distinguished or Canonical Encoding Rules


Distinguished or Canonical Encoding Rules

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Clearly a set of encoding rules must be such that any particular bit pattern corresponds to just one ASN.1 data structure - otherwise software receiving a message would not know which data structure to interpret the bit pattern as. However, the reverse is not necessarily the case - no ambiguity is caused if several different bit patterns can represent the same ASN.1 data structure.

Nevertheless, in some applications, if different bit patterns can represent the same ASN.1 data structure, it does cause problems. For these applications, it's desirable to have a set of encoding rules where each ASN.1 data structure converts to just one bit pattern, and vice versa. This is especially true in secure communications, because if you are digitally signing messages you need semantically equivalent messages to always have the same encoding.

Such a set of encoding rules is called canonical, or distinguished. Two such sets of rules have been developed - one was named the Distinguished Encoding Rules (DER) and the other was named the Canonical Encoding Rules (CER). CER has not caught on, and is very seldom used. However, the standard file extension for a file containing DER is .cer.

In reading documentation of OpenSSL, you will often see mentions of data stored in DER format.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Encoding Rules
Next topic: Object Identifiers


Object Identifiers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An important data type in ASN.1 is the object identifier. An object identifier (OID) is a reference number, unique in the world, that can be allocated to, in principle, any object; in practice, to any object that can be represented as a set of information. The object identifiers form a tree structure, which you can access at Object identifier tree. The branches of the tree are referred to as arcs, and various organizations have been allocated responsibility for assigning nodes in particular parts of the tree to anyone who requests one, to represent particular objects.

Each node has a number, and optionally, a name. An object's OID is the list of numbers representing the nodes in the tree from the root to that object's own node. They are normally shown enclosed in braces and separated by spaces. If a node's name is shown as well, the node's number is normally shown in parentheses. Only the numbers are intended to be machine-readable - the names are there to be human-readable.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Distinguished or Canonical Encoding Rules
Next topic: Octets
Related information
Object identifier tree


Octets

Restriction: This topic applies only when the Enterprise Server feature is enabled.

COBOL programmers are used to working with memory physically organized into groups of eight bits, and calling these groups bytes. However, in communications, where we are talking about a continuous stream of bits on the wire, each group of eight bits is called an octet.

The ASN.1 encoding rules define four types of octet: identifier octet, length octet, contents octet, and end-of-content octet. There's no need to go into detail here about exactly how these are used (it's different for different encoding rules anyway); it suffices to say that the contents octets contain the actual data, while the others are needed for the syntax of the encoded bit-stream.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Object Identifiers
Next topic: UTF8String


UTF8String

Restriction: This topic applies only when the Enterprise Server feature is enabled.

ASN.1 has a number of different string data types. They differ in the range of characters they can support, and in how many octets are used to represent each character.

The string data type you will see mentioned most often is the UTF8String. This is the best data type for internationalization. UTF8 stands for UCS Transformation Format, 8-bit (where UCS stands for Universal Character Set). It in fact uses a variable-length encoding. The original ASCII characters have exactly the same encoding as in ASCII itself, using 7-bits, and with the top bit set to zero. All other characters have the top bit set to 1. Because the encoding is variable length, all known characters can be represented.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Octets
Next topic: Further Information


Further Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For detailed information on ASN.1, see ASN.1 Information Site

The formal standards documents on ASN.1 and its encoding rules are published by the International Telecommunications Union Telecommunications Sector (ITU-T) and International Standards Organization (ISO) / International Electrotechnical Commission (IEC).

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: UTF8String
Next topic: Base64 Encoding
Related information
ASN.1 Information Site


Base64 Encoding

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The bit patterns produced by the encoding rules described above are unlikely, in general, to correspond to printable characters. But sometimes it's convenient to represent the encoded data in printable form. This can be done by converting it to base64 encoding.

Base64 is a scheme for converting binary data to printable ASCII characters, namely the upper- and lower-case Roman alphabet characters (A–Z, a–z), the numerals (0–9), and the "+" and "/" symbols, with the "=" symbol as a special suffix code.

The data's original length must be a multiple of eight bits. To convert data to base64, the first byte is placed in the most significant eight bits of a 24-bit buffer, the next in the middle eight, and the third in the least significant eight bits. If there are fewer than three bytes to encode, the corresponding buffer bits will be zero. The buffer is then used, six bits at a time, most significant first, as indices into the string "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" and each character thus selected is output.

This is repeated until the input data is exhausted. If at the end only one or two input bytes remain, then only the first two or three characters of the output are used, and the output is then padded with two or one "=" characters respectively. This prevents anyone adding extra bits to the reconstructed data.

The resulting base64-encoded data is approximately 33% longer than the original data, and typically appears as seemingly random characters.

Base64 encoding is specified in full in RFC 1421 and RFC 2045.

Many of the commands provided by the openssl.exe utility can convert between normal binary encoding and base64 encoding.

Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Further Information
Next topic: SSLeay


SSLeay

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Open SSL documentation occasionally mentions SSLeay, mainly where it needs to discuss compatibility of OpenSSL with SSLeay.

After SSL was first introduced by Netscape, an independent implementation of it was developed, the SSLeay library by Eric A. Young and Tim Hudson. This was released in 1995. OpenSSL is based on this SSLeay library.

Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Base64 Encoding


Attacks

This topic explains some of the best known strategies for breaking a code, and what features SSL has that you can use to protect yourself from these attacks.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Terminology
  • Brute Force Attack
  • Dictionary Attack
  • Replay Attack
  • Man-in-the-Middle Attack
  • Truncation Attack
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Terminology


Terminology

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A message sent unencrypted is said to be in cleartext or plaintext. A message sent encrypted is said to be in ciphertext.

The US government used to restrict the strength of encryption it allowed to be included in software for export - beyond a certain strength, encryption is regarded as of military value. In January 2000 these restrictions were mostly removed. Nevertheless a lot of encryption software still exists that was designed in that period to be exportable. The term "export cipher" means an algorithm and key length designed to be exportable under these regulations.

The information given here is believed to be correct at the time of writing, but remember that typical computer power and legal requirements are constantly changing.

The word "cipher" is often used to mean an encryption algorithm. A particular algorithm with a particular key length is often referred to by the algorithm's abbreviated name followed by a hyphen and the key length. For example, RC4-40 means "Rivest Cipher 4 with 40-bit keys".

Short keys are usually called small or weak keys.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Attacks
Next topic: Brute Force Attack


Brute Force Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This consists of simply going through every possible key, deciphering the ciphertext with each key, and trying to find some recognizable cleartext in the result. If you use a 128-bit key there are 2128 possible keys.

A would-be code-breaker would regard this type of attack as the last resort, to be used only if there is no feature - that is, weakness - of the cipher that makes possible some more intelligent attack. A cipher that forces the code-breaker to resort to this method is a strong cipher.

However, ciphers that use weak (small) keys are susceptible to brute force attack, in particular RC4-40, RC2-40 and DES-56. There have been many successful brute force attacks against RC4-40 since its release in February 1995.

A brute force attack against ciphers with 128 bits or more is probably impractical in the foreseeable future.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Terminology
Next topic: Dictionary Attack


Dictionary Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This type of attack can be used when the attacker knows or guesses some part of your original message. In the case of a protocol, this may be easy - for example, in HTTP messages the "get" command often appears.

The attacker takes the known cleartext and encrypts it using every possible key. The resulting set of ciphertexts is saved. This set of saved ciphertexts is called a dictionary.

When the attacker gets hold of an encrypted message, he or she searches it for occurrences of any of these ciphertexts. When a match is found, then the key that gave that ciphertext must be the key that was used to encrypt the whole message.

SSL protects you from this kind of attack by using various technical measures that ensure the same plain text produces different ciphertext each time.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Brute Force Attack
Next topic: Replay Attack


Replay Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a replay attack, an attacker records an exchange of messages between a client and server and tries to recreate the exchange later by resending the client messages to the server.

To prevent this, SSL has a nonce number. This is a connection-id, which the server generates as a random number and sends to the client together with the server certificate. Since the nonce is different for each session, someone resending the old set of client messages cannot fool the server into thinking they are a new set. SSL nonces are 128 bits long.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Dictionary Attack
Next topic: Man-in-the-Middle Attack


Man-in-the-Middle Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a man-in-the-middle attack, an attacker intercepts messages and modifies them, and then passes them on to the intended recipient.

SSL's system of certificates and private keys prevents this. An attacker would have to fake a certificate and somehow get it signed with a CA's key.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Replay Attack
Next topic: Truncation Attack


Truncation Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a truncation attack, an attacker inserts into a message a TCP code indicating the message has finished, thus preventing the recipient picking up the rest of the message.

To prevent this, SSL from version v3 onward has a closing handshake, so the recipient knows the message has not ended until this has been performed.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Man-in-the-Middle Attack


Designing a PKI

This chapter advises on points to remember, ideas to consider, and pitfalls to avoid if you are designing a PKI for your organization. This is by no means an exhaustive list, but is intended to be helpful in suggesting points to consider.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • General Points
  • Client Certificates
  • Security
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: General Points


General Points

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Don't design a PKI with a particular application in mind - rather, think of it as a fundamental part of your organization's general data processing setup. If you design it for use with a particular application, you are likely to find it inflexible when you try to use it with other applications.
  • Authentication doesn't imply authorization. Just because someone has the necessary keys to access your data, that doesn't mean they necessarily should be allowed access to all your data. You should still have other mechanisms, for example an access control list (ACL), to ensure people can only access data appropriate to their position.
  • You should make people change their keys from time to time, by applying for new certificate/key pairs. That way if a private key is stolen without anyone noticing, at least it will become useless to the thief next time the certificate/key pair is changed.

    This applies to all private keys - client keys, server keys, subordinate CA keys, and root CA keys.

    The easiest way to enforce this is to include expiry dates in certificates.

  • There are many ways of structuring your tree of trust. Should there be just one root CA, or several? Should subordinate CAs be able to grant CA certificates to other subordinate CAs, or should only root CAs be able to do this?
  • Will your CAs sometimes need to revoke certificates? The commonest way to do this is for a CA to maintain a certificate revocation list (CRL), a list of certificates it has granted and later revoked (they can be deleted from the list once they expire). Users can obtain the CRL and install it in their SSL software.
  • Will users generate their own private keys? In some setups, the CA generates both the certificate and the private key for the user. This saves the ordinary user needing to know how to create a certificate signing request (many of the major CAs on the Web are willing to work in this way) but it means the private key must somehow be conveyed securely to the user. To obtain the maximum security benefit of asymmetric encryption - that the private key is never sent anywhere, so can't be listened in on - the user should him/herself use openssl.exe to create a private key and the matching certificate signing request, and send the latter to the CA, so the CA can create the certificate.
  • It may be an advantage to have all certificate requests handled by your subordinate CA machines. Then your root CA machine only needs to be online when you are using it to certify subordinate CAs. After that it can be taken offline, or at least its private key can be stored offline, until you need it to certify more subordinate CAs. This can greatly improve the security of the root CA, by reducing to a minimum the times when it could be accessed illicitly. It also means the users are not dependent on a single machine, the root CA machine, to keep functioning.

    It will still be possible - and simpler - to have your users install the root CA's certificate in their browsers (or whatever SSL-enabled software they use) rather than the certificates of all the subordinate CAs.

  • If you want really tight control, you might want to delete from your Web browser all the CA certificates that have been installed by default, and install just certificates of your own choosing - from your own CA, if you are setting up a private PKI. However you'd have to think carefully about the effect on accessing other Web sites outside your PKI.
  • If as a Web site owner you want the benefits of non-repudiation, that is, you want to be able to prove that data really was sent to you from a particular client, then you should use full authentication - you can if you wish generate client certificates for your clients (acting as a CA to this extent) and send the clients their certificates for them to store and use. Remember your clients will need to understand how to install these personal certificates in their software, e.g. their browsers.
  • It's worth pointing out a few features of the "world-wide" PKI used on the World Wide Web, which you may or may not choose to emulate in your own PKI:
    • It uses server-only authentication - although there's nothing to stop a particular online service arranging with its known clients that they should have to have certificates.
    • All CAs are equally trusted - there's no concept of some being trusted more than others.
  • When a certificate/keyfile pair is created, you can create pass phrases to protect them. It's essential to protect the keyfile in this way, because a private key is extremely sensitive information and every form of security available should be used to protect it. However, a certificate is intended to be available to anyone who wants to see it, so it's seldom appropriate to protect it in this way.

Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: Designing a PKI
Next topic: Client Certificates


Client Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In looking at certificates installed in Web browsers, you may have noticed that (using Internet Explorer terminology, but the situation is the same with any Web browser) the Personal and Other People's lists are empty or nearly empty, while the Intermediate CA and Trusted Root CA lists contain many entries.

This is a fairly typical situation. As an ordinary Web user, you probably don't actually need a certificate of your own - Web businesses such as online banks and shops generally use server-only authentication. As for Other People's, you could install server certificates sent to you by such online businesses, but it's generally unnecessary as these businesses send their certificates in the initial hand-shake of any communication session. It's much more necessary to have CA certificates installed, since these are needed to validate the certificates these businesses send you.

You might sometimes find it useful to install an entity's client certificate, if you communicate with them peer-to-peer rather than client/server.

Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: General Points
Next topic: Security


Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The security of your CA and RA machines is vital.

Remember you need to ensure reliability and availability, as well as confidentiality and trustworthiness.

Remember that SSL protects data only while it is in transit - once it has been received and stored, it is no longer encrypted, and so you need to look to other methods to ensure it remains confidential.

  • Controlling Network Access
  • Controlling Physical Access
  • Backups
Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: Client Certificates
Next topic: Controlling Network Access


Controlling Network Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You will of course need to protect your machines with a firewall and with virus scanning, and require any user accessing the machines remotely (if you allow this at all) to login, giving their user ID and password.

It's advisable to have the latest version of your operating system - the security features are usually improved at each upgrade.

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Security
Next topic: Controlling Physical Access


Controlling Physical Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You should certainly require anyone using your CA and machines locally on to login, giving their user ID and password, and you should probably control access to the computer room too, so that no-one authorized can even get to the machine.

Also ask yourself about other ways an interloper could get in. Could someone insert an USB device between the printer and the system? Could someone run code from an I/O device? Could someone trick their way into your site by talking to the people who work there, finding out how they work, and emulating them?

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Controlling Network Access
Next topic: Backups


Backups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The private keys of your CA machines are vital. Keep them backed up to guard against accidental loss - but keep the backups every bit as secure as the system itself, to guard against them being stolen.

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Controlling Physical Access


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, the TLS honor server cipher list option is checked in SSL Options or 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
TLS1.1 | Enabled
TLS1.2 | Enabled
TLS1.3 | Enabled

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 Visual COBOL 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. Click here for more information in the OpenSSL documentation. Click here for more information in the Apache documentation.
Note: The Cipher suites string is limited to 255 characters.

The default setting for the Cipher suites list is specified as follows:

@SECLEVEL=0 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=0
Enables various old signature algorithms and cipher suites in OpenSSL. This is to retain compatibility with older certificates such as MD5. The old cipher suites are disabled later in the cipher list.
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 HIGH MEDIUM
Remaining cipher suites are in order of strength.
+3DES +SHA
These are specific hash methods and cipher suites.
!RC4 !aNULL !eNULL !LOW !MD5 !EXP
Known low security collections and hashes that existed within the earlier groupings are excluded.

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.

Should you require compatibility with older browsers or clients then insert MEDIUM after HIGH and remove !MEDIUM, as follows:

kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +SHA !RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP

The use of MEDIUM allows the use of older SSL3 and TLS1 cipher suites which would otherwise be unusable even though those older protocols may have been selected.

The above cipher suite lists break down as follows:

kEECDH+ECDSA
First preference for enabling Perfect Forward Secrecy (PFS), kEECDH with ECDSA cipher suites.
kEECDH
Followed by the rest of the PFS supporting suites, this includes the RSA collection.
kEDH
The remaining Diffie-Helman suites.
HIGH
All remaining high security suites not listed above.
MEDIUM
All remaining medium security suites not listed above.
+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.
!MEDIUM
Specifies not to use any medium strength security cipher suites.
!LOW
Specifies not to use any low strength security cipher suites.
!3DES
Specifies not to use any 3DES ciphers.
!MD5
Specifies not to use any MD5 ciphers.
!EXP
Specifies not to use any EXPORT strength ciphers.
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.
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Dual Cryptographic Identities on a Single Network Endpoint

Visual COBOL 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.

To preserve the behavior of existing installations the 5.0 release continues to support security level 0 as the default setting. This behavior is now deprecated and is provided for backward compatibility only.

Note: If you are setting your own cipher suite collections then they will inherit the new OpenSSL 1.1.1 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.
Attention: The default security level in the 6.0 release will be level 1.

Example Security Level 0

@SECLEVEL=0 kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM !3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
This matches the default configuration.

Example Security Level 1

@SECLEVEL=1 kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM !3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
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.
      Note: If you do not specify a certificate and keyfile MF Directory Server uses the default certificate and keyfile created when DemoCA was installed.
  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 Configuring a TLS Protocols List and Configuring a Cipher Suites List 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


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


Secure Communications (SSL) Legal Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

OpenSSL Acknowledgment

The SSL support provided by the Micro Focus Security Pack is based on OpenSSL.

The OpenSSL project is a collaborative effort to develop a robust, commercial-grade, full-featured, and Open Source toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols as well as a full-strength general purpose cryptography library. The project is managed by a worldwide community of volunteers that use the Internet to communicate, plan, and develop the OpenSSL toolkit and its related documentation.

For further information, see the OpenSSL home page at http://www.openssl.org .

Usage and Export

The ability to send messages in an encrypted form is regarded in some parts of the world as being of military value, and therefore is subject in some countries to legal restrictions and export controls.

Important:

Therefore it may be illegal to use or export SSL or PKIs in or to some countries. You must check the legal position in your country.

Restrictions on Algorithms and Key Lengths

Some encryption or hashing algorithms available in OpenSSL are under patent. Micro Focus has, to the best of its knowledge, not included these in the SSL support included with this COBOL system.

The use of some key lengths may be legally restricted in some countries, because longer key lengths give stronger protection, and therefore may be considered of military value.

Important:

We recommend you take the advice of your own legal department, especially regarding conditions in your country, and especially if you will be shipping products of your own incorporating these features.

Parent topic: Securing Communications


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.

  • 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


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.

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. Use the cascertreg command line utility to map a user certificate to a user ID. You can do this by using the command line utility cascertreg. See cascertreg for more information.
    Note: Regions that use certificate mapping for CICS Web Interface can use the same certificate mappings for DCAS.
  7. 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 the user is able to log on to the server using their certificate as identification. The logon process itself is often performed using a macro which inserts the two well-known placeholder strings into the logon fields, which the server sees and replaces with the mapped username and passtoken. These strings are:

")USR.ID("
For the username.
")PSS.WD("
For the password.
Parent topic: Multi-Factor Authentication
Related reference
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.

Parent topic: Multi-Factor Authentication
Related reference
DCAS conversation type
TN3270 conversation type


Vault Facility

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The vault facility enables certain Enterprise Server components to keep certain sensitive information in a form of storage defined as a vault, accessible via a configurable vault provider.

You need to address three areas of configuration before you can use the vault facility. They are:

  • Configure the vault provider
  • Migrate existing secure data
  • Configure Micro Focus Directory Server (MFDS)
  • Vaults and Vault Providers
    Defines the terms vault and vault provider.
  • The mfsecretsaes Vault Provider
    Describes the mfsecretsaes vault provider.
  • The mfsecretsmscpd Vault Provider
    Describes the mfsecretsmscpd optional vault provider.
  • Configure the Vault Provider
    Describes configuring the mfsecretsaes vault provider using the secrets.cfg file.
  • Configure the Default Vault
    Describes the circumstances that dictate when to migrate MFDS secure data to the vault, and the steps required to do so, and also describes the steps required to configure MFDS to use the vault.
Parent topic: Enterprise Server Security


Vaults and Vault Providers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Vault Facility enables Enterprise Server components to store sensitive data, such as passwords, in one or more vaults.

A vault is some 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.

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 supports UNIX platforms. See The mfsecretsaes Vault Provider for details.

Notes:
  • Micro Focus does not currently provide support for customer-written providers.
  • Additional providers might be supported in a future release.
Parent topic: Vault Facility
Related concepts
The mfsecretsaes Vault Provider
The mfsecretsmscpd Vault Provider
Configure the Vault Provider


The mfsecretsaes Vault Provider

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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 Configure the Vault Provider for more information.

Parent topic: Vault Facility
Related concepts
Vaults and Vault Providers
Configure the Vault Provider


The mfsecretsmscpd Vault Provider

Restriction: This topic applies only when the Enterprise Server feature is enabled.
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 Configure the Vault Provider for more information.

Parent topic: Vault Facility
Related concepts
Vaults and Vault Providers
Configure the Vault Provider


Configure the Vault Provider

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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. In doing this, be sure that your secrets themselves are backed up in a secure fashion, for example in a file on an encrypted USB flash drive, to ensure recovery. We also strongly recommend that you secure and control access to the secrets.cfg file using your operating system file permissions, and that you monitor its access.

The secrets.cfg file is located by default in the $COBDIR/etc directory.

Use the instructions contained in the secrets.cfg file to guide your changes.

The following is a sample secrets.cfg file:

# 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.

# A default vault provider can be set in the "global" configuration.
# Unless a particular applications/software component requires or
# allows use of a specific named provider, the "default" provider
# will be used.
[global]
default provider=mfsecretsaes

# Specify vault providers and their configuration below here.

# Individual vault "providers" will have individual configuration
# requirements. The key=value pairs beneath the logical [provider] label
# will be used by the provider module to control its behaviour.
[mfsecretsaes]

# 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 vault
# 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
# vault.
#
# The product installer will initially set a product-specific
# file location by default.
location=C:\ProgramData\Micro Focus\Enterprise Developer\mfsecrets

# 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=<generated_value>
# Salt is an optional base64 value. By default, the product installer will
# generate a value.
salt=<generated_value>
Parent topic: Vault Facility
Related concepts
The mfsecretsaes Vault Provider
The mfsecretsmscpd Vault Provider
Vaults and Vault Providers


Configure the Default Vault

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before using the default vault, you should migrate any existing MFDS secure data to the vault. Then you can configure MFDS to use the vault.

Migrate MFDS secure data to the vault

If you have used Transport Layer Security (TLS) or External Security with previous versions of MFDS, you need to migrate this information to the vault before configuring MFDS to use it.

  1. Stop the Micro Focus Directory Server process by entering the following at a command prompt in the $COBDIR directory:
    mfds -s
  2. At a command prompt, enter:
    mfds --vault-migrate

Configure MFDS to use the default vault

Out of the box, MFDS does not use the default vault. After configuring a provider and addressing migration issues, you must configure your system to use it.

  1. If the Micro Focus Directory Server service is running, stop the service by entering the following at a command prompt in the $COBDIR directory:
    mfds -s
  2. Set a system environment variable: MFDS_USE_VAULT=Y.
  3. Restart the Micro Focus Directory Server service.

When MFDS is configured correctly, the text [Vault enabled] appears on the Enterprise Server Administration Home page in the top right corner above the licensing status.

Parent topic: Vault Facility
Related reference
mfds


Troubleshooting

Micro Focus enterprise products include a varied set of facilities for problem analysis. These diagnostic facilities are the result of numerous implementations, and the realization that different sorts of problems can occur, each requiring its own type of approach. We will try to suggest here which diagnostic facility to use for which problem.

As a minimum, we recommend that anyone involved in Enterprise Server implementations should know, for each diagnostic tool or technique:

  • What it does
  • How to configure it
  • What the output is that is produced, and where to find it

After identifying the appropriate facility, we aim to help any users of the enterprise products to set up and run the diagnostics, and then either analyze the output themselves or send them to Micro Focus for help from our Support teams.

Depending on the type of problem, you might need to use several of these diagnostic facilities simultaneously. For instance, a regular start point is the console log. However, this rarely shows the full problem, so very often you need a trace output and dump to complete the analysis. The console log might identify the failing process, and the trace and dump output will show the detail of what the process was doing and how it was interacting with the other processes if that is critical. Alone, these might be of little use, but together they can pinpoint what led to the failure.

Although it is well understood that during project implementation and production running, speed can be of the essence to complete the project or bring the business system back up, if Micro Focus is to help, it is vital that the diagnostic output be gathered in its entirety and treated as data of very high value in its detail and its completeness.

Please treat this documentation as a reference, and bear in mind that each problem is different and will require its own approach to diagnosis, so choose from the facilities detailed here based on what you believe to be the type of problem.

  • Diagnostics in Enterprise Server
  • Minimum Diagnostic Configuration Recommendations for Production Systems
  • Production System Failure Data Capture
  • Reporting a Problem
  • Specific Troubleshooting Advice
Parent topic: Visual COBOL Development Hub 5.0


Diagnostics in Enterprise Server

Enterprise Server contains logs that are generally always written to, and which require little or no configuration. For more detailed tracing, additional parameters and configuration files can be set to capture a much more detailed set of diagnostic information.

  • Default Logs
    These logs require no configuration as they are enabled for at least some logging by default.
  • Configurable Traces and Diagnostics
    These require some additional configuration before they are active.
  • Security Tracing
    Security trace messages can be written to the console.log, the MFDS journal.log, and the AUX trace.
  • Non-Micro Focus Diagnostics
    The utilities available with the operating system or available from third parties are often very useful in providing additional information that can complete the diagnostic picture or indeed identify specific problems directly, for example, with the environment setup or network.
Parent topic: Troubleshooting


Default Logs

These logs require no configuration as they are enabled for at least some logging by default.

However, additional configuration is available for some of them, for example, to control their size and content.

  • Console Log
    This is the most important log in the system.
  • Micro Focus Communications Server (MFCS) log.html
    This logs messages from the communications manager process(es) and any associated listeners.
  • Micro Focus Directory Server (MFDS) journal.log
    The MFDS process provides an information repository, and is one of the first things to be accessed during region startup.
Parent topic: Diagnostics in Enterprise Server


Console Log

This is the most important log in the system.

It contains the region activity since startup and hence shows what happened leading up to a failure.

You should review this log first, to see which errors have occurred, when they occurred, and which process was responsible. The Process ID and time from this log lets entries in other logs be associated with this particular error or entry in the console log.

Parent topic: Default Logs


Micro Focus Communications Server (MFCS) log.html

This logs messages from the communications manager process(es) and any associated listeners.

It shows specific information related to the addresses and port numbers used.

Parent topic: Default Logs


Micro Focus Directory Server (MFDS) journal.log

The MFDS process provides an information repository, and is one of the first things to be accessed during region startup.

If security is enabled, this log can also help show whether and which connections to MFDS have been successful or are rejected.

Note: The MFDS process is a single process that provides an information repository for the entire Enterprise Server installation. This means, therefore, that it interacts with all defined regions running on this machine, and hence entries in the journal.log could be from more than one region.
Parent topic: Default Logs


Configurable Traces and Diagnostics

These require some additional configuration before they are active.

A wide range of settings is available to let you collect specific and relevant information.

Note: This can result in very large files, so you should check disk space when configuring these traces.
  • Auxiliary Trace
    This provides a trace of activity over a time period within the main CAS facilities.
  • CASDUMP
    A system dump provides a "time slice" view of resources within the system at the time that the dump is requested, and is valid only for that specific time.
  • CTF Trace
    This is the primary logging mechanism for the COBOL system. It logs what happens in most user programs and what is happening within the internal CAS processes themselves. For example, JCL and the compiler/ debugger.
  • MFCS Connector Tracing
    Each MFCS listener has an associated connector module.
  • Memory Strategy
    Memory strategy can be enabled where memory corruption is detected or suspected.
  • Historical Statistical Facility (HSF)
    Provides the ability to record statistics related to the time spent in a COBOL program.
  • Core on Error
    This feature causes a program core dump to be generated when that program causes an exception.
  • Fileshare Trace
    This facility provides specialist tracing of the transactional file handler technology.
  • External File Handler Trace
    The File Handler module can be configured to generate trace information that can be later replayed and analyzed using the associated utility program.
  • XA Switch Module Tracing
    Additional trace can be enabled to provide more detail regarding the XA Resource Manager interface.
Parent topic: Diagnostics in Enterprise Server


Auxiliary Trace

This provides a trace of activity over a time period within the main CAS facilities.

Because it runs while the system is running, it can affect the performance of the system, and is therefore very configurable in order to record the specific types of events that might be needed for different types of problems. Ideally, production systems should be able to perform adequately with at least the minimum tracing enabled.

Auxiliary trace is usually configured from the Enterprise Server Admin Console (i.e. ‘Aux Trace Active’), but can also be configured using the ‘CTRA’ transaction from a 3270 session. Trace information is written to the trace files CASAUXTA and CASAUXTB, and the amount of information output is controlled by the setting of specific trace flags (e.g. Application (API), Storage Control (SCP), and Application Container (RTS)).

To view a video on the Micro Focus YouTube channel, on how to enable AUX tracing for Enterprise Server, click here.

Parent topic: Configurable Traces and Diagnostics


CASDUMP

A system dump provides a "time slice" view of resources within the system at the time that the dump is requested, and is valid only for that specific time.

Taking the dump should not have any performance impact on the system. A manual dump can be taken at any time (with no additional configuration required) from the command line or the ESMAC interface. However, a region should be configured to generate a system dump whenever a System Abend occurs. This is usually configured in the Enterprise Server Admin Console (i.e. ‘Dump on System Abend’).

Additionally, “Dump on Transaction Abend” can be set in ESMAC so that any abending transactions will also cause a dump to be generated.

Dump information will be written to the current casdump file (casdumpa.rec, casdumpb.rec or casdumpx.rec), and includes the current contents of process memory, server control blocks and the local and system trace tables.

We recommend you take a dump for most problems when they occur, and whilst the system is in the failed state.

Parent topic: Configurable Traces and Diagnostics


CTF Trace

This is the primary logging mechanism for the COBOL system. It logs what happens in most user programs and what is happening within the internal CAS processes themselves. For example, JCL and the compiler/ debugger.

It records activity over a period of time, and is enabled via a separate configuration file. CTF tracing can be restricted to specific components or modules, and certain elements within these components. The level of detail included in the trace can be configured for each component if required.

To view a video on the Micro Focus YouTube channel, on how to enable CTF tracing for Enterprise Server, click here.

Parent topic: Configurable Traces and Diagnostics


MFCS Connector Tracing

Each MFCS listener has an associated connector module.

They can be specified via the "listener type" setting in the MFDS GUI. In turn, most connector modules have optional tracing that is configured in the Configuration Text area for that listener, by using "trace=y" in a [Trace] section.

Parent topic: Configurable Traces and Diagnostics


Memory Strategy

Memory strategy can be enabled where memory corruption is detected or suspected.

When it is enabled, it allows the COBOL sub-system to verify/validate memory addresses as they are used by a program. This means that when memory operations occur, the system is able to validate that only the assigned memory has been used. If this is not the case, an exception will be generated at the point that the corruption is detected. The Memory Strategy facility provides a fine-grained control over which processes are checked, and the extent of the checking that is done: this keeps the overhead of enabling Memory Strategy to a minimum.

Parent topic: Configurable Traces and Diagnostics


Historical Statistical Facility (HSF)

Provides the ability to record statistics related to the time spent in a COBOL program.

The Historical Statistical Facility provides the ability to record statistics related to the time spent in a COBOL program, and the time that parts of that program spent in CICS API commands/ tasks, SQL operations and JCL jobsteps, as well as associated file and TSQ accesses.

Parent topic: Configurable Traces and Diagnostics


Core on Error

This feature causes a program core dump to be generated when that program causes an exception.

Once a core dump is generated, it can be loaded into the development environment where the offending line of code should be shown, so the call stack and values of variables can be examined. It is most useful in a production environment where it is unlikely that a debugger can be dynamically attached: the core dump can be obtained and then analyzed on another system. The .IDY file(s) must be available for the programs that fail, as this allows the core dump to show as much information as possible regarding the state of the program at failure time. Without the .IDY file(s), only a limited amount of diagnostics can be performed.

Parent topic: Configurable Traces and Diagnostics


Fileshare Trace

This facility provides specialist tracing of the transactional file handler technology.

Fileshare is a transactional 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: Configurable Traces and Diagnostics


External File Handler Trace

The File Handler module can be configured to generate trace information that can be later replayed and analyzed using the associated utility program.

This would show information such as filenames accessed, and the operation used (for example, Open or Read). More detailed information can also be generated for specific file operations (for example, access mode and file format).

Parent topic: Configurable Traces and Diagnostics


XA Switch Module Tracing

Additional trace can be enabled to provide more detail regarding the XA Resource Manager interface.

The console.log will contain basic errors and other messages relating to XA resources. Additional AUX and CTF trace flags can be set to output more detailed XA messages to the relevant trace files.

Parent topic: Configurable Traces and Diagnostics


Security Tracing

Security trace messages can be written to the console.log, the MFDS journal.log, and the AUX trace.

You configure detailed security tracing in the relevant Configuration Text areas for:

  • MFDS and globally for all regions (‘security’ button in left hand pane) via:
    • the default Enterprise Server Security tab
    • each Security Manager definition
  • individual regions via:
    • the region’s Security tab (from Server > Properties tabs)

The options available for Security Manager tracing depend on the External Security Manager (ESM) module used by that manager. In addition, the security AUX trace flag (saf) can be enabled for region-specific security tracing.

Note: Problems with initial access to MFDS (for example, to start a region) will be logged in the MFDS journal. However, trace must first be set up in the External Security Manager (ESM) to output these messages.

Security tracing can have a significant effect on performance so should not be left on in a production system.

  • Security Auditing
Parent topic: Diagnostics in Enterprise Server


Security Auditing

The security audit facility is sometimes useful for diagnostic purposes. It maintains a record of security decisions (user sign-on succeeded, resource access request denied, etc). It needs the Audit Manager to be running: you can start it from the command line, or as a service on Windows or a daemon on UNIX. You configure it with a configuration file that is specified with the ‘-c <filename>’ option.

Parent topic: Security Tracing


Non-Micro Focus Diagnostics

The utilities available with the operating system or available from third parties are often very useful in providing additional information that can complete the diagnostic picture or indeed identify specific problems directly, for example, with the environment setup or network.

Tools such as strace and truss might be provided as optional installation components, or are otherwise available for download and installation.

The following external utilities have proved useful in providing supporting information when a problem occurs, or in investigating problems that would be exposed directly to the operating system:

strace/truss
lsof
List open files
netstat
TCP/UDP port connection information
ipcs
interprocess communications - for shared memory etc.
ulimit
limits on open files
Parent topic: Diagnostics in Enterprise Server


Minimum Diagnostic Configuration Recommendations for Production Systems

We recommend that you run your production system with some diagnostics switched on. In this way, unexpected problems can be investigated when they first occur. Diagnostics consume resources, and there is always contention between problem determination facilities and performance. You need to decide how important it is to be able to diagnose a problem the first time it occurs rather than having to try to recreate it or having to just turn on diagnostics and wait for it to re-occur.

‘Dump on System Abend’ should always be enabled in an Enterprise Server region, along with some Auxiliary tracing. The following level of diagnostics is the minimum we recommend for running in production systems.

From the Diagnostics tab on the Enterprise Server Admin Console:

  • Check Dump on System Abend
  • Check Auxiliary Trace Active
  • Check the Task Control (KCP) and Application (API) trace flags

We strongly recommend that you also enable the ‘core_on_error’ facility so that application core dumps are created whenever there is a crash: see the topic Producing a Core Dump for Run-time Errors.

Parent topic: Troubleshooting


Production System Failure Data Capture

For all troubleshooting exercises, it is essential you gather as much information as possible about the state of the enterprise server region when the problem occurred and about the events leading up to the problem. This should include the date/time the problem occurred, and observations on what was happening in the system, how long it had been running, what the symptoms were, and how/where these were observed.

When a problem occurs, you must capture and provide specific logs, traces and dumps, and ideally the contents of various configuration files, directories (for example, MFDS), and the output from a number of operating system tools. This should be done as soon as possible after the failure occurs.

Diagnostic Collection Script

Use the MFESdiags diagnostic script to collect this information automatically.

The script is mfesdiags.sh which can be obtained from SupportLine. Transfer it to the UNIX machine and give it the 'execute' permission (for example, chmod +x mfesdiags.sh). Run the script in the COBOL/Enterprise Server environment. It will prompt for the relevant region name for which to collect diagnostics, and will generate mfesdiags.trz which you should attach to an incident.

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 datasets, casauxta.rec and casauxtb.rec
    • Any system abend dumps, casdumpa.rec, casdumpb.rec or casdumpx.rec
    • Any HSF output files (*.csv)
  • The output from mfsupport, 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
  • A list of shared memory areas and semaphores
  • A list of open files
Note: The MFESdiags script will collect CTF trace logs if the region is configured to generate CTF trace. See the CTF Trace topic for configuration details.
Parent topic: Troubleshooting


Reporting a Problem

The following topics describe best practices in providing information when a problem occurs and an incident needs to be raised.

  • How to Report a Support Incident (SI)
  • Different Types of Incident
  • Managing the Incident
  • Important Considerations for Incidents
  • Naming Conventions for Diagnostic Collection
Parent topic: Troubleshooting


How to Report a Support Incident (SI)

All incidents should be reported either through the SupportLine website or via your local Freephone Support number – this is shown on the SupportLine website.

We recommend you report incidents through the website. General instructions are:

  1. Go to http://supportline.microfocus.com and login (at the left in the margin).
  2. If you do not have a Web ID to login, register for one (on the Log In page below the login fields).
  3. Report the SI online (under “My Incidents”).
  4. Give the incident an informative short description (see the topic Providing an Informative Short Description).
  5. Attach all relevant information that might be useful in supporting the issue diagnosis. They type of problem you are encountering affects this, but in general it should include the following:
    • The MFESdiags output as described above
    • Step–by–step instructions to reproduce the error
    • Any sample programs that can be used to reproduce the problem. Ideally, provide a zip file containing everything necessary to build any program(s)
    • Any directives used if there are problems with compilation
    • Make a note of any Micro Focus consulting FDS or other utility that is being used and attach to the incident if possible
  • Best Practice in Incident Reporting
    Describes the best way to provide information about a problem to Micro Focus.
Parent topic: Reporting a Problem


Best Practice in Incident Reporting

Software problems that are reported to Micro Focus generally fall into two types:

  • Reproducible problems

    The standard process is to detail the reproduction scenario, and to provide whatever is necessary to allow Micro Focus to reproduce the problem quickly and easily.

  • Complex problems

    These are 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.

The following information is good practice, and specifically relates to reporting complex problems, and what you can do to help Micro Focus to give you a quick response.

  • Please report only one problem for each incident.
  • If a solution or workaround has been provided, and you encounter a further problem, then open a new incident with new details.

This allows us to assign the appropriate engineer to each unique issue, and allows for several engineers to progress the issues simultaneously.

All high quality incidents will have:

  • An accurate short description, including details as specific as possible. For example, error message numbers.
  • A long description, with complete details, to provide context, such as chronology, symptoms, configuration, workload levels, what else was happening in the environment at the time, and any third-party software involved.
  • All relevant first point-of-failure diagnostics attached to the initial incident report. Failure diagnostics are critical to help understanding; please always provide them when available.

We recommend your set of diagnostics:

  • Include complete diagnostics – including traces, dumps, console log and other relevant logs.
  • Be chronologically synchronous – all the logs must be from the same failure time, to give the full picture, and to allow us to match the process numbers and relevant details.
  • Be specific – to allow us to identify the exact failure, the date/time of the failure, the symptoms demonstrated, if recovery was achieved, or if manual intervention was required.
  • Attach the diagnostics to the Support incident; for large files then contact your Micro Focus Support engineer for details of how to upload to the Micro Focus ftp site.

The Troubleshooting and Diagnostics Guide provides detailed information on diagnostics, and highlights a script available from Micro Focus Support, MFESDIAGS, that will pull together the various diagnostics that we need. In addition, you should always add your own observations and knowledge. These additional observations help us to analyze the large volume of data more quickly.

If you believe you have a recurring problem on your system:

  • Always capture a new set of diagnostics – multiple sets may help us to see ‘patterns’.
  • Update the existing incident on which the problem was originally reported.
  • Add comments to the incident detailing the date/time of the new failure, why you think it is a recurrence, and as much other context on this new failure as possible, including the similarity with previous failures.
  • Supply the diagnostics to Micro Focus using the naming convention for the diagnostics collections and other files. Note that this naming convention is particularly important when multiple failure collections are taken for the same incident and problem; please refer to the Troubleshooting and Diagnostics Guide on the Micro Focus Support site.
Parent topic: How to Report a Support Incident (SI)


Different Types of Incident

We recognize that different types of problem occur with Micro Focus products. In this section, we address five particular types; there are undoubtedly more, but this advice covers the majority. The five types we concentrate on are:

  • Compiler-related Incidents
  • Debugging Failures
  • Reproducible Run-time Failures
  • Unpredictable Run-time Failures
  • Performance Issues
Parent topic: Reporting a Problem


Compiler-related Incidents

For this type of issue, the minimum that we request you supply is:

  • A cut-down of the particular piece of code that is failing; some compiler failures can be related to size of Working Storage etc, so if it is not possible to cut it down, supply the full program. As a tip, if you compile to .lst and supply this to us, this will automatically include all copybooks, and show the directives being used.
  • If you do not supply a .lst, please supply the directives that you are compiling with.
  • Detail the failure symptom or mode.
  • Explain or reference any supporting material if the issue relates to code that you believe should compile successfully. For instance, under a particular standard or model.
Parent topic: Different Types of Incident


Debugging Failures

If you encounter a failure during a debug session in the IDE, we suggest the following as the minimum to complete a high-quality incident report:

  • A copy of the source code that shows the failure, cut down as much as possible - as with compiler issues, you might want to supply a listing (.lst) file.
  • Take the run-time diagnostics of the failure, pulled together using MFESdiags.
Parent topic: Different Types of Incident


Reproducible Run-time Failures

If you have a failure at run time that is consistently reproducible then we suggest that when reporting the incident you include the following:

  • The code necessary to reproduce the failure – this should be cut down as much as possible.
  • Any data needed to reproduce the failure.
  • The details of what the failure actually is; the run-time error message, a corruption, or that the code is not behaving as you expect.
  • Set the appropriate first point of failure diagnostics; adjust them based on your own judgement as to what you believe will help us to understand and diagnose the problem – for instance, if it is a File Handler problem, refer to that section for possible additional tracing; if a memory corruption seems to be occurring, consider the memory strategy settings.
  • Collect the output from the run, using the MFESdiags script.
  • Report the problem to Micro Focus, and upload the diagnostics captured by the MFESdiags script, using the naming conventions recommended.

We would also be happy to hear of any hypothesis or theory that you have that might help us to address the failure more quickly.

Parent topic: Different Types of Incident


Unpredictable Run-time Failures

When tuning production systems, or during their implementation, failures can be seen that do not occur with any predictable regularity or under definable circumstances. It is these types of failures that require the first point of failure diagnostics to be captured and reported to Micro Focus along with full context and detail of the failure.

We recommend that all systems be run, during implementation or in production, with the minimum diagnostic settings configured. Other diagnostic settings should be configured depending on the failure scenario, symptoms, and area of technology. This document provides information on what is available, for instance for communications tracing, Fileshare/File Handler tracing and other areas.

When the failure re-occurs, you should use the MFESdiags script to gather the diagnostic files and report the incident to Micro Focus, uploading these diagnostics following the naming convention set out in this section.

The long description in particular should provide as much context and detail as possible, including chronology and timeline. For further information, see Important Incident Considerations.

Parent topic: Different Types of Incident


Performance Issues

A lot of projects identify performance issues at some point and occasionally slow-downs can occur in production systems.

These are actually two types of issues and these should be approached differently. For performance testing during implementation, we recommend that the following protocol be followed as closely as possible:

  1. Define what acceptable performance is. This can be:
    • the same as a previous platform (maybe, for example, as the IBM mainframe)
    • as fast as a set of particular users find acceptable
    • some other criteria.

    This gives you a target to aim for, and to measure how close you are to being complete.

  2. Identify a representative benchmark program or execution scenario.
  3. Create a spreadsheet, and in it record for each run of the benchmark:
    • The actual benchmark program that is run for this test – you should run a ‘baseline’ to be the start point for tuning hardware, compilations, execution setup etc, and for measuring the impact.
    • The results; elapsed time, I/O time, or whichever type of data you want to measure.
    • The variables that are adjusted for each run; perhaps the programs are compiled with different directives, perhaps the hardware setup is adjusted, perhaps the database is moved from a remote machine to a local machine.
    • Any comments or observations on each run; did it improve performance or not? Did it seem to show up some type of anomaly or restrictions in scaling?

For performance slowdowns that occur post-production, the obvious question to ask is ‘what has changed?’ This might be upgraded hardware – we have seen that adding hardware power does not always improve performance, indeed it can slow it down if the architecture or system setup is not configured to take advantage of it. If nothing seems to have changed, look for whatever else might be running on the system at the time that the slowdown occurs; we frequently have customers find that anti-virus software or mass searches are being done on a machine when performance slows down.

Another very important aspect of performance to consider is the virtual machine environment, if it is part of the setup. Experience has shown that running with a VM can add up to 20% overhead to performance from straight hardware; it is very important to employ a VM consultant to look at the configuration and setup of the VM that is in use to run the Enterprise Server environment.

Parent topic: Different Types of Incident


Managing the Incident

Reply to the incident within the Web Site with your Web ID, so that any answers are logged immediately, and the incident owner is aware you’ve replied to the questions sent to you.

Remember to continue to give detailed information and background regarding new situations that are being reported, or when responding to requests for further tests/information.

Parent topic: Reporting a Problem


Important Considerations for Incidents

High quality initial incident reporting can considerably shorten the time that it takes to a get to a solution. A high quality incident should have:

  • An accurate short description of the symptom
  • A long description that is full and complete, and covers the circumstances and context of the failure
  • As much context and detail as possible. If you are unsure whether it is relevant, provide it anyway
  • Important details such as chronology, symptoms, configuration, workload levels and third party software involved

Always include relevant diagnostics on the initial report. A good set of diagnostics is:

  • Uploaded to the Micro Focus ftp site or attached to the incident (see the topic Naming Conventions for Diagnostic Collection)
  • Complete – includes traces, dumps, console and other relevant logs
  • From the same failure – submitting a console log from Tuesday, a trace from Wednesday and a dump from Thursday does not help as none of the process numbers or details will match
  • Inclusive of specific failure details (probably in the long description) with particular attention to the date/time of the failure, when it started, what symptoms it demonstrated, whether it recovered or required manual intervention

If you believe that a problem reoccurs on a system:

  • Always capture a new set of diagnostics – multiple sets may help us see ‘patterns’
  • Update the existing incident number that the problem was reported on
  • Add comments to the incident detailing the date/time of the new failure, why you think it is a reoccurrence of the same problem, and as much other context on this new failure as possible, including the similarity with previous failures
  • Supply the diagnostics to Micro Focus using the naming convention for the diagnostics collections and/or other files detailed in the next topic
Parent topic: Reporting a Problem


Naming Conventions for Diagnostic Collection

When MFESdiags is used, the data collected will be in a folder or zip file with a name containing the date and time that the collection was done, for example:

2015-10-06_14-49-36-42-snapshot(.zip)

Please ensure that this convention is carried through so that any additional data provided is identified in the same way.

In addition the incident number should be pre-pended to this collection or any other file that is provided (if it is not attached directly to an incident) in the following manner:

<incident_number>_Date_Time-<name>

For example:

2850000_2015-10-06_14-49-36-snapshot

This naming convention is particularly important when multiple failure data collections are taken for the same incident and problem: sometimes it can take several failures to help in pattern identification for a complex problem resolution.

Parent topic: Reporting a Problem


Specific Troubleshooting Advice

There are numerous topics on troubleshooting throughout your documentation, giving advice on specific areas of the product.

Parent topic: Troubleshooting


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Visual COBOL Development Hub 5.0


Copyright and Trademarks

© Copyright 1984 - 2019 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.

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.

2019-08-20

Parent topic: Copyright and Legal Information


Notations and Conventions

COBOL Conventions
  • PIC X is used rather than PIC 99 with the COMP-X and COMP-5 data types. Unlike PIC 99, PIC X shows the length of the data item and so demonstrates more clearly the use of COMP-X, which is to define a binary item of the specified number of bytes.
Command Line Format
  • Words printed in italics are generic terms representing names to be devised by you.
  • Words printed in nonitalic characters are the actual words you must enter. You must type them in upper or lower case as shown.
  • Material enclosed in square brackets [ ] is optional.
  • When material is enclosed in braces { }, you must choose from the options within them. If there is only one option in the braces, the braces indicate repetition.
  • The ellipsis (. . .) follows { } or [ ] and means you can repeat the material in the { } or [ ]. The number of repetitions allowed is unlimited unless otherwise stated. If the ellipsis is used with [ ] the material can be omitted altogether.
  • If a command line does not fit across the page, it is continued on the next line; the continuation line is indented.
  • The Help may refer you to the readme for details specific to a particular UNIX platform.
  • All command line formats and examples are for the standard UNIX shell, the Bourne shell. If you are using another shell, see your UNIX documentation for the appropriate formats.
  • Where examples showing environment variables do not specifically show them being exported to the shell, it is treated as implicit that they are exported.
  • Some keystrokes using function keys or the Alt or Ctrl keys are not available on all UNIX platforms.The UNIX Key Usage Chart shows how the keystrokes shown in the Help map onto actual keystrokes.
Help System
  • F1=Help appears on every menu in character-mode Micro Focus software. It invokes a help screen describing the current menu.
Keyboard Keys
  • Key names and menu choices are emboldened within the text.
  • Enter refers to the carriage return or Enter key. Where commands to be typed are shown, the Enter key is not explicitly shown; it is treated as implicit that Enter must be pressed at the end of the line.
Numbers
  • Hexadecimal numbers are enclosed in quotation marks and preceded by a lower-case "x" or "h"; for example, x"9D", h"03FF". The "x" is used when the hexadecimal number represents a character string; the "h" when it represents a numerical value.
Path Specifications
  • All path specifications are based on installation to the default installation directory. If you have installed Visual COBOL to a non-default installation directory, adjust the path specifications accordingly.
User Interface
  • Menu choices, and UI control and field names are emboldened within the text.
  • In some environments, you might notice that what appears on your screen differs in minor ways (for example, version numbers) from that illustrated in this Help. This does not affect the operation of your software.
Parent topic: Visual COBOL Development Hub 5.0


TN3270 conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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]
name=DcasCtr


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.


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 CCITRACE environment variable or the [ccitrace_base] section of the CCI.INI configuration file.

If you are also wanting to trace CCI information on a Fileshare server, you must activate tracing when the Fileshare server is started.


Better Method Overload in Managed COBOL

Suppose we have an argument list A with a set of argument types (A1, A2,…An) and two applicable method overloads Mp and Mq with parameter types (P1…Pn) and (Q1,…Qn), where if necessary the parameters have been converted to expanded form (see above).

Then, Mp is said to be a better method overload than Mq if both the following are true:

  • For each argument, the implicit conversion from Ax to Px is not worse than the conversion from Ax to Qx (see below for definition of better conversion)
  • There is at least one argument for which the conversion from Ax to Px is better than the conversion from Ax to Qx

Suppose we have two conversions, from type S to types T1 and T2, then T1 is the better conversion when T1 and T2 are as follows:

T1 is: And T2 is one of:
same as S anything
binary-char
  • binary-char unsigned
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-long unsigned
  • binary-double unsigned
binary-double
  • binary-double unsigned

Otherwise neither conversion is better.


Implicit Conversion in Method Overloading in Managed COBOL

An implicit conversion exists from type S to type T if it is possible to assign an object of type S to an object of type T, with the equivalent of the following statement:

SET obj-T TO obj-S

The following types of implicit conversion are available:

Identity conversions

This simply means that S is the same type as T

Implicit numeric conversions

COBOL generally allows any numeric item to be assigned to any other, with any loss of data being the responsibility of the user. However, when determining if a conversion exists for the purposes of method overloading, we distinguish between proper conversions and truncation conversions. Proper conversions are those for which no loss of data magnitude should result, though even in this case precision can be lost when converting between fixed point and floating point.

For managed COBOL types, proper implicit conversions include:

binary-char
  • binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-char unsigned

The same as binary-char, plus:

  • binary-short unsigned
  • binary-long unsigned
  • binary-double unsigned
binary-short
  • binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-short unsigned

The same as binary-short, plus:

  • binary-long unsigned
  • binary-double unsigned
binary-long
  • binary-double
  • float-short
  • float-long
  • decimal
binary-long unsigned

The same as binary-long, plus:

  • binary-double unsigned
binary-double
  • float-short
  • float-long
  • decimal
binary-double unsigned

The same as binary-double

character
  • binary-short unsigned
  • binary-long
  • binary-long unsigned
  • binary-double
  • binary-double unsigned
  • float-short
  • float-long
  • decimal
float-short
  • float-long
Implicit enumeration conversions

The value 0 may be converted to any enum type

Implicit reference conversions

If S and T are reference types, S may be assigned to T when:

  • Type S is derived (directly or indirectly) from type T. This includes the case where T is java.lang.Object since all types derive from that
  • Type S implements interface type T
  • If S is an array type with element type E1 and T is an array type with element type E2, then S can be assigned to T provided:
    • S and T have the same number of dimensions
    • Both E1 and E2 are reference types
    • An implicit conversion exists from E1 to E2
  • Any array type may be assigned to type java.util.Array in JVM COBOL
  • Null may be assigned to any reference type
Boxing conversions

Any value type can be converted to a java.lang.Object type by a process known as boxing. As part of this process the value is copied onto the object heap and a reference is created

Implicit constant expression conversions

Any numeric constant can be converted to any type capable of containing the full value of that constant. For instance the value 1 can be converted both to BINARY-CHAR UNSIGNED and to BINARY-CHAR.

User defined implicit conversions

A user defined implicit conversion consists of an optional implicit numeric conversion from S to S1 followed by the execution of a user defined implicit conversion operator resulting in T1, followed by another optional implicit numeric conversion to T. User defined implicit conversion operators are defined in COBOL with OPERATOR-ID IMPLICIT and result in methods with the name op_Implicit.

Related information
Type Compatibility of .NET and JVM COBOL with Other Managed Languages


Method Overloading in Managed COBOL

In managed COBOL, it is permissible (and very common practice) for a given class or interface to have multiple methods with the same name, which are distinguished from each other by having different signatures. The signature of a method is determined by the:

  • Number of parameters
  • Type of each parameter
  • Passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter
  • Return type

When code written in COBOL, or any other language, attempts to invoke a method in some class or interface, and more than one method with the given name exists, then a choice of the available methods is made. The choice is based on the number of parameters and the ‘best’ type match for the parameters (the precise definition of ‘best’ is complex and is treated later). If no method with a suitable signature can be found, a ‘method not found’ error results. If there is no method that provides a better match than all the other possible methods with this name, an ‘ambiguous match’ error is given.

Although the type of the RETURNING item is a part of the method's signature, the choice of method to be invoked is never based on the RETURNING type. This is different from .NET and JVM, which allow a class to have multiple methods that differ only by returning type. This is not generally good practice, and COBOL produces an error if it finds such multiple methods within a single class. The only time when such multiple methods can arise from a COBOL program is in the case of the explicit and implicit operators.

Related reference
The Operator-ID Paragraph


Method Signatures Defined by Managed COBOL Programs

The type of a COBOL parameter may be specified by:

  • Referencing the type explicitly in the PROCEDURE DIVISION phrase using the AS syntax
  • Declaring a linkage section item with a given type and referencing that linkage section item in the PROCEDURE DIVISION USING phrase

For REFERENCE and OUTPUT parameters, managed types are exposed directly as managed pointers to the corresponding managed type. COBOL data types that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than BINARY-LONG and so on) are exposed as COBOL pointers.

For VALUE parameters, and RETURNING items, types are exposed as follows:

COBOL types: are exposed as:
Managed types | objects of the corresponding type
Numeric items with more than 19 decimal digit positions | MicroFocus.COBOL.Program.BigDecimal
Numeric items with implied decimal point, such as PIC 9(9)v99, all sizes | - com.microfocus.cobol.program.ScaledInteger in JVM COBOL
Unsigned numeric items with no implied decimal point: In .NET COBOL:
  • < 3 numeric digits - unsigned int8
  • < 5 numeric digits - unsigned int16
  • < 10 numeric digits - unsigned int32
  • < 19 numeric digits - unsigned int64

In JVM COBOL, they are exposed the same as signed numeric items.

Signed numeric items with no implied decimal point:
  • < 3 numeric digits - int8
  • < 5 numeric digits - int16
  • < 10 numeric digits - int32
  • < 19 numeric digits - int64
All other types PIC X, group and so on | string
Related information
Type Compatibility of .NET and JVM COBOL with Other Managed Languages


ACCESS (SQL compiler directive option)

ACCESS

Enables deployment of application code and SQL by updating the SQL Server database at compile time.
  • Creates a stored procedure at compile time for most static SQL statements
  • Compiled OpenESQL code issues a call to the created SQL Server stored procedure
Note: Applies to SQL Server only.

Syntax:

ACCESS=access-plan-name

Parameters:

access-plan-name
The name of the access plan.

Properties:

Default: ACCESS=prog-name

Where prog-name is the COBOL program name.

Dependencies:

To use ACCESS, you must also set the DB SQL compiler directive option.

In some scenarios, you should also set the PASS SQL compiler directive option.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Advantages:

Convenient for testing when the BIND SQL compiler directive option is to be used for deployment.

Comments:

Instead of embedding a SQL Server statement in your compiled module, OpenESQL generates a call to a SQL Server stored procedure. In addition, OpenESQL creates that stored procedure in the schema specified by your SQL Server connection, one for each static SQL statement in the program.

If stored procedures from a previous compilation are present in the schema, OpenESQL drops them before creating new stored procedures.

Related concepts
SQL Code Generation Options


OpenESQL Configuration Utility for Default SQL Cursor Behavior

Use the OpenESQL Configuration utility to change the default behavior for the SQL(BEHAVIOR) directive. OpenESQL uses the default set in the utility only when SQL(BEHAVIOR) is not set explicitly in one of the following places:

  • program source code
  • project settings
  • COBOL compiler directives file

When you specify the SQL(BEHAVIOR) directive in any of these places, the value you specify overrides the default set using the OpenESQL Configuration utility.

You can run this utility, using its command-line implementation (esqlconfig command), on each machine where you have installed Visual COBOL. Do this to change the default for the SQL(BEHAVIOR) directive before attempting to compile programs that do not specify the SQL(BEHAVIOR) directive in one or more of the above-referenced places. You need not run the utility again even after installing software upgrades; however, if you need to change the default behavior at any time, you can run the utility to do so as often as necessary.

Using the OpenESQL Configuration utility, you can set the default behavior to one of the following options:


MAX_POOL_THREAD_CASTRC

Sets the maximum number of pool threads for CASTRC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


MAX_POOL_THREAD_CASGATE

Sets the maximum number of pool threads for CASGATE.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


To start the Samples Browser

Windows 7 and Earlier
  • From your Windows desktop, click > Visual COBOL Samples
Windows 8.1
  • From the Windows Start screen, click the Visual COBOL Samples tile
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus > Visual COBOL Samples


MAX_POOL_THREAD_CASDBC

Sets the maximum number of pool threads for CASDBC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


Getting started with Micro Focus Visual COBOL for Eclipse

This set of tutorials guides you through the use of Micro Focus Visual COBOL for Eclipse. They provide a basic understanding of how the product operates.

These tutorials are designed for developers who have experience with developing COBOL on the mainframe but do not necessarily have a working knowledge of the Integrated Development Environment (IDE). The tutorials provide a basic understanding of the features offered in Visual COBOL for Eclipse to develop and maintain both simple COBOL and mainframe subsystem applications.

Other tutorials, which are designed for Administrators, are available.

Demonstration application

A preconfigured, fully executing application, MFETDUSER, is available in the installation folder for the samples for this product, $COBDIR/demo by default, and in the Mainframe\BankDemo subfolder. This product does not officially support Windows XP but, if you are using it on this platform, the samples are installed in a different folder, C:\Documents and Settings\All Users\Documents\Micro Focus\Visual COBOL\Samples.

The demonstration application includes all the source files needed to run it. The application is both a batch and online application which assesses data on a fictitious bank system. The bank data is stored in VSAM files.

Important: Before attempting this tutorial, create a directory named MFETDUSER on the root of your local drive (C:). Then, copy the entire directory structure for the BankDemo demonstration from the $COBDIR/demo\Mainframe\BankDemo\MFETDUSER folder into the new C:\MFETDUSER folder.

As part of this tutorial, you use to set up a development environment for this application. The tutorials show how you can:

  • Edit the source files
  • Compile the source code
  • Execute and debug the application

Prerequisites

You must have the following software installed:

  • You must have Micro Focus Rumba+ Desktop or an equivalent TN3270 terminal emulator installed to run the CICS application.
    Note: A license for Micro Focus Rumba+ Desktop is included with Enterprise Developer. If you do not have Rumba+ Desktop installed, please refer to the Micro Focus Web site.

Using a remote enterprise server instance for the tutorials

If you have an active firewall on the machine that is running your Directory Server and enterprise server instances, and you want remote clients to be able to connect to them, you must ensure that the firewall allows access to the ports that you are using.

For example, Directory Server is configured, by default, to use port 86. Your must configure your firewall to allow TCP and UDP access to this port. Similarly, the default enterprise server instance, ESDEMO, has a Web Services and J2EE listener that uses port 9003. For remote clients to be able to submit requests to this listener, your firewall must permit access to this port.

We recommend that, if you want remote users to access Enterprise Server functionality through the firewall, you use fixed port values so that you can control access via these.

Note: If you are using Microsoft Windows XP and have installed Service Pack 2, you might find that you cannot see certain Enterprise Server Administration pages, because of firewall restrictions. To get round this, you need to enable access to the ports you are using, for example, 86 for the Enterprise Server Administration Home page and 9003 for the default enterprise server, ESDEMO. Use the Windows Security Center to do this.


DCAS conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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]
allowed formats=allowed-DCAS-request-formats
fingerprint algorithm=encryption-algorithm
fingerprint fallback=use-secondary-algorithm
[Tracing]
trace=trace-level


MAX_POOL_THREAD_CASTMC

Sets the maximum number of pool threads for CASTMC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


MAX_POOL_THREAD_CASTSC

Sets the maximum number of pool threads for CASTSC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


BIND

Enables deployment of application code by generating an SQL batch script that can be used with sqlcmd or SQL Server Management Studio to update the SQL Server database. Compiled OpenESQL code issues a call to SQL Server stored procedures, contained in the SQL batch script.

Syntax:

Note: Applies to SQL Server only.
BIND=bind-script-file

Parameters:

bind-script-file
The name of the bind file.

Properties:

Default: BIND=prog-name

Where prog-name is the COBOL program name.

Dependencies:

When you use BIND, to ensure that your application works, the SQL batch script created must be executed against your SQL Server database.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Advantages:

  • Security can be applied separately to procedures and data so that application users can only access and update data via the application.
  • DBAs can review SQL that is to be deployed without having to access source code.

Comments:

The filename extension for generated bind script files is .sql. For example, if you specify BIND=myprog, the generated bind script file name is myprog.sql.

To update the SQL Server database, run the generated bind script file using sqlcmd or from SQL Server Management Studio.

The generated bind script file contains commands to create a separate stored procedure in the schema specified by your SQL Server connection for each static SQL statement in the program.

If stored procedures from a previous compilation are present in the schema, OpenESQL drops them before creating new stored procedures.

Related concepts
SQL Code Generation Options


MAX_POOL_THREAD_CASMQB

Sets the maximum number of pool threads for CASMQB.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


Overview of Linking Native COBOL Applications and Run-time Systems

Note: The following information applies to native code only.

When you link a program , you link it to any run-time support modules that it uses, and to the run-time system that it needs.

There are two ways to link to the shared run-time system: by importing the run-time system, or by binding to the run-time system dynamically.

The way you link depends on the type of application, as follows:

Application for selling on to an end user
such as those written by Independent Software Vendors (ISVs). This type of application is likely to be the sole COBOL application that the user runs, and so it does not share the run-time system and support files with other applications. If there are other applications, they each use their own versions of the run-time files without disruption. With this model, you create an application that imports the run-time system and support files.

To build this type of application, you build a modular application, and link it with the run-time system. You do not enable dynamic binding so that the run-time files are imported into the application.

Application for corporate use
where multiple COBOL applications are running, and need to share the run-time system and support files both on disk and in memory. With this model, you create an application that is dynamically bound to the run-time system and support files.

To build this type of application, you build a modular application, and dynamically bind it to the run-time system. To do this, you link the top-level COBOL executable to the run-time system and enable dynamic binding.

Related information
Run-time System Configuration


l run-time switch

Enables you to set the maximum amount of memory to be made available to the run-time system, or to cause the run-time system to perform physical cancels instead of logical cancels.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | The maximum number of bytes available to the run-time system.
Type: | General

Comments:

This switch is lower-case "L", not upper-case "I".

The format of this switch is lnnnnnn, where nnnnnn is the amount of memory in bytes to be made available to the run-time system.

You can use this switch to limit the amount of memory the run-time system will use. This might be useful to enable you to tune your system.

By default the run-time system performs logical cancels unless all available memory has been used up. As far as your programs are concerned, the behavior of logical and physical cancels is identical, but logical cancels are faster. A logical cancel flushes all file buffers but does not release any memory. To force all cancels to be physical, you must specify this switch with parameter zero; for example:

+l0

By default, when the run-time system requires memory space it checks that the new request does not exceed the available memory. If it does, the memory that should have been freed by any cancels is freed and the run-time system repeats its request for memory. The run-time system loads programs that have been logically canceled in preference to reloading from disk.

Related information
default_cancel_mode